@weatherboard/gyde-design 0.3.0

package/wiring.mjs

@@ -0,0 +1,297 @@
+/**
+ * G-48 — is the design system actually connected to the app that uses it?
+ *
+ * WHY THIS IS SMALLER THAN IT LOOKED, AND STILL NECESSARY.
+ *
+ * The epic began assuming Gyde would wire a compiler plugin into every build
+ * pipeline. G-58 reversed that: the emitted token layer is plain CSS custom
+ * properties, so there is no plugin to install and nothing per-pipeline to
+ * configure. Most of the wiring problem dissolved with the decision.
+ *
+ * What did not dissolve is the connection itself. Custom properties come from a
+ * stylesheet, and a stylesheet has to be imported. An app that renders
+ * design-system components without importing the tokens gets **components with
+ * no values** — every `var(--color-text)` resolves to nothing, and the page
+ * renders as unstyled HTML.
+ *
+ * That failure is silent in exactly the way CHARTER §5 is about. It does not
+ * throw. The build succeeds. The audit is delighted: the app imports only
+ * design-system components and spells no literal values, so it scores **100%
+ * adoption while rendering nothing recognisable**. A metric that peaks when the
+ * page is broken is worse than no metric.
+ *
+ * So: this checks the link, and reports "could not tell" as its own outcome
+ * rather than collapsing it into "fine".
+ */
+
+import { readFileSync, existsSync, 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", ".css", ".scss"]);
+
+export const WIRING = {
+  OK: "wired",
+  NO_TOKENS: "renders design-system components but never imports the token stylesheet",
+  NO_SYSTEM: "imports the token stylesheet but renders no design-system component",
+  UNUSED: "neither imports the tokens nor renders a component — not a consumer",
+  UNKNOWN: "could not be determined",
+};
+
+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("/"));
+  }
+}
+
+/**
+ * Read the component names the design system actually exports.
+ *
+ * Derived from the barrel, never hardcoded. System B's audit does the same and its
+ * comment explains why: a curated list drifts from the package silently, and a
+ * list that has drifted reports adoption against components nobody has.
+ *
+ * Returns `null` — not `[]` — when the barrel cannot be read. An empty list
+ * would make every app look like it uses nothing, and the resulting 0% is a
+ * measurement failure wearing the costume of a finding.
+ */
+export function exportedComponents(root, systemPath) {
+  for (const candidate of [join(root, systemPath, "src", "index.ts"), join(root, systemPath, "index.ts"), join(root, systemPath, "src", "index.tsx")]) {
+    if (!existsSync(candidate)) continue;
+    let text; try { text = readFileSync(candidate, "utf8"); } catch { continue; }
+    const names = new Set();
+    for (const m of text.matchAll(/export\s+\{([^}]*)\}/g)) {
+      // `export type { X }` is a type, not a component that can be rendered.
+      if (/export\s+type\s*\{/.test(m[0])) continue;
+      for (const raw of m[1].split(",")) {
+        const name = raw.trim().split(/\s+as\s+/).pop()?.trim();
+        if (name && /^[A-Z]/.test(name)) names.add(name);
+      }
+    }
+    /**
+     * `export * from "./button"` — the shadcn convention, and the shape of
+     * System C's barrel. The names are not in this file at all, so
+     * follow one level into each re-exported module.
+     *
+     * Without this the barrel reads as unparseable and every consumer comes
+     * back UNKNOWN — technically honest, and useless against the most common
+     * component-library layout there is.
+     */
+    for (const m of text.matchAll(/export\s+\*\s+from\s+["'](\.[^"']+)["']/g)) {
+      const base = join(candidate, "..", m[1]);
+      for (const ext of [".tsx", ".ts", "/index.tsx", "/index.ts"]) {
+        if (!existsSync(base + ext)) continue;
+        let inner; try { inner = readFileSync(base + ext, "utf8"); } catch { break; }
+        for (const e of inner.matchAll(/export\s+(?:const|function|class)\s+([A-Z]\w*)/g)) names.add(e[1]);
+        for (const e of inner.matchAll(/export\s+\{([^}]*)\}/g)) {
+          if (/export\s+type\s*\{/.test(e[0])) continue;
+          for (const raw of e[1].split(",")) {
+            const n = raw.trim().split(/\s+as\s+/).pop()?.trim();
+            if (n && /^[A-Z]/.test(n)) names.add(n);
+          }
+        }
+        break;
+      }
+    }
+
+    if (names.size === 0) return null;   // a barrel we could not parse is not an empty barrel
+    return [...names].sort();
+  }
+  return null;
+}
+
+/**
+ * Resolve `@import "<pkg>/<file>"` across the workspace, transitively.
+ *
+ * THE FALSE POSITIVE THIS EXISTS TO PREVENT, which was live before it did.
+ *
+ * The correct arrangement is for an app to import the DESIGN SYSTEM's
+ * stylesheet, and for that stylesheet to import the tokens it depends on:
+ *
+ *     apps/manager/globals.css  @import "@x/design-system/styles.css"
+ *     design-system/styles.css  @import "@x/design-tokens/tokens.css"
+ *
+ * A one-level check reports the app as unwired, which is both wrong and the
+ * worst direction to be wrong in — a gate that fails a correctly-wired
+ * repository gets switched off, and then it is not protecting the repositories
+ * that ARE broken either.
+ *
+ * Depth is bounded and cycles are tracked, because a stylesheet importing
+ * itself should be a finding somewhere else, not a hang here.
+ */
+function reachesTokens(root, startFile, { packageDirs, tokensPackage, seen = new Set(), depth = 0 }) {
+  if (depth > 8 || seen.has(startFile)) return false;
+  seen.add(startFile);
+
+  let text; try { text = readFileSync(join(root, startFile), "utf8"); } catch { return false; }
+  if (tokensPackage && text.includes(`${tokensPackage}/`) && /tokens\.css/.test(text)) return true;
+
+  for (const m of text.matchAll(/@import\s+["']([^"']+)["']/g)) {
+    const spec = m[1];
+    if (tokensPackage && spec.startsWith(`${tokensPackage}/`)) return true;
+
+    // A workspace package specifier: `@x/design-system/styles.css`.
+    for (const [name, dir] of Object.entries(packageDirs)) {
+      if (!spec.startsWith(name + "/")) continue;
+      const sub = spec.slice(name.length + 1);
+      for (const guess of [join(dir, sub), join(dir, "src", sub)]) {
+        if (existsSync(join(root, guess))) {
+          if (reachesTokens(root, guess, { packageDirs, tokensPackage, seen, depth: depth + 1 })) return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Check one package's connection to the design system.
+ *
+ * `packageName` is the workspace name of the design-system package, so a
+ * consumer is recognised by what it imports rather than by where it sits.
+ */
+export function checkPackage(root, pkg, { systemPackage, tokensPackage, components, packageDirs = {} }) {
+  const files = [];
+  walk(join(root, pkg.path === "." ? "" : pkg.path), root, files);
+
+  let importsTokens = false;
+  let importsSystem = false;
+  const rendered = new Set();
+
+  for (const rel of files) {
+    let text; try { text = readFileSync(join(root, rel), "utf8"); } catch { continue; }
+
+    // The stylesheet arrives as a JS import, a CSS @import, or — most often, and
+    // correctly — transitively through the design system's own stylesheet.
+    if (!importsTokens) {
+      if (tokensPackage && text.includes(`${tokensPackage}/tokens.css`)) importsTokens = true;
+      else if (/\.css$/.test(rel) || /import\s+["'][^"']*\.css["']/.test(text)) {
+        if (reachesTokens(root, rel, { packageDirs, tokensPackage })) importsTokens = true;
+        else {
+          // A JS file importing a local stylesheet: follow that too.
+          for (const m of text.matchAll(/import\s+["'](\.[^"']*\.css)["']/g)) {
+            const target = join(rel, "..", m[1]);
+            if (reachesTokens(root, target, { packageDirs, tokensPackage })) { importsTokens = true; break; }
+          }
+          for (const m of text.matchAll(/import\s+["']([^".'][^"']*\.css)["']/g)) {
+            const spec = m[1];
+            for (const [name, dir] of Object.entries(packageDirs)) {
+              if (!spec.startsWith(name + "/")) continue;
+              const sub = spec.slice(name.length + 1);
+              for (const guess of [join(dir, sub), join(dir, "src", sub)]) {
+                if (existsSync(join(root, guess)) && reachesTokens(root, guess, { packageDirs, tokensPackage })) importsTokens = true;
+              }
+            }
+          }
+        }
+      }
+    }
+    if (systemPackage && text.includes(systemPackage)) importsSystem = true;
+
+    if (components) {
+      for (const name of components) {
+        if (new RegExp(`<${name}[\\s/>]`).test(text)) rendered.add(name);
+      }
+    }
+  }
+
+  const usesComponents = rendered.size > 0 || importsSystem;
+  let status;
+  if (components === null) status = WIRING.UNKNOWN;
+  else if (!usesComponents && !importsTokens) status = WIRING.UNUSED;
+  else if (usesComponents && !importsTokens) status = WIRING.NO_TOKENS;
+  else if (!usesComponents && importsTokens) status = WIRING.NO_SYSTEM;
+  else status = WIRING.OK;
+
+  return {
+    package: pkg.path,
+    status,
+    importsTokens,
+    importsSystem,
+    rendered: [...rendered].sort(),
+    filesRead: files.length,
+  };
+}
+
+/**
+ * Check every UI-bearing package.
+ *
+ * `blocking` is the subset that must fail a gate. An app rendering components
+ * without the stylesheet is broken on screen while scoring perfectly, which is
+ * the one result a design-system audit must never produce quietly.
+ */
+export function checkWiring(root, packages, { systemPath = "packages/design-system", systemPackage = null, tokensPackage = null } = {}) {
+  const components = exportedComponents(root, systemPath);
+  const consumers = packages.filter((p) => p.carriesUI && p.path !== systemPath);
+
+  // name -> directory, so a specifier can be followed to a real file.
+  const packageDirs = {};
+  for (const p of packages) if (p.name) packageDirs[p.name] = p.path === "." ? "" : p.path;
+
+  const results = consumers.map((p) => checkPackage(root, p, { systemPackage, tokensPackage, components, packageDirs }));
+
+  return {
+    componentsKnown: components ? components.length : null,
+    // Stated rather than implied: if we could not read the barrel, every result
+    // below is UNKNOWN and none of them is evidence of anything.
+    barrelReadable: components !== null,
+    results,
+    blocking: results.filter((r) => r.status === WIRING.NO_TOKENS || r.status === WIRING.UNKNOWN),
+  };
+}
+
+export function formatWiring(w) {
+  const L = [];
+  if (!w.barrelReadable) {
+    L.push("wiring       UNKNOWN — the design system's barrel could not be read.");
+    L.push("             Every result below is undetermined, not clean.");
+  } else {
+    L.push(`wiring       ${w.componentsKnown} exported component(s) known`);
+  }
+  for (const r of w.results) {
+    // Only a BLOCKING status gets a failure mark. NO_SYSTEM — a package that
+    // loads the tokens and renders none of the components — is a legitimate
+    // arrangement (a surface with its own declared vocabulary), so marking it
+    // as a failure trains people to read past the marks that matter.
+    const blocking = r.status === WIRING.NO_TOKENS || r.status === WIRING.UNKNOWN;
+    const mark = blocking ? "✖" : r.status === WIRING.OK ? "✔" : "·";
+    L.push(`  ${mark} ${r.package.padEnd(34)} ${r.status}`);
+    if (r.status === WIRING.NO_TOKENS) {
+      L.push(`      renders ${r.rendered.slice(0, 5).join(", ")}${r.rendered.length > 5 ? "…" : ""} with no values behind them.`);
+      L.push("      This scores as perfect adoption and renders as unstyled HTML.");
+    }
+  }
+  return L.join("\n");
+}
+
+/**
+ * Of a barrel's exports, the ones that are components (G-66).
+ *
+ * `exportedComponents` returns everything capitalised, which is right for
+ * wiring and usage — a re-exported constant is still a thing the barrel
+ * publishes. It is wrong for a document that tells an agent what it can
+ * render: System B's barrel yields 172 names, of which more than a
+ * hundred are `BADGE_DEFAULTS`-style constants and connector maps.
+ *
+ * The test is lowercase somewhere, not "starts with a capital". `UIButton` is
+ * a component and `BADGE_DEFAULTS` is not, and a first-two-letters rule gets
+ * the first one wrong.
+ *
+ * Deliberately a separate function rather than a narrowing of the existing
+ * one: adoption percentages are computed from that list, and quietly changing
+ * its contents would move a published number for an unrelated reason.
+ */
+export const isComponentName = (name) => /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
+
+export function renderableComponents(root, systemPath) {
+  const all = exportedComponents(root, systemPath);
+  if (all === null) return null;          // unparseable is not empty
+  const named = all.filter(isComponentName);
+  return named.length ? named : null;     // a barrel of only constants tells us nothing
+}

package/workflow.mjs

@@ -0,0 +1,221 @@
+/**
+ * G-53 — the workflow that makes the verdict binding.
+ * G-63 — and which reaches Gyde through an action, not a dependency.
+ *
+ * @gyde-emits-source-for-another-repo
+ *
+ * WHY THIS IS THE DIFFERENCE BETWEEN INSTALLED AND DEPLOYED.
+ *
+ * Without it, `gate` is a command somebody remembers to type. The whole premise
+ * of the product is that the verdict is the decision of record and cannot be
+ * skipped (CHARTER §4) — and "skippable by not typing it" is the most complete
+ * skip there is.
+ *
+ * WHAT THE FILE IS DEFENDING AGAINST, WHICH IS NOT VIOLATIONS.
+ *
+ * It is defending against ITSELF not running. `verify-tier` documents six
+ * incidents where green meant nothing ran: a `paths:` filter that skipped a
+ * job, a `pnpm --filter` that matched nothing and exited 0. CHARTER §5 states
+ * the rule this file is built around — "Gyde did not run" and "Gyde found
+ * nothing" must never render the same.
+ *
+ * WHAT CHANGED IN v0.2, AND WHY THE FILE GOT SHORTER.
+ *
+ * It used to install `@weatherboard/gyde-design` as a devDependency, which
+ * meant an `.npmrc`, an `NPM_TOKEN` secret, and a step whose failure had to be
+ * explained. Installing that into two repositories turned every CI job red —
+ * not Gyde's job, all of them — because a private package 404s without a token
+ * and every job runs `pnpm install --frozen-lockfile`.
+ *
+ * The action removes the install entirely. There is no token in the consumer's
+ * CI, nothing added to their dependency graph, and an npm outage cannot turn
+ * their unrelated tests red. Two of the four load-bearing comments this file
+ * used to carry were about defending a fragile install; they are gone because
+ * the fragility is.
+ *
+ * What remains is the part that was never about packaging: no `paths:` filter,
+ * no `continue-on-error`. The proof that the gate ran moved INTO the action,
+ * where it cannot be edited out of a consumer's repository by accident.
+ */
+
+const YAML = ({ action, defaultBranch, failOn, runsOn }) => `# GENERATED BY GYDE — then yours.
+#
+# Gyde wrote this once and will never overwrite it. Edit it freely.
+#
+# ---------------------------------------------------------------------------
+# BEFORE YOU CHANGE THIS FILE, three things are load-bearing:
+# ---------------------------------------------------------------------------
+#
+# 1. There is deliberately NO \`paths:\` filter.
+#
+#    It is the obvious optimisation — only run when design files change — and
+#    it is the documented cause of a check that reports success without
+#    running. A design-system regression arrives through files no glob
+#    predicts: a component's own source, a token value, a config, a new app
+#    directory nobody added to the list. The whole run is seconds. Adding a
+#    filter here trades that for a gate that is green because it was skipped.
+#
+# 2. There is deliberately NO \`continue-on-error\`.
+#
+#    It makes every failure look like a pass, which is the one outcome this
+#    gate exists to prevent. If you need the gate to stop blocking, set
+#    \`fail-on: none\` below: it still runs, still reports, and still fails if
+#    it could not run — it just does not block on the verdict. It is visible in
+#    the diff and reads as the decision it is, which \`continue-on-error\`
+#    does not.
+#
+# 3. Nothing is installed here, and that is deliberate too.
+#
+#    The action carries the engine, which depends on nothing but Node itself.
+#    Your dependency graph is untouched, no registry token is needed, and an
+#    npm outage cannot fail this job. If you find yourself adding an install
+#    step to make Gyde work, something is wrong with the action rather than
+#    with this file.
+#
+#    The action also proves it ran — it writes .gyde/last-verdict.json stamped
+#    with this run's id and checks the stamp before applying any verdict. That
+#    check lives in the action rather than here so it cannot be edited away.
+# ---------------------------------------------------------------------------
+
+name: Gyde
+
+on:
+  pull_request:
+  push:
+    branches: [${defaultBranch}]
+
+permissions:
+  contents: read
+
+jobs:
+  design-system:
+    runs-on: ${runsOn}
+    steps:
+      - uses: actions/checkout@v4
+
+      # Fails on any finding not already in the committed ledger, and on any
+      # surface it could not measure. An unmeasured surface is an unknown, and
+      # an unknown is never a pass.
+      #
+      # The first run in a repository with existing debt records a baseline and
+      # exits non-zero on purpose — recording debt is how it enters, and a run
+      # that recorded rather than judged is not a pass. Commit the ledger it
+      # writes and the next run judges against it.
+      - uses: ${action}
+        with:
+          fail-on: ${failOn}
+`;
+
+/**
+ * The workflow.
+ *
+ * One file now. The `.npmrc` this used to emit alongside it existed only to
+ * authenticate the install, and there is no install — emitting a registry
+ * config into a repository that does not need one would be a third piece of
+ * Gyde state in somebody else's repo for no benefit (G-65).
+ */
+export function emitWorkflow({
+  /**
+   * The action reference, pinned to a tag.
+   *
+   * A moving ref (`@main`) would mean a consumer's gate changes under them
+   * without a commit, which is the same class of problem as a template
+   * upgrading silently. Dependabot bumps a `uses:` tag as readily as it bumps
+   * a dependency, so pinning costs nothing and buys a reviewable diff.
+   */
+  // The action ADDRESS, not a customer name. The de-attribution pass (P-scrub)
+  // rewrote this to "System A/gyde@v1" and two tests caught it — an emitted
+  // workflow pointing at an organisation that does not exist. The org and one
+  // of the products genuinely share a name; only one of the two uses is data.
+  action = "Another-Iteration/gyde@v1",
+  /**
+   * Blocking by default.
+   *
+   * An adopting repository may want `none` for a fortnight while it decides
+   * whether its recorded baseline is right. That is a decision it makes in its
+   * own workflow file, not a default Gyde hands out — a gate that ships
+   * advisory tends to stay advisory.
+   */
+  failOn = "new",
+  /**
+   * The runner label, MATCHED to what the repository already uses.
+   *
+   * Found in System B, where eight of nine workflows run on Blacksmith
+   * (`blacksmith-4vcpu-ubuntu-2404`) and the ninth — the one Gyde wrote — was
+   * the only `ubuntu-latest` in the repository. That is not just a cost
+   * difference. A repository standardising its runners has a reason, usually
+   * cache locality or a self-hosted pool, and a scaffolder that quietly opts
+   * out of it hands somebody a job that behaves differently from every other
+   * job they have, with no note saying why.
+   *
+   * `ubuntu-latest` remains the fallback because it is the only label that
+   * always exists. A Blacksmith label in a repository with no Blacksmith
+   * installation produces a job that queues forever — which is the worst
+   * possible failure for a gate, since a queued job is neither a pass nor a
+   * fail and nothing reports it. So this is detected from the repository's own
+   * workflows by the caller, never assumed here.
+   */
+  runsOn = "ubuntu-latest",
+  path = ".github/workflows/gyde.yml",
+  /**
+   * The repository's default branch, NOT assumed to be `main`.
+   *
+   * Found installing into a real repository whose default branch is `staging`.
+   * The hardcoded `branches: [main]` meant the post-merge run would never fire
+   * there — and it would never fire *silently*, because a trigger that matches
+   * nothing produces no failed job to notice. Pull requests were still gated,
+   * so the gap was partial, which is worse: enough of it worked that nobody
+   * would go looking.
+   *
+   * Detected by the caller from the repository itself rather than guessed here.
+   */
+  defaultBranch = "main",
+} = {}) {
+  /**
+   * One branch or several.
+   *
+   * System B promotes `staging` → `main`, and its own CI audit requires
+   * every workflow to trigger on both. Its reasoning is worth adopting
+   * rather than working around: the release pull request — the merge that puts
+   * code in front of users — was the least-checked pull request in the
+   * repository, because four of six workflows listed only `[staging]` and a
+   * promotion therefore ran none of them.
+   *
+   * A single default branch stays the common case. A repository with a release
+   * branch says so, and gets a gate on both.
+   */
+  const branches = Array.isArray(defaultBranch) ? defaultBranch : [defaultBranch];
+  if (!branches.length || branches.some((b) => !b || /[[\],]/.test(b))) {
+    throw new Error(
+      `Refusing to emit a push trigger for ${JSON.stringify(defaultBranch)}.\n` +
+      "A trigger that matches no branch produces no failed job to notice — the gate\n" +
+      "would simply never fire, which is indistinguishable from finding nothing.");
+  }
+
+  return {
+    [path]: YAML({ action, defaultBranch: branches.join(", "), failOn, runsOn }),
+
+    /**
+     * The verdict file is per-run output, and committing it is actively harmful.
+     *
+     * `.gyde/` holds two different things: generated content a repository should
+     * commit (the agent doc), and `last-verdict.json`, which is written on every
+     * gate run. A committed verdict goes stale immediately — and a stale verdict
+     * is the precise thing the action's proof step exists to catch, so leaving
+     * it tracked means every pull request carries a diff nobody reads and the
+     * one file that must be fresh is the one under version control.
+     *
+     * Scoped to `.gyde/` rather than added to the repository's root .gitignore,
+     * which is theirs and not a file a scaffolder should be editing.
+     */
+    ".gyde/.gitignore": `# GENERATED BY GYDE — then yours.
+#
+# last-verdict.json is written by every \`gyde-design gate\` run. It is evidence
+# that the gate ran in a particular job, so a committed copy is stale by
+# definition — and a stale one is exactly what the action's proof step is
+# looking for. Everything else in this directory is generated content you
+# should commit.
+last-verdict.json
+`,
+  };
+}