@weatherboard/gyde-design 0.3.0

package/clientboundary.mjs

@@ -0,0 +1,399 @@
+/**
+ * G-67 — values must not cross the "use client" boundary.
+ *
+ * WHY THIS EXISTS.
+ *
+ * `emit.mjs` already knows this failure. It writes the defaults module without a
+ * directive, and puts a shouting comment on top telling the reader not to add
+ * one. That comment is knowledge addressed to ourselves: it protects the file
+ * Gyde emitted, on the day it was emitted, and it protects nothing afterwards.
+ * The moment a product adds a fourth component and puts its defaults beside it —
+ * the natural thing to do, which is exactly why the comment predicts it — Gyde
+ * has no way to notice. It emits code shaped to avoid a failure it cannot
+ * detect.
+ *
+ * THE FAILURE, PRECISELY.
+ *
+ * A module carrying "use client" does not export values to a server component.
+ * It exports *client references*: opaque objects with no enumerable properties.
+ * So `<Card {...CARD_DEFAULTS}>` on a server page spreads `{}`, every prop
+ * reverts to undefined, and React reports "Element type is invalid … got:
+ * undefined" — naming neither the element nor the prop that vanished.
+ *
+ * Nothing throws at the boundary. The build passes. The styling rules pass,
+ * because the source says `{...CARD_DEFAULTS}` and that is a perfectly
+ * tokenised thing to write. This is the shape of defect the whole product
+ * exists for: correct-looking code, silent at every gate, wrong at runtime.
+ *
+ * WHAT IS AND IS NOT A CROSSING.
+ *
+ * Importing a client COMPONENT into a server component is the React Server
+ * Components model working as designed, and this rule must never flag it — a
+ * rule that fires on the normal case is one people switch off in a week. React
+ * knows how to render a client reference. It does not know how to spread one.
+ *
+ * So the rule is narrow on purpose: a value-position use — an object spread or
+ * a property read — of a binding that came across the boundary. `<Button />`
+ * is fine. `{...BUTTON_DEFAULTS}` is not. `BUTTON_DEFAULTS.tone` is not.
+ *
+ * Type-only imports are erased before they reach a runtime and are skipped.
+ *
+ * WHAT IT CANNOT SEE, AND WHY THAT IS REPORTED RATHER THAN ASSUMED.
+ *
+ * Resolution is source-level: relative paths, and workspace packages resolved
+ * through their own barrel. It follows `export { X } from "./y"` and `export *
+ * from "./y"` one package deep. It does not run a bundler, so an import it
+ * cannot resolve is returned in `unresolved` rather than being counted as
+ * clean. `wiring.mjs` established that discipline — "could not tell" is its own
+ * outcome, never folded into "fine" — and the same reason applies here: this
+ * rule's whole value is catching a silence, so it must not produce one.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+// G-101. The schedule lives in one place; a second copy here would be free to
+// disagree with the table a consumer reads to plan their upgrade.
+import { SCHEDULE, blocksAt } from "./enforcement.mjs";
+import { join, relative, extname, sep, dirname, resolve as resolvePath } from "node:path";
+
+const SOURCE = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs"]);
+const SKIP = new Set(["node_modules", "dist", "build", ".next", "coverage", "out"]);
+
+/** Extension order for a bare specifier. `.tsx` first: components outnumber modules. */
+const RESOLVE_ORDER = [".tsx", ".ts", ".jsx", ".js", ".mjs"];
+
+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("/"));
+  }
+}
+
+/** A test file discusses the boundary; it does not cross it. Same exclusion as boundaries.mjs. */
+const isTest = (p) => /\.(test|spec)\.[jt]sx?$/.test(p) || /(^|\/)__tests__\//.test(p);
+
+/**
+ * A file whose string literals are source for a DIFFERENT repository.
+ *
+ * A generator holds `import { Card } from "./card"` as data. Reading that as an
+ * import of this repo's `./card` produced fifteen phantom "could not tell"
+ * entries the first time this ran against Gyde itself — a checker whose whole
+ * value is refusing to say "clean" without evidence, manufacturing doubt out of
+ * a template. The marker is the repo's existing convention (paths.test.mjs);
+ * honoured here so one declaration covers both checks.
+ */
+const TEMPLATE_MARKER = "@gyde-emits-source-for-another-repo";
+
+const stripComments = (text) =>
+  text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+
+/**
+ * Is this module a client module?
+ *
+ * The directive is only a directive when it leads the file. A "use client"
+ * further down is an ordinary string expression and React ignores it — so this
+ * checks position, not presence. The emitted defaults module states the rule in
+ * a comment containing the exact characters, which is why comments come off
+ * first: a file explaining the boundary must not read as one that declares it.
+ */
+export function isClientModule(text) {
+  const head = stripComments(text).trim();
+  return /^["']use client["']\s*;?/.test(head);
+}
+
+/**
+ * Imports, with their bindings. Type-only imports and bindings are dropped:
+ * they do not exist at runtime and cannot be spread.
+ */
+export function parseImports(text) {
+  const src = stripComments(text);
+  const out = [];
+  const re = /import\s+(type\s+)?([^;'"]*?)\s*from\s*["']([^"']+)["']/g;
+  let m;
+  while ((m = re.exec(src))) {
+    const [, typeOnly, clause, spec] = m;
+    if (typeOnly) continue;
+    const line = src.slice(0, m.index).split("\n").length;
+    const bindings = [];
+
+    const named = clause.match(/\{([^}]*)\}/);
+    if (named) {
+      for (const part of named[1].split(",")) {
+        const p = part.trim();
+        if (!p || /^type\s/.test(p)) continue;
+        const [imported, local] = p.split(/\s+as\s+/).map((s) => s.trim());
+        bindings.push({ imported, local: local || imported });
+      }
+    }
+    // A default or namespace binding is whatever sits outside the braces.
+    const outside = clause.replace(/\{[^}]*\}/, "").replace(/^\s*,|,\s*$/g, "").trim();
+    if (outside && !outside.startsWith("*")) {
+      bindings.push({ imported: "default", local: outside });
+    }
+    if (bindings.length) out.push({ spec, bindings, line });
+  }
+  return out;
+}
+
+/** Re-exports, for following a barrel to the module that actually declares a name. */
+export function parseReexports(text) {
+  const src = stripComments(text);
+  const out = [];
+  const re = /export\s+(type\s+)?(\*|\{[^}]*\})\s*from\s*["']([^"']+)["']/g;
+  let m;
+  while ((m = re.exec(src))) {
+    const [, typeOnly, clause, spec] = m;
+    if (typeOnly) continue;
+    if (clause === "*") { out.push({ spec, star: true, names: [] }); continue; }
+    const names = clause.replace(/[{}]/g, "").split(",")
+      .map((s) => s.trim()).filter(Boolean).filter((s) => !/^type\s/.test(s))
+      .map((s) => { const [i, a] = s.split(/\s+as\s+/).map((x) => x.trim()); return { imported: i, exported: a || i }; });
+    out.push({ spec, star: false, names });
+  }
+  return out;
+}
+
+/** Does this module declare (rather than re-export) the name? */
+function declaresName(text, name) {
+  const src = stripComments(text);
+  if (name === "default") return /export\s+default\b/.test(src);
+  return new RegExp(`export\\s+(?:async\\s+)?(?:const|let|var|function|class)\\s+${name}\\b`).test(src)
+    || new RegExp(`export\\s*\\{[^}]*\\b${name}\\b[^}]*\\}\\s*(?!from)`).test(src);
+}
+
+function readFile(root, rel) {
+  try { return readFileSync(join(root, rel), "utf8"); } catch { return null; }
+}
+
+/** Resolve a source-relative specifier to a repo-relative file, or null. */
+function resolveRelative(root, fromFile, spec) {
+  const base = resolvePath("/" + dirname(fromFile), spec).slice(1);
+  const candidates = [
+    ...RESOLVE_ORDER.map((e) => base + e),
+    ...RESOLVE_ORDER.map((e) => base + "/index" + e),
+    base,
+  ];
+  for (const c of candidates) if (readFile(root, c) !== null) return c;
+  return null;
+}
+
+/**
+ * Resolve a workspace package specifier to its barrel.
+ *
+ * Deliberately does not read `exports` maps in full. It takes the package's
+ * `main`/`module`/`exports["."]` if that points at source, and otherwise tries
+ * the conventional source barrel. A build output path is useless here — the
+ * directive lives in source, and a compiled bundle has already erased the
+ * question.
+ */
+function resolvePackage(root, spec, packages) {
+  const pkg = packages.find((p) => p.name === spec || spec.startsWith(p.name + "/"));
+  if (!pkg) return null;
+
+  if (spec !== pkg.name) {
+    const sub = spec.slice(pkg.name.length + 1);
+    return resolveRelative(root, pkg.path + "/x", "./" + sub);
+  }
+  for (const guess of ["src/index", "index", "src/main"]) {
+    const hit = resolveRelative(root, pkg.path + "/x", "./" + guess);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+function resolveSpec(root, fromFile, spec, packages) {
+  if (spec.startsWith(".")) return resolveRelative(root, fromFile, spec);
+  return resolvePackage(root, spec, packages);
+}
+
+/**
+ * Follow `name` from `file` to the module that declares it.
+ *
+ * Depth-limited and cycle-guarded. A barrel that re-exports a barrel is normal;
+ * a barrel that eventually re-exports itself is not, and must not hang a gate.
+ */
+function originOf(root, file, name, packages, seen = new Set(), depth = 0) {
+  if (depth > 8 || seen.has(file + "#" + name)) return null;
+  seen.add(file + "#" + name);
+
+  const text = readFile(root, file);
+  if (text === null) return null;
+  if (declaresName(text, name)) return { file, text };
+
+  for (const rx of parseReexports(text)) {
+    const target = resolveSpec(root, file, rx.spec, packages);
+    if (!target) continue;
+    if (rx.star) {
+      const hit = originOf(root, target, name, packages, seen, depth + 1);
+      if (hit) return hit;
+    } else {
+      const match = rx.names.find((n) => n.exported === name);
+      if (match) {
+        const hit = originOf(root, target, match.imported, packages, seen, depth + 1);
+        if (hit) return hit;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Value-position uses of a local binding.
+ *
+ * Two forms, both unambiguous and both the documented failure:
+ *   {...X}   the spread that produced the original defect
+ *   X.prop   a property read, which yields undefined for the same reason
+ *
+ * JSX use (`<X`, `</X`) is explicitly not a crossing. Anything subtler than
+ * these two forms is left alone rather than guessed at: a false positive here
+ * costs more than a miss, because the miss is still caught by the next person
+ * to spread the thing.
+ */
+export function valueUses(text, local) {
+  const src = stripComments(text);
+  const uses = [];
+  const spread = new RegExp(`\\{\\s*\\.\\.\\.\\s*${local}\\s*\\}`, "g");
+  const member = new RegExp(`(?<![\\w$.<])${local}\\s*\\.\\s*[A-Za-z_$]`, "g");
+
+  src.split("\n").forEach((line, i) => {
+    if (spread.test(line)) uses.push({ line: i + 1, form: "spread", source: line.trim() });
+    else if (member.test(line)) uses.push({ line: i + 1, form: "member", source: line.trim() });
+    spread.lastIndex = 0; member.lastIndex = 0;
+  });
+  return uses;
+}
+
+/**
+ * Check a tree for values crossing the client boundary.
+ *
+ * `packages` is the workspace listing from `discover()` — `{ name, path }` — and
+ * without it only relative imports resolve. That is a real reduction in reach
+ * and is reported: `unresolved` is the count of imports this could not follow,
+ * and a caller that prints findings without printing that number is publishing
+ * a clean bill it did not earn.
+ */
+export function checkClientBoundary(root, { packages = [] } = {}) {
+  const files = [];
+  walk(root, root, files);
+
+  const crossings = [];
+  const unresolved = [];
+  let serverFilesChecked = 0;
+
+  for (const file of files.sort()) {
+    if (isTest(file)) continue;
+    const text = readFile(root, file);
+    if (text === null) continue;
+    if (text.includes(TEMPLATE_MARKER)) continue;
+    if (isClientModule(text)) continue;      // a client file may spread freely
+    serverFilesChecked++;
+
+    for (const imp of parseImports(text)) {
+      const target = resolveSpec(root, file, imp.spec, packages);
+      if (!target) {
+        if (imp.spec.startsWith(".") || packages.some((p) => imp.spec.startsWith(p.name))) {
+          unresolved.push({ file, line: imp.line, spec: imp.spec });
+        }
+        continue;                            // third-party: not our boundary to police
+      }
+
+      for (const b of imp.bindings) {
+        const uses = valueUses(text, b.local);
+        if (!uses.length) continue;          // imported but never used as a value
+
+        const origin = originOf(root, target, b.imported, packages);
+        if (!origin) { unresolved.push({ file, line: imp.line, spec: imp.spec, name: b.imported }); continue; }
+        if (!isClientModule(origin.text)) continue;
+
+        for (const u of uses) {
+          crossings.push({
+            file, line: u.line, form: u.form, source: u.source,
+            binding: b.local, imported: b.imported, from: imp.spec, declaredIn: origin.file,
+          });
+        }
+      }
+    }
+  }
+
+  return { crossings, unresolved, serverFilesChecked, filesWalked: files.length };
+}
+
+/**
+ * The template version from which a crossing blocks the gate.
+ *
+ * WHY THIS IS KEYED TO THE PRODUCT'S TEMPLATE VERSION, NOT GYDE'S.
+ *
+ * Every existing consumer has a committed ledger. A new finding class that
+ * blocks on upgrade turns their gate red for something they have not been told
+ * about yet — and "amnesty never" (CHARTER §4) means it cannot be quietly
+ * baselined away either, so there would be no good move available to them.
+ *
+ * Keying to Gyde's own version would be worse: the day Gyde reaches this
+ * number, every consumer's gate changes behaviour at once without anyone
+ * deciding to change it. That is a time bomb wearing a version number.
+ *
+ * So it reads the version in the product's OWN `gyde-emitted.json`, which only
+ * moves when they run `upgrade` and take the change. Blocking becomes something
+ * a product opts into, visible in a diff, at a moment of their choosing.
+ *
+ * A repository with no manifest — an adoption repo where `init` found an
+ * existing system and refused to write over it — is advisory forever by this
+ * rule, because it never opted into anything. That is correct, and it is also
+ * a gap: those are exactly the repositories most likely to have the defect.
+ * Closing it needs a different mechanism than a template version.
+ */
+export const BLOCKS_FROM = SCHEDULE["client-boundary"].version;
+
+const parts = (v) => String(v).split(/[.-]/).slice(0, 3).map((n) => parseInt(n, 10) || 0);
+
+/** Is `a` at or beyond `b`? Numeric compare; a malformed version reads as 0.0.0 and does not block. */
+export function atLeast(a, b) {
+  const [x, y, z] = parts(a), [p, q, r] = parts(b);
+  return x !== p ? x > p : y !== q ? y > q : z >= r;
+}
+
+/** Does a crossing block the gate for a product at this template version? */
+export function blocks(templateVersion) {
+  return blocksAt("client-boundary", templateVersion);
+}
+
+export function formatClientBoundary(result, { blocking = null } = {}) {
+  const lines = [];
+  if (result.crossings.length === 0) {
+    lines.push(`no values cross the "use client" boundary (${result.serverFilesChecked} server file(s) checked)`);
+  } else {
+    lines.push(`${result.crossings.length} value(s) crossing the "use client" boundary:`);
+    for (const c of result.crossings) {
+      lines.push(`  ${c.file}:${c.line}  ${c.form} of \`${c.binding}\``);
+      lines.push(`      declared in ${c.declaredIn}, which is "use client"`);
+      lines.push(`      ${c.source}`);
+    }
+    lines.push("");
+    lines.push("  A server component importing a value from a \"use client\" module gets an");
+    lines.push("  opaque client reference, not the value. Spreading one yields {} and every");
+    lines.push("  prop silently reverts to undefined. Move the value to a module with no");
+    lines.push("  directive, importing only types.");
+
+    // Said in words, every run. An advisory finding that reports quietly is
+    // indistinguishable from one that found nothing — the same reason
+    // `fail-on: none` is loud in action.yml.
+    if (blocking === false) {
+      lines.push("");
+      lines.push(`  ADVISORY — this did not fail the gate. It blocks from template v${BLOCKS_FROM},`);
+      lines.push("  which you take by running `upgrade`. Fixing them now costs nothing later.");
+    } else if (blocking === true) {
+      lines.push("");
+      lines.push(`  BLOCKING — your template version is at or beyond v${BLOCKS_FROM}.`);
+    }
+  }
+  if (result.unresolved.length) {
+    lines.push("");
+    lines.push(`  could not tell for ${result.unresolved.length} import(s) — not counted as clean:`);
+    for (const u of result.unresolved.slice(0, 5)) lines.push(`    ${u.file}:${u.line}  ${u.spec}`);
+  }
+  return lines.join("\n");
+}

package/compound.mjs

@@ -0,0 +1,123 @@
+/**
+ * G-72 — a compound part with no root of its own above it.
+ *
+ * `<Select.Trigger>` outside a `<Select>` reads its root's context and gets
+ * nothing. What happens next depends on the library: a thrown error if it
+ * checks, `undefined` spreading through the part's props if it does not, and
+ * most often a control that renders, looks approximately right, and does not
+ * work. The compiler has no opinion — `Select.Trigger` is a real export and the
+ * JSX is valid.
+ *
+ * It is the same family as G-67. The type system is satisfied, every styling
+ * rule passes, and the defect is a relationship between two places in a tree
+ * that nothing in the toolchain looks at.
+ *
+ * THE FALSE POSITIVE THAT SHAPES THIS RULE.
+ *
+ * The obvious implementation walks the JSX tree and reports any part without an
+ * enclosing root. It is wrong, and commonly wrong:
+ *
+ *   function Header() { return <Card.Header>…</Card.Header>; }   // no root above it
+ *   function Page()   { return <Card><Header /></Card>; }        // …and it is fine
+ *
+ * Extracting a part into its own component is normal, good, and indistinguishable
+ * from the defect without following the call graph across files. A rule that
+ * fires on that is a rule that fires on refactoring, and it would be switched
+ * off the first week.
+ *
+ * So the rule is narrower than the title and says so: a part is reported when
+ * its root appears NOWHERE in the file. That is the case no composition can
+ * explain away locally — the file uses `Card.Header` and has no idea `Card`
+ * exists. It catches the orphan left behind when a root is deleted or renamed,
+ * which is the shape that actually ships.
+ *
+ * The stricter version needs a resolved component graph, which is G-73's
+ * territory. Recording the limit here so the next person does not "fix" this by
+ * widening it into the refactoring case.
+ *
+ * @gyde-emits-source-for-another-repo — the fixtures beside this file are JSX
+ * written as data for a repository that is not this one.
+ */
+
+export const RULE = "compound-part-without-root";
+
+/** `Root.Part`, and the nested `Root.Group.Item` form some libraries use. */
+const PART = /^([A-Z]\w*)((?:\.[A-Z]\w*)+)$/;
+
+/**
+ * Every JSX element opened in a source file.
+ *
+ * Attributes are allowed to span lines, because in real JSX they almost always
+ * do. Matching `[^>]*` on a single line finds the opening `<Card` of a
+ * multi-line element and never its name, so the root would appear absent in
+ * exactly the files most likely to be real.
+ */
+function elements(text) {
+  const out = [];
+  const re = /<\s*([A-Z][\w.]*)(\s[\s\S]*?)?(\/?)>/g;
+  let m;
+  while ((m = re.exec(text))) {
+    out.push({ name: m[1], index: m.index });
+  }
+  return out;
+}
+
+const stripComments = (text) =>
+  text.replace(/\/\*[\s\S]*?\*\//g, (s) => s.replace(/[^\n]/g, " "))
+      .replace(/^\s*\/\/[^\n]*/gm, "");
+
+const lineOf = (text, index) => text.slice(0, index).split("\n").length;
+
+/**
+ * Compound parts used in a file whose root is not used anywhere in that file.
+ *
+ * `roots` narrows the check to a known set — the design system's own exports —
+ * so `Foo.Bar` from an unrelated namespace object is not mistaken for a
+ * compound component. Without it every `Object.keys` shaped identifier in JSX
+ * position would be a candidate, and the rule would be guessing.
+ */
+export function orphanedParts(text, { filename = "", roots = null } = {}) {
+  const src = stripComments(text);
+  const els = elements(src);
+  if (els.length === 0) return [];
+
+  const opened = new Set(els.map((e) => e.name));
+  const found = [];
+  const reported = new Set();
+
+  for (const el of els) {
+    const m = el.name.match(PART);
+    if (!m) continue;
+    const [, root, rest] = m;
+
+    if (roots && !roots.has(root)) continue;          // not one of ours to judge
+
+    // The root itself, or the explicit `Root.Root` some libraries require.
+    if (opened.has(root) || opened.has(`${root}.Root`)) continue;
+
+    const key = `${el.name}@${el.index}`;
+    if (reported.has(key)) continue;
+    reported.add(key);
+
+    found.push({
+      file: filename, rule: RULE, line: lineOf(src, el.index),
+      part: el.name, root, member: rest.slice(1),
+    });
+  }
+
+  return found;
+}
+
+export function formatOrphanedParts(findings) {
+  if (findings.length === 0) return "no compound part is used without its root";
+  const L = [`${findings.length} compound part(s) used with no root in the file:`];
+  for (const f of findings) {
+    L.push(`  ${f.file}:${f.line}  <${f.part}> — <${f.root}> is not used anywhere in this file`);
+  }
+  L.push("");
+  L.push("  A part reads its root's context. Without one it gets nothing, and most");
+  L.push("  libraries render something that looks approximately right and does not work.");
+  L.push("  Either wrap it in its root, or the root was renamed and this is what was");
+  L.push("  left behind.");
+  return L.join("\n");
+}