@decocms/start 2.12.0 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/phase-cleanup-audit.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Tests for Phase 9 (cleanup audit integration into migrate.ts).
+ *
+ * These exercise the wrapper logic — what it prints, when it fails,
+ * how it interacts with --strict and dry-run. The underlying audit
+ * rules are tested separately in post-cleanup/runner.test.ts; we
+ * stub the disk minimally here just to drive findings counts.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanupAudit } from "./phase-cleanup-audit";
+import { createContext } from "./types";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "deco-migrate-audit-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function makeCtx(overrides?: { dryRun?: boolean }) {
+  return createContext(tmpDir, {
+    dryRun: overrides?.dryRun ?? false,
+    verbose: false,
+  });
+}
+
+describe("cleanupAudit — dry-run", () => {
+  it("is a no-op in dry-run mode (returns false, no console output)", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx({ dryRun: true });
+    const failed = cleanupAudit(ctx);
+    expect(failed).toBe(false);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe("cleanupAudit — empty site", () => {
+  it("prints success and returns false when there are no findings", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx);
+    expect(failed).toBe(false);
+    const out = spy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/No findings/);
+    spy.mockRestore();
+  });
+});
+
+describe("cleanupAudit — info-only findings (e.g. local widgets.ts)", () => {
+  beforeEach(() => {
+    // Set up a finding for rule 6 (local-widgets-types):
+    // need src/types/widgets.ts + at least one importer.
+    fs.mkdirSync(path.join(tmpDir, "src", "types"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "types", "widgets.ts"),
+      "export type ImageWidget = string;\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, "src", "sections"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "sections", "Foo.tsx"),
+      'import type { ImageWidget } from "~/types/widgets";\nexport const x: ImageWidget = "y";\n',
+    );
+  });
+
+  it("prints the finding and returns false (info doesn't fail strict)", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx, { strict: true });
+    expect(failed).toBe(false);
+    const out = spy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/Local src\/types\/widgets\.ts/);
+    expect(out).toMatch(/widgets\.ts/);
+    expect(out).toMatch(/deco-post-cleanup --fix/);
+    spy.mockRestore();
+  });
+});
+
+describe("cleanupAudit — warning findings (vtex-shim-regression)", () => {
+  beforeEach(() => {
+    // Trigger rule 5 (vtex-shim-regression, warning severity):
+    // any file outside src/lib/ that imports from ~/lib/vtex-*.
+    fs.mkdirSync(path.join(tmpDir, "src", "loaders"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "Product.ts"),
+      'import { fetchSafe } from "~/lib/vtex-fetch";\nexport default fetchSafe;\n',
+    );
+  });
+
+  it("returns false in non-strict mode even with warning findings", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx, { strict: false });
+    expect(failed).toBe(false);
+    spy.mockRestore();
+  });
+
+  it("returns true in --strict mode when warning findings exist", () => {
+    const spyLog = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx, { strict: true });
+    expect(failed).toBe(true);
+    const out = spyLog.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/--strict/);
+    expect(out).toMatch(/failed the audit/);
+    spyLog.mockRestore();
+  });
+});
+
+describe("cleanupAudit — output truncation", () => {
+  beforeEach(() => {
+    // Fabricate >5 vtex-shim-regression findings to test the cap.
+    fs.mkdirSync(path.join(tmpDir, "src", "loaders"), { recursive: true });
+    for (let i = 0; i < 8; i++) {
+      fs.writeFileSync(
+        path.join(tmpDir, "src", "loaders", `Loader${i}.ts`),
+        'import { fetchSafe } from "~/lib/vtex-fetch";\n',
+      );
+    }
+  });
+
+  it("caps per-rule output at 5 with a 'and N more' suffix", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    cleanupAudit(ctx);
+    const out = spy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/and 3 more/);
+    spy.mockRestore();
+  });
+});

package/scripts/migrate/phase-cleanup-audit.ts

