@weatherboard/gyde-design 0.3.0

package/upgrade.mjs

@@ -0,0 +1,344 @@
+/**
+ * G-54 — how a scaffolded project takes a new Gyde version without forking.
+ *
+ * THE PROBLEM, WHICH IS THE PRODUCT.
+ *
+ * Gyde emits a component set. The product edits it, because editing it is the
+ * point (G-47). Six months later Gyde improves the template — a fixed
+ * accessibility bug, a primitive-library API change, a new token category. How
+ * does the improvement reach a file somebody has been working in?
+ *
+ * The prior-art survey found this is shadcn's openly unsolved problem: three
+ * multi-year issues, and its own documentation calls re-syncing "an ongoing
+ * responsibility rather than a solved problem." System C shows the cost
+ * arriving with no tool involved at all — twelve primitive packages at two
+ * different versions between its shared UI package and the app consuming it,
+ * which nobody decided.
+ *
+ * So this is not a nice-to-have. **If Gyde's answer here is no better than
+ * shadcn's, Gyde is shadcn with a Linear team.**
+ *
+ * THE MECHANISM: PROVENANCE, THEN A THREE-WAY CLASSIFICATION.
+ *
+ * `init` records what it wrote — the Gyde version and a hash of each file's
+ * exact emitted bytes. That record is the missing third point. With it, every
+ * file is one of four cases, and they need completely different handling:
+ *
+ *   neither changed          nothing to do
+ *   Gyde changed only        safe to apply — the product never touched it
+ *   product changed only     nothing to do; their edit is the current truth
+ *   both changed             a CONFLICT, reported for a human, never merged
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO.
+ *
+ * It never auto-merges. A generator that resolves a conflict in somebody's
+ * component is a generator that silently reverts a decision it cannot see the
+ * reason for — and CHARTER §3 says the components are theirs. A conflict is
+ * information, and the honest output is both versions and the diff between
+ * them.
+ *
+ * It also never rewrites a file it has no provenance for. An untracked file is
+ * one Gyde did not write, or wrote before provenance existed; overwriting it
+ * would be exactly the clobbering `init` refuses to do.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+export const MANIFEST = "gyde-emitted.json";
+
+/**
+ * The hash is of the exact bytes emitted.
+ *
+ * Not a normalised or whitespace-insensitive hash: a reformat IS an edit as far
+ * as this is concerned, because a formatter run over a file is a change the
+ * product made and Gyde must not silently discard it.
+ */
+export const hash = (contents) => createHash("sha256").update(contents, "utf8").digest("hex").slice(0, 16);
+
+export function buildManifest(files, { version }) {
+  return {
+    "//": "What Gyde emitted, and when. This is the third point a three-way " +
+          "comparison needs: without it, an upgrade cannot tell YOUR edit from " +
+          "OUR change and has to choose between clobbering and doing nothing. " +
+          "Committed on purpose. Do not edit by hand.",
+    version,
+    files: Object.fromEntries(Object.keys(files).sort().map((p) => [p, hash(files[p])])),
+  };
+}
+
+export function readManifest(root) {
+  const path = join(root, MANIFEST);
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+export function writeManifest(root, manifest) {
+  const path = join(root, MANIFEST);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n");
+}
+
+export const STATUS = {
+  UNCHANGED: "unchanged",       // neither side moved
+  GYDE_ONLY: "gyde-only",       // safe to apply
+  PRODUCT_ONLY: "product-only", // their edit stands
+  CONFLICT: "conflict",         // both moved — a human decides
+  MISSING: "missing",           // emitted once, deleted since
+  UNTRACKED: "untracked",       // no provenance; Gyde will not touch it
+  NEW: "new",                   // this version emits a file the last one did not
+  FOREIGN: "foreign",           // this version emits it, into a directory Gyde has never written to
+};
+
+/**
+ * Directories Gyde has actually written into, from the manifest (G-66).
+ *
+ * The discriminator between two cases that are otherwise identical — a file
+ * this version emits, which is not on disk, and which has no provenance:
+ *
+ *   scaffolded repo   Gyde wrote `src/Button.tsx`; now it also emits
+ *                     `src/Badge.tsx`. Adding it is the feature.
+ *   adoption repo     Gyde wrote a workflow and nothing else; now it emits
+ *                     `packages/design-system/src/Card.tsx` into a package
+ *                     the product wrote. Adding it is the thing CHARTER §3
+ *                     and G-47 forbid.
+ *
+ * A foothold is deliberately the file's OWN directory, not any ancestor. Using
+ * an ancestor would let a repository that took Gyde's tokens — provenance in
+ * `packages/design-tokens/` — become grounds to write into
+ * `packages/design-system/`, which is a different package with a different
+ * owner. The root directory is never a foothold for the same reason: it would
+ * make every path in the repository fair game.
+ *
+ * This is conservative, and knowingly so. A version that emits into a NEW
+ * subdirectory of a repository Gyde did scaffold is refused too, and reported
+ * rather than written. `init` is the way in — it refuses to overwrite, so the
+ * conservative answer costs a command rather than a file.
+ */
+function footholds(recorded) {
+  return new Set(Object.keys(recorded).map((p) => dirname(p)));
+}
+
+/**
+ * Classify every file a new emission would touch.
+ *
+ * `nextFiles` is what the current Gyde version would emit. `manifest` is what a
+ * previous one did emit. The on-disk file is the third point.
+ */
+export function classify(root, nextFiles, manifest) {
+  const recorded = manifest?.files ?? {};
+  const ours = footholds(recorded);
+  const out = [];
+
+  for (const [path, nextContents] of Object.entries(nextFiles)) {
+    const full = join(root, path);
+    const onDisk = existsSync(full) ? readFileSync(full, "utf8") : null;
+    const emitted = recorded[path] ?? null;
+    const next = hash(nextContents);
+
+    if (emitted === null) {
+      // Either Gyde has never written this path, or something else created it.
+      // Both mean the same thing when the file EXISTS: no provenance, no
+      // rewrite. When it does not exist, whether creating it is an upgrade or a
+      // land grab depends on whether Gyde has ever written into that directory.
+      out.push({
+        path,
+        status: onDisk !== null ? STATUS.UNTRACKED
+          : ours.has(dirname(path)) ? STATUS.NEW
+          : STATUS.FOREIGN,
+      });
+      continue;
+    }
+    if (onDisk === null) { out.push({ path, status: STATUS.MISSING }); continue; }
+
+    const current = hash(onDisk);
+    const productMoved = current !== emitted;
+    const gydeMoved = next !== emitted;
+
+    if (!productMoved && !gydeMoved) out.push({ path, status: STATUS.UNCHANGED });
+    else if (gydeMoved && !productMoved) out.push({ path, status: STATUS.GYDE_ONLY });
+    else if (productMoved && !gydeMoved) out.push({ path, status: STATUS.PRODUCT_ONLY });
+    else out.push({ path, status: STATUS.CONFLICT });
+  }
+
+  // A path the manifest records and this version no longer emits. Reported, not
+  // deleted: Gyde does not remove a file the product may now depend on.
+  for (const path of Object.keys(recorded)) {
+    if (!(path in nextFiles)) out.push({ path, status: STATUS.MISSING, retired: true });
+  }
+
+  return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Apply an upgrade.
+ *
+ * Writes only `gyde-only` files: a path the manifest records, whose on-disk
+ * bytes still match what Gyde emitted. Everything else is reported and left
+ * alone, including — especially — conflicts. `dryRun` returns the same
+ * decisions without touching anything, and `upgrade` and its dry run share this
+ * function for the same reason `plan` and `init` share theirs.
+ *
+ * WHY `FOREIGN` EXISTS, AND WHY `NEW` SURVIVED (G-66).
+ *
+ * Found against System B: at the same template version in and out,
+ * `upgrade` proposed sixteen writes into `packages/design-system/` and
+ * `apps/design/` — a design system that repository wrote itself, in a
+ * repository whose manifest records exactly two files. It reported them as
+ * "Gyde changed and you had not touched", which is false on both halves.
+ *
+ * The cause is upstream and is NOT a mistake. `upgrade` deliberately builds the
+ * emission with `hasTokens: false, hasSystem: false`, because an upgrade has to
+ * compare against the templates rather than against a skip decision — otherwise
+ * a scaffolded repository, which by definition has a design-system package,
+ * would never receive a component template fix at all. That reasoning is right
+ * and stays.
+ *
+ * What was wrong is that two different situations produced the same status. A
+ * template absent from disk with no provenance is either:
+ *
+ *   an addition   Gyde wrote this directory; the new version adds a file to it
+ *   a land grab   Gyde has never written here, and the product owns it
+ *
+ * The first is the feature — a scaffolded repository should pick up a new
+ * component template without being asked. The second is the one thing CHARTER
+ * §3 and G-47 forbid. `footholds()` tells them apart using the only evidence
+ * that means anything: whether Gyde has ever written a file into that exact
+ * directory.
+ *
+ * So `NEW` is still written, and `FOREIGN` is reported and never written.
+ * `init` is the way to take a foreign one deliberately — it refuses to
+ * overwrite anything, so running it again is safe.
+ */
+export function applyUpgrade(root, nextFiles, manifest, { version, dryRun = false } = {}) {
+  const decisions = classify(root, nextFiles, manifest);
+  const applied = [];
+  const skipped = [];
+
+  for (const d of decisions) {
+    if (d.status === STATUS.GYDE_ONLY || d.status === STATUS.NEW) {
+      if (!dryRun) {
+        const full = join(root, d.path);
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, nextFiles[d.path]);
+      }
+      applied.push(d);
+    } else {
+      skipped.push(d);
+    }
+  }
+
+  /**
+   * The manifest records what Gyde LAST EMITTED, not what is on disk.
+   *
+   * So a file that was applied advances to the new hash, and one that was not
+   * keeps its old baseline — otherwise the next upgrade would read an unapplied
+   * change as a product edit, and a conflict would quietly become
+   * `product-only` and never be offered again.
+   *
+   * A FOREIGN path gets no record (G-66). Recording a hash for a file Gyde
+   * never wrote would be provenance asserting something false, and the next run
+   * would read it as "Gyde emitted this and the product deleted it" — a
+   * fabricated history that then justifies writing the file for real.
+   */
+  const recorded = manifest?.files ?? {};
+  const nextManifest = {
+    ...buildManifest(nextFiles, { version }),
+    files: Object.fromEntries(
+      decisions
+        .filter((d) => d.path in nextFiles)
+        .filter((d) => applied.includes(d) || d.path in recorded)
+        .map((d) => [d.path, applied.includes(d) ? hash(nextFiles[d.path]) : recorded[d.path]]),
+    ),
+  };
+
+  return { decisions, applied, skipped, nextManifest, conflicts: skipped.filter((d) => d.status === STATUS.CONFLICT) };
+}
+
+/**
+ * A line-level diff, for a human reading a conflict.
+ *
+ * Deliberately naive — this is for reading, not for merging. Anything cleverer
+ * would invite the auto-merge this module exists to refuse.
+ */
+export function diff(before, after, { context = 2 } = {}) {
+  const a = before.split("\n");
+  const b = after.split("\n");
+  const out = [];
+  const max = Math.max(a.length, b.length);
+  let lastPrinted = -1;
+
+  for (let i = 0; i < max; i++) {
+    if (a[i] === b[i]) continue;
+    const from = Math.max(lastPrinted + 1, i - context);
+    if (from > lastPrinted + 1) out.push(`  … ${from - lastPrinted - 1} unchanged line(s)`);
+    for (let j = from; j <= Math.min(max - 1, i + context); j++) {
+      if (j <= lastPrinted) continue;
+      if (a[j] === b[j]) out.push(`   ${a[j] ?? ""}`);
+      else {
+        if (a[j] !== undefined) out.push(`  -${a[j]}`);
+        if (b[j] !== undefined) out.push(`  +${b[j]}`);
+      }
+      lastPrinted = j;
+    }
+  }
+  return out.join("\n");
+}
+
+export function formatUpgrade(result, { manifest, version }) {
+  const L = [];
+  const by = (s) => result.decisions.filter((d) => d.status === s);
+
+  L.push(`from         ${manifest?.version ?? "(no manifest — nothing to upgrade from)"}`);
+  L.push(`to           ${version}`);
+  L.push("");
+  L.push(`applied      ${result.applied.length} file(s) Gyde changed and you had not touched`);
+  for (const d of result.applied.slice(0, 12)) L.push(`               ${d.path}`);
+
+  const conflicts = by(STATUS.CONFLICT);
+  if (conflicts.length) {
+    L.push("");
+    L.push(`CONFLICTS    ${conflicts.length} file(s) changed on BOTH sides. Nothing was written to these.`);
+    L.push("             Gyde does not merge: resolving a conflict in your component means");
+    L.push("             reverting a decision it cannot see the reason for.");
+    for (const d of conflicts) L.push(`               ${d.path}`);
+  }
+
+  const held = by(STATUS.PRODUCT_ONLY);
+  if (held.length) L.push(`\nyours        ${held.length} file(s) you changed and Gyde did not — left alone`);
+
+  const untracked = by(STATUS.UNTRACKED);
+  if (untracked.length) {
+    L.push(`\nuntracked    ${untracked.length} file(s) with no provenance — Gyde will not touch them`);
+    for (const d of untracked.slice(0, 6)) L.push(`               ${d.path}`);
+  }
+
+  /**
+   * Reported loudly, and never written (G-66).
+   *
+   * Silence here would be the worse bug in the other direction: a version that
+   * genuinely adds a template would say nothing, and the repository would sit
+   * one template behind with no signal. So the count is always shown, and the
+   * next step is named rather than implied.
+   */
+  const foreign = by(STATUS.FOREIGN);
+  if (foreign.length) {
+    L.push(`\nnot Gyde's   ${foreign.length} file(s) this version emits, in directories Gyde has`);
+    L.push("             never written to.");
+    L.push("             NOT written. Creating a file inside a package the product owns is");
+    L.push("             the one thing a scaffolder must not do (CHARTER §3, G-47).");
+    for (const d of foreign.slice(0, 8)) L.push(`               ${d.path}`);
+    if (foreign.length > 8) L.push(`               … and ${foreign.length - 8} more`);
+    L.push("             `gyde-design init .` adds them. It never overwrites, so it is safe");
+    L.push("             to run here, and it will skip anything you already have.");
+  }
+
+  const retired = result.decisions.filter((d) => d.retired);
+  if (retired.length) {
+    L.push(`\nretired      ${retired.length} file(s) this version no longer emits — reported, never deleted`);
+    for (const d of retired) L.push(`               ${d.path}`);
+  }
+
+  return L.join("\n");
+}

package/usage.mjs

@@ -0,0 +1,245 @@
+/**
+ * G-59 / G-50 — which component is used where, and what is left over.
+ *
+ * WHY A COUNT OF VIOLATIONS IS NOT ENOUGH.
+ *
+ * The audit answers "is this value tokenised". It cannot answer the two
+ * questions a team actually asks while the library grows:
+ *
+ *   - I need a thing. Does the set already compose it?
+ *   - We shipped a component. Is anybody using it?
+ *
+ * One project states the principle for the first — *"A page that needs something the
+ * set cannot compose has found a gap in the set. That is a finding to file, not
+ * a licence to write bespoke CSS."* — and **nothing in either source repository
+ * implements the check behind that sentence.** This module is the evidence that
+ * check needs.
+ *
+ * THE SECOND QUESTION IS THE ONE THAT DECAYS QUIETLY. A component nobody renders
+ * is not free: it is code that drifts from the set it claims to belong to, and
+ * it is the reason System A deleted a finished `Disclosure` rather than
+ * ship it. An unused component and a component used once look identical
+ * in a diff and completely different in a design system.
+ *
+ * TWO SCOPE TRAPS, BOTH OBSERVED.
+ *
+ * 1. The design system's own source composes its components without adopting
+ *    them. Counting it inflates every number.
+ * 2. A catalogue renders everything by definition. System A's usage
+ *    index reported `Choice` as unused **while it sat at the top of the
+ *    catalogue demonstrating itself** — the index could not see the file it was
+ *    rendered in. So catalogue *entries* are excluded and catalogue *chrome* is
+ *    not, because a catalogue using a component for its own theme switcher is a
+ *    real use.
+ *
+ * Both are configuration, and both are reported, because a scope that moved
+ * silently is how a metric stops describing anything.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, extname, relative, 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"]);
+const isTest = (p) => /\.(test|spec)\.[jt]sx?$/.test(p) || /(^|\/)__tests__\//.test(p);
+
+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)) && !isTest(full)) out.push(relative(root, full).split(sep).join("/"));
+  }
+}
+
+/** Class tokens that belong to a declared vocabulary rather than being bespoke. */
+const declared = (cls, prefixes) => prefixes.some((p) => cls.startsWith(p));
+
+/**
+ * Roots of the utility idiom.
+ *
+ * A utility class is a styling idiom the audit already judges; a bespoke class
+ * name is a vocabulary the product invented. Counting the first as the second
+ * buries the signal this index exists to surface — one page of Tailwind would
+ * out-shout every real finding.
+ *
+ * The test is the ROOT word, with or without a hyphen: the first version
+ * required one and let `flex`, `grid` and `hidden` through as bespoke
+ * vocabulary.
+ *
+ * THE TRADEOFF, STATED. A genuinely bespoke class whose first word happens to
+ * be a utility root — `text-heavy`, `flex-container` — is skipped. That is the
+ * safe direction to be wrong in: a missed gap is a gap somebody files later, an
+ * index drowned in utilities is one nobody reads at all.
+ */
+const UTILITY_ROOTS = new Set([
+  "p", "m", "px", "py", "mx", "my", "pt", "pb", "pl", "pr", "mt", "mb", "ml", "mr",
+  "w", "h", "min", "max", "gap", "space", "inset", "top", "left", "right", "bottom",
+  "text", "bg", "border", "rounded", "shadow", "ring", "outline", "opacity", "divide",
+  "flex", "grid", "col", "row", "order", "items", "justify", "self", "place", "content",
+  "block", "inline", "hidden", "absolute", "relative", "fixed", "sticky", "static",
+  "font", "leading", "tracking", "whitespace", "break", "truncate", "list", "align",
+  "overflow", "object", "cursor", "select", "pointer", "z", "transition", "duration",
+  "ease", "translate", "scale", "rotate", "transform", "filter", "blur", "backdrop",
+  "from", "via", "to", "sr", "not", "aspect", "container", "antialiased", "underline",
+  // Added after a real run: System C's top five "invented vocabularies"
+  // were animate-spin, shrink-0, capitalize, line-clamp-2 and animate-pulse —
+  // every one a stock utility. A gap list made entirely of Tailwind is a gap
+  // list nobody reads, and the roots below are the ones that produced it.
+  "animate", "shrink", "grow", "basis", "capitalize", "uppercase", "lowercase",
+  "line", "decoration", "indent", "resize", "appearance", "caret", "accent",
+  "snap", "touch", "will", "isolate", "mix", "bt", "visible", "invisible",
+  "collapse", "table", "float", "clear", "box", "columns", "gradient", "rounded",
+]);
+
+const isUtility = (cls) => UTILITY_ROOTS.has(cls.split("-")[0]);
+
+/**
+ * Build the index.
+ *
+ * `excludePaths` are places whose usage does not count — the design system's own
+ * source, and a catalogue's entry file. Both are echoed back in the result so
+ * the exclusion is visible next to the number it changed.
+ */
+export function buildUsage(root, {
+  components = [],
+  excludePaths = [],
+  classPrefixes = ["ds-"],
+  scanPaths = null,
+} = {}) {
+  const files = [];
+  for (const base of scanPaths ?? [""]) walk(join(root, base), root, files);
+
+  const excluded = (rel) => excludePaths.some((p) => rel === p || rel.startsWith(p.replace(/\/$/, "") + "/"));
+
+  const used = Object.fromEntries(components.map((c) => [c, []]));
+  const leftovers = {};
+  let filesCounted = 0;
+  let filesExcluded = 0;
+
+  for (const rel of files.sort()) {
+    if (excluded(rel)) { filesExcluded++; continue; }
+    let text; try { text = readFileSync(join(root, rel), "utf8"); } catch { continue; }
+    filesCounted++;
+
+    for (const name of components) {
+      if (new RegExp(`<${name}[\\s/>]`).test(text)) used[name].push(rel);
+    }
+
+    // Bespoke class names: the vocabulary a product invented instead of using
+    // the set. This is the leading indicator — a cluster of them in one area is
+    // a gap in the set showing up before anybody files it.
+    /**
+     * Only STRING LITERALS inside a className, never the whole brace body.
+     *
+     * The first version captured everything after `{`, so
+     * `className={cond ? "a" : "b"}` yielded `cond` and `?` as bespoke class
+     * names. Run against a real repository it reported `?`, `===` and `selected`
+     * as the product's top three invented vocabularies — an output that tells
+     * you nothing and costs the whole feature its credibility.
+     */
+    const literals = [];
+    for (const m of text.matchAll(/(?:className|class)\s*=\s*"([^"]*)"/g)) literals.push(m[1]);
+    for (const m of text.matchAll(/(?:className|class)\s*=\s*'([^']*)'/g)) literals.push(m[1]);
+    for (const m of text.matchAll(/(?:className|class)\s*=\s*\{([\s\S]{0,400}?)\}/g)) {
+      // Interpolations are stripped BEFORE quoted runs are extracted. Doing it
+      // the other way round, a template literal like
+      // `` `row ${active ? "on" : "off"}` `` yields the text between the
+      // backtick and the first quote — so `${active`, `?` and `:` arrive as
+      // class names.
+      const body = m[1].replace(/\$\{[^}]*\}?/g, " ");
+      for (const lit of body.matchAll(/["'`]([^"'`]*)["'`]/g)) literals.push(lit[1]);
+      // A bare template with no quotes inside: `` `row gap` ``.
+      for (const lit of body.matchAll(/`([^`]*)`/g)) literals.push(lit[1]);
+    }
+
+    for (const literal of literals) {
+      for (const cls of literal.replace(/\$\{[^}]*\}/g, " ").split(/\s+/)) {
+        if (!cls || declared(cls, classPrefixes)) continue;
+        // Strip variant prefixes first: `hover:flex` is the same idiom as `flex`.
+        const bare = cls.replace(/^(?:[\w-]+:)+/, "");
+        if (!bare || isUtility(bare)) continue;
+        (leftovers[cls] ??= []).push(rel);
+      }
+    }
+  }
+
+  const unused = components.filter((c) => used[c].length === 0);
+
+  return {
+    scope: { filesCounted, filesExcluded, excludePaths, scanPaths: scanPaths ?? ["(whole tree)"] },
+    used,
+    unused,
+    // Sorted by how often the product reached for something the set did not have.
+    leftovers: Object.fromEntries(
+      Object.entries(leftovers)
+        .map(([cls, files]) => [cls, [...new Set(files)]])
+        .sort((a, b) => b[1].length - a[1].length),
+    ),
+  };
+}
+
+/**
+ * Turn the index into the two questions a team asks.
+ *
+ * This is deliberately advisory. A cluster of bespoke classes is EVIDENCE of a
+ * gap, not proof of one, and reporting it as a violation would be the mistake
+ * G-60 §1 records: the closed system that had no runtime theming did not have a
+ * rule problem, it had a capability problem, and a gate that could not tell the
+ * difference just made the workaround harder to find.
+ */
+export function guidance(usage, { gapThreshold = 3 } = {}) {
+  const findings = [];
+
+  for (const name of usage.unused) {
+    findings.push({
+      kind: "unused-component",
+      subject: name,
+      severity: "advisory",
+      why: `${name} is exported and rendered nowhere. An unused component drifts from the set it claims to belong to — either use it, or delete it and file the gap it was speculating about.`,
+    });
+  }
+
+  for (const [cls, files] of Object.entries(usage.leftovers)) {
+    if (files.length < gapThreshold) continue;
+    findings.push({
+      kind: "possible-gap",
+      subject: cls,
+      severity: "advisory",
+      occurrences: files.length,
+      examples: files.slice(0, 4),
+      why: `"${cls}" is spelled in ${files.length} files. A vocabulary the product keeps reinventing is usually a component the set is missing — file it as a gap before writing it a sixth time.`,
+    });
+  }
+
+  const single = Object.entries(usage.used).filter(([, f]) => f.length === 1);
+  for (const [name, files] of single) {
+    findings.push({
+      kind: "single-use-component",
+      subject: name,
+      severity: "advisory",
+      examples: files,
+      why: `${name} is rendered in exactly one place. That is fine for a genuinely singular surface and a warning sign otherwise — a component with one caller is often a page fragment that was promoted too early.`,
+    });
+  }
+
+  return findings.sort((a, b) => (b.occurrences ?? 0) - (a.occurrences ?? 0));
+}
+
+export function formatUsage(usage, findings) {
+  const L = [];
+  const total = Object.keys(usage.used).length;
+  L.push(`usage        ${total - usage.unused.length} of ${total} component(s) rendered somewhere`);
+  L.push(`             ${usage.scope.filesCounted} file(s) counted, ${usage.scope.filesExcluded} excluded${usage.scope.excludePaths.length ? ` (${usage.scope.excludePaths.join(", ")})` : ""}`);
+  if (usage.unused.length) L.push(`unused       ${usage.unused.join(", ")}`);
+
+  const gaps = findings.filter((f) => f.kind === "possible-gap");
+  if (gaps.length) {
+    L.push(`possible gaps ${gaps.length} vocabulary(ies) the product keeps reinventing:`);
+    for (const g of gaps.slice(0, 8)) L.push(`               ${String(g.occurrences).padStart(4)}×  ${g.subject}`);
+  }
+  return L.join("\n");
+}