@weatherboard/gyde-design 0.3.0

package/enforcement.mjs

@@ -0,0 +1,100 @@
+/**
+ * G-101 — when a rule starts blocking, in one place.
+ *
+ * Three checks now need the same answer: the client boundary (G-67), the
+ * Tailwind ban (G-98) and the styling-layer mandate (G-100). Each arrived
+ * reporting-only, because a rule that starts failing a consumer's build the day
+ * it ships is the surprise red build contract.md §5.2 forbids.
+ *
+ * G-67 established the mechanism and this generalises it: blocking is keyed to
+ * the version in the PRODUCT's own `gyde-emitted.json`, which only moves when
+ * they run `upgrade` and take the change. Keying it to Gyde's version would
+ * change every consumer's gate on the day Gyde reached the number, with nobody
+ * deciding to — a time bomb wearing a version number.
+ *
+ * WHY ONE THRESHOLD AND NOT THREE.
+ *
+ * Three staggered thresholds means three separate mornings where a consumer's
+ * gate fails for a reason they have to go and look up. One threshold means one
+ * conversation, one upgrade, one diff — and a consumer can read this table and
+ * know exactly what taking v0.3.0 costs them before they take it. The
+ * information is the product here as much as the enforcement is.
+ *
+ * A rule may still be given a later version when it genuinely needs more notice
+ * than its neighbours. What it may not do is arrive unlisted: a check that
+ * blocks without appearing here is a check nobody could have planned for.
+ *
+ * THE SCHEDULE IS DATA, DELIBERATELY.
+ *
+ * `pending()` reads it to answer the question a consumer actually has —
+ * "what will start failing me if I upgrade?" — which no amount of prose in a
+ * changelog answers as well as a list generated from the thing that decides.
+ */
+
+/** Rule id → the template version from which a finding blocks the gate. */
+export const SCHEDULE = {
+  "client-boundary": { version: "0.3.0", why: "a value crossing the \"use client\" boundary renders undefined props (G-67)" },
+  "tailwind-present": { version: "0.3.0", why: "Tailwind is not a permitted styling layer (G-98)" },
+  "tailwind-in-css": { version: "0.3.0", why: "Tailwind's vocabulary in a stylesheet is the same ban, one file over (G-98)" },
+  "styling-layer": { version: "0.3.0", why: "StyleX is the mandated styling layer, and must be wired (G-100)" },
+};
+
+const parts = (v) => String(v).split(/[.-]/).slice(0, 3).map((n) => parseInt(n, 10) || 0);
+
+/** Is `a` at or beyond `b`? Numeric, so 0.10.0 is after 0.9.0. A malformed version reads as 0.0.0. */
+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 this rule block for a product at this template version?
+ *
+ * Fails open on purpose. A repository with no manifest never scaffolded, so it
+ * cannot have opted into anything, and blocking it would be enforcement
+ * arriving without notice — which is the whole thing this module prevents.
+ * That is a known gap: adoption repositories are exactly the ones most likely
+ * to have these defects, and closing it needs a mechanism other than a template
+ * version.
+ */
+export function blocksAt(rule, templateVersion) {
+  const entry = SCHEDULE[rule];
+  if (!entry || !templateVersion) return false;
+  return atLeast(templateVersion, entry.version);
+}
+
+/** Every scheduled rule that is not blocking yet for this product, and when it will. */
+export function pending(templateVersion) {
+  return Object.entries(SCHEDULE)
+    .filter(([rule]) => !blocksAt(rule, templateVersion))
+    .map(([rule, e]) => ({ rule, from: e.version, why: e.why }))
+    .sort((a, b) => a.from.localeCompare(b.from) || a.rule.localeCompare(b.rule));
+}
+
+/** Every scheduled rule that IS blocking for this product. */
+export function enforced(templateVersion) {
+  return Object.entries(SCHEDULE)
+    .filter(([rule]) => blocksAt(rule, templateVersion))
+    .map(([rule, e]) => ({ rule, from: e.version, why: e.why }));
+}
+
+export function formatSchedule(templateVersion) {
+  const now = enforced(templateVersion);
+  const later = pending(templateVersion);
+  const L = [];
+
+  L.push(templateVersion
+    ? `enforcement  template v${templateVersion} — ${now.length} rule(s) blocking, ${later.length} advisory`
+    : `enforcement  no gyde-emitted.json — nothing blocks, because nothing was opted into`);
+
+  for (const r of now) L.push(`             blocking   ${r.rule.padEnd(20)} since v${r.from}`);
+  for (const r of later) L.push(`             advisory   ${r.rule.padEnd(20)} blocks from v${r.from}`);
+
+  if (later.length) {
+    L.push("");
+    L.push("  Advisory rules report and do not fail. They begin blocking when you take the");
+    L.push("  template version beside them, by running `upgrade` — so the change arrives in");
+    L.push("  a diff you reviewed, not as a build that broke overnight.");
+  }
+  return L.join("\n");
+}

