@weatherboard/gyde-design 0.5.0 → 0.6.0

package/README.md

@@ -171,6 +171,24 @@ into their repository.
 product's; a scaffolder that clobbers has taken ownership of something it does
 not own, silently.
 
+## Importing a module directly
+
+The barrel (`@weatherboard/gyde-design`) is the curated named surface. Every
+module the package ships is also reachable by its own subpath:
+
+```js
+import { themeStartup } from "@weatherboard/gyde-design/theme-entry.mjs";
+import pkg from "@weatherboard/gyde-design/package.json" with { type: "json" };
+```
+
+That is a stated guarantee rather than an accident of file layout, and
+`exports.test.mjs` fails if a shipped module is not reachable — so verifying
+your own repository never means reaching into `node_modules` by filesystem
+path. The two exceptions are named there with their reasons: the CLI, which is
+the `bin` and executes on import, and the vendored parsers under `vendor/`,
+which ship so the Action can run with nothing installed and are not ours to
+promise.
+
 ## The rules, as data
 
 A rule id reaches you three times — in a finding, in the `rules` stamp inside
@@ -368,6 +386,19 @@ whatever lands under that name next, and it is the only way the list could
 shrink invisibly. The same discipline the allowance ledger has — it may only
 ever get shorter, and never by accident.
 
+**One `file` + tag may repeat, but not with different reasons.** An exception
+identifies its element by file and tag name matched in source order, so nothing
+records *which* `<div>` a reason was written about. Many elements sharing one
+argument is normal and safe — an inline-styled block of markup is genuinely one
+decision — and reordering them changes nothing a reader could act on. Two
+entries for one file and tag carrying **different** arguments is a different
+thing: a reorder reattaches each reason to an element nobody wrote it about,
+with the count, the figure and the verdict all unchanged. That is an **error**,
+and the fix is one reason true of the whole group, because that is the
+granularity the exemption actually has. No occurrence index is offered: an
+explicit ordinal makes the identity visible without making it stable, so the
+same reorder still reattaches the reasons, now with a number agreeing.
+
 **Every path fails closed.** A malformed entry, an unknown key, a scope that
 does not resolve, a scope that matches no markup files, a scope whose files make
 no visual decision, an unreadable component barrel, an exception naming
@@ -382,6 +413,13 @@ and a rule that matches nothing reads exactly like a rule that passes.
   bespoke element and carries a reason somebody wrote. It cannot tell a true
   reason from a plausible sentence. What it buys is that every one of them is
   on the artefact, in the diff, with a name and a line number attached.
+- **Element identity is still ordinal.** The reason-collision check above is a
+  check on the *configuration*, never on the source. A single entry for `<div>`
+  in a file that later grows a second bespoke `<div>` forms no group, so nothing
+  fires — and that entry now matches whichever comes first in source order,
+  which may not be the one it was written about. Within an identical-reason
+  group nothing is guarded at all, by design; if one member is later edited so
+  the shared reason stops being true of it, the group still validates.
 - **It measures markup, not rendering.** An element is the system's if its tag
   is one of the design system's exports. A component that imports the system
   and then restyles it at the call site still counts — that is the styling

package/floor.mjs

@@ -149,6 +149,112 @@ const EXCEPTION_KEYS = new Set(["file", "element", "because"]);
  */
 const MIN_REASON = 12;
 
