@weatherboard/gyde-design 0.3.0 → 0.4.0

package/cli.mjs

@@ -21,7 +21,7 @@
  * matched nothing are reported as suspicious rather than omitted.
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join, resolve, dirname } from "node:path";
 
@@ -43,7 +43,7 @@ import { checkDocDrift, formatDocDrift } from "./docdrift.mjs";
 import { reconcile } from "./adoption.mjs";
 import { detectTailwind, formatTailwind } from "./tailwind.mjs";
 import { migrationProgress, formatMigration } from "./migration.mjs";
-import { checkStyleX, formatStyleX } from "./stylex.mjs";
+import { checkStyleX, formatStyleX, checkClosedStyling, formatClosedStyling } from "./stylex.mjs";
 import { blocksAt, formatSchedule, SCHEDULE } from "./enforcement.mjs";
 import { buildUsage, guidance, formatUsage } from "./usage.mjs";
 import { record, gate, formatGate, adopt, LEDGER_NOTE } from "./ratchet.mjs";
@@ -64,6 +64,24 @@ import { loadRules } from "./rules.mjs";
  * silently never fires. Returns null when it cannot tell, so the caller falls
  * back explicitly instead of this function inventing an answer.
  */
+/**
+ * The design system's own component sources, read from disk.
+ *
+ * Read rather than imported (G-100): a prop removed from a type but still
+ * spread onto the element is a hole an import-based check cannot see, and the
+ * emitted set makes the same choice for the same reason.
+ */
+function systemComponents(root, design) {
+  const dir = join(root, design.systemPath || "packages/design-system", "src");
+  let names; try { names = readdirSync(dir); } catch { return []; }
+  return names
+    .filter((n) => /^[A-Z]\w*\.tsx$/.test(n))
+    .map((n) => {
+      try { return { file: n, text: readFileSync(join(dir, n), "utf8") }; } catch { return null; }
+    })
+    .filter(Boolean);
+}
+
 function detectDefaultBranch(root) {
   try {
     const head = execFileSync("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
@@ -276,7 +294,11 @@ function cmdScan(root, config) {
   // not be removed while classes still resolve through it.
   // G-100. The positive half of G-98: one styling layer, and it is wired.
   console.log("");
-  console.log(formatStyleX(checkStyleX(root, { packages: ws.packages, renders: sum.carryUI })));
+  console.log(formatClosedStyling(checkClosedStyling(root, {
+    packages: ws.packages,
+    renders: sum.carryUI,
+    components: systemComponents(root, config.design || {}),
+  })));
 
   console.log("");
   console.log(formatTailwind(detectTailwind(root, {
@@ -653,13 +675,17 @@ function cmdGate(root, config) {
     utilityClasses: result.tailwindClasses,
     cssDirectives: result.tailwindCssDirectives,
   });
-  const sx = checkStyleX(root, { packages: ws.packages, renders: summarise(ws).carryUI });
+  const sx = checkClosedStyling(root, {
+    packages: ws.packages,
+    renders: summarise(ws).carryUI,
+    components: systemComponents(root, design),
+  });
 
   const breaches = [
     { rule: "client-boundary", n: cb.crossings.length, what: `${cb.crossings.length} value(s) crossing the "use client" boundary` },
     { rule: "tailwind-present", n: tw.present ? tw.dependencies.length + tw.configs.length : 0, what: "Tailwind is installed" },
     { rule: "tailwind-in-css", n: result.tailwindCssDirectives, what: `${result.tailwindCssDirectives} Tailwind directive(s) in stylesheets` },
-    { rule: "styling-layer", n: sx.unknown ? 0 : sx.missing.length + sx.unwired.length + sx.competing.length, what: "the styling layer is not StyleX, or is not wired" },
+    { rule: "styling-layer", n: sx.unknown || sx.ok ? 0 : sx.hatches.length + sx.competing.length, what: "the styling layer is open — a call site can restyle the component set" },
   ].filter((b) => b.n > 0);
 
   const blocking = breaches.filter((b) => blocksAt(b.rule, templateVersion));

package/emit.mjs

@@ -60,7 +60,7 @@ import { generateCss, SEED, varName, CSS_HEADER } from "./tokens.mjs";
  * `emit.test.mjs` enforces it: a fresh scaffold must pass the gate Gyde would
  * run against it.
  */
-export const SCAFFOLD_VERSION = "0.2.4";
+export const SCAFFOLD_VERSION = "0.3.0";
 
 const GENERATED = (what) => `/* GENERATED BY GYDE — then yours.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weatherboard/gyde-design",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Scaffolds a design system into a product repository, then keeps auditing it.",
   "type": "module",

package/stylex.mjs

@@ -45,6 +45,7 @@
  */
 
 import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { propMembers } from "./props.mjs";
 import { join } from "node:path";
 
 export const RULE = "styling-layer";
@@ -176,3 +177,110 @@ export function formatStyleX(result) {
   }
   return L.join("\n");
 }
+
+/**
+ * G-100, narrowed — the styling layer must be CLOSED, not specifically StyleX.
+ *
+ * The original mandate named an implementation, and its own scaffold failed it.
+ * Gyde emits components that style through data attributes against one
+ * stylesheet of custom properties, exposing no `className` and no `style` prop
+ * at all — and `emit.mjs` ships a test that fails the build if one appears.
+ *
+ * That set is STRICTER than StyleX, not looser. `stylex.props()` returns a
+ * className, which is the escape hatch this rule exists to close. Converting
+ * the templates to satisfy the letter of G-100 would have weakened the wall and
+ * added a compiler to every scaffold — the cost G-58 Decision 3 measured and
+ * declined.
+ *
+ * So the mandate is restated as the property it was always about:
+ *
+ *   A design system's components must not accept styling from the call site.
+ *
+ * StyleX satisfies it when wired. So does a closed component set over custom
+ * properties. Tailwind does not, which was the actual point (G-98), and neither
+ * does a component that takes `className`.
+ *
+ * WHY THE COMPONENT API IS THE REAL CHECK.
+ *
+ * Package detection asks what a repository INSTALLED. This asks what its
+ * components ACCEPT, which is the thing that decides whether every other rule
+ * is enforceable or advisory: one `className` prop on one shared component
+ * makes the token layer optional everywhere it is used, whatever the manifest
+ * says. G-58 Decision 2 called the wrapper the wall; this is the test that the
+ * wall has no door in it.
+ */
+export const CLOSED_RULE = "styling-layer";
+
+/** Props that hand styling control back to the call site. */
+const ESCAPE_HATCH = /^(className|class|style|css|sx|tw|unstyled|classNames)$/;
+
+/**
+ * Does the design system expose a way to style it from outside?
+ *
+ * `components` is the source of the system's own components, as
+ * `[{ file, text }]`. Read rather than imported: a prop removed from a type but
+ * still spread onto the element is a hole an import-based check cannot see.
+ */
+export function escapeHatches(components) {
+  const found = [];
+  for (const { file, text } of components) {
+    for (const m of propMembers(text, { filename: file })) {
+      if (!ESCAPE_HATCH.test(m.prop)) continue;
+      found.push({
+        file, rule: CLOSED_RULE, line: m.line, raw: m.prop,
+        prop: m.prop, type: m.type, kind: "escape-hatch",
+      });
+    }
+  }
+  return found;
+}
+
+/**
+ * Is the styling layer closed?
+ *
+ * Two ways to satisfy it, and the check reports WHICH, because "closed by
+ * construction" and "closed by StyleX" fail differently later and a consumer
+ * should know which one they are relying on.
+ */
+export function checkClosedStyling(root, { packages = [], renders = null, components = [] } = {}) {
+  const hatches = escapeHatches(components);
+  const sx = checkStyleX(root, { packages, renders });
+
+  // A competing runtime CSS-in-JS is still a second way to express styles, and
+  // that stays a finding whichever implementation is chosen.
+  const competing = sx.unknown ? [] : sx.competing;
+
+  const hasStyleX = !sx.unknown && sx.missing.length === 0 && sx.unwired.length === 0;
+  const closedByConstruction = components.length > 0 && hatches.length === 0;
+
+  return {
+    unknown: components.length === 0 && sx.unknown,
+    hatches, competing,
+    implementation: hasStyleX ? "stylex" : closedByConstruction ? "closed-set" : null,
+    stylex: sx,
+    ok: hatches.length === 0 && competing.length === 0 && (hasStyleX || closedByConstruction),
+    componentsChecked: components.length,
+  };
+}
+
+export function formatClosedStyling(r) {
+  if (r.unknown) return "styling layer could not tell — no components read and no package manifest to judge";
+  if (r.ok) {
+    return r.implementation === "stylex"
+      ? `styling layer closed, via StyleX (${r.componentsChecked} component(s) expose no styling prop)`
+      : `styling layer closed by construction — ${r.componentsChecked} component(s) accept no className, style or css prop`;
+  }
+
+  const L = [`styling layer ${r.hatches.length + r.competing.length} problem(s)`];
+  for (const h of r.hatches) L.push(`             ${h.file}:${h.line}  ${h.type}.${h.prop} — the call site can restyle this component`);
+  for (const c of r.competing) L.push(`             ${c.package}  ${c.name}@${c.version} — ${c.why}`);
+  if (r.hatches.length) {
+    L.push("");
+    L.push("  One styling prop on one shared component makes the token layer optional");
+    L.push("  everywhere it is used, whatever the manifest says. The wrapper is the wall");
+    L.push("  (G-58 §2); this is the test that the wall has no door in it.");
+  } else if (!r.implementation) {
+    L.push(`             no closed styling layer detected — neither StyleX wired, nor a component set without escape hatches`);
+  }
+  return L.join("\n");
+}