@decocms/blocks-cli 8.0.0 → 8.1.0-next.0

package/scripts/migrate/phase-transform.ts

@@ -5,12 +5,15 @@ import type { MigrationContext, TransformResult, SectionMeta } from "./types";
 import { log, logPhase } from "./types";
 import { transformImports } from "./transforms/imports";
 import { transformJsx } from "./transforms/jsx";
+import { transformPicture } from "./transforms/picture";
+import { transformTimerTypes } from "./transforms/timer-types";
 import { transformFreshApis } from "./transforms/fresh-apis";
 import { transformCtxCompat } from "./transforms/ctx-compat";
 import { transformDenoIsms } from "./transforms/deno-isms";
 import { transformTailwind } from "./transforms/tailwind";
 import { transformDeadCode } from "./transforms/dead-code";
 import { transformHtmxOnEvents } from "./transforms/htmx-on-events";
+import { transformUseScriptHandlers } from "./transforms/use-script-handlers";
 import { createSectionConventionsTransform } from "./transforms/section-conventions";
 
 /** Map of section path → metadata, populated per-run */
@@ -28,7 +31,7 @@ function getSectionMeta(ctx: MigrationContext, relPath: string): SectionMeta | u
 
 /**
  * Cached per-run section-conventions closure. Built once from the
- * resolved config sets (`ctx.config.sectionConventions`), so casaevideo
+ * resolved config sets (`ctx.config.sectionConventions`), so the built-in
  * defaults still apply when no config file exists.
  */
 let cachedSectionTransform:
@@ -67,10 +70,13 @@ function applyTransforms(content: string, filePath: string, ctx?: MigrationConte
     { name: "imports", fn: (c) => transformImports(c, ctx?.islandWrapperTargets) },
     { name: "jsx", fn: transformJsx },
     { name: "htmx-on-events", fn: transformHtmxOnEvents },
+    { name: "use-script-handlers", fn: transformUseScriptHandlers },
     { name: "fresh-apis", fn: transformFreshApis },
     { name: "ctx-compat", fn: transformCtxCompat },
     { name: "dead-code", fn: (c) => transformDeadCode(c, ctx?.platform) },
     { name: "deno-isms", fn: transformDenoIsms },
+    { name: "timer-types", fn: transformTimerTypes },
+    { name: "picture", fn: transformPicture },
     { name: "tailwind", fn: transformTailwind },
   ];
 
@@ -146,6 +152,37 @@ export function transform(ctx: MigrationContext): void {
       });
     }
 
