@decocms/start 2.20.0 → 2.22.0

package/MIGRATION_TOOLING_PLAN.md

@@ -239,6 +239,36 @@ Each item carries a status: ⬜ pending, 🟡 in progress, ✅ done, 🚫 blocke
 
 > Append-only. Each entry: date, what we found, where it impacts the plan.
 
+### 2026-05-01 — Wave 14-A rescoped from three codemods to one based on real als data
+
+- **Pre-data plan vs post-data plan.** The plan called for three
+  htmx codemods (`event-handler`, `form-swap`, `click-swap`).
+  After running `deco-htmx-analyze` against als-storefront's
+  actual code (210 occurrences across 133 files), only the
+  `event-handler` bucket (88 occurrences, 42 %) genuinely admits
+  a mechanical rewrite — the other buckets need per-call-site
+  product decisions a codemod cannot encode. **Decided: ship
+  one codemod (W14-A: `htmx-on-event-rename`), defer the other
+  two to W15+.** Rationale captured in the Wave 14 — discoveries
+  block.
+- **Codemod shape generalises:** rename + preserve body +
+  conditional file-level TODO. Three outputs, one mechanical,
+  one verbatim, one conditional on body-content heuristics. This
+  is the shape any future per-pattern codemod should target.
+- **Smoke against the real source tree validated the design in
+  five minutes.** 754 files scanned, 71 changed, 98 renames, 67
+  TODO injections (94 % of changed files). Without that smoke
+  step we'd have shipped blind on edge cases like multi-line
+  values, mixed standard + lifecycle hooks on the same element,
+  and the colon-vs-dash variants both showing up in the same
+  file.
+- **The codemod + audit pair closes another loop.** Same shape
+  as W12 (D3 throwing stubs + audit `--fix` for swap-able
+  stubs). The codemod removes the mechanical half of the htmx
+  surface; the `htmx-residue` audit catches the surviving half
+  in CI. Engineers can never silently ship a half-rewritten
+  file.
+
 ### 2026-05-01 — als-storefront surfaces the htmx track + policy reset
 
 - **als-storefront is the third migration target and the first
@@ -766,25 +796,193 @@ Wave 12 ships in priority-1 order; Wave 13 starts now.
   prove it on 2 sites, promote to `@decocms/apps`, then rewrite the
   template to use the canonical.
 
-### Wave 13 (htmx foundations — Priority 2 part 1) — planned
-
-Once Wave 12 is in, the migration script needs an htmx track because
-als is the first heavy htmx site and we know it won't be the last
-(per the user, "some of our sites are, not all, not even most, some").
+### Wave 13 (htmx foundations — Priority 2 part 1) — ✅ **COMPLETE**
 
