cem-plugin-wrec 0.0.1

package/README.md

@@ -0,0 +1,90 @@
+# cem-plugin-wrec
+
+This is a Custom Elements Manifest (CEM) plugin
+for the [wrec](https://github.com/mvolkmann/wrec) library.
+
+## Installing
+
+```bash
+npm i -D @custom-elements-manifest/analyzer
+npm i -D cem-plugin-wrec
+```
+
+## Configuring
+
+Add the following scripts in your `package.json` file:
+
+```json
+"cem": "custom-elements-manifest analyze",
+"cem:watch": "custom-elements-manifest analyze --watch",
+```
+
+Create the file `custom-elements-manifest.config.js` containing the following:
+
+```js
+import wrecPlugin from "cem-plugin-wrec";
+
+export default {
+  plugins: [wrecPlugin()],
+};
+```
+
+## Supported syntax
+
+This plugin supports web components implementing using the wrec library.
+See the example component defined in `my-counter.js`.
+
+## Expected output
+
+Document an example of the expected output custom elements manifest
+
+```diff
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/my-element.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "This is a counter web component.",
+          "name": "MyCounter",
+          "members": [
+            {
+              "kind": "method",
+              "name": "decrement"
+            }
+          ],
+          "attributes": [
+            {
+              "default": 0,
+              "description": "initial value",
+              "fieldName": "count",
+              "name": "count",
+              "type": "Number"
+            }
+          ],
+          "superclass": {
+            "name": "Wrec",
+            "package": "wrec"
+          },
+          "tagName": "my-counter",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "my-counter",
+          "declaration": {
+            "name": "MyCounter",
+            "module": "src/my-element.js"
+          }
+        }
+      ]
+    }
+  ]
+}
+```

package/SyntaxKind.md

@@ -0,0 +1,401 @@
+# ts.SyntaxKind Properties
+
+0 - FirstToken
+0 - Unknown
+1 - EndOfFileToken
+2 - FirstTriviaToken
+2 - SingleLineCommentTrivia
+3 - MultiLineCommentTrivia
+4 - NewLineTrivia
+5 - WhitespaceTrivia
+6 - ShebangTrivia
+7 - ConflictMarkerTrivia
+7 - LastTriviaToken
+8 - NonTextFileMarkerTrivia
+9 - FirstLiteralToken
+9 - NumericLiteral
+10 - BigIntLiteral
+11 - StringLiteral
+12 - JsxText
+13 - JsxTextAllWhiteSpaces
+14 - RegularExpressionLiteral
+15 - FirstTemplateToken
+15 - LastLiteralToken
+15 - NoSubstitutionTemplateLiteral
+16 - TemplateHead
+17 - TemplateMiddle
+18 - LastTemplateToken
+18 - TemplateTail
+19 - FirstPunctuation
+19 - OpenBraceToken
+20 - CloseBraceToken
+21 - OpenParenToken
+22 - CloseParenToken
+23 - OpenBracketToken
+24 - CloseBracketToken
+25 - DotToken
+26 - DotDotDotToken
+27 - SemicolonToken
+28 - CommaToken
+29 - QuestionDotToken
+30 - FirstBinaryOperator
+30 - LessThanToken
+31 - LessThanSlashToken
+32 - GreaterThanToken
+33 - LessThanEqualsToken
+34 - GreaterThanEqualsToken
+35 - EqualsEqualsToken
+36 - ExclamationEqualsToken
+37 - EqualsEqualsEqualsToken
+38 - ExclamationEqualsEqualsToken
+39 - EqualsGreaterThanToken
+40 - PlusToken
+41 - MinusToken
+42 - AsteriskToken
+43 - AsteriskAsteriskToken
+44 - SlashToken
+45 - PercentToken
+46 - PlusPlusToken
+47 - MinusMinusToken
+48 - LessThanLessThanToken
+49 - GreaterThanGreaterThanToken
+50 - GreaterThanGreaterThanGreaterThanToken
+51 - AmpersandToken
+52 - BarToken
+53 - CaretToken
+54 - ExclamationToken
+55 - TildeToken
+56 - AmpersandAmpersandToken
+57 - BarBarToken
+58 - QuestionToken
+59 - ColonToken
+60 - AtToken
+61 - QuestionQuestionToken
+62 - BacktickToken
+63 - HashToken
+64 - EqualsToken
+64 - FirstAssignment
+65 - FirstCompoundAssignment
+65 - PlusEqualsToken
+66 - MinusEqualsToken
+67 - AsteriskEqualsToken
+68 - AsteriskAsteriskEqualsToken
+69 - SlashEqualsToken
+70 - PercentEqualsToken
+71 - LessThanLessThanEqualsToken
+72 - GreaterThanGreaterThanEqualsToken
+73 - GreaterThanGreaterThanGreaterThanEqualsToken
+74 - AmpersandEqualsToken
+75 - BarEqualsToken
+76 - BarBarEqualsToken
+77 - AmpersandAmpersandEqualsToken
+78 - QuestionQuestionEqualsToken
+79 - CaretEqualsToken
+79 - LastAssignment
+79 - LastBinaryOperator
+79 - LastCompoundAssignment
+79 - LastPunctuation
+80 - Identifier
+81 - PrivateIdentifier
+82 - JSDocCommentTextToken
+83 - BreakKeyword
+83 - FirstKeyword
+83 - FirstReservedWord
+84 - CaseKeyword
+85 - CatchKeyword
+86 - ClassKeyword
+87 - ConstKeyword
+88 - ContinueKeyword
+89 - DebuggerKeyword
+90 - DefaultKeyword
+91 - DeleteKeyword
+92 - DoKeyword
+93 - ElseKeyword
+94 - EnumKeyword
+95 - ExportKeyword
+96 - ExtendsKeyword
+97 - FalseKeyword
+98 - FinallyKeyword
+99 - ForKeyword
+100 - FunctionKeyword
+101 - IfKeyword
+102 - ImportKeyword
+103 - InKeyword
+104 - InstanceOfKeyword
+105 - NewKeyword
+106 - NullKeyword
+107 - ReturnKeyword
+108 - SuperKeyword
+109 - SwitchKeyword
+110 - ThisKeyword
+111 - ThrowKeyword
+112 - TrueKeyword
+113 - TryKeyword
+114 - TypeOfKeyword
+115 - VarKeyword
+116 - VoidKeyword
+117 - WhileKeyword
+118 - LastReservedWord
+118 - WithKeyword
+119 - FirstFutureReservedWord
+119 - ImplementsKeyword
+120 - InterfaceKeyword
+121 - LetKeyword
+122 - PackageKeyword
+123 - PrivateKeyword
+124 - ProtectedKeyword
+125 - PublicKeyword
+126 - StaticKeyword
+127 - LastFutureReservedWord
+127 - YieldKeyword
+128 - AbstractKeyword
+128 - FirstContextualKeyword
+129 - AccessorKeyword
+130 - AsKeyword
+131 - AssertsKeyword
+132 - AssertKeyword
+133 - AnyKeyword
+134 - AsyncKeyword
+135 - AwaitKeyword
+136 - BooleanKeyword
+137 - ConstructorKeyword
+138 - DeclareKeyword
+139 - GetKeyword
+140 - InferKeyword
+141 - IntrinsicKeyword
+142 - IsKeyword
+143 - KeyOfKeyword
+144 - ModuleKeyword
+145 - NamespaceKeyword
+146 - NeverKeyword
+147 - OutKeyword
+148 - ReadonlyKeyword
+149 - RequireKeyword
+150 - NumberKeyword
+151 - ObjectKeyword
+152 - SatisfiesKeyword
+153 - SetKeyword
+154 - StringKeyword
+155 - SymbolKeyword
+156 - TypeKeyword
+157 - UndefinedKeyword
+158 - UniqueKeyword
+159 - UnknownKeyword
+160 - UsingKeyword
+161 - FromKeyword
+162 - GlobalKeyword
+163 - BigIntKeyword
+164 - OverrideKeyword
+165 - LastContextualKeyword
+165 - LastKeyword
+165 - LastToken
+165 - OfKeyword
+166 - FirstNode
+166 - QualifiedName
+167 - ComputedPropertyName
+168 - TypeParameter
+169 - Parameter
+170 - Decorator
+171 - PropertySignature
+172 - PropertyDeclaration
+173 - MethodSignature
+174 - MethodDeclaration
+175 - ClassStaticBlockDeclaration
+176 - Constructor
+177 - GetAccessor
+178 - SetAccessor
+179 - CallSignature
+180 - ConstructSignature
+181 - IndexSignature
+182 - FirstTypeNode
+182 - TypePredicate
+183 - TypeReference
+184 - FunctionType
+185 - ConstructorType
+186 - TypeQuery
+187 - TypeLiteral
+188 - ArrayType
+189 - TupleType
+190 - OptionalType
+191 - RestType
+192 - UnionType
+193 - IntersectionType
+194 - ConditionalType
+195 - InferType
+196 - ParenthesizedType
+197 - ThisType
+198 - TypeOperator
+199 - IndexedAccessType
+200 - MappedType
+201 - LiteralType
+202 - NamedTupleMember
+203 - TemplateLiteralType
+204 - TemplateLiteralTypeSpan
+205 - ImportType
+205 - LastTypeNode
+206 - ObjectBindingPattern
+207 - ArrayBindingPattern
+208 - BindingElement
+209 - ArrayLiteralExpression
+210 - ObjectLiteralExpression
+211 - PropertyAccessExpression
+212 - ElementAccessExpression
+213 - CallExpression
+214 - NewExpression
+215 - TaggedTemplateExpression
+216 - TypeAssertionExpression
+217 - ParenthesizedExpression
+218 - FunctionExpression
+219 - ArrowFunction
+220 - DeleteExpression
+221 - TypeOfExpression
+222 - VoidExpression
+223 - AwaitExpression
+224 - PrefixUnaryExpression
+225 - PostfixUnaryExpression
+226 - BinaryExpression
+227 - ConditionalExpression
+228 - TemplateExpression
+229 - YieldExpression
+230 - SpreadElement
+231 - ClassExpression
+232 - OmittedExpression
+233 - ExpressionWithTypeArguments
+234 - AsExpression
+235 - NonNullExpression
+236 - MetaProperty
+237 - SyntheticExpression
+238 - SatisfiesExpression
+239 - TemplateSpan
+240 - SemicolonClassElement
+241 - Block
+242 - EmptyStatement
+243 - FirstStatement
+243 - VariableStatement
+244 - ExpressionStatement
+245 - IfStatement
+246 - DoStatement
+247 - WhileStatement
+248 - ForStatement
+249 - ForInStatement
+250 - ForOfStatement
+251 - ContinueStatement
+252 - BreakStatement
+253 - ReturnStatement
+254 - WithStatement
+255 - SwitchStatement
+256 - LabeledStatement
+257 - ThrowStatement
+258 - TryStatement
+259 - DebuggerStatement
+259 - LastStatement
+260 - VariableDeclaration
+261 - VariableDeclarationList
+262 - FunctionDeclaration
+263 - ClassDeclaration
+264 - InterfaceDeclaration
+265 - TypeAliasDeclaration
+266 - EnumDeclaration
+267 - ModuleDeclaration
+268 - ModuleBlock
+269 - CaseBlock
+270 - NamespaceExportDeclaration
+271 - ImportEqualsDeclaration
+272 - ImportDeclaration
+273 - ImportClause
+274 - NamespaceImport
+275 - NamedImports
+276 - ImportSpecifier
+277 - ExportAssignment
+278 - ExportDeclaration
+279 - NamedExports
+280 - NamespaceExport
+281 - ExportSpecifier
+282 - MissingDeclaration
+283 - ExternalModuleReference
+284 - JsxElement
+285 - JsxSelfClosingElement
+286 - JsxOpeningElement
+287 - JsxClosingElement
+288 - JsxFragment
+289 - JsxOpeningFragment
+290 - JsxClosingFragment
+291 - JsxAttribute
+292 - JsxAttributes
+293 - JsxSpreadAttribute
+294 - JsxExpression
+295 - JsxNamespacedName
+296 - CaseClause
+297 - DefaultClause
+298 - HeritageClause
+299 - CatchClause
+300 - AssertClause
+300 - ImportAttributes
+301 - AssertEntry
+301 - ImportAttribute
+302 - ImportTypeAssertionContainer
+303 - PropertyAssignment
+304 - ShorthandPropertyAssignment
+305 - SpreadAssignment
+306 - EnumMember
+307 - UnparsedPrologue
+308 - UnparsedPrepend
+309 - UnparsedText
+310 - UnparsedInternalText
+311 - UnparsedSyntheticReference
+312 - SourceFile
+313 - Bundle
+314 - UnparsedSource
+315 - InputFiles
+316 - FirstJSDocNode
+316 - JSDocTypeExpression
+317 - JSDocNameReference
+318 - JSDocMemberName
+319 - JSDocAllType
+320 - JSDocUnknownType
+321 - JSDocNullableType
+322 - JSDocNonNullableType
+323 - JSDocOptionalType
+324 - JSDocFunctionType
+325 - JSDocVariadicType
+326 - JSDocNamepathType
+327 - JSDoc
+327 - JSDocComment
+328 - JSDocText
+329 - JSDocTypeLiteral
+330 - JSDocSignature
+331 - JSDocLink
+332 - JSDocLinkCode
+333 - JSDocLinkPlain
+334 - FirstJSDocTagNode
+334 - JSDocTag
+335 - JSDocAugmentsTag
+336 - JSDocImplementsTag
+337 - JSDocAuthorTag
+338 - JSDocDeprecatedTag
+339 - JSDocClassTag
+340 - JSDocPublicTag
+341 - JSDocPrivateTag
+342 - JSDocProtectedTag
+343 - JSDocReadonlyTag
+344 - JSDocOverrideTag
+345 - JSDocCallbackTag
+346 - JSDocOverloadTag
+347 - JSDocEnumTag
+348 - JSDocParameterTag
+349 - JSDocReturnTag
+350 - JSDocThisTag
+351 - JSDocTypeTag
+352 - JSDocTemplateTag
+353 - JSDocTypedefTag
+354 - JSDocSeeTag
+355 - JSDocPropertyTag
+356 - JSDocThrowsTag
+357 - JSDocSatisfiesTag
+357 - LastJSDocNode
+357 - LastJSDocTagNode
+358 - SyntaxList
+359 - NotEmittedStatement
+360 - PartiallyEmittedExpression
+361 - CommaListExpression
+362 - SyntheticReferenceExpression

package/dev.js

@@ -0,0 +1,15 @@
+import fs from 'fs';
+import ts from 'typescript';
+import { create } from '@custom-elements-manifest/analyzer/src/create.js';
+import myPlugin from './index.js';
+
+const code = fs.readFileSync('fixtures/default/sourcecode/default.js').toString();
+
+const modules = [ts.createSourceFile(
+  'my-element.js',
+  code,
+  ts.ScriptTarget.ES2015,
+  true,
+)];
+
+console.log(JSON.stringify(create({modules, plugins: [myPlugin()]}), null, 2));

package/fixtures/default/actual.json

@@ -0,0 +1,39 @@
+{
+  "schemaVersion": "0.1.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "my-element.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "MyElement",
+          "members": [
+            {
+              "kind": "field",
+              "name": "someField",
+              "default": "",
+              "foo": "Some custom information!"
+            }
+          ],
+          "superclass": {
+            "name": "HTMLElement"
+          },
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "MyElement",
+          "declaration": {
+            "name": "MyElement",
+            "module": "my-element.js"
+          }
+        }
+      ]
+    }
+  ]
+}

