@assure-one/design-system 1.32.0 → 1.34.0

package/codemods/lib/report.mjs

@@ -63,6 +63,7 @@ export function renderMarkdown(report) {
         const what = [
           f.component,
           f.rule,
+          f.action,
           f.severity && `severity ${f.severity}`,
           f.gate && `gate ${f.gate}`,
           f.confidence && `confidence ${f.confidence}`,

package/codemods/lib/runner.mjs

@@ -15,7 +15,7 @@ import {
   loadPostcss,
   loadTypeScript,
 } from "./environment.mjs";
-import { appliedIds, guardProblems, readLedger, recordApplied } from "./ledger.mjs";
+import { appliedIds, guardProblems, readLedger, recordApplied, requireLedger } from "./ledger.mjs";
 import { loadCodemod } from "./registry.mjs";
 
 export const REPORT_SCHEMA = 1;
@@ -37,18 +37,31 @@ export class Refused extends Error {
  * @param {string[]} [options.paths] files or directories (default: the root)
  * @param {boolean} [options.dry] report only; never write files or the ledger
  * @param {() => Date} [options.now] clock, for tests
+ * @param {(id: string) => Promise<object|null>} [options.load] codemod loader, for tests
  * @returns {Promise<object>} the report
  */
 export async function runCodemod(
   id,
-  { root, paths = [], dry = false, now = () => new Date() } = {},
+  { root, paths = [], dry = false, now = () => new Date(), load = loadCodemod } = {},
 ) {
-  const mod = await loadCodemod(id);
+  const mod = await load(id);
   if (!mod) throw new Refused([`Unknown codemod ${id}. \`run.mjs list\` shows the available ids.`]);
   const meta = mod.meta;
   const dsVersion = installedDsVersion();
   const ledger = readLedger(root);
   const problems = guardProblems(meta, ledger, dsVersion, compareVersions);
+  // A codemod whose prerequisite depends on its own state (CM-03 phase 2)
+  // exports `guard`; it gets the ledger and `requireLedger(ids)` bound to it.
+  if (typeof mod.guard === "function") {
+    const extra = await mod.guard({
+      root,
+      ledger,
+      dsVersion,
+      dry,
+      requireLedger: (ids) => requireLedger(ledger, ids, { id: meta.id }),
+    });
+    problems.push(...(extra ?? []));
+  }
   // A dry run may preview an already-applied one-shot codemod; missing
   // prerequisites still refuse, because the preview would be wrong.
   const blocking = dry ? problems.filter((p) => !p.includes("already applied")) : problems;
@@ -108,7 +121,13 @@ export async function runCodemod(
       String(a.match).localeCompare(String(b.match)),
   );
 
-  const applied = meta.class !== "X" && !dry && changed.length > 0;
+  // A transforming codemod is recorded when it ran for real: on its first run
+  // even when every call site was already in the target shape (a prerequisite
+  // such as CM-02 must be satisfiable in such a project), and again whenever
+  // it changed a file. A run that changes nothing in a project that already
+  // records it adds no entry.
+  const applied =
+    meta.class !== "X" && !dry && (changed.length > 0 || !appliedIds(ledger).has(meta.id));
   const appliedAt = now().toISOString();
   if (applied)
     recordApplied(root, { id: meta.id, appliedAt, dsVersion, filesChanged: changed.length });

package/codemods/transforms/cm-02-button-explicit-size.mjs

@@ -0,0 +1,96 @@
+/**
+ * CM-02 — Button: make the implicit default size explicit (class A; plan §29
+ * seq 4, registry `C-BTN-SIZE`, prerequisite of the size remap CM-03 and of
+ * 2.0 gate G6).
+ *
+ * Every `Button`, `SubmitButton` and `LinkButton` imported from the design
+ * system that passes no `size` gets `size="md"` — the value the component
+ * resolves today (`defaultVariants.size = "md"`, 40px), so the change is
+ * pixel-neutral. It exists because a size *meaning* can only change once no
+ * call site depends on the default: after CM-02, flipping what `md` or the
+ * default means (D5, W9-06) touches nothing a consumer did not write down.
+ *
+ * ## What it changes
+ *
+ * | rule            | registry   | what happens                                          |
+ * | --------------- | ---------- | ----------------------------------------------------- |
+ * | `implicit-size` | C-BTN-SIZE | `size="md"` is added, after `variant` when there is one |
+ *
+ * The attribute follows the file's own formatting (one per line or inline,
+ * see `lib/jsx-edit.mjs`), so a Prettier-formatted file stays formatted.
+ *
+ * ## What it leaves alone, and reports
+ *
+ * - An element with a spread (`<Button {...props}>`): the spread may already
+ *   carry `size`, and adding a literal before or after it would either be
+ *   overridden or override. It is listed under "could not be transformed"
+ *   with its line, for a human.
+ * - An element that already has `size` — any value, including the icon sizes
+ *   and a dynamic `size={x}` — is not touched. That is also what makes the
+ *   codemod idempotent.
+ * - Local components called `Button` that are not imported from the design
+ *   system, and test files (the scanner that measures G6 counts production
+ *   files only).
+ */
+import { analyseForms } from "../lib/forms.mjs";
+import { applyInsertions, insertAttribute, openingOf } from "../lib/jsx-edit.mjs";
+
+export const meta = {
+  id: "CM-02",
+  title: 'Button: make the implicit default size explicit (size="md")',
+  class: "A",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-BTN-SIZE"],
+};
+
+/** The design-system components whose `size` defaults to `md` today. */
+export const SIZED_BUTTONS = new Set(["Button", "SubmitButton", "LinkButton"]);
+
+/** What the component resolves when `size` is omitted (button.tsx `defaultVariants`). */
+export const DEFAULT_SIZE = "md";
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const findings = [];
+  const notTransformed = [];
+  const edits = [];
+
+  for (const el of facts.elements) {
+    if (!el.isDs || !SIZED_BUTTONS.has(el.base) || el.component !== el.base) continue;
+    if (el.props.has("size")) continue;
+    if (el.spread) {
+      notTransformed.push({
+        line: el.line,
+        reason: "spread-props",
+        detail: `<${el.tag} {…}> — the spread may already pass \`size\`; add size="${DEFAULT_SIZE}" by hand if it does not`,
+      });
+      continue;
+    }
+    edits.push(
+      insertAttribute(ts, facts.sf, openingOf(ts, el.node), `size="${DEFAULT_SIZE}"`, {
+        after: "variant",
+      }),
+    );
+    findings.push({
+      line: el.line,
+      registryId: "C-BTN-SIZE",
+      rule: "implicit-size",
+      match: `<${el.tag}>`,
+      component: el.component,
+      action: "applied",
+      gate: "G6",
+    });
+  }
+
+  return {
+    output: edits.length ? applyInsertions(file.source, edits) : file.source,
+    findings,
+    notTransformed,
+    parseErrors: facts.parseErrors,
+  };
+}

package/codemods/transforms/cm-12-button-type-submit.mjs

@@ -0,0 +1,115 @@
+/**
+ * CM-12 — Button: `type="submit"` where the intent is evident, a report for
+ * the rest (class R; plan §29 seq 8, registry `C-BTN-TYPE`, feeds 2.0 gate
+ * G4).
+ *
+ * A `Button` that passes no `type` renders `<button>` without one, which the
+ * browser treats as `type="submit"`: inside a `<form>` it submits. 65% of the
+ * applications' Buttons pass no `type`, and the design system flips the
+ * default to `"button"` in 2.0 (W9-05) — a change that silently stops a form
+ * from submitting wherever the untyped Button was the submitter. CM-12
+ * writes down, before the flip, which Buttons submit **on purpose**.
+ *
+ * ## What it changes
+ *
+ * Only what is evident from the file itself: an untyped design-system
+ * `Button` that is lexically inside a lower-case `<form>` element **in the
+ * same file**, has no `onClick` and no spread gets `type="submit"`. That
+ * states what the browser does today, so the edit is behaviour-neutral; the
+ * report lists it (rule `submit-in-form`) because a human still has to agree
+ * that submitting is what the button is for — a "Cancel" that matches this
+ * shape is a bug today, and the codemod has just made it visible.
+ *
+ * ## What it reports and leaves to a human
+ *
+ * | rule               | severity | why a human decides                                                            |
+ * | ------------------ | -------- | ------------------------------------------------------------------------------ |
+ * | `in-form-onclick`  | high     | inside a `<form>` with an `onClick`: submit with side effects, or a plain button? |
+ * | `in-form-spread`   | high     | inside a `<form>` with `{...props}`: the spread may or may not carry `type`     |
+ * | `outside-form`     | low      | no `<form>` in this file; if the component is rendered in one elsewhere, it submits today |
+ *
+ * Choosing `submit` or `button` is behaviour, which plan §29 never automates
+ * beyond the evident case. Nothing is followed across files: a component
+ * defined in this file and rendered inside a `<form>` by another is
+ * `outside-form`. A capitalised `<Form>` is not a form element (the
+ * react-hook-form / shadcn `Form` is a context provider), so it does not
+ * count.
+ *
+ * Not reported: `SubmitButton` (always `type="submit"`), `LinkButton` (an
+ * anchor), a Button with any `type` — literal or dynamic — and a Button with
+ * `asChild` (it renders its child, `type` does not apply to it). Test files
+ * are skipped, as by the scanner that measures G4.
+ */
+import { analyseForms } from "../lib/forms.mjs";
+import { applyInsertions, insertAttribute, openingOf } from "../lib/jsx-edit.mjs";
+
+export const meta = {
+  id: "CM-12",
+  title: 'Button: type="submit" on evident form submitters, a review list for the rest',
+  class: "R",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-BTN-TYPE"],
+};
+
+/** The one design-system component whose untyped rendering submits. */
+export const TYPED_BUTTON = "Button";
+
+/** The element that gives an untyped button a form to submit. Lower-case only. */
+export const FORM_TAG = "form";
+
+/** Whether the element has a lower-case `<form>` ancestor in this file. */
+export function insideForm(elements, el) {
+  for (let i = el.parent; i !== null; i = elements[i].parent) {
+    if (elements[i].tag === FORM_TAG) return true;
+  }
+  return false;
+}
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const findings = [];
+  const edits = [];
+
+  for (const el of facts.elements) {
+    if (!el.isDs || el.base !== TYPED_BUTTON || el.component !== el.base) continue;
+    if (el.props.has("type") || el.props.has("asChild")) continue;
+
+    const inForm = insideForm(facts.elements, el);
+    const onClick = el.props.has("onClick");
+    const base = {
+      line: el.line,
+      registryId: "C-BTN-TYPE",
+      match: `<${el.tag}>`,
+      component: el.component,
+      gate: "G4",
+      detail: { inForm, onClick, spread: el.spread },
+    };
+
+    if (!inForm) {
+      findings.push({ ...base, rule: "outside-form", severity: "low", action: "review" });
+      continue;
+    }
+    if (el.spread) {
+      findings.push({ ...base, rule: "in-form-spread", severity: "high", action: "review" });
+      continue;
+    }
+    if (onClick) {
+      findings.push({ ...base, rule: "in-form-onclick", severity: "high", action: "review" });
+      continue;
+    }
+    edits.push(insertAttribute(ts, facts.sf, openingOf(ts, el.node), 'type="submit"'));
+    findings.push({ ...base, rule: "submit-in-form", severity: "medium", action: "applied" });
+  }
+
+  return {
+    output: edits.length ? applyInsertions(file.source, edits) : file.source,
+    findings,
+    notTransformed: [],
+    parseErrors: facts.parseErrors,
+  };
+}

package/codemods/transforms/cm-14-hidden-mirrors.mjs

@@ -0,0 +1,275 @@
+/**
+ * CM-14 — hidden-input mirror finder (class X, report-only; plan §29,
+ * registry `C-HIDDEN-MIRRORS`, feeds Wave 4 W4-04).
+ *
+ * A *mirror* is a hidden `<input name="…">` a consumer added because a
+ * controlled design-system control emits no native form value ([CU §18]:
+ * "controlled design-system fields (Select, DatePicker) don't emit a native
+ * form value"). W4-04 gives those controls native participation, and the
+ * moment a call site passes `name` to the control **and** keeps its mirror,
+ * the form posts the field twice and the server action reads whichever the
+ * platform hands it first (plan §33, the duplicate-submission risk).
+ *
+ * Deleting a mirror therefore changes what the server receives, which is the
+ * one thing plan §29 never automates. CM-14 is report-only for ever: it
+ * names the site, the control, the field name and whether the control at
+ * that site already takes `name`, and a human decides each one.
+ *
+ * ## What it detects
+ *
+ * The applications do **not** put a mirror next to its control — they collect
+ * the mirrors at the top of the `<form>` and bind the control 200 lines
+ * lower. "Next to" is therefore read as *bound to the same state*:
+ *
+ * | rule                      | registry          | what it is                                                       |
+ * | ------------------------- | ----------------- | ---------------------------------------------------------------- |
+ * | `mirror-shared-binding`   | C-HIDDEN-MIRRORS  | the hidden input's `value` reads a binding a DS control is bound to |
+ * | `mirror-in-form`          | C-HIDDEN-MIRRORS  | same `<form>` as a DS control that posts nothing today, no shared binding |
+ * | `unregistered-hidden-input` | (unregistered)  | a hidden input with no DS control to mirror — a server-supplied field |
+ *
+ * The third rule is what makes the report reconcile with the audit's census
+ * of 64 hidden `<input>`s in PRO [CU §24]: that number counts every hidden
+ * input, and most of the auth-form ones carry a token or an email the server
+ * sent, not a mirrored control value. CM-14 reports all three classes so the
+ * difference is visible rather than asserted.
+ *
+ * ## What it deliberately does not do
+ *
+ * - It never writes a file (the runner refuses on class X).
+ * - It does not decide which of the two values is correct, and it does not
+ *   report a `name` collision as an error: `<name>_from`/`_to`
+ *   (DateRangePicker) and repeated `name`s read with `getAll()` are both
+ *   legitimate.
+ * - It says nothing about hidden inputs the design system renders itself
+ *   (DatePicker's own `<input type="hidden" name>`): those are inside the
+ *   package, never in consumer source.
+ * - `<input type={expr}>` with a computed type is not resolved; it appears
+ *   in `notTransformed` so the human sees what the scan could not read.
+ * - It does not look across files. A mirror in one file and its control in
+ *   another is reported as `unregistered-hidden-input`, with the name, and
+ *   left to the reader.
+ */
+import { CHANGE_PROPS, VALUE_PROPS, analyseForms, isWithin, literalValue } from "../lib/forms.mjs";
+
+export const meta = {
+  id: "CM-14",
+  title: "hidden-input mirror finder: hidden <input name> next to a design-system control",
+  class: "X",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-HIDDEN-MIRRORS"],
+};
+
+/** How a finding is weighted in the report and in the Wave 4 work. */
+export const SEVERITY = { high: "high", medium: "medium", low: "low" };
+
+/**
+ * Design-system controls a consumer mirrors, and whether they take `name`
+ * today (design system 1.32.0).
+ *
+ * - `"yes"` — the control accepts `name` now: `Select`, `DatePicker` and
+ *   `DateRangePicker` declare it themselves (`DatePicker` renders its own
+ *   hidden input, `DateRangePicker` renders `<name>_from`/`<name>_to`), and
+ *   `Checkbox`, `Switch`, `RadioGroup` and `Slider` inherit the Radix root
+ *   props and spread them, so Radix's own hidden input posts the value.
+ *   A mirror next to one of these is a *duplicate today* the moment the call
+ *   site also passes `name`.
+ * - `"planned"` — no `name` today; native participation arrives with the
+ *   Wave 4 item named in the comment. A mirror here is load-bearing until
+ *   then and must not be removed.
+ *
+ * `tests/codemods/cm-14.test.mjs` checks this table against the design
+ * system's own sources, so it cannot drift from the components it describes.
+ */
+export const NAME_CAPABILITY = {
+  Select: "yes", // src/primitives/select.tsx — `name?: string`
+  DatePicker: "yes", // renders `<input type="hidden" name>` with the ISO value
+  DateRangePicker: "yes", // renders `<name>_from` and `<name>_to`
+  Checkbox: "yes", // Radix checkbox root props
+  Switch: "yes", // Radix switch root props
+  RadioGroup: "yes", // Radix radio-group root props
+  Slider: "yes", // Radix slider root props
+  ClientSelect: "yes", // renders its own hidden `<input name>` (default `client_id`)
+  SearchSelect: "planned", // W4-12 (adapter over Combobox)
+  TeamMemberSelect: "planned", // W4-08/W4-12
+  MultiSelectField: "planned", // W4-08
+  ToggleGroup: "planned", // W4-16
+  PhoneCountryInput: "planned", // W4-04
+  OtpInput: "planned", // W4-04
+  Questions: "planned", // W4-04 (answer widgets)
+};
+
+/**
+ * Controls that already post a native value without any help, so a hidden
+ * input in the same form is not a mirror of them. They are still recorded as
+ * bindings, because a mirror of a controlled `Input` does exist ([CU §18]:
+ * `contact_name`) and is worth reporting — it just is not a design-system
+ * gap.
+ */
+export const NATIVE_CONTROLS = new Set(["Input", "Textarea", "SearchInput", "SubmitButton"]);
+
+const CONTROLS = new Set([...Object.keys(NAME_CAPABILITY), ...NATIVE_CONTROLS]);
+
+/** Whether an `<input>` element is `type="hidden"`. */
+const hiddenType = (el) => {
+  if (el.tag !== "input") return null;
+  const prop = el.props.get("type");
+  if (!prop) return null;
+  const literal = literalValue(prop);
+  if (literal === "hidden") return "literal";
+  if (prop.literals.includes("hidden")) return "computed";
+  return prop.expression ? "unknown" : null;
+};
+
+/** The bindings an attribute set reads, for the given attribute names. */
+const bindingsOf = (el, names) => {
+  const out = new Set();
+  for (const name of names) {
+    const prop = el.props.get(name);
+    if (!prop) continue;
+    for (const id of prop.identifiers) out.add(id);
+  }
+  return out;
+};
+
+const intersect = (a, b) => [...a].filter((x) => b.has(x)).sort();
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const findings = [];
+  const notTransformed = [];
+
+  const hidden = [];
+  for (const el of facts.elements) {
+    const kind = hiddenType(el);
+    if (kind === null) continue;
+    if (kind === "unknown") {
+      notTransformed.push({
+        line: el.line,
+        reason: "dynamic-type",
+        detail: `<input type={${el.props.get("type").text}}> — the type is computed, so the scan cannot tell whether it is hidden`,
+      });
+      continue;
+    }
+    hidden.push(el);
+  }
+  if (!hidden.length) return { findings, notTransformed, parseErrors: facts.parseErrors };
+
+  // Every design-system control in the file, with the bindings it is bound to.
+  const controls = facts.elements
+    .filter((el) => el.isDs && CONTROLS.has(el.base))
+    .map((el) => ({
+      el,
+      bindings: new Set([...bindingsOf(el, VALUE_PROPS), ...bindingsOf(el, CHANGE_PROPS)]),
+      acceptsName: NAME_CAPABILITY[el.base] ?? null,
+      native: NATIVE_CONTROLS.has(el.base),
+      named: literalValue(el.props.get("name")) ?? (el.props.has("name") ? "(expression)" : null),
+    }));
+  /** Controls that post nothing today and are the reason a mirror exists. */
+  const needMirror = controls.filter((c) => !c.native);
+
+  for (const el of hidden) {
+    const nameProp = el.props.get("name");
+    const name = nameProp ? (literalValue(nameProp) ?? nameProp.text) : null;
+    const valueProp = el.props.get("value");
+    const reads = new Set(valueProp?.identifiers ?? []);
+
+    // 1. The strong signal: the mirror and a control read the same binding.
+    const shared = controls
+      .map((c) => ({ c, common: intersect(reads, c.bindings) }))
+      .filter((x) => x.common.length)
+      .sort((a, b) => b.common.length - a.common.length);
+    if (shared.length) {
+      const best = shared[0];
+      const duplicate = best.c.named !== null && best.c.acceptsName === "yes";
+      add(findings, {
+        line: el.line,
+        registryId: "C-HIDDEN-MIRRORS",
+        severity: duplicate
+          ? SEVERITY.high
+          : best.c.acceptsName === "yes"
+            ? SEVERITY.medium
+            : SEVERITY.low,
+        rule: "mirror-shared-binding",
+        scope: el.form === null ? "no-form" : "form",
+        component: best.c.el.component,
+        match: name === null ? '<input type="hidden">' : `name=${JSON.stringify(name)}`,
+        detail: {
+          name,
+          binding: best.common.join(", "),
+          acceptsName: best.c.acceptsName,
+          controlPassesName: best.c.named,
+          controlLine: best.c.el.line,
+          sameForm: isWithin(facts.elements, best.c.el.index, el.form),
+          alsoMatches: shared.slice(1).map((x) => x.c.el.component),
+          nativeControl: best.c.native,
+        },
+        confidence: "high",
+      });
+      continue;
+    }
+
+    // 2. The weak signal: the same `<form>` holds a control that posts
+    //    nothing today, but nothing ties this input to it.
+    const inForm =
+      el.form === null
+        ? []
+        : needMirror.filter((c) => isWithin(facts.elements, c.el.index, el.form));
+    if (inForm.length) {
+      add(findings, {
+        line: el.line,
+        registryId: "C-HIDDEN-MIRRORS",
+        severity: SEVERITY.low,
+        rule: "mirror-in-form",
+        scope: "form",
+        component: [...new Set(inForm.map((c) => c.el.component))].sort().join(", "),
+        match: name === null ? '<input type="hidden">' : `name=${JSON.stringify(name)}`,
+        detail: {
+          name,
+          binding: null,
+          acceptsName: [...new Set(inForm.map((c) => c.acceptsName))].sort().join(", "),
+          controlPassesName: null,
+          controlLine: inForm[0].el.line,
+          sameForm: true,
+        },
+        confidence: "low",
+      });
+      continue;
+    }
+
+    // 3. Not a mirror: a hidden field carrying a value the server supplied.
+    add(findings, {
+      line: el.line,
+      registryId: null,
+      severity: SEVERITY.low,
+      rule: "unregistered-hidden-input",
+      scope: el.form === null ? "no-form" : "form",
+      component: null,
+      match: name === null ? '<input type="hidden">' : `name=${JSON.stringify(name)}`,
+      detail: {
+        name,
+        binding: valueProp?.text ?? null,
+        acceptsName: null,
+        controlPassesName: null,
+        dsControlsInFile: [...new Set(needMirror.map((c) => c.el.component))].sort(),
+      },
+      confidence: "medium",
+    });
+  }
+
+  return {
+    findings,
+    notTransformed,
+    parseErrors: facts.parseErrors,
+    context: {
+      hiddenInputs: hidden.length,
+      controls: [...new Set(controls.map((c) => c.el.component))].sort(),
+    },
+  };
+}
+
+const add = (findings, finding) => findings.push({ gate: null, ...finding });