@weatherboard/gyde-design 0.3.0

package/workspace.mjs

@@ -0,0 +1,318 @@
+/**
+ * G-53 — finding the packages a design system has to cover.
+ *
+ * WHY THIS IS ITS OWN MODULE, AND WHY IT IS FIRST.
+ *
+ * The obvious implementation is `glob("apps/*")`, and it is wrong in a way that
+ * fails silently. Measured across the three repositories we have:
+ *
+ *   System B     pnpm workspace   apps/* + packages/*        7 apps
+ *   System A     pnpm workspace   apps/* + packages/*        3 apps
+ *   System C     pnpm + turbo     control-plane/*,           2 apps
+ *                                          customer-facing/*,
+ *                                          agentic-ai/*, packages/*
+ *
+ * Two of three match the convention. The third has no `apps/` directory at all,
+ * so a scaffolder that assumes one would discover nothing, emit a design system
+ * no application consumes, and report success. That is CHARTER §5's failure mode
+ * — a check that passes without running — reached before a single rule executes.
+ *
+ * So: read the workspace declaration, never the directory names.
+ *
+ * WHY IT REPORTS WHAT IT SKIPPED.
+ *
+ * `System C` has Python services (Poetry) in the same workspace as its
+ * TypeScript packages. They cannot carry a design system and must be excluded —
+ * but excluding them *silently* removes them from the denominator, and an
+ * adoption percentage that quietly stopped counting some of the tree is the
+ * measurement bug this product exists to prevent. Every package is classified
+ * and every exclusion carries a reason, so "we skipped it" and "it passed"
+ * never render the same.
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+/** Directories never worth walking into. */
+const SKIP_DIRS = new Set([
+  "node_modules", "dist", "build", ".next", ".turbo", ".git",
+  "coverage", "test-results", ".venv", "__pycache__", ".pytest_cache",
+]);
+
+/**
+ * Build-pipeline signatures, in the order we report them.
+ *
+ * A package can match more than one — `apps/design` in System B has both a
+ * postcss.config.mjs and a vite.config.ts — so this is a list rather than a
+ * lookup. The `styleLayerPlugin` field names where a token compiler would have
+ * to be wired, which is what G-48's "unwired pipeline fails loudly" rule needs
+ * to know before it can check anything.
+ */
+const PIPELINES = [
+  { kind: "next", files: ["next.config.ts", "next.config.js", "next.config.mjs"], styleLayerPlugin: "next.config" },
+  { kind: "vite", files: ["vite.config.ts", "vite.config.js", "vite.config.mjs"], styleLayerPlugin: "vite.config" },
+  { kind: "postcss", files: ["postcss.config.mjs", "postcss.config.js", "postcss.config.cjs"], styleLayerPlugin: "postcss.config" },
+  { kind: "expo", files: ["app.json", "app.config.ts"], styleLayerPlugin: null },
+];
+
+/**
+ * Why a package carries no design system. Each value is a *reason*, not a flag:
+ * the same discipline as System A's RENDERS_UI_WITHOUT_THE_SYSTEM map,
+ * where the note exists "because 'we forgot' and 'we decided' look identical
+ * from outside".
+ */
+export const EXCLUSION = {
+  NOT_JS: "no package.json — not a JavaScript or TypeScript package",
+  NO_UI: "declares no UI framework dependency, so it renders nothing",
+  TOOLING: "a build or CLI package, not a rendered surface",
+};
+
+/**
+ * Parse the `packages:` globs out of pnpm-workspace.yaml.
+ *
+ * Hand-rolled rather than pulling in a YAML dependency. The file is a single
+ * list of strings in every real example, and the parse is deliberately strict:
+ * anything it does not recognise is returned as `null` so the caller falls back
+ * to another declaration rather than proceeding on a half-read file. A silently
+ * empty glob list is exactly the failure this module exists to prevent, so
+ * "I could not read this" must be distinguishable from "it declared nothing".
+ */
+export function parsePnpmWorkspace(text) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => /^packages\s*:/.test(l));
+  if (start === -1) return null;
+
+  const globs = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^\S/.test(line)) break;                 // dedented out of the block
+    const m = line.match(/^\s*-\s*["']?([^"'#]+?)["']?\s*(?:#.*)?$/);
+    if (m) globs.push(m[1].trim());
+    else if (line.trim() && !line.trim().startsWith("#")) return null;
+  }
+  return globs.length ? globs : null;
+}
+
+/**
+ * Where this workspace declares its packages, and how we know.
+ *
+ * The `source` is reported because a scaffolder that guessed wrong should be
+ * debuggable from its output alone.
+ */
+export function readWorkspaceGlobs(root) {
+  const pnpmPath = join(root, "pnpm-workspace.yaml");
+  if (existsSync(pnpmPath)) {
+    const globs = parsePnpmWorkspace(readFileSync(pnpmPath, "utf8"));
+    if (globs) return { source: "pnpm-workspace.yaml", globs };
+  }
+
+  const pkgPath = join(root, "package.json");
+  if (existsSync(pkgPath)) {
+    let pkg;
+    try { pkg = JSON.parse(readFileSync(pkgPath, "utf8")); } catch { pkg = null; }
+    const ws = pkg && pkg.workspaces;
+    const globs = Array.isArray(ws) ? ws : ws && Array.isArray(ws.packages) ? ws.packages : null;
+    if (globs && globs.length) return { source: "package.json#workspaces", globs };
+  }
+
+  // A single-package repository is a legitimate shape, not an error. Say so
+  // explicitly rather than returning an empty list that reads as "found none".
+  return { source: "none — treating the root as a single package", globs: ["."] };
+}
+
+/** Expand one workspace glob. Only the `*` and `**` forms that appear in real manifests. */
+function expandGlob(root, glob) {
+  const clean = glob.replace(/\/+$/, "");
+  if (clean === ".") return [root];
+
+  const parts = clean.split("/");
+  let dirs = [root];
+  for (const part of parts) {
+    const next = [];
+    for (const dir of dirs) {
+      if (part === "*" || part === "**") {
+        let entries = [];
+        try { entries = readdirSync(dir); } catch { continue; }
+        for (const e of entries) {
+          if (SKIP_DIRS.has(e) || e.startsWith(".")) continue;
+          const full = join(dir, e);
+          try { if (statSync(full).isDirectory()) next.push(full); } catch { /* raced */ }
+        }
+      } else {
+        const full = join(dir, part);
+        try { if (statSync(full).isDirectory()) next.push(full); } catch { /* absent */ }
+      }
+    }
+    dirs = next;
+  }
+  return dirs;
+}
+
+/** Anything that renders UI needs one of these. Kept broad on purpose. */
+const UI_DEPS = [/^react$/, /^react-dom$/, /^next$/, /^vue$/, /^svelte$/, /^solid-js$/, /^preact$/];
+
+/** Packages whose job is tooling. A CLI that imports React to render Ink is not a surface. */
+const TOOLING_HINTS = [/-cli$/, /^cli$/, /eslint/, /^config$/, /-config$/, /^tsconfig/];
+
+function classify(dir, pkg) {
+  if (!pkg) return { carriesUI: false, reason: EXCLUSION.NOT_JS };
+
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}), ...(pkg.peerDependencies || {}) };
+  const names = Object.keys(deps);
+  const hasUI = names.some((n) => UI_DEPS.some((re) => re.test(n)));
+  if (!hasUI) return { carriesUI: false, reason: EXCLUSION.NO_UI };
+
+  const short = (pkg.name || "").split("/").pop() || "";
+  if (TOOLING_HINTS.some((re) => re.test(short)) && !pkg.dependencies?.next) {
+    return { carriesUI: false, reason: EXCLUSION.TOOLING };
+  }
+  return { carriesUI: true, reason: null };
+}
+
+function detectPipelines(dir) {
+  const found = [];
+  for (const p of PIPELINES) {
+    const file = p.files.find((f) => existsSync(join(dir, f)));
+    if (file) found.push({ kind: p.kind, file, styleLayerPlugin: p.styleLayerPlugin });
+  }
+  return found;
+}
+
+/**
+ * Discover every package in a workspace, classified.
+ *
+ * Returns `{ root, source, globs, packages }` where each package carries its
+ * path, name, whether it renders UI, its build pipelines, and — when it is
+ * excluded — the reason. Nothing is dropped from the list; exclusion is a field,
+ * not a filter, so a caller cannot accidentally report a percentage over a
+ * denominator that quietly shrank.
+ */
+export function discover(root) {
+  const { source, globs } = readWorkspaceGlobs(root);
+
+  const seen = new Set();
+  const packages = [];
+  for (const glob of globs) {
+    for (const dir of expandGlob(root, glob)) {
+      if (seen.has(dir)) continue;
+      seen.add(dir);
+
+      const pkgPath = join(dir, "package.json");
+      let pkg = null;
+      if (existsSync(pkgPath)) {
+        try { pkg = JSON.parse(readFileSync(pkgPath, "utf8")); } catch { pkg = null; }
+      }
+      const { carriesUI, reason } = classify(dir, pkg);
+      const rel = relative(root, dir) || ".";
+      packages.push({
+        path: rel.split(sep).join("/"),
+        absolute: dir,
+        name: pkg?.name ?? null,
+        carriesUI,
+        excludedBecause: reason,
+        pipelines: carriesUI ? detectPipelines(dir) : [],
+      });
+    }
+  }
+
+  packages.sort((a, b) => a.path.localeCompare(b.path));
+  return { root, source, globs, packages };
+}
+
+/**
+ * The npm scope this workspace names its packages under.
+ *
+ * WHY THIS IS DETECTED RATHER THAN ASKED.
+ *
+ * Emitted code has to import the packages it emits — `@x/design-system`,
+ * `@x/design-tokens` — and the first version hardcoded a placeholder scope. A
+ * scaffolded repository therefore contained imports that resolved to nothing,
+ * and would not build. It looked right in every test, because every test
+ * compared the emitted text against itself.
+ *
+ * The workspace already knows the answer: both real consumers name every
+ * package under one scope. So take the most common one, report it, and let
+ * `gyde.config.json` override — a project with no scope at all, or two, needs
+ * to say which it wants rather than have one guessed.
+ */
+export function detectScope(result) {
+  const counts = new Map();
+  for (const p of result.packages) {
+    const m = (p.name ?? "").match(/^(@[^/]+)\//);
+    if (m) counts.set(m[1], (counts.get(m[1]) ?? 0) + 1);
+  }
+  if (counts.size === 0) return { scope: null, why: "no package in this workspace uses a scope" };
+
+  const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  return {
+    scope: ranked[0][0],
+    why: `${ranked[0][1]} of ${result.packages.length} package(s) use it`,
+    // Reported so a repo with two scopes is a decision rather than a coin toss.
+    others: ranked.slice(1).map(([s, n]) => ({ scope: s, count: n })),
+  };
+}
+
+/**
+ * The one-line summary a scaffolder prints before it writes anything.
+ *
+ * It names the skipped packages rather than counting them. A run that says
+ * "4 packages excluded" invites nobody to check whether the right four were
+ * excluded; a run that names them does.
+ */
+export function summarise(result) {
+  const ui = result.packages.filter((p) => p.carriesUI);
+  const skipped = result.packages.filter((p) => !p.carriesUI);
+  const unwireable = ui.filter((p) => p.pipelines.length === 0);
+
+  return {
+    source: result.source,
+    total: result.packages.length,
+    carryUI: ui.map((p) => p.path),
+    pipelines: ui.flatMap((p) => p.pipelines.map((x) => `${p.path}:${x.kind}`)),
+    skipped: skipped.map((p) => ({ path: p.path, because: p.excludedBecause })),
+    // Surfaces that render but have no build pipeline we recognise. Not an
+    // error here — G-48 decides what to do — but never silently fine either.
+    uiWithoutPipeline: unwireable.map((p) => p.path),
+  };
+}
+
+/**
+ * The runner this repository already uses, read from its workflows.
+ *
+ * Same rule as the default branch: the repository is the source of truth and a
+ * guess is worse than a fallback. Found in System B, where eight of nine
+ * workflows are on Blacksmith and the ninth — Gyde's — was the only
+ * `ubuntu-latest` in the repo.
+ *
+ * WHY THE MAJORITY, AND WHY IT MUST BE A REAL LABEL.
+ *
+ * A wrong runner label does not fail: GitHub queues the job against a label
+ * nothing listens on, and it waits. A queued job is neither a pass nor a fail,
+ * nothing reports it, and the gate is silently absent — which is the CHARTER §5
+ * failure with no error message attached. So this only ever returns a label
+ * already in use by a workflow that runs in this repository today, and returns
+ * null rather than inventing one.
+ *
+ * Matrix expressions are skipped: `runs-on: ${{ matrix.os }}` names no runner,
+ * and copying it into a job with no matrix produces exactly the empty label
+ * above.
+ */
+export function detectRunner(root) {
+  const dir = join(root, ".github", "workflows");
+  if (!existsSync(dir)) return null;
+
+  const counts = new Map();
+  for (const file of readdirSync(dir)) {
+    if (!/\.ya?ml$/.test(file)) continue;
+    // Gyde's own workflow is excluded, or the first run's choice becomes
+    // self-justifying and a repository can never be detected as having moved.
+    if (file === "gyde.yml") continue;
+    let text; try { text = readFileSync(join(dir, file), "utf8"); } catch { continue; }
+    for (const [, label] of text.matchAll(/^\s*runs-on:\s*(\S.*?)\s*$/gm)) {
+      if (label.includes("${{") || label.startsWith("[")) continue;
+      const clean = label.replace(/^["']|["']$/g, "");
+      counts.set(clean, (counts.get(clean) || 0) + 1);
+    }
+  }
+  if (!counts.size) return null;
+  return [...counts].sort((a, b) => b[1] - a[1])[0][0];
+}