@weatherboard/gyde-design 0.3.0

package/boundaries.mjs

@@ -0,0 +1,350 @@
+/**
+ * G-55 — boundary rules, and the register of what is exempt.
+ *
+ * The shape is System A's (`packages/design-audit/src/boundaries.ts`),
+ * adopted rather than reinvented, with two things made structural that were
+ * conventions there.
+ *
+ * 1. **`why` is required.** Every boundary carries an argument written as prose,
+ *    not a label. A rule with a name survives until the first person it
+ *    inconveniences; a rule with a reason has to be argued with. Their Base UI
+ *    entry is the model, and it is quoted in full in the seed below.
+ *
+ * 2. **An exemption keeps counting.** `RENDERS_UI_WITHOUT_THE_SYSTEM` exists
+ *    *"because 'we forgot' and 'we decided' look identical from outside, and
+ *    this is the list that says which one it was."* The load-bearing detail is
+ *    that exempt code's violations stay in the allowance rather than being
+ *    excused — an exemption that shrinks the denominator hides the thing it
+ *    exempts, which is how two of System B's apps reported 0% adoption without
+ *    anybody bypassing anything.
+ *
+ * THE DEPENDENCY RULE IS NEW, and System C is why. Its dashboard
+ * declares twelve Radix packages it does not import — at versions newer than
+ * the shared UI package pins. An import rule catches somebody reaching past the
+ * wrapper; only a dependency rule catches the standing invitation to do it.
+ *
+ * @gyde-emits-source-for-another-repo — the G-71 fixtures below are import
+ * lines written as data, for a repository that is not this one. Without the
+ * marker, paths.test.mjs resolves `"./scale"` and `"../utils"` against this
+ * directory and reports them as broken. This module imports nothing but
+ * `node:` builtins, so the marker costs no real coverage here.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, relative, extname, sep } from "node:path";
+
+const SKIP = new Set(["node_modules", "dist", "build", ".next", ".turbo", ".git", "coverage"]);
+const SOURCE = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".css"]);
+
+/**
+ * The seed boundaries.
+ *
+ * `from: ""` means everywhere. Paths are workspace-relative prefixes; the
+ * primitive package name is configuration, because which headless library a
+ * project uses is the product's choice (G-58) and a rule that hard-codes one
+ * would be a leak.
+ */
+export function seedBoundaries({ primitive = "@base-ui/react", systemPath = "packages/design-system", tokensPath = "packages/design-tokens", appPaths = [] } = {}) {
+  return [
+    {
+      from: tokensPath,
+      forbid: [{
+        pattern: new RegExp(escape(systemPath.split("/").pop())),
+        why: "the dictionary cannot depend on the components; it is the layer beneath them, and the cycle would make either one unusable alone",
+        // The pattern is the LAST SEGMENT of a configured path put through a
+        // regex escape. Four transformations from what a reader pictures, and
+        // any of them can yield a pattern that never fires.
+        catches: [`import { Button } from "@acme/${systemPath.split("/").pop()}";`],
+        allows: ["import { space } from \"./scale\";"],
+      }],
+    },
+    {
+      from: systemPath,
+      forbid: appPaths.map((app) => ({
+        pattern: new RegExp(escape(app)),
+        why: "a component that knows which app it is in is not a component",
+        catches: [`import { route } from "../../${app}/routes";`],
+        allows: ["import { cn } from \"../utils\";"],
+      })),
+    },
+    {
+      from: "",
+      exceptIn: [systemPath],
+      forbid: [{
+        pattern: new RegExp(escape(primitive)),
+        catches: [`import { Checkbox } from "${primitive}/checkbox";`],
+        allows: [`import { Checkbox } from "@acme/${systemPath.split("/").pop()}";`],
+        why: `${primitive} is the BEHAVIOUR under ${systemPath} and nothing else may reach it. Its components accept className, style and a render prop on every part — by design, because they are unstyled primitives — so an app importing one directly makes every refusal in the component set advisory again. The design system wraps them and keeps its own closed API; that wrapper is the wall, and this is the rule that stops somebody walking round it`,
+      }],
+    },
+  ].filter((b) => b.forbid.length > 0);
+}
+
+const escape = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Dependency boundaries: who may DECLARE a package, not just import one.
+ *
+ * Separate from the import rules because the failure is different. An undeclared
+ * import is a build error somebody notices; a declared-but-unused dependency is
+ * a loaded gun sitting in a manifest, and it is what System C has today.
+ */
+export function seedDependencyBoundaries({ primitive = "@base-ui/react", systemPath = "packages/design-system" } = {}) {
+  return [{
+    packagePattern: new RegExp("^" + escape(primitive)),
+    onlyIn: [systemPath],
+    catches: [primitive, primitive + "/checkbox"],
+    allows: ["react", "@acme/" + systemPath.split("/").pop()],
+    why: `only ${systemPath} may depend on the primitive library. A package that declares it can import it, and the boundary check would then be the only thing standing between an app and the unwrapped API — one rule deep instead of two`,
+  }];
+}
+
+/**
+ * Does this line breach this pattern?
+ *
+ * Extracted so the fixtures below are proved through the SAME predicate the
+ * real check runs. A fixture verified against a re-implementation of the rule
+ * proves the re-implementation.
+ */
+export function isImportBreach(line, pattern) {
+  const code = String(line).replace(/\/\/.*$/, "").replace(/\/\*.*?\*\//g, "");
+  if (!/\b(import|require|from)\b/.test(code)) return false;
+  return pattern.test(code);
+}
+
+/** Every boundary must carry an argument. Checked at load, like the rule fixtures. */
+export function validateBoundaries(boundaries) {
+  const problems = [];
+  for (const b of boundaries) {
+    for (const f of b.forbid || []) {
+      if (!f.pattern) problems.push(`boundary from "${b.from}": no pattern`);
+      if (!f.why || String(f.why).trim().split(/\s+/).length < 8) {
+        problems.push(
+          `boundary from "${b.from}" (${f.pattern}): the reason is missing or is a label rather than an argument. ` +
+          `A rule with a name survives until the first person it inconveniences`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * G-71 — prove every boundary bites, and prove it discriminates.
+ *
+ * WHY PRESENCE IS NOT ENOUGH HERE.
+ *
+ * `loadRules` checks that fixtures EXIST. For a boundary that is too weak, and
+ * the reason is the shape of the thing being checked: a boundary is a regular
+ * expression, and the failure mode is a regex that silently matches nothing.
+ * `new RegExp(escape(systemPath.split("/").pop()))` is four transformations
+ * away from the string a reader has in mind, and every one of them can produce
+ * a pattern that is valid, loads cleanly, and never fires.
+ *
+ * A ban enforced with an empty allow-list makes that undetectable. Silence is
+ * its success condition — "no breaches" is exactly what a working ban and a
+ * broken pattern both print. So these fixtures are EXECUTED, not merely
+ * counted, and they are executed through `isImportBreach`, the same predicate
+ * `checkBoundaries` runs.
+ *
+ * Both directions are required, for the reason rules.mjs gives: the fix for a
+ * rule that catches nothing is to widen it, and the natural end of widening is
+ * a rule that catches everything. `catches` pins one end, `allows` the other.
+ *
+ * This is the check a product's own fixture linting was doing. It must exist
+ * here BEFORE that product retires theirs, or the retirement is a real
+ * reduction in enforcement wearing the clothes of a tidy-up (contract.md §7).
+ */
+export function proveBoundaries(boundaries) {
+  const problems = [];
+  for (const b of boundaries) {
+    for (const f of b.forbid || []) {
+      const where = `boundary from "${b.from}" (${f.pattern})`;
+
+      if (!Array.isArray(f.catches) || f.catches.length === 0) {
+        problems.push(`${where}: no \`catches\` fixture — nothing proves this pattern ever fires`);
+      }
+      if (!Array.isArray(f.allows) || f.allows.length === 0) {
+        problems.push(`${where}: no \`allows\` fixture — nothing proves this pattern is not simply matching everything`);
+      }
+      if (!f.pattern) continue;
+
+      for (const line of f.catches || []) {
+        if (!isImportBreach(line, f.pattern)) {
+          problems.push(`${where}: does NOT catch its own fixture — ${JSON.stringify(line)}`);
+        }
+      }
+      for (const line of f.allows || []) {
+        if (isImportBreach(line, f.pattern)) {
+          problems.push(`${where}: fires on a line it must allow — ${JSON.stringify(line)}`);
+        }
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * Validate and prove, or refuse to run.
+ *
+ * Throwing rather than warning, for the reason `loadRules` throws: a warning is
+ * read once and then lives in a log nobody opens, and the thing being guarded
+ * against is a boundary that is present, believed, and not working.
+ */
+export function loadBoundaries(boundaries) {
+  const problems = [...validateBoundaries(boundaries), ...proveBoundaries(boundaries)];
+  if (problems.length) {
+    throw new Error(
+      "Invalid boundary rules:\n  " + problems.join("\n  ") +
+      "\nA boundary that matches nothing prints the same 'no breaches' as one that works.",
+    );
+  }
+  return boundaries;
+}
+
+/** The dependency half. Same discipline, matched against package NAMES rather than import lines. */
+export function proveDependencyBoundaries(rules) {
+  const problems = [];
+  for (const r of rules) {
+    const where = `dependency boundary (${r.packagePattern})`;
+    if (!r.packagePattern) { problems.push(`${where}: no packagePattern`); continue; }
+    if (!r.why || String(r.why).trim().split(/\s+/).length < 8) {
+      problems.push(`${where}: the reason is missing or is a label rather than an argument`);
+    }
+    if (!Array.isArray(r.catches) || r.catches.length === 0) {
+      problems.push(`${where}: no \`catches\` fixture — nothing proves this pattern ever fires`);
+    }
+    if (!Array.isArray(r.allows) || r.allows.length === 0) {
+      problems.push(`${where}: no \`allows\` fixture`);
+    }
+    for (const name of r.catches || []) {
+      if (!r.packagePattern.test(name)) problems.push(`${where}: does NOT catch ${JSON.stringify(name)}`);
+    }
+    for (const name of r.allows || []) {
+      if (r.packagePattern.test(name)) problems.push(`${where}: fires on ${JSON.stringify(name)}, which it must allow`);
+    }
+  }
+  return problems;
+}
+
+export function loadDependencyBoundaries(rules) {
+  const problems = proveDependencyBoundaries(rules);
+  if (problems.length) {
+    throw new Error("Invalid dependency boundary rules:\n  " + problems.join("\n  "));
+  }
+  return rules;
+}
+
+function walk(dir, root, out) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const name of entries) {
+    if (SKIP.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);
+    else if (SOURCE.has(extname(name))) out.push(relative(root, full).split(sep).join("/"));
+  }
+}
+
+const inScope = (file, prefix) => prefix === "" || file === prefix || file.startsWith(prefix + "/");
+
+/** A test file discusses imports; it does not make them. */
+const isTest = (p) => /\.(test|spec)\.[jt]sx?$/.test(p) || /(^|\/)__tests__\//.test(p);
+
+/**
+ * Check import boundaries across a tree.
+ *
+ * Three things are excluded deliberately, and all three were found by a rule
+ * firing on the thing that described it:
+ *
+ * - **comments**, so the sentence explaining a boundary is not a breach of it;
+ * - **`package.json` name fields**, which System A's own test pins;
+ * - **test files**, which quote forbidden imports as string fixtures. Running
+ *   this against System A reported its `boundaries.test.ts` as the
+ *   repository's only breach — the test proving their rule works, flagged by
+ *   ours. A rule that fires on its own evidence is a rule people switch off.
+ */
+export function checkBoundaries(root, boundaries, { exemptions = new Map() } = {}) {
+  loadBoundaries(boundaries);
+
+  const files = [];
+  walk(root, root, files);
+  const breaches = [];
+
+  for (const file of files.sort()) {
+    if (isTest(file)) continue;
+    let text; try { text = readFileSync(join(root, file), "utf8"); } catch { continue; }
+
+    for (const b of boundaries) {
+      if (!inScope(file, b.from)) continue;
+      if ((b.exceptIn || []).some((p) => inScope(file, p))) continue;
+
+      text.split("\n").forEach((line, i) => {
+        for (const f of b.forbid) {
+          if (isImportBreach(line, f.pattern)) {
+            breaches.push({ file, line: i + 1, from: b.from, why: f.why, source: line.trim() });
+          }
+        }
+      });
+    }
+  }
+
+  return {
+    breaches,
+    exemptions: [...exemptions.entries()].map(([path, why]) => ({ path, why })),
+    filesChecked: files.length,
+  };
+}
+
+/** Check who DECLARES a forbidden package, whether or not they import it. */
+export function checkDependencyBoundaries(root, rules, { packages = [] } = {}) {
+  loadDependencyBoundaries(rules);
+  const breaches = [];
+  for (const pkg of packages) {
+    const manifest = join(root, pkg.path === "." ? "" : pkg.path, "package.json");
+    if (!existsSync(manifest)) continue;
+    let json; try { json = JSON.parse(readFileSync(manifest, "utf8")); } catch { continue; }
+    const declared = { ...(json.dependencies || {}), ...(json.devDependencies || {}) };
+
+    for (const rule of rules) {
+      if (rule.onlyIn.some((p) => inScope(pkg.path, p))) continue;
+      for (const [name, version] of Object.entries(declared)) {
+        if (rule.packagePattern.test(name)) {
+          breaches.push({ package: pkg.path, dependency: name, version, why: rule.why });
+        }
+      }
+    }
+  }
+  return breaches;
+}
+
+/**
+ * The same package pinned at different versions in one workspace.
+ *
+ * Not a boundary, but it lives here because it is the same failure one layer
+ * down: System C has twelve Radix packages at two versions between its
+ * shared UI package and the dashboard that consumes it, and nobody decided
+ * that. It is what a copy-in component library does when nothing watches the
+ * manifests, and it is the measured form of the problem G-54 has to solve.
+ */
+export function findVersionDrift(root, { packages = [], match = /./ } = {}) {
+  const versions = new Map();
+  for (const pkg of packages) {
+    const manifest = join(root, pkg.path === "." ? "" : pkg.path, "package.json");
+    if (!existsSync(manifest)) continue;
+    let json; try { json = JSON.parse(readFileSync(manifest, "utf8")); } catch { continue; }
+    for (const [name, v] of Object.entries({ ...(json.dependencies || {}), ...(json.devDependencies || {}) })) {
+      if (!match.test(name)) continue;
+      if (!versions.has(name)) versions.set(name, new Map());
+      versions.get(name).set(pkg.path, v);
+    }
+  }
+
+  const drifted = [];
+  for (const [name, byPkg] of versions) {
+    const distinct = new Set(byPkg.values());
+    if (distinct.size > 1) drifted.push({ dependency: name, versions: Object.fromEntries(byPkg) });
+  }
+  return drifted.sort((a, b) => a.dependency.localeCompare(b.dependency));
+}