@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/scripts/generate-cem.mjs

@@ -0,0 +1,244 @@
+/**
+ * Publishes the Custom Elements Manifest (custom-elements.json) at the package
+ * root: the standard machine-readable API of every sonic-* element, for IDEs
+ * and coding agents.
+ *
+ * Starts from the raw analyzer output and:
+ * - fills `tagName` (components use `@customElement(tagName)` with a constant
+ *   the analyzer does not resolve);
+ * - expands string-literal union aliases (`ButtonType` → `"default" | …`) so
+ *   allowed values are visible;
+ * - keeps custom elements and their public API only.
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { extractTagNameFromSource, runCem } from "./generate-sdui-catalog.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+export const CEM_OUT = path.join(ROOT, "custom-elements.json");
+const CEM_CONFIG = path.join(ROOT, "custom-elements-manifest.public.config.mjs");
+const CEM_RAW = path.join(ROOT, ".tmp-cem-public", "custom-elements.json");
+
+const LIFECYCLE = new Set([
+  "render",
+  "connectedCallback",
+  "disconnectedCallback",
+  "attributeChangedCallback",
+  "createRenderRoot",
+  "firstUpdated",
+  "updated",
+  "willUpdate",
+  "shouldUpdate",
+  "update",
+  "getUpdateComplete",
+]);
+
+/**
+ * `export type X = "a" | "b"` aliases made only of string literals.
+ * A name defined twice with different values is left out.
+ * @param {string[]} sources TypeScript source texts
+ * @returns {Map<string, string>} alias name → `"a" | "b"`
+ */
+export function collectLiteralUnions(sources) {
+  const unions = new Map();
+  const conflicts = new Set();
+  const re = /export\s+type\s+([A-Z]\w*)\s*=\s*([^;]+);/g;
+  for (const src of sources) {
+    for (const [, name, body] of src.matchAll(re)) {
+      const parts = body
+        .split("|")
+        .map((p) => p.trim())
+        .filter(Boolean);
+      if (!parts.length || !parts.every((p) => /^(["'])[^"']*\1$/.test(p))) continue;
+      const text = parts.map((p) => `"${p.slice(1, -1)}"`).join(" | ");
+      if (unions.has(name) && unions.get(name) !== text) conflicts.add(name);
+      unions.set(name, text);
+    }
+  }
+  for (const name of conflicts) unions.delete(name);
+  return unions;
+}
+
+/** Replace alias identifiers in a type text by their literal union. */
+export function expandType(text, unions) {
+  if (!text) return text;
+  return text
+    .replace(/\b[A-Z]\w*\b/g, (id) => unions.get(id) ?? id)
+    .replace(/\s+/g, " ")
+    .replace(/^\|\s*/, "")
+    .trim();
+}
+
+/** Names declared with Lit `@property(…)` (fields and accessors) in a source. */
+export function collectLitProperties(source) {
+  const names = new Set();
+  const re =
+    /@property\((?:[^()]|\([^()]*\))*\)\s*(?:\/\*[\s\S]*?\*\/\s*|\/\/[^\n]*\n\s*)*(?:(?:declare|readonly|public|override|accessor)\s+)*(?:(?:get|set)\s+)?(\w+)/g;
+  for (const [, name] of source.matchAll(re)) names.add(name);
+  return names;
+}
+
+function withType(entry, unions) {
+  if (!entry?.type?.text) return entry;
+  return { ...entry, type: { ...entry.type, text: expandType(entry.type.text, unions) } };
+}
+
+/**
+ * Public API: Lit properties (with or without attribute) and documented
+ * public methods. Undocumented helpers that merely lack `private` are dropped.
+ */
+function isPublicMember(member, isLitProperty) {
+  if (member.static) return false;
+  if (member.privacy === "private" || member.privacy === "protected") return false;
+  if (member.name.startsWith("_") || member.name.startsWith("#")) return false;
+  if (member.kind === "field") return Boolean(member.attribute) || isLitProperty(member);
+  if (member.kind === "method") return !LIFECYCLE.has(member.name) && Boolean(member.description);
+  return false;
+}
+
+/**
+ * @param {object} raw analyzer manifest
+ * @param {{
+ *   resolveTagName: (modulePath: string) => string | undefined,
+ *   unions: Map<string, string>,
+ *   litProperties: (modulePath: string) => Set<string>,
+ *   exclude?: (modulePath: string) => boolean,
+ * }} options
+ */
+export function buildManifest(raw, { resolveTagName, unions, litProperties, exclude = () => false }) {
+  const byModule = new Map((raw.modules || []).map((m) => [m.path, m]));
+  /** Mixin declaration for `{ name, module | package }` (package paths map to src/). */
+  const resolveMixin = (ref) => {
+    const modulePath =
+      ref.module ??
+      (ref.package?.startsWith("@supersoniks/concorde/")
+        ? `src/${ref.package.slice("@supersoniks/concorde/".length)}.ts`
+        : undefined);
+    const mod = modulePath && byModule.get(modulePath);
+    const decl = mod?.declarations?.find((d) => d.kind === "mixin");
+    return decl ? { decl, modulePath, name: ref.name } : undefined;
+  };
+  /** Own entries first, then each mixin's, skipping names already present. */
+  const withMixins = (d, field) => {
+    const out = [...(d[field] || [])];
+    const seen = new Set(out.map((e) => e.name));
+    for (const ref of d.mixins || []) {
+      const mixin = resolveMixin(ref);
+      for (const entry of mixin?.decl[field] || []) {
+        if (seen.has(entry.name)) continue;
+        seen.add(entry.name);
+        out.push({ ...entry, inheritedFrom: { name: mixin.name, module: mixin.modulePath } });
+      }
+    }
+    return out;
+  };
+  const modules = [];
+  for (const mod of raw.modules || []) {
+    if (exclude(mod.path)) continue;
+    const defined = new Set(
+      (mod.exports || [])
+        .filter((e) => e.kind === "custom-element-definition")
+        .map((e) => e.declaration?.name),
+    );
+    const elements = (mod.declarations || []).filter(
+      (d) => d.kind === "class" && (d.customElement || defined.has(d.name)),
+    );
+    const declarations = [];
+    for (const element of elements) {
+      const tagName = element.tagName || resolveTagName(mod.path);
+      if (!tagName) continue;
+      const d = {
+        ...element,
+        attributes: withMixins(element, "attributes"),
+        members: withMixins(element, "members"),
+      };
+      declarations.push({
+        kind: "class",
+        name: d.name,
+        tagName,
+        customElement: true,
+        ...(d.summary && { summary: d.summary }),
+        ...(d.description && { description: d.description }),
+        ...(d.attributes?.length && {
+          attributes: d.attributes.map((a) => withType(a, unions)),
+        }),
+        ...(d.members?.length && {
+          members: d.members
+            .filter((m) =>
+              isPublicMember(m, (member) =>
+                litProperties(member.inheritedFrom?.module ?? mod.path).has(member.name),
+              ),
+            )
+            .map((m) => withType(m, unions)),
+        }),
+        ...(d.events?.length && { events: d.events }),
+        ...(d.slots?.length && { slots: d.slots }),
+        ...(d.cssProperties?.length && { cssProperties: d.cssProperties }),
+        ...(d.cssParts?.length && { cssParts: d.cssParts }),
+      });
+    }
+    if (!declarations.length) continue;
+    modules.push({
+      kind: "javascript-module",
+      path: mod.path,
+      declarations,
+      exports: declarations.flatMap((d) => [
+        { kind: "js", name: d.name, declaration: { name: d.name, module: mod.path } },
+        {
+          kind: "custom-element-definition",
+          name: d.tagName,
+          declaration: { name: d.name, module: mod.path },
+        },
+      ]),
+    });
+  }
+  modules.sort((a, b) => a.path.localeCompare(b.path));
+  return { schemaVersion: raw.schemaVersion || "1.0.0", readme: "", modules };
+}
+
+function listTsFiles(dir, files = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) listTsFiles(p, files);
+    else if (entry.name.endsWith(".ts") && !/\.(spec|test|demo)\.ts$/.test(entry.name)) {
+      files.push(p);
+    }
+  }
+  return files;
+}
+
+/** Writes custom-elements.json at the package root and returns its path. */
+export function generateCem() {
+  runCem(CEM_CONFIG);
+  const raw = JSON.parse(fs.readFileSync(CEM_RAW, "utf8"));
+  const unions = collectLiteralUnions(
+    listTsFiles(path.join(ROOT, "src/core")).map((f) => fs.readFileSync(f, "utf8")),
+  );
+  const propertyCache = new Map();
+  const manifest = buildManifest(raw, {
+    unions,
+    resolveTagName: (modulePath) => extractTagNameFromSource(path.join(ROOT, modulePath)),
+    litProperties: (modulePath) => {
+      if (!propertyCache.has(modulePath)) {
+        const file = path.join(ROOT, modulePath);
+        propertyCache.set(
+          modulePath,
+          fs.existsSync(file) ? collectLitProperties(fs.readFileSync(file, "utf8")) : new Set(),
+        );
+      }
+      return propertyCache.get(modulePath);
+    },
+    // Copy-paste starter, not a library element
+    exclude: (modulePath) => modulePath.includes("/functional/example/"),
+  });
+  fs.writeFileSync(CEM_OUT, JSON.stringify(manifest, null, 2) + "\n");
+  const count = manifest.modules.reduce((n, m) => n + m.declarations.length, 0);
+  console.log(`✅ custom-elements.json: ${count} elements`);
+  return CEM_OUT;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  generateCem();
+}

package/scripts/generate-cem.test.mjs

@@ -0,0 +1,122 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  buildManifest,
+  collectLitProperties,
+  collectLiteralUnions,
+  expandType,
+} from "./generate-cem.mjs";
+
+test("collectLiteralUnions keeps string-literal aliases only", () => {
+  const unions = collectLiteralUnions([
+    `export type Size = "sm" | "md";\nexport type Route = string | URL;`,
+    `export type Shape =\n  | "default"\n  | "circle";`,
+  ]);
+  assert.equal(unions.get("Size"), `"sm" | "md"`);
+  assert.equal(unions.get("Shape"), `"default" | "circle"`);
+  assert.equal(unions.has("Route"), false);
+});
+
+test("collectLiteralUnions drops names defined twice with different values", () => {
+  const unions = collectLiteralUnions([`export type Mode = "a" | "b";`, `export type Mode = "c" | "d";`]);
+  assert.equal(unions.has("Mode"), false);
+});
+
+test("expandType replaces aliases and normalizes whitespace", () => {
+  const unions = new Map([["Size", `"sm" | "md"`]]);
+  assert.equal(expandType("Size | undefined", unions), `"sm" | "md" | undefined`);
+  assert.equal(expandType(`| "a"\n    | "b"`, unions), `"a" | "b"`);
+  assert.equal(expandType("Route | string", unions), "Route | string");
+});
+
+test("collectLitProperties finds fields and accessors, with comments in between", () => {
+  const names = collectLitProperties(`
+    @property({ type: String }) label = "";
+    @property({
+      type: Function,
+      attribute: false,
+    }) /** doc */
+    get items() { return this._items; }
+    @state() open = false;
+  `);
+  assert.deepEqual([...names].sort(), ["items", "label"]);
+});
+
+const raw = {
+  schemaVersion: "1.0.0",
+  modules: [
+    {
+      path: "src/core/mixins/FormElement.ts",
+      declarations: [
+        {
+          kind: "mixin",
+          name: "Form",
+          attributes: [{ name: "name", type: { text: "string" }, fieldName: "name" }],
+          members: [{ kind: "field", name: "name", attribute: "name" }],
+        },
+      ],
+    },
+    {
+      path: "src/core/components/ui/button/button.ts",
+      declarations: [
+        {
+          kind: "class",
+          name: "Button",
+          customElement: true,
+          mixins: [{ name: "FormElement", package: "@supersoniks/concorde/core/mixins/FormElement" }],
+          attributes: [{ name: "size", type: { text: "Size" }, fieldName: "size" }],
+          members: [
+            { kind: "field", name: "size", attribute: "size", type: { text: "Size" } },
+            { kind: "field", name: "items", type: { text: "ListItems" } },
+            { kind: "field", name: "pointerDownTime", type: { text: "number" } },
+            { kind: "field", name: "_internal" },
+            { kind: "method", name: "render" },
+            { kind: "method", name: "handleClick" },
+            { kind: "method", name: "show", description: "Opens it." },
+          ],
+        },
+      ],
+      exports: [{ kind: "custom-element-definition", declaration: { name: "Button" } }],
+    },
+    {
+      path: "src/core/components/functional/example/example.ts",
+      declarations: [{ kind: "class", name: "Example", customElement: true }],
+      exports: [{ kind: "custom-element-definition", declaration: { name: "Example" } }],
+    },
+  ],
+};
+
+function build() {
+  return buildManifest(raw, {
+    unions: new Map([["Size", `"sm" | "md"`]]),
+    resolveTagName: (p) => (p.includes("button") ? "sonic-button" : "sonic-example"),
+    litProperties: (p) => (p.includes("button") ? new Set(["size", "items"]) : new Set()),
+    exclude: (p) => p.includes("/functional/example/"),
+  });
+}
+
+test("buildManifest keeps elements with their tag name and definition export", () => {
+  const manifest = build();
+  assert.equal(manifest.modules.length, 1);
+  const [mod] = manifest.modules;
+  const [el] = mod.declarations;
+  assert.equal(el.tagName, "sonic-button");
+  assert.deepEqual(
+    mod.exports.find((e) => e.kind === "custom-element-definition"),
+    { kind: "custom-element-definition", name: "sonic-button", declaration: { name: "Button", module: mod.path } },
+  );
+  assert.equal(el.attributes.find((a) => a.name === "size").type.text, `"sm" | "md"`);
+});
+
+test("buildManifest keeps the public API only and merges mixins", () => {
+  const [el] = build().modules[0].declarations;
+  assert.deepEqual(
+    el.members.map((m) => m.name),
+    ["size", "items", "show", "name"],
+  );
+  const inherited = el.attributes.find((a) => a.name === "name");
+  assert.deepEqual(inherited.inheritedFrom, {
+    name: "FormElement",
+    module: "src/core/mixins/FormElement.ts",
+  });
+});