+/**
+ * G-135 — two exceptions for one `file` + tag, carrying DIFFERENT reasons.
+ *
+ * ===========================================================================
+ * THE DEFECT, AND WHY THE OBVIOUS GUARD IS THE WRONG ONE
+ * ===========================================================================
+ *
+ * `measureFloor` identifies an excepted element by `file` + tag name, matched
+ * in SOURCE ORDER: the first unclaimed `<div>` in that file, then the next.
+ * Nothing in the configuration says WHICH `div`, because nothing in the
+ * configuration can. So move a block, wrap something, reorder a return — and
+ * entry 1's reason attaches to entry 2's element. Every element is still real,
+ * the count is still right, the floor is still met: the gate stays green and
+ * the ledger now misdescribes which element was argued for and why. A silent
+ * wrong answer, which this repository holds to be worse than a red one.
+ *
+ * The obvious guard — refuse any repeated `file` + tag — is too blunt, and
+ * measurably so. Against the first consumer to adopt a floor, fourteen of
+ * nineteen exceptions sat in same-file-same-tag groups, and thirteen of those
+ * were one inline-styled preview surface: many elements, genuinely ONE
+ * argument. Reordering them is harmless, because the reasons are
+ * interchangeable in fact and not merely in the matcher. Forcing thirteen
+ * distinct sentences there would produce worse prose, not better identity.
+ *
+ * So the hazard is not repetition. It is **repetition carrying different
+ * reasons**, and that is exactly what is checked here.
+ *
+ * ===========================================================================
+ * WHY THIS REFUSES RATHER THAN WARNS
+ * ===========================================================================
+ *
+ * Every other malformed floor is an error — an unknown key, a duplicate scope,
+ * a zero-match scope, a stale exception. A warning would be the one advisory
+ * thing in a fail-closed file, and this repository's standing finding is that
+ * a gate nobody must act on is a gate that does not exist.
+ *
+ * The usual objection to refusing is that it removes a capability with nothing
+ * to replace it. It does not, and this is the crux: the per-element precision
+ * a differing-reason group appears to have **was never delivered**. Four divs
+ * with four reasons read as four arguments about four elements; the matcher
+ * can only offer "four of the divs in this file are excepted". The
+ * configuration is claiming a precision the mechanism does not have, and
+ * refusing it is Gyde declining to keep up the appearance.
+ *
+ * The way to express it is therefore already in the format, needs no new key,
+ * and is what the error says: **write one reason that covers the group.** A
+ * single argument true of all four members is a claim the matcher can actually
+ * honour, and a reader who disagrees with it disagrees with all four at once —
+ * which is the granularity the exemption really has.
+ *
+ * NO DISAMBIGUATOR IS ADDED, AND THAT IS A DECISION RATHER THAN AN OMISSION.
+ * An optional occurrence index (`nth`) is the tempting small fix and it buys
+ * nothing: it makes the ordinal identity EXPLICIT without making it STABLE, so
+ * the reorder that reattached the reasons silently still reattaches them —
+ * now with a number in the config agreeing. Line anchors and content hashes do
+ * fix identity, and were rejected on the issue for churning a reviewed ledger
+ * into a file people update mechanically without reading, which is the failure
+ * the reasons exist to prevent. A guard that needs no new vocabulary is worth
+ * more here than a key that needs one and still does not work.
+ *
+ * ===========================================================================
+ * WHAT THIS DOES NOT PROTECT AGAINST
+ * ===========================================================================
+ *
+ * - **A reorder inside an identical-reason group.** Deliberately unguarded:
+ *   the reasons are interchangeable, so the reattachment changes nothing a
+ *   reader could act on. The residue is that if one member is later edited so
+ *   the shared reason stops being true of it, the group still validates and
+ *   nothing notices.
+ * - **A collision introduced by the FILE rather than the config.** This is a
+ *   schema check: it reads the configuration and never the source. One entry
+ *   for `<div>` in a file that later grows a second bespoke `<div>` is not a
+ *   group, so nothing here fires — and yet the single entry now matches
+ *   whichever `div` comes first in source order, which may not be the one it
+ *   was written about. That is the same defect arriving from the other side,
+ *   and it is not covered.
+ * - **Whether a shared reason is true.** As everywhere else in this file,
+ *   Gyde checks that a reason was written, never that it is honest.
+ */
+function reasonCollisions(at, exceptions) {
+  const groups = new Map();
+  exceptions.forEach((ex, j) => {
+    if (!isPlainObject(ex) || typeof ex.file !== "string" || typeof ex.element !== "string") return;
+    const key = JSON.stringify([norm(ex.file), ex.element]);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push({ j, because: typeof ex.because === "string" ? ex.because.trim() : "" });
+  });
+
+  const out = [];
+  for (const [key, members] of groups) {
+    if (members.length < 2) continue;
+    const distinct = new Set(members.map((m) => m.because));
+    if (distinct.size < 2) continue;
+    const [file, element] = JSON.parse(key);
+    out.push(
+      `${at}.exceptions: ${members.length} exceptions name <${element}> in ${file} and ${distinct.size} of them ` +
+      `give DIFFERENT reasons (entries ${members.map((m) => m.j).join(", ")}). An exception identifies its element ` +
+      `by file and tag name in source order, so nothing records which <${element}> each reason was written about: ` +
+      `reorder the file and the reasons reattach to different elements, silently, with the count and the verdict ` +
+      `unchanged. Repeating a tag is fine — repeating it with different arguments is not. Give the group ONE reason ` +
+      `that is true of all ${members.length}, which is the granularity this exemption actually has.`,
+    );
+  }
+  return out;
+}
+
 /**
  * Validate the declared floors.
  *
@@ -243,6 +349,7 @@ export function validateFloors(raw) {
             `(at least ${MIN_REASON} characters). An exception nobody had to justify is an exemption, not an exception.`);
         }
       });
+      for (const e of reasonCollisions(at, exceptions)) errors.push(e);
     }
 
     floors.push({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weatherboard/gyde-design",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": false,
   "description": "Scaffolds a design system into a product repository, then keeps auditing it.",
   "type": "module",
@@ -15,32 +15,39 @@
   },
   "exports": {
     ".": "./index.mjs",
-    "./workspace.mjs": "./workspace.mjs",
-    "./normalise.mjs": "./normalise.mjs",
-    "./rules.mjs": "./rules.mjs",
-    "./ruleindex.mjs": "./ruleindex.mjs",
-    "./scan.mjs": "./scan.mjs",
-    "./tokens.mjs": "./tokens.mjs",
+    "./package.json": "./package.json",
+    "./adoption.mjs": "./adoption.mjs",
+    "./agentdocs.mjs": "./agentdocs.mjs",
     "./boundaries.mjs": "./boundaries.mjs",
-    "./ratchet.mjs": "./ratchet.mjs",
-    "./emit.mjs": "./emit.mjs",
     "./catalogue.mjs": "./catalogue.mjs",
-    "./agentdocs.mjs": "./agentdocs.mjs",
-    "./upgrade.mjs": "./upgrade.mjs",
-    "./usage.mjs": "./usage.mjs",
-    "./wiring.mjs": "./wiring.mjs",
     "./clientboundary.mjs": "./clientboundary.mjs",
-    "./props.mjs": "./props.mjs",
-    "./docdrift.mjs": "./docdrift.mjs",
     "./compound.mjs": "./compound.mjs",
+    "./docdrift.mjs": "./docdrift.mjs",
+    "./emit.mjs": "./emit.mjs",
+    "./enforcement.mjs": "./enforcement.mjs",
+    "./floor.mjs": "./floor.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",
+    "./normalise.mjs": "./normalise.mjs",
+    "./props.mjs": "./props.mjs",
+    "./ratchet.mjs": "./ratchet.mjs",
+    "./ruleindex.mjs": "./ruleindex.mjs",
+    "./rules.mjs": "./rules.mjs",
+    "./scan.mjs": "./scan.mjs",
+    "./scope.mjs": "./scope.mjs",
+    "./selfgate.mjs": "./selfgate.mjs",
     "./stylex.mjs": "./stylex.mjs",
-    "./enforcement.mjs": "./enforcement.mjs"
+    "./tailwind.mjs": "./tailwind.mjs",
+    "./theme-choice.mjs": "./theme-choice.mjs",
+    "./theme-entry.mjs": "./theme-entry.mjs",
+    "./themehost.mjs": "./themehost.mjs",
+    "./tokens.mjs": "./tokens.mjs",
+    "./upgrade.mjs": "./upgrade.mjs",
+    "./usage.mjs": "./usage.mjs",
+    "./wiring.mjs": "./wiring.mjs",
+    "./workflow.mjs": "./workflow.mjs",
+    "./workspace.mjs": "./workspace.mjs"
   },
   "files": [
     "*.mjs",

package/theme-entry.mjs

@@ -106,29 +106,103 @@ export function parseEntry(source) {
   }
 }
 
+/**
+ * Why the answer names the QUESTION it answered, and not only "no" (G-141).
+ *
+ * `{ started: false, parseError: null }` used to be the answer to four
+ * different questions, and a caller could not tell them apart:
+ *
+ *   - the entry has no import of `startThemeChoice` at all
+ *   - it imports it as a TYPE, which is erased before the module runs
+ *   - it imports it and the call is not the next top-level statement
+ *   - `systemPackage` was never passed, so the walk searched for an import
+ *     from the literal string `undefined/theme-choice` and matched nothing
+ *
+ * The last is a CALLER error and not a verdict about the entry, and it is the
+ * one that cost two wrong measurements: `themeStartup(source)` reads unary,
+ * returns the byte-identical shape of a genuinely unwired entry, and a
+ * correctly-wired file is then reported as failing the gate. So a missing or
+ * non-string `systemPackage` now THROWS rather than being searched for. A
+ * programming mistake that produces a plausible verdict is worse than one that
+ * produces an exception, which is G-134's lesson one layer along: a file the
+ * parser never read is not a wiring complaint, and a question nobody asked is
+ * not a wiring verdict either.
+ *
+ * The other three are real verdicts and stay verdicts — but each gets its own
+ * `reason`, because the caller's single message named only the third
+ * possibility and was therefore a false statement about the first two.
+ */
+export const STARTUP_REASON = Object.freeze({
+  STARTED: "started",
+  PARSE_ERROR: "parse-error",
+  /** Nothing in the file imports `startThemeChoice` as a value from the controller. */
+  NO_IMPORT: "no-import",
+  /** It is imported, but as a type, so the binding does not exist at runtime. */
+  TYPE_ONLY_IMPORT: "type-only-import",
+  /** It is imported as a value, and the call is not the next top-level statement. */
+  CALL_NOT_ADJACENT: "call-not-adjacent",
+});
+
+/**
+ * Worse news wins. A file with one irrelevant import and one nearly-correct one
+ * should be told about the nearly-correct one, so the reasons are ranked and
+ * the walk keeps the strongest it has seen rather than the last.
+ */
+const REASON_RANK = [
+  STARTUP_REASON.NO_IMPORT,
+  STARTUP_REASON.TYPE_ONLY_IMPORT,
+  STARTUP_REASON.CALL_NOT_ADJACENT,
+];
+
 /**
  * Only an actual VALUE import followed by a direct top-level call counts.
  *
- * `{ started: true }`              the contract is met
- * `{ started: false }`             parsed fine, the wiring is not there
- * `{ started: false, parseError }` never read; say so and say where
+ * `{ started: true,  reason: "started" }`        the contract is met
+ * `{ started: false, reason: "no-import" }`      parsed fine, nothing imports it
+ * `{ started: false, reason: "type-only-import" }` imported, but erased at runtime
+ * `{ started: false, reason: "call-not-adjacent" }` imported, not called next
+ * `{ started: false, reason: "parse-error", parseError }` never read; say where
+ *
+ * @throws {TypeError} if `systemPackage` is missing or is not a non-empty
+ *   string. See the note above: searching for `undefined/theme-choice` and
+ *   reporting the miss as a wiring failure is a lie about the consumer's file.
  */
 export function themeStartup(source, systemPackage) {
+  if (typeof systemPackage !== "string" || systemPackage === "") {
+    throw new TypeError(
+      "themeStartup(source, systemPackage): systemPackage must be a non-empty string naming the design-system " +
+      `package whose /theme-choice module the entry imports; received ${
+        systemPackage === undefined ? "undefined — it takes TWO arguments" : JSON.stringify(systemPackage)}`,
+    );
+  }
   const { program, error } = parseEntry(source);
-  if (error) return { started: false, parseError: error };
+  if (error) return { started: false, reason: STARTUP_REASON.PARSE_ERROR, parseError: error };
+  let reason = STARTUP_REASON.NO_IMPORT;
+  const worse = (next) => {
+    if (REASON_RANK.indexOf(next) > REASON_RANK.indexOf(reason)) reason = next;
+  };
   for (const [index, node] of program.body.entries()) {
     if (node.type !== "ImportDeclaration" ||
         node.source.value !== `${systemPackage}/theme-choice`) continue;
-    // `import type { … }` is erased before the module runs.
-    if (node.importKind === "type") continue;
-    const binding = node.specifiers.find((part) => part.type === "ImportSpecifier" &&
-      part.importKind !== "type" &&
-      part.imported.type === "Identifier" && part.imported.name === "startThemeChoice")?.local.name;
-    if (!binding) continue;
+    const named = node.specifiers.find((part) => part.type === "ImportSpecifier" &&
+      part.imported.type === "Identifier" && part.imported.name === "startThemeChoice");
+    if (!named) continue;
+    // `import type { … }` and `import { type … }` are both erased before the
+    // module runs, so the call beside them throws rather than starting the theme.
+    if (node.importKind === "type" || named.importKind === "type") {
+      worse(STARTUP_REASON.TYPE_ONLY_IMPORT);
+      continue;
+    }
+    worse(STARTUP_REASON.CALL_NOT_ADJACENT);
+    const binding = named.local.name;
     const next = program.body[index + 1];
-    if (next?.type === "ExpressionStatement" && directCall(next.expression, binding)) return { started: true };
+    if (next?.type === "ExpressionStatement" && directCall(next.expression, binding)) {
+      return { started: true, reason: STARTUP_REASON.STARTED, parseError: null };
+    }
     if (next?.type === "VariableDeclaration" && next.kind === "const" &&
-        next.declarations.length === 1 && directCall(next.declarations[0].init, binding)) return { started: true };
+        next.declarations.length === 1 && directCall(next.declarations[0].init, binding)) {
+      return { started: true, reason: STARTUP_REASON.STARTED, parseError: null };
+    }
   }
