feat(audit): htmx-residue rule (W13-C)

[vibe-dex]

Summary

Closes the W13-C item in the migration tooling plan: an eighth
post-migration cleanup rule that flags any leftover hx-*
attribute in a migrated site's src/.

The rule reuses the W13-A analyzer's classifier (analyzeFile from
scripts/migrate/analyzers/htmx-analyze.ts) so categorisation
stays consistent with the standalone deco-htmx-analyze CLI. Each
finding is a per-file warning with a category breakdown — e.g.

[WARNING] src/components/AddToBag.tsx:14 — 1 hx-* element(s) — event-handler=1
  fix: Rewrite per .agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md
       (run `deco-htmx-analyze` for the per-category breakdown)

--strict exits 2 on any finding; this is the "rewrite-complete"
CI gate for any site that came off Fresh+HTMX. Detect-only —
htmx rewrites are non-mechanical (state machine vs. sub-route vs.
mutation choices vary per call site), so adding applyFix would
be misleading; the W13-B references/htmx-rewrite.md skill is the
playbook.

Why detect-only?

D2 forbids any htmx runtime in @decocms/start. This rule is the
enforcement side of D2: the framework gives a migrated site no
htmx runtime to import; the audit catches every leftover hx-*
in code review. Together: a migrated site cannot accidentally
rely on htmx without it being visible.

Tests + smoke

• npx vitest run scripts/migrate/post-cleanup/runner.test.ts —
  60/60 pass, 7 new test cases for the rule covering
  aggregation, severity, test-file exclusion (*.test.tsx,
  *.spec.ts, __tests__/), scope (src/ only — files in
  /scripts/, /docs/ ignored), zero-finding gate (clean tree),
  first-occurrence line-number reporting, and
  supportsAutoFix: false.
• npx vitest run — full deco-start suite 310/310 pass.
• npm run typecheck — clean.
• Smoke against casaevideo-storefront (no htmx) — 0 findings,
  rule registered at position [8].
• Smoke against synthetic fixture — 2 findings, correct
  categorisation, --strict exits 2.

Scope

• New rule ruleHtmxResidue in
  scripts/migrate/post-cleanup/rules.ts.
• Registered in ALL_RULES and _internals.rules for direct test
  access.
• Skill doc § 7 (post-migration-cleanup.md) added.
• CLI help text in scripts/migrate-post-cleanup.ts updated to
  list obsolete-vite-plugins (was already auto-fix in 2.19) and
  call out htmx-residue as detect-only.
• MIGRATION_TOOLING_PLAN.md marks Wave 13 complete (Wave 13-A,
  -B, -C all shipped) and adds a Wave 13 discoveries section.

Test plan

• npx vitest run — 310/310 pass
• npm run typecheck — clean
• Smoke npx tsx scripts/migrate-post-cleanup.ts against
  casaevideo-storefront — 0 findings (expected)
• Smoke against synthetic htmx fixture — 2 findings, both
  categorised, --strict → exit 2
• No linter findings on touched files

Made with Cursor

---

Summary by cubic

Adds a detect-only htmx-residue audit rule that flags leftover hx-* attributes under src/ with a per-file category breakdown. Reuses the Wave 13 analyzer and makes --strict a "rewrite-complete" CI gate; docs and CLI help updated (completes Wave 13 / W13-C).

• New Features

  • Scans src/**/*.{ts,tsx} for hx-*; excludes *.test.tsx, *.spec.ts, and __tests__/, and ignores files outside src/.
  • Aggregates one warning per file with categories: event-handler, form-swap, click-swap, auto-fetch, oob-swap, boost, unmatched.
  • Severity is warning; --strict exits 2. Fix hint points to .agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md. No auto-fix.
  • Help text notes detect-only; post-migration cleanup doc adds an HTMX section; 7 new tests added; full suite passes.

• Migration

  • After finishing HTMX rewrites, enable scripts/migrate-post-cleanup.ts --strict in CI to block regressions.
  • Use deco-htmx-analyze for detailed per-category inventories when triaging larger codebases.

^{Written for commit 208eb25. Summary will update on new commits.}

[github-actions]

🎉 This PR is included in version 2.21.0 🎉

The release is available on:

• v2.21.0
• GitHub release

Your semantic-release bot 📦🚀