@decocms/start 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.5.0",
+  "version": "2.6.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.test.ts

@@ -0,0 +1,141 @@
+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 { writeImportedLibShims } from "./phase-cleanup";
+import type { MigrationContext } from "./types";
+
+/**
+ * Build a minimal `MigrationContext` for integration tests of
+ * `writeImportedLibShims`. Only the fields that function reads are
+ * non-default; everything else is a placeholder with the right shape.
+ */
+function makeCtx(sourceDir: string, dryRun = false): MigrationContext {
+  return {
+    sourceDir,
+    siteName: "test-site",
+    platform: "vtex",
+    vtexAccount: null,
+    gtmId: null,
+    importMap: {},
+    discoveredNpmDeps: {},
+    themeColors: {},
+    fontFamily: null,
+    files: [],
+    sectionMetas: [],
+    islandClassifications: [],
+    islandWrapperTargets: new Map(),
+    loaderInventory: [],
+    scaffoldedFiles: [],
+    transformedFiles: [],
+    deletedFiles: [],
+    movedFiles: [],
+    manualReviewItems: [],
+    frameworkFindings: [],
+    dryRun,
+    verbose: false,
+  };
+}
+
+describe("writeImportedLibShims (integration)", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "lazy-shim-test-"));
+    fs.mkdirSync(path.join(tmpDir, "src", "loaders"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("writes nothing when no ~/lib imports are found", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "products.ts"),
+      `import { something } from "@decocms/apps/vtex";\nexport const x = 1;\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir));
+
+    expect(fs.existsSync(path.join(tmpDir, "src", "lib"))).toBe(false);
+  });
+
+  it("writes only the shim files matching imports actually present in src/", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "search.ts"),
+      `import { getSegmentFromBag } from "~/lib/vtex-segment";\n` +
+        `import { toFilterSearchString } from "~/lib/filter-navigate";\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir));
+
+    const libDir = path.join(tmpDir, "src", "lib");
+    expect(fs.existsSync(libDir)).toBe(true);
+    const written = fs.readdirSync(libDir).sort();
+    expect(written).toEqual(["filter-navigate.ts", "vtex-segment.ts"]);
+  });
+
+  it("writes nothing in dry-run mode (but does not throw)", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "search.ts"),
+      `import { getSegmentFromBag } from "~/lib/vtex-segment";\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir, /* dryRun */ true));
+
+    expect(fs.existsSync(path.join(tmpDir, "src", "lib"))).toBe(false);
+  });
+
+  it("strips trailing .ts from the import specifier when scanning", () => {
+    // Some Fresh sites use explicit .ts extensions in their imports.
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "search.ts"),
+      `import { fn } from "~/lib/vtex-transform.ts";\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir));
+
+    expect(
+      fs.existsSync(path.join(tmpDir, "src", "lib", "vtex-transform.ts")),
+    ).toBe(true);
+  });
+
+  it("ignores imports inside the lib dir itself (no self-amplification)", () => {
+    fs.mkdirSync(path.join(tmpDir, "src", "lib"));
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "lib", "existing.ts"),
+      `import { x } from "~/lib/should-not-be-generated";\nexport const y = 1;\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir));
+
+    // Only the existing file should remain; nothing new generated.
+    const files = fs.readdirSync(path.join(tmpDir, "src", "lib"));
+    expect(files).toEqual(["existing.ts"]);
+  });
+
+  it("scans .tsx files too, not just .ts", () => {
+    fs.mkdirSync(path.join(tmpDir, "src", "components"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "components", "Filter.tsx"),
+      `import { toFilterSearchString } from "~/lib/filter-navigate";\n` +
+        `export const C = () => null;\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir));
+
+    expect(
+      fs.existsSync(path.join(tmpDir, "src", "lib", "filter-navigate.ts")),
+    ).toBe(true);
+  });
+
+  it("does nothing when src/ does not exist", () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), "no-src-"));
+    try {
+      writeImportedLibShims(makeCtx(empty));
+      expect(fs.readdirSync(empty)).toEqual([]);
+    } finally {
+      fs.rmSync(empty, { recursive: true, force: true });
+    }
+  });
+});

package/scripts/migrate/phase-cleanup.ts

@@ -2,6 +2,10 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { MigrationContext } from "./types";
 import { log, logPhase } from "./types";
