@decocms/start 2.13.0 → 2.14.0

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

@@ -159,18 +159,44 @@ 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, 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/...'
+```
+
+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.14.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,97 @@ const ruleSiteLocalGlobals: Rule = {
 /* Rule 5 — `~/lib/vtex-*` shim regression                             */
 /* ------------------------------------------------------------------ */
 
+/**
+ * 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("; ")
+      ;
       findings.push({
         rule: "vtex-shim-regression",
         severity: "warning",
         file: rel,
-        message: `Imports from dead shim(s): ${shims.join(", ")} — runtime is silently stubbed`,
+        message: `Imports stub-only symbols from ${detail} — runtime is silently stubbed`,
         fix: "Repoint imports to '@decocms/apps/vtex/...' or 'apps/commerce/utils/...'",
-        meta: { shims },
+        meta: {
+          stubsBySim: Object.fromEntries(stubsBySim),
+        },
       });
     }
     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,122 @@ 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: local-widgets-types", () => {

package/scripts/migrate/post-cleanup/shim-classify.test.ts

@@ -0,0 +1,352 @@
+import { describe, expect, it } from "vitest";
+import { classifyShimExports, type ClassifiedExport } from "./shim-classify";
+
+function classMap(content: string): Record<string, ClassifiedExport["class"]> {
+  return Object.fromEntries(
+    classifyShimExports(content).map((e) => [e.name, e.class]),
+  );
+}
+
+describe("classifyShimExports — single statement function bodies", () => {
+  it("returns null → stub", () => {
+    const code = `
+      export function getSegmentFromBag(_req?: any): Record<string, unknown> | null {
+        return null;
+      }
+    `;
+    expect(classMap(code)).toEqual({ getSegmentFromBag: "stub" });
+  });
+
+  it("returns {} → stub", () => {
+    const code = `
+      export function getISCookiesFromBag(_req?: any): Record<string, string> {
+        return {};
+      }
+    `;
+    expect(classMap(code)).toEqual({ getISCookiesFromBag: "stub" });
+  });
+
+  it("returns [] → stub", () => {
+    const code = `export function emptyList(): string[] { return []; }`;
+    expect(classMap(code)).toEqual({ emptyList: "stub" });
+  });
+
+  it("returns empty string → stub", () => {
+    const code = `export function emptyStr(): string { return ""; }`;
+    expect(classMap(code)).toEqual({ emptyStr: "stub" });
+  });
+
+  it("identity cast (return x as T) → stub", () => {
+    const code = `
+      import type { Product } from "@decocms/apps/commerce/types";
+      export function toProduct(vtexProduct: any): Product {
+        return vtexProduct as Product;
+      }
+    `;
+    expect(classMap(code)).toEqual({ toProduct: "stub" });
+  });
+
+  it("identity cast on member (return x.foo as T) → stub", () => {
+    const code = `export function toThing(o: any): X { return o.payload as X; }`;
+    expect(classMap(code)).toEqual({ toThing: "stub" });
+  });
+
+  it("unconditional throw → stub", () => {
+    const code = `
+      export function notImplemented(): never {
+        throw new Error("not implemented");
+      }
+    `;
+    expect(classMap(code)).toEqual({ notImplemented: "stub" });
+  });
+
+  it("returns non-empty value → functional", () => {
+    const code = `export function answer(): number { return 42; }`;
+    expect(classMap(code)).toEqual({ answer: "functional" });
+  });
+
+  it("returns non-identity expression → functional", () => {
+    const code = `
+      export function isFilterParam(key: string): boolean {
+        return key.startsWith("filter.");
+      }
+    `;
+    expect(classMap(code)).toEqual({ isFilterParam: "functional" });
+  });
+
+  it("multi-statement body → functional (default safe)", () => {
+    const code = `
+      export async function fetchSafe(input: string): Promise<Response> {
+        const response = await fetch(input);
+        if (!response.ok) {
+          console.error(response.status);
+        }
+        return response;
+      }
+    `;
+    expect(classMap(code)).toEqual({ fetchSafe: "functional" });
+  });
+
+  it("body with nested blocks → functional", () => {
+    const code = `
+      export function withDefaultParams(params: any, defaults?: any): any {
+        if (params instanceof URLSearchParams) {
+          if (defaults) {
+            for (const [key, value] of Object.entries(defaults)) {
+              if (!params.has(key)) {
+                params.set(key, value);
+              }
+            }
+          }
+          return params;
+        }
+        return { ...params, ...defaults };
+      }
+    `;
+    expect(classMap(code)).toEqual({ withDefaultParams: "functional" });
+  });
+
+  it("comments before return → still classified by content", () => {
+    const code = `
+      export function stubWithComment(): null {
+        // Intentionally a stub — see migration notes.
+        return null;
+      }
+    `;
+    expect(classMap(code)).toEqual({ stubWithComment: "stub" });
+  });
+
+  it("trailing semicolon optional", () => {
+    const code = `export function noSemi(): null { return null }`;
+    expect(classMap(code)).toEqual({ noSemi: "stub" });
+  });
+});
+
+describe("classifyShimExports — async functions", () => {
+  it("async returns null → stub", () => {
+    const code = `export async function asyncStub(): Promise<null> { return null; }`;
+    expect(classMap(code)).toEqual({ asyncStub: "stub" });
+  });
+
+  it("async with real work → functional", () => {
+    const code = `
+      export async function fetcher(): Promise<Response> {
+        const r = await fetch("/x");
+        return r;
+      }
+    `;
+    expect(classMap(code)).toEqual({ fetcher: "functional" });
+  });
+});
+
+describe("classifyShimExports — const arrow functions", () => {
+  it("arrow returns null (block body) → stub", () => {
+    const code = `export const noop = (): null => { return null; };`;
+    expect(classMap(code)).toEqual({ noop: "stub" });
+  });
+
+  it("arrow returns null (expression body) → stub", () => {
+    const code = `export const noop = (): null => null;`;
+    expect(classMap(code)).toEqual({ noop: "stub" });
+  });
+
+  it("arrow returns empty object literal expression → stub", () => {
+    const code = `export const noop = () => ({});`;
+    expect(classMap(code)).toEqual({ noop: "stub" });
+  });
+
+  it("arrow with real expression → functional", () => {
+    const code = `export const square = (n: number) => n * n;`;
+    expect(classMap(code)).toEqual({ square: "functional" });
+  });
+
+  it("non-arrow const (object literal) → functional", () => {
+    const code = `export const config = { account: "x" };`;
+    expect(classMap(code)).toEqual({ config: "functional" });
+  });
+});
+
+describe("classifyShimExports — type/interface declarations", () => {
+  it("interface → type-only", () => {
+    const code = `
+      export interface VTEXCommerceStable {
+        account: string;
+        environment?: string;
+      }
+    `;
+    expect(classMap(code)).toEqual({ VTEXCommerceStable: "type-only" });
+  });
+
+  it("type alias → type-only", () => {
+    const code = `export type AccountId = string;`;
+    expect(classMap(code)).toEqual({ AccountId: "type-only" });
+  });
+});
+
+describe("classifyShimExports — real casaevideo-storefront fixtures", () => {
+  it("vtex-segment.ts (mixed: stub + functional)", () => {
+    const code = `
+      export function getSegmentFromBag(_req?: any): Record<string, unknown> | null {
+        return null;
+      }
+
+      export function withSegmentCookie(..._args: any[]): any {
+        for (const arg of _args) {
+          if (arg instanceof Headers) {
+            return arg;
+          }
+        }
+        return new Headers();
+      }
+    `;
+    expect(classMap(code)).toEqual({
+      getSegmentFromBag: "stub",
+      // Multi-statement / nested block — defaults to functional. This is a
+      // *known* false negative (see module docstring): the function looks
+      // functional but actually drops the segment cookie. We accept this
+      // trade-off rather than risk false positives on real implementations.
+      withSegmentCookie: "functional",
+    });
+  });
+
+  it("vtex-transform.ts (single identity-cast stub)", () => {
+    const code = `
+      import type { Product } from "@decocms/apps/commerce/types";
+      export function toProduct(vtexProduct: any): Product {
+        return vtexProduct as Product;
+      }
+    `;
+    expect(classMap(code)).toEqual({ toProduct: "stub" });
+  });
+
+  it("vtex-client.ts (interface only)", () => {
+    const code = `
+      export interface VTEXCommerceStable {
+        account: string;
+        environment?: string;
+      }
+    `;
+    expect(classMap(code)).toEqual({ VTEXCommerceStable: "type-only" });
+  });
+
+  it("vtex-fetch.ts (functional)", () => {
+    const code = `
+      export async function fetchSafe(
+        input: string | URL | Request,
+        init?: RequestInit,
+      ): Promise<Response> {
+        const response = await fetch(input, init);
+        if (!response.ok) {
+          console.error(\`VTEX fetch failed: \${response.status}\`);
+        }
+        return response;
+      }
+    `;
+    expect(classMap(code)).toEqual({ fetchSafe: "functional" });
+  });
+
+  it("vtex-id.ts (functional cookie parser)", () => {
+    const code = `
+      export function parseCookie(cookieStr?: string | null): Record<string, string> {
+        if (!cookieStr) return {};
+        return Object.fromEntries(
+          cookieStr.split(";").map((c) => {
+            const [key, ...rest] = c.trim().split("=");
+            return [key, rest.join("=")];
+          }),
+        );
+      }
+    `;
+    expect(classMap(code)).toEqual({ parseCookie: "functional" });
+  });
+
+  it("vtex-intelligent-search.ts (mixed: 1 stub + 4 functional)", () => {
+    const code = `
+      export function getISCookiesFromBag(_req?: any): Record<string, string> {
+        return {};
+      }
+
+      export function isFilterParam(key: string): boolean {
+        return key.startsWith("filter.");
+      }
+
+      export function toPath(facets: { key: string; value: string }[]): string {
+        return facets.map((f) => \`\${f.key}/\${f.value}\`).join("/");
+      }
+
+      export function withDefaultFacets(
+        facets: { key: string; value: string }[],
+        defaults?: any,
+      ): { key: string; value: string }[] {
+        if (Array.isArray(defaults)) {
+          return [...defaults, ...facets];
+        }
+        return [...facets];
+      }
+
+      export function withDefaultParams(
+        params: any,
+        defaults?: Record<string, string>,
+      ): any {
+        if (params instanceof URLSearchParams) {
+          if (defaults) {
+            for (const [key, value] of Object.entries(defaults)) {
+              if (!params.has(key)) {
+                params.set(key, value);
+              }
+            }
+          }
+          return params;
+        }
+        return { ...params, ...defaults };
+      }
+    `;
+    expect(classMap(code)).toEqual({
+      getISCookiesFromBag: "stub",
+      isFilterParam: "functional",
+      toPath: "functional",
+      withDefaultFacets: "functional",
+      withDefaultParams: "functional",
+    });
+  });
+});
+
+describe("classifyShimExports — defensive cases", () => {
+  it("empty file → no exports", () => {
+    expect(classifyShimExports("")).toEqual([]);
+  });
+
+  it("file with only imports → no exports", () => {
+    const code = `import { x } from "y";`;
+    expect(classifyShimExports(code)).toEqual([]);
+  });
+
+  it("non-export function ignored", () => {
+    const code = `function private_(): null { return null; }`;
+    expect(classifyShimExports(code)).toEqual([]);
+  });
+
+  it("export default skipped (intentional — only flag named exports)", () => {
+    const code = `export default function() { return null; }`;
+    expect(classifyShimExports(code)).toEqual([]);
+  });
+
+  it("strings containing braces don't break body extraction", () => {
+    const code = `
+      export function withBrace(): string {
+        return "{not a real brace}";
+      }
+    `;
+    expect(classMap(code)).toEqual({ withBrace: "functional" });
+  });
+
+  it("template literal with brace-like substitution", () => {
+    const code = `
+      export function withTemplate(): string {
+        return \`hello \${1 + 1}\`;
+      }
+    `;
+    // Single statement, but the value is non-empty/non-null → functional.
+    expect(classMap(code)).toEqual({ withTemplate: "functional" });
+  });
+});