@decocms/start 2.13.0 → 2.15.0

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" });
+  });
+});

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

@@ -0,0 +1,246 @@
+/**
+ * Per-export classifier for `~/lib/vtex-*` shim files.
+ *
+ * The post-migration audit's `vtex-shim-regression` rule used to flag
+ * any import from these shims. That was overconfident — some shims have
+ * functional implementations of utility code (cookie parsing, fetch
+ * wrapping), while others are silent stubs (`return null`, `return {}`,
+ * identity casts) that drop runtime data and cause hard-to-trace bugs.
+ *
+ * This classifier inspects each export of a shim and labels it as:
+ *
+ * - **stub**: definitely a silent regression — body is `return null`,
+ *   `return {}`, `return []`, an identity cast `return x as T`, or an
+ *   unconditional `throw`. Importing this symbol means the shim is
+ *   pretending to do work but isn't.
+ * - **type-only**: `interface` or `type` declaration — no runtime impact,
+ *   never a regression.
+ * - **functional**: anything else (real implementations, even trivial
+ *   ones like `return key.startsWith("filter.")`). Default-safe label —
+ *   if we can't prove it's a stub, treat it as functional and don't flag.
+ *
+ * Trade-off — by design, we err toward "functional" when uncertain.
+ * That means some lossy implementations (e.g. a `withSegmentCookie`
+ * that returns `new Headers()` instead of attaching the cookie) classify
+ * as functional even though they're effectively stubs. Catching those
+ * would need real semantic analysis. False negatives are tolerable; the
+ * rule still warns when *any* imported symbol from the shim is a clear
+ * stub, which is enough to surface the real-world regressions we've
+ * actually seen on production sites (casaevideo: `getSegmentFromBag`,
+ * `getISCookiesFromBag`, `toProduct`).
+ *
+ * Implementation note — string parsing, not a real TypeScript AST. The
+ * shim files are tiny by design (the casaevideo ones are 1-39 lines).
+ * A balanced-brace body extractor + small set of stub patterns covers
+ * every case observed on real sites. If this ever needs to handle
+ * decorators, generics on consts, or weirder JSX forms, the right move
+ * is to swap in `typescript`'s `createSourceFile` — but we don't pay
+ * that dependency cost until it's clearly needed.
+ */
+
+export type ExportClass = "stub" | "type-only" | "functional";
+
+export interface ClassifiedExport {
+  name: string;
+  class: ExportClass;
+  /** Short, human-readable reason for the classification. */
+  reason?: string;
+}
+
+/**
+ * Strip line/block comments from a string before regex-matching the
+ * body. Keeps newlines so positions stay roughly aligned for debug.
+ */
+function stripComments(s: string): string {
+  return s
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+    .replace(/\/\/[^\n]*/g, "");
+}
+
+/**
+ * Find the matching `}` for the `{` at `openIdx`. Returns the index of
+ * the closing brace, or -1 if unbalanced. Tolerates strings and template
+ * literals that may contain stray braces — we honor the basic quoting
+ * rules, not full TS lexer fidelity.
+ */
+function findMatchingBrace(content: string, openIdx: number): number {
+  let depth = 0;
+  let i = openIdx;
+  let inStr: string | null = null;
+  let esc = false;
+  while (i < content.length) {
+    const c = content[i];
+    if (inStr) {
+      if (esc) {
+        esc = false;
+      } else if (c === "\\") {
+        esc = true;
+      } else if (c === inStr) {
+        inStr = null;
+      }
+    } else if (c === '"' || c === "'" || c === "`") {
+      inStr = c;
+    } else if (c === "{") {
+      depth++;
+    } else if (c === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return -1;
+}
+
+/**
+ * Match `return null` / `return {}` / `return []` / `return X as Y` /
+ * `throw new Error(...)` as the only meaningful statement in the body.
+ * Comments and whitespace are tolerated.
+ */
+function classifyBodyText(body: string): { class: ExportClass; reason?: string } | null {
+  const cleaned = stripComments(body).trim();
+  // Allow a trailing semicolon, but not multiple statements.
+  const single = cleaned.replace(/;\s*$/, "").trim();
+  if (single === "") return null;
+  // Reject anything that looks like multiple statements.
+  if (/[;\n]/.test(single.replace(/\s+/g, " ").trim()) && !/^return\s/.test(single)) {
+    return null;
+  }
+  if (/^return\s+null$/.test(single)) {
+    return { class: "stub", reason: "returns null" };
+  }
+  if (/^return\s+\{\s*\}$/.test(single)) {
+    return { class: "stub", reason: "returns empty object" };
+  }
+  if (/^return\s+\[\s*\]$/.test(single)) {
+    return { class: "stub", reason: "returns empty array" };
+  }
+  if (/^return\s+""$/.test(single) || /^return\s+''$/.test(single)) {
+    return { class: "stub", reason: "returns empty string" };
+  }
+  // Identity cast: `return ident as Type`. The right-hand side must be a
+  // bare identifier (or nested member like `obj.prop`) — anything else is
+  // probably real work.
+  const identityMatch = single.match(
+    /^return\s+([A-Za-z_][A-Za-z0-9_.]*)\s+as\s+[A-Za-z_][A-Za-z0-9_<>,\s.|&]*$/,
+  );
+  if (identityMatch) {
+    return { class: "stub", reason: `identity cast (return ${identityMatch[1]} as …)` };
+  }
+  if (/^throw\s+new\s+\w+\s*\(/.test(single)) {
+    return { class: "stub", reason: "unconditional throw" };
+  }
+  return null;
+}
+
+/**
+ * Locate `export function NAME(args): RT { body }` and `export async`
+ * variants. Returns each export with its body classified.
+ */
+function classifyFunctionDecls(content: string): ClassifiedExport[] {
+  const out: ClassifiedExport[] = [];
+  // Anchored at start-of-line + optional indent — avoids catching
+  // `export default function` (which has no name immediately after).
+  const re = /(?:^|\n)[ \t]*export\s+(?:async\s+)?function\s+([A-Za-z_][A-Za-z0-9_]*)\b/g;
+  for (const m of content.matchAll(re)) {
+    const name = m[1];
+    const startSearchAt = (m.index ?? 0) + m[0].length;
+    const openIdx = content.indexOf("{", startSearchAt);
+    if (openIdx === -1) {
+      out.push({ name, class: "functional", reason: "no body found (declaration only)" });
+      continue;
+    }
+    const closeIdx = findMatchingBrace(content, openIdx);
+    if (closeIdx === -1) {
+      out.push({ name, class: "functional", reason: "unbalanced braces" });
+      continue;
+    }
+    const body = content.slice(openIdx + 1, closeIdx);
+    const verdict = classifyBodyText(body);
+    out.push(
+      verdict
+        ? { name, class: verdict.class, reason: verdict.reason }
+        : { name, class: "functional" },
+    );
+  }
+  return out;
+}
+
+/**
+ * Locate `export const NAME = (args) => …` and classify the arrow body.
+ * Block-bodied arrows reuse the function-body classifier; expression
+ * bodies are matched directly.
+ */
+function classifyConstArrowDecls(content: string): ClassifiedExport[] {
+  const out: ClassifiedExport[] = [];
+  const re = /(?:^|\n)[ \t]*export\s+const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=/g;
+  for (const m of content.matchAll(re)) {
+    const name = m[1];
+    const startIdx = (m.index ?? 0) + m[0].length;
+    const after = content.slice(startIdx);
+    // Look for: optional `async`, `(args)`, optional `: ReturnType`, `=>`.
+    const arrowHead = after.match(/^\s*(?:async\s+)?\([^)]*\)\s*(?::[^=]+)?=>\s*/);
+    if (!arrowHead) {
+      out.push({ name, class: "functional" });
+      continue;
+    }
+    const bodyStart = startIdx + arrowHead[0].length;
+    // Block body: classify the inside via the shared body classifier.
+    if (content[bodyStart] === "{") {
+      const closeIdx = findMatchingBrace(content, bodyStart);
+      if (closeIdx === -1) {
+        out.push({ name, class: "functional", reason: "unbalanced braces" });
+        continue;
+      }
+      const body = content.slice(bodyStart + 1, closeIdx);
+      const verdict = classifyBodyText(body);
+      out.push(
+        verdict
+          ? { name, class: verdict.class, reason: verdict.reason }
+          : { name, class: "functional" },
+      );
+      continue;
+    }
+    // Expression body: read until line break / semicolon.
+    const exprMatch = content.slice(bodyStart).match(/^([^;\n]+?)\s*;?\s*(?:\n|$)/);
+    if (!exprMatch) {
+      out.push({ name, class: "functional" });
+      continue;
+    }
+    const expr = exprMatch[1].trim();
+    if (expr === "null") {
+      out.push({ name, class: "stub", reason: "arrow returns null" });
+    } else if (/^\(\s*\{\s*\}\s*\)$/.test(expr) || expr === "{}") {
+      out.push({ name, class: "stub", reason: "arrow returns empty object" });
+    } else if (/^\[\s*\]$/.test(expr)) {
+      out.push({ name, class: "stub", reason: "arrow returns empty array" });
+    } else {
+      out.push({ name, class: "functional" });
+    }
+  }
+  return out;
+}
+
+/**
+ * Locate `export interface NAME` / `export type NAME` declarations.
+ */
+function classifyTypeDecls(content: string): ClassifiedExport[] {
+  const out: ClassifiedExport[] = [];
+  const re = /(?:^|\n)[ \t]*export\s+(?:interface|type)\s+([A-Za-z_][A-Za-z0-9_]*)\b/g;
+  for (const m of content.matchAll(re)) {
+    out.push({ name: m[1], class: "type-only" });
+  }
+  return out;
+}
+
+/**
+ * Classify every top-level export in a shim file. Returns one entry per
+ * export, in source order is not guaranteed (we run three passes over
+ * the content); callers should look up by `name`.
+ */
+export function classifyShimExports(content: string): ClassifiedExport[] {
+  return [
+    ...classifyFunctionDecls(content),
+    ...classifyConstArrowDecls(content),
+    ...classifyTypeDecls(content),
+  ];
+}