@wc-toolkit/cem-generator-fast 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wc-toolkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @wc-toolkit/cem-generator-fast
+
+FAST detector plugin for `@microsoft/fast-element` components.
+
+## Detects
+
+- classes extending `FASTElement` or `FastElement`
+- `@customElement("tag-name")` and `@customElement({ name: "tag-name" })`
+- `@attr` fields and custom attribute names from `@attr({ attribute: "..." })`
+- standard members, JSDoc metadata, and types through the core generator
+- literal `$emit("event-name", detail)` calls as `CustomEvent` entries
+
+FAST lifecycle and infrastructure members such as `connectedCallback`,
+`disconnectedCallback`, `attributeChangedCallback`, `$fastController`, and
+`$emit` are excluded from the public member list.
+
+`mode: "boolean"` is accepted by FAST but requires no special CEM metadata; the field type remains the source of truth.
+
+## Usage
+
+```ts
+import { generateCem } from "@wc-toolkit/cem-generator";
+import { fastPlugin } from "@wc-toolkit/cem-generator-fast";
+
+const manifest = generateCem({
+  plugins: [fastPlugin()],
+});
+```
+
+Run the included demo with `pnpm demo:fast`. It writes the generated manifest to `demo/custom-elements.json`.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { type DetectorPlugin } from "@wc-toolkit/cem-generator";
+export declare function fastPlugin(): DetectorPlugin;

package/dist/index.js