package/fixtures/default/expected.json

@@ -0,0 +1,39 @@
+{
+  "schemaVersion": "0.1.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "my-element.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "MyElement",
+          "members": [
+            {
+              "kind": "field",
+              "name": "someField",
+              "default": "",
+              "foo": "Some custom information!"
+            }
+          ],
+          "superclass": {
+            "name": "HTMLElement"
+          },
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "MyElement",
+          "declaration": {
+            "name": "MyElement",
+            "module": "my-element.js"
+          }
+        }
+      ]
+    }
+  ]
+}

package/fixtures/default/sourcecode/default.js

@@ -0,0 +1,6 @@
+export class MyElement extends HTMLElement { 
+  /**
+   * @foo Some custom information!
+   */
+  someField = '';
+}

package/index.js

@@ -0,0 +1,135 @@
+function wrecPlugin() {
+  //export default // TODO: Need this?
+
+  const MEMBERS_TO_HIDE = new Set(["css", "html", "properties"]);
+
+  let currentClass;
+  let isStatic = false;
+  let Kind = {};
+  let propertyName = "";
+
+  function nodeValue(node) {
+    const { initializer } = node;
+    switch (initializer.kind) {
+      case Kind.Identifier:
+        return initializer.getText();
+      case Kind.FalseKeyword:
+        return false;
+      case Kind.TrueKeyword:
+        return true;
+      case Kind.NumericLiteral:
+        return Number(node.initializer.text);
+      case Kind.NullKeyword:
+        return null;
+      case Kind.StringLiteral:
+        return node.initializer.text;
+      default:
+        return undefined;
+    }
+  }
+
+  return {
+    name: "wrec-plugin",
+
+    // Runs before analysis starts
+    //initialize({ ts, customElementsManifest, context }) {},
+
+    // Runs for all modules in a project, before continuing to the analyzePhase
+    //collectPhase({ ts, node, context }) {},
+
+    // Runs for each module
+    analyzePhase({ ts, node, moduleDoc, context }) {
+      Kind = ts.SyntaxKind;
+
+      switch (node.kind) {
+        case Kind.ClassDeclaration:
+          const className = node.name.getText();
+          const heritage = node.heritageClauses[0];
+          if (heritage) {
+            const superclass = heritage.types[0].expression.getText();
+            if (superclass === "Wrec") {
+              const elementName = className
+                .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+                .toLowerCase();
+              moduleDoc.exports.push({
+                kind: "custom-element-definition",
+                name: elementName,
+                declaration: {
+                  name: className,
+                  module: moduleDoc.path,
+                },
+              });
+              currentClass = moduleDoc?.declarations?.find(
+                (declaration) => declaration.name === className
+              );
+            }
+          }
+          break;
+
+        case Kind.ObjectLiteralExpression: {
+          if (isStatic && propertyName === "properties") {
+            if (!currentClass.attributes) currentClass.attributes = [];
+
+            for (const property of node.properties) {
+              const name = property.name.getText();
+              let doc = "";
+              let type;
+              let value;
+
+              if (property.kind === Kind.PropertyAssignment) {
+                const { initializer } = property;
+                if (initializer.kind === Kind.ObjectLiteralExpression) {
+                  for (const property2 of initializer.properties) {
+                    const name2 = property2.name.getText();
+                    const value2 = nodeValue(property2);
+                    if (name2 === "doc") doc = value2;
+                    if (name2 === "type") type = value2;
+                    if (name2 === "value") value = value2;
+                  }
+                }
+              }
+
+              currentClass.attributes.push({
+                default: value,
+                description: doc,
+                fieldName: name,
+                name,
+                type,
+              });
+            }
+
+            isStatic = false;
+          }
+          break;
+        }
+
+        case Kind.PropertyDeclaration:
+          propertyName = node.name.getText();
+          break;
+
+        case Kind.StaticKeyword:
+          isStatic = true;
+          break;
+      }
+    },
+
+    // Runs for each module, after analyzing, all information about your module should now be available
+    moduleLinkPhase({ moduleDoc, context }) {
+      const classes = moduleDoc?.declarations?.filter(
+        (declaration) => declaration.kind === "class"
+      );
+
+      for (aClass of classes) {
+        const { members } = aClass;
+        if (members) {
+          aClass.members = members.filter(
+            (member) => !MEMBERS_TO_HIDE.has(member.name)
+          );
+        }
+      }
+    },
+
+    // Runs after modules have been parsed and after post-processing
+    //packageLinkPhase({ customElementsManifest, context }) {},
+  };
+}