package/index.mjs

@@ -0,0 +1,40 @@
+/**
+ * `@weatherboard/gyde-design` — the public surface.
+ *
+ * Everything below is re-exported deliberately rather than by a wildcard, so
+ * adding a module does not silently widen what customers depend on. The v0.1
+ * consumers are two repositories inside the same organisation; that is exactly
+ * the point at which an accidental export becomes something you cannot remove.
+ *
+ * ZERO RUNTIME DEPENDENCIES. Only `node:` builtins, which is what makes a git
+ * dependency viable at all: nothing to install, nothing to build, and no
+ * transitive tree to audit. If that ever stops being true it should be a
+ * decision recorded here, not a line in a lockfile.
+ */
+
+export { discover, summarise, detectScope, detectRunner, readWorkspaceGlobs, parsePnpmWorkspace, EXCLUSION } from "./workspace.mjs";
+export { normaliseSource, normaliseCss, normaliseUtilities, normaliseDeclaration, toPx, PROP } from "./normalise.mjs";
+export { loadRules, run as runRules, coverage, RULES_BY_ID, FIXTURES, CLASSIFICATION, DEFAULTS as RULE_DEFAULTS } from "./rules.mjs";
+export { scan, format as formatScan, classify as classifyFile } from "./scan.mjs";
+
+export { SEED, themed, validate, generateCss, generateConstants, generateDtcg, generateStyleX, varName, kebab, CSS_HEADER } from "./tokens.mjs";
+export { seedBoundaries, seedDependencyBoundaries, validateBoundaries, proveBoundaries, proveDependencyBoundaries, loadBoundaries, loadDependencyBoundaries, isImportBreach, checkBoundaries, checkDependencyBoundaries, findVersionDrift } from "./boundaries.mjs";
+export { record, compare, gate, formatGate, tally, LEDGER_NOTE } from "./ratchet.mjs";
+
+export { emitTokens, emitSystem, emitConfig, SEED_COMPONENTS, SCAFFOLD_VERSION, NOT_UPGRADEABLE } from "./emit.mjs";
+export { emitCatalogue, CATALOGUE_ENTRIES } from "./catalogue.mjs";
+export { emitAgentDocs, agentDoc, agentInstructionsFragment } from "./agentdocs.mjs";
+
+export { hash, buildManifest, readManifest, writeManifest, classify as classifyUpgrade, applyUpgrade, diff, formatUpgrade, STATUS as UPGRADE_STATUS, MANIFEST } from "./upgrade.mjs";
+export { buildUsage, guidance, formatUsage } from "./usage.mjs";
+export { exportedComponents, renderableComponents, isComponentName, checkWiring, checkPackage, formatWiring, WIRING } from "./wiring.mjs";
+export { propMembers, optionalProps, optionalPropsIn, formatOptionalProps, requiredNullableGuards, formatRequiredNullableGuards, RULE as OPTIONAL_PROP_RULE, GUARD_RULE } from "./props.mjs";
+export { SCHEDULE, blocksAt, pending, enforced, formatSchedule } from "./enforcement.mjs";
+export { checkStyleX, stylexFindings, formatStyleX, RULE as STYLEX_RULE } from "./stylex.mjs";
+export { migrationProgress, formatMigration } from "./migration.mjs";
+export { detectTailwind, tailwindFindings, formatTailwind, importsTailwind, tailwindInCss, formatTailwindCss, RULE as TAILWIND_RULE, CSS_RULE as TAILWIND_CSS_RULE } from "./tailwind.mjs";
+export { reconcile, formatAdoption, LAYERS as ADOPTION_LAYERS } from "./adoption.mjs";
+export { classifyMarkup, markupAdoption, formatMarkup, KIND as MARKUP_KIND } from "./markup.mjs";
+export { orphanedParts, formatOrphanedParts, RULE as COMPOUND_RULE } from "./compound.mjs";
+export { checkDocDrift, importedFrom, formatDocDrift, namedInProse, isContractDoc, isFixtureDeclaration, stalePaths, rootDirectories, formatStalePaths, RULE as DOC_DRIFT_RULE, PROSE_RULE, PATH_RULE } from "./docdrift.mjs";
+export { isClientModule, parseImports, parseReexports, valueUses, checkClientBoundary, formatClientBoundary } from "./clientboundary.mjs";