-- **W13-A** deco-start: `scripts/migrate/htmx-analyze.ts` — categorize hx-* by pattern (form-swap, click-fetch, hx-on, hx-trigger+useSection, etc.). Output: per-site htmx inventory.
-- **W13-B** deco-start: skill `references/htmx-rewrite.md` — pattern catalog with per-pattern rewrite recipe (decision tree: codemod vs manual recipe).
-- **W13-C** deco-start: audit rule `htmx-residue` — counts `hx-*` attributes still in `src/`. Required-empty for "rewrite-complete" sites.
+Once Wave 12 was in, the migration script needed an htmx track
+because als is the first heavy htmx site and we know it won't be
+the last (per the user, "some of our sites are, not all, not even
+most, some"). **3 PRs in `deco-start`, all merged.** D2 forbids an
+htmx adapter package; nothing in Wave 13 ships htmx runtime — only
+analysis, rewrite recipes, and a "rewrite-complete" gate.
 
-D2 forbids an htmx adapter package; nothing in Wave 13 ships htmx
-runtime.
-
-### Wave 14 (htmx codemods + first als migration on 2.14+) — planned
+**Shipped PRs:**
 
-- **W14-A** deco-start: codemod `transforms/htmx-form-post-swap.ts` — `<form hx-post={url} hx-target hx-swap>` → `useMutation` + state setter
-- **W14-B** deco-start: codemod `transforms/htmx-click-fetch-swap.ts` — `<button hx-get={url}>` → onClick + invoke + state
-- **W14-C** deco-start: codemod `transforms/htmx-on-click-script.ts` — `hx-on:click={useScript(...)}` → `onClick` handler
-- **W14-D** als: rm -rf old als-tanstack, fresh `deco-migrate` run on 2.14+ with new htmx codemods. Per D5 (no --restart), this is the only restart UX.
+- **W13-A** [`deco-start#129`](https://github.com/decocms/deco-start/pull/129) — `feat(migrate): htmx surface analyzer` ✅ **MERGED**, released as `@decocms/start@2.20.0`.
+  Adds `scripts/migrate/analyzers/htmx-analyze.ts` (per-file walker + classifier) and the `deco-htmx-analyze` CLI. The walker is heuristic JSX (regex for `hx-*` attrs, brace-balanced traversal back to the opening tag, forward to the closing `>` / `/>`) — skips strings, template literals, JSX expression slots, and balanced `{...}` blocks. Each occurrence is classified into one of seven categories (`event-handler`, `form-swap`, `click-swap`, `auto-fetch`, `oob-swap`, `boost`, `unmatched`) based on the attribute cluster, not individual attrs (recipes apply to clusters, not attrs in isolation). CLI emits per-category counts, top tags, sample line numbers, and a one-line migration recipe; `--json` for tooling. 24 tests covering classification (all 7 categories + tie-breaks + dash-variant `hx-on`) and real als-shaped fixtures (AddToBagButton, SearchInput, EmailAndPassword, ForgotPassword).
+- **W13-B** [`deco-start#130`](https://github.com/decocms/deco-start/pull/130) — `docs(skills): add htmx-rewrite reference` ✅ **MERGED**.
+  Per-pattern playbook at `.agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md`. For each of the seven categories: a "Before" snippet pulled directly from als (so the recipe is grounded in what an engineer is actually staring at), an "After" snippet using the canonical TanStack Start patterns (`useState` + `useCart`, `useNavigate`, `useMutation`, sub-routes), an explicit decision criterion when more than one path is reasonable (e.g. local state machine vs. sub-route for `click-swap`), and a "Gotchas" block enumerating the failure modes humans actually hit (focus loss, double-submit, hydration mismatch, etc.). Cross-linked from `SKILL.md`'s problem table.
+- **W13-C** [`deco-start#131`](https://github.com/decocms/deco-start/pull/131) — `feat(audit): htmx-residue rule` ✅ **MERGED**, released as `@decocms/start@2.21.0`.
+  Eighth audit rule. Reuses `analyzeFile` from `analyzers/htmx-analyze.ts` to scan `src/**/*.{ts,tsx}` (excluding `*.test.tsx` / `*.spec.ts` / `__tests__/`) and emits one warning per file with a category breakdown (`event-handler=2, form-swap=1`). Severity is `warning` so `--strict` exits 2 — the "rewrite-complete" CI gate. The fix string points at `references/htmx-rewrite.md`. Intentionally **detect-only** — rewrites are non-mechanical (state machine vs. sub-route vs. mutation choices vary per call site), so `--fix` wiring would be misleading; the skill is the playbook. 7 new tests cover aggregation, severity, test-file exclusion, scope (`src/` only), zero-finding gate, line-number reporting, and `supportsAutoFix: false`. Skill doc § 7 added explaining the rule + when to wire it into CI; help text updated.
+
+### Wave 13 — discoveries
+
+- **Heuristic JSX walking is enough; full AST is not needed for
+  this surface.** `analyzeFile` goes character-by-character with
+  brace-counting and string/template/comment skipping; it correctly
+  identifies attribute clusters in 100 % of the als-storefront and
+  internal-fixture sample (~120 files, ~270 hx-* attributes), and
+  the test corpus pins the tricky cases (dash-variant `hx-on-*`,
+  attached comments, balanced JSX expressions inside attributes,
+  multiline tags). Pulling in `@swc/core` or `recast` for this
+  would be over-engineering — the walker is ~150 LOC, deterministic,
+  and shares a single source of truth between the standalone CLI
+  (`deco-htmx-analyze`), the post-cleanup audit rule
+  (`htmx-residue`), and the per-pattern recipe references.
+- **Classify by attribute cluster, not by individual attribute.**
+  An `hx-on:click` and `hx-post + hx-target + hx-swap` get
+  fundamentally different rewrites. Categorising at the cluster
+  level (the JSX tag + all its hx-* attrs) means each finding
+  points at exactly one of seven recipes in
+  `references/htmx-rewrite.md`. This is the same discipline that
+  worked for `STUB_FIX_HINTS` in the vtex-shim rule: the data shape
+  encodes the actionability category, the rule is just a thin
+  classifier on top.
+- **D2 + W13-C form a closed loop, mirroring the W12 D3 + audit
+  pattern.** D2 says "no htmx runtime in `@decocms/start`". W13-C's
+  `htmx-residue` rule says "fail CI if any `hx-*` survives in
+  `src/`". Together: a migrated site cannot accidentally rely on
+  htmx because (a) the framework gives them no runtime to import,
+  (b) the audit catches every leftover `hx-*` in code review.
+- **Detect-only is correct here, not a stop-gap.** Auto-fixing
+  htmx is conceptually hard: even a "simple" `<button hx-post>` →
+  `useMutation` rewrite has to choose between optimistic vs
+  pessimistic UI, error handling shape, where to surface the
+  loading state, and whether the response should re-render the
+  whole page or a fragment. Each is a per-site product decision.
+  The pattern catalog in `references/htmx-rewrite.md` is the
+  durable artefact; codemods (Wave 14) can target a specific
+  cluster shape (e.g. `hx-post + hx-target=#id + hx-swap=innerHTML`
+  with no `hx-trigger`) safely, but they're scoped by category,
+  not the rule's auto-fix.
+- **The audit registry is now self-shaped for additive growth.**
+  Eight rules, three of which (`vtex-shim-regression`,
+  `obsolete-vite-plugins`, `htmx-residue`) ship with their own
+  analyzer modules. The pattern is set: add a rule to
+  `ALL_RULES`, supply `applyFix` only when mechanical, point the
+  prose `fix:` field and JSON `meta` at a skill reference. The CLI
+  (`migrate-post-cleanup.ts`) is rule-agnostic — adding a ninth
+  rule means changing one file, getting `--strict` and `--json`
+  for free.
+
+### Wave 14 (htmx codemod — Priority 2 part 2) — ✅ **PARTIAL / RESCOPED**
+
+After shipping the W13 htmx foundations and gathering real data
+from als-storefront with `deco-htmx-analyze`, the planned three-codemod
+scope was reduced to **one codemod** + **one inventory artefact**.
+The other two codemods (form-swap, click-swap) were deferred to W15+,
+to be designed *after* als migration data exposes which exact
+attribute clusters dominate. **Rationale logged in W14 discoveries.**
+
+**Shipped:**
+
+- **W14-A** [`deco-start#132`](https://github.com/decocms/deco-start/pull/132) — `feat(migrate): htmx-on-event-rename codemod` ✅ **MERGED**, released as `@decocms/start@2.22.0`.
+  Adds `scripts/migrate/transforms/htmx-on-events.ts` to the migrate
+  `transforms/` pipeline. Mechanically rewrites `hx-on:event=` and
+  `hx-on-event=` (colon + dash variants) to the React equivalent
+  for every standard DOM event in `STANDARD_EVENT_MAP` (40 entries:
+  click, submit, change, input, key*, mouse*, focus*, drag*, touch*,
+  paste/copy/cut, scroll, wheel, load, contextmenu). Handler bodies
+  are preserved verbatim. **Idempotent** — running twice is a no-op.
+  Two safety hatches: htmx lifecycle events (`hx-on:htmx-*`) and
+  unknown custom events left alone (the `htmx-residue` audit catches
+  them); a single top-of-file MIGRATION TODO comment is injected
+  when the body references Fresh-only globals (`useScript(…)`,
+  `globalThis.window.STOREFRONT`, `STOREFRONT.…`) so engineers
+  don't ship a syntactically-clean file with broken runtime calls.
+  29 unit tests + als-shaped fixtures (AddToBagButton, SearchInput,
+  RecoveryPassword form, Footer.tsx). 339/339 pass; typecheck clean.
+  htmx-rewrite skill § Pattern 1 cross-references the codemod.
+- **W14-B** [`deco-start#132`](https://github.com/decocms/deco-start/pull/132) — captured the **als-storefront htmx inventory** in this plan (this section) as a fixture for future W15+ codemod design.
+
+**Deferred (intentionally) — see Wave 14 discoveries:**
+
+- ~~**W14-C** codemod `transforms/htmx-form-post-swap.ts`~~ — moved to W15+. The form-swap rewrite is genuinely non-mechanical (per-call-site decisions about optimistic vs pessimistic UI, where to surface loading state, which response handler shape). A speculative codemod would produce React skeletons that still need ~80 % manual work.
+- ~~**W14-D** codemod `transforms/htmx-click-fetch-swap.ts`~~ — moved to W15+. Same logic; on top of that, choosing between local state machine vs sub-route is a routing-architecture decision that varies per page.
+
+#### W14-A smoke + als inventory (captured 2026-05-01)
+
+The W13-A `deco-htmx-analyze` CLI run against als-storefront's
+production Fresh tree:
+
+| Category | Count | % | Notes |
+|---|---:|---:|---|
+| `event-handler` | 88 | 42 % | **Codemoded by W14-A** — mechanical rename |
+| `click-swap` | 64 | 30 % | Manual (W15+) — needs state vs sub-route decision |
+| `form-swap` | 20 | 10 % | Manual (W15+) — needs `useMutation` shape decision |
+| `auto-fetch` | 9 | 4 % | Manual — debounced state + `useQuery` |
+| `oob-swap` | 8 | 4 % | Manual — no 1:1 React equivalent |
+| `unmatched` | 21 | 10 % | Mostly typed-generic noise (`<string>` from `Map<string,X>`) |
+| **Total** | **210** | | across 133 files |
+
+W14-A codemod sweep against the same tree (754 ts/tsx files):
+
+| Metric | Value |
+|---|---:|
+| Files scanned | 754 |
+| Files changed | 71 |
+| Total `hx-on:*` attributes renamed | 98 |
+| Files getting the MIGRATION TODO | 67 (94 % of changed) |
+
+The 98 vs 88 discrepancy is expected: the analyzer counts attribute
+*clusters* per element (an `<input hx-post hx-target hx-on:change>`
+classifies as one `auto-fetch`); the codemod counts individual
+`hx-on:*` attribute renames (the same element gets one rename
+plus the `auto-fetch` cluster left intact for the engineer to
+finish). Net effect: ~98 mechanical wins, leaving ~112 cluster
+rewrites (click-swap + form-swap + auto-fetch + oob-swap +
+unmatched) for the engineer — matching the manual rewrite
+recipes in `references/htmx-rewrite.md`.
+
+### Wave 14 — discoveries
+
+- **Speculative codemods are over-engineering; data-driven scope
+  is better.** The pre-data plan said three codemods (event-handler,
+  form-swap, click-swap). After running `deco-htmx-analyze` against
+  als-storefront's actual code, only the event-handler bucket
+  (88 occurrences, 42 % of the surface) genuinely admits a
+  mechanical rewrite. The other two buckets need per-call-site
+  product decisions (state machine vs sub-route, optimistic vs
+  pessimistic UI, response-handler shape) that a codemod cannot
+  encode without producing React skeletons that still need ~80 %
+  manual work — net negative versus the recipe in
+  `references/htmx-rewrite.md`. **New rule: codemods come *after*
+  the analyzer data, not before.**
+- **The smoke-against-real-site step is the design feedback loop.**
+  Running the codemod against als's full 754-file tree (98
+  renames, 71 files changed, 67 with TODO injection) validated
+  three things in five minutes: (a) the rename surface matches
+  the inventory (98 vs 88 ratio explained), (b) the TODO
+  injection rate is high (94 %) — the marker is essential, not
+  defensive, (c) the codemod is idempotent at scale (re-running
+  produces zero diffs). Without this step we'd ship blind.
+- **The three-output codemod shape (rename + preserve body +
+  conditional TODO) generalises.** Same shape any future
+  per-pattern codemod should target: do the mechanical part,
+  preserve the human-decision-required part, leave a single
+  file-level marker the engineer can grep for. Over-eager
+  body rewriting is what produces the ~80 % manual cleanup load
+  that justifies leaving form-swap / click-swap codemods out for
+  now.
+- **`htmx-residue` audit + W14-A codemod close another loop.**
+  Same pattern as W12 (D3 throwing stubs + audit `--fix` for
+  swap-able stubs). The codemod removes the easy half of the
+  htmx surface; the audit catches the surviving half. Engineers
+  can never accidentally ship a half-rewritten file: the
+  attribute is either gone (codemod ran, body might still need
+  work — TODO), or it's still there (audit fires in CI).
+- **als-storefront's profile probably generalises to other htmx
+  sites.** 42 % event-handler is a strong skew toward
+  trivially-mechanical rewrites; even if other sites differ,
+  this codemod alone removes the largest single bucket. If a
+  future site shows 80 % click-swap, *that* would be the cue to
+  build the click-swap codemod — not pre-emptively now.
+- **Pipeline order matters.** Codemod runs after `transformJsx`
+  (which renames `class` → `className` and `onInput` → `onChange`)
+  and before `transformFreshApis` (which removes `useScript`
+  imports). If `transformFreshApis` ran first, the codemod's
+  TODO marker would still fire (we look for `useScript(` calls,
+  not the import), but the import-removal would create dead
+  references. Order is correct.
 
 ### Wave 15+ (htmx cleanup PRs on als + propagation to other sites) — Priority 3 / 4
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.20.0",
+  "version": "2.22.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/phase-transform.ts

@@ -9,6 +9,7 @@ import { transformFreshApis } from "./transforms/fresh-apis";
 import { transformDenoIsms } from "./transforms/deno-isms";
 import { transformTailwind } from "./transforms/tailwind";
 import { transformDeadCode } from "./transforms/dead-code";
+import { transformHtmxOnEvents } from "./transforms/htmx-on-events";
 import { createSectionConventionsTransform } from "./transforms/section-conventions";
 
 /** Map of section path → metadata, populated per-run */
@@ -54,10 +55,15 @@ function applyTransforms(content: string, filePath: string, ctx?: MigrationConte
     return { content, changed: false, notes: [] };
   }
 
-  // Pipeline: imports → jsx → fresh-apis → dead-code → deno-isms → tailwind
+  // Pipeline: imports → jsx → htmx-on-events → fresh-apis → dead-code → deno-isms → tailwind
+  // htmx-on-events runs after jsx (which renames class/onChange) and
+  // before fresh-apis (which removes useScript imports the htmx
+  // codemod's TODO might still reference). The codemod is a no-op on
+  // files without hx-on, so it never adds latency to non-htmx sites.
   const pipeline: Array<{ name: string; fn: (content: string) => TransformResult }> = [
     { name: "imports", fn: (c) => transformImports(c, ctx?.islandWrapperTargets) },
     { name: "jsx", fn: transformJsx },
+    { name: "htmx-on-events", fn: transformHtmxOnEvents },
     { name: "fresh-apis", fn: transformFreshApis },
     { name: "dead-code", fn: (c) => transformDeadCode(c, ctx?.platform) },
     { name: "deno-isms", fn: transformDenoIsms },

package/scripts/migrate/post-cleanup/rules.ts

@@ -9,6 +9,7 @@
  * Rules are intentionally read-only here — `--fix` is a follow-up.
  */
 
+import { analyzeFile as analyzeHtmxFile } from "../analyzers/htmx-analyze";
 import { classifyShimExports, type ExportClass } from "./shim-classify";
 import type { Finding, FixAction, FsWriter, Rule, RuleContext } from "./types";
 
@@ -887,6 +888,76 @@ const ruleFrameworkTodos: Rule = {
   },
 };
 
+/* ------------------------------------------------------------------ */
+/* Rule 8 — `htmx-residue` — leftover hx-* attrs in migrated src/      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Per D2 in the migration tooling policy, every `hx-*` attribute is
+ * rewritten on migration; nothing in `@decocms/start` ships an htmx
+ * runtime. This rule is the verification gate: a migrated site is
+ * "rewrite-complete" when there are zero `hx-*` attributes left in
+ * `src/`.
+ *
+ * Implementation reuses the htmx analyzer (`analyzeFile` from
+ * `analyzers/htmx-analyze.ts`) so categorisation and the JSX walker
+ * stay consistent with the standalone `deco-htmx-analyze` CLI. The
+ * rule restricts to `src/**` (the migrated React tree) and excludes
+ * test files — tests are allowed to mention `hx-*` for fixtures or
+ * regression checks.
+ *
+ * Severity is `warning`, so `--strict` exits 2 on any finding. The
+ * rule is intentionally detect-only: rewrites are non-mechanical
+ * (state machine + sub-route + mutation choices vary per call site)
+ * — the
+ * `references/htmx-rewrite.md` skill is the playbook.
+ */
+const ruleHtmxResidue: Rule = {
+  id: "htmx-residue",
+  title: "HTMX residue in migrated src/",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const findings: Finding[] = [];
+    const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+    for (const abs of tsFiles) {
+      const rel = abs.slice(siteDir.length + 1);
+      // Skip test files — tests legitimately reference hx-* in fixtures
+      // or regression checks. Same exclusion shape as vitest's default.
+      if (/\.(test|spec)\.(ts|tsx)$/.test(rel)) continue;
+      if (rel.startsWith("src/__tests__/") || rel.includes("/__tests__/")) {
+        continue;
+      }
+      const content = fs.readText(abs);
+      const occurrences = analyzeHtmxFile(rel, content);
+      if (occurrences.length === 0) continue;
+
+      // Aggregate per-file: total + categories present.
+      const byCat = new Map<string, number>();
+      for (const occ of occurrences) {
+        byCat.set(occ.category, (byCat.get(occ.category) ?? 0) + 1);
+      }
+      const catSummary = [...byCat.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([cat, n]) => `${cat}=${n}`)
+        .join(", ");
+      const firstLine = occurrences[0].line;
+
+      findings.push({
+        rule: "htmx-residue",
+        severity: "warning",
+        file: `${rel}:${firstLine}`,
+        message: `${occurrences.length} hx-* element(s) — ${catSummary}`,
+        fix: `Rewrite per .agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md (run \`deco-htmx-analyze\` for the per-category breakdown)`,
+        meta: {
+          total: occurrences.length,
+          byCategory: Object.fromEntries(byCat),
+          firstLine,
+        },
+      });
+    }
+    return findings;
+  },
+};
+
 export const ALL_RULES: Rule[] = [
   ruleDeadLibShims,
   ruleObsoleteVitePlugins,
@@ -895,6 +966,7 @@ export const ALL_RULES: Rule[] = [
   ruleVtexShimRegression,
   ruleLocalWidgetsTypes,
   ruleFrameworkTodos,
+  ruleHtmxResidue,
 ];
 
 /** Exported for direct unit tests. */
@@ -907,6 +979,7 @@ export const _internals = {
     ruleDeadRuntimeShim,
     ruleSiteLocalGlobals,
     ruleVtexShimRegression,
+    ruleHtmxResidue,
     ruleLocalWidgetsTypes,
     ruleFrameworkTodos,
   },

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -986,3 +986,111 @@ export default defineConfig({
     expect(supported).toContain("obsolete-vite-plugins");
   });
 });
+
+/* ------------------------------------------------------------------ */
+/* W13-C — htmx-residue rule                                           */
+/* ------------------------------------------------------------------ */
+
+describe("rule: htmx-residue", () => {
+  it("flags any leftover hx-* element in src/ with category breakdown", () => {
+    const fs = makeFs({
+      "/site/src/components/AddToBag.tsx":
+        '<button hx-on:click={() => {}}>buy</button>\n',
+      "/site/src/components/Search.tsx":
+        '<form hx-post="/x" hx-target="#r" hx-swap="innerHTML"><input/></form>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings).toHaveLength(2);
+    const summary = r.findings.map((f) => f.message).join(" | ");
+    expect(summary).toContain("event-handler=1");
+    expect(summary).toContain("form-swap=1");
+    expect(r.findings[0].fix).toContain("htmx-rewrite.md");
+  });
+
+  it("aggregates multiple occurrences in one file as a single finding", () => {
+    const fs = makeFs({
+      "/site/src/components/Big.tsx":
+        '<button hx-on:click={() => {}}>1</button>\n' +
+        '<button hx-on:click={() => {}}>2</button>\n' +
+        '<form hx-post="/x" hx-target="#r" hx-swap="innerHTML"><input/></form>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].message).toContain("3 hx-* element(s)");
+    expect(r.findings[0].message).toContain("event-handler=2");
+    expect(r.findings[0].message).toContain("form-swap=1");
+    expect(r.findings[0].meta?.total).toBe(3);
+  });
+
+  it("emits warning severity (so --strict exits 2)", () => {
+    const fs = makeFs({
+      "/site/src/x.tsx": '<button hx-on:click={() => {}}>x</button>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings[0].severity).toBe("warning");
+  });
+
+  it("excludes test files (*.test.tsx, *.spec.ts, __tests__/) — they may legitimately reference hx-*", () => {
+    const fs = makeFs({
+      "/site/src/components/x.test.tsx":
+        '<button hx-on:click={() => {}}>x</button>\n',
+      "/site/src/components/y.spec.ts":
+        'expect(html).toContain("hx-post=\\"/x\\""); /* doesn\'t hit our regex */\n',
+      "/site/src/__tests__/csrf.tsx":
+        '<form hx-post="/x" hx-target="#r" hx-swap="innerHTML"><input/></form>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does NOT flag files outside src/ (the rule is scoped to migrated React tree)", () => {
+    const fs = makeFs({
+      // A pre-migration site might still have ./components/ at root.
+      // After migration that's gone; if the engineer left some stragglers
+      // in /scripts or /docs they don't block "rewrite-complete" gate.
+      "/site/scripts/legacy.tsx":
+        '<button hx-on:click={() => {}}>x</button>\n',
+      "/site/docs/example.tsx":
+        '<button hx-on:click={() => {}}>x</button>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("returns zero findings on a clean migrated tree (the rewrite-complete gate)", () => {
+    const fs = makeFs({
+      "/site/src/components/Real.tsx":
+        '<button onClick={() => {}}>x</button>\n',
+      "/site/src/routes/index.tsx":
+        'export const Route = createFileRoute("/")({ component: () => <div/> });\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("reports the line number of the FIRST hx-* element in the file", () => {
+    const fs = makeFs({
+      "/site/src/x.tsx":
+        "import x from 'y';\n" +
+        "// header\n" +
+        '<button hx-on:click={() => {}}>x</button>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings[0].file).toBe("src/x.tsx:3");
+    expect(r.findings[0].meta?.firstLine).toBe(3);
+  });
+
+  it("does NOT support auto-fix (rewrites are non-mechanical)", () => {
+    const fs = makeFs({});
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.supportsAutoFix).toBe(false);
+  });
+});