@assure-one/design-system 1.33.0 → 1.34.0

package/codemods/README.md

@@ -15,7 +15,7 @@ node node_modules/@assure-one/design-system/codemods/run.mjs list
 node node_modules/@assure-one/design-system/codemods/run.mjs CM-15 src --dry --print
 
 # Apply, and write a JSON + Markdown report next to the run
-node node_modules/@assure-one/design-system/codemods/run.mjs CM-05 src --report reports/cm-05
+node node_modules/@assure-one/design-system/codemods/run.mjs CM-02 src --report reports/cm-02
 
 # Everything this project is missing, in program order
 node node_modules/@assure-one/design-system/codemods/run.mjs upgrade --dry
@@ -81,12 +81,19 @@ Commit it with the codemod's changes. It is what makes
   second time (a `--dry` preview is still allowed, with a warning);
 - **prerequisites enforceable** — `requires.codemods` refuses to run before the
   codemods it builds on, and `requires.dsVersion` before the release that ships
-  the replacement API;
+  the replacement API; a codemod whose prerequisite depends on its own state
+  exports a `guard` hook and calls `requireLedger([…])` from it (CM-03 phase 2
+  runs only when the ledger shows phase 1 **and** CM-02);
 - **`upgrade` exact** — a consumer several versions behind gets precisely the
   codemods it is missing, in program order.
 
-Report-only codemods and dry runs never touch it. The consumer scanner reads
-the file and the migration dashboard shows the applied ids
+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 (`filesChanged: 0` —
+a project whose Buttons were all explicit must still be able to satisfy a
+prerequisite on CM-02), and again whenever a later run changed a file. A run
+that changes nothing in a project that already records the codemod adds no
+entry. Report-only codemods and dry runs never touch it. The consumer scanner
+reads the file and the migration dashboard shows the applied ids
 (`migration-status/<app>.json` → `codemodLedger`).
 
 ## Reports
@@ -100,15 +107,65 @@ the list a human has to pick up — spread props, dynamic expressions, conflicti
 
 ## Codemods
 
-| Id    | Class | What it does                                                                                                                        |
-| ----- | ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| CM-14 | X     | hidden-input mirror finder: hidden `<input name>` a consumer added because a design-system control posts nothing                    |
-| CM-15 | X     | DOM-selector finder: consumer code that depends on the internal DOM of design-system components, mapped to registry `C-DOM-*` ids   |
-| CM-16 | X     | `globals.css` analyser: `@source` into the package, duplicate preflight, colliding `@theme` keys, unlayered globals, legacy `var()` |
-| CM-20 | X     | Select sentinel finder: option values standing in for "no value", and the line where each is converted back                         |
+| Id    | Class | What it does                                                                                                                          |
+| ----- | ----- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| CM-02 | A     | Button explicit default size: `size="md"` on every `Button`, `SubmitButton` and `LinkButton` that passes no `size` (pixel-neutral)    |
+| CM-12 | R     | Button `type="submit"` where the intent is evident (inside `<form>` in the same file, no `onClick`); everything else untyped → report |
+| CM-14 | X     | hidden-input mirror finder: hidden `<input name>` a consumer added because a design-system control posts nothing                      |
+| CM-15 | X     | DOM-selector finder: consumer code that depends on the internal DOM of design-system components, mapped to registry `C-DOM-*` ids     |
+| CM-16 | X     | `globals.css` analyser: `@source` into the package, duplicate preflight, colliding `@theme` keys, unlayered globals, legacy `var()`   |
+| CM-20 | X     | Select sentinel finder: option values standing in for "no value", and the line where each is converted back                           |
 
 The remaining ids of plan §29 land with the waves that ship their replacement
