@decocms/start 2.12.0 → 2.14.0

package/.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -159,18 +159,44 @@ opt-in and tested.
 Older versions of the migration script's `phase-cleanup` had a bug where
 it actively rewrote valid `@decocms/apps/vtex/utils/*` and
 `@decocms/apps/vtex/client` imports back to the dead `~/lib/vtex-*` shims.
-Confirm your loaders import direct from `@decocms/apps`:
+
+The post-cleanup audit now classifies **per-symbol**: it reads each
+`~/lib/vtex-*` shim file, labels every named export as `stub`,
+`type-only`, or `functional`, and only flags an import when at least
+one imported symbol is a real silent stub (returns `null` / `{}` / `[]`
+/ identity-cast / unconditional throw). Functional helpers shipped
+alongside stubs (e.g. a `parseCookie` cookie parser, a `fetchSafe`
+wrapper) no longer create noise.
+
+The audit's finding names the exact stub symbols, e.g.
+
+```
+[WARNING] src/loaders/search/x.ts — Imports stub-only symbols from
+  vtex-transform (toProduct); vtex-segment (getSegmentFromBag) —
+  runtime is silently stubbed
+    fix: Repoint imports to '@decocms/apps/vtex/...' or
+         'apps/commerce/utils/...'
+```
+
+Manual sweep (still useful if you don't have the audit handy):
 
 ```bash
 rg "from ['\"]~/lib/vtex-" src/
 # Expected: 0 hits (or only site-specific reasons you can articulate)
 ```
 
-If you see hits, update the imports to point at `@decocms/apps/vtex/...`
-directly (or the corresponding `commerce/utils/*` if it's a generic
-utility). Your runtime behavior gets MUCH better — segment cookies, IS
-cookies, VTEX session auth all start working again instead of being
-silently stubbed to `{}` / `null`.
+When you see real findings, update the imports to point at
+`@decocms/apps/vtex/...` directly (or the corresponding
+`commerce/utils/*` if it's a generic utility). Your runtime behavior
+gets MUCH better — segment cookies, IS cookies, VTEX session auth all
+start working again instead of being silently stubbed to `{}` / `null`.
+
+**Note on `--fix`**: this rule is intentionally detect-only. Repointing
+imports requires a per-symbol map to canonical apps/start exports
+(e.g. `getSegmentFromBag` → `@decocms/apps/vtex/utils/segment`), which
+the framework doesn't ship yet. Detect-only is still strictly more
+useful than nothing — the precision means each finding maps to exactly
+one PR's worth of mechanical work.
 
 ## 6. Drop `src/types/widgets.ts` — framework owns it
 

package/CLAUDE.md

@@ -117,7 +117,7 @@ Schema is composed at runtime: `generate-schema.ts` produces section schemas, `c
 
 ## Migration Guide
 
-Detailed migration playbook from Fresh/Preact/Deno to TanStack Start/React/Workers is available at `.cursor/skills/deco-to-tanstack-migration/`. Covers:
+Detailed migration playbook from Fresh/Preact/Deno to TanStack Start/React/Workers is available at `.agents/skills/deco-to-tanstack-migration/` (the canonical location — also surfaced as a Cursor skill via the `.agents/` skills root). Covers:
 
 - Import rewrites (Preact → React, @preact/signals → @tanstack/store)
 - Deco framework elimination (@deco/deco/*, $fresh/*)

package/package.json

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

@@ -0,0 +1,137 @@
+/**
+ * Tests for Phase 9 (cleanup audit integration into migrate.ts).
+ *
+ * These exercise the wrapper logic — what it prints, when it fails,
+ * how it interacts with --strict and dry-run. The underlying audit
+ * rules are tested separately in post-cleanup/runner.test.ts; we
+ * stub the disk minimally here just to drive findings counts.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanupAudit } from "./phase-cleanup-audit";
+import { createContext } from "./types";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "deco-migrate-audit-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function makeCtx(overrides?: { dryRun?: boolean }) {
+  return createContext(tmpDir, {
+    dryRun: overrides?.dryRun ?? false,
+    verbose: false,
+  });
+}
+
+describe("cleanupAudit — dry-run", () => {
+  it("is a no-op in dry-run mode (returns false, no console output)", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx({ dryRun: true });
+    const failed = cleanupAudit(ctx);
+    expect(failed).toBe(false);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe("cleanupAudit — empty site", () => {
+  it("prints success and returns false when there are no findings", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx);
+    expect(failed).toBe(false);
+    const out = spy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/No findings/);
+    spy.mockRestore();
+  });
+});
+
+describe("cleanupAudit — info-only findings (e.g. local widgets.ts)", () => {
+  beforeEach(() => {
+    // Set up a finding for rule 6 (local-widgets-types):
+    // need src/types/widgets.ts + at least one importer.
+    fs.mkdirSync(path.join(tmpDir, "src", "types"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "types", "widgets.ts"),
+      "export type ImageWidget = string;\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, "src", "sections"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "sections", "Foo.tsx"),
+      'import type { ImageWidget } from "~/types/widgets";\nexport const x: ImageWidget = "y";\n',
+    );
+  });
+
+  it("prints the finding and returns false (info doesn't fail strict)", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx, { strict: true });
+    expect(failed).toBe(false);
+    const out = spy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/Local src\/types\/widgets\.ts/);
+    expect(out).toMatch(/widgets\.ts/);
+    expect(out).toMatch(/deco-post-cleanup --fix/);
+    spy.mockRestore();
+  });
+});
+
+describe("cleanupAudit — warning findings (vtex-shim-regression)", () => {
+  beforeEach(() => {
+    // Trigger rule 5 (vtex-shim-regression, warning severity):
+    // any file outside src/lib/ that imports from ~/lib/vtex-*.
+    fs.mkdirSync(path.join(tmpDir, "src", "loaders"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "Product.ts"),
+      'import { fetchSafe } from "~/lib/vtex-fetch";\nexport default fetchSafe;\n',
+    );
+  });
+
+  it("returns false in non-strict mode even with warning findings", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx, { strict: false });
+    expect(failed).toBe(false);
+    spy.mockRestore();
+  });
+
+  it("returns true in --strict mode when warning findings exist", () => {
+    const spyLog = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx, { strict: true });
+    expect(failed).toBe(true);
+    const out = spyLog.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/--strict/);
+    expect(out).toMatch(/failed the audit/);
+    spyLog.mockRestore();
+  });
+});
+
+describe("cleanupAudit — output truncation", () => {
+  beforeEach(() => {
+    // Fabricate >5 vtex-shim-regression findings to test the cap.
+    fs.mkdirSync(path.join(tmpDir, "src", "loaders"), { recursive: true });
+    for (let i = 0; i < 8; i++) {
+      fs.writeFileSync(
+        path.join(tmpDir, "src", "loaders", `Loader${i}.ts`),
+        'import { fetchSafe } from "~/lib/vtex-fetch";\n',
+      );
+    }
+  });
+
+  it("caps per-rule output at 5 with a 'and N more' suffix", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    cleanupAudit(ctx);
+    const out = spy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/and 3 more/);
+    spy.mockRestore();
+  });
+});

package/scripts/migrate/phase-cleanup-audit.ts

@@ -0,0 +1,105 @@
+/**
+ * Phase 9: Post-Migration Cleanup Audit
+ *
+ * Runs the same `deco-post-cleanup` audit logic as the standalone CLI,
+ * but inline at the tail of `deco-migrate`. The goal is to surface any
+ * residual debt the migration script can't fix on its own (e.g.
+ * silent vtex shim regressions, orphan TODOs, manual-review items)
+ * the moment the migration completes — without making the user
+ * remember a separate command.
+ *
+ * Behaviour:
+ * - Always READ-ONLY. Auto-fix is opt-in via the standalone CLI's
+ *   `--fix` flag — never invoked from inside the migration script
+ *   to keep the migration's mutation surface predictable.
+ * - Skipped in dry-run (no migrated output to scan).
+ * - Skipped via `--no-cleanup-audit` when integrated runs are noisy.
+ * - In `--strict` mode, returns true (caller exits 2) if any
+ *   warning-severity findings exist. Info findings never fail the
+ *   build — they're just hints.
+ */
+
+import { banner, bold, gray, green, red, yellow } from "./colors";
+import { realFsAdapter, runAudit } from "./post-cleanup/runner";
+import type { AuditReport, Severity } from "./post-cleanup/types";
+import type { MigrationContext } from "./types";
+
+export interface CleanupAuditOptions {
+  /** Promote warning findings to fatal (exit 2 from main). Default: false. */
+  strict?: boolean;
+}
+
+/**
+ * Returns `true` when the caller should exit with a non-zero code.
+ * Always false in normal mode — audit is informational by default.
+ */
+export function cleanupAudit(ctx: MigrationContext, opts: CleanupAuditOptions = {}): boolean {
+  if (ctx.dryRun) {
+    return false;
+  }
+
+  banner("Phase 9: Post-Migration Cleanup Audit");
+
+  const report = runAudit(ctx.sourceDir, realFsAdapter);
+
+  if (report.totalFindings === 0) {
+    console.log(`  ${green("✓")} No findings — migration output is clean.`);
+    return false;
+  }
+
+  printSummary(report);
+
+  const warnings = countSeverity(report, "warning");
+  const infos = countSeverity(report, "info");
+  const willFail = (opts.strict ?? false) && warnings > 0;
+
+  console.log("");
+  console.log(
+    `  ${bold("Audit:")} ${report.totalFindings} finding(s) — ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`,
+  );
+  console.log(
+    `  ${gray("Run")} ${bold("deco-post-cleanup --fix")} ${gray("from this directory to auto-correct the safe rules,")}`,
+  );
+  console.log(`  ${gray("or see post-migration-cleanup.md for the full per-rule playbook.")}`);
+
+  if (willFail) {
+    console.log(
+      `\n  ${red("--strict:")} ${warnings} warning-severity finding(s) failed the audit.`,
+    );
+    return true;
+  }
+
+  return false;
+}
+
+function severityTag(sev: Severity, text: string): string {
+  if (sev === "warning") return yellow(text);
+  return gray(text);
+}
+
+function printSummary(report: AuditReport): void {
+  let idx = 0;
+  for (const summary of report.rules) {
+    idx++;
+    if (summary.findings.length === 0) continue;
+    const headColor = yellow;
+    console.log(
+      `  ${headColor(`[${idx}] ${summary.title}`)} ${gray(`(${summary.findings.length} found)`)}`,
+    );
+    // Cap the per-rule output so a noisy site doesn't drown the
+    // migration's own report. Standalone CLI shows everything.
+    const visible = summary.findings.slice(0, 5);
+    for (const f of visible) {
+      const tag = severityTag(f.severity, `[${f.severity.toUpperCase()}]`);
+      console.log(`      ${tag} ${bold(f.file)} — ${f.message}`);
+    }
+    const hidden = summary.findings.length - visible.length;
+    if (hidden > 0) {
+      console.log(`      ${gray(`...and ${hidden} more (run deco-post-cleanup for full list)`)}`);
+    }
+  }
+}
+
+function countSeverity(report: AuditReport, sev: Severity): number {
+  return report.rules.flatMap((r) => r.findings).filter((f) => f.severity === sev).length;
+}

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

@@ -9,6 +9,7 @@
  * Rules are intentionally read-only here — `--fix` is a follow-up.
  */
 
+import { classifyShimExports, type ExportClass } from "./shim-classify";
 import type { Finding, FixAction, FsWriter, Rule, RuleContext } from "./types";
 
 const SRC_GLOB_EXCLUDES = ["node_modules", "dist", ".wrangler", ".vite", ".tanstack", "build"];
@@ -238,27 +239,97 @@ const ruleSiteLocalGlobals: Rule = {
 /* Rule 5 — `~/lib/vtex-*` shim regression                             */
 /* ------------------------------------------------------------------ */
 
+/**
+ * Parse one or more ES `import { a, b as c, type d } from "spec"` blocks
+ * targeting a specific source spec out of a file. Returns the list of
+ * imported names (resolved to their original symbol, ignoring `as`
+ * rebinds), with `import type {…}` and inline `type` modifiers stripped
+ * — those carry no runtime, so the rule treats them as out-of-scope.
+ */
+function namedRuntimeImportsFrom(content: string, spec: string): string[] {
+  const escaped = spec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // `(type\s+)?` captures the entire-import `import type { … }` form.
+  // Per-symbol `type` modifiers inside the braces are stripped below.
+  const re = new RegExp(
+    `import\\s+(type\\s+)?\\{([^}]+)\\}\\s+from\\s+['\"]${escaped}['\"]`,
+    "g",
+  );
+  const out: string[] = [];
+  for (const m of content.matchAll(re)) {
+    if (m[1]) continue; // entire import is type-only
+    for (const raw of m[2].split(",")) {
+      const trimmed = raw.trim();
+      if (!trimmed || trimmed.startsWith("type ")) continue;
+      // `foo as bar` → `foo` (we want the source symbol, not the local alias).
+      const sourceName = trimmed.split(/\s+as\s+/)[0].trim();
+      if (sourceName) out.push(sourceName);
+    }
+  }
+  return out;
+}
+
 const ruleVtexShimRegression: Rule = {
   id: "vtex-shim-regression",
   title: "Imports from ~/lib/vtex-* (silent stub regression)",
   run({ siteDir, fs }: RuleContext): Finding[] {
     const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
     const findings: Finding[] = [];
-    const re = /from\s+['"]~\/lib\/vtex-([A-Za-z0-9-]+)['"]/g;
+
+    // Per-shim classification cache. Each shim file is read at most once
+    // per audit run, even when imported by dozens of consumers.
+    const shimClasses = new Map<string, Map<string, ExportClass>>();
+    function classOf(shim: string, symbol: string): ExportClass {
+      let map = shimClasses.get(shim);
+      if (!map) {
+        const abs = `${siteDir}/src/lib/${shim}.ts`;
+        map = new Map<string, ExportClass>();
+        if (fs.exists(abs)) {
+          for (const ce of classifyShimExports(fs.readText(abs))) {
+            map.set(ce.name, ce.class);
+          }
+        }
+        shimClasses.set(shim, map);
+      }
+      // Unknown symbols (file missing or not exported) default to "stub" —
+      // pessimistic on purpose. If the symbol can't be found locally, the
+      // import is at best dead code, at worst a TS error; either way the
+      // user wants visibility into it. Compile phase catches the TS side.
+      return map.get(symbol) ?? "stub";
+    }
+
+    // Match the bare `from "~/lib/vtex-X"` to know which shims are touched.
+    const fromRe = /from\s+['"]~\/lib\/vtex-([A-Za-z0-9-]+)['"]/g;
     for (const abs of tsFiles) {
       if (abs.includes("/src/lib/")) continue;
       const content = fs.readText(abs);
-      const matches = [...content.matchAll(re)];
-      if (matches.length === 0) continue;
+      const usedShims = new Set<string>(
+        [...content.matchAll(fromRe)].map((m) => `vtex-${m[1]}`),
+      );
+      if (usedShims.size === 0) continue;
+
+      // Per-file: which shim → which stub symbols are imported.
+      const stubsBySim = new Map<string, string[]>();
+      for (const shim of usedShims) {
+        const symbols = namedRuntimeImportsFrom(content, `~/lib/${shim}`);
+        const stubs = symbols.filter((s) => classOf(shim, s) === "stub");
+        if (stubs.length > 0) stubsBySim.set(shim, stubs);
+      }
+      if (stubsBySim.size === 0) continue;
+
       const rel = abs.slice(siteDir.length + 1);
-      const shims = [...new Set(matches.map((m) => `vtex-${m[1]}`))];
+      const detail = [...stubsBySim.entries()]
+        .map(([s, syms]) => `${s} (${syms.join(", ")})`)
+        .join("; ")
+      ;
       findings.push({
         rule: "vtex-shim-regression",
         severity: "warning",
         file: rel,
-        message: `Imports from dead shim(s): ${shims.join(", ")} — runtime is silently stubbed`,
+        message: `Imports stub-only symbols from ${detail} — runtime is silently stubbed`,
         fix: "Repoint imports to '@decocms/apps/vtex/...' or 'apps/commerce/utils/...'",
-        meta: { shims },
+        meta: {
+          stubsBySim: Object.fromEntries(stubsBySim),
+        },
       });
     }
     return findings;

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -263,14 +263,19 @@ describe("rule: site-local-with-globals", () => {
 });
 
 describe("rule: vtex-shim-regression", () => {
-  it("flags imports from ~/lib/vtex-segment", () => {
+  // Default-pessimistic case: shim file missing → unknown symbols treated
+  // as stubs so audit always surfaces the import. (Compile phase catches
+  // the underlying TS error separately.)
+  it("flags imports when shim file is missing (defensive default)", () => {
     const fs = makeFs({
       "/site/src/sections/Foo.tsx": 'import { getSegment } from "~/lib/vtex-segment";\n',
     });
     const report = runAudit(SITE, fs);
     const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
     expect(r.findings).toHaveLength(1);
-    expect(r.findings[0].meta?.shims).toContain("vtex-segment");
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-segment": ["getSegment"],
+    });
   });
 
   it("does not flag imports from src/lib itself", () => {
@@ -281,6 +286,122 @@ describe("rule: vtex-shim-regression", () => {
     const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
     expect(r.findings).toEqual([]);
   });
+
+  it("does NOT flag when imported symbols are all functional", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-id.ts":
+        "export function parseCookie(s?: string): Record<string,string> {\n" +
+        "  if (!s) return {};\n" +
+        "  return Object.fromEntries(s.split(';').map(c => c.split('=') as [string,string]));\n" +
+        "}\n",
+      "/site/src/actions/x.ts": 'import { parseCookie } from "~/lib/vtex-id";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    // parseCookie has nested-block functional impl → not a stub → no warning.
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags only the stub symbols when import set is mixed", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-segment.ts":
+        "export function getSegmentFromBag(_req?: any): null { return null; }\n" +
+        "export function withSegmentCookie(headers: Headers): Headers {\n" +
+        "  headers.set('x', 'y');\n" +
+        "  return headers;\n" +
+        "}\n",
+      "/site/src/loaders/x.ts":
+        'import { getSegmentFromBag, withSegmentCookie } from "~/lib/vtex-segment";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-segment": ["getSegmentFromBag"],
+    });
+    expect(r.findings[0].message).toContain("getSegmentFromBag");
+    expect(r.findings[0].message).not.toContain("withSegmentCookie");
+  });
+
+  it("flags identity-cast (toProduct) as a stub", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-transform.ts":
+        "export function toProduct(p: any): unknown { return p as unknown; }\n",
+      "/site/src/loaders/search.ts":
+        'import { toProduct } from "~/lib/vtex-transform";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-transform": ["toProduct"],
+    });
+  });
+
+  it("does NOT flag `import type { X }` from a stub-having shim", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-client.ts":
+        "export interface VTEXCommerceStable { account: string; }\n" +
+        "export function stub(): null { return null; }\n",
+      "/site/src/loaders/x.ts":
+        'import type { VTEXCommerceStable } from "~/lib/vtex-client";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    // Type-only imports have no runtime → never a regression.
+    expect(r.findings).toEqual([]);
+  });
+
+  it("ignores per-symbol `type` modifier and only flags runtime imports", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-mixed.ts":
+        "export interface Cfg { a: string; }\n" +
+        "export function stub(): null { return null; }\n" +
+        "export function ok(): boolean { return true; }\n",
+      "/site/src/loaders/x.ts":
+        'import { type Cfg, stub, ok } from "~/lib/vtex-mixed";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-mixed": ["stub"],
+    });
+  });
+
+  it("aggregates findings per file across multiple shims", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-segment.ts":
+        "export function getSegmentFromBag(): null { return null; }\n",
+      "/site/src/lib/vtex-transform.ts":
+        "export function toProduct(p: any): unknown { return p as unknown; }\n",
+      "/site/src/loaders/search.ts":
+        'import { getSegmentFromBag } from "~/lib/vtex-segment";\n' +
+        'import { toProduct } from "~/lib/vtex-transform";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-segment": ["getSegmentFromBag"],
+      "vtex-transform": ["toProduct"],
+    });
+  });
+
+  it("supports `as`-renamed imports (resolves to source name)", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-segment.ts":
+        "export function getSegmentFromBag(): null { return null; }\n",
+      "/site/src/loaders/x.ts":
+        'import { getSegmentFromBag as getSeg } from "~/lib/vtex-segment";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.stubsBySim).toEqual({
+      "vtex-segment": ["getSegmentFromBag"],
+    });
+  });
 });
 
 describe("rule: local-widgets-types", () => {