@decocms/start 2.10.0 → 2.12.0

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

package/scripts/migrate-post-cleanup.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env tsx
+/**
+ * Post-Migration Cleanup Audit
+ *
+ * Read-only audit that scans a migrated site for dead code and obsolete
+ * boilerplate that the framework now owns. Mirrors the human checklist at
+ * `.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md`
+ * but turns it into something CI can actually run.
+ *
+ * Usage (from a migrated site directory):
+ *   npx -p @decocms/start deco-post-cleanup
+ *   npx -p @decocms/start deco-post-cleanup --json
+ *
+ * Options:
+ *   --source <dir>   Site directory to audit (default: current directory)
+ *   --json           Emit machine-readable JSON instead of pretty text
+ *   --strict         Exit code 2 if any warning-severity findings exist
+ *   --help, -h       Show this help
+ *
+ * This script is intentionally read-only. Auto-fix support (`--fix`) is
+ * a planned follow-up — see the SKILL doc.
+ */
+
+import * as path from "node:path";
+import { banner, bold, cyan, gray, green, red, yellow } from "./migrate/colors";
+import { realFsAdapter, realFsWriter, runAudit } from "./migrate/post-cleanup/runner";
+import type { AuditReport, Severity } from "./migrate/post-cleanup/types";
+
+interface CliOpts {
+  source: string;
+  json: boolean;
+  strict: boolean;
+  help: boolean;
+  fix: boolean;
+}
+
+function parseArgs(args: string[]): CliOpts {
+  let source = ".";
+  let json = false;
+  let strict = false;
+  let help = false;
+  let fix = false;
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--source":
+        source = args[++i];
+        break;
+      case "--json":
+        json = true;
+        break;
+      case "--strict":
+        strict = true;
+        break;
+      case "--fix":
+        fix = true;
+        break;
+      case "--help":
+      case "-h":
+        help = true;
+        break;
+    }
+  }
+  return { source, json, strict, help, fix };
+}
+
+function showHelp() {
+  console.log(`
+  @decocms/start — Post-Migration Cleanup Audit
+
+  Scans a migrated site for dead code and obsolete boilerplate that the
+  framework now owns. Read-only — prints findings, does not modify files.
+
+  Usage:
+    npx -p @decocms/start deco-post-cleanup [options]
+
+  Options:
+    --source <dir>   Site directory to audit (default: .)
+    --fix            Auto-apply mechanical fixes for the safe rules
+                     (dead-lib-shims, dead-runtime-shim, local-widgets-types).
+                     Other rules still detect-only.
+    --json           Emit machine-readable JSON instead of pretty text
+    --strict         Exit code 2 if any warning-severity findings exist
+    --help, -h       Show this help
+
+  Examples:
+    npx -p @decocms/start deco-post-cleanup
+    npx -p @decocms/start deco-post-cleanup --source ./my-site --json
+    npx -p @decocms/start deco-post-cleanup --fix
+    npx -p @decocms/start deco-post-cleanup --fix --strict   # fail CI if anything left
+
+  See: .agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md
+  `);
+}
+
+function severityColor(sev: Severity, text: string): string {
+  if (sev === "warning") return yellow(text);
+  return gray(text);
+}
+
+function printText(report: AuditReport, fixMode: boolean): void {
+  banner(fixMode ? "Post-Migration Cleanup Audit (--fix)" : "Post-Migration Cleanup Audit");
+  console.log(`  ${gray("Site:")} ${bold(report.site)}`);
+  console.log(`  ${gray("Findings:")} ${bold(String(report.totalFindings))}`);
+  if (fixMode) {
+    console.log(`  ${gray("Auto-fixed:")} ${bold(String(report.totalFixActions))}`);
+  }
+  console.log("");
+
+  let idx = 0;
+  for (const summary of report.rules) {
+    idx++;
+    const count = summary.findings.length;
+    const fixCount = summary.fixes?.length ?? 0;
+    const headColor = count === 0 ? green : yellow;
+    const suffix = fixMode
+      ? gray(`(${count} found, ${fixCount} fixed${summary.supportsAutoFix ? "" : ", manual"})`)
+      : gray(`(${count} found)`);
+    console.log(`${headColor(`[${idx}] ${summary.title}`)} ${suffix}`);
+    for (const f of summary.findings) {
+      const tag = severityColor(f.severity, `[${f.severity.toUpperCase()}]`);
+      console.log(`    ${tag} ${bold(f.file)} — ${f.message}`);
+      if (f.fix && !summary.fixes) {
+        console.log(`        ${gray("fix:")} ${f.fix}`);
+      }
+    }
+    if (summary.fixes) {
+      for (const a of summary.fixes) {
+        console.log(`    ${cyan("[FIXED]")} ${bold(a.file)} — ${a.detail}`);
+      }
+    }
+    if (count === 0) console.log(`    ${gray("(nothing to clean up)")}`);
+    console.log("");
+  }
+
+  const warnings = report.rules
+    .flatMap((r) => r.findings)
+    .filter((f) => f.severity === "warning").length;
+  const infos = report.totalFindings - warnings;
+  const tail = fixMode
+    ? `${report.totalFindings} finding(s) — ${cyan(`${report.totalFixActions} auto-fixed`)}, ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`
+    : `${report.totalFindings} finding(s) — ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`;
+  console.log(`${bold("Summary:")} ${tail}`);
+  if (report.totalFindings > 0) {
+    const hint = fixMode
+      ? "  Some rules require manual fixes — see post-migration-cleanup.md."
+      : "  Run with --fix to auto-correct the safe rules, or see post-migration-cleanup.md.";
+    console.log(gray(hint));
+  }
+}
+
+function printJson(report: AuditReport): void {
+  console.log(JSON.stringify(report, null, 2));
+}
+
+function shouldFail(report: AuditReport, strict: boolean): boolean {
+  if (!strict) return false;
+  return report.rules.some((r) => r.findings.some((f) => f.severity === "warning"));
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const siteDir = path.resolve(opts.source);
+  const report = runAudit(siteDir, realFsAdapter, {
+    writer: opts.fix ? realFsWriter : undefined,
+  });
+
+  if (opts.json) {
+    printJson(report);
+  } else {
+    printText(report, opts.fix);
+  }
+
+  if (shouldFail(report, opts.strict)) {
+    process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  console.error(red(`Audit failed: ${(err as Error).message}`));
+  process.exit(1);
+});

