@decocms/start 2.23.0 → 2.24.0

package/.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -18,8 +18,10 @@ npx -p @decocms/start deco-post-cleanup
 
 # Auto-apply mechanical fixes for the safe rules, then report what's left.
 # Safe rules: dead-lib-shims, dead-runtime-shim, local-widgets-types,
-# vtex-shim-regression (swap subset), obsolete-vite-plugins.
-# Other rules stay detect-only — they require human judgment.
+# vtex-shim-regression (swap subset), obsolete-vite-plugins,
+# local-framework-duplicate (auto-fixable subset of the registry).
+# Other rules — and the warn-only entries of local-framework-duplicate —
+# stay detect-only. They require human judgment.
 npx -p @decocms/start deco-post-cleanup --fix
 
 # Combine for CI: auto-fix safe rules, fail (exit 2) if warnings remain.
@@ -29,14 +31,16 @@ npx -p @decocms/start deco-post-cleanup --fix --strict
 npx -p @decocms/start deco-post-cleanup --json
 ```
 
-The audit covers all 7 rules below and prints the exact file path +
+The audit covers all 9 rules below and prints the exact file path +
 suggested fix for each finding. With `--fix`, the safe rules
 auto-apply: `rm` for dead files, regex-anchored import rewrites for
 shadowed shims (`local-widgets-types`, `dead-runtime-shim`), the swap
-subset of `vtex-shim-regression`, and JS-aware removal of obsolete
-inline plugin literals from `vite.config.ts`. The output explicitly
-tags rules that require manual work as `(0 fixed, manual)`, so you
-always know what's left after auto-fix runs.
+subset of `vtex-shim-regression`, JS-aware removal of obsolete
+inline plugin literals from `vite.config.ts`, and rewrite-imports +
+delete for the auto-fixable subset of `local-framework-duplicate`
+(see § 8). The output explicitly tags rules that require manual work
+as `(0 fixed, manual)`, so you always know what's left after auto-fix
+runs.
 
 Real-world signal: on baggagio, `--fix` produced a byte-identical
 diff to the manual cleanup PR a human had just made (45 files,
@@ -398,7 +402,58 @@ In `--strict` mode any residue exits 2 — wire that into CI once a
 site has finished its HTMX rewrite to prevent regressions sneaking
 back in via copy-paste from a Fresh source.
 
-## 8. Search for orphan `TODO: move into framework` comments
+## 8. Drop site-local copies of framework code (`local-framework-duplicate`)
+
+The audit's `local-framework-duplicate` rule encodes a registry of
+files we expect sites to NOT carry locally because the canonical
+implementation already ships in `@decocms/start`. New entries go in
+`scripts/migrate/post-cleanup/rules.ts → FRAMEWORK_DUPLICATES`.
+
+Two kinds of finding:
+
+| Kind | Auto-fix | Example | What you do |
+|---|---|---|---|
+| **Pure dup** (`safeToAutoFix: true`) | YES | `src/sdk/clx.ts` matches `@decocms/start/sdk/clx` byte-for-byte | `--fix` rewrites every `from "~/sdk/clx"` to `from "@decocms/start/sdk/clx"` and deletes the file. Zero behavior change. |
+| **Partial overlap** (`safeToAutoFix: false`) | NO | `src/sdk/useSendEvent.ts` (typed) overlaps `@decocms/start/sdk/analytics → useSendEvent` (permissive) | The rule emits a `warning` with a `reason` explaining the manual judgement: widen the framework export, accept type loss, or fork on purpose. Human picks. |
+
+### How the rule fires
+
+The site file must match every regex in `contentSignature` before
+the rule treats it as the framework dup. This is conservative on
+purpose — sites that genuinely forked the helper (added platform
+logic, wrapped in something else) are skipped automatically.
+
+### Current registry
+
+| Site path | Canonical | Auto-fix? | Reason / status |
+|---|---|---|---|
+| `src/sdk/clx.ts` | `@decocms/start/sdk/clx` | yes | Identical implementation; baggagio's extra `clsx` alias has zero callers. |
+| `src/sdk/useSendEvent.ts` | `@decocms/start/sdk/analytics` | no | Site copy uses `<E extends AnalyticsEvent>` generic; framework export is permissive. Replace 1:1 = type-safety loss. Either widen the framework first or accept the loss. |
+| `src/matchers/location.ts` | `@decocms/start/matchers/builtins` | no | Framework's `registerBuiltinMatchers()` ships a richer location matcher (`request.cf` first, geo cookies fallback, headers fallback) plus 10 sibling matchers. Adopting changes behaviour — verify country-name lookup parity, swap `setup.ts`'s `customMatchers` entry. |
+
+### Adding a new entry
+
+When you spot a site carrying its own copy of code that lives in
+`@decocms/start`, add an entry to `FRAMEWORK_DUPLICATES`:
+
+```ts
+{
+  id: "<short-stable-id>",
+  sitePath: "src/<path>.ts",
+  canonicalImport: "@decocms/start/<path>",
+  contentSignature: [/<regex 1>/, /<regex 2>/],
+  safeToAutoFix: true | false,
+  reason: "<required when not safeToAutoFix>",
+  description: "<one-liner used in finding message>",
+}
+```
+
+Per **D4** in the migration tooling policy, the framework promotion
+itself happens at 3+ sites. This registry is the *enforcement* layer
+once promoted: every other site picks up the convergence
+automatically the next time `deco-post-cleanup --fix` runs.
+
+## 9. Search for orphan `TODO: move into framework` comments
 
 Real sites accumulate `TODO` comments like `// TODO: move into decoVitePlugin
 in next @decocms/start release`. These are roadmap items the framework
@@ -415,7 +470,7 @@ For each hit, decide:
 
 ## Verification checklist
 
-After completing 1-8:
+After completing 1-9:
 
 - [ ] `npm run typecheck` baseline matches pre-cleanup count (no new errors)
 - [ ] `npm run dev` starts and `/`, `/some-pdp/p`, `/s?q=foo` all render

package/MIGRATION_TOOLING_PLAN.md

@@ -1128,6 +1128,97 @@ had no skill coverage. Wave 15-A closes both loops in one PR.
   `useSendEvent`/`clx`/location-matcher imports, `relative()`
   SKU-stripping extension. Sequenced after 15-A merges.
 
+### Wave 15-B-1 (cross-site convergence — `local-framework-duplicate` audit rule) — 🟡 **IN FLIGHT**
+
+First slice of the cross-site-convergence backlog deferred from
+Wave 15-A. Concrete data first (per the user-rule "verify before
+designing"): the `useSendEvent`/`clx`/location-matcher promotion
+turned out to be *not* a "promote site code → framework" exercise.
+The framework already has each helper. The work is **enforcing the
+existing canonical** when sites carry their own copy.
+
+Verified state (2026-05-01 grep against both sites):
+
+| Item | casaevideo | baggagio | Action |
+|---|---|---|---|
+| `src/sdk/clx.ts` | absent (already canonical) | present, identical body + dead `clsx` alias (zero callers) | pure dup → **auto-fix** |
+| `src/sdk/useSendEvent.ts` | absent | present, **stricter** typing (`<E extends AnalyticsEvent>` generic) vs framework's permissive shape | **warn-only** (replacing 1:1 weakens types) |
+| `src/matchers/location.ts` | present, cookie-only subset of framework | absent | **warn-only** (framework's `registerBuiltinMatchers()` is a behavior superset; needs per-site verification of country-name lookup parity) |
+
+So this is exactly *one* mechanically-applicable fix (`clx` in
+baggagio) plus two judgement calls. Hand-applying would be cheap;
+the value is making the audit *enforce* the convergence so the next
+copy-paste regression on any future site gets caught automatically.
+
+**Shipped (one PR against `decocms/deco-start`):**
+
+38. `feat(migrate): local-framework-duplicate audit rule with registry-driven enforcement` 🟡 **WAITING ON CI**
+    - **New rule `local-framework-duplicate`** in
+      `scripts/migrate/post-cleanup/rules.ts` driven by an exported
+      `FRAMEWORK_DUPLICATES` registry. Each entry is `{ id,
+      sitePath, canonicalImport, contentSignature: RegExp[],
+      safeToAutoFix, reason?, description }`. The rule fires only
+      when **every** content-signature regex matches the site file
+      — conservative on purpose so genuinely-forked helpers are
+      skipped.
+    - **Auto-fix path** (when `safeToAutoFix: true`): rewrite all
+      `from "~/<derived>"` importers to `from
+      "<canonicalImport>"` via the existing `rewriteImportSpec`
+      helper, then delete the file. Already-canonical importers
+      are left untouched.
+    - **Warn-only path** (when `safeToAutoFix: false`): rule still
+      fires + populates the finding's `fix:` field with the
+      `reason` so engineers see *why* auto-fix is gated and what
+      they need to verify before manual cleanup.
+    - **Three initial entries** in the registry, mapped 1:1 to the
+      cross-site audit findings:
+      | id | site path | canonical | auto-fix? |
+      |---|---|---|---|
+      | `clx` | `src/sdk/clx.ts` | `@decocms/start/sdk/clx` | **yes** |
+      | `use-send-event` | `src/sdk/useSendEvent.ts` | `@decocms/start/sdk/analytics` | no (typing regression) |
+      | `location-matcher` | `src/matchers/location.ts` | `@decocms/start/matchers/builtins` | no (behavior superset, parity check needed) |
+    - **11 new tests** covering: pure-dup detection, fork detection
+      (signature mismatch → no flag), warn-only entries, severity
+      uniformity (warning for both kinds, so `--strict` gates
+      everything), auto-fix happy-path (delete + rewrite both
+      importers, leave canonical importers alone), warn-only
+      auto-fix is a no-op (does NOT delete partial-overlap files),
+      mixed coexistence (auto-fixable `clx` and warn-only
+      `useSendEvent` in the same tree → only `clx` gets auto-fixed),
+      `supportsAutoFix` flag is true (since rule has `applyFix`).
+    - **CLI help text + `post-migration-cleanup.md` § 8** updated
+      with the new rule's table and the "adding a new entry"
+      section. Old § 8 (orphan TODO comments) renumbered to § 9.
+    - 345 → 353 tests pass, typecheck clean, end-to-end disk smoke
+      against a temp fixture confirmed: 2 importers rewritten + 1
+      file deleted in one `--fix` run.
+    - **Real-site smoke**:
+      - **baggagio**: rule fires twice — `clx.ts` (auto-fixable),
+        `useSendEvent.ts` (warn-only with the typed-generic reason).
+      - **casaevideo**: rule fires once — `location.ts` (warn-only
+        with the `registerBuiltinMatchers()` adoption hint).
+    - **Net**: every future site that copy-pastes any of these three
+      files gets a tight audit finding + auto-fix on the safe one.
+      The registry pattern means adding a 4th cross-site duplicate
+      is a single object literal — no new rule, no new tests
+      scaffolding, no new doc section.
+
+**Still in the cross-site backlog (sequenced behind 15-B-1):**
+
+- **15-B-2** — `useSuggestions` framework helper (new export in
+  `@decocms/start/sdk` typed by `Resolved<T>`, optional Sentry
+  hook). Sites adopt incrementally; once 2+ adopt, add a registry
+  entry pointing the legacy hand-rolled implementations at the
+  canonical via `local-framework-duplicate`.
+- **15-B-3** — `useOffer` factory (D4 candidate; needs design pass
+  for PIX/installment plugin slots).
+- **15-B-4** — `Picture` API unification (breaking; needs a
+  picking-the-winner pass between casaevideo's and baggagio's
+  shapes, plus a codemod for call sites).
+- **15-B-5** — `relative()` SKU-stripping option in
+  `@decocms/apps/commerce/sdk/url`. Apps-side change; sites delete
+  their wrapper.
+
 ### Wave 15+ (htmx cleanup PRs on als + propagation to other sites) — Priority 3 / 4
 
 Each htmx pattern that survives the codemod becomes a per-pattern PR

package/package.json

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

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

@@ -943,6 +943,181 @@ const ruleFrameworkTodos: Rule = {
   },
 };
 
+/* ------------------------------------------------------------------ */
+/* Rule — `local-framework-duplicate` — site-local copy of fwk code   */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Registry of files we expect sites to NOT carry locally because the
+ * canonical implementation already lives in `@decocms/start` (or a
+ * sibling apps package).
+ *
+ * Two flavours:
+ *  - `safeToAutoFix: true`  — site file is a behaviour-equivalent dup
+ *    of the framework export. `--fix` rewrites every `from "~/<path>"`
+ *    importer to `from "<canonicalImport>"` and deletes the file.
+ *  - `safeToAutoFix: false` — site file *overlaps* with framework code
+ *    but isn't a clean drop-in (different typing, partial coverage,
+ *    stricter behaviour, etc.). The rule still flags it so the entry
+ *    surfaces in audits, but never deletes — the `reason` explains why
+ *    a human has to make the call.
+ *
+ * `contentSignature` regexes ALL must match the site file's contents
+ * before the rule fires. They are deliberately specific enough to
+ * avoid catching forks that happen to share a filename but have
+ * diverged.
+ */
+interface FrameworkDuplicate {
+  /** Stable id surfaced in finding meta and CLI/JSON output. */
+  id: string;
+  /** Site-relative path of the duplicated file (e.g. "src/sdk/clx.ts"). */
+  sitePath: string;
+  /** Canonical import to rewrite to. */
+  canonicalImport: string;
+  /**
+   * Heuristic content fingerprint. The site file must match every
+   * regex for the rule to consider it the framework dup.
+   */
+  contentSignature: RegExp[];
+  /**
+   * When true, the rule's `applyFix` will rewrite all importers and
+   * delete the file. When false, the rule emits a warning only —
+   * `reason` explains the manual judgement required.
+   */
+  safeToAutoFix: boolean;
+  /**
+   * Required when `safeToAutoFix: false`. Surfaces in the finding's
+   * `fix:` field so users see *why* the auto-fix is gated.
+   */
+  reason?: string;
+  /**
+   * Human-readable one-liner shown in the finding message and used
+   * to compose the `fix:` hint when auto-fixable.
+   */
+  description: string;
+}
+
+/**
+ * Add an entry here when:
+ *  - 1+ migrated sites carry their own copy of code that already
+ *    exists in `@decocms/start` (or a sibling apps package), AND
+ *  - the canonical version is at least feature-equivalent.
+ *
+ * Per D4 in the migration tooling policy, the framework promotion
+ * itself happens at 3+ sites — but once promoted, this registry is
+ * how we *enforce* convergence on the remaining sites.
+ */
+export const FRAMEWORK_DUPLICATES: FrameworkDuplicate[] = [
+  {
+    id: "clx",
+    sitePath: "src/sdk/clx.ts",
+    canonicalImport: "@decocms/start/sdk/clx",
+    contentSignature: [
+      /export\s+const\s+clx\s*=/,
+      /args\.filter\(Boolean\)\.join/,
+    ],
+    safeToAutoFix: true,
+    description: "src/sdk/clx.ts duplicates @decocms/start/sdk/clx",
+  },
+  {
+    id: "use-send-event",
+    sitePath: "src/sdk/useSendEvent.ts",
+    canonicalImport: "@decocms/start/sdk/analytics",
+    contentSignature: [
+      /export\s+(?:const|function)\s+useSendEvent/,
+      /data-event/,
+      /encodeURIComponent/,
+    ],
+    safeToAutoFix: false,
+    reason:
+      "site copy uses a typed AnalyticsEvent generic; the framework export is permissive. " +
+      "Replacing 1:1 weakens type-safety. Either widen the framework export (preferred), or " +
+      "rewrite call sites to drop the generic. Manual review required.",
+    description:
+      "src/sdk/useSendEvent.ts overlaps with @decocms/start/sdk/analytics → useSendEvent",
+  },
+  {
+    id: "location-matcher",
+    sitePath: "src/matchers/location.ts",
+    canonicalImport: "@decocms/start/matchers/builtins",
+    contentSignature: [
+      /registerMatcher\(\s*['"]website\/matchers\/location\.ts['"]/,
+      /__cf_geo/,
+    ],
+    safeToAutoFix: false,
+    reason:
+      "framework's registerBuiltinMatchers() ships a richer location matcher (request.cf + " +
+      "geo cookies + headers + 10 sibling matchers). Adopting it changes behaviour: " +
+      "verify country-name lookup parity (resolveCountryCode vs site's inline table) and " +
+      "swap setup.ts's customMatchers entry to call registerBuiltinMatchers().",
+    description:
+      "src/matchers/location.ts overlaps with @decocms/start/matchers/builtins → registerBuiltinMatchers()",
+  },
+];
+
+const ruleLocalFrameworkDuplicate: Rule = {
+  id: "local-framework-duplicate",
+  title: "Site-local copy of framework code",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const findings: Finding[] = [];
+    for (const dup of FRAMEWORK_DUPLICATES) {
+      const abs = `${siteDir}/${dup.sitePath}`;
+      if (!fs.exists(abs)) continue;
+      const content = fs.readText(abs);
+      const matchesAll = dup.contentSignature.every((re) => re.test(content));
+      if (!matchesAll) continue;
+
+      const fixMessage = dup.safeToAutoFix
+        ? `Auto-fixable: rewrite \`from "~/${stripExt(dup.sitePath.replace(/^src\//, ""))}"\` → \`from "${dup.canonicalImport}"\` and delete ${dup.sitePath}.`
+        : dup.reason ?? "Manual review required.";
+
+      findings.push({
+        rule: "local-framework-duplicate",
+        severity: "warning",
+        file: dup.sitePath,
+        message: `${dup.description}${dup.safeToAutoFix ? " (pure dup)" : " (partial overlap)"}`,
+        fix: fixMessage,
+        meta: {
+          id: dup.id,
+          canonicalImport: dup.canonicalImport,
+          safeToAutoFix: dup.safeToAutoFix,
+          ...(dup.reason ? { reason: dup.reason } : {}),
+        },
+      });
+    }
+    return findings;
+  },
+  applyFix(ctx, findings, writer): FixAction[] {
+    const actions: FixAction[] = [];
+    for (const f of findings) {
+      const id = f.meta?.id as string | undefined;
+      const safe = f.meta?.safeToAutoFix === true;
+      if (!safe || !id) continue;
+      const dup = FRAMEWORK_DUPLICATES.find((d) => d.id === id);
+      if (!dup) continue;
+
+      const siteImportSpec = `~/${stripExt(dup.sitePath.replace(/^src\//, ""))}`;
+      const updated = rewriteImportSpec(
+        ctx,
+        writer,
+        siteImportSpec,
+        dup.canonicalImport,
+      );
+      writer.deleteFile(`${ctx.siteDir}/${dup.sitePath}`);
+      actions.push({
+        file: dup.sitePath,
+        kind: "rewrite-imports+delete",
+        detail: `rewrote ${updated.length} import(s) "${siteImportSpec}" → "${dup.canonicalImport}" and deleted ${dup.sitePath}`,
+      });
+    }
+    return actions;
+  },
+};
+
+function stripExt(path: string): string {
+  return path.replace(/\.(ts|tsx|js|jsx|mjs)$/, "");
+}
+
 /* ------------------------------------------------------------------ */
 /* Rule 8 — `htmx-residue` — leftover hx-* attrs in migrated src/      */
 /* ------------------------------------------------------------------ */
