@weatherboard/gyde-design 0.3.0

package/rules.mjs

@@ -0,0 +1,258 @@
+/**
+ * G-51 — the violation rules, written once against the normalised form.
+ *
+ * WHAT IS DIFFERENT ABOUT THESE.
+ *
+ * Every rule here takes a `Decl` (see normalise.mjs), never a line of source.
+ * That is the whole design: `rounded-lg`, `border-radius: 8px`, `borderRadius: 8`
+ * and a cva variant string all arrive as the same radius decision, so one rule
+ * covers three repositories written in three idioms.
+ *
+ * TWO STRUCTURAL GUARANTEES, both learned from rules that failed silently.
+ *
+ * 1. **A rule with no failing fixture does not load.** System A's
+ *    phrasing is the standard: "A rule without one is assumed broken." Here it
+ *    is not a convention — `loadRules()` throws. A rule nobody proved against a
+ *    known-bad example is worse than no rule, because it reports zero.
+ *
+ * 2. **A rule with no passing fixture does not load either.** The fix for a rule
+ *    that catches nothing is to widen it, and the natural end of widening is a
+ *    rule that catches everything. A noisy rule gets switched off exactly as
+ *    fast as a silent one, so both directions are pinned.
+ *
+ * WHAT THE RULES DELIBERATELY DO NOT DO.
+ *
+ * They never name a product's component, token, route or brand value. If a rule
+ * cannot be stated without one, it is a leak and belongs in per-project
+ * configuration (G-55's genericity check enforces this). The thresholds and the
+ * allowed token prefixes are configuration; the concepts are not.
+ */
+
+import { PROP } from "./normalise.mjs";
+
+/**
+ * Classifications that are not violations, and why that matters.
+ *
+ * System A finished its remediation with 33 violations, of which three were
+ * "containment rules for foreign content — the iframe's column, the iframe, a
+ * screenshot of someone else's page. Not a visual vocabulary."
+ *
+ * A rule set that cannot tell foreign-content containment from bespoke styling
+ * reports those three forever, and a number that never reaches zero stops being
+ * read. So the category exists, it is declared per project, and code inside it
+ * is COUNTED AND REPORTED SEPARATELY rather than dropped — the same discipline
+ * as the exemption registry in boundaries.mjs.
+ */
+export const CLASSIFICATION = {
+  SYSTEM: "system",        // the design system's own source — it IS the tokens
+  FOREIGN: "foreign",      // containment for content we do not control
+  PRODUCT: "product",      // ordinary product code: the rules apply in full
+};
+
+export const DEFAULTS = {
+  /** Prefixes that mark a class as belonging to a declared vocabulary rather than being bespoke. */
+  classPrefixes: ["ds-", "dx-", "cx-"],
+  /** How many distinct type sizes a project may spell before it has a scale problem. */
+  maxTypeSizes: 6,
+  /** Shadows are a deliberate, countable decision. System A shipped with exactly one. */
+  maxShadows: 1,
+};
+
+/**
+ * Every rule: `{ id, summary, property, test }`.
+ *
+ * `test(decl, config)` returns true when the declaration VIOLATES the rule.
+ * Keeping the predicate positive ("this is wrong") rather than negative reads
+ * the same way the finding does, which is a small thing that stops sign errors.
+ */
+const RULES = [
+  {
+    id: "untokenised-radius",
+    property: PROP.RADIUS,
+    summary: "A radius spelled at the call site rather than taken from the dictionary.",
+    // Both mature systems here independently closed radius to exactly three
+    // semantic values (card, control, pill), and System A measured
+    // that radius had NOT drifted even while type and space had — 2 distinct
+    // values across 807 lines. So this is the cheapest rule to adopt and the
+    // one most likely to already pass.
+    test: (d) => !d.tokenised && !d.neutral && d.px !== null,
+  },
+  {
+    id: "untokenised-space",
+    property: PROP.SPACE,
+    summary: "A padding, margin or gap spelled at the call site.",
+    test: (d) => !d.tokenised && !d.neutral && d.px !== null,
+  },
+  {
+    id: "untokenised-type",
+    property: PROP.TYPE,
+    summary: "A font size spelled at the call site.",
+    test: (d) => !d.tokenised && !d.neutral && d.px !== null,
+  },
+  {
+    id: "untokenised-colour",
+    property: PROP.COLOR,
+    summary: "A colour literal, or a palette colour chosen at the call site.",
+    test: (d) => !d.tokenised && !d.neutral,
+  },
+  {
+    id: "arbitrary-shadow",
+    property: PROP.SHADOW,
+    summary: "A shadow that is not from the dictionary. Depth is a semantic decision, not a garnish.",
+    test: (d) => !d.tokenised && !d.neutral,
+  },
+];
+
+export const RULES_BY_ID = new Map(RULES.map((r) => [r.id, r]));
+
+/**
+ * Fixtures. Every rule needs both lists, and `loadRules` enforces it.
+ *
+ * The `bad` entries are deliberately spelled in DIFFERENT IDIOMS from each
+ * other. That is the point of the whole module: if `untokenised-radius` is
+ * tested only against `border-radius: 8px`, it is being validated against
+ * exactly the rule we are trying not to write again.
+ */
+export const FIXTURES = {
+  "untokenised-radius": {
+    bad: [
+      { css: ".a { border-radius: 8px }" },
+      { source: '<div className="rounded-lg" />', filename: "a.tsx" },
+      { source: '<div className="rounded-3xl" />', filename: "a.tsx" },     // the spelling one hand-written audit missed
+      { source: "const s = { borderRadius: 8 }", filename: "a.ts" },
+      { source: '<div className="rounded-[7px]" />', filename: "a.tsx" },
+    ],
+    good: [
+      { css: ".a { border-radius: var(--radius-card) }" },
+      { css: ".a { border-radius: 0 }" },
+      { source: "const s = { borderRadius: radius.control }", filename: "a.ts" },
+      { source: '<div className="rounded-card" />', filename: "a.tsx" },     // project semantic radius
+    ],
+  },
+  "untokenised-space": {
+    bad: [
+      { css: ".a { padding: 12px }" },
+      { css: ".a { margin: 0 auto 12px }" },                                 // only the third value is wrong
+      { source: '<div className="px-4" />', filename: "a.tsx" },
+      { source: "const s = { gap: 16 }", filename: "a.ts" },
+    ],
+    good: [
+      { css: ".a { padding: var(--space-3) }" },
+      { css: ".a { padding: 0 var(--space-2) }" },
+      { css: ".a { margin: 0 }" },
+    ],
+  },
+  "untokenised-type": {
+    bad: [
+      { css: ".a { font-size: 13px }" },
+      { css: ".a { font-size: 1.125rem }" },
+      { source: '<span className="text-3xl" />', filename: "a.tsx" },
+    ],
+    good: [
+      { css: ".a { font-size: var(--text-body) }" },
+      { source: "const s = { fontSize: text.body }", filename: "a.ts" },
+    ],
+  },
+  "untokenised-colour": {
+    bad: [
+      { css: ".a { color: #ff0000 }" },
+      { css: ".a { background: rgb(12 14 16) }" },
+      { css: ".a { border-color: red }" },
+      { source: '<div className="bg-red-500" />', filename: "a.tsx" },
+      { source: 'el.style.background = "#fff"', filename: "a.ts" },
+    ],
+    good: [
+      { css: ".a { color: var(--color-text) }" },
+      { css: ".a { background: transparent }" },
+      { source: '<div className="bg-primary" />', filename: "a.tsx" },        // shadcn semantic utility
+      { source: '<div className="text-muted-foreground" />', filename: "a.tsx" },
+      { css: ":root { --color-surface: #0b0d10 }" },                          // a second palette, legitimately
+    ],
+  },
+  "arbitrary-shadow": {
+    bad: [
+      { css: ".a { box-shadow: 0 1px 2px rgba(0,0,0,.2) }" },
+      { source: '<div className="shadow-lg" />', filename: "a.tsx" },
+    ],
+    good: [
+      { css: ".a { box-shadow: var(--shadow-overlay) }" },
+      { css: ".a { box-shadow: none }" },
+    ],
+  },
+};
+
+/**
+ * Load the rules, refusing any that is not proved in both directions.
+ *
+ * Throwing rather than warning is deliberate. A warning at load time is read
+ * once and then lives in a log nobody opens; the failure mode we are guarding
+ * against is precisely a rule that is present, believed, and not working.
+ */
+export function loadRules({ fixtures = FIXTURES } = {}) {
+  const missing = [];
+  for (const rule of RULES) {
+    const f = fixtures[rule.id];
+    if (!f || !Array.isArray(f.bad) || f.bad.length === 0) missing.push(`${rule.id}: no failing fixture`);
+    if (!f || !Array.isArray(f.good) || f.good.length === 0) missing.push(`${rule.id}: no passing fixture`);
+  }
+  if (missing.length) {
+    throw new Error(
+      "Refusing to load rules that are not proved in both directions:\n  " + missing.join("\n  ") +
+      "\nA rule with no failing fixture reports zero and looks identical to a rule that works.",
+    );
+  }
+  return RULES;
+}
+
+/**
+ * Run every rule over a set of normalised declarations.
+ *
+ * `classification` decides whether findings apply: the design system's own
+ * source defines the tokens rather than consuming them, and foreign-content
+ * containment is not a visual vocabulary. Both are reported in their own
+ * buckets rather than filtered away, so the denominator never moves silently.
+ */
+export function run(decls, { config = DEFAULTS, classification = CLASSIFICATION.PRODUCT } = {}) {
+  const rules = loadRules();
+  const findings = [];
+
+  if (classification === CLASSIFICATION.PRODUCT) {
+    for (const d of decls) {
+      for (const rule of rules) {
+        if (rule.property !== d.property) continue;
+        if (!rule.test(d, config)) continue;
+        findings.push({
+          rule: rule.id,
+          property: d.property,
+          raw: d.raw,
+          line: d.line ?? null,
+          source: d.source,
+          // Carried through so a reviewer can tell a measured violation from an
+          // inferred one. A finding derived from an assumed Tailwind scale is
+          // still a finding, but it is not the same evidence as a literal.
+          confidence: d.confidence,
+          scaleHint: d.scaleHint,
+        });
+      }
+    }
+  }
+
+  return { classification, findings, counted: decls.length };
+}
+
+/**
+ * Coverage: which rules matched nothing anywhere.
+ *
+ * "A rule that matched zero files across an entire repository is reported as
+ * SUSPICIOUS, not as clean." This is the direct countermeasure to the
+ * failure, where `no-rounded-lg` reported zero against 178 real hits and nobody
+ * could tell. Silence and success must not render the same.
+ */
+export function coverage(allFindings, { rules = loadRules() } = {}) {
+  const seen = new Set(allFindings.map((f) => f.rule));
+  return rules.map((r) => ({
+    rule: r.id,
+    matched: seen.has(r.id),
+    verdict: seen.has(r.id) ? "firing" : "suspicious — matched nothing; verify it can still match at all",
+  }));
+}

