Merge pull request #127 from runem/refactor

Architectural improvements
runem · Dec 12, 2019 · 15caed4 · 15caed4
2 parents 1703001 + 5d19404
commit 15caed4
Show file tree

Hide file tree

Showing 230 changed files with 109,006 additions and 24,115 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -0,0 +1,3 @@
+node_modules
+out
+lib
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -0,0 +1,26 @@
+{
+	"env": {
+		"es6": true,
+		"node": true
+	},
+	"extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended", "prettier", "prettier/@typescript-eslint"],
+	"parser": "@typescript-eslint/parser",
+	"plugins": ["@typescript-eslint"],
+	"rules": {
+		"no-console": "error",
+		"@typescript-eslint/no-empty-function": "off",
+		"@typescript-eslint/no-use-before-define": "off",
+		"@typescript-eslint/explicit-function-return-type": "off",
+		"@typescript-eslint/no-object-literal-type-assertion": "off",
+		"@typescript-eslint/explicit-member-accessibility": "off",
+		"@typescript-eslint/no-parameter-properties": "off",
+		"@typescript-eslint/no-var-requires": "off",
+		"@typescript-eslint/interface-name-prefix": "off",
+		"@typescript-eslint/no-unused-vars": "off",
+		"@typescript-eslint/ban-types": "off",
+		"@typescript-eslint/no-non-null-assertion": "off",
+		"@typescript-eslint/prefer-interface": "off",
+		"@typescript-eslint/no-empty-interface": "off",
+		"no-dupe-class-members": "off"
+	}
+}
diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml
@@ -18,7 +18,7 @@ jobs:
           node-version: 10.x
 
       - name: Cache
-        uses: actions/cache@preview
+        uses: actions/cache@v1
         id: cache
         with:
           path: node_modules
@@ -34,7 +34,7 @@ jobs:
         run: npm run lint
 
       - name: Cache Dev
