@decocms/start 2.9.0 → 2.11.0

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

@@ -0,0 +1,66 @@
+/**
+ * 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[];
+}
+
+export interface AuditReport {
+  site: string;
+  rules: RuleSummary[];
+  totalFindings: 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;
+}
+
+export interface Rule {
+  id: string;
+  title: string;
+  run(ctx: RuleContext): Finding[];
+}

package/scripts/migrate/transforms/section-conventions.ts

@@ -1,4 +1,8 @@
-import type { TransformResult, SectionMeta } from "../types";
+import type {
+	SectionConventionSets,
+} from "../config";
+import { resolveSectionConventions } from "../config";
+import type { SectionMeta, TransformResult } from "../types";
 
 /**
  * Adds section convention exports (sync, eager, layout, cache)
@@ -6,158 +10,179 @@ import type { TransformResult, SectionMeta } from "../types";
  *
  * These exports are read by generate-sections.ts in @decocms/start
  * to build the sections.gen.ts registry.
+ *
+ * The set of section *names* that get hints applied is configurable
+ * via `.deco-migrate.config.json` (see `migrate/config.ts`). The exported
+ * `transformSectionConventions` keeps a back-compat signature using the
+ * baked-in defaults; new callers should prefer
+ * `createSectionConventionsTransform(sets)` so config can drive the lists.
  */
 
-const EAGER_SYNC_SECTIONS = new Set([
-  "UtilLinks",
-  "DepartamentList",
-  "ImageGallery",
-  "BannersGrid",
-  "Carousel",
-  "Tipbar",
-  "Live",
-]);
-
-const SYNC_SECTIONS = new Set([
-  "ProductShelf",
-  "ProductShelfTabbed",
-  "ProductShelfGroup",
-  "ProductShelfTopSort",
-  "CouponList",
-  "NotFoundChallenge",
-  "MountedPDP",
-  "BackgroundWrapper",
-  "SearchResult",
-  "LpCartao",
-]);
-
-const LISTING_CACHE_SECTIONS = new Set([
-  "ProductShelf",
-  "ProductShelfTabbed",
-  "ProductShelfGroup",
-  "ProductShelfTimedOffers",
-]);
-
-const STATIC_CACHE_SECTIONS = new Set([
-  "InstagramPosts",
-  "Faq",
-]);
-
 function getSectionBasename(filePath: string): string {
-  return filePath.split("/").pop()?.replace(/\.\w+$/, "") || "";
+	return filePath.split("/").pop()?.replace(/\.\w+$/, "") || "";
+}
+
+/**
+ * Build a `transformSectionConventions` closure bound to the given
+ * resolved sets. This is the preferred entry point — the caller (usually
+ * `phase-transform`) loads config once and passes the sets in.
+ */
+export function createSectionConventionsTransform(
+	sets: SectionConventionSets,
+) {
+	return (
+		content: string,
+		sectionMeta: SectionMeta | undefined,
+	): TransformResult => transformWithSets(content, sectionMeta, sets);
 }
 
