@decocms/blocks-cli 7.0.0

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

@@ -0,0 +1,137 @@
+/**
+ * Post-migration cleanup audit — orchestrator.
+ *
+ * `runAudit` is the testable, FS-injected entry. The CLI in
+ * `../../migrate-post-cleanup.ts` wires up the real disk adapter.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ALL_RULES } from "./rules";
+import type { AuditReport, FsAdapter, FsWriter, Rule, RuleSummary } from "./types";
+
+export interface RunAuditOptions {
+  /**
+   * When set, rules with an `applyFix` implementation will run their
+   * fix and the report will include the resulting `FixAction[]`.
+   * Without this, the runner is purely read-only.
+   */
+  writer?: FsWriter;
+  /** Restrict to a subset of rules (defaults to all). */
+  rules?: Rule[];
+}
+
+export function runAudit(
+  siteDir: string,
+  adapter: FsAdapter,
+  options: RunAuditOptions = {},
+): AuditReport {
+  const rules = options.rules ?? ALL_RULES;
+  const summaries: RuleSummary[] = rules.map((rule) => {
+    const findings = rule.run({ siteDir, fs: adapter });
+    const supportsAutoFix = typeof rule.applyFix === "function";
+    let fixes: RuleSummary["fixes"];
+    if (options.writer && rule.applyFix && findings.length > 0) {
+      fixes = rule.applyFix({ siteDir, fs: adapter }, findings, options.writer);
+    }
+    return {
+      rule: rule.id,
+      title: rule.title,
+      findings,
+      supportsAutoFix,
+      fixes,
+    };
+  });
+  return {
+    site: siteDir,
+    rules: summaries,
+    totalFindings: summaries.reduce((acc, s) => acc + s.findings.length, 0),
+    totalFixActions: summaries.reduce((acc, s) => acc + (s.fixes?.length ?? 0), 0),
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Real disk adapter                                                  */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Minimal recursive-walk glob — intentionally tiny, no external deps.
+ * Supports `**`, `*`, and `{a,b,c}` brace expansion.  Does NOT support
+ * extglob, negation, or `?`. That's fine: every pattern in this audit
+ * fits the supported subset.
+ */
+function expandBraces(pattern: string): string[] {
+  const m = pattern.match(/\{([^{}]+)\}/);
+  if (!m) return [pattern];
+  const [whole, inner] = m;
+  const start = pattern.indexOf(whole);
+  const before = pattern.slice(0, start);
+  const after = pattern.slice(start + whole.length);
+  const branches = inner.split(",");
+  return branches.flatMap((b) => expandBraces(`${before}${b}${after}`));
+}
+
+function patternToRegex(pattern: string): RegExp {
+  const re = pattern
+    .replace(/[.+^$()|]/g, "\\$&")
+    .replace(/\*\*\//g, "<<DBL>>")
+    .replace(/\*\*/g, "<<DBL>>")
+    .replace(/\*/g, "[^/]*")
+    .replace(/<<DBL>>/g, "(?:.*/)?");
+  return new RegExp(`^${re}$`);
+}
+
+function walk(dir: string, rootDir: string, excludeDirs: Set<string>, out: string[]): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (excludeDirs.has(entry.name)) continue;
+      walk(abs, rootDir, excludeDirs, out);
+    } else if (entry.isFile()) {
+      out.push(abs);
+    }
+  }
+}
+
+export const realFsAdapter: FsAdapter = {
+  exists(absPath: string) {
+    return fs.existsSync(absPath);
+  },
+  readText(absPath: string) {
+    return fs.readFileSync(absPath, "utf-8");
+  },
+  glob(siteDir: string, pattern: string, excludeDirs: string[] = []) {
+    const allFiles: string[] = [];
+    walk(siteDir, siteDir, new Set(excludeDirs), allFiles);
+    const patterns = expandBraces(pattern).map(patternToRegex);
+    const matches = allFiles.filter((abs) => {
+      const rel = abs.slice(siteDir.length + 1).replace(/\\/g, "/");
+      return patterns.some((re) => re.test(rel));
+    });
+    return matches.sort();
+  },
+};
+
+/**
+ * Real disk writer used by the CLI when `--fix` is on. Tests should
+ * use a recording adapter and never instantiate this.
+ *
+ * `deleteFile` is intentionally tolerant: if the file is already gone
+ * (race with a previous fix or manual cleanup), we treat that as a
+ * no-op rather than crashing the audit.
+ */
+export const realFsWriter: FsWriter = {
+  deleteFile(absPath: string) {
+    if (fs.existsSync(absPath)) fs.unlinkSync(absPath);
+  },
+  writeText(absPath: string, content: string) {
+    fs.writeFileSync(absPath, content, "utf-8");
+  },
+};

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