@weatherboard/gyde-design 0.4.3 → 0.4.4

package/floor.mjs

@@ -0,0 +1,479 @@
+/**
+ * G-133 — a scoped adoption floor, and the exceptions that are allowed to sit
+ * outside it.
+ *
+ * ===========================================================================
+ * WHY A FLOOR IS NOT A LEDGER
+ * ===========================================================================
+ *
+ * `ratchet.mjs` already answers "has this got worse?" — it records debt and
+ * judges the delta. That is the right instrument for a repository with 4,061
+ * existing findings and the wrong one for the opposite case: a product that
+ * has finished the work over a defined slice of its tree and wants the
+ * finishing to stay finished.
+ *
+ * A ledger cannot express that. An empty ledger for a scope says "nothing was
+ * recorded here", which is also what a scope nobody measured says, and the two
+ * must never render the same (CHARTER §5). A floor says something a ledger
+ * cannot: *of the eligible visual elements under this path, this many must be
+ * the system's, and here is the denominator.*
+ *
+ * ===========================================================================
+ * IT IS OPT-IN, AND THAT IS LOAD-BEARING RATHER THAN POLITE
+ * ===========================================================================
+ *
+ * There is no implicit floor and no repository-wide default. A product that
+ * declares nothing is measured exactly as it is today. CHARTER §2 keeps the
+ * DEFINITION of adoption Gyde's — a product cannot redefine the metric — but
+ * *where* a product has decided to hold a line is a product decision, and a
+ * floor Gyde imposed on a tree nobody had finished would be a gate that is red
+ * on arrival, which is a gate people switch off.
+ *
+ * ===========================================================================
+ * 100% MEANS ZERO, AND IS NEVER ROUNDED INTO EXISTENCE
+ * ===========================================================================
+ *
+ * `Math.round(999 / 1000 * 100)` is 100, and a report that prints "100%" over a
+ * denominator holding one bespoke element is a lie that reads as an
+ * achievement. So the comparison here is made on the COUNTS, not on the
+ * percentage: a floor of 100 is met when the bespoke count is zero, full stop.
+ * The percentage is a rendering of the fraction, floored, and it never appears
+ * without its numerator, its denominator and the scope it was taken over.
+ *
+ * ===========================================================================
+ * EXCEPTIONS ARE NAMED, REASONED, AND REPORTED OUTSIDE THE FIGURE
+ * ===========================================================================
+ *
+ * Some elements are not a missed component and never will be — a containment
+ * frame whose whole job is to be a sized box around something else. Counting
+ * them against a product teaches it to ignore the number; hiding them inside
+ * the NUMERATOR teaches it that adoption went up when nothing was adopted.
+ *
+ * So an exception leaves the denominator instead, individually, by name, with
+ * a reason, and is printed in its own block underneath the figure. The reader
+ * sees "17 of 17 (100%), 6 elements excepted" and can disagree with all six.
+ *
+ * THEY CANNOT GROW QUIETLY. An exception is a committed line of configuration,
+ * so adding one is a diff somebody reviews; and until it is declared the
+ * element it would have covered is an ordinary bespoke element that fails the
+ * floor. The ledger discipline this repository already applies reaches here
+ * unchanged — the list may only ever get shorter without a deliberate,
+ * reviewable act.
+ *
+ * AN EXCEPTION THAT MATCHES NOTHING IS AN ERROR. A stale entry is not
+ * harmless: it is a line of prose asserting that a hazard exists at a path
+ * where nothing does, and the next reader will believe it. It is also the only
+ * way the list could shrink invisibly — the element is refactored away and the
+ * exemption stays behind, ready to cover the next thing that lands there.
+ *
+ * ===========================================================================
+ * EVERY PATH FAILS CLOSED, AND THE ZERO-FILE CASE IS THE IMPORTANT ONE
+ * ===========================================================================
+ *
+ * A scope that matches no files would otherwise report 100% forever: no
+ * bespoke elements, floor met, green. That is this repository's oldest defect
+ * wearing a new hat — "a rule that matches nothing reads exactly like a rule
+ * that passes" — so it is an ERROR naming the scope, and so is an
+ * unresolvable path, a malformed entry, an unreadable barrel, and an exception
+ * naming something that is no longer there.
+ *
+ * None of them is a finding, none is allowanceable, and none can be turned into
+ * a pass by recording a baseline.
+ *
+ * ===========================================================================
+ * WHAT THIS DOES NOT PROTECT AGAINST
+ * ===========================================================================
+ *
+ * Stated plainly, because an unstated limit gets read as a covered one.
+ *
+ * - **It does not judge the exceptions.** Gyde checks that each one names a
+ *   real bespoke element and carries a reason somebody wrote. It cannot tell a
+ *   true reason from a plausible sentence, and a product that is willing to
+ *   write six false reasons can except six real components. What it buys is
+ *   that the six are on the artefact, in the diff, with names attached.
+ * - **It measures markup, not rendering.** An element classified as the
+ *   system's is one whose tag is an export of the declared design system. A
+ *   component that imports the system and then restyles it at the call site
+ *   still counts as system here; that is `stylex.mjs`'s question, not this
+ *   one.
+ * - **The scope is a path prefix, not a semantic boundary.** A floor over
+ *   `apps/x/src` covers what is under that path today. Code moved out from
+ *   under it silently leaves the floor's denominator — the figure stays true
+ *   and the coverage shrinks, and nothing here notices. The scope is printed
+ *   with the figure precisely so that a reader can.
+ * - **It says nothing about files with no visual decisions in them.** A scope
+ *   of two hundred files where only three carry markup reports a denominator
+ *   of three. The denominator is the honest part; whether three is enough
+ *   evidence is a judgement Gyde does not make for you.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+import { classifyMarkup, KIND } from "./markup.mjs";
+
+/** The config key a product declares floors under. */
+export const KEY = "design.adoptionFloors";
+
+/**
+ * Directories never walked, matching `scan.mjs`.
+ *
+ * Deliberately a copy rather than an import, and deliberately noted as one:
+ * `scan.mjs` does not export it. If a third copy ever appears, that is the
+ * moment to hoist it, not before.
+ */
+const SKIP_DIRS = new Set([
+  "node_modules", "dist", "build", ".next", ".turbo", ".git", "coverage",
+  "test-results", "__pycache__", ".venv", "e2e", "fixtures", "snapshots",
+]);
+
+/** Markup lives in JSX. A `.ts` file makes no elements. */
+const MARKUP_EXT = /\.(tsx|jsx)$/;
+
+/** Same exclusion `scan.mjs` makes: a test describes behaviour, it is not a surface. */
+const isTest = (p) => /\.(test|spec)\.(?:[cm]?[jt]sx?)$/.test(p) || /__tests__/.test(p);
+
+/** A file whose string literals are source for a DIFFERENT repository. */
+const TEMPLATE_MARKER = "@gyde-emits-source-for-another-repo";
+
+const FLOOR_KEYS = new Set(["scope", "minimum", "exceptions"]);
+const EXCEPTION_KEYS = new Set(["file", "element", "because"]);
+
+/**
+ * A reason has to be a sentence somebody wrote, not a placeholder.
+ *
+ * Twelve characters is not a quality bar — nothing here can be — it is a
+ * tripwire for `"n/a"`, `"todo"` and `"-"`, which is what an empty-string check
+ * alone lets through. The same trick `verify.mjs` plays on a truncated
+ * contract, for the same reason.
+ */
+const MIN_REASON = 12;
+
+/**
+ * Validate the declared floors.
+ *
+ * A SCHEMA check: it needs nothing but the value, so it runs wherever the
+ * config is read and costs nothing on a repository with no files yet. Every
+ * error names the entry it came from — "adoptionFloors[1].minimum" — because a
+ * config error that does not say which entry is a config error somebody fixes
+ * by guessing.
+ *
+ * @param {unknown} raw  `design.adoptionFloors` as committed
+ * @returns {{ ok: boolean, declared: boolean, floors: object[], errors: string[] }}
+ */
+export function validateFloors(raw) {
+  if (raw === undefined || raw === null) {
+    return { ok: true, declared: false, floors: [], errors: [] };
+  }
+  if (!Array.isArray(raw)) {
+    return {
+      ok: false, declared: true, floors: [],
+      errors: [`${KEY} must be an array of floor objects (got ${typeOf(raw)})`],
+    };
+  }
+  if (raw.length === 0) {
+    return {
+      ok: false, declared: true, floors: [],
+      errors: [
+        `${KEY} is an empty array. Declaring no floors and declaring the key are ` +
+        `different intentions, and an empty list would hold no line while looking ` +
+        `like it does — remove the key instead.`,
+      ],
+    };
+  }
+
+  const errors = [];
+  const floors = [];
+  const seen = new Map();
+
+  raw.forEach((floor, i) => {
+    const at = `${KEY}[${i}]`;
+    if (!isPlainObject(floor)) {
+      errors.push(`${at} must be an object (got ${typeOf(floor)})`);
+      return;
+    }
+    for (const key of Object.keys(floor)) {
+      if (!FLOOR_KEYS.has(key)) {
+        errors.push(`${at}.${key} is not a key Gyde knows. A key Gyde ignores reads as a ` +
+          `declaration Gyde honours; known keys are ${[...FLOOR_KEYS].join(", ")}.`);
+      }
+    }
+
+    const scope = floor.scope;
+    if (typeof scope !== "string" || scope.trim() === "") {
+      errors.push(`${at}.scope must be a non-empty path relative to the repository root, such as "apps/web/src"`);
+    } else if (scope.startsWith("/") || /(^|\/)\.\.(\/|$)/.test(scope)) {
+      errors.push(`${at}.scope must stay inside the repository: "${scope}" is absolute or escapes the root`);
+    } else if (seen.has(norm(scope))) {
+      errors.push(`${at}.scope "${scope}" is already declared at ${KEY}[${seen.get(norm(scope))}]. ` +
+        `Two floors over one scope is two answers to one question — merge them.`);
+    } else {
+      seen.set(norm(scope), i);
+    }
+
+    const min = floor.minimum;
+    if (typeof min !== "number" || !Number.isFinite(min) || !Number.isInteger(min) || min < 0 || min > 100) {
+      errors.push(`${at}.minimum must be a whole number from 0 to 100 (got ${JSON.stringify(min)})`);
+    }
+
+    const exceptions = floor.exceptions ?? [];
+    if (!Array.isArray(exceptions)) {
+      errors.push(`${at}.exceptions must be an array (got ${typeOf(exceptions)})`);
+    } else {
+      exceptions.forEach((ex, j) => {
+        const eat = `${at}.exceptions[${j}]`;
+        if (!isPlainObject(ex)) {
+          errors.push(`${eat} must be an object (got ${typeOf(ex)})`);
+          return;
+        }
+        for (const key of Object.keys(ex)) {
+          if (!EXCEPTION_KEYS.has(key)) {
+            errors.push(`${eat}.${key} is not a key Gyde knows; known keys are ${[...EXCEPTION_KEYS].join(", ")}.`);
+          }
+        }
+        if (typeof ex.file !== "string" || ex.file.trim() === "") {
+          errors.push(`${eat}.file must be the path of the file the element is in, relative to the repository root`);
+        }
+        if (typeof ex.element !== "string" || !/^[a-z][\w.-]*$/.test(ex.element)) {
+          errors.push(`${eat}.element must be the lowercase tag name of the bespoke element, such as "div". ` +
+            `A capitalised name is a component, and a component is never bespoke markup.`);
+        }
+        if (typeof ex.because !== "string" || ex.because.trim().length < MIN_REASON) {
+          errors.push(`${eat}.because must say why this element is structural and will never be a component ` +
+            `(at least ${MIN_REASON} characters). An exception nobody had to justify is an exemption, not an exception.`);
+        }
+      });
+    }
+
+    floors.push({
+      scope: typeof scope === "string" ? norm(scope) : scope,
+      minimum: min,
+      exceptions: Array.isArray(exceptions) ? exceptions : [],
+    });
+  });
+
+  return { ok: errors.length === 0, declared: true, floors: errors.length ? [] : floors, errors };
+}
+
+/**
+ * Every markup-bearing product file under a scope.
+ *
+ * Returns an `error` rather than an empty list for the two cases that must not
+ * look like a clean measurement: the path is not there, and the path is there
+ * and holds nothing to measure.
+ */
+export function collectScopeFiles(root, scope) {
+  const base = join(root, scope);
+  let st;
+  try { st = statSync(base); } catch {
+    return {
+      files: [], error:
+        `scope "${scope}" does not resolve to anything in this repository. ` +
+        `A floor over a path that is not there would measure nothing and pass forever.`,
+    };
+  }
+  if (!st.isDirectory() && !MARKUP_EXT.test(scope)) {
+    return { files: [], error: `scope "${scope}" is a file Gyde cannot read markup from; name a directory or a .tsx/.jsx file` };
+  }
+
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const name of entries.sort()) {
+      if (SKIP_DIRS.has(name) || name.startsWith(".")) continue;
+      const full = join(dir, name);
+      let s; try { s = statSync(full); } catch { continue; }
+      if (s.isDirectory()) { walk(full); continue; }
+      if (!MARKUP_EXT.test(name) || isTest(full)) continue;
+      let text; try { text = readFileSync(full, "utf8"); } catch { continue; }
+      // A generator holding another repository's source as string data is not
+      // this repository's markup, exactly as `scan.mjs` decides.
+      if (text.includes(TEMPLATE_MARKER)) continue;
+      out.push({ file: relative(root, full).split(sep).join("/"), text });
+    }
+  };
+
+  if (st.isDirectory()) walk(base);
+  else {
+    let text; try { text = readFileSync(base, "utf8"); } catch { text = null; }
+    if (text !== null && !text.includes(TEMPLATE_MARKER)) {
+      out.push({ file: norm(scope), text });
+    }
+  }
+
+  if (out.length === 0) {
+    return {
+      files: [], error:
+        `scope "${scope}" matched no markup files. This is an error rather than 100%: ` +
+        `a floor over an empty denominator reports success forever, and a rule that ` +
+        `matches nothing reads exactly like a rule that passes.`,
+    };
+  }
+  return { files: out.sort((a, b) => a.file.localeCompare(b.file)), error: null };
+}
+
+/**
+ * Measure one floor over an already-collected file set.
+ *
+ * Takes the files rather than walking, for the reason `markupAdoption` does:
+ * the scope decision is made in one place and cannot drift between the
+ * measurement and the thing printed beside it.
+ *
+ * @returns a result carrying `used`, `of`, `percent`, the scope, the exceptions
+ *   it applied, and — on any fail-closed path — `errors`.
+ */
+export function measureFloor(floor, files, { systemNames = null } = {}) {
+  const base = { scope: floor.scope, minimum: floor.minimum, used: null, of: null, percent: null,
+    bespoke: [], exceptions: [], errors: [], ok: false };
+
+  if (!systemNames || systemNames.size === 0) {
+    return { ...base, errors: [
+      `scope "${floor.scope}": the design system's exports could not be read, so no element ` +
+      `can be attributed to it. An unmeasurable floor is an error, never a pass — ` +
+      `"Gyde did not measure this" and "Gyde found nothing here" must not render the same.`,
+    ] };
+  }
+
+  /** Every bespoke element under the scope, in file then line order. */
+  const bespoke = [];
+  let system = 0;
+  for (const { file, text } of files) {
+    const r = classifyMarkup(text, { systemNames });
+    if (r.unknown) continue;
+    system += r.counts[KIND.SYSTEM];
+    for (const el of r.bespokeElements) bespoke.push({ file, element: el.name, line: el.line });
+  }
+
+  /**
+   * Apply the exceptions, one element each.
+   *
+   * One entry removes ONE element. An entry that covered every `div` in a file
+   * would let a seventh arrive under an exemption written for six, which is
+   * the silent expansion this whole mechanism exists to prevent.
+   */
+  const remaining = [...bespoke];
+  const applied = [];
+  const unmatched = [];
+  for (const ex of floor.exceptions) {
+    const at = remaining.findIndex((b) => b.file === norm(ex.file) && b.element === ex.element);
+    if (at === -1) { unmatched.push(ex); continue; }
+    applied.push({ ...remaining[at], because: ex.because });
+    remaining.splice(at, 1);
+  }
+
+  if (unmatched.length) {
+    return { ...base, exceptions: applied, errors: unmatched.map((ex) =>
+      `scope "${floor.scope}": the declared exception for <${ex.element}> in ${ex.file} matches no ` +
+      `bespoke element there. Either it was refactored away — in which case delete the exception, ` +
+      `because a stale one is an exemption waiting for the next element to land under it — or the ` +
+      `path is wrong and the real element is still in the denominator.`) };
+  }
+
+  const of = system + remaining.length;
+  if (of === 0) {
+    return { ...base, exceptions: applied, errors: [
+      `scope "${floor.scope}": ${files.length} file(s) were read and not one of them made a visual ` +
+      `decision, so there is nothing to hold a floor over. This is not 100%.`,
+    ] };
+  }
+
+  /**
+   * The verdict is taken on the COUNTS, never on the percentage.
+   *
+   * 999 of 1000 floors to 99 here, so this happens to agree — but it agrees by
+   * luck of the rounding direction, and a floor of 99 met by a rounded 99 is
+   * the same defect one point down. Comparing the fraction against the floor
+   * directly removes the question.
+   */
+  const percent = Math.floor((system / of) * 100);
+  const ok = floor.minimum === 100 ? remaining.length === 0 : system * 100 >= floor.minimum * of;
+
+  return {
+    scope: floor.scope, minimum: floor.minimum,
+    used: system, of, percent,
+    files: files.length,
+    bespoke: remaining,
+    exceptions: applied,
+    errors: [],
+    ok,
+  };
+}
+
+/**
+ * Check every declared floor against the repository.
+ *
+ * `errors` and `failures` are kept apart on purpose: an error means Gyde could
+ * not take the measurement and the run is invalid; a failure means it took the
+ * measurement and the line was not held. Both block, and a reader has to be
+ * able to tell which happened.
+ */
+export function checkFloors(root, design = {}, { systemNames = null } = {}) {
+  const schema = validateFloors(design.adoptionFloors);
+  if (!schema.declared) {
+    return { declared: false, ok: true, results: [], errors: [], failures: [] };
+  }
+  if (!schema.ok) {
+    return { declared: true, ok: false, results: [], errors: schema.errors, failures: [] };
+  }
+
+  const results = [];
+  const errors = [];
+  for (const floor of schema.floors) {
+    const { files, error } = collectScopeFiles(root, floor.scope);
+    if (error) {
+      errors.push(error);
+      results.push({ scope: floor.scope, minimum: floor.minimum, used: null, of: null,
+        percent: null, bespoke: [], exceptions: [], errors: [error], ok: false });
+      continue;
+    }
+    const r = measureFloor(floor, files, { systemNames });
+    results.push(r);
+    for (const e of r.errors) errors.push(e);
+  }
+
+  const failures = results.filter((r) => r.errors.length === 0 && !r.ok);
+  return { declared: true, ok: errors.length === 0 && failures.length === 0, results, errors, failures };
+}
+
+/** The gate's lines for this check. Never a bare percentage. */
+export function formatFloors(result) {
+  if (!result.declared) {
+    return `adoption floors  none declared — ${KEY} is opt-in, so nothing is held to a line here`;
+  }
+
+  const L = [`adoption floors  ${result.results.length} declared`];
+  for (const r of result.results) {
+    if (r.errors.length) {
+      L.push(`  ✖ ${r.scope}  COULD NOT MEASURE`);
+      for (const e of r.errors) L.push(`      ${e}`);
+      continue;
+    }
+    const mark = r.ok ? "✔" : "✖";
+    L.push(`  ${mark} ${r.scope}  ${r.used} of ${r.of} eligible element(s) are the system ` +
+      `— ${r.percent}%, floor ${r.minimum}%  (${r.files} file(s) read)`);
+    if (r.exceptions.length) {
+      L.push(`      ${r.exceptions.length} structural exception(s), excluded from the denominator above and listed here rather than counted as adoption:`);
+      for (const e of r.exceptions) L.push(`        <${e.element}> ${e.file}:${e.line} — ${e.because}`);
+    }
+    if (!r.ok) {
+      L.push(`      ${r.bespoke.length} bespoke element(s) are below the floor and are not declared exceptions:`);
+      for (const b of r.bespoke.slice(0, 10)) L.push(`        <${b.element}> ${b.file}:${b.line}`);
+      if (r.bespoke.length > 10) L.push(`        … and ${r.bespoke.length - 10} more`);
+      L.push(`      Use the component set, or declare each one in ${KEY} with a reason.`);
+    }
+  }
+
+  if (result.errors.length) {
+    L.push("");
+    L.push("  A floor Gyde could not measure is an error, not a pass. Nothing here is allowanceable:");
+    L.push("  a floor is a line the product drew, and a ledger cannot record a line as debt.");
+  }
+  return L.join("\n");
+}
+
+// -------------------------------------------------------------------- bits
+
+const norm = (p) => String(p).replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const typeOf = (v) => (v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`);

package/htmlscan.mjs

@@ -0,0 +1,149 @@
+/**
+ * A first-party HTML scanner for the theme-host gate — G-138.
+ *
+ * WHY THIS IS NOT parse5.
+ *
+ * `action.yml` runs this package straight out of the action checkout with no
+ * install step, so every module it reaches may import `node:` builtins and
+ * files inside the action path, and nothing else. `themehost.mjs` imported
+ * `parse5`, which is not carried there, and every consumer's gate went red the
+ * moment the tag moved (G-138). parse5 v8 is also a fifteen-file ESM tree with
+ * its own `entities` dependency, so carrying it would mean carrying a
+ * dependency tree by hand and re-copying it on every update.
+ *
+ * The job here is small and fully specified by `themehost.test.mjs`: find the
+ * elements a browser would actually execute in a plain HTML entry, and refuse
+ * to be fooled by markup written inside comments, templates, raw text, RCDATA
+ * or foreign content. That is worth 120 lines of our own code. Parsing
+ * arbitrary JavaScript is not, which is why `theme-entry.mjs` carries a
+ * vendored acorn instead of a hand-rolled lexer — see `vendor/README.md`.
+ *
+ * WHERE IT IS DELIBERATELY STRICTER THAN A BROWSER.
+ *
+ * Foreign content (`<svg>`, `<math>`) is skipped whole, including the HTML
+ * integration points — `foreignObject`, `desc`, `annotation-xml` — where a
+ * browser would return to the HTML namespace. A gate may only err towards
+ * refusing wiring it cannot prove: the cost is an author being told to move a
+ * bootstrap out of an SVG, and the alternative is a false pass. The same
+ * applies to `<noscript>`, whose contents are parsed as markup only with
+ * scripting disabled, and to `<template>`, whose contents are inert in the
+ * host document.
+ *
+ * Character references are not decoded. Raw text (`script`, `style`) is not
+ * entity-decoded by a browser either, and it is the only text this gate
+ * compares, so decoding RCDATA would add a difference nothing reads.
+ */
+
+/** Contents are text, never markup, and are not entity-decoded. */
+const RAW_TEXT = new Set(["script", "style"]);
+/** Contents are text, never markup. */
+const RCDATA = new Set(["textarea", "title"]);
+/** Never have contents, so they never open a scope. */
+const VOID = new Set(["area", "base", "br", "col", "embed", "hr", "img",
+  "input", "link", "meta", "param", "source", "track", "wbr"]);
+/** Contents are not executed in the host document, so they are not scanned. */
+const OPAQUE = new Set(["template", "noscript", "svg", "math"]);
+
+const NAME = /[a-zA-Z][^\s/>]*/y;
+const ATTR = /\s*([^\s/>=]+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s>]*))?/y;
+
+/** Skip to the end tag that closes `name`, honouring nesting of the same name. */
+function skipSubtree(html, from, name) {
+  let depth = 1;
+  const tag = new RegExp(`<(/?)${name}(?=[\\s/>])`, "giy");
+  for (let i = from; i < html.length; i += 1) {
+    tag.lastIndex = i;
+    const m = tag.exec(html);
+    if (!m) continue;
+    depth += m[1] ? -1 : 1;
+    if (depth === 0) return html.indexOf(">", m.index) + 1 || html.length;
+    i = m.index;
+  }
+  return html.length;
+}
+
+/**
+ * Every element a browser would put in the HTML namespace of this document,
+ * in source order, with the byte offset of its start tag.
+ *
+ * `index` is that offset, so "did the bootstrap come before this stylesheet"
+ * is answered from the source rather than from tree order, which an implied
+ * `<head>` would otherwise distort.
+ */
+export function htmlElements(html) {
+  const nodes = [];
+  const stack = [];
+  let i = 0;
+  const addText = (text) => { if (stack.length) stack.at(-1).text += text; };
+
+  while (i < html.length) {
+    const lt = html.indexOf("<", i);
+    if (lt === -1) { addText(html.slice(i)); break; }
+    addText(html.slice(i, lt));
+
+    if (html.startsWith("<!--", lt)) {
+      const end = html.indexOf("-->", lt + 4);
+      i = end === -1 ? html.length : end + 3;
+      continue;
+    }
+    if (html.startsWith("<!", lt) || html.startsWith("<?", lt)) {
+      const end = html.indexOf(">", lt);
+      i = end === -1 ? html.length : end + 1;
+      continue;
+    }
+    if (html.startsWith("</", lt)) {
+      NAME.lastIndex = lt + 2;
+      const closing = NAME.exec(html)?.[0]?.toLowerCase();
+      const end = html.indexOf(">", lt);
+      i = end === -1 ? html.length : end + 1;
+      if (closing) {
+        const at = stack.findLastIndex((n) => n.name === closing);
+        if (at !== -1) stack.length = at;
+      }
+      continue;
+    }
+
+    NAME.lastIndex = lt + 1;
+    const raw = NAME.exec(html)?.[0];
+    if (!raw) { addText("<"); i = lt + 1; continue; }
+    const name = raw.toLowerCase();
+
+    const attrs = new Map();
+    let cursor = lt + 1 + raw.length;
+    let selfClosing = false;
+    for (;;) {
+      while (html[cursor] === "/" ) { selfClosing = true; cursor += 1; }
+      if (cursor >= html.length || html[cursor] === ">") break;
+      ATTR.lastIndex = cursor;
+      const attr = ATTR.exec(html);
+      if (!attr || attr.index + attr[0].length === cursor) break;
+      cursor = ATTR.lastIndex;
+      const value = attr[2] ?? "";
+      attrs.set(attr[1].toLowerCase(), /^["']/.test(value) ? value.slice(1, -1) : value);
+    }
+    const open = html.indexOf(">", cursor);
+    i = open === -1 ? html.length : open + 1;
+
+    // Foreign and inert subtrees contribute no executable HTML element — not
+    // the container, and not anything inside it.
+    if (OPAQUE.has(name)) {
+      if (!selfClosing) i = skipSubtree(html, i, name);
+      continue;
+    }
+
+    const node = { name, attrs, parent: stack.at(-1)?.name ?? null, index: lt, text: "" };
+    nodes.push(node);
+    if (selfClosing || VOID.has(name)) continue;
+
+    if (RAW_TEXT.has(name) || RCDATA.has(name)) {
+      const close = new RegExp(`</${name}(?=[\\s/>])`, "i").exec(html.slice(i));
+      const end = close ? i + close.index : html.length;
+      node.text = html.slice(i, end);
+      const gt = html.indexOf(">", end);
+      i = close ? (gt === -1 ? html.length : gt + 1) : html.length;
+      continue;
+    }
+    stack.push(node);
+  }
+  return nodes;
+}

package/index.mjs

@@ -38,4 +38,5 @@ export { classifyMarkup, markupAdoption, formatMarkup, KIND as MARKUP_KIND } fro
 export { orphanedParts, formatOrphanedParts, RULE as COMPOUND_RULE } from "./compound.mjs";
 export { checkDocDrift, importedFrom, formatDocDrift, namedInProse, isContractDoc, isFixtureDeclaration, stalePaths, rootDirectories, formatStalePaths, RULE as DOC_DRIFT_RULE, PROSE_RULE, PATH_RULE } from "./docdrift.mjs";
 export { rules, rulesJson } from "./ruleindex.mjs";
+export { validateFloors, collectScopeFiles, measureFloor, checkFloors, formatFloors, KEY as ADOPTION_FLOORS_KEY } from "./floor.mjs";
 export { isClientModule, parseImports, parseReexports, valueUses, checkClientBoundary, formatClientBoundary } from "./clientboundary.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weatherboard/gyde-design",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "private": false,
   "description": "Scaffolds a design system into a product repository, then keeps auditing it.",
   "type": "module",
@@ -33,7 +33,9 @@
     "./props.mjs": "./props.mjs",
     "./docdrift.mjs": "./docdrift.mjs",
     "./compound.mjs": "./compound.mjs",
+    "./htmlscan.mjs": "./htmlscan.mjs",
     "./markup.mjs": "./markup.mjs",
+    "./floor.mjs": "./floor.mjs",
     "./adoption.mjs": "./adoption.mjs",
     "./tailwind.mjs": "./tailwind.mjs",
     "./migration.mjs": "./migration.mjs",
@@ -43,6 +45,8 @@
   "files": [
     "*.mjs",
     "!*.test.mjs",
+    "vendor/*.mjs",
+    "vendor/README.md",
     "README.md",
     "LICENSE"
   ],

package/theme-entry.mjs

@@ -1,5 +1,9 @@
 /** Parse the linked JavaScript module before accepting theme startup wiring. */
-import { parse } from "acorn";
+// 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 &&