+import {
+  LIB_TEMPLATES,
+  selectImportedLibTemplates,
+} from "./templates/lib-utils";
 
 /** Directories to remove entirely after migration */
 const DIRS_TO_DELETE = [
@@ -1479,7 +1483,106 @@ export function cleanup(ctx: MigrationContext): void {
   console.log("  Fixing Worker-incompatible APIs...");
   fixWorkerIncompatibleApis(ctx);
 
+  // 14. LAZY: write only the src/lib/* shim files that the migrated
+  //     codebase actually imports. Run after every previous step so we
+  //     observe the final import graph (transforms + cleanup rewrites
+  //     + inline-stub hoisting all settled).
+  console.log("  Writing src/lib/* shims (lazy)...");
+  writeImportedLibShims(ctx);
+
   console.log(
     `  Deleted ${ctx.deletedFiles.length} files/dirs, moved ${ctx.movedFiles.length} files`,
   );
 }
+
+/**
+ * Walk `src/**\/*.{ts,tsx}` looking for `from "~/lib/<name>"` imports.
+ * For each unique `<name>` that has a registered template in
+ * `LIB_TEMPLATES`, write `src/lib/<name>.ts` with the template content.
+ *
+ * Sites that import none of the shims end up with no `src/lib/` directory
+ * at all, instead of 11 dead files.
+ *
+ * Exported (rather than file-local) for unit testability — see
+ * `phase-cleanup.test.ts`.
+ */
+export function writeImportedLibShims(ctx: MigrationContext): void {
+  const srcRoot = path.join(ctx.sourceDir, "src");
+  if (!fs.existsSync(srcRoot)) return;
+
+  const importedSpecifiers = new Set<string>();
+  // Match `from "~/lib/<name>"` or `from '~/lib/<name>'`. We don't care
+  // about default vs named imports here — only the path matters.
+  const importRe = /from\s+["']~\/lib\/([^"']+?)(?:\.ts)?["']/g;
+
+  /** Recursively scan a directory for .ts/.tsx files and collect specifiers. */
+  const walk = (dir: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        // Skip the lib dir itself so we don't count internal cross-refs
+        // when we later add them.
+        if (full === path.join(srcRoot, "lib")) continue;
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!/\.(ts|tsx)$/.test(entry.name)) continue;
+      const content = fs.readFileSync(full, "utf-8");
+      let m: RegExpExecArray | null;
+      while ((m = importRe.exec(content)) !== null) {
+        importedSpecifiers.add(m[1]);
+      }
+    }
+  };
+  walk(srcRoot);
+
+  if (importedSpecifiers.size === 0) {
+    log(ctx, "  No ~/lib/* imports detected — no shims written.");
+    return;
+  }
+
+  const known = new Set(
+    Object.keys(LIB_TEMPLATES).map((k) =>
+      k.replace(/^src\/lib\//, "").replace(/\.ts$/, ""),
+    ),
+  );
+  const unknown: string[] = [];
+  for (const spec of importedSpecifiers) {
+    if (!known.has(spec)) unknown.push(spec);
+  }
+  if (unknown.length > 0) {
+    log(
+      ctx,
+      `  Warning: ~/lib/{${unknown.join(", ")}} imported but no template registered. ` +
+        `Write the file by hand or add a template to scripts/migrate/templates/lib-utils.ts.`,
+    );
+  }
+
+  const toWrite = selectImportedLibTemplates(importedSpecifiers);
+  if (Object.keys(toWrite).length === 0) return;
+
+  if (ctx.dryRun) {
+    for (const relPath of Object.keys(toWrite)) {
+      log(ctx, `  [DRY] Would write: ${relPath}`);
+    }
+    return;
+  }
+
+  const libDir = path.join(srcRoot, "lib");
+  if (!fs.existsSync(libDir)) {
+    fs.mkdirSync(libDir, { recursive: true });
+  }
+
+  for (const [relPath, content] of Object.entries(toWrite)) {
+    const fullPath = path.join(ctx.sourceDir, relPath);
+    fs.writeFileSync(fullPath, content, "utf-8");
+    log(ctx, `  Wrote: ${relPath}`);
+  }
+
+  log(
+    ctx,
+    `  Generated ${Object.keys(toWrite).length} src/lib/* shim(s) ` +
+      `(out of ${Object.keys(LIB_TEMPLATES).length} available templates).`,
+  );
+}

package/scripts/migrate/phase-scaffold.ts

@@ -18,7 +18,9 @@ import { generateCommerceLoaders } from "./templates/commerce-loaders";
 import { generateSectionLoaders } from "./templates/section-loaders";
 import { generateCacheConfig } from "./templates/cache-config";
 import { generateSdkFiles } from "./templates/sdk-gen";
