@weatherboard/gyde-design 0.3.0

package/props.mjs

@@ -0,0 +1,255 @@
+/**
+ * G-68 — the optional-props ban.
+ *
+ * Absorbed from a product that wrote it by hand, under the promotion route in
+ * contract.md §7. It passes the test there: it can be stated without naming a
+ * component, a token, a route or a brand value, and a second product on a
+ * different stack would want it.
+ *
+ * WHAT IT IS FOR.
+ *
+ * `emit.mjs` states the principle on the one prop it mattered most for:
+ *
+ *   "Required and nullable rather than optional. An omittable onClick on a real
+ *    button compiles, renders, and does nothing — pass null to say the no-op is
+ *    deliberate."
+ *
+ * That is the whole rule generalised. An optional prop lets a caller omit a
+ * decision, and the component then makes it silently. The omission and the
+ * decision are indistinguishable afterwards: nobody reading the call site can
+ * tell whether `size` was left out because medium was wanted, or because the
+ * author did not think about it. Required-and-nullable forces the author to say
+ * which, once, in the place where it is legible.
+ *
+ * WHY IT COUNTS RATHER THAN BLOCKS.
+ *
+ * Every real component set has these already — Gyde's own emitted set has ten.
+ * A ban that fails on all of them on day one is an outage, so this enters the
+ * allowance ledger like any other finding and ratchets down from wherever a
+ * repository starts. That is CHARTER §4 exactly: debt is recorded, never
+ * amnestied, and the list may only get shorter.
+ *
+ * The mechanism that lets it arrive at all is G-68's other half — a rule a
+ * ledger predates is adopted as existing debt rather than failing the build
+ * (ratchet.mjs, `rulesKnownTo`). Without it this rule could not ship to an
+ * existing consumer without turning their gate red for code they did not
+ * change.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO.
+ *
+ * It does not read defaults. `type = "button"` in a destructure is a real
+ * default and a reasonable argument for `type?`, but reading destructures to
+ * excuse declarations would make the rule depend on two places agreeing, and a
+ * rule that needs two places to agree fires on the disagreement rather than on
+ * the thing it is about. The ratchet already handles "this one is fine" — it
+ * is recorded, and it stops being counted the day somebody makes it required.
+ *
+ * @gyde-emits-source-for-another-repo — the fixtures in the test beside this
+ * file are TypeScript written as data for a repository that is not this one.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const RULE = "optional-prop";
+
+/** A Props type: `export type XProps = {`, `export interface XProps {`, and the non-exported forms. */
+const PROPS_DECL = /\b(?:type|interface)\s+(\w*Props)\b[^{]*\{/;
+
+const stripComments = (text) =>
+  text.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+      .replace(/\/\/[^\n]*/g, "");
+
+/**
+ * An optional member declaration.
+ *
+ * Anchored to the start of a line so a `?` inside a type expression — a
+ * conditional type, an optional tuple element, a nested object's own member —
+ * cannot be read as a member of THIS type. Missing one of those is a miss; a
+ * false positive on a repository's existing code is a rule people switch off.
+ */
+const OPTIONAL_MEMBER = /^\s*(?:readonly\s+)?(\w+)\s*\?\s*:/;
+
+/** Any member declaration: `name: T`, `name?: T`, `readonly name: T`. */
+const MEMBER = /^\s*(?:readonly\s+)?(\w+)\s*(\?)?\s*:\s*(.+?)\s*;?\s*$/;
+
+/**
+ * Does this type include `null` as its own alternative?
+ *
+ * Union members only — `A | null`, `(() => void) | null`. A `null` appearing
+ * inside a generic argument (`Map<string, null>`) is that generic's business,
+ * not this member's, so the split is on top-level `|` with bracket depth zero.
+ */
+function unionIncludesNull(type) {
+  let depth = 0, current = "", prev = "";
+  const parts = [];
+  for (const ch of type) {
+    // `>` closes a generic — unless it is the tail of an arrow. Counting the
+    // arrow in `(() => void) | null` drove the depth negative, so the top-level
+    // `|` was never seen and the most important required-nullable shape in the
+    // emitted set read as non-nullable.
+    if ("<([{".includes(ch)) depth++;
+    else if (")]}".includes(ch)) depth--;
+    else if (ch === ">" && prev !== "=") depth--;
+
+    if (ch === "|" && depth === 0) { parts.push(current); current = ""; prev = ch; continue; }
+    current += ch;
+    prev = ch;
+  }
+  parts.push(current);
+  return parts.some((p) => p.trim() === "null");
+}
+
+/**
+ * Find every optional member of every Props type in a source file.
+ *
+ * Brace-depth tracked rather than regex-matched to the closing brace: a member
+ * whose type is itself an object literal (`options: { value: string }[]`) would
+ * otherwise end the block early and hide every member after it.
+ */
+export function propMembers(text, { filename = "" } = {}) {
+  const lines = stripComments(text).split("\n");
+  const found = [];
+
+  let depth = 0;
+  let typeName = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (typeName === null) {
+      const m = line.match(PROPS_DECL);
+      if (!m) continue;
+      typeName = m[1];
+      depth = countBraces(line.slice(line.indexOf("{")));
+      if (depth <= 0) typeName = null;               // a one-line type, already closed
+      continue;
+    }
+
+    // Only members at the type's own top level count. A nested object's members
+    // are that object's shape, not this component's API.
+    if (depth === 1) {
+      const optional = OPTIONAL_MEMBER.test(line);
+      const m = line.match(MEMBER);
+      if (m) {
+        found.push({
+          file: filename, line: i + 1, prop: m[1], type: typeName,
+          optional,
+          nullable: unionIncludesNull(m[3]),
+          declared: m[3],
+        });
+      }
+    }
+
+    depth += countBraces(line);
+    if (depth <= 0) typeName = null;
+  }
+
+  return found;
+}
+
+export function optionalProps(text, { filename = "" } = {}) {
+  return propMembers(text, { filename })
+    .filter((m) => m.optional)
+    .map((m) => ({ file: m.file, rule: RULE, line: m.line, prop: m.prop, type: m.type }));
+}
+
+function countBraces(s) {
+  let n = 0;
+  for (const ch of s) { if (ch === "{") n++; else if (ch === "}") n--; }
+  return n;
+}
+
+/** Read one file from disk and report its optional props. Returns [] for anything unreadable. */
+export function optionalPropsIn(root, rel) {
+  let text;
+  try { text = readFileSync(join(root, rel), "utf8"); } catch { return []; }
+  if (!/\bProps\b/.test(text)) return [];            // cheap reject before the line walk
+  return optionalProps(text, { filename: rel });
+}
+
+export const GUARD_RULE = "required-nullable-guard";
+
+/**
+ * G-69 — a guard against `undefined` on a prop that can never be undefined.
+ *
+ * This is the defect the optional-props ban CREATES if nobody looks for it.
+ * Converting `onClick?: () => void` to `onClick: (() => void) | null` is the
+ * fix G-68 asks for, and it silently turns every existing
+ * `if (onClick !== undefined)` into a condition that is always true. The
+ * component keeps compiling. The branch keeps running. The case the guard was
+ * written to exclude is now included, and nothing anywhere reports it.
+ *
+ * TypeScript will not catch it: the comparison is legal, and with
+ * `strictNullChecks` the narrowed type is simply unchanged. A linter's
+ * no-unnecessary-condition rule can catch it, but it requires type information,
+ * which means it is off in most repositories that most need it.
+ *
+ * The three spellings are all here because they are all the same mistake, and a
+ * rule that catches two of three teaches people which spelling is safe:
+ *
+ *   x !== undefined      x === undefined      typeof x === "undefined"
+ *
+ * `x ?? fallback` and `x?.y` are NOT findings. Nullish coalescing and optional
+ * chaining both test null and undefined together, so they stay correct across
+ * exactly the change that breaks the explicit comparisons. They are the shape
+ * people should be moving to.
+ *
+ * SCOPE, and its honest limit. A bare identifier is matched, because props
+ * arrive destructured and that is how they are written. A local variable that
+ * shares a prop's name would be a false positive. That is accepted: the guard
+ * would still be reading a name the file declares as required-nullable, which
+ * is worth a second look either way.
+ */
+export function requiredNullableGuards(text, { filename = "" } = {}) {
+  const members = propMembers(text, { filename }).filter((m) => !m.optional && m.nullable);
+  if (members.length === 0) return [];
+
+  const byName = new Map(members.map((m) => [m.prop, m]));
+  const src = stripComments(text);
+  const found = [];
+
+  src.split("\n").forEach((line, i) => {
+    for (const [name, member] of byName) {
+      const compare = new RegExp(`(?<![\\w$.])${name}\\s*[!=]==\\s*undefined`);
+      const typeofCmp = new RegExp(`typeof\\s+${name}\\s*[!=]==\\s*["']undefined["']`);
+      if (!compare.test(line) && !typeofCmp.test(line)) continue;
+
+      found.push({
+        file: filename, rule: GUARD_RULE, line: i + 1, prop: name, type: member.type,
+        declared: member.declared, source: line.trim(),
+      });
+    }
+  });
+
+  return found;
+}
+
+export function formatRequiredNullableGuards(findings) {
+  if (findings.length === 0) return "no guards compare a required-nullable prop against undefined";
+  const L = [`${findings.length} always-true guard(s):`];
+  for (const f of findings) {
+    L.push(`  ${f.file}:${f.line}  ${f.type}.${f.prop} is \`${f.declared}\` — required, so never undefined`);
+    L.push(`      ${f.source}`);
+  }
+  L.push("");
+  L.push("  The prop is required, so it cannot be undefined and this condition is always");
+  L.push("  true. The case it was written to exclude is being included. Compare against");
+  L.push("  null, or use ?? / ?. which test both and stay correct.");
+  return L.join("\n");
+}
+
+export function formatOptionalProps(findings) {
+  if (findings.length === 0) return "no optional props in any Props type";
+  const byFile = {};
+  for (const f of findings) (byFile[f.file] ??= []).push(f);
+  const L = [`${findings.length} optional prop(s) across ${Object.keys(byFile).length} file(s):`];
+  for (const [file, fs] of Object.entries(byFile)) {
+    L.push(`  ${file}  ${fs.map((f) => `${f.type}.${f.prop}`).join(", ")}`);
+  }
+  L.push("");
+  L.push("  An optional prop lets a caller omit a decision and the component makes it");
+  L.push("  silently. Afterwards nobody can tell an omission from a choice. Required and");
+  L.push("  nullable says which, once, where it is legible.");
+  return L.join("\n");
+}

package/ratchet.mjs

@@ -0,0 +1,290 @@
+/**
+ * G-52 — the allowance ledger, and the gate that reads it.
+ *
+ * A gate that blocks on every existing violation is an outage. System B had ~100
+ * pre-existing hits and System C has 4,061, so the only usable shape is
+ * to record what is already wrong and judge a change on what it introduced.
+ *
+ * THE SENTENCE THAT MAKES IT WORK, carried from System B almost verbatim,
+ * because without it an allowance file becomes a to-do list nobody reads:
+ *
+ *   "This list may only ever get shorter: a new violation in any of these files
+ *    fails the gate, and so does re-adding an entry that has been cleared. It is
+ *    not a permission to leave them — it is the record of what was already there
+ *    when the measurement became honest."
+ *
+ * THE MECHANISM WORTH COPYING EXACTLY. A cleared entry is **deleted** from the
+ * ledger, never zeroed. That single choice makes "a new violation" and "a
+ * violation somebody re-added" the same code path, so the third failure mode
+ * needs no code of its own and cannot be forgotten.
+ *
+ * WHAT System B ADDS. Compare **per scope**, never on the headline. Their gate had
+ * to be rewritten because widening the measurement to a newly-included
+ * app moved the average down while no file had got worse. An average is a
+ * number that can regress with nothing behind it regressing; a per-file tally
+ * cannot.
+ */
+
+export const LEDGER_NOTE =
+  "This list may only ever get shorter: a new violation in any of these files " +
+  "fails the gate, and so does re-adding an entry that has been cleared. It is " +
+  "not a permission to leave them — it is the record of what was already there " +
+  "when the measurement became honest. Regenerate ONLY after clearing " +
+  "violations, never to make a failure go away.";
+
+/** Tally findings into `{ file: { rule: count } }`. */
+export function tally(findings) {
+  const out = {};
+  for (const f of findings) {
+    (out[f.file] ??= {});
+    out[f.file][f.rule] = (out[f.file][f.rule] || 0) + 1;
+  }
+  return sortDeep(out);
+}
+
+function sortDeep(obj) {
+  const out = {};
+  for (const k of Object.keys(obj).sort()) {
+    out[k] = Object.fromEntries(Object.entries(obj[k]).sort(([a], [b]) => a.localeCompare(b)));
+  }
+  return out;
+}
+
+/**
+ * Record the current state as the baseline.
+ *
+ * CHARTER §4: *"Amnesty never: adoption of an existing codebase records current
+ * debt as allowances and ratchets from there; it does not reset anything to zero
+ * by declaration."* This function is that sentence — it is the only sanctioned
+ * way debt enters the ledger, and it always enters as a recorded number rather
+ * than as an exemption.
+ */
+export function record(findings, { recorded, ticket = null, rules = null } = {}) {
+  const allowed = tally(findings);
+  const total = Object.values(allowed).reduce(
+    (n, rules) => n + Object.values(rules).reduce((m, c) => m + c, 0), 0);
+  return {
+    note: LEDGER_NOTE,
+    // Passed in rather than read from the clock: a generated file whose content
+    // depends on when it ran cannot be diffed against its generator.
+    recorded: recorded ?? null,
+    ticket,
+    // G-68. Which rules this ledger was measured against — NOT which ones
+    // found something. Without it, "a rule that did not exist when this was
+    // recorded" and "a rule whose every entry has been cleared" are the same
+    // observation: absent from `allowed`. They must not be, because one has to
+    // be recorded and the other has to fail. See `rulesKnownTo`.
+    rules: rules ? [...new Set(rules)].sort() : null,
+    total,
+    allowed,
+  };
+}
+
+/**
+ * The rule set that existed before ledgers recorded their own.
+ *
+ * A ledger written before G-68 has no `rules` field, and the question "what did
+ * it know?" has to be answered somehow. The first attempt inferred it from the
+ * entries the ledger carries — and that is wrong in a way the existing tests
+ * caught immediately: a ledger recorded on a clean repository carries no
+ * entries, so it would appear to know nothing, and the first real violation
+ * would be adopted as pre-existing debt instead of failing.
+ *
+ * That is enforcement shrinking without anybody choosing it, which is the exact
+ * failure contract.md §7 forbids. So the answer is not inferred, it is
+ * recorded: these are the five rules that existed when the field did not.
+ * Anything on this list is enforced against a legacy ledger exactly as before.
+ */
+export const LEGACY_RULES = [
+  "arbitrary-shadow",
+  "untokenised-colour",
+  "untokenised-radius",
+  "untokenised-space",
+  "untokenised-type",
+];
+
+/**
+ * The rules a ledger was measured against.
+ *
+ * Fails closed. A ledger that does not say is treated as knowing every rule
+ * that existed before ledgers said — never as knowing none — so adoption can
+ * only ever apply to a rule that genuinely postdates it.
+ */
+export function rulesKnownTo(ledger) {
+  if (Array.isArray(ledger?.rules)) return { rules: new Set(ledger.rules), inferred: false };
+  return { rules: new Set(LEGACY_RULES), inferred: true };
+}
+
+/**
+ * Fold adopted entries into a ledger, and record which rules it now knows.
+ *
+ * Separate from `record` because it is not the same act. `record` takes a
+ * measurement of everything; this takes an existing measurement and adds the
+ * rules that did not exist when it was made, leaving every other number exactly
+ * as it was. A rule arriving must not silently re-baseline a file whose debt
+ * somebody has been paying down.
+ *
+ * `rules` is the full set the scan ran, not just the adopted ones — otherwise a
+ * rule that found nothing this time stays unknown, and its first violation
+ * would be adopted instead of failed.
+ */
+export function adopt(ledger, adopted, { rules }) {
+  const allowed = JSON.parse(JSON.stringify(ledger?.allowed ?? {}));
+  for (const a of adopted) {
+    (allowed[a.file] ??= {});
+    allowed[a.file][a.rule] = a.count;
+  }
+  const known = new Set([...(rulesKnownTo(ledger).rules), ...rules]);
+  const total = Object.values(allowed).reduce(
+    (n, rs) => n + Object.values(rs).reduce((m, c) => m + c, 0), 0);
+  return {
+    ...ledger,
+    note: LEDGER_NOTE,
+    rules: [...known].sort(),
+    total,
+    allowed: sortDeep(allowed),
+  };
+}
+
+/**
+ * Compare a fresh scan against the ledger.
+ *
+ * Returns `{ ok, failures, cleared, unchanged }`. `cleared` is a *result*, not a
+ * pass: a count that went down must be committed, or the next run silently
+ * allows the violation to come back. Progress that is not written down is not
+ * ratcheted.
+ */
+export function compare(findings, ledger) {
+  const current = tally(findings);
+  const allowed = ledger?.allowed ?? {};
+  const known = rulesKnownTo(ledger);
+
+  const failures = [];
+  const cleared = [];
+  const adopted = [];
+  let unchanged = 0;
+
+  for (const [file, rules] of Object.entries(current)) {
+    for (const [rule, count] of Object.entries(rules)) {
+      const budget = allowed[file]?.[rule];
+
+      // G-68. A rule this ledger was never measured against did not exist when
+      // the measurement was taken, so its hits are pre-existing debt rather
+      // than something this change introduced. Recording them is CHARTER §4
+      // working as written — debt enters as a recorded allowance, never as zero
+      // by declaration — and it is what contract.md §5.2 promises a customer:
+      // a new rule arrives as an allowance-backed ratchet, not a red build.
+      //
+      // This deliberately does NOT weaken the delete-not-zero guarantee. A rule
+      // the ledger knows about, with an entry that has been cleared, is still
+      // absent from `allowed` and still fails below.
+      if (budget === undefined && !known.rules.has(rule)) {
+        adopted.push({ file, rule, count, inferred: known.inferred });
+        continue;
+      }
+
+      if (budget === undefined) {
+        // Covers BOTH "never seen" and "cleared and re-added", because a
+        // cleared entry is deleted rather than zeroed. One code path, so the
+        // re-adding case cannot be the one somebody forgets to write.
+        failures.push({
+          file, rule, count, allowed: 0, kind: "new",
+          why: "not in the ledger — either new, or cleared once and re-added. Both fail.",
+        });
+        continue;
+      }
+      if (count > budget) {
+        failures.push({
+          file, rule, count, allowed: budget, kind: "increased",
+          why: `was ${budget}, now ${count}. The ledger may only ever get shorter.`,
+        });
+        continue;
+      }
+      if (count < budget) {
+        cleared.push({ file, rule, count, allowed: budget });
+        continue;
+      }
+      unchanged++;
+    }
+  }
+
+  // An entry in the ledger with nothing behind it any more. Reported so a stale
+  // allowance cannot sit there forever quietly permitting a file that was
+  // deleted — the ledger has to track reality in both directions or it stops
+  // describing anything.
+  for (const [file, rules] of Object.entries(allowed)) {
+    for (const [rule, budget] of Object.entries(rules)) {
+      if (current[file]?.[rule] === undefined) cleared.push({ file, rule, count: 0, allowed: budget });
+    }
+  }
+
+  return { ok: failures.length === 0, failures, cleared, adopted, unchanged };
+}
+
+/**
+ * The gate's verdict over one or more scopes.
+ *
+ * Scopes are compared independently and the worst result wins. This is System B's
+ * lesson made structural: there is no averaging step for a newly-measured
+ * scope to dilute, because there is no average.
+ *
+ * `unmeasured` is a first-class outcome, not an empty result. CHARTER §5 — a
+ * surface Gyde could not review must fail, never pass quietly. "Gyde did not run
+ * here" and "Gyde found nothing here" must never render the same.
+ */
+export function gate(scopes) {
+  const results = [];
+  for (const s of scopes) {
+    if (s.unmeasured) {
+      results.push({
+        scope: s.name, ok: false, unmeasured: true,
+        why: s.why || "could not be measured, which fails by default rather than passing quietly",
+        failures: [], cleared: [],
+      });
+      continue;
+    }
+    results.push({ scope: s.name, unmeasured: false, ...compare(s.findings, s.ledger) });
+  }
+
+  return {
+    ok: results.every((r) => r.ok),
+    results,
+    failures: results.flatMap((r) => r.failures.map((f) => ({ ...f, scope: r.scope }))),
+    adopted: results.flatMap((r) => (r.adopted || []).map((a) => ({ ...a, scope: r.scope }))),
+    unmeasured: results.filter((r) => r.unmeasured).map((r) => r.scope),
+  };
+}
+
+/** A short report. Failures first — they are the only part that changes an exit code. */
+export function formatGate(verdict) {
+  const L = [];
+  for (const r of verdict.results) {
+    if (r.unmeasured) { L.push(`✖ ${r.scope}: UNMEASURED — ${r.why}`); continue; }
+    if (r.ok && r.cleared.length === 0 && (r.adopted || []).length === 0) {
+      L.push(`✔ ${r.scope}: held (${r.unchanged} allowed entries unchanged)`); continue;
+    }
+    if (r.ok && r.cleared.length === 0) { L.push(`✔ ${r.scope}: held (${r.unchanged} allowed entries unchanged)`); continue; }
+    if (r.ok) { L.push(`✔ ${r.scope}: held, and ${r.cleared.length} entry(ies) improved — commit the ledger to keep the ground`); continue; }
+    L.push(`✖ ${r.scope}: ${r.failures.length} failure(s)`);
+    for (const f of r.failures.slice(0, 10)) L.push(`    ${f.file}  ${f.rule}  ${f.why}`);
+    if (r.failures.length > 10) L.push(`    … and ${r.failures.length - 10} more`);
+  }
+  // Adoption is reported at the volume of a failure without being one. A rule
+  // that arrives, records silently and is never mentioned is a rule the product
+  // never learns it now has — and an unmentioned allowance is the to-do list
+  // nobody reads that LEDGER_NOTE exists to prevent.
+  if ((verdict.adopted || []).length) {
+    const byRule = {};
+    for (const a of verdict.adopted) (byRule[a.rule] ??= []).push(a);
+    L.push("", `${verdict.adopted.length} entry(ies) adopted for ${Object.keys(byRule).length} rule(s) this ledger predates:`);
+    for (const [rule, entries] of Object.entries(byRule)) {
+      const n = entries.reduce((s, e) => s + e.count, 0);
+      L.push(`    ${rule}: ${n} across ${entries.length} file(s) — recorded as existing debt, not judged`);
+    }
+    L.push("    Commit gyde-allowance.json, or the next run adopts them again and the rule never ratchets.");
+  }
+  if (verdict.unmeasured.length) {
+    L.push("", `${verdict.unmeasured.length} scope(s) could not be measured. That is a failure, not a pass.`);
+  }
+  return L.join("\n");
+}