@assure-one/design-system 1.32.0 → 1.33.0

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 });