-import { generateLibUtils } from "./templates/lib-utils";
+// `lib-utils` is imported lazily — see end of phase-cleanup. Eager
+// generation of all 11 shims left every site with dead code that had
+// to be cleaned up by hand.
 import { extractTheme } from "./analyzers/theme-extractor";
 
 function writeFile(ctx: MigrationContext, relPath: string, content: string) {
@@ -108,8 +110,10 @@ export function scaffold(ctx: MigrationContext): void {
   writeFile(ctx, "src/sdk/logger.ts", generateLoggerStub());
   writeMultiFile(ctx, generateSdkFiles(ctx));
 
-  // VTEX utility wrappers (signature-compatible stubs for custom loaders)
-  writeMultiFile(ctx, generateLibUtils(ctx));
+  // VTEX utility wrappers (signature-compatible stubs) are no longer
+  // generated eagerly here. They're written lazily at end of phase-cleanup,
+  // after all import rewrites have run, so that we only emit shims that
+  // some file actually imports. See `writeImportedLibShims` in phase-cleanup.
 
   // Replace Context-based useDevice with SSR-safe useSyncExternalStore version.
   // @decocms/start shell-renders sections in a separate React root without

package/scripts/migrate/templates/lib-utils.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import {
+  LIB_TEMPLATES,
+  selectImportedLibTemplates,
+} from "./lib-utils";
+
+describe("LIB_TEMPLATES registry", () => {
+  it("has entries", () => {
+    expect(Object.keys(LIB_TEMPLATES).length).toBeGreaterThan(0);
+  });
+
+  it("uses src/lib/<name>.ts keys (relative paths the writer expects)", () => {
+    for (const key of Object.keys(LIB_TEMPLATES)) {
+      expect(key).toMatch(/^src\/lib\/[a-z][a-z0-9-]*\.ts$/);
+    }
+  });
+
+  it("has non-empty contents for every entry", () => {
+    for (const [key, value] of Object.entries(LIB_TEMPLATES)) {
+      expect(value, `${key} should have content`).toBeTruthy();
+      expect(value.length, `${key} length`).toBeGreaterThan(20);
+    }
+  });
+
+  it("has unique keys (no shadowing)", () => {
+    const keys = Object.keys(LIB_TEMPLATES);
+    const set = new Set(keys);
+    expect(set.size).toBe(keys.length);
+  });
+});
+
+describe("selectImportedLibTemplates()", () => {
+  it("returns empty record when no specifiers are imported", () => {
+    expect(selectImportedLibTemplates(new Set())).toEqual({});
+  });
+
+  it("returns only the templates whose specifier is in the set", () => {
+    const result = selectImportedLibTemplates(new Set(["vtex-segment"]));
+    expect(Object.keys(result)).toEqual(["src/lib/vtex-segment.ts"]);
+    expect(result["src/lib/vtex-segment.ts"]).toBe(LIB_TEMPLATES["src/lib/vtex-segment.ts"]);
+  });
+
+  it("returns multiple templates when multiple specifiers are imported", () => {
+    const result = selectImportedLibTemplates(
+      new Set(["vtex-segment", "vtex-transform", "filter-navigate"]),
+    );
+    const keys = Object.keys(result).sort();
+    expect(keys).toEqual([
+      "src/lib/filter-navigate.ts",
+      "src/lib/vtex-segment.ts",
+      "src/lib/vtex-transform.ts",
+    ]);
+  });
+
+  it("ignores unknown specifiers without throwing", () => {
+    const result = selectImportedLibTemplates(
+      new Set(["vtex-segment", "this-template-does-not-exist"]),
+    );
+    expect(Object.keys(result)).toEqual(["src/lib/vtex-segment.ts"]);
+  });
+
+  it("does not mutate LIB_TEMPLATES (returns a fresh object)", () => {
+    const before = JSON.stringify(LIB_TEMPLATES);
+    const result = selectImportedLibTemplates(new Set(["vtex-segment"]));
+    result["src/lib/vtex-segment.ts"] = "// HIJACKED";
+    expect(JSON.stringify(LIB_TEMPLATES)).toBe(before);
+  });
+
+  it("covers every well-known migration target the writer might emit", () => {
+    // Sanity check: the names that `transforms/imports.ts` rewrites to
+    // and that phase-cleanup hoists for inline-stub injection MUST all
+    // have templates registered, otherwise migrated sites get import
+    // errors with no warning.
+    const expectedSpecifiers = [
+      "vtex-transform",
+      "vtex-intelligent-search",
+      "vtex-segment",
+      "vtex-fetch",
+      "vtex-id",
+      "vtex-client",
+      "fetch-utils",
+      "http-utils",
+      "graphql-utils",
+      "filter-navigate",
+    ];
+    for (const spec of expectedSpecifiers) {
+      const key = `src/lib/${spec}.ts`;
+      expect(LIB_TEMPLATES, `expected template for ${key}`).toHaveProperty(key);
+    }
+  });
+});

package/scripts/migrate/templates/lib-utils.ts

@@ -1,25 +1,41 @@
-import type { MigrationContext } from "../types";
+/**
+ * Templates for src/lib/ utility wrappers that bridge signature gaps
+ * between deco-cx/apps (old stack) and @decocms/apps-start (new stack).
+ *
+ * These are written *lazily*: only shims that are actually imported by
+ * the migrated codebase get generated. See `selectImportedLibTemplates`.
+ *
+ * Lazy generation matters because:
+ * - Most sites end up importing zero of these (apps-start exports
+ *   direct equivalents for most VTEX utilities — see migrate#107).
+ * - Eager generation creates dead `src/lib/*.ts` files that every site
+ *   then has to clean up by hand (see baggagio-tanstack#7, ~235 LOC).
+ *
+ * Registry shape: `"src/lib/<name>.ts"` → file contents.
+ */
+export const LIB_TEMPLATES: Record<string, string> = {
+  // Filled in below after the const declarations to keep the registry
+  // and template literals colocated. See trailing assignment.
+};
 
 /**
- * Generates src/lib/ utility wrappers that provide signature-compatible
- * stubs for VTEX utilities. The old stack (deco-cx/apps) exports functions
- * with different signatures than @decocms/apps-start, and some types
- * (VTEXCommerceStable, LabelledFuzzy) don't exist at all. These wrappers
- * bridge the gap so custom loaders continue to compile and run.
+ * Given the set of `~/lib/X` imports actually present in the migrated
+ * codebase, return the subset of templates to write.
+ *
+ * `importedSpecifiers` are the `X` parts (without `~/lib/` prefix and
+ * without `.ts` extension), e.g. `"vtex-transform"`, `"http-utils"`.
  */
-export function generateLibUtils(_ctx: MigrationContext): Record<string, string> {
-  return {
-    "src/lib/vtex-transform.ts": LIB_VTEX_TRANSFORM,
-    "src/lib/vtex-intelligent-search.ts": LIB_VTEX_INTELLIGENT_SEARCH,
-    "src/lib/vtex-segment.ts": LIB_VTEX_SEGMENT,
-    "src/lib/http-utils.ts": LIB_HTTP_UTILS,
-    "src/lib/vtex-client.ts": LIB_VTEX_CLIENT,
-    "src/lib/fetch-utils.ts": LIB_FETCH_UTILS,
-    "src/lib/vtex-fetch.ts": LIB_VTEX_FETCH,
-    "src/lib/vtex-id.ts": LIB_VTEX_ID,
-    "src/lib/graphql-utils.ts": LIB_GRAPHQL_UTILS,
-    "src/lib/filter-navigate.ts": LIB_FILTER_NAVIGATE,
-  };
+export function selectImportedLibTemplates(
+  importedSpecifiers: Set<string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const spec of importedSpecifiers) {
+    const key = `src/lib/${spec}.ts`;
+    if (key in LIB_TEMPLATES) {
+      out[key] = LIB_TEMPLATES[key];
+    }
+  }
+  return out;
 }
 
 const LIB_VTEX_TRANSFORM = `import type { Product } from "@decocms/apps/commerce/types";
@@ -253,3 +269,19 @@ export function toFilterSearchString(filterUrl: string): string {
   return clean ? \`?\${clean}\` : "";
 }
 `;
+
+// Populate the registry now that all template literals are declared.
+// Keys must match the relative path the migration script writes; values
+// are the file contents.
+Object.assign(LIB_TEMPLATES, {
+  "src/lib/vtex-transform.ts": LIB_VTEX_TRANSFORM,
+  "src/lib/vtex-intelligent-search.ts": LIB_VTEX_INTELLIGENT_SEARCH,
+  "src/lib/vtex-segment.ts": LIB_VTEX_SEGMENT,
+  "src/lib/http-utils.ts": LIB_HTTP_UTILS,
+  "src/lib/vtex-client.ts": LIB_VTEX_CLIENT,
+  "src/lib/fetch-utils.ts": LIB_FETCH_UTILS,
+  "src/lib/vtex-fetch.ts": LIB_VTEX_FETCH,
+  "src/lib/vtex-id.ts": LIB_VTEX_ID,
+  "src/lib/graphql-utils.ts": LIB_GRAPHQL_UTILS,
+  "src/lib/filter-navigate.ts": LIB_FILTER_NAVIGATE,
+});

package/vitest.config.ts

@@ -1,9 +1,19 @@
 import { defineConfig } from "vitest/config";
 
+// Two test suites, one runner:
+// - `src/**` runs in jsdom (React rendering, hooks, browser globals).
+// - `scripts/**` runs in node (filesystem, migration script logic).
+// vitest applies env-per-file via the `environmentMatchGlobs` map.
 export default defineConfig({
   test: {
     environment: "jsdom",
-    include: ["src/**/*.test.{ts,tsx}"],
+    environmentMatchGlobs: [
+      ["scripts/**", "node"],
+    ],
+    include: [
+      "src/**/*.test.{ts,tsx}",
+      "scripts/**/*.test.ts",
+    ],
     globals: true,
   },
 });