package/markup.mjs

@@ -0,0 +1,177 @@
+/**
+ * G-73 — importing the system is not using it.
+ *
+ * CHARTER §2 asks for "markup-aware adoption (bespoke-pattern density, not just
+ * imports)". Every adoption number Gyde has produced so far is import-shaped or
+ * declaration-shaped, and both can be high while the rendered page is
+ * hand-rolled:
+ *
+ * - **Import-level** says a file imports `Button`. A file can import Button
+ *   once, render it once, and hand-roll forty styled divs underneath.
+ * - **Declaration-level** — Gyde's current number — says what fraction of style
+ *   DECLARATIONS are tokenised. A page built entirely from bare `<div>`s with
+ *   semantic utility classes scores beautifully, because every declaration it
+ *   makes is tokenised. It just is not using the component set.
+ *
+ * Neither is wrong. They answer different questions, and the measured spread
+ * between them in one repository — 95% against 15% — is what G-74 exists to
+ * reconcile. This module supplies the missing third view: of the elements that
+ * carry visual weight, how many are the system's?
+ *
+ * WHAT IS COUNTED, AND WHY THE DENOMINATOR IS NOT "EVERY ELEMENT".
+ *
+ * A layout `<div>` with no styling is not a missed opportunity to use a
+ * component. It is a div. Counting it as un-adopted makes the number a measure
+ * of how much markup a page has, which no team can act on and every team will
+ * learn to ignore.
+ *
+ * So the denominator is elements that carry a VISUAL DECISION — a system
+ * component, or a bare element that was styled at the call site. That is the
+ * population where "should this have been a component?" is a real question.
+ *
+ *   system      <Button>, <Card.Header>      the set, used
+ *   bespoke     <div className="…">          a styled element that is not the set
+ *   structural  <div>, <span>                no visual decision; not counted
+ *   foreign     <Image>, <Suspense>          somebody else's component; not counted
+ *
+ * `foreign` is excluded rather than counted against, for the same reason
+ * `structural` is: a framework's `<Image>` is not a component the design system
+ * was ever going to provide, and a number that falls when you adopt Next.js is
+ * a number that is measuring the wrong thing.
+ *
+ * THE NUMBER IS NEVER EMITTED WITHOUT ITS DENOMINATOR. That is this module's
+ * inherited contract (scan.mjs), and it matters more here than anywhere,
+ * because a markup ratio over four elements is noise wearing a percentage sign.
+ *
+ * @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 KIND = {
+  SYSTEM: "system",
+  BESPOKE: "bespoke",
+  STRUCTURAL: "structural",
+  FOREIGN: "foreign",
+};
+
+/**
+ * An opening JSX element, with its attribute text.
+ *
+ * Attributes may span lines — in real JSX they usually do — so the attribute
+ * group crosses newlines deliberately. A single-line match finds `<div` and
+ * never the `className` three lines down, which would classify every
+ * multi-line styled element as structural and inflate adoption exactly where
+ * the markup is most complex.
+ */
+function elements(text) {
+  const out = [];
+  const re = /<\s*([A-Za-z][\w.]*)((?:\s[^<>]*?)?)(\/?)>/g;
+  let m;
+  while ((m = re.exec(text))) out.push({ name: m[1], attrs: m[2] || "", index: m.index });
+  return out;
+}
+
+const stripComments = (text) =>
+  text.replace(/\/\*[\s\S]*?\*\//g, (s) => s.replace(/[^\n]/g, " "))
+      .replace(/^\s*\/\/[^\n]*/gm, "");
+
+/** Does this element carry a visual decision made at the call site? */
+const STYLED = /\b(className|class|style|css|sx|tw)\s*=/;
+
+/**
+ * Classify every element in a source file.
+ *
+ * `systemNames` is the design system's own exports. Without it nothing can be
+ * classified as `system`, so the caller gets `unknown` rather than a confident
+ * zero — a repository whose barrel could not be read has not scored 0% markup
+ * adoption, it has not been measured.
+ */
+export function classifyMarkup(text, { systemNames = null } = {}) {
+  if (!systemNames) return { unknown: true, why: "the design system's exports are not known, so nothing can be attributed to it" };
+
+  const src = stripComments(text);
+  const counts = { system: 0, bespoke: 0, structural: 0, foreign: 0 };
+  const bespokeElements = [];
+
+  for (const el of elements(src)) {
+    const isComponent = /^[A-Z]/.test(el.name);
+    const root = el.name.split(".")[0];
+
+    if (isComponent) {
+      if (systemNames.has(root)) counts.system++;
+      else counts.foreign++;
+      continue;
+    }
+
+    if (STYLED.test(el.attrs)) {
+      counts.bespoke++;
+      bespokeElements.push({ name: el.name, line: src.slice(0, el.index).split("\n").length });
+    } else {
+      counts.structural++;
+    }
+  }
+
+  const of = counts.system + counts.bespoke;
+  return {
+    unknown: false,
+    counts,
+    // The population where "should this have been a component?" is a real
+    // question. Never the total element count.
+    adoption: { used: counts.system, of, percent: of ? Math.round((counts.system / of) * 100) : null },
+    bespokeElements,
+  };
+}
+
+/**
+ * Markup adoption across a set of already-read files.
+ *
+ * Takes `[{ file, text }]` rather than walking, so the caller's scope decisions
+ * — which files are product code, which are templates for another repository —
+ * are made in one place instead of being re-derived here and drifting.
+ */
+export function markupAdoption(files, { systemNames = null } = {}) {
+  if (!systemNames) {
+    return { unknown: true, why: "the design system's exports are not known, so nothing can be attributed to it", perFile: [] };
+  }
+
+  const totals = { system: 0, bespoke: 0, structural: 0, foreign: 0 };
+  const perFile = [];
+
+  for (const { file, text } of files) {
+    const r = classifyMarkup(text, { systemNames });
+    if (r.unknown) continue;
+    if (r.adoption.of === 0) continue;            // no visual decisions here at all
+    for (const k of Object.keys(totals)) totals[k] += r.counts[k];
+    perFile.push({ file, ...r.adoption, counts: r.counts });
+  }
+
+  const of = totals.system + totals.bespoke;
+  return {
+    unknown: false,
+    counts: totals,
+    adoption: { used: totals.system, of, percent: of ? Math.round((totals.system / of) * 100) : null },
+    perFile: perFile.sort((a, b) => (a.percent ?? 101) - (b.percent ?? 101)),
+    filesWithMarkup: perFile.length,
+  };
+}
+
+export function formatMarkup(result) {
+  if (result.unknown) return `markup adoption: could not tell — ${result.why}`;
+
+  const { counts, adoption } = result;
+  const L = [];
+  L.push(`markup       ${adoption.used} of ${adoption.of} styled element(s) are the system` +
+         (adoption.percent === null ? " (nothing to measure)" : ` — ${adoption.percent}%`));
+  L.push(`             ${counts.bespoke} bespoke, ${counts.structural} structural (not counted), ${counts.foreign} foreign (not counted)`);
+
+  const worst = result.perFile.filter((f) => f.percent !== null && f.percent < 100).slice(0, 5);
+  if (worst.length) {
+    L.push("");
+    L.push("  most bespoke markup:");
+    for (const f of worst) L.push(`    ${f.file}  ${f.used}/${f.of} (${f.percent}%)`);
+  }
+  L.push("");
+  L.push("  A structural div is not a missed component and is not counted against you.");
+  L.push("  This asks only about elements that made a visual decision at the call site.");
+  return L.join("\n");
+}

package/migration.mjs

@@ -0,0 +1,148 @@
+/**
+ * G-99 — a migration is a ratchet you can see moving.
+ *
+ * G-98 raised the objection honestly: 4,842 findings with no incremental fix is
+ * a migration, not a ratchet, and a shrink-only ledger that sits flat for weeks
+ * is one people stop reading.
+ *
+ * Half of that turned out to be wrong, and it is worth writing down which half.
+ *
+ * THE GATE WAS ALREADY CORRECT. `compare` fails on an increase, passes on flat,
+ * and reports a decrease. For a framework removal that is exactly the behaviour
+ * wanted: no NEW Tailwind may appear anywhere, and the existing 4,842 may sit
+ * while the work happens. Nobody has to justify a file they did not touch. The
+ * instinct to build a second gate for migrations would have replaced a correct
+ * mechanism with a parallel one.
+ *
+ * THE REPORT WAS NOT. A flat 4,842 renders identically whether the migration is
+ * progressing in a branch, blocked on a decision, or dead — and "the number has
+ * not moved" is the only thing anybody can see. That is CHARTER §5's rule again:
+ * "no progress was made" and "progress is not visible from here" must not
+ * render the same.
+ *
+ * So this adds no gate and changes no verdict. It reads the baseline the ledger
+ * already recorded, compares it to now, and says how far a declared migration
+ * has come. The ledger has carried the answer since G-52; nothing had ever
+ * subtracted the two numbers.
+ *
+ * WHY THE BASELINE IS THE LEDGER AND NOT A SEPARATE FILE.
+ *
+ * A migration target stored anywhere else is a second record of the same debt,
+ * free to disagree with the first, and the disagreement would be discovered
+ * during the migration it was meant to track. The ledger is already the
+ * committed, reviewed, shrink-only record of what was there when the
+ * measurement became honest — which is the definition of a migration baseline.
+ */
+
+/** Sum a `{ file: { rule: count } }` tally for one rule. */
+function totalFor(allowed, rule) {
+  let total = 0, files = 0;
+  for (const rules of Object.values(allowed || {})) {
+    const n = rules?.[rule];
+    if (n === undefined) continue;
+    total += n; files++;
+  }
+  return { total, files };
+}
+
+function tallyFindings(findings) {
+  const out = {};
+  for (const f of findings) {
+    (out[f.file] ??= {});
+    out[f.file][f.rule] = (out[f.file][f.rule] || 0) + 1;
+  }
+  return out;
+}
+
+/**
+ * Progress of each declared migration, against the ledger's baseline.
+ *
+ * `migrating` is a list of rule ids the project has declared it is removing
+ * entirely, rather than ratcheting down indefinitely. Declaring it is the
+ * product's call: the difference between "we are reducing this" and "this is
+ * going to zero and here is the date" is a commitment, not a measurement, and
+ * Gyde should not infer it from a trend.
+ */
+export function migrationProgress(findings, ledger, { migrating = [] } = {}) {
+  if (!ledger) {
+    return { unknown: true, why: "no ledger, so there is no baseline to measure progress against", rules: [] };
+  }
+
+  const current = tallyFindings(findings);
+  const rules = [];
+
+  for (const rule of migrating) {
+    const base = totalFor(ledger.allowed, rule);
+    const now = totalFor(current, rule);
+
+    // A rule the ledger never recorded has no baseline, so it has no progress —
+    // reported as such rather than as 100% complete, which is what a naive
+    // subtraction from zero would produce.
+    if (base.total === 0 && now.total === 0) {
+      rules.push({ rule, unknown: true, why: "not in the ledger and not in the scan — nothing to migrate", baseline: 0, current: 0 });
+      continue;
+    }
+    if (base.total === 0) {
+      rules.push({ rule, unknown: true, why: "not in the ledger, so this scan has no baseline to compare against", baseline: 0, current: now.total });
+      continue;
+    }
+
+    const cleared = base.total - now.total;
+    rules.push({
+      rule,
+      unknown: false,
+      baseline: base.total, baselineFiles: base.files,
+      current: now.total, currentFiles: now.files,
+      cleared,
+      percent: Math.round((cleared / base.total) * 100),
+      done: now.total === 0,
+      // A negative number here is not an error to hide. The gate has already
+      // failed the increase; this is the same fact in the units the migration
+      // is measured in.
+      regressed: cleared < 0,
+    });
+  }
+
+  const measured = rules.filter((r) => !r.unknown);
+  const baseline = measured.reduce((n, r) => n + r.baseline, 0);
+  const remaining = measured.reduce((n, r) => n + r.current, 0);
+
+  return {
+    unknown: false,
+    rules,
+    recordedAt: ledger.recorded ?? null,
+    total: {
+      baseline, remaining, cleared: baseline - remaining,
+      percent: baseline ? Math.round(((baseline - remaining) / baseline) * 100) : null,
+    },
+  };
+}
+
+export function formatMigration(result) {
+  if (result.unknown) return `migration    could not tell — ${result.why}`;
+  if (result.rules.length === 0) return "migration    none declared";
+
+  const L = [];
+  const t = result.total;
+  L.push(
+    t.baseline === 0
+      ? "migration    nothing to measure — no declared rule has a baseline"
+      : `migration    ${t.percent}% complete  (${t.cleared} of ${t.baseline} cleared, ${t.remaining} remaining)` +
+        (result.recordedAt ? `  since ${result.recordedAt}` : ""),
+  );
+
+  for (const r of result.rules) {
+    if (r.unknown) { L.push(`             ${r.rule}: ${r.why}`); continue; }
+    const state = r.done ? "done" : r.regressed ? `REGRESSED by ${-r.cleared}` : `${r.percent}%`;
+    L.push(`             ${r.rule.padEnd(26)} ${String(r.current).padStart(5)} of ${r.baseline}  ${state}`);
+  }
+
+  if (t.baseline > 0 && t.cleared === 0) {
+    L.push("");
+    L.push("  Nothing cleared since the baseline. That is a fact about the work, not about");
+    L.push("  the gate — the gate passes a migration that has not moved, because nobody");
+    L.push("  should have to justify a file they did not touch. It is reported so that");
+    L.push("  'not started' and 'not visible from here' do not read the same.");
+  }
+  return L.join("\n");
+}