@weatherboard/gyde-design 0.4.3 → 0.5.0

package/README.md

@@ -137,6 +137,7 @@ against all five.
 | `agentdocs.mjs` | What an agent building the product reads before writing UI. |
 | `ruleindex.mjs` | Every rule as data — id, name, intent, fix shape. Describes; never decides. |
 | `selfgate.mjs` | Emits a scaffold and gates it. Gyde held to its own rules. |
+| `floor.mjs` | Opt-in scoped adoption floors and their named structural exceptions. Fails closed on a scope that matches nothing. |
 
 ## Measured, on the three repositories it was built from
 
@@ -314,6 +315,87 @@ This command updates only `.gyde/design-system.md` and refuses to replace a
 handwritten file. It lists component names without guessing their props or
 claiming theme APIs that Gyde has not verified in that product.
 
+## A floor over a scope you have finished
+
+The ledger answers *has this got worse?* That is the right instrument for a
+repository carrying four thousand 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. An empty ledger cannot say that — "nothing
+was recorded here" is also what an unmeasured scope says.
+
+So a product may declare a **floor**, and nothing more happens without one:
+
+```json
+{
+  "design": {
+    "adoptionFloors": [
+      {
+        "scope": "apps/console/src",
+        "minimum": 100,
+        "exceptions": [
+          {
+            "file": "apps/console/src/frame/MediaFrame.tsx",
+            "element": "iframe",
+            "because": "A browser-owned element the design system cannot render or restyle from inside."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+| key | |
+| --- | --- |
+| `scope` | A path inside the repository. Not an npm scope — that is `design.scope`, a different key answering a different question. |
+| `minimum` | A whole number, 0 to 100. The fraction of eligible visual elements under the scope that must be the system's. |
+| `exceptions` | Elements excluded from the denominator. Each names one element, in one file, with one reason. |
+
+`gyde-design gate` prints the figure with its numerator, its denominator and the
+scope, and prints the exceptions underneath it rather than inside it. A working
+example is in `examples/scoped-floor`.
+
+**100% means zero.** The verdict is taken on the counts, never on the rendered
+percentage: 999 of 1,000 floors to 99% and does not meet a floor of 100. That is
+the whole reason this exists — a report reading "100%" over a denominator that
+still holds a bespoke element is a lie that looks like an achievement.
+
+**Exceptions cannot grow quietly.** One entry excuses one element. Until an
+element is declared it is an ordinary bespoke element and it fails the floor, so
+the seventh exception costs a diff a reviewer reads. And an exception that stops
+matching anything is an **error**: a stale exemption is a line sitting open for
+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.
+
+**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
+something that is gone — each is an ERROR that names the cause, and none of them
+is allowanceable or recordable as a baseline. The zero-file case is the one that
+mattered most: a floor over an empty denominator would report success forever,
+and a rule that matches nothing reads exactly like a rule that passes.
+
+### What a floor does not protect against
+
+- **Gyde does not judge the exceptions.** It checks that each names a real
+  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.
+- **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
+  layer's question, not this one.
+- **The scope is a path, not a semantic boundary.** Code moved out from under
+  it leaves the denominator silently. The figure stays true and the coverage
+  shrinks; nothing here notices. The scope is printed beside the figure
+  precisely so that a reader can.
+- **A small denominator is still a denominator.** A scope of two hundred files
+  where three carry markup reports three. Whether three is enough evidence is a
+  judgement Gyde does not make for you — which is why the number is never
+  printed without it.
+
+
 ## Not built yet
 
 Build-pipeline wiring for a compiled token layer — moot while the emitted tokens

package/cli.mjs

@@ -50,6 +50,7 @@ import { record, gate, formatGate, adopt, trim, formatTrim, LEDGER_NOTE } from "
 import { loadRules } from "./rules.mjs";
 import { validateScopeShape, checkScopeAgreement, formatScope } from "./scope.mjs";
 import { checkThemeHosts, formatThemeHosts } from "./themehost.mjs";
+import { checkFloors, formatFloors, validateFloors, KEY as FLOORS_KEY } from "./floor.mjs";
 
 /**
  * The single source of what would be written.
@@ -222,6 +223,22 @@ function readConfig(root) {
       "A scope names the packages the emitted code imports, so a wrong one produces imports that resolve to nothing.");
   }
 
+  /**
+   * G-133. The schema half of the adoption floors, at the same one place.
+   *
+   * Here rather than in `gate` alone for the reason above and one more: a floor
+   * is the only configuration in this file that can make a gate PASS, by
+   * excluding an element from a denominator. A malformed one must therefore be
+   * refused everywhere the config is read, and must never be recoverable by
+   * falling back to a default — a floor Gyde half-understood would hold a line
+   * nobody drew.
+   */
+  const floors = validateFloors(design.adoptionFloors);
+  if (!floors.ok) {
+    throw new Error(`gyde.config.json: ${FLOORS_KEY} is malformed and Gyde will not guess at it:\n  ` +
+      floors.errors.join("\n  "));
+  }
+
   return { present: true, design };
 }
 
@@ -346,6 +363,13 @@ function cmdScan(root, config) {
     console.log(formatUsage(usage, found));
   }
 
+  // G-133. Reported wherever adoption is reported, and reported even when no
+  // floor is declared — "none declared" and "all held" are different facts.
+  console.log("");
+  console.log(formatFloors(checkFloors(root, design, {
+    systemNames: scanRoots ? new Set(scanRoots) : null,
+  })));
+
   if (!config.present) {
     console.log(
       "\nnote         no gyde.config.json — every path was treated as product code.\n" +
@@ -618,7 +642,7 @@ function cmdGuidance(root, config, { write }) {
  * report the wrong one, confidently. So the evidence carries `why`, and every
  * path writes it.
  */
-function writeEvidence(root, result, { ok, why, clientBoundary = null, enforcement = null }) {
+function writeEvidence(root, result, { ok, why, clientBoundary = null, enforcement = null, floors = null }) {
   mkdirSync(join(root, ".gyde"), { recursive: true });
   writeFileSync(join(root, ".gyde", "last-verdict.json"), JSON.stringify({
     "//": "Written by `gyde-design gate`. Proof the gate ran, not just that a job went green.",
@@ -648,9 +672,24 @@ function writeEvidence(root, result, { ok, why, clientBoundary = null, enforceme
     rulesThatMatchedNothing: result ? result.coverage.filter((c) => !c.matched).map((c) => c.rule) : [],
     clientBoundary,
     enforcement,
+    /**
+     * G-133. The floors, with their denominators, so the action's summary can
+     * print the fraction rather than a percentage somebody has to trust.
+     */
+    floors,
   }, null, 2) + "\n");
 }
 
+/** The floors as data: never a bare percentage, always the fraction and the scope. */
+function floorEvidence(floors) {
+  if (!floors.declared) return null;
+  return floors.results.map((r) => ({
+    scope: r.scope, minimum: r.minimum, used: r.used, of: r.of, percent: r.percent,
+    exceptions: r.exceptions.length, bespoke: r.bespoke.length,
+    ok: r.ok, errors: r.errors,
+  }));
+}
+
 /** The design system package's own `name`, read from disk. Null when there is no package there. */
 function systemPackageName(root, systemPath) {
   try {
@@ -700,6 +739,31 @@ function cmdGate(root, config, { recordNewRules = false, trimLedger = false } =
   }
 
   const roots = exportedComponents(root, systemPath);
+
+  /**
+   * G-133. Before the baseline path, for the same reason theme hosts are.
+   *
+   * A floor is a line the product drew over a scope it says is finished. It is
+   * not style debt, so it is never an allowance entry — and recording a
+   * baseline underneath a floor that could not be measured would turn "Gyde
+   * could not tell" into a committed number and then into a pass.
+   */
+  const floors = checkFloors(root, design, { systemNames: roots ? new Set(roots) : null });
+  if (floors.declared) {
+    console.log(formatFloors(floors));
+    console.log("");
+  }
+  if (!floors.ok) {
+    writeEvidence(root, null, {
+      ok: false,
+      why: floors.errors.length
+        ? `an adoption floor could not be measured: ${floors.errors[0]}`
+        : `an adoption floor was not held: ${floors.failures.map((f) => `${f.scope} at ${f.used}/${f.of}, floor ${f.minimum}%`).join("; ")}`,
+      floors: floorEvidence(floors),
+    });
+    return 1;
+  }
+
   const result = scan(root, { config: { ...design, componentRoots: roots ? new Set(roots) : null } });
 
   // G-113. `--trim` on a repository with no ledger must NOT fall through to the
@@ -866,6 +930,7 @@ function cmdGate(root, config, { recordNewRules = false, trimLedger = false } =
 
   writeEvidence(root, result, {
     ok, why,
+    floors: floorEvidence(floors),
     clientBoundary: { crossings: cb.crossings.length, unresolved: cb.unresolved.length, blocking: cbBlocks },
     enforcement: {
       templateVersion,