@decocms/blocks-cli 7.0.0

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

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

@@ -0,0 +1,106 @@
+/**
+ * Post-migration cleanup audit — shared types.
+ *
+ * The audit runner is a thin orchestrator: it loads the site, runs each
+ * rule, and prints the findings. The interesting bits live in `rules.ts`.
+ *
+ * Rules are pure(ish) functions over an injected `FsAdapter`, which means
+ * they can be unit-tested with an in-memory file system and never touch
+ * the real disk in CI.
+ */
+
+export type Severity = "info" | "warning";
+
+export interface Finding {
+  /** Stable rule identifier (e.g. "dead-lib-shims"). */
+  rule: string;
+  severity: Severity;
+  /** Site-relative path of the file the finding refers to. */
+  file: string;
+  /** One-line message — shown in default text output. */
+  message: string;
+  /** Suggested human action, if any. */
+  fix?: string;
+  /** Free-form structured payload for JSON consumers. */
+  meta?: Record<string, unknown>;
+}
+
+export interface RuleSummary {
+  /** Stable rule identifier. */
+  rule: string;
+  /** Human-readable section title. */
+  title: string;
+  findings: Finding[];
+  /** Populated only when fix mode is on. */
+  fixes?: FixAction[];
+  /**
+   * True when the rule has an `applyFix` implementation. Lets the CLI
+   * tell users which findings would auto-fix vs require manual work.
+   */
+  supportsAutoFix: boolean;
+}
+
+export interface AuditReport {
+  site: string;
+  rules: RuleSummary[];
+  totalFindings: number;
+  /** Total fix actions across all rules (0 if not in fix mode). */
+  totalFixActions: number;
+}
+
+/**
+ * Minimal file-system adapter — read + glob. Keeping the surface tiny
+ * is what lets us pass an in-memory map in unit tests.
+ */
+export interface FsAdapter {
+  exists(absPath: string): boolean;
+  readText(absPath: string): string;
+  /**
+   * Return absolute paths matching the glob, ordered by path. Globs are
+   * relative to `siteDir`. Implementations must respect `excludeDirs` and
+   * skip them entirely.
+   */
+  glob(siteDir: string, pattern: string, excludeDirs?: string[]): string[];
+}
+
+export interface RuleContext {
+  siteDir: string;
+  fs: FsAdapter;
+}
+
+/**
+ * Mutating side of the FS adapter. Kept separate from `FsAdapter` so
+ * read-only audits (the default) cannot accidentally write. Tests
+ * substitute a recorder that captures actions without touching disk.
+ */
+export interface FsWriter {
+  deleteFile(absPath: string): void;
+  writeText(absPath: string, content: string): void;
+}
+
+/**
+ * One concrete change applied (or that would have been applied) by a
+ * rule's `applyFix` implementation. Consumed by the CLI to render a
+ * summary, and by the JSON output for CI dashboards.
+ */
+export interface FixAction {
+  /** Site-relative path the action targets. */
+  file: string;
+  /** "delete" | "rewrite-imports" | future: "edit" — kept open. */
+  kind: string;
+  /** Human-readable description, e.g. "deleted" or "rewrote 44 imports". */
+  detail: string;
+}
+
+export interface Rule {
+  id: string;
+  title: string;
+  run(ctx: RuleContext): Finding[];
+  /**
+   * Optional. Implement for rules whose findings can be safely
+   * auto-corrected. Called only when the runner is in fix mode.
+   * Must return one or more `FixAction`s describing what changed
+   * (used both for output and for tests with a stubbed writer).
+   */
+  applyFix?(ctx: RuleContext, findings: Finding[], writer: FsWriter): FixAction[];
+}