@@ -0,0 +1,174 @@
+import ts from "typescript";
+import { detectClassMembers, detectClassEvents, mergeClassEvents, discoverFrameworkApis, } from "@wc-toolkit/cem-generator";
+import { getJSDocInfo, getNodeTypeText, getParsedTypeText, parseCemClassTags, resolveParsedTypeFromText, } from "@wc-toolkit/cem-generator-utils";
+export function fastPlugin() {
+    return {
+        name: "fast",
+        shouldAnalyze(sourceText) {
+            return /from\s+["']@microsoft\/fast-(?:element|foundation)["']/.test(sourceText) ||
+                /extends\s+(?:FASTElement|FastElement)/.test(sourceText) ||
+                /@(?:customElement|attr)\b/.test(sourceText);
+        },
+        onFile(context) {
+            const fragment = {};
+            ts.forEachChild(context.sourceFile, function visit(node) {
+                if (ts.isClassDeclaration(node) && node.name && extendsFastElement(node, context.checker)) {
+                    const className = node.name.text;
+                    const classDoc = parseCemClassTags(node);
+                    const tagName = getCustomElementTagName(node);
+                    const members = filterFastMembers(detectClassMembers(node, context));
+                    const attributes = getAttrMetadata(node, context, members);
+                    const discovered = discoverFrameworkApis(node, context.sourceFile);
+                    const classFragment = {
+                        name: className,
+                        exportName: getExportName(node),
+                        module: context.filePath,
+                        description: getJSDocInfo(node).description || undefined,
+                        summary: classDoc.summary,
+                        deprecated: classDoc.deprecated,
+                        tagName: classDoc.tagName ?? tagName,
+                        superclass: { name: "FASTElement", module: "@microsoft/fast-element" },
+                        members,
+                        attributes: mergeByName(attributes, classDoc.attributes),
+                        slots: mergeByName(discovered.slots, classDoc.slots),
+                        events: mergeClassEvents(mergeFastEvents(mergeClassEvents(discovered.events, detectClassEvents(node, context)), node, context), classDoc.events?.map((event) => ({
+                            ...event,
+                            parsedType: resolveParsedTypeFromText(event.type, context.sourceFile, context.checker),
+                        }))),
+                        cssParts: mergeByName(discovered.cssParts, classDoc.cssParts),
+                        cssProperties: mergeByName(discovered.cssProperties, classDoc.cssProperties),
+                        cssStates: mergeByName(discovered.cssStates, classDoc.cssStates),
+                        omitInherited: classDoc.omitInherited,
+                        customJsDocTags: classDoc.customJsDocTags,
+                    };
+                    for (const attr of classFragment.attributes ?? []) {
+                        attr.parsedType ??= resolveParsedTypeFromText(attr.type, context.sourceFile, context.checker);
+                    }
+                    fragment[className] = classFragment;
+                }
+                ts.forEachChild(node, visit);
+            });
+            return fragment;
+        },
+    };
+}
+function extendsFastElement(node, checker) {
+    const heritage = node.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword);
+    const seen = new Set();
+    function visit(expression) {
+        if (seen.has(expression))
+            return false;
+        seen.add(expression);
+        if (ts.isIdentifier(expression) && (expression.text === "FASTElement" || expression.text === "FastElement"))
+            return true;
+        if (!ts.isIdentifier(expression))
+            return false;
+        const symbol = checker.getSymbolAtLocation(expression);
+        const resolved = symbol && symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+        const declaration = resolved?.declarations?.find(ts.isClassDeclaration);
+        const base = declaration?.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword);
+        return !!base?.types[0] && visit(base.types[0].expression);
+    }
+    return !!heritage?.types.some((type) => visit(type.expression));
+}
+function getAttrMetadata(node, context, members) {
+    const byName = new Map((members ?? []).map((member) => [member.name, member]));
+    const attributes = [];
+    for (const member of node.members) {
+        if (!ts.isPropertyDeclaration(member))
+            continue;
+        const attrDecorator = (ts.getDecorators?.(member) ?? []).find((decorator) => getDecoratorName(decorator) === "attr");
+        if (!attrDecorator)
+            continue;
+        const name = member.name.getText();
+        const field = byName.get(name);
+        if (!field || field.internal)
+            continue;
+        const options = getAttrOptions(attrDecorator);
+        const attributeName = options.attribute ?? name;
+        attributes.push({
+            name: attributeName,
+            type: getNodeTypeText(member, context.checker),
+            parsedType: getParsedTypeText(member, context.checker),
+            description: field.description,
+            summary: field.summary,
+            deprecated: field.deprecated,
+            default: field.default,
+            fieldName: name,
+        });
+        field.attribute = attributeName;
+    }
+    return attributes.length ? attributes : undefined;
+}
+function getCustomElementTagName(node) {
+    const decorator = (ts.getDecorators?.(node) ?? []).find((item) => getDecoratorName(item) === "customElement");
+    if (!decorator || !ts.isCallExpression(decorator.expression))
+        return undefined;
+    const argument = decorator.expression.arguments[0];
+    if (argument && ts.isStringLiteralLike(argument))
+        return argument.text;
+    if (!argument || !ts.isObjectLiteralExpression(argument))
+        return undefined;
+    const name = argument.properties.find((property) => ts.isPropertyAssignment(property) && property.name.getText() === "name")?.initializer;
+    return name && ts.isStringLiteralLike(name) ? name.text : undefined;
+}
+function getDecoratorName(decorator) {
+    const expression = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+    return ts.isIdentifier(expression) ? expression.text : undefined;
+}
+function getAttrOptions(decorator) {
+    if (!ts.isCallExpression(decorator.expression))
+        return {};
+    const argument = decorator.expression.arguments[0];
+    if (!argument || !ts.isObjectLiteralExpression(argument))
+        return {};
+    const attribute = argument.properties.find((property) => ts.isPropertyAssignment(property) && property.name.getText() === "attribute")?.initializer;
+    return attribute && ts.isStringLiteralLike(attribute) ? { attribute: attribute.text } : {};
+}
+function filterFastMembers(members) {
+    const frameworkMembers = new Set([
+        "$fastController",
+        "$emit",
+        "connectedCallback",
+        "disconnectedCallback",
+        "attributeChangedCallback",
+    ]);
+    const filtered = members?.filter((member) => !frameworkMembers.has(member.name));
+    return filtered?.length ? filtered : undefined;
+}
+function mergeFastEvents(events, node, context) {
+    const byName = new Map((events ?? []).map((event) => [event.name, event]));
+    function visit(current) {
+        if (ts.isClassDeclaration(current))
+            return;
+        if (ts.isCallExpression(current) &&
+            ts.isPropertyAccessExpression(current.expression) &&
+            current.expression.name.text === "$emit") {
+            const name = current.arguments[0];
+            if (name && ts.isStringLiteralLike(name)) {
+                const detail = current.arguments[1];
+                byName.set(name.text, {
+                    name: name.text,
+                    type: "CustomEvent",
+                    detail: detail ? getNodeTypeText(detail, context.checker) : undefined,
+                });
+            }
+        }
+        ts.forEachChild(current, visit);
+    }
+    ts.forEachChild(node, visit);
+    return byName.size ? [...byName.values()] : undefined;
+}
+function getExportName(node) {
+    const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    if (!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword))
+        return undefined;
+    return modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword) ? "default" : node.name?.text;
+}
+function mergeByName(...sources) {
+    const merged = new Map();
+    for (const source of sources)
+        for (const item of source ?? [])
+            merged.set(item.name, { ...merged.get(item.name), ...item });
+    return merged.size ? [...merged.values()] : undefined;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@wc-toolkit/cem-generator-fast",
+  "version": "0.1.1",
+  "description": "FAST detector plugin for generating Custom Elements Manifests.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wc-toolkit/cem-generator.git",
+    "directory": "packages/plugins/fast"
+  },
+  "bugs": {
+    "url": "https://github.com/wc-toolkit/cem-generator/issues"
+  },
+  "homepage": "https://wc-toolkit.github.io/cem-generator/plugins/fast/",
+  "keywords": [
+    "custom-elements",
+    "custom-elements-manifest",
+    "web-components",
+    "fast"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "typescript": "^5.9.0",
+    "@wc-toolkit/cem-generator": "0.1.1",
+    "@wc-toolkit/cem-generator-utils": "0.1.0"
+  },
+  "devDependencies": {
+    "@microsoft/fast-element": "^3.0.2"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "demo": "tsx demo/run.ts"
+  }
+}