@decocms/start 2.14.0 → 2.16.0

package/package.json

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

package/scripts/migrate/templates/lib-utils.test.ts

@@ -89,3 +89,51 @@ describe("selectImportedLibTemplates()", () => {
     }
   });
 });
+
+describe("D3 — generated stubs throw at runtime", () => {
+  // Each stub MUST throw an Error whose message identifies:
+  //  - the stub path so the dev sees it in their stack trace
+  //  - the canonical replacement (so the fix is mechanical)
+  //
+  // See migration-tooling-policy.mdc § Decision 3.
+  it("vtex-transform.toProduct throws and points at the canonical path", () => {
+    const src = LIB_TEMPLATES["src/lib/vtex-transform.ts"];
+    expect(src).toMatch(/throw new Error/);
+    expect(src).toMatch(/@decocms\/apps\/vtex\/utils\/transform/);
+    expect(src).toMatch(/\[deco-migrate\]/);
+  });
+
+  it("vtex-intelligent-search.getISCookiesFromBag throws", () => {
+    const src = LIB_TEMPLATES["src/lib/vtex-intelligent-search.ts"];
+    expect(src).toMatch(/getISCookiesFromBag[\s\S]*?throw new Error/);
+    expect(src).toMatch(/\[deco-migrate\]/);
+    // The other helpers in this file (isFilterParam, toPath,
+    // withDefaultFacets, withDefaultParams) are real impls — must not
+    // throw.
+    expect(src).toMatch(/export function isFilterParam[\s\S]*?return key\.startsWith/);
+  });
+
+  it("vtex-segment.getSegmentFromBag and withSegmentCookie both throw", () => {
+    const src = LIB_TEMPLATES["src/lib/vtex-segment.ts"];
+    expect(src).toMatch(/getSegmentFromBag[\s\S]*?throw new Error/);
+    expect(src).toMatch(/withSegmentCookie[\s\S]*?throw new Error/);
+    expect(src).toMatch(/@decocms\/apps\/vtex\/utils\/segment/);
+  });
+
+  it("non-stub helpers stay implemented (negative check — no throw)", () => {
+    // These are real impls, not stubs. They must not throw.
+    const real = [
+      "src/lib/http-utils.ts",
+      "src/lib/vtex-id.ts",
+      "src/lib/graphql-utils.ts",
+      "src/lib/filter-navigate.ts",
+      "src/lib/fetch-utils.ts",
+    ];
+    for (const key of real) {
+      const src = LIB_TEMPLATES[key];
+      expect(src, `${key} should not contain a generated stub throw`).not.toMatch(
+        /\[deco-migrate\][^"]*generated stub/,
+      );
+    }
+  });
+});

package/scripts/migrate/templates/lib-utils.ts

@@ -38,15 +38,41 @@ export function selectImportedLibTemplates(
   return out;
 }
 
+// Per the migration tooling policy (D3 — Throwing stubs):
+// generated stubs MUST throw at runtime so the first call surfaces the
+// gap loudly. Silent identity-cast `toProduct` was the bug behind
+// baggagio-tanstack#10 (PDP product data was being dropped on the floor
+// for weeks before anyone noticed).
+//
+// Each thrown message points at the canonical replacement so the fix
+// is mechanical. `deco-post-cleanup --fix` automates the swap.
 const LIB_VTEX_TRANSFORM = `import type { Product } from "@decocms/apps/commerce/types";
 
-export function toProduct(vtexProduct: any): Product {
-  return vtexProduct as Product;
+const STUB =
+  "[deco-migrate] \`~/lib/vtex-transform.toProduct\` is a generated stub. " +
+  "Replace with: import { toProduct } from '@decocms/apps/vtex/utils/transform' " +
+  "(canonical signature: \`toProduct(product, sku, level, options)\`). " +
+  "Run \`deco-post-cleanup --fix\` or see the deco-to-tanstack-migration skill " +
+  "(post-migration-cleanup § 5).";
+
+export function toProduct(_vtexProduct: any, ..._rest: any[]): Product {
+  throw new Error(STUB);
 }
 `;
 
-const LIB_VTEX_INTELLIGENT_SEARCH = `export function getISCookiesFromBag(_req?: any): Record<string, string> {
-  return {};
+const LIB_VTEX_INTELLIGENT_SEARCH = `// Per the migration tooling policy (D3): \`getISCookiesFromBag\` cannot
+// be implemented on TanStack Start because the bag-based lookup
+// mechanism does not exist. Sites must read cookies directly from the
+// request — see the \`vtex-shim-regression\` audit rule for guidance.
+const STUB_GET_IS_COOKIES =
+  "[deco-migrate] \`~/lib/vtex-intelligent-search.getISCookiesFromBag\` is a " +
+  "generated stub. Refactor: extract IS cookies from " +
+  "\`request.headers.get('cookie')\` directly. The bag-based lookup mechanism " +
+  "does not exist on TanStack Start. See the deco-to-tanstack-migration " +
+  "skill (post-migration-cleanup § 5).";
+
+export function getISCookiesFromBag(_req?: any): Record<string, string> {
+  throw new Error(STUB_GET_IS_COOKIES);
 }
 
 export function isFilterParam(key: string): boolean {
@@ -85,17 +111,30 @@ export function withDefaultParams(
 }
 `;
 
-const LIB_VTEX_SEGMENT = `export function getSegmentFromBag(_req?: any): Record<string, unknown> | null {
-  return null;
+const LIB_VTEX_SEGMENT = `// Per the migration tooling policy (D3): both these stubs throw at
+// runtime to force the call site to be fixed. Silent fallbacks here
+// mean the storefront silently fails to forward VTEX segment data
+// (sales channel, regionId, currency, etc.) and pricing/inventory
+// quietly diverge from what the user should see.
+const STUB_GET_SEGMENT_FROM_BAG =
+  "[deco-migrate] \`~/lib/vtex-segment.getSegmentFromBag\` is a generated " +
+  "stub. Refactor: 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.";
+
+const STUB_WITH_SEGMENT_COOKIE =
+  "[deco-migrate] \`~/lib/vtex-segment.withSegmentCookie\` is a generated " +
+  "stub. Replace with: import { withSegmentCookie } from " +
+  "'@decocms/apps/vtex/utils/segment' (canonical signature: " +
+  "\`withSegmentCookie(segment, headers?)\`). Run \`deco-post-cleanup --fix\` " +
+  "or see the deco-to-tanstack-migration skill.";
+
+export function getSegmentFromBag(_req?: any): Record<string, unknown> | null {
+  throw new Error(STUB_GET_SEGMENT_FROM_BAG);
 }
 
 export function withSegmentCookie(..._args: any[]): any {
-  for (const arg of _args) {
-    if (arg instanceof Headers) {
-      return arg;
-    }
-  }
-  return new Headers();
+  throw new Error(STUB_WITH_SEGMENT_COOKIE);
 }
 `;