@decocms/start 2.19.0 → 2.21.0

package/scripts/migrate/analyzers/htmx-analyze.ts

@@ -0,0 +1,425 @@
+/**
+ * HTMX surface analyzer.
+ *
+ * For sites with significant HTMX usage (the deco-cx Fresh stack
+ * embraced htmx as the interactivity model), the migration to TanStack
+ * Start has to either rewrite or eliminate every `hx-*` attribute.
+ * Per D2 in the migration tooling policy we don't ship a runtime —
+ * everything gets rewritten to React. This analyzer is the first step:
+ * it inventories the `hx-*` surface so the engineer (or the next
+ * codemod wave) knows exactly what shapes are out there before
+ * starting the rewrite.
+ *
+ * The output is a structured `HtmxInventory`: per-category counts,
+ * per-file counts, and three sample call sites per category. The
+ * report is the source of truth for the rewrite recipes documented
+ * in `references/htmx-rewrite.md` (Wave 13-B).
+ *
+ * Categorization is heuristic — we group elements by their **attribute
+ * cluster** rather than by individual attribute, because the rewrite
+ * recipe depends on the cluster (e.g. `hx-post + hx-target + hx-swap`
+ * on a `<form>` is a different rewrite than `hx-get + hx-target` on a
+ * `<button>`). False positives are recoverable: a human reads the
+ * report.
+ *
+ * Wave 13-A. Closes the analysis half of `htmx-foundations`; the
+ * codemods proper land in Wave 14.
+ */
+
+import type { FsAdapter } from "../post-cleanup/types";
+
+const SRC_GLOB_EXCLUDES = [
+	"node_modules",
+	"dist",
+	".wrangler",
+	".vite",
+	".tanstack",
+	"build",
+	".cursor",
+	".agents",
+	"docs",
+];
+
+/* ------------------------------------------------------------------ */
+/* Public types                                                        */
+/* ------------------------------------------------------------------ */
+
+export type HtmxCategory =
+	| "event-handler"
+	| "form-swap"
+	| "click-swap"
+	| "auto-fetch"
+	| "oob-swap"
+	| "boost"
+	| "unmatched";
+
+export interface HtmxOccurrence {
+	category: HtmxCategory;
+	file: string;
+	/** 1-indexed line of the opening tag's start. */
+	line: number;
+	/** Tag name (e.g. "button", "form", "input", "MyComponent"). */
+	tag: string;
+	/** Set of canonical hx-* attribute names found on this element. */
+	attrs: string[];
+}
+
+export interface HtmxFileSummary {
+	file: string;
+	total: number;
+	byCategory: Record<HtmxCategory, number>;
+}
+
+export interface HtmxInventory {
+	totalFiles: number;
+	totalOccurrences: number;
+	byCategory: Record<HtmxCategory, number>;
+	files: HtmxFileSummary[];
+	/** Up to 3 sample occurrences per category (ordered by file path). */
+	samples: Record<HtmxCategory, HtmxOccurrence[]>;
+}
+
+/* ------------------------------------------------------------------ */
+/* Entry point                                                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Analyze every `*.{ts,tsx}` file under `siteDir` and return a
+ * structured inventory of htmx usage. Pure over the injected
+ * `FsAdapter`, so callers (CLI, tests, migration phase wiring) can
+ * substitute in-memory file systems.
+ */
+export function analyzeHtmx(siteDir: string, fs: FsAdapter): HtmxInventory {
+	const files = fs.glob(siteDir, "**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+	const occurrences: HtmxOccurrence[] = [];
+	const fileSummaries: HtmxFileSummary[] = [];
+
+	for (const abs of files) {
+		const rel = abs.startsWith(`${siteDir}/`)
+			? abs.slice(siteDir.length + 1)
+			: abs;
+		const content = fs.readText(abs);
+		const fileOccurrences = analyzeFile(rel, content);
+		if (fileOccurrences.length === 0) continue;
+		const summary: HtmxFileSummary = {
+			file: rel,
+			total: fileOccurrences.length,
+			byCategory: emptyCategoryRecord(),
+		};
+		for (const occ of fileOccurrences) {
+			summary.byCategory[occ.category]++;
+		}
+		fileSummaries.push(summary);
+		occurrences.push(...fileOccurrences);
+	}
+
+	const byCategory = emptyCategoryRecord();
+	for (const occ of occurrences) byCategory[occ.category]++;
+
+	const samples = emptyCategorySamples();
+	for (const occ of occurrences) {
+		const bucket = samples[occ.category];
+		if (bucket.length < 3) bucket.push(occ);
+	}
+
+	// Order files by total descending so the "biggest offenders" land
+	// at the top of the report — that's the order an engineer wants to
+	// chip away at the surface in.
+	fileSummaries.sort((a, b) => b.total - a.total || a.file.localeCompare(b.file));
+
+	return {
+		totalFiles: fileSummaries.length,
+		totalOccurrences: occurrences.length,
+		byCategory,
+		files: fileSummaries,
+		samples,
+	};
+}
+
+function emptyCategoryRecord(): Record<HtmxCategory, number> {
+	return {
+		"event-handler": 0,
+		"form-swap": 0,
+		"click-swap": 0,
+		"auto-fetch": 0,
+		"oob-swap": 0,
+		boost: 0,
+		unmatched: 0,
+	};
+}
+
+function emptyCategorySamples(): Record<HtmxCategory, HtmxOccurrence[]> {
+	return {
+		"event-handler": [],
+		"form-swap": [],
+		"click-swap": [],
+		"auto-fetch": [],
+		"oob-swap": [],
+		boost: [],
+		unmatched: [],
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Per-file analysis                                                   */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Parse a single source file and extract one occurrence per JSX
+ * opening-tag that carries any `hx-*` attribute. Exported so tests
+ * can exercise the parser without needing an FsAdapter.
+ */
+export function analyzeFile(file: string, content: string): HtmxOccurrence[] {
+	const occurrences: HtmxOccurrence[] = [];
+	const seenTagStarts = new Set<number>();
+
+	// Anchored on the attribute name only (not the value), so JSX
+	// expression slots in the value (`hx-post={useSection({...})}`)
+	// don't trip the regex up.
+	const HX_ATTR_RE = /\bhx-([a-z]+(?:-[a-z]+)*(?::[A-Za-z]+)?)\b/g;
+
+	for (const m of content.matchAll(HX_ATTR_RE)) {
+		const attrIdx = m.index;
+		if (attrIdx === undefined) continue;
+		const tagOpen = findEnclosingTagOpen(content, attrIdx);
+		if (tagOpen < 0) continue;
+		if (seenTagStarts.has(tagOpen)) continue;
+		const tagClose = findOpeningTagClose(content, tagOpen);
+		if (tagClose < 0) continue;
+		seenTagStarts.add(tagOpen);
+
+		const tagSpan = content.slice(tagOpen, tagClose + 1);
+		const tag = extractTagName(tagSpan);
+		const attrs = collectHxAttrs(tagSpan);
+		const line = lineNumberAt(content, tagOpen);
+		const category = classify(tag, attrs);
+
+		occurrences.push({
+			category,
+			file,
+			line,
+			tag,
+			attrs,
+		});
+	}
+
+	return occurrences;
+}
+
+/**
+ * Walk backwards from `attrIdx` to the most recent `<` that starts an
+ * opening tag (`<TagName`). Returns the index of that `<`, or -1 if
+ * no plausible tag start is found before the start of the file.
+ *
+ * "Plausible tag start" = `<` followed by a letter or `_`, where the
+ * `<` is not part of a `</` (closing tag), `<<` (operator), or
+ * preceded by an operand that would make it a comparison.
+ */
+function findEnclosingTagOpen(content: string, attrIdx: number): number {
+	for (let i = attrIdx - 1; i >= 0; i--) {
+		if (content[i] !== "<") continue;
+		// Closing tag — `</foo>` — wouldn't carry attributes.
+		if (content[i + 1] === "/") continue;
+		// Comparison / shift operator — left side is a non-tag char.
+		const next = content[i + 1];
+		if (!/[A-Za-z_]/.test(next ?? "")) continue;
+		// Be slightly defensive: if the character right before `<` is a
+		// closing-paren or another `>`, we're definitely in JSX. If it's
+		// an alpha char or `]`, this could be `a < b` — but `a < b` is
+		// followed by an *expression*, not a tag-name + space + `hx-…`,
+		// so the regex hit at attrIdx would be far away. Don't bother
+		// disambiguating; just return the candidate.
+		return i;
+	}
+	return -1;
+}
+
+/**
+ * From the `<` at `tagOpen`, walk forward to find the index of the
+ * `>` that closes the *opening tag* (not the close tag of the same
+ * element). Skips strings (single-, double-, backtick-quoted) and
+ * tracks balanced `{...}` expression slots so JSX expressions in
+ * attributes (`hx-post={useSection({...})}`) don't mislead us.
+ */
+function findOpeningTagClose(content: string, tagOpen: number): number {
+	let i = tagOpen + 1;
+	const n = content.length;
+	while (i < n) {
+		const ch = content[i];
+		if (ch === '"' || ch === "'") {
+			i = skipStringQuote(content, i, ch);
+			continue;
+		}
+		if (ch === "`") {
+			i = skipTemplateLiteral(content, i);
+			continue;
+		}
+		if (ch === "{") {
+			i = skipBraceBalanced(content, i);
+			continue;
+		}
+		if (ch === "/" && content[i + 1] === ">") return i + 1;
+		if (ch === ">") return i;
+		i++;
+	}
+	return -1;
+}
+
+function skipStringQuote(content: string, start: number, quote: string): number {
+	let i = start + 1;
+	const n = content.length;
+	while (i < n) {
+		if (content[i] === "\\") {
+			i += 2;
+			continue;
+		}
+		if (content[i] === quote) return i + 1;
+		i++;
+	}
+	return n;
+}
+
+function skipTemplateLiteral(content: string, start: number): number {
+	let i = start + 1;
+	const n = content.length;
+	while (i < n) {
+		if (content[i] === "\\") {
+			i += 2;
+			continue;
+		}
+		if (content[i] === "`") return i + 1;
+		if (content[i] === "$" && content[i + 1] === "{") {
+			i = skipBraceBalanced(content, i + 1);
+			continue;
+		}
+		i++;
+	}
+	return n;
+}
+
+function skipBraceBalanced(content: string, openIdx: number): number {
+	let i = openIdx + 1;
+	let depth = 1;
+	const n = content.length;
+	while (i < n && depth > 0) {
+		const ch = content[i];
+		if (ch === '"' || ch === "'") {
+			i = skipStringQuote(content, i, ch);
+			continue;
+		}
+		if (ch === "`") {
+			i = skipTemplateLiteral(content, i);
+			continue;
+		}
+		if (ch === "{") {
+			depth++;
+			i++;
+			continue;
+		}
+		if (ch === "}") {
+			depth--;
+			i++;
+			continue;
+		}
+		i++;
+	}
+	return i;
+}
+
+function extractTagName(tagSpan: string): string {
+	// tagSpan starts with `<`. The tag name is /[A-Za-z_][\w.-]*/ until
+	// whitespace, `/`, or `>`.
+	const m = /^<([A-Za-z_][\w.-]*)/.exec(tagSpan);
+	return m?.[1] ?? "";
+}
+
+function collectHxAttrs(tagSpan: string): string[] {
+	// Strip JSX expression slots so `hx-post={someFn({hx-thing: 1})}`
+	// — which doesn't actually exist in JSX, but defensive — doesn't
+	// inflate attr counts. We match the same name shape as the entry
+	// regex.
+	const seen = new Set<string>();
+	const re = /\bhx-([a-z]+(?:-[a-z]+)*(?::[A-Za-z]+)?)\b/g;
+	for (const m of tagSpan.matchAll(re)) {
+		seen.add(`hx-${m[1]}`);
+	}
+	return [...seen].sort();
+}
+
+function lineNumberAt(content: string, idx: number): number {
+	let line = 1;
+	for (let i = 0; i < idx && i < content.length; i++) {
+		if (content[i] === "\n") line++;
+	}
+	return line;
+}
+
+/* ------------------------------------------------------------------ */
+/* Classification                                                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Bucket an element with attribute set `attrs` into one of the
+ * `HtmxCategory` values. Order is intentional: the more specific
+ * shapes are checked first.
+ *
+ * - **boost**: `hx-boost="true"` is a top-level switch — handled
+ *   first so it doesn't conflate with click-swap/form-swap shapes.
+ * - **oob-swap**: `hx-swap-oob` / `hx-select-oob` is a structural
+ *   pattern that almost never has a clean React equivalent.
+ * - **auto-fetch**: a fetch attribute paired with a `hx-trigger` that
+ *   isn't user-driven (`keyup`, `intersect`, `revealed`, `load`,
+ *   `every:`).
+ * - **form-swap**: `hx-post` (with or without `hx-target`/`hx-swap`)
+ *   on a `<form>`, OR with an explicit `hx-trigger="submit"`.
+ * - **click-swap**: `hx-get` (or `hx-post`) on anything else with
+ *   `hx-target` — the dominant button-driven pattern.
+ * - **event-handler**: `hx-on:*` or `hx-on:click` etc with no
+ *   fetch attr — pure client-side handler that happens to be wired
+ *   via htmx for historical consistency.
+ * - **unmatched**: anything that didn't fit cleanly. Reported as a
+ *   manual-review bucket.
+ */
+export function classify(tag: string, attrs: string[]): HtmxCategory {
+	const has = (name: string) => attrs.includes(name);
+	const hasAny = (re: RegExp) => attrs.some((a) => re.test(a));
+
+	if (has("hx-boost")) return "boost";
+	if (has("hx-swap-oob") || has("hx-select-oob")) return "oob-swap";
+
+	const hasFetch = hasAny(/^hx-(get|post|put|patch|delete)$/);
+	// htmx supports both colon (`hx-on:click`) and dash (`hx-on-click`)
+	// syntax for event handlers; HTML's spec doesn't allow `:` in
+	// attribute names so htmx 2.x canonicalised the dash form. Match
+	// both. The dash form is followed by an event name (`click`,
+	// `htmx-config-request`, etc.), the colon form by `:event`.
+	const hasOn = hasAny(/^hx-on(?:[:-]|$)/);
+	const hasTarget = has("hx-target");
+	const triggerIsAutoLike =
+		// We don't have the value of the trigger here — just whether
+		// the attribute exists. The dominant non-form pattern *with*
+		// hx-trigger is "keyup changed delay:Xms" or "intersect".
+		// Without value access, we infer "auto-fetch" by elimination:
+		// fetch + hx-trigger + non-form. Form-submit explicit triggers
+		// are caught by the form-swap branch via `tag === "form"`.
+		has("hx-trigger");
+
+	if (hasFetch) {
+		// `<form>` element — form-swap (regardless of trigger).
+		if (tag === "form") return "form-swap";
+		// `<input>`, `<textarea>` etc carrying a fetch attribute —
+		// they fire on input event, treat as auto-fetch.
+		if (tag === "input" || tag === "textarea" || tag === "select") {
+			return "auto-fetch";
+		}
+		// Non-form / non-input element with fetch + auto-trigger →
+		// auto-fetch (could be `<div hx-trigger="intersect" hx-get>`).
+		if (triggerIsAutoLike && !hasTarget) return "auto-fetch";
+		// Default for the dominant button-driven pattern.
+		return "click-swap";
+	}
+
+	if (hasOn) return "event-handler";
+
+	return "unmatched";
+}

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

package/scripts/migrate-post-cleanup.ts

@@ -76,8 +76,9 @@ function showHelp() {
   Options:
     --source <dir>   Site directory to audit (default: .)
     --fix            Auto-apply mechanical fixes for the safe rules
-                     (dead-lib-shims, dead-runtime-shim, local-widgets-types).
-                     Other rules still detect-only.
+                     (dead-lib-shims, dead-runtime-shim, local-widgets-types,
+                     vtex-shim-regression swap subset, obsolete-vite-plugins).
+                     Other rules — including htmx-residue — stay detect-only.
     --json           Emit machine-readable JSON instead of pretty text
     --strict         Exit code 2 if any warning-severity findings exist
     --help, -h       Show this help