@weatherboard/gyde-design 0.4.2 → 0.4.4

package/theme-entry.mjs

@@ -0,0 +1,34 @@
+/** Parse the linked JavaScript module before accepting theme startup wiring. */
+// Vendored rather than depended on: `action.yml` installs nothing, so every
+// module it reaches may import only node: builtins and files inside the
+// action path. G-138 is what happened when that was a comment. See
+// vendor/README.md, and selfcontained.test.mjs for the guard.
+import { parse } from "./vendor/acorn.mjs";
+
+const directCall = (node, binding) => node?.type === "CallExpression" &&
+  node.callee.type === "Identifier" && node.callee.name === binding &&
+  node.arguments.length === 0 && !node.optional;
+
+/**
+ * Only an actual named import followed by a direct top-level call counts.
+ * Acorn's module AST excludes comments, strings, template literals, regex
+ * literals, branches and callbacks from this path. A syntax error is a failed
+ * static contract rather than a guess that source-looking text will execute.
+ */
+export function hasThemeStartup(source, systemPackage) {
+  let program;
+  try { program = parse(source, { ecmaVersion: "latest", sourceType: "module" }); }
+  catch { return false; }
+  for (const [index, node] of program.body.entries()) {
+    if (node.type !== "ImportDeclaration" ||
+        node.source.value !== `${systemPackage}/theme-choice`) continue;
+    const binding = node.specifiers.find((part) => part.type === "ImportSpecifier" &&
+      part.imported.type === "Identifier" && part.imported.name === "startThemeChoice")?.local.name;
+    if (!binding) continue;
+    const next = program.body[index + 1];
+    if (next?.type === "ExpressionStatement" && directCall(next.expression, binding)) return true;
+    if (next?.type === "VariableDeclaration" && next.kind === "const" &&
+        next.declarations.length === 1 && directCall(next.declarations[0].init, binding)) return true;
+  }
+  return false;
+}

package/themehost.mjs

@@ -0,0 +1,85 @@
+/** Static host contract for app shells Gyde knows how to inspect. */
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve, relative, sep } from "node:path";
+import { htmlElements } from "./htmlscan.mjs";
+import { hasThemeStartup } from "./theme-entry.mjs";
+
+function within(root, path) {
+  if (typeof path !== "string" || !path || path.startsWith("/")) return null;
+  const full = resolve(root, path);
+  const rel = relative(root, full);
+  return rel && rel !== ".." && !rel.startsWith(`..${sep}`) ? full : null;
+}
+
+function read(root, path) {
+  const full = within(root, path);
+  if (!full || !existsSync(full)) return null;
+  try { return readFileSync(full, "utf8"); } catch { return null; }
+}
+
+/**
+ * `html-inline` is intentionally narrow: it proves concrete wiring in a
+ * standard HTML entry and its directly linked module. Framework layouts need
+ * their own adapter; a text marker in config is never accepted as evidence.
+ */
+export function checkThemeHosts(root, design = {}, { packages = null } = {}) {
+  const declared = design.themeHosts;
+  if (declared === undefined) return { checked: 0, errors: [] };
+  if (!Array.isArray(declared)) return { checked: 0, errors: ["design.themeHosts must be an array"] };
+  const errors = [];
+  const systemPath = design.systemPath || "packages/design-system";
+  const systemPackage = design.systemPackage || `${design.scope}/design-system`;
+  const expected = read(root, `${systemPath}/src/theme-bootstrap.js`);
+  for (const [index, host] of declared.entries()) {
+    const label = `design.themeHosts[${index}]`;
+    if (!host || typeof host !== "object" || host.adapter !== "html-inline") {
+      errors.push(`${label}: unsupported adapter; this gate currently supports html-inline`);
+      continue;
+    }
+    const app = within(root, host.appPath);
+    if (!app || !existsSync(join(app, "package.json")) ||
+        (packages && !packages.some((p) => p.absolute === app))) {
+      errors.push(`${label}: appPath must name an existing workspace package`);
+      continue;
+    }
+    const html = read(app, host.html);
+    const entry = read(app, host.entry);
+    if (html === null) errors.push(`${label}: declared HTML file is missing or unreadable`);
+    if (entry === null) errors.push(`${label}: declared module entry is missing or unreadable`);
+    if (expected === null) errors.push(`${label}: emitted theme-bootstrap.js is missing or unreadable`);
+    if (html === null || entry === null || expected === null) continue;
+    const elements = htmlElements(html);
+    if (!elements.some((n) => n.name === "head")) {
+      errors.push(`${label}: HTML has no head element`);
+      continue;
+    }
+    const headNodes = elements.filter((n) => n.parent === "head");
+    const inline = headNodes.find((n) => n.name === "script" &&
+      !["src", "type", "defer", "async", "nomodule"].some((attr) => n.attrs.has(attr)) &&
+      n.text.trim() === expected.trim());
+    if (!inline) errors.push(`${label}: head must contain the exact emitted bootstrap as an inline script`);
+    else {
+      const earlyResource = headNodes.some((n) => n.index < inline.index &&
+        (n.name === "style" ||
+          (n.name === "link" && n.attrs.get("rel")?.toLowerCase().split(/\s+/).includes("stylesheet")) ||
+          (n.name === "script" && n.attrs.has("src"))));
+      if (earlyResource) {
+        errors.push(`${label}: bootstrap must precede styles and external scripts in head`);
+      }
+    }
+    const src = `/${host.entry?.replace(/^\/+/, "")}`;
+    const moduleTag = elements.some((n) => n.name === "script" &&
+      n.attrs.get("type")?.toLowerCase() === "module" && n.attrs.get("src") === src);
+    if (!moduleTag) errors.push(`${label}: HTML must load the declared entry as a module script`);
+    if (!hasThemeStartup(entry, systemPackage)) {
+      errors.push(`${label}: linked entry must import and immediately call startThemeChoice at module top level`);
+    }
+  }
+  return { checked: declared.length, errors };
+}
+
+export function formatThemeHosts(result) {
+  return result.errors.length
+    ? `theme hosts  ${result.checked} declared, ${result.errors.length} error(s):\n${result.errors.map((e) => `  ${e}`).join("\n")}`
+    : `theme hosts  ${result.checked} declared, checked`;
+}