+/** Default-configured transform. Uses the baked-in defaults from `config.ts`. */
+const defaultSets = resolveSectionConventions(null);
+
 export function transformSectionConventions(
-  content: string,
-  sectionMeta: SectionMeta | undefined,
+	content: string,
+	sectionMeta: SectionMeta | undefined,
+): TransformResult {
+	return transformWithSets(content, sectionMeta, defaultSets);
+}
+
+function transformWithSets(
+	content: string,
+	sectionMeta: SectionMeta | undefined,
+	sets: SectionConventionSets,
 ): TransformResult {
-  if (!sectionMeta) {
-    return { content, changed: false, notes: [] };
-  }
-
-  const notes: string[] = [];
-  let result = content;
-  let changed = false;
-  const basename = getSectionBasename(sectionMeta.path);
-
-  // Header, footer, theme → eager + sync + layout
-  if (sectionMeta.isHeader || sectionMeta.isFooter || sectionMeta.isTheme) {
-    if (!result.includes("export const eager")) {
-      result += "\nexport const eager = true;\n";
-      notes.push("Added: export const eager = true");
-      changed = true;
-    }
-    if (!result.includes("export const sync")) {
-      result += "export const sync = true;\n";
-      notes.push("Added: export const sync = true");
-      changed = true;
-    }
-    // Header in golden does NOT have layout=true; only footer+theme do
-    if ((sectionMeta.isFooter || sectionMeta.isTheme) && !result.includes("export const layout")) {
-      result += "export const layout = true;\n";
-      notes.push("Added: export const layout = true");
-      changed = true;
-    }
-  }
-
-  // Known eager+sync sections (non-layout)
-  if (EAGER_SYNC_SECTIONS.has(basename)) {
-    if (!result.includes("export const eager")) {
-      result += "\nexport const eager = true;\n";
-      notes.push(`Added: export const eager = true (${basename})`);
-      changed = true;
-    }
-    if (!result.includes("export const sync")) {
-      result += "export const sync = true;\n";
-      notes.push(`Added: export const sync = true (${basename})`);
-      changed = true;
-    }
-  }
-
-  // Known sync-only sections
-  if (SYNC_SECTIONS.has(basename) && !result.includes("export const sync")) {
-    result += "\nexport const sync = true;\n";
-    notes.push(`Added: export const sync = true (${basename})`);
-    changed = true;
-  }
-
-  // Listing cache sections
-  if (LISTING_CACHE_SECTIONS.has(basename) && !result.includes("export const cache")) {
-    result += '\nexport const cache = "listing";\n';
-    notes.push(`Added: export const cache = "listing" (${basename})`);
-    changed = true;
-  }
-
-  // Static cache sections
-  if (STATIC_CACHE_SECTIONS.has(basename) && !result.includes("export const cache")) {
-    result += '\nexport const cache = "static";\n';
-    notes.push(`Added: export const cache = "static" (${basename})`);
-    changed = true;
-  }
-
-  // Generic: listing sections not already matched above
-  if (sectionMeta.isListing && !result.includes("export const cache")) {
-    result += '\nexport const cache = "listing";\n';
-    notes.push('Added: export const cache = "listing"');
-    changed = true;
-  }
-
-  // Sections with loaders that use device → add sync (needs SSR device detection)
-  if (sectionMeta.hasLoader && sectionMeta.loaderUsesDevice && !result.includes("export const sync")) {
-    result += "\nexport const sync = true;\n";
-    notes.push("Added: export const sync = true (loader uses device)");
-    changed = true;
-  }
-
-  // Sections that render nested Section children need sync so they're in
-  // the syncComponents registry (SectionRenderer resolves the string key).
-  const hasNestedSections =
-    /children:\s*Section\b/.test(result) || /fallback:\s*Section\b/.test(result);
-  if (hasNestedSections && !result.includes("export const sync")) {
-    result += "\nexport const sync = true;\n";
-    notes.push("Added: export const sync = true (renders nested Section children)");
-    changed = true;
-  }
-
-  // Re-export sections that wrap PDP/nested content need sync too.
-  // Detect: file is a re-export AND the target component renders nested Sections
-  const isReExport = /^export\s+\{[^}]*default[^}]*\}\s+from\s+/.test(result.trim());
-  if (isReExport && (basename === "MountedPDP" || basename === "NotFoundChallenge")) {
-    if (!result.includes("export const sync")) {
-      result += "\nexport const sync = true;\n";
-      notes.push(`Added: export const sync = true (re-export: ${basename})`);
-      changed = true;
-    }
-  }
-
-  // Don't add LoadingFallback re-exports to thin section files —
-  // we can't guarantee the target component exports it.
-  // Instead, if it's a listing section, a generic skeleton will be added below.
-
-  // Generate a basic LoadingFallback if the section doesn't have one
-  // and it's a listing section (visible skeleton improvement)
-  if (sectionMeta.isListing && !sectionMeta.hasLoadingFallback && !result.includes("LoadingFallback")) {
-    result += `
+	if (!sectionMeta) {
+		return { content, changed: false, notes: [] };
+	}
+
+	const notes: string[] = [];
+	let result = content;
+	let changed = false;
+	const basename = getSectionBasename(sectionMeta.path);
+
+	// Header, footer, theme → eager + sync + layout
+	if (sectionMeta.isHeader || sectionMeta.isFooter || sectionMeta.isTheme) {
+		if (!result.includes("export const eager")) {
+			result += "\nexport const eager = true;\n";
+			notes.push("Added: export const eager = true");
+			changed = true;
+		}
+		if (!result.includes("export const sync")) {
+			result += "export const sync = true;\n";
+			notes.push("Added: export const sync = true");
+			changed = true;
+		}
+		// Header in golden does NOT have layout=true; only footer+theme do
+		if (
+			(sectionMeta.isFooter || sectionMeta.isTheme) &&
+			!result.includes("export const layout")
+		) {
+			result += "export const layout = true;\n";
+			notes.push("Added: export const layout = true");
+			changed = true;
+		}
+	}
+
+	// Known eager+sync sections (non-layout)
+	if (sets.eagerSync.has(basename)) {
+		if (!result.includes("export const eager")) {
+			result += "\nexport const eager = true;\n";
+			notes.push(`Added: export const eager = true (${basename})`);
+			changed = true;
+		}
+		if (!result.includes("export const sync")) {
+			result += "export const sync = true;\n";
+			notes.push(`Added: export const sync = true (${basename})`);
+			changed = true;
+		}
+	}
+
+	// Known sync-only sections
+	if (sets.sync.has(basename) && !result.includes("export const sync")) {
+		result += "\nexport const sync = true;\n";
+		notes.push(`Added: export const sync = true (${basename})`);
+		changed = true;
+	}
+
+	// Listing cache sections
+	if (
+		sets.listingCache.has(basename) &&
+		!result.includes("export const cache")
+	) {
+		result += '\nexport const cache = "listing";\n';
+		notes.push(`Added: export const cache = "listing" (${basename})`);
+		changed = true;
+	}
+
+	// Static cache sections
+	if (
+		sets.staticCache.has(basename) &&
+		!result.includes("export const cache")
+	) {
+		result += '\nexport const cache = "static";\n';
+		notes.push(`Added: export const cache = "static" (${basename})`);
+		changed = true;
+	}
+
+	// Generic: listing sections not already matched above
+	if (sectionMeta.isListing && !result.includes("export const cache")) {
+		result += '\nexport const cache = "listing";\n';
+		notes.push('Added: export const cache = "listing"');
+		changed = true;
+	}
+
+	// Sections with loaders that use device → add sync (needs SSR device detection)
+	if (
+		sectionMeta.hasLoader &&
+		sectionMeta.loaderUsesDevice &&
+		!result.includes("export const sync")
+	) {
+		result += "\nexport const sync = true;\n";
+		notes.push("Added: export const sync = true (loader uses device)");
+		changed = true;
+	}
+
+	// Sections that render nested Section children need sync so they're in
+	// the syncComponents registry (SectionRenderer resolves the string key).
+	const hasNestedSections =
+		/children:\s*Section\b/.test(result) ||
+		/fallback:\s*Section\b/.test(result);
+	if (hasNestedSections && !result.includes("export const sync")) {
+		result += "\nexport const sync = true;\n";
+		notes.push(
+			"Added: export const sync = true (renders nested Section children)",
+		);
+		changed = true;
+	}
+
+	// Re-export sections that wrap PDP/nested content need sync too.
+	// Detect: file is a re-export AND the target component renders nested Sections
+	const isReExport = /^export\s+\{[^}]*default[^}]*\}\s+from\s+/.test(
+		result.trim(),
+	);
+	if (
+		isReExport &&
+		(basename === "MountedPDP" || basename === "NotFoundChallenge")
+	) {
+		if (!result.includes("export const sync")) {
+			result += "\nexport const sync = true;\n";
+			notes.push(`Added: export const sync = true (re-export: ${basename})`);
+			changed = true;
+		}
+	}
+
+	// Don't add LoadingFallback re-exports to thin section files —
+	// we can't guarantee the target component exports it.
+	// Instead, if it's a listing section, a generic skeleton will be added below.
+
+	// Generate a basic LoadingFallback if the section doesn't have one
+	// and it's a listing section (visible skeleton improvement)
+	if (
+		sectionMeta.isListing &&
+		!sectionMeta.hasLoadingFallback &&
+		!result.includes("LoadingFallback")
+	) {
+		result += `
 export function LoadingFallback() {
   return (
     <div className="w-full py-8">
@@ -177,9 +202,9 @@ export function LoadingFallback() {
   );
 }
 `;
-    notes.push("Added: LoadingFallback skeleton for listing section");
-    changed = true;
-  }
+		notes.push("Added: LoadingFallback skeleton for listing section");
+		changed = true;
+	}
 
-  return { content: result, changed, notes };
+	return { content: result, changed, notes };
 }

package/scripts/migrate/types.ts

@@ -137,6 +137,14 @@ export interface MigrationContext {
   vtexAccount: string | null;
   gtmId: string | null;
 
+  /**
+   * Per-site config loaded from `.deco-migrate.config.json`. `null` means
+   * no config file was present — defaults apply throughout. Imported
+   * lazily as `MigrateConfig` to avoid a circular dependency between
+   * `types.ts` and `config.ts`.
+   */
+  config?: import("./config").MigrateConfig | null;
+
   /** deno.json import map entries */
   importMap: Record<string, string>;
 
@@ -191,7 +199,11 @@ export interface TransformResult {
 
 export function createContext(
   sourceDir: string,
-  opts: { dryRun?: boolean; verbose?: boolean } = {},
+  opts: {
+    dryRun?: boolean;
+    verbose?: boolean;
+    config?: import("./config").MigrateConfig | null;
+  } = {},
 ): MigrationContext {
   return {
     sourceDir,
@@ -199,6 +211,7 @@ export function createContext(
     platform: "custom",
     vtexAccount: null,
     gtmId: null,
+    config: opts.config ?? null,
     importMap: {},
     discoveredNpmDeps: {},
     themeColors: {},

package/scripts/migrate-post-cleanup.ts

@@ -0,0 +1,156 @@
+#!/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, gray, green, red, yellow } from "./migrate/colors";
+import { realFsAdapter, 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;
+}
+
+function parseArgs(args: string[]): CliOpts {
+  let source = ".";
+  let json = false;
+  let strict = false;
+  let help = 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 "--help":
+      case "-h":
+        help = true;
+        break;
+    }
+  }
+  return { source, json, strict, help };
+}
+
+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: .)
+    --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
+
+  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): void {
+  banner("Post-Migration Cleanup Audit");
+  console.log(`  ${gray("Site:")} ${bold(report.site)}`);
+  console.log(`  ${gray("Findings:")} ${bold(String(report.totalFindings))}`);
+  console.log("");
+
+  let idx = 0;
+  for (const summary of report.rules) {
+    idx++;
+    const count = summary.findings.length;
+    const headColor = count === 0 ? green : yellow;
+    console.log(`${headColor(`[${idx}] ${summary.title}`)} ${gray(`(${count} found)`)}`);
+    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) console.log(`        ${gray("fix:")} ${f.fix}`);
+    }
+    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;
+  console.log(
+    `${bold("Summary:")} ${report.totalFindings} finding(s) — ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`,
+  );
+  if (report.totalFindings > 0) {
+    console.log(gray("  See post-migration-cleanup.md for the canonical fix steps per rule."));
+  }
+}
+
+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);
+
+  if (opts.json) {
+    printJson(report);
+  } else {
+    printText(report);
+  }
+
+  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

@@ -25,6 +25,7 @@
 
 import * as path from "node:path";
 import { execSync } from "node:child_process";
+import { loadConfig, validateConfig } from "./migrate/config";
 import { createContext, logPhase } from "./migrate/types";
 import { analyze } from "./migrate/phase-analyze";
 import { scaffold } from "./migrate/phase-scaffold";
@@ -121,9 +122,19 @@ async function main() {
   stat("Mode", opts.dryRun ? yellow("DRY RUN") : green("EXECUTE"));
   stat("Verbose", opts.verbose ? "yes" : "no");
 
+  // Load optional per-site config from `.deco-migrate.config.json`. Drives
+  // section-conventions hardcoded lists today; future fields will tune
+  // import rewrites, scaffolding, etc.
+  const siteConfig = loadConfig(sourceDir);
+  if (siteConfig) {
+    validateConfig(siteConfig);
+    stat("Config", green(".deco-migrate.config.json (loaded)"));
+  }
+
   const ctx = createContext(sourceDir, {
     dryRun: opts.dryRun,
     verbose: opts.verbose,
+    config: siteConfig,
   });
 
   try {