@decocms/start 2.13.0 → 2.15.0

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

@@ -159,18 +159,144 @@ opt-in and tested.
 Older versions of the migration script's `phase-cleanup` had a bug where
 it actively rewrote valid `@decocms/apps/vtex/utils/*` and
 `@decocms/apps/vtex/client` imports back to the dead `~/lib/vtex-*` shims.
-Confirm your loaders import direct from `@decocms/apps`:
+
+The post-cleanup audit now classifies **per-symbol**: it reads each
+`~/lib/vtex-*` shim file, labels every named export as `stub`,
+`type-only`, or `functional`, and only flags an import when at least
+one imported symbol is a real silent stub (returns `null` / `{}` / `[]`
+/ identity-cast / unconditional throw). Functional helpers shipped
+alongside stubs (e.g. a `parseCookie` cookie parser, a `fetchSafe`
+wrapper) no longer create noise.
+
+The audit's finding names the exact stub symbols **and emits per-symbol
+fix guidance**, e.g.
+
+```
+[WARNING] src/loaders/search/x.ts — Imports stub-only symbols from
+  vtex-transform (toProduct); vtex-segment (getSegmentFromBag) —
+  runtime is silently stubbed
+    fix: toProduct → @decocms/apps/vtex/utils/transform (1:1 import swap)
+         — canonical signature is `toProduct(product, sku, level, options)`;
+         1-arg call sites need to expand args first | getSegmentFromBag →
+         call-site refactor: read cookies via `request.headers.get('cookie')`
+         then call `buildSegmentFromCookies()` from
+         '@decocms/apps/vtex/utils/segment'.
+```
+
+JSON consumers can read structured guidance from `meta.fixHints`:
+
+```json
+{
+  "rule": "vtex-shim-regression",
+  "meta": {
+    "stubsBySim": { "vtex-transform": ["toProduct"], "vtex-segment": ["getSegmentFromBag"] },
+    "fixHints": {
+      "toProduct": { "kind": "swap", "canonical": "@decocms/apps/vtex/utils/transform", "note": "..." },
+      "getSegmentFromBag": { "kind": "refactor", "note": "..." }
+    }
+  }
+}
+```
+
+### Canonical replacement table
+
+| Stub symbol | Kind | Canonical / fix |
+|---|---|---|
+| `toProduct` | swap | `@decocms/apps/vtex/utils/transform.toProduct` — note canonical signature is `(product, sku, level, options)`; 1-arg call sites need to expand args |
+| `withSegmentCookie` | swap | `@decocms/apps/vtex/utils/segment.withSegmentCookie` — note canonical signature is `(segment, headers?)` |
+| `getSegmentFromBag` | refactor | read cookies via `request.headers.get('cookie')`, then `buildSegmentFromCookies()` from `@decocms/apps/vtex/utils/segment` |
+| `getISCookiesFromBag` | refactor | extract IS cookies from `request.headers.get('cookie')` directly — no canonical helper, the bag-based mechanism doesn't exist on TanStack Start |
+
+Symbols not in the table get the generic guidance ("repoint to
+`@decocms/apps/vtex/...` or `apps/commerce/utils/...`") — when you find
+a new one worth pinning down, add it to `STUB_FIX_HINTS` in
+[`scripts/migrate/post-cleanup/rules.ts`](https://github.com/decocms/deco-start/blob/main/scripts/migrate/post-cleanup/rules.ts).
+
+### Recipe: expanding 1-arg `toProduct(p)` call sites
+
+Two real-world patterns surface, requiring different fixes:
+
+**Pattern A — call site already passes 4 args under `as any`** (e.g.
+`smartShelfForYou.ts` on casaevideo): the dev wrote the call for
+canonical, the import pointed at the stub. Fix is **import-only**:
+
+```diff
+-import { toProduct } from "~/lib/vtex-transform";
++import { toProduct } from "@decocms/apps/vtex/utils/transform";
+
+ const normalizedProducts = rawProducts.data.map((p: VTEXProduct) =>
+   (toProduct as any)(p, p.items?.[0], 0, {
+     baseUrl: baseURL,
+     priceCurrency: "BRL",
+   }),
+ );
+```
+
+The `as any` cast may stay if local `~/types/vtex.Product` and
+canonical `LegacyProductVTEX | ProductVTEX` differ structurally — that's
+a separate refactor.
+
+**Pattern B — call site uses true 1-arg form** (e.g.
+`intelligenseSearch.ts` on casaevideo): the dev relied on the stub's
+identity-cast behaviour. Fix is to **expand the call** mirroring the
+canonical pattern in
+[`apps-start/vtex/loaders/autocomplete.ts`](https://github.com/decocms/apps-start/blob/main/vtex/loaders/autocomplete.ts):
+
+```diff
+-import { toProduct } from "~/lib/vtex-transform";
++import { pickSku, toProduct } from "@decocms/apps/vtex/utils/transform";
+
+ const baseURL = new URL(req.url).origin;
+ return {
+   searches,
+-  products: (products ?? []).map((p) => toProduct(p)).slice(0, count),
++  products: (products ?? []).slice(0, count).map((p: any) => {
++    const sku = pickSku(p);
++    return toProduct(p, sku, 0, { baseUrl: baseURL, priceCurrency: "BRL" });
++  }),
+ };
+```
+
+`pickSku` handles the IS-shape SKU selection; without it, downstream
+fields like `productID`, `gtin`, `additionalProperty[]` come back
+empty.
+
+**Pattern C — keep the stub deliberately**: rare, but valid when the
+upstream API already returns canonical `Product[]` shape and the call
+is purely a type-narrowing cast. Replace with a typed cast at the
+boundary instead of importing a stub:
+
+```diff
+-import { toProduct } from "~/lib/vtex-transform";
++import type { Product } from "@decocms/apps/commerce/types";
+
+-products: (products ?? []).map((p) => toProduct(p)).slice(0, count),
++products: ((products ?? []) as Product[]).slice(0, count),
+```
+
+This silences the audit (the stub import is gone) without changing
+behaviour. Only do this if you've **verified** the upstream payload is
+already schema.org-shaped.
+
+Manual sweep (still useful if you don't have the audit handy):
 
 ```bash
 rg "from ['\"]~/lib/vtex-" src/
 # Expected: 0 hits (or only site-specific reasons you can articulate)
 ```
 
-If you see hits, update the imports to point at `@decocms/apps/vtex/...`
-directly (or the corresponding `commerce/utils/*` if it's a generic
-utility). Your runtime behavior gets MUCH better — segment cookies, IS
-cookies, VTEX session auth all start working again instead of being
-silently stubbed to `{}` / `null`.
+When you see real findings, update the imports to point at
+`@decocms/apps/vtex/...` directly (or the corresponding
+`commerce/utils/*` if it's a generic utility). Your runtime behavior
+gets MUCH better — segment cookies, IS cookies, VTEX session auth all
+start working again instead of being silently stubbed to `{}` / `null`.
+
+**Note on `--fix`**: this rule is intentionally detect-only. Repointing
+imports requires a per-symbol map to canonical apps/start exports
+(e.g. `getSegmentFromBag` → `@decocms/apps/vtex/utils/segment`), which
+the framework doesn't ship yet. Detect-only is still strictly more
+useful than nothing — the precision means each finding maps to exactly
+one PR's worth of mechanical work.
 
 ## 6. Drop `src/types/widgets.ts` — framework owns it
 

package/CLAUDE.md

@@ -117,7 +117,7 @@ Schema is composed at runtime: `generate-schema.ts` produces section schemas, `c
 
 ## Migration Guide
 
-Detailed migration playbook from Fresh/Preact/Deno to TanStack Start/React/Workers is available at `.cursor/skills/deco-to-tanstack-migration/`. Covers:
+Detailed migration playbook from Fresh/Preact/Deno to TanStack Start/React/Workers is available at `.agents/skills/deco-to-tanstack-migration/` (the canonical location — also surfaced as a Cursor skill via the `.agents/` skills root). Covers:
 
 - Import rewrites (Preact → React, @preact/signals → @tanstack/store)
 - Deco framework elimination (@deco/deco/*, $fresh/*)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.13.0",
+  "version": "2.15.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

@@ -9,6 +9,7 @@
  * Rules are intentionally read-only here — `--fix` is a follow-up.
  */
 
+import { classifyShimExports, type ExportClass } from "./shim-classify";
 import type { Finding, FixAction, FsWriter, Rule, RuleContext } from "./types";
 
 const SRC_GLOB_EXCLUDES = ["node_modules", "dist", ".wrangler", ".vite", ".tanstack", "build"];
@@ -238,27 +239,215 @@ const ruleSiteLocalGlobals: Rule = {
 /* Rule 5 — `~/lib/vtex-*` shim regression                             */
 /* ------------------------------------------------------------------ */
 
+/**
+ * Per-symbol guidance for the canonical replacement of each known
+ * shim stub. Used by the `vtex-shim-regression` rule to compose
+ * actionable `fix:` messages instead of the generic "Repoint imports"
+ * fallback.
+ *
+ * Kept as data (not code) so the JSON output of the audit can carry
+ * structured fix metadata for downstream tooling (CI dashboards,
+ * follow-up auto-fix rules, etc.).
+ *
+ * Categories:
+ * - `swap`: 1:1 import swap is safe — caller imports the symbol from
+ *   `canonical` instead of the local shim. Note may flag a signature
+ *   gotcha that the caller has to address at the call site.
+ * - `refactor`: a call-site rewrite is required (typically because the
+ *   stub's "bag-based" API has no analog on TanStack Start; the request
+ *   headers are the new source of truth). The note explains the pattern.
+ *
+ * Symbols absent from this table fall back to the generic guidance.
+ * The rule still flags them — only the `fix:` prose changes.
+ */
+export type FixHint =
+  | { kind: "swap"; canonical: string; note?: string }
+  | { kind: "refactor"; note: string };
+
+export const STUB_FIX_HINTS: Record<string, FixHint> = {
+  // src/lib/vtex-transform
+  toProduct: {
+    kind: "swap",
+    canonical: "@decocms/apps/vtex/utils/transform",
+    note:
+      "canonical signature is `toProduct(product, sku, level, options)`; " +
+      "1-arg call sites need to expand args first — see skill § 5",
+  },
+  // src/lib/vtex-segment
+  getSegmentFromBag: {
+    kind: "refactor",
+    note:
+      "read cookies via `request.headers.get('cookie')` then call " +
+      "`buildSegmentFromCookies()` from '@decocms/apps/vtex/utils/segment'. " +
+      "The bag-based lookup mechanism does not exist on TanStack Start.",
+  },
+  withSegmentCookie: {
+    kind: "swap",
+    canonical: "@decocms/apps/vtex/utils/segment",
+    note:
+      "canonical signature is `withSegmentCookie(segment, headers?)`; " +
+      "if you currently pass only headers, also pass a segment object",
+  },
+  // src/lib/vtex-intelligent-search
+  getISCookiesFromBag: {
+    kind: "refactor",
+    note:
+      "extract IS cookies from `request.headers.get('cookie')` directly. " +
+      "The bag-based lookup mechanism does not exist on TanStack Start.",
+  },
+};
+
+/**
+ * Format a single symbol's fix guidance as a one-liner suitable for
+ * the audit's `fix:` field. Returns undefined when the symbol has no
+ * specific entry in `STUB_FIX_HINTS`.
+ */
+export function formatFixHint(symbol: string): string | undefined {
+  const hint = STUB_FIX_HINTS[symbol];
+  if (!hint) return undefined;
+  if (hint.kind === "swap") {
+    const head = `${symbol} → ${hint.canonical} (1:1 import swap)`;
+    return hint.note ? `${head} — ${hint.note}` : head;
+  }
+  return `${symbol} → call-site refactor: ${hint.note}`;
+}
+
+/**
+ * Compose the `fix:` message for a finding from the per-shim stub map.
+ * Splits symbols into "have specific guidance" vs "fall back to generic".
+ * Output joins each piece with ` | ` so the message stays one logical
+ * line even when there are several stubs.
+ */
+export function buildVtexShimFixMessage(stubsBySim: Map<string, string[]>): string {
+  const known: string[] = [];
+  const unknown: string[] = [];
+  for (const syms of stubsBySim.values()) {
+    for (const s of syms) {
+      const hint = formatFixHint(s);
+      if (hint) known.push(hint);
+      else unknown.push(s);
+    }
+  }
+  const parts: string[] = [...known];
+  if (unknown.length > 0) {
+    parts.push(
+      `${unknown.join(", ")} → repoint to '@decocms/apps/vtex/...' or 'apps/commerce/utils/...'`,
+    );
+  }
+  return parts.length > 0
+    ? parts.join(" | ")
+    : "Repoint imports to '@decocms/apps/vtex/...' or 'apps/commerce/utils/...'";
+}
+
+/**
+ * Build the structured `fixHints` payload for `meta` so JSON consumers
+ * (CI dashboards, follow-up tooling) can render their own UI. Each
+ * entry is keyed by symbol; symbols without specific guidance are
+ * omitted (the prose fallback covers them).
+ */
+function fixHintsToMeta(stubsBySim: Map<string, string[]>): Record<string, FixHint> {
+  const out: Record<string, FixHint> = {};
+  for (const syms of stubsBySim.values()) {
+    for (const s of syms) {
+      const hint = STUB_FIX_HINTS[s];
+      if (hint) out[s] = hint;
+    }
+  }
+  return out;
+}
+
+/**
+ * Parse one or more ES `import { a, b as c, type d } from "spec"` blocks
+ * targeting a specific source spec out of a file. Returns the list of
+ * imported names (resolved to their original symbol, ignoring `as`
+ * rebinds), with `import type {…}` and inline `type` modifiers stripped
+ * — those carry no runtime, so the rule treats them as out-of-scope.
+ */
+function namedRuntimeImportsFrom(content: string, spec: string): string[] {
+  const escaped = spec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // `(type\s+)?` captures the entire-import `import type { … }` form.
+  // Per-symbol `type` modifiers inside the braces are stripped below.
+  const re = new RegExp(
+    `import\\s+(type\\s+)?\\{([^}]+)\\}\\s+from\\s+['\"]${escaped}['\"]`,
+    "g",
+  );
+  const out: string[] = [];
+  for (const m of content.matchAll(re)) {
+    if (m[1]) continue; // entire import is type-only
+    for (const raw of m[2].split(",")) {
+      const trimmed = raw.trim();
+      if (!trimmed || trimmed.startsWith("type ")) continue;
+      // `foo as bar` → `foo` (we want the source symbol, not the local alias).
+      const sourceName = trimmed.split(/\s+as\s+/)[0].trim();
+      if (sourceName) out.push(sourceName);
+    }
+  }
+  return out;
+}
+
 const ruleVtexShimRegression: Rule = {
   id: "vtex-shim-regression",
   title: "Imports from ~/lib/vtex-* (silent stub regression)",
   run({ siteDir, fs }: RuleContext): Finding[] {
     const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
     const findings: Finding[] = [];
-    const re = /from\s+['"]~\/lib\/vtex-([A-Za-z0-9-]+)['"]/g;
+
+    // Per-shim classification cache. Each shim file is read at most once
+    // per audit run, even when imported by dozens of consumers.
+    const shimClasses = new Map<string, Map<string, ExportClass>>();
+    function classOf(shim: string, symbol: string): ExportClass {
+      let map = shimClasses.get(shim);
+      if (!map) {
+        const abs = `${siteDir}/src/lib/${shim}.ts`;
+        map = new Map<string, ExportClass>();
+        if (fs.exists(abs)) {
+          for (const ce of classifyShimExports(fs.readText(abs))) {
+            map.set(ce.name, ce.class);
+          }
+        }
+        shimClasses.set(shim, map);
+      }
+      // Unknown symbols (file missing or not exported) default to "stub" —
+      // pessimistic on purpose. If the symbol can't be found locally, the
+      // import is at best dead code, at worst a TS error; either way the
+      // user wants visibility into it. Compile phase catches the TS side.
+      return map.get(symbol) ?? "stub";
+    }
+
+    // Match the bare `from "~/lib/vtex-X"` to know which shims are touched.
+    const fromRe = /from\s+['"]~\/lib\/vtex-([A-Za-z0-9-]+)['"]/g;
     for (const abs of tsFiles) {
       if (abs.includes("/src/lib/")) continue;
       const content = fs.readText(abs);
-      const matches = [...content.matchAll(re)];
-      if (matches.length === 0) continue;
+      const usedShims = new Set<string>(
+        [...content.matchAll(fromRe)].map((m) => `vtex-${m[1]}`),
+      );
+      if (usedShims.size === 0) continue;
+
+      // Per-file: which shim → which stub symbols are imported.
+      const stubsBySim = new Map<string, string[]>();
+      for (const shim of usedShims) {
+        const symbols = namedRuntimeImportsFrom(content, `~/lib/${shim}`);
+        const stubs = symbols.filter((s) => classOf(shim, s) === "stub");
+        if (stubs.length > 0) stubsBySim.set(shim, stubs);
+      }
+      if (stubsBySim.size === 0) continue;
+
       const rel = abs.slice(siteDir.length + 1);
-      const shims = [...new Set(matches.map((m) => `vtex-${m[1]}`))];
+      const detail = [...stubsBySim.entries()]
+        .map(([s, syms]) => `${s} (${syms.join(", ")})`)
+        .join("; ");
+      const fixHintsMeta = fixHintsToMeta(stubsBySim);
       findings.push({
         rule: "vtex-shim-regression",
         severity: "warning",
         file: rel,
-        message: `Imports from dead shim(s): ${shims.join(", ")} — runtime is silently stubbed`,
-        fix: "Repoint imports to '@decocms/apps/vtex/...' or 'apps/commerce/utils/...'",
-        meta: { shims },
+        message: `Imports stub-only symbols from ${detail} — runtime is silently stubbed`,
+        fix: buildVtexShimFixMessage(stubsBySim),
+        meta: {
+          stubsBySim: Object.fromEntries(stubsBySim),
+          ...(Object.keys(fixHintsMeta).length > 0 ? { fixHints: fixHintsMeta } : {}),
+        },
       });
     }
     return findings;

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

@@ -263,14 +263,19 @@ describe("rule: site-local-with-globals", () => {
 });
 
 describe("rule: vtex-shim-regression", () => {
-  it("flags imports from ~/lib/vtex-segment", () => {
+  // Default-pessimistic case: shim file missing → unknown symbols treated
+  // as stubs so audit always surfaces the import. (Compile phase catches
+  // the underlying TS error separately.)
+  it("flags imports when shim file is missing (defensive default)", () => {
     const fs = makeFs({
       "/site/src/sections/Foo.tsx": 'import { getSegment } from "~/lib/vtex-segment";\n',
     });
     const report = runAudit(SITE, fs);
     const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
     expect(r.findings).toHaveLength(1);
-    expect(r.findings[0].meta?.shims).toContain("vtex-segment");
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-segment": ["getSegment"],
+    });
   });
 
   it("does not flag imports from src/lib itself", () => {
@@ -281,6 +286,224 @@ describe("rule: vtex-shim-regression", () => {
     const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
     expect(r.findings).toEqual([]);
   });
+
+  it("does NOT flag when imported symbols are all functional", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-id.ts":
+        "export function parseCookie(s?: string): Record<string,string> {\n" +
+        "  if (!s) return {};\n" +
+        "  return Object.fromEntries(s.split(';').map(c => c.split('=') as [string,string]));\n" +
+        "}\n",
+      "/site/src/actions/x.ts": 'import { parseCookie } from "~/lib/vtex-id";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    // parseCookie has nested-block functional impl → not a stub → no warning.
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags only the stub symbols when import set is mixed", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-segment.ts":
+        "export function getSegmentFromBag(_req?: any): null { return null; }\n" +
+        "export function withSegmentCookie(headers: Headers): Headers {\n" +
+        "  headers.set('x', 'y');\n" +
+        "  return headers;\n" +
+        "}\n",
+      "/site/src/loaders/x.ts":
+        'import { getSegmentFromBag, withSegmentCookie } from "~/lib/vtex-segment";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-segment": ["getSegmentFromBag"],
+    });
+    expect(r.findings[0].message).toContain("getSegmentFromBag");
+    expect(r.findings[0].message).not.toContain("withSegmentCookie");
+  });
+
+  it("flags identity-cast (toProduct) as a stub", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-transform.ts":
+        "export function toProduct(p: any): unknown { return p as unknown; }\n",
+      "/site/src/loaders/search.ts":
+        'import { toProduct } from "~/lib/vtex-transform";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-transform": ["toProduct"],
+    });
+  });
+
+  it("does NOT flag `import type { X }` from a stub-having shim", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-client.ts":
+        "export interface VTEXCommerceStable { account: string; }\n" +
+        "export function stub(): null { return null; }\n",
+      "/site/src/loaders/x.ts":
+        'import type { VTEXCommerceStable } from "~/lib/vtex-client";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    // Type-only imports have no runtime → never a regression.
+    expect(r.findings).toEqual([]);
+  });
+
+  it("ignores per-symbol `type` modifier and only flags runtime imports", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-mixed.ts":
+        "export interface Cfg { a: string; }\n" +
+        "export function stub(): null { return null; }\n" +
+        "export function ok(): boolean { return true; }\n",
+      "/site/src/loaders/x.ts":
+        'import { type Cfg, stub, ok } from "~/lib/vtex-mixed";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-mixed": ["stub"],
+    });
+  });
+
+  it("aggregates findings per file across multiple shims", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-segment.ts":
+        "export function getSegmentFromBag(): null { return null; }\n",
+      "/site/src/lib/vtex-transform.ts":
+        "export function toProduct(p: any): unknown { return p as unknown; }\n",
+      "/site/src/loaders/search.ts":
+        'import { getSegmentFromBag } from "~/lib/vtex-segment";\n' +
+        'import { toProduct } from "~/lib/vtex-transform";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-segment": ["getSegmentFromBag"],
+      "vtex-transform": ["toProduct"],
+    });
+  });
+
+  it("supports `as`-renamed imports (resolves to source name)", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-segment.ts":
+        "export function getSegmentFromBag(): null { return null; }\n",
+      "/site/src/loaders/x.ts":
+        'import { getSegmentFromBag as getSeg } from "~/lib/vtex-segment";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-segment": ["getSegmentFromBag"],
+    });
+  });
+});
+
+describe("rule: vtex-shim-regression — per-symbol fix hints", () => {
+  it("emits 1:1 swap hint for `toProduct`", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-transform.ts":
+        "export function toProduct(p: any): unknown { return p as unknown; }\n",
+      "/site/src/loaders/x.ts":
+        'import { toProduct } from "~/lib/vtex-transform";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    const f = r.findings[0];
+    expect(f.fix).toContain("toProduct → @decocms/apps/vtex/utils/transform");
+    expect(f.fix).toContain("1:1 import swap");
+    expect(f.meta?.fixHints).toEqual({
+      toProduct: {
+        kind: "swap",
+        canonical: "@decocms/apps/vtex/utils/transform",
+        note: expect.stringContaining("canonical signature"),
+      },
+    });
+  });
+
+  it("emits refactor hint for `getSegmentFromBag`", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-segment.ts":
+        "export function getSegmentFromBag(): null { return null; }\n",
+      "/site/src/loaders/x.ts":
+        'import { getSegmentFromBag } from "~/lib/vtex-segment";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    const f = r.findings[0];
+    expect(f.fix).toContain("getSegmentFromBag → call-site refactor");
+    expect(f.fix).toContain("buildSegmentFromCookies");
+    expect(f.meta?.fixHints).toEqual({
+      getSegmentFromBag: {
+        kind: "refactor",
+        note: expect.stringContaining("buildSegmentFromCookies"),
+      },
+    });
+  });
+
+  it("composes hints for files with multiple stubs", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-segment.ts":
+        "export function getSegmentFromBag(): null { return null; }\n",
+      "/site/src/lib/vtex-transform.ts":
+        "export function toProduct(p: any): unknown { return p as unknown; }\n",
+      "/site/src/loaders/x.ts":
+        'import { getSegmentFromBag } from "~/lib/vtex-segment";\n' +
+        'import { toProduct } from "~/lib/vtex-transform";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    const f = r.findings[0];
+    expect(f.fix).toContain("getSegmentFromBag → call-site refactor");
+    expect(f.fix).toContain("toProduct → @decocms/apps/vtex/utils/transform");
+    // Joined with " | " for visual separation.
+    expect(f.fix).toContain(" | ");
+    expect(Object.keys(f.meta?.fixHints as object)).toEqual(
+      expect.arrayContaining(["toProduct", "getSegmentFromBag"]),
+    );
+  });
+
+  it("falls back to generic hint for symbols without entries", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-mystery.ts":
+        "export function unknownStub(): null { return null; }\n",
+      "/site/src/loaders/x.ts":
+        'import { unknownStub } from "~/lib/vtex-mystery";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    const f = r.findings[0];
+    expect(f.fix).toContain("unknownStub → repoint to '@decocms/apps/vtex/...");
+    // No fixHints in meta when no symbols match the table.
+    expect(f.meta?.fixHints).toBeUndefined();
+  });
+
+  it("mixes specific hints and generic fallback in one message", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-transform.ts":
+        "export function toProduct(p: any): unknown { return p as unknown; }\n",
+      "/site/src/lib/vtex-mystery.ts":
+        "export function unknownStub(): null { return null; }\n",
+      "/site/src/loaders/x.ts":
+        'import { toProduct } from "~/lib/vtex-transform";\n' +
+        'import { unknownStub } from "~/lib/vtex-mystery";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    const f = r.findings[0];
+    expect(f.fix).toContain("toProduct → @decocms/apps/vtex/utils/transform");
+    expect(f.fix).toContain("unknownStub → repoint");
+    // Only the known symbol shows up in fixHints.
+    expect(f.meta?.fixHints).toEqual({
+      toProduct: expect.objectContaining({ kind: "swap" }),
+    });
+  });
 });
 
 describe("rule: local-widgets-types", () => {