-        uses: actions/cache@preview
+        uses: actions/cache@v1
         id: cache-dev
         with:
           path: ./dev/node_modules

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,51 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/)
+
+<!-- # Unreleased -->
+<!-- ### Added -->
+<!-- ### Changed -->
+<!-- ### Removed -->
+<!-- ### Fixed -->
+
+## [1.0.0] - 2019-12-01
+
+### Added
+
+- Methods are now analyzed
+- `@private`, `@protected`, `@public` and `@access` jsdoc tags are now support ([#106](https://github.com/runem/web-component-analyzer/issues/106)), ([#126](https://github.com/runem/web-component-analyzer/issues/126)) ([#105](https://github.com/runem/web-component-analyzer/issues/105))
+- It's now possible to choose if private and/or protected members should be included in the output using `--visibility protected` CLI option ([#112](https://github.com/runem/web-component-analyzer/issues/112))
+- JSX typescript declaration files are now support (IntrinsicAttributes and IntrinsicElements) ([#116](https://github.com/runem/web-component-analyzer/issues/116))
+- Support for extending HTMLElement with members using Typescript declaration files
+- A list of used mixins for a given component is now included in the markdown output
+- Support for the `@deprecated` jsdoc tag ([#103](https://github.com/runem/web-component-analyzer/issues/103))
+- Support for specifying default css property values: `@cssproperty {Color} [--my-color=red]`
+- `default` is now included in the json format for attributes, properties and css custom properties
+- `deprecated` is now included in the json format for attributes, properties and events ([#103](https://github.com/runem/web-component-analyzer/issues/103))
+- The library ships with different module formats `esm` and `cjs` split in two modules `api` and `cli`. This makes it possible to use WCA in the browser ([#118](https://github.com/runem/web-component-analyzer/issues/118))
+- It's now possible to specify which featues should be analyzed
+- Emitted members now include metadata that flavors can add (eg. LitElement specific metadata)
+- Examples added using the `@example` jsdoc tag will be included in the markdown format.
+- Getter are now also analyzed, making it possible to emit `readonly` properties.
+- Support for the `@readonly` jsdoc tag
+- Support `@param` and `@returns` jsdoc tags
+- Support `@ignore` jsdoc tag
+- Add new flag to the CLI called `--outFiles`. This flag can take special values such as {dir}, {tagname} and {filename}. Read `--help` to learn more.
+- Add new flag to the CLI called `--dry` to test the analyzer without writing files.
+
+### Removed
+
+- It's no longer possible to emit diagnostics using the CLI
+- `jsDoc` has been removed from the json format
+
+### Fixed
+
+- Big internal refactor, including adding a lot of tests
+- Improved merging of component features ([#101](https://github.com/runem/web-component-analyzer/issues/101)), ([#124](https://github.com/runem/web-component-analyzer/issues/124))
+- Improved performance by using caching and lazy evaluation where appropriate
+- Improved support for `@type` jsdoc ([#67](https://github.com/runem/web-component-analyzer/issues/67))
+- Improved jsdoc tag parsing. Default notation like `@attr {string} [my-attr=123]` is now supported
+- Using an object literal as `default` value no longer truncates to the first letter ([#102](https://github.com/runem/web-component-analyzer/issues/102))
+- Fixed problems with some default values ([#130](https://github.com/runem/web-component-analyzer/issues/130))
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -0,0 +1,23 @@
+# The architecture
+
+This is an overview of the architecture. When analyzing a file, the analyzer goes through these steps using `flavors` to find components and features.
+
+<img src="https://user-images.githubusercontent.com/5372940/69460288-09342080-0d74-11ea-822e-2194f986115d.png" />
+
+# Flavors
+
+Each flavor finds features on components. Features can be "properties", "attributes", "slot", eg. Flavors can be toggled on/off, but all are run as default.
+
+# Analyzing and Merging
+
+Multiple features can be emitted per property (eg. if you have both a constructor assignment and a class field that reference the same property). Here are some highlights of feature merging.
+
+**Highlights:**
+
+- Each feature emitted is emitted with a priority (low, medium, high)
+- Features are sorted and merged from highest to lowest priority
+- For example, properties found in the constructor are "low" priority and class fields are "high" priority
+- A given field on a feature (such as `required`) prefers the value of the first non-undefined value found (after priority-sort)
+- In TS-file the type checker is preferred over the `@type` JSDoc. In JS-file the `@type` JSDoc is preferred over the type checker
+- In TS-file constructor assignments are not checked (this is more aligned with what Typescript does)
+- An attribute with same name as a property is always connected to the property (this might however be unwanted behavior in some cases)
diff --git a/README.md b/README.md
@@ -31,36 +31,50 @@ In addition to [vanilla web components](https://developer.mozilla.org/en-US/docs
 $ npm install -g web-component-analyzer
 ```
 
-[![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#usage)
+**or**
 
-## Analyze
+<!-- prettier-ignore -->
+```bash
+$ npx web-component-analyzer src
+```
 
-The analyze command analyses an optional `input glob` and emits the output to the console as default. When the `input glob` is omitted it will find all components excluding `node_modules`. The default format is `markdown`.
+[![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#usage)
 
-<img src="https://user-images.githubusercontent.com/5372940/54445420-02fd9700-4745-11e9-9305-47d6ec3c6307.gif" />
+## ➤ Usage
 
 <!-- prettier-ignore -->
 ```bash
 $ wca analyze
 $ wca analyze src --format markdown
 $ wca analyze "src/**/*.{js,ts}" --outDir components
 $ wca analyze my-element.js --outFile custom-elements.json
+$ wca analyze --outFiles {dir}/custom-element.json
 ```
 
+<img src="https://user-images.githubusercontent.com/5372940/54445420-02fd9700-4745-11e9-9305-47d6ec3c6307.gif" />
+
+The analyze command analyses an optional `<input glob>` and emits the output to the console as default. When the `<input glob>` is omitted it will find all components excluding `node_modules`. The default format is `markdown`.
+
 ### Options
 
-| Option               | Type                             | Description                                                                  |
-| -------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
-| `--format FORMAT`    | `markdown` \| `json` \| `vscode` | Specify output format.                                                       |
-| `--outFile FILE`     | `file path`                      | Concatenate and emit output to a single file.                                |
-| `--outDir DIRECTORY` | `directory path`                 | Direct output to a directory where each file corresponds to a web component. |
+<!-- prettier-ignore -->
+| Option                      | Type                             | Description                                                                  |
+| --------------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
+| `--format <format>`         | `markdown` \| `json` \| `vscode` | Specify output format. Default is `markdown`.                                |
+| `--outDir <path>`           | `directory path`                 | Direct output to a directory where each file corresponds to a web component. |
+| `--outFile <path>`          | `file path`                      | Concatenate and emit output to a single file.                                |
+| `--outFiles <path>`         | `file path with pattern`         | Emit output to multiple files using a pattern. Available substitutions:<br>**{dir}**: The directory of the component<br>**{filename}**: The filename (without ext) of the component<br>**{tagname}**: The element's tag name |
+| `--visibility <visibility>` | `public | protected | private`   | The mininmum member visibility to output. Default is `public`.               |
+| `--features <features>` | `member | method | cssproperty | csspart | event | slot`   | Choose specific features to output. Multiple features are given seperated by a space. All features are enabled as default.<br>**Example**: `--features member slot event`               |
+| `--dry`                     | `boolean`                        | Don't write any files  |
 
 [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#api)
 
-## Output Formats
+## ➤ Output Formats
 
 ### json
 
+<!-- prettier-ignore -->
 ```bash
 wca analyze src --format json --outFile custom-elements.json
 ```
@@ -74,6 +88,7 @@ This json format is for experimental and demo purposes, and is still being activ
 
 ### markdown
 
+<!-- prettier-ignore -->
 ```bash
 wca analyze src --format markdown --outDir readme
 ```
@@ -84,6 +99,7 @@ Web Component Analyzer can output markdown documentation of your web components.
 
 ### vscode
 
+<!-- prettier-ignore -->
 ```bash
 wca analyze src --format vscode --outFile vscode-html-custom-data.json
 ```
@@ -92,34 +108,13 @@ VSCode supports a JSON format called [vscode custom data](https://github.com/mic
 
 [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#how-does-this-tool-analyze-my-components)
 
-## ➤ API
-
-You can also use the underlying functionality of this tool if you don't want to use the CLI. Documentation will be added as soon as the API is considered stable.
-
-<!-- prettier-ignore -->
-```typescript
-import { analyzeComponents } from "web-component-analyzer";
-
-analyzeComponents(sourceFile, { checker });
-```
-
-[![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#how-does-this-tool-analyze-my-components)
-
-## ➤ How does this tool analyze my components?
-
-This tool extract information about your components by looking at your code directly and by looking at your JSDoc comments.
-
-**Code**: Web Component Analyzer supports multiple libraries. [Click here](https://github.com/runem/web-component-analyzer/blob/master/ANALYZE.md) for an overview of how each library is analyzed.
-
-**JSDoc**: Read next section to learn more about how JSDoc is analyzed.
-
 [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#how-to-document-your-components-using-jsdoc)
 
 ## ➤ How to document your components using JSDoc
 
 In addition to analyzing the code of your components, this library also use JSDoc to construct the documentation. It's especially a good idea to use JSDoc for documenting `slots`, `events`, `css custom properties` and `css shadow parts` as these not analyzed statically by this tool as of now (except when constructing a CustomEvent within your component).
 
-Here's an example including all supported JSDoc tags. All JSDoc tags are on the the form `@tag {type} name - comment`.
+Here's an example including all supported JSDoc tags. All JSDoc tags are on the the form `@tag {type} name - comment` and `@tag {type} [name=default] - comment`.
 
 <!-- prettier-ignore -->
 ```javascript
@@ -133,7 +128,7 @@ Here's an example including all supported JSDoc tags. All JSDoc tags are on the
  * 
  * @attr {Boolean} disabled - This jsdoc tag documents an attribute.
  * @attr {on|off} switch - Here is an attribute with either the "on" or "off" value.
- * @attr my-attr
+ * @attr [my-attr=default value]
  * 
  * @prop {String} myProp - You can use this jsdoc tag to document properties.
  * @prop value
@@ -143,7 +138,7 @@ Here's an example including all supported JSDoc tags. All JSDoc tags are on the
  * @slot end
  * 
  * @cssprop --main-bg-color - This jsdoc tag can be used to document css custom properties.
- * @cssprop --main-color
+ * @cssprop [--main-color=red]
 
  * @csspart container 
  */
@@ -164,11 +159,21 @@ class MyElement extends HTMLElement {
    */
   myProp = 10
 
+  static get observedAttributes () {
+    return [
+      /**
+       * The header text of this element
+       */
+      "header"
+    ];
+  }
+
 }
 ```
 
 ### Overview of supported JSDoc tags
 
+<!-- prettier-ignore -->
 | JSDoc Tag                    | Description                                                                                                                                  |
 | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@element`                   | Gives your component a tag name. This JSDoc tag is useful if your 'customElements.define` is called dynamically eg. using a custom function. |
@@ -181,6 +186,68 @@ class MyElement extends HTMLElement {
 
 [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#contributors)
 
+## ➤ How does this tool analyze my components?
+
+This tool extract information about your components by looking at your code directly and by looking at your JSDoc comments.
+
+**Code**: Web Component Analyzer supports multiple libraries. [Click here](https://github.com/runem/web-component-analyzer/blob/master/ANALYZE.md) for an overview of how each library is analyzed.
+
+**JSDoc**: Read next section to learn more about how JSDoc is analyzed.
+
+## ➤ API
+
+You can also directly use the underlying functionality of this tool if you don't want to use the CLI. Web Component Analyzer analyzes Typescript source files, so you will have to include the Typescript parser. Here are some examples of how to use the API.
+
+### Analyze Typescript source file
+
+<!-- prettier-ignore -->
+```typescript
+import { analyzeSourceFile } from "web-component-analyzer";
+
+const result = analyzeSourceFile(sourceFile, { checker });
+```
+
+### Analyze text
+
+<!-- prettier-ignore -->
+```javascript
+import { analyzeText } from "web-component-analyzer";
+
+const code = `class MyElement extends HTMLElement {
+
+}
+
+customElements.define("my-element", MyElement);
+`;
+
+
+const { results, program } = analyzeText(code);
+// or
+const { results, program } = analyzeText([
+  { fileName: "file1.js", text: code },
+  { fileName: "file2.js", text: "..." }, // these files can depend on each other
+  { fileName: "file3.js", text: "...", analyze: false }
+]);
+// each result in "results" is the result of analyzing the corresponding text where "analyze" is not false
+```
+
+### Transform the result
+
+<!-- prettier-ignore -->
+```javascript
+import { transformAnalyzerResult } from "web-component-analyzer";
+
+const result = // the result of analyzing the component using one of the above functions
+
+const format = "markdown"; // or "json"
+
+const output = transformAnalyzerResult(format, result, program);
+
+// "output" is now a string containing the result of the "markdown" transformer
+```
+
+[![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#how-does-this-tool-analyze-my-components)
+
 ## ➤ Contributors
 
 | [<img alt="Rune Mehlsen" src="https://avatars0.githubusercontent.com/u/5372940?s=400&u=43d97899257af3c47715679512919eadb07eab26&v=4" width="100">](https://github.com/runem) |

diff --git a/cli.js b/cli.js
@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
-require("./lib/index.cjs")
+require("./lib/cjs/cli.js")
 	.cli()
+	// eslint-disable-next-line no-console
 	.catch(console.log);