package/my-counter.js

@@ -0,0 +1,46 @@
+import Wrec from "wrec";
+
+/**
+ * This is a counter web component.
+ */
+class MyCounter extends Wrec {
+  static properties = {
+    count: { doc: "initial value", type: Number, reflect: true, value: 0 },
+  };
+
+  css() {
+    return /*css*/ `
+       .counter {
+         display: flex;
+         align-items: center;
+         gap: 0.5rem;
+       }
+
+       button {
+         background-color: lightgreen;
+       }
+
+       button:disabled {
+         background-color: gray;
+       }
+     `;
+  }
+
+  html() {
+    return /*html*/ `
+      <div>
+        <button onClick="decrement" type="button"
+          disabled="this.count === 0">-</button>
+        <span>this.count</span>
+        <button onClick="this.count++" type="button">+</button>
+        <span>(this.count < 10 ? "single" : "double") + " digit"</span>
+      </div>
+    `;
+  }
+
+  decrement() {
+    if (this.count > 0) this.count--;
+  }
+}
+
+MyCounter.register();

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "cem-plugin-wrec",
+  "version": "0.0.1",
+  "description": "plugin for use with @custom-elements-manifest/analyzer",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "nodemon dev.js",
+    "test": "uvu test"
+  },
+  "keywords": [
+    "custom-elements",
+    "custom-elements-json",
+    "custom-elements-manifest",
+    "customelements",
+    "webcomponents",
+    "customelementsjson",
+    "customelementsmanifest"
+  ],
+  "author": "R. Mark Volkmann",
+  "license": "ISC",
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "^0.1.14",
+    "globby": "^11.0.3",
+    "nodemon": "^2.0.7",
+    "typescript": "^4.3.2",
+    "uvu": "^0.5.1"
+  }
+}