package/scan.mjs

@@ -0,0 +1,291 @@
+/**
+ * G-51/G-52 — walk a project, normalise it, run the rules, report honestly.
+ *
+ * THE MEASUREMENT BUGS THIS IS BUILT AGAINST.
+ *
+ * Both prior implementations shipped a correct rule set and still reported the
+ * wrong number, twice, for reasons that had nothing to do with the rules:
+ *
+ * - System B measured only `apps/pubs/src` for a long stretch, then widened. Adding
+ *   a newly-measured app moved the headline DOWN while no file got worse, so
+ *   their gate had to compare per-app rather than on the average.
+ * - `apps/map` and `apps/pints` reported **0% adoption** while composing a
+ *   shared package that renders design-system UI, because the import graph was
+ *   resolved at barrel level rather than per name.
+ *
+ * Both are scope errors, not rule errors. So this module's contract is that
+ * **scope is always explicit and always reported**: every file walked is
+ * counted, every file skipped is named with a reason, and a percentage is never
+ * emitted without the denominator beside it.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, extname, sep } from "node:path";
+
+import { normaliseSource } from "./normalise.mjs";
+import { run, coverage, CLASSIFICATION, DEFAULTS, loadRules } from "./rules.mjs";
+import { optionalProps, requiredNullableGuards, RULE as OPTIONAL_PROP_RULE, GUARD_RULE } from "./props.mjs";
+import { orphanedParts, RULE as COMPOUND_RULE } from "./compound.mjs";
+import { stalePaths, rootDirectories, PATH_RULE } from "./docdrift.mjs";
+import { markupAdoption } from "./markup.mjs";
+import { reconcile, formatAdoption } from "./adoption.mjs";
+import { tailwindInCss } from "./tailwind.mjs";
+
+const SKIP_DIRS = new Set([
+  "node_modules", "dist", "build", ".next", ".turbo", ".git", "coverage",
+  "test-results", "__pycache__", ".venv", "e2e", "fixtures", "snapshots",
+]);
+
+const READ = new Set([".css", ".scss", ".ts", ".tsx", ".js", ".jsx", ".mjs"]);
+
+/** A file whose string literals are source for a DIFFERENT repository. */
+const TEMPLATE_MARKER = "@gyde-emits-source-for-another-repo";
+
+/**
+ * A test file describes behaviour; it is not a surface anybody sees.
+ *
+ * `[jt]sx?` missed `.mjs` and `.cjs`, so `foo.test.mjs` was walked as product
+ * code. It cost nothing while the rules only read styling — a test file has
+ * little — and cost forty false findings the moment a rule started reading
+ * string literals, because a test's fixtures are the one place paths and
+ * component APIs are written to be wrong on purpose.
+ */
+const isTest = (p) => /\.(test|spec)\.(?:[cm]?[jt]sx?)$/.test(p) || /__tests__/.test(p);
+
+/**
+ * How a file is classified, and why the answer must be declared rather than guessed.
+ *
+ * `system` and `foreign` both suppress findings, so a wrong classification is a
+ * silent pass — the failure mode this whole product exists to prevent. They are
+ * therefore taken from configuration the project commits, never inferred from a
+ * path heuristic, and every classified path is echoed in the report so a
+ * reviewer can see what was excused and disagree with it.
+ */
+export function classify(relPath, config) {
+  const match = (globs = []) => globs.some((g) => {
+    if (g.endsWith("/**")) return relPath.startsWith(g.slice(0, -3));
+    if (g.endsWith("/")) return relPath.startsWith(g);
+    return relPath === g || relPath.startsWith(g + "/");
+  });
+
+  if (match(config.systemPaths)) return CLASSIFICATION.SYSTEM;
+  if (match(config.foreignPaths)) return CLASSIFICATION.FOREIGN;
+  return CLASSIFICATION.PRODUCT;
+}
+
+function walk(dir, root, out) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const name of entries) {
+    if (SKIP_DIRS.has(name) || name.startsWith(".")) continue;
+    const full = join(dir, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) { walk(full, root, out); continue; }
+    if (!READ.has(extname(name))) continue;
+    if (isTest(full)) continue;
+    out.push(relative(root, full).split(sep).join("/"));
+  }
+}
+
+/**
+ * Scan a directory tree.
+ *
+ * `config.systemPaths` / `config.foreignPaths` are project configuration: the
+ * design system's own source, and the places that legitimately contain styling
+ * for content we do not control. Everything else is product code.
+ */
+export function scan(root, { config = {}, ruleConfig = DEFAULTS } = {}) {
+  const cfg = { systemPaths: [], foreignPaths: [], componentRoots: null, ...config };
+
+  const files = [];
+  walk(root, root, files);
+  files.sort();
+
+  // G-70. Computed once: the anchor for deciding whether a path-shaped string
+  // is a claim about THIS repository.
+  const rootDirs = rootDirectories(root);
+  let pathsSkipped = 0;
+
+  // G-73. Collected during the walk rather than re-read afterwards, so the
+  // scope decisions above — product code only, no templates written for another
+  // repository — are made once and cannot drift between the two adoption
+  // numbers. A metric measured over a different file set than the one it is
+  // printed beside is the scope error this module's header exists about.
+  const markupFiles = [];
+
+  // G-98. Counted here because normalise.mjs is the one place that knows what a
+  // Tailwind utility is. Counting them again in tailwind.mjs would be a second
+  // implementation of the same question, free to disagree with the first.
+  let tailwindClasses = 0;
+  let tailwindCssDirectives = 0;
+
+  const findings = [];
+  const perFile = [];
+  const byClassification = { system: 0, foreign: 0, product: 0 };
+
+  for (const rel of files) {
+    let text;
+    try { text = readFileSync(join(root, rel), "utf8"); } catch { continue; }
+
+    const classification = classify(rel, cfg);
+    byClassification[classification]++;
+
+    // G-68. Before the styling short-circuit below: a file can declare a
+    // component API and contain no styling at all, and that file is exactly
+    // where a Props type lives.
+    // A generator holds another repository's source as string data. Reading it
+    // as this repository's own code is how Gyde scanning itself reported ten
+    // optional props that live in its emitted TEMPLATES, and thirty-six stale
+    // paths that resolve perfectly well in the repository they are written for.
+    //
+    // The marker is the convention paths.test.mjs and clientboundary.mjs
+    // already use. It is an opt-out a file must DECLARE, not a heuristic — and
+    // it does not weaken the checks in a consumer repository, where the
+    // emitted components are real files that say no such thing.
+    const isTemplateSource = text.includes(TEMPLATE_MARKER);
+
+    if (classification === CLASSIFICATION.PRODUCT && !isTemplateSource) {
+      for (const f of optionalProps(text, { filename: rel })) findings.push(f);
+      // G-69. The defect G-68 creates. The ban pushes optional props towards
+      // required-nullable, and every guard already written against undefined
+      // becomes always-true at that moment, with no compiler error.
+      for (const f of requiredNullableGuards(text, { filename: rel })) findings.push(f);
+      // G-72. `componentRoots` is the design system's own exports, passed in
+      // rather than read here — scan walks a tree, it does not resolve barrels.
+      // Absent, the check is skipped rather than run against every `Foo.Bar` in
+      // JSX position, because a rule with no allow-list here would be guessing.
+      if (cfg.componentRoots) {
+        for (const f of orphanedParts(text, { filename: rel, roots: cfg.componentRoots })) findings.push(f);
+      }
+      // G-70, second half. A path rendered to a reader is documentation
+      // whatever file it lives in — a consumer lost six of twenty registry
+      // entries to a migration because their doc gate only read markdown.
+      const paths = stalePaths(root, rel, text, { rootDirs });
+      for (const f of paths.found) findings.push(f);
+      pathsSkipped += paths.skipped.length;
+      if (/\.(tsx|jsx)$/.test(rel)) markupFiles.push({ file: rel, text });
+    }
+
+    const decls = normaliseSource(text, { filename: rel });
+    if (decls.length === 0) continue;
+
+    for (const d of decls) if (d.source === "tailwind") tailwindClasses++;
+    // G-98, fourth level. A stylesheet can carry the whole vocabulary with no
+    // class in any component, and it breaks on removal the same silent way.
+    if (/\.(css|scss)$/.test(rel)) tailwindCssDirectives += tailwindInCss(text, { filename: rel }).length;
+
+    const result = run(decls, { config: ruleConfig, classification });
+    const tokenised = decls.filter((d) => d.tokenised || d.neutral).length;
+
+    perFile.push({
+      file: rel,
+      classification,
+      declarations: decls.length,
+      tokenised,
+      findings: result.findings.length,
+    });
+    for (const f of result.findings) findings.push({ ...f, file: rel });
+  }
+
+  const product = perFile.filter((f) => f.classification === CLASSIFICATION.PRODUCT);
+  const declarations = product.reduce((n, f) => n + f.declarations, 0);
+  const tokenised = product.reduce((n, f) => n + f.tokenised, 0);
+
+  return {
+    root,
+    // Scope, always reported beside the numbers it produced.
+    scope: {
+      filesWalked: files.length,
+      filesWithStyling: perFile.length,
+      byClassification,
+      systemPaths: cfg.systemPaths,
+      foreignPaths: cfg.foreignPaths,
+    },
+    // Adoption as a fraction with its denominator visible, never a bare percent.
+    adoption: { tokenised, of: declarations, percent: declarations ? Math.round((tokenised / declarations) * 100) : null },
+    /**
+     * G-73. A different question, deliberately reported separately rather than
+     * folded into the number above.
+     *
+     * Declaration adoption asks what fraction of style decisions are tokenised.
+     * A page built entirely from bare divs with semantic utility classes scores
+     * beautifully on it and is not using the component set at all. Markup
+     * adoption asks what fraction of the elements that made a visual decision
+     * are the system's.
+     *
+     * Neither is wrong and neither replaces the other. Averaging them would
+     * produce a third number describing nothing. Reconciling them is G-74.
+     */
+    markup: markupAdoption(markupFiles, { systemNames: cfg.componentRoots }),
+    findings,
+    /**
+     * Every rule this scan RAN, whether or not it found anything.
+     *
+     * The ledger stamps this (G-68), and the first version stamped
+     * `loadRules()` instead — which knows only the five Decl rules. The two
+     * Props rules were therefore never in the stamp, so they were unknown to
+     * every ledger, adopted on every run, and could never ratchet. A rule that
+     * reports forever and gates never is the exact silence this product
+     * exists to prevent, and it was introduced by the mechanism meant to let
+     * rules arrive safely.
+     *
+     * Derived here rather than assembled by the caller, so a rule added to
+     * this function cannot be left out of the stamp.
+     */
+    rulesRun: [...new Set([
+      ...loadRules().map((r) => r.id),
+      OPTIONAL_PROP_RULE, GUARD_RULE,
+      // Only when it actually ran. Stamping a rule the scan SKIPPED is the same
+      // bug in reverse: the ledger would claim to know it, so the day roots
+      // become available its first finding fails instead of adopting — the
+      // surprise red build the stamp exists to prevent.
+      PATH_RULE,
+      ...(cfg.componentRoots ? [COMPOUND_RULE] : []),
+    ])].sort(),
+    pathsSkipped,
+    tailwindClasses,
+    tailwindCssDirectives,
+    byRule: tally(findings, (f) => f.rule),
+    byFile: tally(findings, (f) => f.file),
+    // Which rules never fired. Silence and success must not render the same.
+    coverage: coverage(findings),
+    perFile,
+  };
+}
+
+function tally(items, key) {
+  const out = {};
+  for (const i of items) out[key(i)] = (out[key(i)] || 0) + 1;
+  return Object.fromEntries(Object.entries(out).sort((a, b) => b[1] - a[1]));
+}
+
+/**
+ * A short human report.
+ *
+ * Prints the denominator, the classified-out paths, and the rules that matched
+ * nothing — in that order, because those are the three things that make a
+ * headline number either trustworthy or meaningless.
+ */
+export function format(result) {
+  const L = [];
+  const { scope, adoption } = result;
+  L.push(`scope        ${scope.filesWithStyling} files with styling, of ${scope.filesWalked} walked`);
+  L.push(`             product ${scope.byClassification.product}, system ${scope.byClassification.system}, foreign ${scope.byClassification.foreign}`);
+  // G-74. One figure, defined as the weakest layer, with both layers under it.
+  // Printing two headline percentages was the state this replaces: a reader had
+  // to decide which one meant "adopted", and two teams reading the same output
+  // reached different answers.
+  L.push(formatAdoption(reconcile({
+    token: { ...adoption, used: adoption.tokenised },
+    markup: result.markup?.unknown ? null : result.markup?.adoption,
+  })));
+  L.push(`findings     ${result.findings.length}`);
+  for (const [rule, n] of Object.entries(result.byRule)) L.push(`               ${String(n).padStart(5)}  ${rule}`);
+  const silent = result.coverage.filter((c) => !c.matched);
+  if (silent.length) {
+    L.push(`suspicious   ${silent.length} rule(s) matched nothing anywhere:`);
+    for (const s of silent) L.push(`               ${s.rule}`);
+  }
+  return L.join("\n");
+}