@@ -1021,6 +1196,7 @@ export const ALL_RULES: Rule[] = [
   ruleVtexShimRegression,
   ruleLocalWidgetsTypes,
   ruleFrameworkTodos,
+  ruleLocalFrameworkDuplicate,
   ruleHtmxResidue,
 ];
 
@@ -1037,5 +1213,6 @@ export const _internals = {
     ruleHtmxResidue,
     ruleLocalWidgetsTypes,
     ruleFrameworkTodos,
+    ruleLocalFrameworkDuplicate,
   },
 };

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

@@ -666,6 +666,7 @@ describe("runAudit — totals", () => {
       [
         "dead-lib-shims",
         "dead-runtime-shim",
+        "local-framework-duplicate",
         "local-widgets-types",
         "obsolete-vite-plugins",
         "vtex-shim-regression",
@@ -1170,3 +1171,193 @@ describe("rule: htmx-residue", () => {
     expect(r.supportsAutoFix).toBe(false);
   });
 });
+
+/* ------------------------------------------------------------------ */
+/* W15-B-1 — local-framework-duplicate rule                            */
+/* ------------------------------------------------------------------ */
+
+describe("rule: local-framework-duplicate", () => {
+  it("flags src/sdk/clx.ts when content matches the framework export (auto-fixable)", () => {
+    const fs = makeFs({
+      "/site/src/sdk/clx.ts":
+        "export const clx = (...args: (string | null | undefined | false)[]) =>\n" +
+        '  args.filter(Boolean).join(" ").replace(/\\s\\s+/g, " ");\n' +
+        "export default clx;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toBe("src/sdk/clx.ts");
+    expect(r.findings[0].message).toContain("pure dup");
+    expect(r.findings[0].meta?.id).toBe("clx");
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(true);
+    expect(r.findings[0].meta?.canonicalImport).toBe("@decocms/start/sdk/clx");
+  });
+
+  it("flags src/sdk/clx.ts when site adds a clsx alias (signature still matches)", () => {
+    const fs = makeFs({
+      "/site/src/sdk/clx.ts":
+        "export const clx = (...args: (string | null | undefined | false)[]) =>\n" +
+        '  args.filter(Boolean).join(" ").replace(/\\s\\s+/g, " ");\n' +
+        "export const clsx = clx;\n" +
+        "export default clx;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.id).toBe("clx");
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(true);
+  });
+
+  it("does NOT flag a clx.ts that has been forked (signature mismatch)", () => {
+    const fs = makeFs({
+      // Realistic fork: uses lodash-style cn from a different package.
+      "/site/src/sdk/clx.ts":
+        'import { cn } from "lodash";\nexport const clx = cn;\nexport default clx;\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags src/sdk/useSendEvent.ts as warn-only (typing regression risk)", () => {
+    const fs = makeFs({
+      "/site/src/sdk/useSendEvent.ts":
+        'import { AnalyticsEvent } from "@decocms/apps/commerce/types";\n' +
+        "export const useSendEvent = <E extends AnalyticsEvent>(\n" +
+        "  { event, on }: { event: E; on: 'click' | 'view' | 'change' },\n" +
+        ") => ({\n" +
+        '  "data-event": encodeURIComponent(JSON.stringify(event)),\n' +
+        '  "data-event-trigger": on,\n' +
+        "});\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toBe("src/sdk/useSendEvent.ts");
+    expect(r.findings[0].message).toContain("partial overlap");
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(false);
+    expect(r.findings[0].fix).toContain("typed AnalyticsEvent generic");
+  });
+
+  it("flags src/matchers/location.ts as warn-only (behaviour-superset opportunity)", () => {
+    const fs = makeFs({
+      "/site/src/matchers/location.ts":
+        'import { registerMatcher } from "@decocms/start/cms";\n' +
+        "export function registerLocationMatcher(): void {\n" +
+        '  registerMatcher("website/matchers/location.ts", (rule, ctx) => {\n' +
+        "    const cookies = ctx.cookies ?? {};\n" +
+        "    const country = cookies.__cf_geo_country ?? '';\n" +
+        "    return Boolean(country);\n" +
+        "  });\n" +
+        "}\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toBe("src/matchers/location.ts");
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(false);
+    expect(r.findings[0].fix).toContain("registerBuiltinMatchers");
+  });
+
+  it("emits zero findings on a clean tree (no duplicates present)", () => {
+    const fs = makeFs({
+      "/site/src/sections/Hello.tsx":
+        'import { clx } from "@decocms/start/sdk/clx";\nexport default () => <div className={clx("a")}>x</div>;\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("emits warning severity for both auto-fixable AND warn-only entries (--strict gates everything)", () => {
+    const fs = makeFs({
+      "/site/src/sdk/clx.ts":
+        'export const clx = (...args: any[]) => args.filter(Boolean).join(" ").replace(/\\s\\s+/g, " ");\n',
+      "/site/src/sdk/useSendEvent.ts":
+        'export const useSendEvent = (e: any) => ({ "data-event": encodeURIComponent(JSON.stringify(e)) });\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    for (const f of r.findings) expect(f.severity).toBe("warning");
+  });
+
+  it("auto-fix rewrites importers using ~/sdk/clx and deletes the file", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/sdk/clx.ts":
+        'export const clx = (...args: any[]) => args.filter(Boolean).join(" ").replace(/\\s\\s+/g, " ");\n',
+      "/site/src/components/A.tsx":
+        'import { clx } from "~/sdk/clx";\nexport default () => clx("x");\n',
+      "/site/src/components/B.tsx":
+        'import { clx } from "~/sdk/clx";\nimport React from "react";\nexport default () => clx("y");\n',
+      "/site/src/components/Unrelated.tsx":
+        'import { clx } from "@decocms/start/sdk/clx";\nexport default () => clx("z");\n',
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.fixes).toBeDefined();
+    expect(r.fixes!.length).toBe(1);
+    expect(r.fixes![0].kind).toBe("rewrite-imports+delete");
+    expect(r.fixes![0].detail).toContain("rewrote 2 import(s)");
+    // File deleted from the in-memory store
+    expect(store["/site/src/sdk/clx.ts"]).toBeUndefined();
+    // Importers rewritten
+    expect(store["/site/src/components/A.tsx"]).toContain(
+      'from "@decocms/start/sdk/clx"',
+    );
+    expect(store["/site/src/components/B.tsx"]).toContain(
+      'from "@decocms/start/sdk/clx"',
+    );
+    // Already-canonical import untouched
+    expect(store["/site/src/components/Unrelated.tsx"]).toContain(
+      'from "@decocms/start/sdk/clx"',
+    );
+    expect(store["/site/src/components/Unrelated.tsx"]).not.toMatch(/~\/sdk\/clx/);
+  });
+
+  it("auto-fix is a no-op for warn-only entries (does NOT delete partial-overlap files)", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/sdk/useSendEvent.ts":
+        'import { AnalyticsEvent } from "@decocms/apps/commerce/types";\n' +
+        "export const useSendEvent = <E extends AnalyticsEvent>() => ({\n" +
+        '  "data-event": encodeURIComponent("x"),\n' +
+        "});\n",
+      "/site/src/matchers/location.ts":
+        'import { registerMatcher } from "@decocms/start/cms";\n' +
+        'registerMatcher("website/matchers/location.ts", () => Boolean(__cf_geo_country));\n',
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.findings.length).toBe(2);
+    // Both fixes are no-ops because safeToAutoFix === false.
+    expect(r.fixes ?? []).toEqual([]);
+    // Files preserved.
+    expect(store["/site/src/sdk/useSendEvent.ts"]).toBeDefined();
+    expect(store["/site/src/matchers/location.ts"]).toBeDefined();
+  });
+
+  it("auto-fix runs only on auto-fixable entries when both kinds coexist", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/sdk/clx.ts":
+        'export const clx = (...args: any[]) => args.filter(Boolean).join(" ").replace(/\\s\\s+/g, " ");\n',
+      "/site/src/sdk/useSendEvent.ts":
+        'export const useSendEvent = (e: any) => ({ "data-event": encodeURIComponent(JSON.stringify(e)) });\n',
+      "/site/src/components/A.tsx":
+        'import { clx } from "~/sdk/clx";\nexport default () => clx("x");\n',
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.findings.length).toBe(2);
+    expect(r.fixes!.length).toBe(1); // only clx auto-fixed
+    expect(r.fixes![0].file).toBe("src/sdk/clx.ts");
+    expect(store["/site/src/sdk/clx.ts"]).toBeUndefined();
+    expect(store["/site/src/sdk/useSendEvent.ts"]).toBeDefined();
+  });
+
+  it("supportsAutoFix is true (the rule has applyFix even though some entries are warn-only)", () => {
+    const fs = makeFs({});
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.supportsAutoFix).toBe(true);
+  });
+});

package/scripts/migrate-post-cleanup.ts

@@ -77,8 +77,10 @@ function showHelp() {
     --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,
-                     vtex-shim-regression swap subset, obsolete-vite-plugins).
-                     Other rules — including htmx-residue — stay detect-only.
+                     vtex-shim-regression swap subset, obsolete-vite-plugins,
+                     local-framework-duplicate auto-fixable subset).
+                     Other rules — including htmx-residue and the warn-only
+                     entries of local-framework-duplicate — 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