package/test/integration.test.js

@@ -0,0 +1,44 @@
+import { test } from 'uvu';
+import * as assert from 'uvu/assert';
+import path from 'path';
+import fs from 'fs';
+import globby from 'globby';
+import ts from 'typescript';
+import { create } from '@custom-elements-manifest/analyzer/src/create.js';
+import myPlugin from '../index.js';
+
+const fixturesDir = path.join(process.cwd(), 'fixtures');
+let testCases = fs.readdirSync(fixturesDir);
+
+testCases.forEach(testCase => {
+  test(`Testcase ${testCase}`, async () => {
+
+    const fixturePath = path.join(fixturesDir, `${testCase}/expected.json`);
+    const fixture = JSON.parse(fs.readFileSync(fixturePath, 'utf-8'));
+
+    const packagePath = path.join(fixturesDir, `${testCase}/sourcecode`);
+    const packagePathPosix = packagePath.split(path.sep).join(path.posix.sep);
+    const outputPath = path.join(fixturesDir, `${testCase}/actual.json`);
+
+    const globs = await globby(packagePathPosix);
+    const modules = globs.map(glob => {
+        const relativeModulePath = `.${path.sep}${path.relative(process.cwd(), glob)}`;
+        const source = fs.readFileSync(relativeModulePath).toString();
+    
+        return ts.createSourceFile(
+          'my-element.js',
+          source,
+          ts.ScriptTarget.ES2015,
+          true,
+        );
+      });
+
+    const result = create({modules, plugins: [myPlugin()]});
+
+    fs.writeFileSync(outputPath, JSON.stringify(result, null, 2));
+
+    assert.equal(result, fixture);
+  });
+});
+
+test.run();