Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Architectural improvements #127

Merged
merged 76 commits into from
Dec 12, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
76 commits
Select commit Hold shift + click to select a range
4a49a16
Architectural improvements
runem Nov 27, 2019
c08bd46
Add visibility jsdoc tests
runem Nov 28, 2019
e2dde1a
Export esm/cjs modules with cli and api entrypoints
runem Nov 28, 2019
fdd6f66
Add 'visibility' column to markdown output
runem Nov 28, 2019
02f8979
Add 'visibility' column to markdown output
runem Nov 28, 2019
edfa968
Introduce exclude-node flavor method that can be used to ignore lib f…
runem Nov 28, 2019
59874f9
Rename interface
runem Nov 28, 2019
cc43748
Refactor analyze-text function and export it from the library
runem Nov 28, 2019
eadce63
Refactor transformers and export a single function to transform results
runem Nov 28, 2019
8dcefb7
Fix problem with _ prefixed name not getting recognized as private
runem Nov 29, 2019
6574e9d
Add 'default' to json output for attributes and properties
runem Nov 29, 2019
cc4bc49
Support circular inheritance
runem Nov 29, 2019
e4eedb9
1.0.0-next.0
runem Nov 29, 2019
be8133c
Move Typescript from peer dependency to dependency
runem Nov 29, 2019
57f12a5
1.0.0-next.1
runem Nov 29, 2019
5010b74
Fix problems with resolveNodeValue function
runem Nov 30, 2019
725eaad
Respect private visibility of method names prefixed with underscore
runem Nov 30, 2019
a6fd160
Support multiline jsdoc
runem Nov 30, 2019
8803a1b
Refactor typehint function
runem Nov 30, 2019
c1fc6d7
Reintroduce support for polymer
runem Nov 30, 2019
cd6be84
1.0.0-next.2
runem Nov 30, 2019
148c4aa
Add mixins to markdown output format
runem Nov 30, 2019
dd680b7
1.0.0-next.3
runem Nov 30, 2019
d04c877
Add support for css prop default value
runem Nov 30, 2019
f20d85b
1.0.0-next.4
runem Nov 30, 2019
4d1705e
Show default css prop value in markdown output
runem Nov 30, 2019
6aa8bac
Add type to component methods
runem Nov 30, 2019
3b69e1f
Return program from analyzeText function
runem Dec 1, 2019
6fcdbdc
1.0.0-next.5
runem Dec 1, 2019
f79255f
Visibility in transformer config is now optional
runem Dec 1, 2019
059b532
Take into account that typescript sys can be undefined when running i…
runem Dec 1, 2019
2791339
1.0.0-next.6
runem Dec 1, 2019
10a7e76
Fix problems with object literals in resolve-node-value
runem Dec 1, 2019
ebd5047
Make config optional in transformAnalyzerResult function
runem Dec 1, 2019
26bf34b
1.0.0-next.7
runem Dec 1, 2019
df4fbc4
Make it possible to analyze multiple files using analyzeText
runem Dec 1, 2019
6f7b787
1.0.0-next.8
runem Dec 1, 2019
c487aee
Remove jsDoc from json format
runem Dec 1, 2019
6e07b40
1.0.0-next.9
runem Dec 1, 2019
c90dd82
Remove Object.fromEntries because it's not available in node 10
runem Dec 1, 2019
d7e7e2d
Always check constructor assignments when discovering members
runem Dec 1, 2019
58682d3
Add support for analyzing global features
runem Dec 1, 2019
ac727d6
Update snapshot tests
runem Dec 1, 2019
9d6e00c
Add CHANGELOG.md
runem Dec 1, 2019
b1886aa
Add deprecated and deprecatedMessage to experimental json format
runem Dec 1, 2019
455fce2
Update README.md
runem Dec 2, 2019
7a7bc7c
Add DEVELOPMENT.md
runem Dec 2, 2019
1ce381b
Fix problem when merging typeHint between attributes and properties
runem Dec 2, 2019
81ffe82
1.0.0-next.10
runem Dec 2, 2019
852352c
Fix issues with markdown transformer and documenting events
runem Dec 2, 2019
481d6b6
1.0.0-next.11
runem Dec 2, 2019
86e066a
Make LitElement-speicifc methods protected
runem Dec 2, 2019
438e068
1.0.0-next.12
runem Dec 2, 2019
59b7d33
Improve support for using mixins in combination with typescript decla…
runem Dec 2, 2019
49769dc
Support extending HTMLElementEventMap with global events
runem Dec 2, 2019
ca2f989
Add support for @example jsdoc tag
runem Dec 2, 2019
b3b12af
1.0.0-next.13
runem Dec 2, 2019
4e13efb
Add support for readonly modifier
runem Dec 3, 2019
36cb432
Update CHANGELOG.md
runem Dec 3, 2019
3afe7a5
1.0.0-next.14
runem Dec 3, 2019
c64cb7c
Improve mixin discovering algorithm
runem Dec 3, 2019
354f42e
1.0.0-next.15
runem Dec 3, 2019
1b1a55c
Support param and returns jsdoc tags for methods
runem Dec 5, 2019
4c0c281
1.0.0-next.16
runem Dec 5, 2019
dd57d9b
Setup eslint
runem Dec 5, 2019
e19f551
Add documentation
runem Dec 7, 2019
bad2b56
Add the library yargs and improve the CLI
runem Dec 11, 2019
c5c2c72
1.0.0-next.17
runem Dec 11, 2019
f7c0f9f
Remove unused log statement
runem Dec 11, 2019
62ec08a
Change 'debug' CLI flag to 'verbose'
runem Dec 12, 2019
61ef415
Add support for the ignore jsdoc tag
runem Dec 12, 2019
632f53b
Improve parsing of default values. This fixes #130
runem Dec 12, 2019
1988b9e
1.0.0-next.18
runem Dec 12, 2019
dceaabe
Better error message when no files were found
runem Dec 12, 2019
3b372d1
Update README
runem Dec 12, 2019
5d19404
Fix problem where keys with undefined values would overwrite default …
runem Dec 12, 2019
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .eslintignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
node_modules
out
lib
26 changes: 26 additions & 0 deletions .eslintrc.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
4 changes: 2 additions & 2 deletions .github/workflows/workflow.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
51 changes: 51 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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))
23 changes: 23 additions & 0 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
@@ -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)
135 changes: 101 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand All @@ -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
```
Expand All @@ -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
```
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
*/
Expand All @@ -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. |
Expand All @@ -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) |
Expand Down
3 changes: 2 additions & 1 deletion cli.js
Original file line number Diff line number Diff line change
@@ -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);
Loading