@decocms/start 2.14.0 → 2.15.0

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

@@ -168,16 +168,116 @@ one imported symbol is a real silent stub (returns `null` / `{}` / `[]`
 alongside stubs (e.g. a `parseCookie` cookie parser, a `fetchSafe`
 wrapper) no longer create noise.
 
-The audit's finding names the exact stub symbols, e.g.
+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: Repoint imports to '@decocms/apps/vtex/...' or
-         'apps/commerce/utils/...'
+    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

package/package.json

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

@@ -239,6 +239,123 @@ 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
@@ -319,16 +436,17 @@ const ruleVtexShimRegression: Rule = {
       const rel = abs.slice(siteDir.length + 1);
       const detail = [...stubsBySim.entries()]
         .map(([s, syms]) => `${s} (${syms.join(", ")})`)
-        .join("; ")
-      ;
+        .join("; ");
+      const fixHintsMeta = fixHintsToMeta(stubsBySim);
       findings.push({
         rule: "vtex-shim-regression",
         severity: "warning",
         file: rel,
         message: `Imports stub-only symbols from ${detail} — runtime is silently stubbed`,
-        fix: "Repoint imports to '@decocms/apps/vtex/...' or 'apps/commerce/utils/...'",
+        fix: buildVtexShimFixMessage(stubsBySim),
         meta: {
           stubsBySim: Object.fromEntries(stubsBySim),
+          ...(Object.keys(fixHintsMeta).length > 0 ? { fixHints: fixHintsMeta } : {}),
         },
       });
     }

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

@@ -404,6 +404,108 @@ describe("rule: vtex-shim-regression", () => {
   });
 });
 
+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", () => {
   it("flags presence of src/types/widgets.ts and counts imports", () => {
     const fs = makeFs({