-  return { started: false, parseError: null };
+  return { started: false, reason, parseError: null };
 }

package/themehost.mjs

@@ -2,7 +2,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join, resolve, relative, sep } from "node:path";
 import { htmlElements } from "./htmlscan.mjs";
-import { themeStartup } from "./theme-entry.mjs";
+import { themeStartup, STARTUP_REASON } from "./theme-entry.mjs";
 
 function within(root, path) {
   if (typeof path !== "string" || !path || path.startsWith("/")) return null;
@@ -24,14 +24,43 @@ function read(root, path) {
  */
 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"] };
+  if (declared === undefined) return { declared: 0, checked: 0, errors: [] };
+  if (!Array.isArray(declared)) return { declared: 0, checked: 0, errors: ["design.themeHosts must be an array"] };
   const errors = [];
+  /**
+   * `declared` and `checked` are two different numbers and used to be one
+   * (G-141 follow-up). The config-gap return below reported
+   * `checked: declared.length` from a path that inspects nothing — a count
+   * claiming work it did not do, which is the same defect class as the verdict
+   * that claimed an answer to a question nobody asked. CHARTER §5: "Gyde did
+   * not run" and "Gyde found nothing" must never render the same, and a single
+   * number cannot tell them apart.
+   *
+   * So this one is COUNTED as hosts are inspected rather than restated from
+   * the input. A count derived from `declared.length` is an assertion about
+   * the loop; a count the loop increments is a measurement of it, and only the
+   * second goes wrong when the loop stops running.
+   */
+  let checked = 0;
   const systemPath = design.systemPath || "packages/design-system";
-  const systemPackage = design.systemPackage || `${design.scope}/design-system`;
+  // `${undefined}/design-system` is a STRING, so an undeclared scope used to
+  // produce the specifier "undefined/design-system", match no import, and be
+  // reported as a consumer's broken wiring (G-141, same shape as the arity bug
+  // below). Say which key is missing instead.
+  const named = (value) => (typeof value === "string" && value !== "" ? value : null);
+  const systemPackage = named(design.systemPackage) ??
+    (named(design.scope) ? `${design.scope}/design-system` : null);
+  if (systemPackage === null) {
+    return {
+      declared: declared.length,
+      checked: 0,
+      errors: ["design.themeHosts is declared, but neither design.systemPackage nor design.scope names the design-system package the entry must import"],
+    };
+  }
   const expected = read(root, `${systemPath}/src/theme-bootstrap.js`);
   for (const [index, host] of declared.entries()) {
     const label = `design.themeHosts[${index}]`;
+    checked += 1;
     if (!host || typeof host !== "object" || host.adapter !== "html-inline") {
       errors.push(`${label}: unsupported adapter; this gate currently supports html-inline`);
       continue;
@@ -74,20 +103,35 @@ export function checkThemeHosts(root, design = {}, { packages = null } = {}) {
     // A file the parser never finished reading has not failed the wiring
     // contract; it has failed to be read. Saying otherwise sends the reader to
     // rearrange imports the parser never reached (G-134).
+    //
+    // And one message for "not wired" was a false statement about two of the
+    // three ways an entry can be unwired (G-141): a file with no import at all
+    // was told its call was misplaced. Each reason gets the sentence that is
+    // true of it, or the reader is sent to fix something that is not wrong.
     const startup = themeStartup(entry, systemPackage);
-    if (startup.parseError) {
+    if (startup.reason === STARTUP_REASON.PARSE_ERROR) {
       const { message, line, column } = startup.parseError;
       const at = line === null ? "" : ` at line ${line}, column ${column}`;
       errors.push(`${label}: declared module entry ${host.entry} could not be parsed${at} — ${message}`);
-    } else if (!startup.started) {
-      errors.push(`${label}: linked entry must import and immediately call startThemeChoice at module top level`);
+    } else if (startup.reason === STARTUP_REASON.NO_IMPORT) {
+      errors.push(`${label}: linked entry ${host.entry} has no import of startThemeChoice from ${systemPackage}/theme-choice`);
+    } else if (startup.reason === STARTUP_REASON.TYPE_ONLY_IMPORT) {
+      errors.push(`${label}: linked entry ${host.entry} imports startThemeChoice as a TYPE, which is erased before the module runs — import it as a value and call it at module top level`);
+    } else if (startup.reason === STARTUP_REASON.CALL_NOT_ADJACENT) {
+      errors.push(`${label}: linked entry ${host.entry} imports startThemeChoice but must call it immediately, at module top level`);
     }
   }
-  return { checked: declared.length, errors };
+  return { declared: declared.length, checked, errors };
 }
 
+/**
+ * Both numbers are printed, always. The line used to render `checked` under
+ * the word "declared", so one number stood for two claims and the reader could
+ * not see a run that declared hosts and inspected none of them.
+ */
 export function formatThemeHosts(result) {
+  const counts = `${result.declared} declared, ${result.checked} checked`;
   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`;
+    ? `theme hosts  ${counts}, ${result.errors.length} error(s):\n${result.errors.map((e) => `  ${e}`).join("\n")}`
+    : `theme hosts  ${counts}`;
 }