@@ -0,0 +1,105 @@
+/**
+ * Phase 9: Post-Migration Cleanup Audit
+ *
+ * Runs the same `deco-post-cleanup` audit logic as the standalone CLI,
+ * but inline at the tail of `deco-migrate`. The goal is to surface any
+ * residual debt the migration script can't fix on its own (e.g.
+ * silent vtex shim regressions, orphan TODOs, manual-review items)
+ * the moment the migration completes — without making the user
+ * remember a separate command.
+ *
+ * Behaviour:
+ * - Always READ-ONLY. Auto-fix is opt-in via the standalone CLI's
+ *   `--fix` flag — never invoked from inside the migration script
+ *   to keep the migration's mutation surface predictable.
+ * - Skipped in dry-run (no migrated output to scan).
+ * - Skipped via `--no-cleanup-audit` when integrated runs are noisy.
+ * - In `--strict` mode, returns true (caller exits 2) if any
+ *   warning-severity findings exist. Info findings never fail the
+ *   build — they're just hints.
+ */
+
+import { banner, bold, gray, green, red, yellow } from "./colors";
+import { realFsAdapter, runAudit } from "./post-cleanup/runner";
+import type { AuditReport, Severity } from "./post-cleanup/types";
+import type { MigrationContext } from "./types";
+
+export interface CleanupAuditOptions {
+  /** Promote warning findings to fatal (exit 2 from main). Default: false. */
+  strict?: boolean;
+}
+
+/**
+ * Returns `true` when the caller should exit with a non-zero code.
+ * Always false in normal mode — audit is informational by default.
+ */
+export function cleanupAudit(ctx: MigrationContext, opts: CleanupAuditOptions = {}): boolean {
+  if (ctx.dryRun) {
+    return false;
+  }
+
+  banner("Phase 9: Post-Migration Cleanup Audit");
+
+  const report = runAudit(ctx.sourceDir, realFsAdapter);
+
+  if (report.totalFindings === 0) {
+    console.log(`  ${green("✓")} No findings — migration output is clean.`);
+    return false;
+  }
+
+  printSummary(report);
+
+  const warnings = countSeverity(report, "warning");
+  const infos = countSeverity(report, "info");
+  const willFail = (opts.strict ?? false) && warnings > 0;
+
+  console.log("");
+  console.log(
+    `  ${bold("Audit:")} ${report.totalFindings} finding(s) — ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`,
+  );
+  console.log(
+    `  ${gray("Run")} ${bold("deco-post-cleanup --fix")} ${gray("from this directory to auto-correct the safe rules,")}`,
+  );
+  console.log(`  ${gray("or see post-migration-cleanup.md for the full per-rule playbook.")}`);
+
+  if (willFail) {
+    console.log(
+      `\n  ${red("--strict:")} ${warnings} warning-severity finding(s) failed the audit.`,
+    );
+    return true;
+  }
+
+  return false;
+}
+
+function severityTag(sev: Severity, text: string): string {
+  if (sev === "warning") return yellow(text);
+  return gray(text);
+}
+
+function printSummary(report: AuditReport): void {
+  let idx = 0;
+  for (const summary of report.rules) {
+    idx++;
+    if (summary.findings.length === 0) continue;
+    const headColor = yellow;
+    console.log(
+      `  ${headColor(`[${idx}] ${summary.title}`)} ${gray(`(${summary.findings.length} found)`)}`,
+    );
+    // Cap the per-rule output so a noisy site doesn't drown the
+    // migration's own report. Standalone CLI shows everything.
+    const visible = summary.findings.slice(0, 5);
+    for (const f of visible) {
+      const tag = severityTag(f.severity, `[${f.severity.toUpperCase()}]`);
+      console.log(`      ${tag} ${bold(f.file)} — ${f.message}`);
+    }
+    const hidden = summary.findings.length - visible.length;
+    if (hidden > 0) {
+      console.log(`      ${gray(`...and ${hidden} more (run deco-post-cleanup for full list)`)}`);
+    }
+  }
+}
+
+function countSeverity(report: AuditReport, sev: Severity): number {
+  return report.rules.flatMap((r) => r.findings).filter((f) => f.severity === sev).length;
+}

package/scripts/migrate.ts

@@ -30,6 +30,7 @@ import { banner, green, red, stat, yellow } from "./migrate/colors";
 import { loadConfig, validateConfig } from "./migrate/config";
 import { analyze } from "./migrate/phase-analyze";
 import { cleanup } from "./migrate/phase-cleanup";
+import { cleanupAudit } from "./migrate/phase-cleanup-audit";
 import { compile } from "./migrate/phase-compile";
 import { report } from "./migrate/phase-report";
 import { scaffold } from "./migrate/phase-scaffold";
@@ -46,6 +47,7 @@ function parseArgs(args: string[]): {
   strict: boolean;
   withBuild: boolean;
   noCompile: boolean;
+  noCleanupAudit: boolean;
 } {
   let source = ".";
   let dryRun = false;
@@ -54,6 +56,7 @@ function parseArgs(args: string[]): {
   let strict = false;
   let withBuild = false;
   let noCompile = false;
+  let noCleanupAudit = false;
 
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
@@ -75,6 +78,9 @@ function parseArgs(args: string[]): {
       case "--no-compile":
         noCompile = true;
         break;
+      case "--no-cleanup-audit":
+        noCleanupAudit = true;
+        break;
       case "--help":
       case "-h":
         help = true;
@@ -82,7 +88,16 @@ function parseArgs(args: string[]): {
     }
   }
 
-  return { source, dryRun, verbose, help, strict, withBuild, noCompile };
+  return {
+    source,
+    dryRun,
+    verbose,
+    help,
+    strict,
+    withBuild,
+    noCompile,
+    noCleanupAudit,
+  };
 }
 
 function showHelp() {
@@ -93,13 +108,15 @@ function showHelp() {
     npx -p @decocms/start deco-migrate [options]
 
   Options:
-    --source <dir>    Source directory (default: .)
-    --dry-run         Preview changes without writing files
-    --verbose         Show detailed output for every file
-    --strict          Fail (exit 2) when typecheck/build report errors
-    --with-build      Also run \`vite build\` after typecheck (slower)
-    --no-compile      Skip the post-bootstrap compile phase entirely
-    --help, -h        Show this help message
+    --source <dir>        Source directory (default: .)
+    --dry-run             Preview changes without writing files
+    --verbose             Show detailed output for every file
+    --strict              Fail (exit 2) when typecheck/build report errors
+    --with-build          Also run \`vite build\` after typecheck (slower)
+    --no-compile          Skip the post-bootstrap compile phase entirely
+    --no-cleanup-audit    Skip the post-migration cleanup audit (run separately
+                          via \`deco-post-cleanup\` if needed)
+    --help, -h            Show this help message
 
   Examples:
     npx -p @decocms/start deco-migrate --dry-run --verbose
@@ -191,6 +208,17 @@ async function main() {
         process.exit(2);
       }
     }
+
+    // Phase 9: Post-migration cleanup audit
+    // Read-only scan that catches residual debt the migration script
+    // can't (or won't) fix. Always informational unless --strict is on,
+    // in which case warning-severity findings exit 2.
+    if (!opts.noCleanupAudit) {
+      const auditFailed = cleanupAudit(ctx, { strict: opts.strict });
+      if (auditFailed) {
+        process.exit(2);
+      }
+    }
   } catch (error) {
     console.error(`\n  ${red("Migration failed:")}`, error);
     process.exit(1);