package/scripts/migrate.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env tsx
+
 /**
  * Migration Script: Fresh/Deno/Preact → TanStack Start/React/Cloudflare Workers
  *
@@ -23,18 +24,19 @@
  *   6. Verify   — Smoke test the migrated output
  */
 
-import * as path from "node:path";
 import { execSync } from "node:child_process";
+import * as path from "node:path";
+import { banner, green, red, stat, yellow } from "./migrate/colors";
 import { loadConfig, validateConfig } from "./migrate/config";
-import { createContext, logPhase } from "./migrate/types";
 import { analyze } from "./migrate/phase-analyze";
-import { scaffold } from "./migrate/phase-scaffold";
-import { transform } from "./migrate/phase-transform";
 import { cleanup } from "./migrate/phase-cleanup";
+import { compile } from "./migrate/phase-compile";
 import { report } from "./migrate/phase-report";
+import { scaffold } from "./migrate/phase-scaffold";
+import { transform } from "./migrate/phase-transform";
 import { verify } from "./migrate/phase-verify";
-import { compile } from "./migrate/phase-compile";
-import { banner, stat, red, green, yellow } from "./migrate/colors";
+import { detectSourceLayout, explainNonClassicLayout } from "./migrate/source-layout";
+import { createContext, logPhase } from "./migrate/types";
 
 function parseArgs(args: string[]): {
   source: string;
@@ -137,6 +139,19 @@ async function main() {
     config: siteConfig,
   });
 
+  // Phase 0: Source-layout detection (early-abort for unsupported layouts).
+  // The analyzer assumes a classic root layout (sections/, islands/, ...);
+  // running it on a modern src/ layout silently yields a near-empty
+  // migration. Detect-and-abort here so the user gets an actionable error
+  // before we touch any files.
+  const layout = detectSourceLayout(sourceDir);
+  if (layout !== "classic") {
+    console.error(red(`Error: ${layout} source layout`));
+    console.error("");
+    console.error(explainNonClassicLayout(layout, sourceDir));
+    process.exit(2);
+  }
+
   try {
     // Phase 1: Analyze source
     analyze(ctx);
@@ -210,7 +225,9 @@ function bootstrap(ctx: { sourceDir: string }) {
   run("npx tsr generate", "Generate TanStack routes");
 
   if (failures > 0) {
-    console.log(`\n  ${yellow("Bootstrap completed with warnings.")} Check errors above before running dev.\n`);
+    console.log(
+      `\n  ${yellow("Bootstrap completed with warnings.")} Check errors above before running dev.\n`,
+    );
   } else {
     console.log(`\n  ${green("Ready!")} Run \`${pm} run dev\` to start the dev server.\n`);
   }