+    // Flag usePartialSection (Fresh load-more / "Ver mais" pattern) with an
+    // actionable useLoadMore recipe instead of a generic HTMX warning.
+    if (/usePartialSection/.test(result.content)) {
+      const hasAppend = /mode\s*:\s*["']append["']/.test(result.content);
+      ctx.manualReviewItems.push({
+        file: targetPath,
+        reason:
+          `usePartialSection${hasAppend ? " (mode:append)" : ""} detected — ` +
+          "this is the Fresh load-more / \"Ver mais\" pagination pattern. " +
+          "In TanStack it is a no-op stub; the button navigates replacing all products instead of appending. " +
+          "Convert to useLoadMore from @decocms/blocks/hooks:\n\n" +
+          '  import { useLoadMore } from "@decocms/blocks/hooks"\n\n' +
+          '  // At the top of your component (must be "use client"):\n' +
+          "  const { pages, loadMore, loading, hasMore } = useLoadMore(\n" +
+          "    props.page ?? { products: [], pageInfo: {} },\n" +
+          '    "LOADER_KEY" // replace with your loader path, e.g.\n' +
+          '    // "apps/vtex.ts/loaders/intelligentSearch/productListingPage.ts"\n' +
+          "  )\n" +
+          "  const allProducts = pages.flatMap(p => p.products ?? [])\n\n" +
+          "  // Replace the usePartialSection anchor/button with:\n" +
+          "  {hasMore && (\n" +
+          '    <button onClick={loadMore} disabled={loading}>\n' +
+          '      {loading ? "Carregando..." : "Ver mais"}\n' +
+          "    </button>\n" +
+          "  )}\n\n" +
+          "Add \"use client\" to the top of the file. " +
+          "See deco-to-tanstack-migration skill, 'Ver mais / Load More' section.",
+        severity: "warning",
+      });
+    }
+
     // Flag files with hx-on:click that use useScript (simpler pattern)
     if (/hx-on:click=\{useScript/.test(result.content)) {
       ctx.manualReviewItems.push({
@@ -190,7 +227,7 @@ export function transform(ctx: MigrationContext): void {
           "that ships HTML fragments and swaps them client-side. It does not work on TanStack Start. " +
           "Recipes: " +
           "(1) Self-contained UI toggles → keep state in React (`useState` + event handlers); " +
-          "(2) Form submissions / mutations → `createServerFn` + `useMutation` (see casaevideo-storefront for canonical examples); " +
+          "(2) Form submissions / mutations → `createServerFn` + `useMutation` (see a production storefront for canonical examples); " +
           "(3) Ad-hoc data fetches → call the loader/action via `~/server/invoke` and store results in `useState`. " +
           "Remove the import after refactoring, then delete `src/sections/Component.tsx`.",
         severity: "error",
@@ -233,6 +270,74 @@ export function transform(ctx: MigrationContext): void {
   // the actual file and rewrite the import.
   if (!ctx.dryRun) {
     fixIslandImports(ctx);
+    reconcileIconCasing(ctx);
+  }
+}
+
+/**
+ * `<Icon id="close">` → `<Icon id="Close">`. Deco-fresh (Deno) didn't strictly
+ * typecheck, so sites often used lowercase icon ids that don't match their own
+ * PascalCase `AvailableIcons` union — the stricter TanStack typecheck then fails
+ * ("Type '\"close\"' is not assignable to type 'AvailableIcons'"). This
+ * case-corrects any `<Icon id="X">` whose name matches an AvailableIcons entry
+ * case-insensitively. Names with NO match (a genuinely missing icon) are left
+ * as-is and flagged for manual review — adding them to the type + sprite is a
+ * design decision, not a rename.
+ */
+export function reconcileIconCasing(ctx: MigrationContext): void {
+  const srcDir = path.join(ctx.sourceDir, "src");
+  if (!fs.existsSync(srcDir)) return;
+
+  const walk = (dir: string, visit: (file: string, content: string) => void) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue;
+        walk(path.join(dir, entry.name), visit);
+      } else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) {
+        visit(path.join(dir, entry.name), fs.readFileSync(path.join(dir, entry.name), "utf-8"));
+      }
+    }
+  };
+
+  // 1. Canonical icon names from the declared `AvailableIcons` union (if any).
+  const canonical = new Map<string, string>(); // lowercased → canonical casing
+  walk(srcDir, (_file, content) => {
+    const m = content.match(/export type AvailableIcons\s*=\s*([\s\S]*?);/);
+    if (m) for (const n of m[1].matchAll(/["']([A-Za-z0-9_-]+)["']/g)) canonical.set(n[1].toLowerCase(), n[1]);
+  });
+  if (canonical.size === 0) return;
+
+  // 2. Case-correct `<Icon id="X">` usages; flag unmatched names once per file.
+  const iconIdRe = /(<Icon\b[^>]*?\bid=["'])([A-Za-z0-9_-]+)(["'])/g;
+  let corrected = 0;
+  walk(srcDir, (file, content) => {
+    let modified = false;
+    const flagged = new Set<string>();
+    const next = content.replace(iconIdRe, (whole, pre, name, post) => {
+      const canon = canonical.get(name.toLowerCase());
+      if (canon) {
+        if (canon !== name) {
+          modified = true;
+          corrected++;
+          return `${pre}${canon}${post}`;
+        }
+        return whole;
+      }
+      if (!flagged.has(name)) {
+        flagged.add(name);
+        ctx.manualReviewItems.push({
+          file: path.relative(ctx.sourceDir, file).replace(/\\/g, "/"),
+          reason: `<Icon id="${name}"> is not in AvailableIcons — add it to the type in Icon.tsx and the sprite, or the icon renders blank.`,
+          severity: "warning",
+        });
+      }
+      return whole;
+    });
+    if (modified) fs.writeFileSync(file, next, "utf-8");
+  });
+
+  if (corrected > 0) {
+    console.log(`  Icon casing: corrected ${corrected} <Icon id> to match AvailableIcons`);
   }
 }
 

package/scripts/migrate/phase-verify-legacy-specifiers.test.ts

@@ -17,6 +17,7 @@ import type { MigrationContext } from "./types";
 function makeCtx(sourceDir: string): MigrationContext {
   return {
     sourceDir,
+    layout: "classic",
     siteName: "test-site",
     platform: "custom",
     vtexAccount: null,
@@ -25,6 +26,18 @@ function makeCtx(sourceDir: string): MigrationContext {
     discoveredNpmDeps: {},
     themeColors: {},
     fontFamily: null,
+    googleFonts: { preconnects: [], stylesheets: [] },
+    tailwindConfig: {
+      colors: {},
+      fontFamily: {},
+      screens: {},
+      animations: {},
+      keyframes: {},
+      safelist: [],
+      safelistPatterns: [],
+      plugins: [],
+      reviewItems: [],
+    },
     files: [],
     sectionMetas: [],
     islandClassifications: [],

package/scripts/migrate/phase-verify.test.ts

@@ -28,7 +28,9 @@ function makeCtx(sourceDir: string): MigrationContext {
     importMap: {},
     discoveredNpmDeps: {},
     themeColors: {},
-  tailwindConfig: { colors: {}, fontFamily: {}, screens: {}, safelist: [], safelistPatterns: [], plugins: [], reviewItems: [] },
+  tailwindConfig: { colors: {}, fontFamily: {}, screens: {}, animations: {}, keyframes: {}, safelist: [], safelistPatterns: [], plugins: [], reviewItems: [] },
+  layout: "classic",
+  googleFonts: { preconnects: [], stylesheets: [] },
     fontFamily: null,
     files: [],
     sectionMetas: [],

package/scripts/migrate/phase-verify.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { parseJsonc } from "../lib/jsonc";
 import type { MigrationContext } from "./types";
 import { logPhase } from "./types";
 
@@ -20,8 +21,15 @@ const REQUIRED_FILES = [
   // Deploy / preview / sync-secrets pipelines are owned by Cloudflare
   // Workers Builds (D6.3) -- configured in the CF dashboard, not via
   // GitHub workflow files in the site repo.
-  ".github/workflows/regen-blocks.yml",
   ".github/workflows/lockfile-check.yml",
+  ".github/workflows/ci.yml",
+  ".github/workflows/main-push-guard.yml",
+  ".github/workflows/playwright.yml",
+  ".github/workflows/react-doctor.yml",
+  ".github/workflows/parity.yml",
+  ".github/workflows/sync-blocks-bot.yml",
+  "tools/gates/no-suppressions.sh",
+  "playwright.config.ts",
   "knip.config.ts",
   ".prettierrc",
   "src/server.ts",
@@ -69,9 +77,7 @@ export const checks: Check[] = [
     name: "All scaffolded files exist",
     severity: "error",
     fn: (ctx) => {
-      const missing = REQUIRED_FILES.filter(
-        (f) => !fs.existsSync(path.join(ctx.sourceDir, f)),
-      );
+      const missing = REQUIRED_FILES.filter((f) => !fs.existsSync(path.join(ctx.sourceDir, f)));
       if (missing.length > 0) {
         console.log(`    Missing: ${missing.join(", ")}`);
         return false;
@@ -79,13 +85,50 @@ export const checks: Check[] = [
       return true;
     },
   },
+  {
+    // Fast Deploy needs THREE things and is inert unless all three are present:
+    // the DECO_KV binding, DECO_FAST_DEPLOY=1, and setup.ts handing the KV
+    // resolver to blocks-admin. Two of three is the worst state — it looks
+    // configured, the Studio publish reports success, and nothing reaches KV.
+    name: "Fast Deploy wired end to end",
+    severity: "error",
+    fn: (ctx) => {
+      const missing: string[] = [];
+      const wranglerPath = path.join(ctx.sourceDir, "wrangler.jsonc");
+      try {
+        const cfg = parseJsonc(fs.readFileSync(wranglerPath, "utf-8")) as {
+          kv_namespaces?: Array<{ binding?: string }>;
+          vars?: Record<string, unknown>;
+        };
+        const flag = cfg.vars?.DECO_FAST_DEPLOY;
+        if (!(cfg.kv_namespaces ?? []).some((n) => n?.binding === "DECO_KV")) {
+          missing.push("wrangler.jsonc kv_namespaces is missing the DECO_KV binding");
+        }
+        if (flag !== "1" && flag !== "true") {
+          missing.push('wrangler.jsonc vars.DECO_FAST_DEPLOY is not "1"');
+        }
+      } catch (e) {
+        missing.push(`wrangler.jsonc could not be parsed: ${(e as Error).message}`);
+      }
+
+      const setupPath = path.join(ctx.sourceDir, "src", "setup.ts");
+      const setup = fs.existsSync(setupPath) ? fs.readFileSync(setupPath, "utf-8") : "";
+      if (!setup.includes("setupTanstackFastDeploy()")) {
+        missing.push("src/setup.ts does not call setupTanstackFastDeploy()");
+      }
+
+      if (missing.length > 0) {
+        for (const m of missing) console.log(`    ${m}`);
+        return false;
+      }
+      return true;
+    },
+  },
   {
     name: "Old artifacts removed",
     severity: "error",
     fn: (ctx) => {
-      const remaining = MUST_NOT_EXIST.filter(
-        (f) => fs.existsSync(path.join(ctx.sourceDir, f)),
-      );
+      const remaining = MUST_NOT_EXIST.filter((f) => fs.existsSync(path.join(ctx.sourceDir, f)));
       if (remaining.length > 0) {
         console.log(`    Still exists: ${remaining.join(", ")}`);
         return false;
@@ -136,14 +179,16 @@ export const checks: Check[] = [
     },
   },
   {
-    name: 'No class= in JSX (should be className=)',
+    name: "No class= in JSX (should be className=)",
     severity: "warning",
     fn: (ctx) => {
       const srcDir = path.join(ctx.sourceDir, "src");
       if (!fs.existsSync(srcDir)) return true;
       const bad = findFilesWithPattern(srcDir, /<[a-zA-Z][^>]*\sclass\s*=/);
       if (bad.length > 0) {
-        console.log(`    Still has class= in JSX: ${bad.slice(0, 5).join(", ")}${bad.length > 5 ? ` (+${bad.length - 5} more)` : ""}`);
+        console.log(
+          `    Still has class= in JSX: ${bad.slice(0, 5).join(", ")}${bad.length > 5 ? ` (+${bad.length - 5} more)` : ""}`,
+        );
         return false;
       }
       return true;
@@ -158,12 +203,8 @@ export const checks: Check[] = [
         console.log("    public/ directory missing");
         return false;
       }
-      const hasSprites = fs.existsSync(
-        path.join(publicDir, "sprites.svg"),
-      );
-      const hasFavicon = fs.existsSync(
-        path.join(publicDir, "favicon.ico"),
-      );
+      const hasSprites = fs.existsSync(path.join(publicDir, "sprites.svg"));
+      const hasFavicon = fs.existsSync(path.join(publicDir, "favicon.ico"));
       if (!hasSprites) console.log("    Missing: public/sprites.svg");
       if (!hasFavicon) console.log("    Missing: public/favicon.ico");
       return hasSprites && hasFavicon;
@@ -272,7 +313,9 @@ export const checks: Check[] = [
       const bad = findFilesWithPattern(srcDir, /(?<!<(?:img|Image)[^>]*)-z-\d+/);
       if (bad.length > 0) {
         console.log(`    Negative z-index on non-image elements: ${bad.join(", ")}`);
-        console.log(`    These may be invisible due to stacking contexts. Replace with z-0 or positive z-index.`);
+        console.log(
+          `    These may be invisible due to stacking contexts. Replace with z-0 or positive z-index.`,
+        );
         return false;
       }
       return true;
@@ -319,7 +362,9 @@ export const checks: Check[] = [
         // Check that runtime.ts exists and has the invoke proxy
         const runtimePath = path.join(srcDir, "runtime.ts");
         if (!fs.existsSync(runtimePath)) {
-          console.log(`    Files use invoke.* but src/runtime.ts is missing: ${hasInvoke.join(", ")}`);
+          console.log(
+            `    Files use invoke.* but src/runtime.ts is missing: ${hasInvoke.join(", ")}`,
+          );
           return false;
         }
       }
@@ -374,7 +419,10 @@ export const checks: Check[] = [
     fn: (ctx) => {
       const srcDir = path.join(ctx.sourceDir, "src");
       if (!fs.existsSync(srcDir)) return true;
-      const bad = findFilesWithPattern(srcDir, /\bhx-(?:get|post|put|delete|patch|trigger|target|swap|on|indicator|sync|select)\b/);
+      const bad = findFilesWithPattern(
+        srcDir,
+        /\bhx-(?:get|post|put|delete|patch|trigger|target|swap|on|indicator|sync|select)\b/,
+      );
       if (bad.length > 0) {
         console.log(`    HTMX attributes found (needs manual React migration): ${bad.join(", ")}`);
         return false;
@@ -428,7 +476,9 @@ export const checks: Check[] = [
       ];
       const unique = [...new Set(bad)];
       if (unique.length > 0) {
-        console.log(`    Still references frozen @decocms/start or @decocms/apps/* specifiers: ${unique.join(", ")}`);
+        console.log(
+          `    Still references frozen @decocms/start or @decocms/apps/* specifiers: ${unique.join(", ")}`,
+        );
         return false;
       }
       return true;
@@ -445,9 +495,7 @@ export const checks: Check[] = [
         "src/setup/commerce-init.ts",
         "src/setup/section-loaders.ts",
       ];
-      const missing = setupFiles.filter(
-        (f) => !fs.existsSync(path.join(ctx.sourceDir, f)),
-      );
+      const missing = setupFiles.filter((f) => !fs.existsSync(path.join(ctx.sourceDir, f)));
       if (missing.length > 0) {
         console.log(`    Missing setup infrastructure: ${missing.join(", ")}`);
         return false;
@@ -463,9 +511,13 @@ export const checks: Check[] = [
       if (fs.existsSync(islandsDir)) {
         try {
           const files = fs.readdirSync(islandsDir, { recursive: true });
-          const tsxFiles = (files as string[]).filter((f: string) => f.endsWith(".tsx") || f.endsWith(".ts"));
+          const tsxFiles = (files as string[]).filter(
+            (f: string) => f.endsWith(".tsx") || f.endsWith(".ts"),
+          );
           if (tsxFiles.length > 0) {
-            console.log(`    src/islands/ still has ${tsxFiles.length} files — should be moved to components/`);
+            console.log(
+              `    src/islands/ still has ${tsxFiles.length} files — should be moved to components/`,
+            );
             return false;
           }
         } catch {}
@@ -482,9 +534,7 @@ export const checks: Check[] = [
         "src/hooks/useUser.ts",
         "src/hooks/useWishlist.ts",
       ];
-      const missing = hookFiles.filter(
-        (f) => !fs.existsSync(path.join(ctx.sourceDir, f)),
-      );
+      const missing = hookFiles.filter((f) => !fs.existsSync(path.join(ctx.sourceDir, f)));
       if (missing.length > 0) {
         console.log(`    Missing hooks: ${missing.join(", ")}`);
         return false;
@@ -502,9 +552,7 @@ export const checks: Check[] = [
         "src/types/deco.ts",
         "src/types/commerce-app.ts",
       ];
-      const missing = typeFiles.filter(
-        (f) => !fs.existsSync(path.join(ctx.sourceDir, f)),
-      );
+      const missing = typeFiles.filter((f) => !fs.existsSync(path.join(ctx.sourceDir, f)));
       if (missing.length > 0) {
         console.log(`    Missing type files: ${missing.join(", ")}`);
         return false;
@@ -525,7 +573,8 @@ function findFilesWithPattern(
   for (const entry of entries) {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "server") continue;
+      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "server")
+        continue;
       findFilesWithPattern(fullPath, pattern, results, root);
     } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
       const content = fs.readFileSync(fullPath, "utf-8");
@@ -558,7 +607,8 @@ function findMatchesWithPattern(
   for (const entry of entries) {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "server") continue;
+      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "server")
+        continue;
       findMatchesWithPattern(fullPath, pattern, results, root);
     } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
       const content = fs.readFileSync(fullPath, "utf-8");
@@ -586,7 +636,11 @@ export function verify(ctx: MigrationContext): boolean {
 
   for (const check of checks) {
     const pass = check.fn(ctx);
-    const icon = pass ? "\x1b[32m✓\x1b[0m" : check.severity === "error" ? "\x1b[31m✗\x1b[0m" : "\x1b[33m⚠\x1b[0m";
+    const icon = pass
+      ? "\x1b[32m✓\x1b[0m"
+      : check.severity === "error"
+        ? "\x1b[31m✗\x1b[0m"
+        : "\x1b[33m⚠\x1b[0m";
     console.log(`  ${icon} ${check.name}`);
     if (!pass) {
       if (check.severity === "error") errors++;

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

@@ -1090,8 +1090,8 @@ export const FRAMEWORK_DUPLICATES: FrameworkDuplicate[] = [
     sitePath: "src/sdk/useSuggestions.ts",
     canonicalImport: "@decocms/blocks/sdk/useSuggestions",
     // Fingerprint: hand-rolled hook with the module-level signal +
-    // serial-queue + latestQuery cancel pattern. Both casaevideo and
-    // baggagio independently invented this exact shape. Sites that
+    // serial-queue + latestQuery cancel pattern. Multiple production sites
+    // independently invented this exact shape. Sites that
     // already adopted `createUseSuggestions(…)` factory calls won't
     // match this signature.
     contentSignature: [
@@ -1702,9 +1702,21 @@ const ruleVtexProxyHandlerMissing: Rule = {
 const MODULE_SIGNAL_RE =
   /^(?:export\s+)?const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:\w+\.)?signal\s*\(/m;
 
+// Well-known signals returned by useUI(). These are never declared with
+// `const x = signal(...)` at module scope — they come from a hook — so
+// MODULE_SIGNAL_RE won't catch them. The list is stable: it's the public
+// API surface of useUI() across all deco storefronts.
+const WELL_KNOWN_UI_SIGNALS = new Set([
+  "displayCart",
+  "displayMenu",
+  "displayNav",
+  "displaySearchbar",
+  "displaySearchPopup",
+]);
+
 const ruleSignalValueReads: Rule = {
   id: "signal-value-reads",
-  title: "Module-level signal .value reads without useStore()",
+  title: "Signal .value reads without subscription (freezes UI)",
   run({ siteDir, fs }: RuleContext): Finding[] {
     const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
 
@@ -1724,7 +1736,13 @@ const ruleSignalValueReads: Rule = {
       }
     }
 
-    if (moduleSignals.size === 0) return [];
+    // Also check well-known useUI() signals — they never appear as module-level
+    // declarations, so MODULE_SIGNAL_RE never picks them up.
+    for (const name of WELL_KNOWN_UI_SIGNALS) {
+      if (!moduleSignals.has(name)) {
+        moduleSignals.set(name, "useUI()");
+      }
+    }
 
     // Pre-compile per-signal regexes once — avoids N×M compilations in Pass 2.
     const valueReMap = new Map<string, RegExp>(
@@ -1732,7 +1750,8 @@ const ruleSignalValueReads: Rule = {
     );
 
     // Pass 2: for each .tsx file, check per-signal whether .value is read
-    // without a matching useStore(name.store call in the same file.
+    // without a matching subscription in the same file.
+    // Accepts either useStore(name.store or useSignalValue(name as subscriptions.
     const tsxFiles = tsFiles.filter((f) => f.endsWith(".tsx"));
     const findings: Finding[] = [];
 
@@ -1743,18 +1762,17 @@ const ruleSignalValueReads: Rule = {
       for (const [name, declaredIn] of moduleSignals) {
         const valueRe = valueReMap.get(name)!;
         if (!valueRe.test(content)) continue;
-        // Per-signal subscription check: useStore(name.store is the canonical
-        // subscription pattern. A file that subscribes to a different signal
-        // is not considered subscribed to this one.
-        const subscribedRe = new RegExp(`\\buseStore\\s*\\(\\s*${name}\\.store\\b`);
+        const subscribedRe = new RegExp(
+          `\\buseStore\\s*\\(\\s*${name}\\.store\\b|\\buseSignalValue\\s*\\(\\s*${name}\\b`,
+        );
         if (subscribedRe.test(content)) continue;
 
         findings.push({
           rule: "signal-value-reads",
           severity: "warning",
           file: rel,
-          message: `'${name}.value' read without useStore() — component will not re-render when the signal changes`,
-          fix: `Use useStore(${name}.store, (s) => s) to subscribe, or replace with useQuery / useMutation`,
+          message: `'${name}.value' read without subscription — component will not re-render when the signal changes`,
+          fix: `Replace with \`const ${name}Value = useSignalValue(${name})\` (from ~/sdk/signal) or \`useStore(${name}.store)\``,
           meta: { signalName: name, declaredIn },
         });
       }

package/scripts/migrate/post-cleanup/shim-classify.test.ts

@@ -183,7 +183,7 @@ describe("classifyShimExports — type/interface declarations", () => {
   });
 });
 
-describe("classifyShimExports — real casaevideo-storefront fixtures", () => {
+describe("classifyShimExports — real production storefront fixtures", () => {
   it("vtex-segment.ts (mixed: stub + functional)", () => {
     const code = `
       export function getSegmentFromBag(_req?: any): Record<string, unknown> | null {

package/scripts/migrate/post-cleanup/shim-classify.ts

@@ -26,11 +26,11 @@
  * would need real semantic analysis. False negatives are tolerable; the
  * rule still warns when *any* imported symbol from the shim is a clear
  * stub, which is enough to surface the real-world regressions we've
- * actually seen on production sites (casaevideo: `getSegmentFromBag`,
+ * actually seen on production sites (e.g. `getSegmentFromBag`,
  * `getISCookiesFromBag`, `toProduct`).
  *
  * Implementation note — string parsing, not a real TypeScript AST. The
- * shim files are tiny by design (the casaevideo ones are 1-39 lines).
+ * shim files are tiny by design (the real ones are 1-39 lines).
  * A balanced-brace body extractor + small set of stub patterns covers
  * every case observed on real sites. If this ever needs to handle
  * decorators, generics on consts, or weirder JSX forms, the right move

package/scripts/migrate/source-layout.test.ts

@@ -19,6 +19,26 @@ function makeFs(paths: string[]): FsLike {
   };
 }
 
+/**
+ * FsLike where each dir path is tagged as populated (has files) or empty.
+ * `dirsWithFiles` exist AND report `hasFiles: true`; `emptyDirs` exist but
+ * report `hasFiles: false` (leftover stubs).
+ */
+function makeFsWithFiles(dirsWithFiles: string[], emptyDirs: string[] = []): FsLike {
+  const norm = (p: string) => p.replace(/\\/g, "/");
+  const populated = new Set(dirsWithFiles.map(norm));
+  const empty = new Set(emptyDirs.map(norm));
+  return {
+    existsSync(p) {
+      const n = norm(p);
+      return populated.has(n) || empty.has(n);
+    },
+    hasFiles(p) {
+      return populated.has(norm(p));
+    },
+  };
+}
+
 const SITE = "/site";
 
 describe("detectSourceLayout — classic layout", () => {
@@ -64,6 +84,29 @@ describe("detectSourceLayout — mixed layout", () => {
   });
 });
 
+describe("detectSourceLayout — empty leftover dirs (hasFiles)", () => {
+  it("ignores an EMPTY root sections/ next to a populated src/sections/ → modern", () => {
+    // The real portal-davinci case: leftover empty `sections/` + real `src/sections/`.
+    const fs = makeFsWithFiles(["/site/src/sections"], ["/site/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("modern");
+  });
+
+  it("ignores an EMPTY src/sections/ next to a populated root sections/ → classic", () => {
+    const fs = makeFsWithFiles(["/site/sections"], ["/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("classic");
+  });
+
+  it("still flags genuinely mixed (both populated) as mixed", () => {
+    const fs = makeFsWithFiles(["/site/sections", "/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("mixed");
+  });
+
+  it("empty dirs on both sides → empty", () => {
+    const fs = makeFsWithFiles([], ["/site/sections", "/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("empty");
+  });
+});
+
 describe("detectSourceLayout — empty layout", () => {
   it("returns empty when neither root nor src/ has recognised dirs", () => {
     const fs = makeFs(["/site/package.json", "/site/README.md"]);

package/scripts/migrate/source-layout.ts

@@ -31,19 +31,46 @@ const RECOGNISED_DIRS = ["sections", "islands", "components", "loaders", "action
 
 export interface FsLike {
   existsSync(p: string): boolean;
+  /**
+   * True when `p` is a directory containing at least one FILE (recursively).
+   * An empty leftover dir (e.g. a `sections/` stub next to a populated
+   * `src/sections/`) must NOT count as a layout, or it triggers a false
+   * "mixed layout" abort. Optional so existing `{ existsSync }` stubs keep
+   * working — when absent, mere existence counts (previous behaviour).
+   */
+  hasFiles?(p: string): boolean;
 }
 
-const realFs: FsLike = { existsSync: fs.existsSync };
+/** Recursively: does this dir hold at least one file? Empty dirs → false. */
+function realHasFiles(p: string): boolean {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(p, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const e of entries) {
+    if (e.isFile()) return true;
+    if (e.isDirectory() && realHasFiles(path.join(p, e.name))) return true;
+  }
+  return false;
+}
+
+const realFs: FsLike = { existsSync: fs.existsSync, hasFiles: realHasFiles };
 
 /**
  * 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)),
-  );
+  // A recognised dir only "counts" if it exists AND holds files — an empty
+  // leftover `sections/` next to a populated `src/sections/` is not a real
+  // second layout and must not trigger a "mixed" abort. Falls back to mere
+  // existence when the adapter doesn't implement hasFiles (old test stubs).
+  const counts = (p: string): boolean =>
+    fsAdapter.existsSync(p) && (fsAdapter.hasFiles ? fsAdapter.hasFiles(p) : true);
+  const hasRootDir = RECOGNISED_DIRS.some((d) => counts(path.join(sourceDir, d)));
+  const hasSrcDir = RECOGNISED_DIRS.some((d) => counts(path.join(sourceDir, "src", d)));
 
   if (hasRootDir && hasSrcDir) return "mixed";
   if (hasSrcDir) return "modern";