package/vendor/README.md

@@ -0,0 +1,43 @@
+# Vendored third-party source
+
+Files here are **copied verbatim from an npm package** and imported by relative
+path. They are not edited, ever. `selfcontained.test.mjs` asserts each one is
+byte-identical to the installed package it came from, so a hand edit or a stale
+copy is a failing gate rather than a divergence nobody can see.
+
+## Why anything is vendored at all
+
+`action.yml` runs `packages/design/cli.mjs` straight out of the action checkout
+and **installs nothing** — no network call, no lockfile, no registry credential
+in a consumer's CI. That is the whole of G-63, and it means every module the
+action reaches may import `node:` builtins and files inside the action path,
+and nothing else.
+
+G-138 is what happens when that is stated in a comment and enforced by nothing:
+`themehost.mjs` imported `parse5` and `theme-entry.mjs` imported `acorn`, the
+`v1` tag moved, and every consumer's `design-system` check went red with
+`ERR_MODULE_NOT_FOUND` — in a repository whose own CI installs both and was
+therefore green. `selfcontained.test.mjs` is the guard that would have caught
+it; this directory is how a genuinely needed package is carried.
+
+## Why acorn, and why not parse5
+
+Vendoring is the second choice. The first is not needing the package.
+
+`parse5`'s job in `themehost.mjs` was narrow and fully pinned by
+`themehost.test.mjs`, and parse5 v8 is a fifteen-file ESM tree with its own
+`entities` dependency — carrying it means carrying a dependency tree by hand.
+So it was **dropped** for `../htmlscan.mjs`, 120 lines of our own code.
+
+`acorn` parses arbitrary JavaScript, which must not be hand-rolled: the gate's
+whole claim is that a call inside a string, a template, a regex or a dead
+branch is not startup wiring, and that claim is only as good as the parser. It
+ships `dist/acorn.mjs` as a **single self-contained ESM file with no
+dependencies of its own**, so carrying it is one file and one equality check.
+
+| file | package | from |
+| --- | --- | --- |
+| `acorn.mjs` | `acorn` | `node_modules/acorn/dist/acorn.mjs` |
+
+To update: change the version in the root `package.json`, `npm install`, copy
+the file across, and run `npm run verify`.