@weatherboard/gyde-design 0.3.0

package/docdrift.mjs

@@ -0,0 +1,439 @@
+/**
+ * G-70 — every component a doc names must resolve.
+ *
+ * CHARTER §2 promises "machine-verified component catalogs… every component
+ * reference checked against real package exports in CI, so docs cannot rot
+ * silently." contract.md ranks `docs-rot` as the highest-priority intake class
+ * because "stale docs actively misroute agents", against a measured failure of
+ * roughly seventeen stale references in one repository.
+ *
+ * The generated artefacts cannot rot: `.gyde/design-system.md` and the
+ * catalogue are built from the same metadata as the barrel, so they cannot name
+ * a component that does not exist. That was the easy half, and it is done.
+ *
+ * This is the other half. Hand-written docs — a README, a CLAUDE.md, an
+ * onboarding page, an architecture note — are where the rot actually
+ * accumulates, because nothing regenerates them when a component is renamed or
+ * deleted. They are also the ones an agent reads first.
+ *
+ * WHY IT CHECKS IMPORTS RATHER THAN EVERY CAPITALISED WORD.
+ *
+ * The tempting rule is "every `<Thing />` in a doc must be a real component".
+ * It is wrong in both directions. A doc legitimately shows `<Image>` from a
+ * framework, `<Suspense>` from React, or a component belonging to a library it
+ * is comparing against — and flagging those makes the check noise, which is how
+ * a docs check gets switched off in the week it is added.
+ *
+ * So the signal is an import FROM THE SYSTEM PACKAGE. That is the one place a
+ * doc states, unambiguously, "this name comes from your design system" — and
+ * the barrel states, unambiguously, whether it does. Both halves are facts, so
+ * the comparison has no judgment in it.
+ *
+ * A name imported from the system and then used as JSX is checked once, at the
+ * import. Usage without an import is not reported: it is ambiguous, and this
+ * check earns its place by being believed.
+ *
+ * AN UNPARSEABLE BARREL IS NOT AN EMPTY ONE.
+ *
+ * `exportedComponents` returns null when it cannot read the barrel, and this
+ * returns `unknown: true` rather than declaring every reference in the
+ * repository broken. wiring.mjs established that discipline and it matters more
+ * here than anywhere: a docs check that reports every doc as rotten on the day
+ * somebody changes their barrel format is a check nobody will ever trust again.
+ *
+ * @gyde-emits-source-for-another-repo — the fixtures beside this file are
+ * markdown and TypeScript written as data for a repository that is not this one.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, relative, extname, sep } from "node:path";
+
+export const RULE = "doc-drift";
+
+const SKIP = new Set([
+  "node_modules", "dist", "build", ".next", ".turbo", ".git", "coverage",
+  "CHANGELOG.md",
+]);
+
+/**
+ * Dot-directories a declared contract-doc glob reaches into.
+ *
+ * The walker skips dotted directories, which is right for `.git` and `.next`
+ * and wrong for the one that matters: a product whose component contracts live
+ * in `.claude/*.md` had those documents skipped entirely, so the prose check
+ * would have reported a confident zero over a directory it never opened. A
+ * declaration is an instruction, and a walker that silently ignores it turns
+ * "you told us where to look" into "we did not look".
+ */
+function dottedRoots(globs) {
+  const out = new Set([".gyde"]);
+  for (const g of globs || []) {
+    const first = g.split("/")[0];
+    if (first.startsWith(".") && !first.includes("*")) out.add(first);
+  }
+  return out;
+}
+
+function walk(dir, root, out, allowedDots = new Set([".gyde"])) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const name of entries) {
+    if (SKIP.has(name)) continue;
+    if (name.startsWith(".") && !allowedDots.has(name)) continue;
+    const full = join(dir, name);
+    let st; try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) walk(full, root, out, allowedDots);
+    else if (extname(name) === ".md") out.push(relative(root, full).split(sep).join("/"));
+  }
+}
+
+/**
+ * Named imports from a given package, wherever they appear in a markdown file.
+ *
+ * Fenced or not: a stale name misroutes a reader identically whether or not it
+ * is inside triple backticks, and the fence is a rendering decision.
+ */
+export function importedFrom(text, packageName) {
+  const found = [];
+  const esc = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`import\\s+(?:type\\s+)?\\{([^}]*)\\}\\s*from\\s*["']${esc}(?:/[^"']*)?["']`, "g");
+
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    for (const m of lines[i].matchAll(re)) {
+      // `import type { X }` is a type reference, not a component that renders.
+      if (/import\s+type\s*\{/.test(m[0])) continue;
+      for (const raw of m[1].split(",")) {
+        const part = raw.trim();
+        if (!part || /^type\s/.test(part)) continue;
+        const name = part.split(/\s+as\s+/)[0].trim();
+        if (/^[A-Z]\w*$/.test(name)) found.push({ name, line: i + 1, source: lines[i].trim() });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Check every markdown file in a tree for components that no longer exist.
+ *
+ * `systemPackage` is the npm name a doc would import from. Without it there is
+ * no unambiguous signal and the check declines to guess — reported as
+ * `unknown`, never as clean.
+ */
+export function checkDocDrift(root, { systemPackage = null, exports: exported = null, contractDocs = [] } = {}) {
+  if (!systemPackage) {
+    return { unknown: true, why: "no system package name configured, so a doc's imports cannot be attributed", drift: [], docsChecked: 0 };
+  }
+  if (exported === null) {
+    return { unknown: true, why: "the design system's barrel could not be read, and an unparseable barrel is not an empty one", drift: [], docsChecked: 0 };
+  }
+
+  const known = new Set(exported);
+  const docs = [];
+  walk(root, root, docs, dottedRoots(contractDocs));
+
+  const drift = [];
+  let referencing = 0;
+
+  let contractDocsChecked = 0;
+  let namesChecked = 0;
+
+  for (const doc of docs.sort()) {
+    let text; try { text = readFileSync(join(root, doc), "utf8"); } catch { continue; }
+
+    const imports = importedFrom(text, systemPackage);
+    if (imports.length > 0) {
+      referencing++;
+      for (const imp of imports) {
+        if (known.has(imp.name)) continue;
+        drift.push({
+          file: doc, rule: RULE, line: imp.line, name: imp.name,
+          source: imp.source, from: systemPackage,
+        });
+      }
+    }
+
+    // G-96. Only inside a doc the product declared a component contract. An
+    // import says where a name came from; prose does not, so the scope has to
+    // be declared rather than guessed.
+    if (!isContractDoc(doc, contractDocs)) continue;
+    contractDocsChecked++;
+
+    for (const claim of namedInProse(text)) {
+      namesChecked++;
+      if (known.has(claim.name.split(".")[0])) continue;
+      drift.push({
+        file: doc, rule: PROSE_RULE, line: claim.line, name: claim.name,
+        source: claim.source, from: "prose in a declared contract doc",
+      });
+    }
+  }
+
+  return {
+    unknown: false, drift,
+    docsChecked: docs.length, docsReferencing: referencing,
+    contractDocsChecked, namesChecked, known: known.size,
+    // Stated so a repository that declared nothing cannot read "no drift" as
+    // "checked and clean". The prose assertion did not run.
+    proseScoped: (contractDocs || []).length > 0,
+  };
+}
+
+export const PROSE_RULE = "doc-drift-prose";
+
+/**
+ * G-96 — a component named in prose, in a doc the product declared a contract.
+ *
+ * The import-based check above was promoted from a product gate and is
+ * narrower than it, which nobody noticed until it was run against the
+ * repository the original came from: 94 docs, **zero** of them carrying an
+ * import statement, 185 component names written in backticks. The check was
+ * wired and dormant. Their `verify-doc-components.mjs` had been holding that
+ * ground the whole time.
+ *
+ * That is the assertion gap contract.md §7 now requires a promotion to state.
+ * This closes it.
+ *
+ * WHY THIS NEEDS A DECLARED SCOPE WHERE THE IMPORT CHECK DID NOT.
+ *
+ * An import says where a name came from. Prose does not: a backticked `Button`
+ * might be this system's Button, React's, a competitor's, or a sentence about
+ * buttons in general. Checking every backticked capitalised word across a
+ * repository would flag `Image`, `Suspense`, `Promise` and every type name in
+ * every architecture note — the noise that gets a docs check switched off.
+ *
+ * So the product declares which documents are component contracts, exactly as
+ * the source gate did by scoping itself to `.claude/*.md`. Inside a declared
+ * contract doc, a backticked PascalCase name is a claim about the component
+ * set and is checked. Outside one, nothing changes.
+ *
+ * The declaration is the point rather than an implementation detail: it is a
+ * product saying "these documents describe my components, hold me to them",
+ * which is a different and stronger statement than a tool guessing.
+ */
+const BACKTICKED = /`([A-Z][A-Za-z0-9]*(?:\.[A-Z][A-Za-z0-9]*)*)`/g;
+
+/**
+ * Names that are never a claim about the design system.
+ *
+ * Deliberately short. A long list is a rule being tuned to one repository,
+ * which is the leak CHARTER §7 forbids — these are language and framework
+ * built-ins that any repository's prose may reasonably name.
+ */
+const NOT_COMPONENTS = new Set([
+  "React", "Promise", "Array", "Object", "String", "Number", "Boolean", "Map", "Set",
+  "Date", "Error", "JSON", "Math", "TypeScript", "JavaScript", "Node", "CSS", "HTML",
+  "Fragment", "Suspense", "StrictMode", "Props", "Partial", "Record", "Pick", "Omit",
+]);
+
+/** Does this path match one of the declared contract-doc globs? */
+export function isContractDoc(rel, globs) {
+  return (globs || []).some((g) => {
+    if (g.endsWith("/**")) return rel.startsWith(g.slice(0, -3) + "/") || rel === g.slice(0, -3);
+    if (g.includes("*")) {
+      const re = new RegExp("^" + g.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*") + "$");
+      return re.test(rel);
+    }
+    return rel === g || rel.startsWith(g + "/");
+  });
+}
+
+/** Component names claimed in prose, in a declared contract doc. */
+export function namedInProse(text) {
+  const found = [];
+  text.split("\n").forEach((line, i) => {
+    for (const m of line.matchAll(BACKTICKED)) {
+      const name = m[1];
+      if (NOT_COMPONENTS.has(name.split(".")[0])) continue;
+      found.push({ name, line: i + 1, source: line.trim() });
+    }
+  });
+  return found;
+}
+
+export const PATH_RULE = "stale-source-path";
+
+/**
+ * G-70, second half — a string that names a source file which is not there.
+ *
+ * The first half checks docs written in markdown. A consumer found the other
+ * shape the hard way: a component registry, written in TypeScript, whose
+ * `sourcePath` fields were rendered verbatim on every component page. Six of
+ * twenty pointed at a directory deleted during a migration. Their own doc gate
+ * checked markdown against real exports and never looked at the registry,
+ * because the registry is a `.ts` file — "the same failure the doc gate exists
+ * to prevent, one file over".
+ *
+ * That is the argument for this being a rule rather than a lint on markdown. A
+ * path rendered to a reader is documentation regardless of the extension it
+ * lives in, and the file type is exactly the wrong thing to scope the check by.
+ *
+ * WHAT MAKES A STRING A CLAIM ABOUT THIS REPOSITORY.
+ *
+ * Not every path-shaped string is one. A URL, a glob, a template with an
+ * interpolation, a relative import (which the build already resolves), a
+ * package specifier — none of them are checkable here, and guessing at them is
+ * how a rule earns a reputation for noise.
+ *
+ * The signal used is narrow and deliberate: **the first segment is a directory
+ * that exists at the repository root.** `packages/ui/src/Button.tsx` is a claim
+ * about this repository, because `packages/` is right there. `src/Button.tsx`
+ * inside some package is not checkable from here and is skipped rather than
+ * guessed at — reported in `skipped`, never silently treated as fine.
+ */
+const PATH_LIKE = /["'`]([A-Za-z0-9_][\w.-]*(?:\/[\w.-]+)+\.(?:tsx?|jsx?|mjs|cjs|css|scss|md|json))["'`]/g;
+
+/**
+ * G-94 — a path declared as fixture data is not a claim that the path exists.
+ *
+ * All fifteen false positives this rule produced against its first real
+ * consumer were in one file, and that file is the one G-71 was promoted FROM.
+ * It declares ESLint fixtures — code fed to `lintText` to prove a boundary rule
+ * rejects what it claims — and every fixture carries a `file:` naming a path
+ * that deliberately does not exist:
+ *
+ *   { name: "Base UI imported in app code",
+ *     file: "apps/pubs/src/__boundary_fixture__.tsx",   // never written to disk
+ *     code: `import { Dialog } from "@base-ui/react/dialog";`,
+ *     mustFail: true }
+ *
+ * Its own header explains why nothing is written: "a committed file that must
+ * fail lint is a file that breaks every other lint run." The path is not stale.
+ * It is an address for code that exists only in memory.
+ *
+ * WHY NOT A FILENAME CONVENTION.
+ *
+ * The obvious fix is to skip files named like fixtures. The consumer's own
+ * argument against it is the right one: the convention is exactly what failed
+ * here. `verify-boundaries.ts` is not named `*.test.*`, so the `isTest` skip
+ * did not catch it, and widening that pattern only moves the guess.
+ *
+ * The structural signal is the shape of the declaration. A path that sits in an
+ * object literal beside a key holding SOURCE CODE is an address for that code,
+ * not a reference to a file. That is true of any fixture table in any
+ * repository, whatever the file is called, and it is false of a registry entry
+ * — `{ name: "Button", sourcePath: "…" }` has no code sibling, which is why the
+ * registry case G-70 exists for still fires.
+ */
+const CODE_SIBLING = /(^|[\s{,])(code|source|contents|snippet|template|body)\s*:/;
+
+/** The object literal enclosing a line, bounded so a malformed file cannot walk the whole tree. */
+function enclosingObject(lines, at, span = 40) {
+  let depth = 0, start = at;
+  for (let i = at; i >= Math.max(0, at - span); i--) {
+    for (const ch of [...lines[i]].reverse()) {
+      if (ch === "}") depth++;
+      else if (ch === "{") { if (depth === 0) { start = i; i = -1; break; } depth--; }
+    }
+    if (i === -1) break;
+    start = i;
+  }
+  const end = Math.min(lines.length - 1, at + span);
+  return lines.slice(start, end + 1).join("\n");
+}
+
+export function isFixtureDeclaration(lines, at) {
+  return CODE_SIBLING.test(enclosingObject(lines, at));
+}
+
+export function stalePaths(root, rel, text, { rootDirs }) {
+  const found = [];
+  const skipped = [];
+
+  // A path named in prose explaining a rule is not a claim that the path
+  // exists. `upgrade.mjs` illustrates the adoption case with
+  // `packages/design-system/src/Card.tsx` — a file that deliberately does not
+  // exist, in a comment describing what Gyde must not write. Reporting it is
+  // the same mistake boundaries.mjs guards against: a rule firing on the
+  // sentence that explains it. Newlines are preserved so line numbers survive.
+  const src = text
+    .replace(/\/\*[\s\S]*?\*\//g, (s) => s.replace(/[^\n]/g, " "))
+    .replace(/^\s*\/\/[^\n]*/gm, "");
+
+  const lines = src.split("\n");
+  lines.forEach((line, i) => {
+    for (const m of line.matchAll(PATH_LIKE)) {
+      const p = m[1];
+      if (p.includes("*") || p.includes("${") || p.includes("://")) continue;
+
+      const first = p.split("/")[0];
+      if (!rootDirs.has(first)) { skipped.push({ file: rel, line: i + 1, path: p }); continue; }
+
+      if (existsSync(join(root, p))) continue;
+      if (isFixtureDeclaration(lines, i)) { skipped.push({ file: rel, line: i + 1, path: p, why: "fixture data" }); continue; }
+
+      found.push({
+        file: rel, rule: PATH_RULE, line: i + 1, path: p,
+        // `raw` as well as `path`, because every other finding in this engine
+        // carries `raw` and a caller printing findings uniformly rendered these
+        // as `verify-boundaries.ts:134  undefined` — unactionable, and
+        // unmatchable against source even where the finding was genuine.
+        raw: p,
+        source: line.trim(),
+      });
+    }
+  });
+
+  return { found, skipped };
+}
+
+/** Directory names directly under the repository root — the anchor for "is this ours?". */
+export function rootDirectories(root) {
+  const dirs = new Set();
+  let entries;
+  try { entries = readdirSync(root); } catch { return dirs; }
+  for (const name of entries) {
+    if (SKIP.has(name) || name.startsWith(".")) continue;
+    try { if (statSync(join(root, name)).isDirectory()) dirs.add(name); } catch { /* unreadable */ }
+  }
+  return dirs;
+}
+
+export function formatStalePaths(findings, { skipped = 0 } = {}) {
+  if (findings.length === 0) {
+    return `no string names a source file that is missing` +
+      (skipped ? ` (${skipped} path-shaped string(s) were not repository-relative and could not be checked)` : "");
+  }
+  const L = [`${findings.length} string(s) naming a file that does not exist:`];
+  for (const f of findings) {
+    L.push(`  ${f.file}:${f.line}  ${f.path}`);
+    L.push(`      ${f.source}`);
+  }
+  L.push("");
+  L.push("  A path rendered to a reader is documentation whatever file it lives in. This");
+  L.push("  is the registry case: a component page printing a source location that was");
+  L.push("  deleted in a migration, with no gate reading it because it is not markdown.");
+  if (skipped) L.push(`  ${skipped} further path-shaped string(s) were not repository-relative and were not judged.`);
+  return L.join("\n");
+}
+
+export function formatDocDrift(result) {
+  if (result.unknown) return `doc drift: could not tell — ${result.why}`;
+  if (result.drift.length === 0) {
+    const L = [`no doc names a component that does not exist ` +
+      `(${result.docsReferencing} of ${result.docsChecked} doc(s) import the system, ${result.known} export(s))`];
+    // Which assertions actually ran. A repository that declared no contract
+    // docs has not been checked for prose, and must not read this as clean —
+    // the state that left 185 named components unguarded across 94 documents.
+    L.push(result.proseScoped
+      ? `             prose: ${result.namesChecked} name(s) across ${result.contractDocsChecked} declared contract doc(s)`
+      : `             prose: NOT CHECKED — no \`contractDocs\` declared, so names written in backticks are unguarded`);
+    return L.join("\n");
+  }
+  const L = [`${result.drift.length} stale component reference(s) in docs:`];
+  for (const d of result.drift) {
+    // The two assertions are worded differently because they are different
+    // claims. An import says where a name came from; prose in a doc the product
+    // declared a contract says the product stands behind the name.
+    L.push(d.rule === PROSE_RULE
+      ? `  ${d.file}:${d.line}  ${d.name} is named in a declared contract doc and is not exported`
+      : `  ${d.file}:${d.line}  ${d.name} is imported from ${d.from} and is not exported`);
+    L.push(`      ${d.source}`);
+  }
+  L.push("");
+  L.push("  A doc naming a component that does not exist routes a reader — or an agent —");
+  L.push("  to build against something that was renamed or deleted. It is worse than a");
+  L.push("  missing doc, because it still looks authoritative.");
+  return L.join("\n");
+}