@decocms/blocks-cli 7.0.0

package/scripts/migrate/analyzers/section-metadata.ts

@@ -0,0 +1,147 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { MigrationContext, SectionMeta } from "../types";
+import { log } from "../types";
+
+const HEADER_RE = /\bheader\b/i;
+const FOOTER_RE = /\bfooter\b/i;
+const THEME_RE = /\btheme\b/i;
+const LISTING_RE = /\b(?:shelf|carousel|slider|product\s*list|search\s*result)\b/i;
+
+const LOADER_CONST_RE = /^export\s+const\s+loader\b/m;
+const LOADER_FN_RE = /^export\s+(?:async\s+)?function\s+loader\b/m;
+const LOADER_REEXPORT_RE = /^export\s*\{[^}]*\bloader\b[^}]*\}\s*from/m;
+const LOADING_FALLBACK_RE = /^export\s+(?:const|function)\s+LoadingFallback\b|^export\s*\{[^}]*LoadingFallback[^}]*\}/m;
+const JSDOC_TITLE_RE = /@title\b/;
+const JSDOC_DESC_RE = /@description\b/;
+const CTX_DEVICE_RE = /ctx\.device|useDevice|device.*(?:mobile|desktop)/i;
+const DEVICE_PROP_RE_BROAD = /\bdevice\b.*(?:mobile|desktop|tablet)|\bisMobile\b|\bis_mobile\b/i;
+const CTX_URL_RE = /ctx\.url|req\.url|ctx\.request|searchParam|pathname/i;
+const ASYNC_RE = /^export\s+async\s+function\s+loader\b/m;
+const STATUS_ONLY_RE = /ctx\.response\.status\s*=/;
+const IS_MOBILE_RE = /isMobile|is_mobile|ctx\.device\s*===?\s*["']mobile["']/i;
+const DEVICE_PROP_RE = /device\s*:\s*ctx\.device/;
+const REEXPORT_FROM_RE = /^export\s*\{[^}]*\}\s*from\s*["']([^"']+)["']/m;
+
+function isStatusOnlyLoader(content: string): boolean {
+  const loaderMatch = content.match(
+    /(?:export\s+const\s+loader\s*=|export\s+(?:async\s+)?function\s+loader)\s*[\s\S]*?\n(?=export\s|\z)/m,
+  );
+  if (!loaderMatch) return false;
+  const loaderBody = loaderMatch[0];
+  if (!STATUS_ONLY_RE.test(loaderBody)) return false;
+  const meaningful = loaderBody
+    .replace(/\/\/.*$/gm, "")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/ctx\.response\.status\s*=\s*\d+;?/g, "")
+    .replace(/return\s+props;?/g, "")
+    .replace(/if\s*\(props\.\w+\s*===?\s*null\)/g, "")
+    .replace(/export\s+(const|async\s+)?function\s+loader[^{]*\{/g, "")
+    .replace(/\};\s*$/g, "")
+    .trim();
+  return meaningful.replace(/[\s{}();,]/g, "").length < 30;
+}
+
+/**
+ * Resolve a re-export target path to an absolute file path.
+ * Handles `~/` prefix (mapped to `src/`) and relative paths.
+ */
+function resolveReExportTarget(importPath: string, sectionAbsPath: string, sourceDir: string): string | null {
+  let resolved: string;
+  if (importPath.startsWith("~/")) {
+    resolved = path.join(sourceDir, "src", importPath.slice(2));
+  } else if (importPath.startsWith("./") || importPath.startsWith("../")) {
+    resolved = path.resolve(path.dirname(sectionAbsPath), importPath);
+  } else {
+    return null;
+  }
+
+  const candidates = [
+    resolved + ".tsx", resolved + ".ts",
+    path.join(resolved, "index.tsx"), path.join(resolved, "index.ts"),
+    resolved, // might already have extension
+  ];
+
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+/**
+ * Try to read the content of the component that a section barrel re-exports from.
+ * Returns null if the section is not a barrel or the target can't be found.
+ */
+function readReExportTargetContent(content: string, sectionAbsPath: string, sourceDir: string): string | null {
+  const match = content.match(REEXPORT_FROM_RE);
+  if (!match) return null;
+
+  const targetPath = resolveReExportTarget(match[1], sectionAbsPath, sourceDir);
+  if (!targetPath) return null;
+
+  try {
+    return fs.readFileSync(targetPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export function extractSectionMetadata(ctx: MigrationContext): void {
+  const sectionFiles = ctx.files.filter(
+    (f) => f.category === "section" && f.action !== "delete",
+  );
+
+  for (const file of sectionFiles) {
+    let content: string;
+    try {
+      content = fs.readFileSync(file.absPath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const basename = path.basename(file.path, path.extname(file.path));
+    const dirName = path.dirname(file.path).split("/").pop() || "";
+    const parentDirs = path.dirname(file.path).split("/");
+
+    const hasLoaderConst = LOADER_CONST_RE.test(content);
+    const hasLoaderFn = LOADER_FN_RE.test(content);
+    const hasLoaderReExport = LOADER_REEXPORT_RE.test(content);
+    const hasLoader = hasLoaderConst || hasLoaderFn || hasLoaderReExport;
+
+    const isAccountSection = parentDirs.some((d) => d.toLowerCase() === "account");
+
+    // For re-export barrels, also check the target component for device/url usage
+    const targetContent = readReExportTargetContent(content, file.absPath, ctx.sourceDir);
+    const combined = targetContent ? content + "\n" + targetContent : content;
+
+    const usesDevice = CTX_DEVICE_RE.test(combined) || DEVICE_PROP_RE_BROAD.test(combined);
+    const usesUrl = CTX_URL_RE.test(combined);
+    const usesMobile = IS_MOBILE_RE.test(combined) && !DEVICE_PROP_RE.test(combined);
+
+    const meta: SectionMeta = {
+      path: file.path,
+      hasLoader,
+      loaderIsAsync: hasLoader && ASYNC_RE.test(combined),
+      hasLoadingFallback: LOADING_FALLBACK_RE.test(content) || (targetContent ? LOADING_FALLBACK_RE.test(targetContent) : false),
+      isHeader: HEADER_RE.test(basename) || HEADER_RE.test(dirName),
+      isFooter: FOOTER_RE.test(basename) || FOOTER_RE.test(dirName),
+      isTheme: THEME_RE.test(basename) || THEME_RE.test(dirName),
+      isListing: LISTING_RE.test(basename) || LISTING_RE.test(dirName),
+      hasTitle: JSDOC_TITLE_RE.test(content),
+      hasDescription: JSDOC_DESC_RE.test(content),
+      loaderUsesDevice: usesDevice,
+      loaderUsesUrl: hasLoader && usesUrl,
+      isAccountSection,
+      isStatusOnly: hasLoader && isStatusOnlyLoader(content),
+      usesMobileBoolean: usesMobile,
+    };
+
+    ctx.sectionMetas.push(meta);
+  }
+
+  const withLoader = ctx.sectionMetas.filter((m) => m.hasLoader).length;
+  const layouts = ctx.sectionMetas.filter((m) => m.isHeader || m.isFooter || m.isTheme).length;
+  const accounts = ctx.sectionMetas.filter((m) => m.isAccountSection).length;
+  const statusOnly = ctx.sectionMetas.filter((m) => m.isStatusOnly).length;
+  log(ctx, `Sections analyzed: ${ctx.sectionMetas.length} total, ${withLoader} with loader, ${layouts} layout, ${accounts} account, ${statusOnly} status-only`);
+}

package/scripts/migrate/analyzers/theme-extractor.ts

@@ -0,0 +1,122 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { MigrationContext } from "../types";
+import { log } from "../types";
+
+export interface ExtractedTheme {
+  /** Raw CSS variable -> hex color map from DEFAULT_THEME */
+  variables: Record<string, string>;
+  /** Font family string (from Theme.tsx or default_theme) */
+  fontFamily: string | null;
+  /** DaisyUI semantic colors derived from the brand palette */
+  daisyUiColors: Record<string, string>;
+}
+
+const DAISYUI_MAPPING: Record<string, string[]> = {
+  "--color-primary": ["--brand-primary-1"],
+  "--color-secondary": ["--brand-secondary-1"],
+  "--color-accent": ["--brand-terciary-1", "--brand-terciary-base"],
+  "--color-neutral": ["--neutral-900", "--neutral-1"],
+  "--color-base-100": ["--neutral-0", "--neutral-50"],
+  "--color-base-200": ["--brand-secondary-50", "--neutral-100"],
+  "--color-base-300": ["--brand-secondary-500", "--neutral-500"],
+  "--color-info": ["--information"],
+  "--color-success": ["--success"],
+  "--color-warning": ["--warning"],
+  "--color-error": ["--error"],
+};
+
+function extractDefaultTheme(sourceDir: string): Record<string, string> | null {
+  const candidates = [
+    "styles/default_theme.ts",
+    "styles/defaultTheme.ts",
+    "sdk/default_theme.ts",
+  ];
+
+  for (const candidate of candidates) {
+    const filePath = path.join(sourceDir, candidate);
+    if (!fs.existsSync(filePath)) continue;
+
+    const content = fs.readFileSync(filePath, "utf-8");
+
+    const vars: Record<string, string> = {};
+    const entryRe = /["'](--.+?)["']\s*:\s*["'](.+?)["']/g;
+    let match: RegExpExecArray | null;
+    while ((match = entryRe.exec(content)) !== null) {
+      vars[match[1]] = match[2];
+    }
+
+    if (Object.keys(vars).length > 0) return vars;
+  }
+
+  return null;
+}
+
+function extractFontFamily(sourceDir: string): string | null {
+  const candidates = [
+    "sections/Theme/Theme.tsx",
+    "sections/theme/Theme.tsx",
+  ];
+
+  for (const candidate of candidates) {
+    const filePath = path.join(sourceDir, candidate);
+    if (!fs.existsSync(filePath)) continue;
+
+    const content = fs.readFileSync(filePath, "utf-8");
+
+    const fontMatch = content.match(
+      /["']--font-family["']\s*,\s*\n?\s*["'](.*?)["']/,
+    );
+    if (fontMatch) {
+      return fontMatch[1].split(",")[0].trim();
+    }
+
+    const fontMatch2 = content.match(
+      /font.*?["']([\w\s]+(?:,\s*[\w\s-]+)*)/i,
+    );
+    if (fontMatch2) {
+      const family = fontMatch2[1].split(",")[0].trim();
+      if (family && family !== "sans-serif") return family;
+    }
+  }
+
+  return null;
+}
+
+function deriveDaisyUiColors(vars: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  for (const [daisyKey, sourceKeys] of Object.entries(DAISYUI_MAPPING)) {
+    for (const sourceKey of sourceKeys) {
+      if (vars[sourceKey]) {
+        result[daisyKey] = vars[sourceKey];
+        break;
+      }
+    }
+  }
+
+  return result;
+}
+
+export function extractTheme(ctx: MigrationContext): ExtractedTheme {
+  const vars = extractDefaultTheme(ctx.sourceDir);
+
+  if (!vars) {
+    log(ctx, "No styles/default_theme.ts found — using placeholder theme");
+    return {
+      variables: {},
+      fontFamily: ctx.fontFamily,
+      daisyUiColors: {},
+    };
+  }
+
+  const fontFamily = extractFontFamily(ctx.sourceDir) || ctx.fontFamily;
+  const daisyUiColors = deriveDaisyUiColors(vars);
+
+  log(
+    ctx,
+    `Theme extracted: ${Object.keys(vars).length} variables, ${Object.keys(daisyUiColors).length} DaisyUI colors, font: ${fontFamily || "none"}`,
+  );
+
+  return { variables: vars, fontFamily, daisyUiColors };
+}

package/scripts/migrate/colors.ts

@@ -0,0 +1,46 @@
+/**
+ * Terminal color utilities — keeps output readable without adding dependencies.
+ */
+
+const isColorSupported =
+  typeof process !== "undefined" &&
+  process.stdout?.isTTY &&
+  !process.env.NO_COLOR;
+
+function wrap(code: number, resetCode: number) {
+  return (text: string) =>
+    isColorSupported ? `\x1b[${code}m${text}\x1b[${resetCode}m` : text;
+}
+
+export const bold = wrap(1, 22);
+export const dim = wrap(2, 22);
+export const red = wrap(31, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const blue = wrap(34, 39);
+export const cyan = wrap(36, 39);
+export const gray = wrap(90, 39);
+
+export const icons = {
+  success: isColorSupported ? "\x1b[32m✓\x1b[0m" : "[OK]",
+  error: isColorSupported ? "\x1b[31m✗\x1b[0m" : "[FAIL]",
+  warning: isColorSupported ? "\x1b[33m⚠\x1b[0m" : "[WARN]",
+  info: isColorSupported ? "\x1b[34mℹ\x1b[0m" : "[INFO]",
+  arrow: isColorSupported ? "\x1b[36m→\x1b[0m" : "->",
+  bullet: isColorSupported ? "\x1b[90m•\x1b[0m" : "-",
+};
+
+export function banner(text: string) {
+  const line = "═".repeat(58);
+  console.log(`\n${cyan(`╔${line}╗`)}`);
+  console.log(`${cyan("║")}  ${bold(text.padEnd(56))}${cyan("║")}`);
+  console.log(`${cyan(`╚${line}╝`)}`);
+}
+
+export function phase(name: string) {
+  console.log(`\n${bold(blue(`━━━ ${name} ━━━`))}\n`);
+}
+
+export function stat(label: string, value: string | number) {
+  console.log(`  ${gray(label + ":")} ${bold(String(value))}`);
+}

package/scripts/migrate/config.test.ts

@@ -0,0 +1,202 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+	DEFAULT_SECTION_CONVENTIONS,
+	loadConfig,
+	resolveSectionConventions,
+	validateConfig,
+} from "./config";
+
+describe("loadConfig", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "config-test-"));
+	});
+
+	afterEach(() => {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("returns null when the config file is missing", () => {
+		expect(loadConfig(tmpDir)).toBeNull();
+	});
+
+	it("loads valid JSON", () => {
+		const content = JSON.stringify({
+			sectionConventions: { extend: { sync: ["MySection"] } },
+		});
+		fs.writeFileSync(
+			path.join(tmpDir, ".deco-migrate.config.json"),
+			content,
+			"utf-8",
+		);
+		const config = loadConfig(tmpDir);
+		expect(config).toEqual({
+			sectionConventions: { extend: { sync: ["MySection"] } },
+		});
+	});
+
+	it("throws with a helpful error on malformed JSON", () => {
+		fs.writeFileSync(
+			path.join(tmpDir, ".deco-migrate.config.json"),
+			"not valid json{",
+			"utf-8",
+		);
+		expect(() => loadConfig(tmpDir)).toThrow(
+			/Failed to parse.*Expected valid JSON/s,
+		);
+	});
+});
+
+describe("resolveSectionConventions", () => {
+	it("returns the defaults when config is null", () => {
+		const sets = resolveSectionConventions(null);
+		expect(sets.eagerSync.has("UtilLinks")).toBe(true);
+		expect(sets.sync.has("ProductShelf")).toBe(true);
+		expect(sets.listingCache.has("ProductShelf")).toBe(true);
+		expect(sets.staticCache.has("Faq")).toBe(true);
+	});
+
+	it("preserves all default eagerSync entries", () => {
+		const sets = resolveSectionConventions(null);
+		for (const name of DEFAULT_SECTION_CONVENTIONS.eagerSync ?? []) {
+			expect(sets.eagerSync.has(name)).toBe(true);
+		}
+	});
+
+	it("extend mode adds to defaults", () => {
+		const sets = resolveSectionConventions({
+			sectionConventions: {
+				extend: { sync: ["MySection"], staticCache: ["MyStatic"] },
+			},
+		});
+		// Default still present
+		expect(sets.sync.has("ProductShelf")).toBe(true);
+		// Extension added
+		expect(sets.sync.has("MySection")).toBe(true);
+		// Default static still present
+		expect(sets.staticCache.has("Faq")).toBe(true);
+		// Extension added
+		expect(sets.staticCache.has("MyStatic")).toBe(true);
+	});
+
+	it("extend mode handles partial extensions (only some categories)", () => {
+		const sets = resolveSectionConventions({
+			sectionConventions: { extend: { eagerSync: ["FrontFacing"] } },
+		});
+		// All defaults still present in untouched categories
+		expect(sets.sync.has("ProductShelf")).toBe(true);
+		expect(sets.staticCache.has("Faq")).toBe(true);
+		// Extension added
+		expect(sets.eagerSync.has("FrontFacing")).toBe(true);
+		// Defaults still present in extended category
+		expect(sets.eagerSync.has("UtilLinks")).toBe(true);
+	});
+
+	it("replace mode discards defaults", () => {
+		const sets = resolveSectionConventions({
+			sectionConventions: {
+				replace: { sync: ["OnlyThis"] },
+			},
+		});
+		// Default removed
+		expect(sets.sync.has("ProductShelf")).toBe(false);
+		// Replacement present
+		expect(sets.sync.has("OnlyThis")).toBe(true);
+		// Untouched categories empty
+		expect(sets.eagerSync.size).toBe(0);
+		expect(sets.listingCache.size).toBe(0);
+		expect(sets.staticCache.size).toBe(0);
+	});
+
+	it("replace mode is full replacement, not partial overlay", () => {
+		const sets = resolveSectionConventions({
+			sectionConventions: {
+				replace: {
+					eagerSync: ["X"],
+					sync: ["Y"],
+					listingCache: ["Z"],
+					staticCache: ["W"],
+				},
+			},
+		});
+		expect(Array.from(sets.eagerSync)).toEqual(["X"]);
+		expect(Array.from(sets.sync)).toEqual(["Y"]);
+		expect(Array.from(sets.listingCache)).toEqual(["Z"]);
+		expect(Array.from(sets.staticCache)).toEqual(["W"]);
+	});
+
+	it("returns empty sets when given empty arrays in replace", () => {
+		const sets = resolveSectionConventions({
+			sectionConventions: { replace: {} },
+		});
+		expect(sets.eagerSync.size).toBe(0);
+		expect(sets.sync.size).toBe(0);
+		expect(sets.listingCache.size).toBe(0);
+		expect(sets.staticCache.size).toBe(0);
+	});
+
+	it("returns defaults when sectionConventions is undefined", () => {
+		const sets = resolveSectionConventions({});
+		expect(sets.sync.has("ProductShelf")).toBe(true);
+	});
+});
+
+describe("validateConfig", () => {
+	it("accepts an empty config", () => {
+		expect(() => validateConfig({})).not.toThrow();
+	});
+
+	it("accepts a config with extend", () => {
+		expect(() =>
+			validateConfig({
+				sectionConventions: { extend: { sync: ["Foo"] } },
+			}),
+		).not.toThrow();
+	});
+
+	it("accepts a config with replace", () => {
+		expect(() =>
+			validateConfig({
+				sectionConventions: { replace: { sync: ["Foo"] } },
+			}),
+		).not.toThrow();
+	});
+
+	it("rejects non-object root", () => {
+		expect(() => validateConfig("bad")).toThrow(
+			/must be a JSON object/,
+		);
+	});
+
+	it("rejects non-object sectionConventions", () => {
+		expect(() => validateConfig({ sectionConventions: "bad" })).toThrow(
+			/sectionConventions must be an object/,
+		);
+	});
+
+	it("rejects non-array values in convention lists", () => {
+		expect(() =>
+			validateConfig({
+				sectionConventions: { extend: { sync: "not-an-array" } },
+			}),
+		).toThrow(/must be string\[\]/);
+	});
+
+	it("rejects non-string entries in convention lists", () => {
+		expect(() =>
+			validateConfig({
+				sectionConventions: { extend: { sync: [1, 2, 3] } },
+			}),
+		).toThrow(/must be string\[\]/);
+	});
+
+	it("ignores unknown top-level fields gracefully", () => {
+		expect(() =>
+			validateConfig({ unknownField: 123, sectionConventions: {} }),
+		).not.toThrow();
+	});
+});

package/scripts/migrate/config.ts

@@ -0,0 +1,186 @@
+/**
+ * Per-site migration configuration.
+ *
+ * Looks for `.deco-migrate.config.json` next to the source root. The file
+ * is optional — without it the script falls back to a baked-in default set
+ * of section-convention names that work for `casaevideo` and most other
+ * Deco/VTEX sites that derived from the same template.
+ *
+ * The defaults are kept here (not in `transforms/section-conventions.ts`)
+ * so that:
+ *   1. They live alongside the schema that consumes them.
+ *   2. They can be overridden per site without forking the transform.
+ *   3. Other phases (analyze, report) can read them too.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Names of section files that get framework hints applied during the
+ * `transformSectionConventions` step.
+ *
+ * - `eagerSync`: render server-side eagerly *and* register as sync (no
+ *   client-side defer).
+ * - `sync`: register as sync (sectionLoaders.sync), but server-side
+ *   loading remains the default.
+ * - `listingCache`: `export const cache = "listing"` (medium TTL).
+ * - `staticCache`: `export const cache = "static"` (long TTL).
+ */
+export interface SectionConventionConfig {
+	eagerSync?: string[];
+	sync?: string[];
+	listingCache?: string[];
+	staticCache?: string[];
+}
+
+export interface MigrateConfig {
+	sectionConventions?: {
+		/**
+		 * Replace the built-in defaults entirely. Use only when porting a
+		 * site whose section names don't overlap the defaults at all.
+		 */
+		replace?: SectionConventionConfig;
+		/**
+		 * Add to the built-in defaults. Recommended path for sites that
+		 * share most defaults but have a few extra section names.
+		 */
+		extend?: SectionConventionConfig;
+	};
+}
+
+/**
+ * Resolved sets used by `transformSectionConventions`. Always provided —
+ * either from defaults, from config replace, or defaults+config.extend.
+ */
+export interface SectionConventionSets {
+	eagerSync: Set<string>;
+	sync: Set<string>;
+	listingCache: Set<string>;
+	staticCache: Set<string>;
+}
+
+/**
+ * Built-in defaults. Originally extracted from `casaevideo` migration —
+ * these names are common across Deco/VTEX storefronts that share the
+ * lineage. Sites that don't have these sections are unaffected (the
+ * matcher just never fires).
+ */
+export const DEFAULT_SECTION_CONVENTIONS: SectionConventionConfig = {
+	eagerSync: [
+		"UtilLinks",
+		"DepartamentList",
+		"ImageGallery",
+		"BannersGrid",
+		"Carousel",
+		"Tipbar",
+		"Live",
+	],
+	sync: [
+		"ProductShelf",
+		"ProductShelfTabbed",
+		"ProductShelfGroup",
+		"ProductShelfTopSort",
+		"CouponList",
+		"NotFoundChallenge",
+		"MountedPDP",
+		"BackgroundWrapper",
+		"SearchResult",
+		"LpCartao",
+	],
+	listingCache: [
+		"ProductShelf",
+		"ProductShelfTabbed",
+		"ProductShelfGroup",
+		"ProductShelfTimedOffers",
+	],
+	staticCache: ["InstagramPosts", "Faq"],
+};
+
+/** Load `.deco-migrate.config.json` from the source dir, if present. */
+export function loadConfig(sourceDir: string): MigrateConfig | null {
+	const configPath = path.join(sourceDir, ".deco-migrate.config.json");
+	if (!fs.existsSync(configPath)) return null;
+	try {
+		return JSON.parse(fs.readFileSync(configPath, "utf-8")) as MigrateConfig;
+	} catch (e) {
+		const msg = (e as Error).message;
+		throw new Error(
+			`Failed to parse ${configPath}: ${msg}. Expected valid JSON.`,
+		);
+	}
+}
+
+/** Resolve config + defaults into the four sets the transform consumes. */
+export function resolveSectionConventions(
+	config: MigrateConfig | null,
+): SectionConventionSets {
+	const sc = config?.sectionConventions;
+
+	// Replace mode: use only what the user provided. No defaults mixed in.
+	if (sc?.replace) {
+		return toSets(sc.replace);
+	}
+
+	// Default + extend: start from defaults, union in extend lists.
+	const merged: SectionConventionConfig = {
+		eagerSync: [
+			...(DEFAULT_SECTION_CONVENTIONS.eagerSync ?? []),
+			...(sc?.extend?.eagerSync ?? []),
+		],
+		sync: [
+			...(DEFAULT_SECTION_CONVENTIONS.sync ?? []),
+			...(sc?.extend?.sync ?? []),
+		],
+		listingCache: [
+			...(DEFAULT_SECTION_CONVENTIONS.listingCache ?? []),
+			...(sc?.extend?.listingCache ?? []),
+		],
+		staticCache: [
+			...(DEFAULT_SECTION_CONVENTIONS.staticCache ?? []),
+			...(sc?.extend?.staticCache ?? []),
+		],
+	};
+	return toSets(merged);
+}
+
+function toSets(c: SectionConventionConfig): SectionConventionSets {
+	return {
+		eagerSync: new Set(c.eagerSync ?? []),
+		sync: new Set(c.sync ?? []),
+		listingCache: new Set(c.listingCache ?? []),
+		staticCache: new Set(c.staticCache ?? []),
+	};
+}
+
+/** Cheap structural validation — throws on obviously invalid shapes. */
+export function validateConfig(config: unknown): asserts config is MigrateConfig {
+	if (config === null || typeof config !== "object") {
+		throw new Error(".deco-migrate.config.json must be a JSON object");
+	}
+	const c = config as Record<string, unknown>;
+	const sc = c.sectionConventions;
+	if (sc === undefined) return;
+	if (typeof sc !== "object" || sc === null) {
+		throw new Error("sectionConventions must be an object");
+	}
+	const scObj = sc as Record<string, unknown>;
+	for (const key of ["replace", "extend"] as const) {
+		const v = scObj[key];
+		if (v === undefined) continue;
+		if (typeof v !== "object" || v === null) {
+			throw new Error(`sectionConventions.${key} must be an object`);
+		}
+		const sub = v as Record<string, unknown>;
+		for (const f of ["eagerSync", "sync", "listingCache", "staticCache"]) {
+			const arr = sub[f];
+			if (arr === undefined) continue;
+			if (
+				!Array.isArray(arr) ||
+				!arr.every((s): s is string => typeof s === "string")
+			) {
+				throw new Error(`sectionConventions.${key}.${f} must be string[]`);
+			}
+		}
+	}
+}