@weatherboard/gyde-design 0.4.3 → 0.4.4

package/themehost.mjs

@@ -1,43 +1,9 @@
 /** 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 { parse } from "parse5";
+import { htmlElements } from "./htmlscan.mjs";
 import { hasThemeStartup } from "./theme-entry.mjs";
 
-const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
-
-/**
- * Read browser-parsed elements in a plain HTML entry. The parser handles
- * raw text, RCDATA, and template contents as the browser does, so markup
- * written inside them cannot masquerade as executable scripts.
- */
-function htmlElements(html) {
-  const nodes = [];
-  const visit = (node, parent = null) => {
-    if (node.tagName && node.namespaceURI === HTML_NAMESPACE) {
-      if (node.tagName === "noscript") return;
-      // An implied head is not evidence that the source declares one.
-      if (node.sourceCodeLocation) {
-        nodes.push({
-          name: node.tagName,
-          attrs: new Map(node.attrs.map(({ name, value }) => [name, value])),
-          parent,
-          inert: false,
-          index: node.sourceCodeLocation.startOffset,
-          text: node.childNodes?.filter((child) => child.nodeName === "#text")
-            .map((child) => child.value).join("") ?? "",
-        });
-      }
-      parent = node.tagName;
-    }
-    // parse5 stores template children in `content`, separate from childNodes.
-    // Do not visit them: their scripts are inert in the host document.
-    for (const child of node.childNodes ?? []) visit(child, parent);
-  };
-  visit(parse(html, { sourceCodeLocationInfo: true, scriptingEnabled: true }));
-  return nodes;
-}
-
 function within(root, path) {
   if (typeof path !== "string" || !path || path.startsWith("/")) return null;
   const full = resolve(root, path);
@@ -83,11 +49,11 @@ export function checkThemeHosts(root, design = {}, { packages = null } = {}) {
     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" && !n.inert)) {
+    if (!elements.some((n) => n.name === "head")) {
       errors.push(`${label}: HTML has no head element`);
       continue;
     }
-    const headNodes = elements.filter((n) => n.parent === "head" && !n.inert);
+    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());
@@ -102,7 +68,7 @@ export function checkThemeHosts(root, design = {}, { packages = null } = {}) {
       }
     }
     const src = `/${host.entry?.replace(/^\/+/, "")}`;
-    const moduleTag = elements.some((n) => n.name === "script" && !n.inert &&
+    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)) {

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`.