@decocms/blocks-cli 7.3.1 → 7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.3.1",
+  "version": "7.4.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -34,7 +34,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.3.1",
+    "@decocms/blocks": "7.4.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.19.0"
   },

package/scripts/generate-schema.test.ts

@@ -1,6 +1,29 @@
 import { Project } from "ts-morph";
 import { describe, expect, it } from "vitest";
-import { WIDGET_TYPE_FORMATS, applyWidgetFormat, typeToJsonSchema } from "./generate-schema";
+import {
+  WIDGET_TYPE_FORMATS,
+  applyWidgetFormat,
+  definitionIdForPath,
+  typeToJsonSchema,
+} from "./generate-schema";
+
+describe("definitionIdForPath", () => {
+  it("is repo-relative, never absolute", () => {
+    const id = definitionIdForPath(
+      "/Users/anyone/code/mysite/src/sections/Hero.tsx",
+      "/Users/anyone/code/mysite",
+    );
+    expect(Buffer.from(id, "base64").toString()).toBe("src/sections/Hero.tsx");
+  });
+
+  it("normalizes file:// prefixes from ts-morph", () => {
+    const id = definitionIdForPath(
+      "file:///Users/anyone/code/mysite/src/sections/Hero.tsx",
+      "/Users/anyone/code/mysite",
+    );
+    expect(Buffer.from(id, "base64").toString()).toBe("src/sections/Hero.tsx");
+  });
+});
 
 describe("applyWidgetFormat", () => {
   it("recovers an unresolved widget alias (empty schema) as string + format", () => {

package/scripts/generate-schema.ts

@@ -31,6 +31,7 @@ import {
   SyntaxKind,
   type Type,
 } from "ts-morph";
+import { isExcludedCodegenFile } from "./lib/codegenExclusions";
 
 // ---------------------------------------------------------------------------
 // CLI arg parsing
@@ -72,6 +73,18 @@ function toBase64(str: string): string {
   return Buffer.from(str).toString("base64");
 }
 
+/**
+ * Definition IDs must be stable across machines: the raw ts-morph path is
+ * absolute (`file:///Users/<user>/...`), which made meta.gen.json differ
+ * per machine and destabilized the /live/_meta ETag. IDs are opaque to the
+ * admin — only internal $ref consistency matters — so relativize to root.
+ */
+export function definitionIdForPath(filePath: string, rootDir: string): string {
+  const cleaned = filePath.replace(/^file:\/+/, "/");
+  const rel = path.relative(rootDir, cleaned).replaceAll("\\", "/");
+  return toBase64(rel.startsWith("..") ? cleaned : rel);
+}
+
 /**
  * Map JSDoc tags to JSON Schema 7 keywords.
  * Supports all 20+ tags from deco-cx/deco.
@@ -734,6 +747,7 @@ function findTsxFiles(dir: string): string[] {
   const results: string[] = [];
   if (!fs.existsSync(dir)) return results;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (isExcludedCodegenFile(entry.name)) continue;
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) results.push(...findTsxFiles(full));
     else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) results.push(full);
@@ -1141,7 +1155,7 @@ function generateMeta(): MetaResponse {
 
       const propCount = Object.keys(propsSchema.properties || {}).length;
 
-      const propsDefKey = toBase64(`file:///${filePath.replaceAll("\\", "/")}`) + "@Props";
+      const propsDefKey = definitionIdForPath(filePath, root) + "@Props";
       definitions[propsDefKey] = propsSchema;
 
       const sectionDefKey = toBase64(blockKey);
@@ -1232,7 +1246,7 @@ function generateMeta(): MetaResponse {
 
         const propCount = Object.keys(propsSchema.properties || {}).length;
 
-        const propsDefKey = toBase64(`file:///${filePath.replaceAll("\\", "/")}`) + "@Props";
+        const propsDefKey = definitionIdForPath(filePath, root) + "@Props";
         definitions[propsDefKey] = propsSchema;
 
         const appDefKey = toBase64(blockKey);

package/scripts/generate-sections.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Integration test for `generate-sections.ts`.
+ *
+ * Drives the script as a child process against a tmp sections-dir fixture,
+ * mirroring the pattern used by migrate-to-cf-observability.test.ts. The
+ * script has no `isMainModule()` guard (unlike generate-schema.ts) — it runs
+ * its filesystem walk and write on import — so it's exercised as a subprocess
+ * rather than imported directly.
+ *
+ * Verifies the operationally important behavior: a co-located test/spec/
+ * stories/gen file sitting next to a real section must never be walked into
+ * sectionMeta (the fila incident this generator's `walkDir` reproduced:
+ * `sections.test.ts` became a bogus section in a site's generated output).
+ */
+import * as cp from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const SCRIPT = path.resolve(__dirname, "generate-sections.ts");
+
+function runGenerator(args: string[]): { stdout: string; stderr: string; code: number } {
+  const r = cp.spawnSync("npx", ["tsx", SCRIPT, ...args], { encoding: "utf8" });
+  return { stdout: r.stdout || "", stderr: r.stderr || "", code: r.status ?? 0 };
+}
+
+describe("generate-sections walkDir exclusions", () => {
+  let tmpDir: string;
+  let sectionsDir: string;
+  let outFile: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-sections-"));
+    sectionsDir = path.join(tmpDir, "sections");
+    outFile = path.join(tmpDir, "out", "sections.gen.ts");
+    fs.mkdirSync(sectionsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("excludes co-located test/spec/stories/gen files from the generated sectionMeta", () => {
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.tsx"),
+      `export const eager = true;\nexport default function Hero() { return null; }\n`,
+    );
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.test.tsx"),
+      `export const eager = true;\nexport default function HeroTest() { return null; }\n`,
+    );
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.stories.tsx"),
+      `export const eager = true;\nexport default function HeroStories() { return null; }\n`,
+    );
+    fs.writeFileSync(
+      path.join(sectionsDir, "sections.gen.ts"),
+      `export const eager = true;\n`,
+    );
+
+    const { code } = runGenerator(["--sections-dir", sectionsDir, "--out-file", outFile]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    expect(generated).toContain("site/sections/Hero.tsx");
+    expect(generated).not.toContain("Hero.test.tsx");
+    expect(generated).not.toContain("Hero.stories.tsx");
+    expect(generated).not.toContain("sections.gen.ts");
+  });
+});
+
+describe("generate-sections --registry", () => {
+  let tmpDir: string;
+  let sectionsDir: string;
+  let outFile: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-sections-registry-"));
+    sectionsDir = path.join(tmpDir, "sections");
+    outFile = path.join(tmpDir, "out", "sections.gen.ts");
+    fs.mkdirSync(path.join(sectionsDir, "Nested"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function expectedImportPath(filePath: string): string {
+    let rel = path.relative(path.dirname(outFile), filePath).replace(/\\/g, "/");
+    if (!rel.startsWith(".")) rel = `./${rel}`;
+    return rel.replace(/\.tsx?$/, "");
+  }
+
+  it("emits sectionImports keyed glob-style with relative dynamic imports, built from all scanned section files (not just convention-carrying ones)", () => {
+    const heroPath = path.join(sectionsDir, "Hero.tsx");
+    const promoPath = path.join(sectionsDir, "Nested", "Promo.tsx");
+    fs.writeFileSync(
+      heroPath,
+      "export const sync = true\nexport default function Hero() { return null }\n",
+    );
+    // No convention exports — regression guard: without --registry this file
+    // never makes it into `entries`, so the registry must be built from the
+    // raw `sectionFiles` walk, not from `entries`.
+    fs.writeFileSync(
+      promoPath,
+      "export default function Promo() { return null }\n",
+    );
+
+    const { code } = runGenerator([
+      "--sections-dir", sectionsDir,
+      "--out-file", outFile,
+      "--registry",
+    ]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    expect(generated).toContain("export const sectionImports");
+    expect(generated).toContain(
+      `"./sections/Hero.tsx": () => import("${expectedImportPath(heroPath)}")`,
+    );
+    expect(generated).toContain(
+      `"./sections/Nested/Promo.tsx": () => import("${expectedImportPath(promoPath)}")`,
+    );
+  });
+
+  it("does not emit sectionImports without the --registry flag", () => {
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.tsx"),
+      "export const sync = true\nexport default function Hero() { return null }\n",
+    );
+    fs.writeFileSync(
+      path.join(sectionsDir, "Nested", "Promo.tsx"),
+      "export default function Promo() { return null }\n",
+    );
+
+    const { code } = runGenerator(["--sections-dir", sectionsDir, "--out-file", outFile]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    expect(generated).not.toContain("sectionImports");
+  });
+
+  it("emits a doc comment that does not self-terminate early, and the resulting file is importable (regression: a literal `**/` inside the emitted /** */ comment used to close it prematurely, leaving prose as bare statements and making every --registry output invalid TypeScript)", () => {
+    const heroPath = path.join(sectionsDir, "Hero.tsx");
+    fs.writeFileSync(
+      heroPath,
+      "export const sync = true\nexport default function Hero() { return null }\n",
+    );
+
+    const { code } = runGenerator([
+      "--sections-dir", sectionsDir,
+      "--out-file", outFile,
+      "--registry",
+    ]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+
+    // Pin the regression directly: the doc comment's body (everything
+    // between the opening `/**` and its own closing `*/`) must contain
+    // exactly one `*/` — the intended closing marker itself, at the very
+    // end. A premature `*/` embedded in the prose (e.g. from a literal
+    // `**/*.tsx` glob pattern) would close the block comment early and
+    // leave the rest of the doc text as bare top-level statements.
+    const docCommentStart = generated.indexOf("/**\n * Lazy section registry");
+    const exportStart = generated.indexOf("export const sectionImports");
+    expect(docCommentStart).toBeGreaterThan(-1);
+    expect(exportStart).toBeGreaterThan(docCommentStart);
+    const docComment = generated.slice(docCommentStart + "/**".length, exportStart);
+    const closeMarkerCount = (docComment.match(/\*\//g) ?? []).length;
+    expect(closeMarkerCount).toBe(1);
+    expect(docComment.trimEnd().endsWith("*/")).toBe(true);
+
+    // Strongest available check: actually import the generated file through
+    // tsx (esbuild) and confirm it parses/executes as valid TS/ESM and
+    // exports `sectionImports`. A premature `*/` would leave trailing prose
+    // as bare top-level statements, which fails to parse. `tsx -e` evaluates
+    // its argument as CommonJS (named exports of a dynamic `import()` come
+    // back CJS-interop-wrapped), so write a real `.mjs` file instead and run
+    // that — mirrors the check used to hand-verify this fix.
+    const checkerFile = path.join(tmpDir, "check-import.mjs");
+    fs.writeFileSync(
+      checkerFile,
+      [
+        `import { pathToFileURL } from "node:url";`,
+        `const m = await import(${JSON.stringify(pathToFileURL(outFile).href)});`,
+        `if (typeof m.sectionImports !== "object" || m.sectionImports === null) {`,
+        `  throw new Error("sectionImports missing or not an object");`,
+        `}`,
+      ].join("\n"),
+    );
+
+    const importResult = cp.spawnSync("npx", ["tsx", checkerFile], { encoding: "utf8" });
+    expect(importResult.status, importResult.stderr).toBe(0);
+  }, 30_000);
+});

package/scripts/generate-sections.ts

@@ -17,9 +17,16 @@
  * CLI:
  *   --sections-dir  override input  (default: src/sections)
  *   --out-file      override output (default: src/server/cms/sections.gen.ts)
+ *   --registry      also emit `sectionImports` — a lazy section-import map
+ *                   keyed glob-style (`./sections/...`), the Next.js/webpack
+ *                   equivalent of Vite's `import.meta.glob("./sections/**\/*.tsx")`.
+ *                   Built from every scanned section file, not just the ones
+ *                   carrying convention exports. Off by default so existing
+ *                   Vite sites regenerating sections.gen.ts in CI see zero diff.
  */
 import fs from "node:fs";
 import path from "node:path";
+import { isExcludedCodegenFile } from "./lib/codegenExclusions";
 
 const args = process.argv.slice(2);
 function arg(name: string, fallback: string): string {
@@ -29,6 +36,7 @@ function arg(name: string, fallback: string): string {
 
 const sectionsDir = path.resolve(process.cwd(), arg("sections-dir", "src/sections"));
 const outFile = path.resolve(process.cwd(), arg("out-file", "src/server/cms/sections.gen.ts"));
+const EMIT_REGISTRY = args.includes("--registry");
 
 interface SectionMeta {
   eager?: boolean;
@@ -92,7 +100,10 @@ function walkDir(dir: string, base: string = dir): string[] {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       results.push(...walkDir(fullPath, base));
-    } else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) {
+    } else if (
+      (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) &&
+      !isExcludedCodegenFile(entry.name)
+    ) {
       results.push(fullPath);
     }
   }
@@ -223,6 +234,25 @@ if (allFallbacks.length > 0) {
 }
 lines.push("");
 
+// Lazy section-import registry — opt-in via --registry, built from every
+// scanned section file (not just convention-carrying `entries`).
+if (EMIT_REGISTRY) {
+  lines.push("");
+  lines.push("/**");
+  lines.push(" * Lazy section registry — the Next.js/webpack equivalent of Vite's");
+  lines.push(" * `import.meta.glob` scan over every file under ./sections, recursively.");
+  lines.push(" * Keys use the glob-style `./sections/...` form so this map drops");
+  lines.push(" * straight into `createSiteSetup({ sections })` / `createNextSetup({ sections })`.");
+  lines.push(" */");
+  lines.push("export const sectionImports: Record<string, () => Promise<any>> = {");
+  for (const filePath of sectionFiles) {
+    const rel = path.relative(sectionsDir, filePath).replace(/\\/g, "/");
+    const importPath = relativeImportPath(outFile, filePath);
+    lines.push(`  "./sections/${rel}": () => import("${importPath}"),`);
+  }
+  lines.push("};");
+}
+
 fs.mkdirSync(path.dirname(outFile), { recursive: true });
 fs.writeFileSync(outFile, lines.join("\n"));
 

package/scripts/lib/codegenExclusions.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { isExcludedCodegenFile } from "./codegenExclusions";
+
+describe("isExcludedCodegenFile", () => {
+  it.each([
+    "Hero.test.tsx",
+    "Hero.test.ts",
+    "Hero.spec.tsx",
+    "Hero.stories.tsx",
+    "sections.gen.ts",
+    "meta.gen.json",
+  ])("excludes %s", (name) => {
+    expect(isExcludedCodegenFile(name)).toBe(true);
+  });
+
+  it.each(["Hero.tsx", "Product/SearchResult.tsx", "testimonials.tsx", "generic.ts"])(
+    "keeps %s",
+    (name) => {
+      expect(isExcludedCodegenFile(name)).toBe(false);
+    },
+  );
+});

package/scripts/lib/codegenExclusions.ts

@@ -0,0 +1,11 @@
+/**
+ * Files the codegen scanners must never treat as section/loader sources.
+ * `generate-schema.ts` once emitted a site's co-located test file as a
+ * section block (it scans every .ts/.tsx under the sections dir), so both
+ * generators route their directory walks through this predicate.
+ */
+const EXCLUDED_SUFFIX_RE = /\.(test|spec|stories|gen)\.(ts|tsx|js|jsx|json)$/;
+
+export function isExcludedCodegenFile(fileName: string): boolean {
+  return EXCLUDED_SUFFIX_RE.test(fileName);
+}