package/scripts/migrate/source-layout.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import {
+  detectSourceLayout,
+  explainNonClassicLayout,
+  type FsLike,
+  type SourceLayout,
+} from "./source-layout";
+
+/**
+ * In-memory FsLike for tests. Holds a Set of paths that "exist" — no
+ * content needed since `detectSourceLayout` only calls `existsSync`.
+ */
+function makeFs(paths: string[]): FsLike {
+  const set = new Set(paths.map((p) => p.replace(/\\/g, "/")));
+  return {
+    existsSync(p: string) {
+      return set.has(p.replace(/\\/g, "/"));
+    },
+  };
+}
+
+const SITE = "/site";
+
+describe("detectSourceLayout — classic layout", () => {
+  it("classifies a site with sections/ at root as classic", () => {
+    const fs = makeFs(["/site/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("classic");
+  });
+
+  it("classifies multi-dir root layout as classic", () => {
+    const fs = makeFs(["/site/sections", "/site/islands", "/site/components", "/site/loaders"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("classic");
+  });
+
+  it("any single recognised root dir is enough", () => {
+    for (const d of ["sections", "islands", "components", "loaders", "actions"]) {
+      const fs = makeFs([`/site/${d}`]);
+      expect(detectSourceLayout(SITE, fs)).toBe("classic");
+    }
+  });
+});
+
+describe("detectSourceLayout — modern layout", () => {
+  it("classifies src/sections-only as modern", () => {
+    const fs = makeFs(["/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("modern");
+  });
+
+  it("classifies multi-dir src/ layout as modern", () => {
+    const fs = makeFs(["/site/src/sections", "/site/src/islands", "/site/src/components"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("modern");
+  });
+});
+
+describe("detectSourceLayout — mixed layout", () => {
+  it("flags both root + src/ as mixed", () => {
+    const fs = makeFs(["/site/sections", "/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("mixed");
+  });
+
+  it("flags partial overlap as mixed (root islands + src sections)", () => {
+    const fs = makeFs(["/site/islands", "/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("mixed");
+  });
+});
+
+describe("detectSourceLayout — empty layout", () => {
+  it("returns empty when neither root nor src/ has recognised dirs", () => {
+    const fs = makeFs(["/site/package.json", "/site/README.md"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("empty");
+  });
+
+  it("returns empty for an unrelated dir", () => {
+    const fs = makeFs(["/site/random-dir/x.txt"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("empty");
+  });
+});
+
+describe("detectSourceLayout — works against the real disk", () => {
+  it("uses real fs by default", () => {
+    // Just call with no fsAdapter on a real path that doesn't exist —
+    // should return "empty" without throwing. Smoke check that the
+    // default-arg wiring works.
+    expect(detectSourceLayout("/this/does/not/exist")).toBe("empty");
+  });
+});
+
+describe("explainNonClassicLayout — message content", () => {
+  const cases: Array<[Exclude<SourceLayout, "classic">, string[]]> = [
+    ["modern", ['Modern Fresh "src/" layout', "Move src/sections", "File an issue"]],
+    ["mixed", ["Mixed layout", "pick one layout", "clean checkout"]],
+    [
+      "empty",
+      [
+        "No recognizable Deco layout",
+        "sections, islands, components, loaders, actions",
+        "--source",
+      ],
+    ],
+  ];
+
+  for (const [layout, fragments] of cases) {
+    it(`${layout}: includes site path + key guidance`, () => {
+      const msg = explainNonClassicLayout(layout, "/some/site");
+      expect(msg).toContain("/some/site");
+      for (const f of fragments) {
+        expect(msg).toContain(f);
+      }
+    });
+  }
+});

package/scripts/migrate/source-layout.ts

@@ -0,0 +1,103 @@
+/**
+ * Source-layout detection.
+ *
+ * Classic Fresh sites place sections, islands, components etc. at the
+ * repo root. Modern Fresh (post 1.6) and several community starters
+ * use a `src/` layout where everything lives under `src/sections/`,
+ * `src/islands/`, etc. The migration analyzer's `SKIP_DIRS` includes
+ * `"src"` (because the OUTPUT site stores migrated code there), so
+ * a modern-layout source would be silently scanned as if it were
+ * empty — yielding a near-empty migration with no helpful errors.
+ *
+ * This module classifies a source directory into one of:
+ *   - "classic": expected layout (sections/, islands/, …) at root
+ *   - "modern":  src/-layout (src/sections/, src/islands/, …)
+ *   - "mixed":   both root sections/ AND src/sections/ — usually a
+ *                half-migrated repo
+ *   - "empty":   nothing recognizable; could be a fresh scaffold
+ *
+ * The migration script consumes this for an early-abort with an
+ * actionable error message. Eventually the analyzer can be extended
+ * to scan `src/` natively, at which point the "modern" branch can
+ * proceed instead of aborting.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type SourceLayout = "classic" | "modern" | "mixed" | "empty";
+
+const RECOGNISED_DIRS = ["sections", "islands", "components", "loaders", "actions"];
+
+export interface FsLike {
+  existsSync(p: string): boolean;
+}
+
+const realFs: FsLike = { existsSync: fs.existsSync };
+
+/**
+ * Classify the source directory's layout. Pure function — accepts
+ * a `FsLike` so unit tests can stub the disk without mocking node:fs.
+ */
+export function detectSourceLayout(sourceDir: string, fsAdapter: FsLike = realFs): SourceLayout {
+  const hasRootDir = RECOGNISED_DIRS.some((d) => fsAdapter.existsSync(path.join(sourceDir, d)));
+  const hasSrcDir = RECOGNISED_DIRS.some((d) =>
+    fsAdapter.existsSync(path.join(sourceDir, "src", d)),
+  );
+
+  if (hasRootDir && hasSrcDir) return "mixed";
+  if (hasSrcDir) return "modern";
+  if (hasRootDir) return "classic";
+  return "empty";
+}
+
+/**
+ * Build a human-readable, actionable message for a non-classic
+ * layout. Consumed by the CLI to print before exiting. Lives in
+ * this module so the test can pin the exact wording.
+ */
+export function explainNonClassicLayout(
+  layout: Exclude<SourceLayout, "classic">,
+  sourceDir: string,
+): string {
+  switch (layout) {
+    case "modern":
+      return [
+        `Modern Fresh "src/" layout detected at ${sourceDir}/src.`,
+        "",
+        "  This migration script currently scans only the classic root layout",
+        "  (sections/, islands/, components/, loaders/, actions/ at the repo root).",
+        "",
+        "  Workaround until native support lands:",
+        "  1. Move src/sections, src/islands, src/components, src/loaders, src/actions",
+        "     up one level to the repo root (the script's expected layout).",
+        "  2. Re-run the migration.",
+        "  3. (If desired) Restructure to a src/ layout post-migration — the",
+        "     TanStack Start scaffold uses src/ on the output side regardless.",
+        "",
+        "  File an issue with your site URL so this can be supported natively.",
+      ].join("\n");
+    case "mixed":
+      return [
+        `Mixed layout detected at ${sourceDir}.`,
+        "",
+        "  Both root sections/ and src/sections/ are present. This usually means",
+        "  the migration was previously run partially against this directory, or",
+        "  the source genuinely has parallel layouts (rare).",
+        "",
+        "  Resolution: pick one layout and remove the other before re-running.",
+        "  If this is a half-migrated repo, restore the original via git and",
+        "  run the migration against a clean checkout (--source <fresh-path>).",
+      ].join("\n");
+    case "empty":
+      return [
+        `No recognizable Deco layout found at ${sourceDir}.`,
+        "",
+        "  Expected one of these directories at the repo root or under src/:",
+        `    ${RECOGNISED_DIRS.join(", ")}`,
+        "",
+        "  Did you point --source at the correct directory? It should be the",
+        "  root of an existing Fresh-based Deco site, not the new TanStack site.",
+      ].join("\n");
+  }
+}