-APIs.
+APIs (CM-04 and CM-05 need the Button `intent` and `iconStart`/`iconEnd` API of
+W3-02 and W3-07).
+
+### CM-02 — Button explicit default size
+
+Class A. Every `Button`, `SubmitButton` and `LinkButton` imported from the
+design system (aliased and namespace imports included) that passes no `size`
+gets `size="md"` — the value the component resolves today
+(`defaultVariants.size`, 40px), so nothing moves on screen. It exists because
+a size _meaning_ can only change once no call site depends on the default:
+after CM-02, the D5 size flip (CM-03 phase 2, W9-06) touches nothing a
+consumer did not write down, and 2.0 gate G6 counts exactly this.
+
+The attribute goes after `variant` when there is one (the order the
+applications use) and first otherwise, on its own line when the element's
+attributes are one per line — a Prettier-formatted file stays formatted.
+
+| rule            | Contract   | What happens         |
+| --------------- | ---------- | -------------------- |
+| `implicit-size` | C-BTN-SIZE | `size="md"` is added |
+
+Not touched, and listed under "could not be transformed": an element with a
+spread (`<Button {...props}>`) — the spread may already carry `size`. Not
+touched and not reported: an element with any `size` (the icon sizes, a
+dynamic `size={x}`), a local component called `Button`, test files (the
+scanner that measures G6 counts production files only).
+
+### CM-12 — Button `type="submit"` where evident
+
+Class R. An untyped `Button` renders `<button>` without a `type`, which the
+browser treats as `submit`; 2.0 flips the default to `"button"` (W9-05,
+C-BTN-TYPE, gate G4). CM-12 writes down, before the flip, which Buttons submit
+on purpose — and only where the file itself makes that evident:
+
+| rule              | Action  | Severity | When                                                                         |
+| ----------------- | ------- | -------- | ---------------------------------------------------------------------------- |
+| `submit-in-form`  | applied | medium   | inside a lower-case `<form>` in the same file, no `onClick`, no spread       |
+| `in-form-onclick` | review  | high     | inside a `<form>` with an `onClick` — submit with side effects, or a button? |
+| `in-form-spread`  | review  | high     | inside a `<form>` with `{...props}` — the spread may carry `type`            |
+| `outside-form`    | review  | low      | no `<form>` in this file; rendered inside one elsewhere, it submits today    |
+
+The applied change states what the browser does today, so it is
+behaviour-neutral; it is still in the report because a human has to agree that
+submitting is what the button is for — a "Cancel" matching that shape is a
+bug today, now visible. Nothing is followed across files (a component
+rendered inside a `<form>` by another component is `outside-form`), and a
+capitalised `<Form>` does not count: the react-hook-form / shadcn `Form` is a
+context provider, not a form element. `SubmitButton`, `LinkButton`, a Button
+with any `type`, a Button with `asChild` and test files are not reported.
 
 ### CM-14 — hidden-input mirror finder
 
@@ -271,26 +328,41 @@ export function transform(file, { ts, postcss }) {
 ```
 
 `usesTypeScript` and `usesPostcss` ask the runner to resolve that parser from
-the project and inject it; a codemod never imports one itself.
+the project and inject it; a codemod never imports one itself. A transforming
+codemod edits the source with `lib/jsx-edit.mjs` (`insertAttribute`,
+`applyInsertions`), which keeps the file's own formatting; a finding it
+applied carries `action: "applied"`, one it leaves to a human
+`action: "review"`.
+
+A codemod may also export `guard(context)`, run before any file is read, that
+returns the problems that refuse the run. It receives `{ root, ledger,
+dsVersion, dry, requireLedger }`, where `requireLedger(["CM-02"])` returns one
+problem per prerequisite the ledger lacks. `meta.requires.codemods` is the
+declarative form of the same check; the hook is for a prerequisite that
+depends on the codemod's own state (CM-03 phase 2).
 
 The runner owns everything else: the guards, which files are read, writing
 files and the ledger, the report, and the rule that a class X codemod may not
 change anything.
 
 Fixtures live in `codemods/__test__/<id>/*.snap` — one file per case, holding a
-small project and the expected findings (and, for transforming codemods, the
-expected output):
+small project, the expected findings and, for transforming codemods, the
+expected output of every file that changes:
 
 ```
 === file: src/thing.tsx
 <source>
+=== output: src/thing.tsx
+<the source after the codemod>
 === expect
 { "findings": [ ["src/thing.tsx:12", "C-DOM-03", "class-on-component", "<class token>"] ] }
 ```
 
 `codemods/__test__/harness.mjs` materialises a fixture in a temporary
-directory, runs the codemod **twice** and asserts that the second run finds the
-same things and changes nothing — the idempotency requirement of plan §29.
+directory, runs the codemod **twice** and asserts that the second run changes
+nothing and finds what the first run did not apply — the idempotency
+requirement of plan §29. A file without an `=== output:` section must come out
+unchanged; a fixture with none is report-only and may write no ledger.
 `tests/codemods/*.test.mjs` runs all of it as part of `pnpm test:contracts`.
 
 Fixtures are `.snap` on purpose: Tailwind scans every other repository file for

package/codemods/lib/jsx-edit.mjs

@@ -0,0 +1,59 @@
+/**
+ * Source edits for transforming codemods.
+ *
+ * A transforming codemod (class A or R) changes consumer files that are
+ * formatted by the consumer's Prettier, so an edit must leave the file in the
+ * shape Prettier would produce: a new attribute goes on its own line when the
+ * element's attributes are one per line, and inline when they are inline. The
+ * edits are computed against the parsed tree and applied to the original text
+ * from the end backwards, so nothing else in the file moves.
+ *
+ * As everywhere in `codemods/lib`, the TypeScript module is passed in.
+ */
+
+const isWhitespace = (text) => /^\s*$/.test(text);
+
+/**
+ * The edit that inserts `text` (e.g. `size="md"`) as an attribute of the JSX
+ * opening or self-closing element `opening`.
+ *
+ * The attribute goes right after the attribute named `after` when the element
+ * has one, otherwise first. The separator copies the whitespace the element
+ * already uses before that position (a newline plus the indentation for
+ * one-attribute-per-line elements, a space otherwise).
+ *
+ * @returns {{ pos: number, text: string }}
+ */
+export function insertAttribute(ts, sf, opening, text, { after = null } = {}) {
+  const source = sf.text;
+  const attrs = opening.attributes.properties;
+  const attributesStart = opening.attributes.pos;
+  const separatorBefore = (index) => {
+    const from = index === 0 ? attributesStart : attrs[index - 1].getEnd();
+    const gap = source.slice(from, attrs[index].getStart(sf));
+    return gap && isWhitespace(gap) ? gap : " ";
+  };
+
+  if (after) {
+    const index = attrs.findIndex(
+      (attr) => ts.isJsxAttribute(attr) && attr.name.getText(sf) === after,
+    );
+    if (index >= 0) {
+      return { pos: attrs[index].getEnd(), text: `${separatorBefore(index)}${text}` };
+    }
+  }
+  const separator = attrs.length ? separatorBefore(0) : " ";
+  return { pos: attributesStart, text: `${separator}${text}` };
+}
+
+/** `source` with every `{ pos, text }` insertion applied. */
+export function applyInsertions(source, edits) {
+  let out = source;
+  for (const edit of [...edits].sort((a, b) => b.pos - a.pos)) {
+    out = `${out.slice(0, edit.pos)}${edit.text}${out.slice(edit.pos)}`;
+  }
+  return out;
+}
+
+/** The opening element of a JSX element node (a self-closing one is its own). */
+export const openingOf = (ts, node) => (ts.isJsxElement(node) ? node.openingElement : node);

package/codemods/lib/ledger.mjs

@@ -56,9 +56,25 @@ export function recordApplied(root, { id, appliedAt, dsVersion, filesChanged })
   return { schema: LEDGER_SCHEMA, applied };
 }
 
+/**
+ * The problems that stop codemod `id` while the codemods in `ids` are not in
+ * the ledger — one line per missing prerequisite, `[]` when all are there.
+ *
+ * `meta.requires.codemods` is the declarative form and goes through here. A
+ * codemod whose prerequisite depends on its own state calls it from its
+ * `guard` hook instead: CM-03 phase 2 runs only when the ledger shows phase 1
+ * and CM-02 (`requireLedger(["CM-02"])`, plan §29).
+ */
+export function requireLedger(ledger, ids, { id = "This codemod" } = {}) {
+  const applied = appliedIds(ledger);
+  return ids
+    .filter((required) => !applied.has(required))
+    .map((required) => `${id} needs ${required} to be applied first (not in ${LEDGER_FILE}).`);
+}
+
 /**
  * Why `meta` may not be applied to a project with this ledger and installed
- * DS version, or `null`. Checked before any file is read.
+ * DS version, or `[]`. Checked before any file is read.
  */
 export function guardProblems(meta, ledger, dsVersion, compareVersions) {
   const problems = [];
@@ -69,11 +85,7 @@ export function guardProblems(meta, ledger, dsVersion, compareVersions) {
       `${meta.id} is a one-shot codemod and the ledger shows it was already applied${when ? ` (${when})` : ""}.`,
     );
   }
-  for (const required of meta.requires?.codemods ?? []) {
-    if (!ids.has(required)) {
-      problems.push(`${meta.id} needs ${required} to be applied first (not in ${LEDGER_FILE}).`);
-    }
-  }
+  problems.push(...requireLedger(ledger, meta.requires?.codemods ?? [], { id: meta.id }));
   const minimum = meta.requires?.dsVersion;
   if (minimum && compareVersions(dsVersion, minimum) < 0) {
     problems.push(

package/codemods/lib/registry.mjs

@@ -3,6 +3,8 @@
  * codemods listed here can be run by id; the sequence is the plan's.
  */
 export const CODEMODS = [
+  { id: "CM-02", module: "../transforms/cm-02-button-explicit-size.mjs" },
+  { id: "CM-12", module: "../transforms/cm-12-button-type-submit.mjs" },
   { id: "CM-14", module: "../transforms/cm-14-hidden-mirrors.mjs" },
   { id: "CM-15", module: "../transforms/cm-15-dom-selectors.mjs" },
   { id: "CM-16", module: "../transforms/cm-16-globals-css.mjs" },

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,
+  };
+}