@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/plugins/build-report.ts

@@ -13,11 +13,16 @@
  * Task: TIM-287
  */
 
+import { readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
 import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { SegmentNode, RouteTree } from '#/routing/types.js';
-import { formatSize } from '#/utils/format.js';
+import type { PluginContext } from '../plugin-context.js';
+import type { SegmentNode, RouteTree } from '../routing/types.js';
+import type { CaptureSummary } from '../server/prebuilt-builder.js';
+import type { PrebuiltManifest } from '../server/prebuilt/payload-source.js';
+import { collectLeafRoutes } from '../routing/walkers.js';
+import { formatSize } from '../utils/format.js';
 
 // ─── Public types ─────────────────────────────────────────────────────────
 
@@ -43,25 +48,19 @@ const ROUTE_TYPE_ICONS: Record<RouteType, string> = {
 /**
  * Classify a route by its segment chain and output mode.
  *
- * In server mode (default), all pages are dynamic (rendered per-request).
- * In static mode, only pages with dynamic/catch-all segments are dynamic.
- * API routes (route.ts) are always classified as function.
+ * In server mode (default), all pages are dynamic (rendered per-request)
+ * and API routes (route.ts) are classified as function.
+ * In static mode, everything is pre-rendered at build time — all routes
+ * are static regardless of dynamic segments or route.ts presence.
  */
 export function classifyRoute(
   segments: SegmentNode[],
   outputMode: 'server' | 'static' = 'server'
 ): RouteType {
+  if (outputMode === 'static') return 'static';
   const leaf = segments[segments.length - 1];
   if (leaf?.route) return 'function';
-  if (outputMode === 'server') return 'dynamic';
-
-  const isDynamic = segments.some(
-    (s) =>
-      s.segmentType === 'dynamic' ||
-      s.segmentType === 'catch-all' ||
-      s.segmentType === 'optional-catch-all'
-  );
-  return isDynamic ? 'dynamic' : 'static';
+  return 'dynamic';
 }
 
 // ─── Size helpers ─────────────────────────────────────────────────────────
@@ -83,33 +82,23 @@ interface RouteInfo {
 /**
  * Walk the route tree and collect all leaf routes (pages + API endpoints).
  *
- * Parallel slots (`@artists`, `@shows`, etc.) are intentionally skipped —
- * they render alongside the parent page at the same URL and are not
- * separately URL-addressable. Their JS is captured in shared/layout chunks.
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Parallel slots
+ * (`@artists`, `@shows`, etc.) are intentionally skipped — they render
+ * alongside the parent page at the same URL and are not separately
+ * URL-addressable. Their JS is captured in shared/layout chunks.
  *
  * After collection, entries are deduplicated by URL path so that overlapping
  * route groups (e.g. `(browse)` and `(marketing)` both producing `/`) only
- * appear once. The entry with the largest route-specific size wins.
+ * appear once. The entry with the longest segment chain (most specific
+ * match) wins.
  */
 export function collectRoutes(tree: RouteTree): RouteInfo[] {
-  const routes: RouteInfo[] = [];
-
-  function walk(node: SegmentNode, chain: SegmentNode[]): void {
-    const currentChain = [...chain, node];
-    const path = node.urlPath || '/';
-
-    if (node.page) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.page.filePath });
-    }
-    if (node.route) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.route.filePath });
-    }
-
-    // Recurse into child segments only — skip parallel slots (node.slots)
-    for (const child of node.children) walk(child, currentChain);
-  }
-
-  walk(tree.root, []);
+  const leaves = collectLeafRoutes(tree.root);
+  const routes: RouteInfo[] = leaves.map((leaf) => ({
+    path: leaf.urlPath,
+    segments: leaf.segments,
+    entryFilePath: leaf.page?.filePath ?? leaf.route?.filePath ?? null,
+  }));
 
   // Deduplicate entries with the same URL path (e.g. from overlapping route groups).
   // Keep the entry with the longest segment chain (most specific match).
@@ -169,6 +158,21 @@ export function buildRouteReport(entries: RouteEntry[], sharedSize: number): str
   return lines;
 }
 
+/** Check route entries against a First-Load-JS budget and return warning lines. */
+export function buildWarnings(entries: RouteEntry[], budget?: { firstLoadJs?: number }): string[] {
+  if (!budget?.firstLoadJs) return [];
+  const limit = budget.firstLoadJs;
+  const warnings: string[] = [];
+  for (const entry of entries) {
+    if (entry.firstLoadSize > limit) {
+      warnings.push(
+        `⚠ ${entry.path} first-load JS (${formatSize(entry.firstLoadSize)}) exceeds budget (${formatSize(limit)})`
+      );
+    }
+  }
+  return warnings;
+}
+
 function pad(str: string, width: number, align: 'left' | 'right' = 'right'): string {
   const gap = Math.max(0, width - stripAnsi(str).length);
   return align === 'left' ? ' '.repeat(gap) + str : str + ' '.repeat(gap);
@@ -179,6 +183,120 @@ function stripAnsi(str: string): string {
   return str.replace(/\u001b\[\d+m/g, '');
 }
 
+// ─── Prebuilt component stats ────────────────────────────────────────────
+
+export interface PrebuiltComponentStats {
+  componentId: string;
+  entryCount: number;
+  totalBytes: number;
+}
+
+export interface PrebuiltReportData {
+  components: PrebuiltComponentStats[];
+  totalEntries: number;
+  totalBytes: number;
+  skippedCount: number;
+  skippedReasons: Array<{ componentId: string; route: string; message: string }>;
+}
+
+export function loadPrebuiltManifest(buildDir: string): PrebuiltManifest | null {
+  try {
+    const raw = readFileSync(join(buildDir, 'prebuilt', 'manifest.json'), 'utf-8');
+    return JSON.parse(raw) as PrebuiltManifest;
+  } catch {
+    return null;
+  }
+}
+
+export function buildPrebuiltReportData(
+  manifest: PrebuiltManifest | null,
+  summary: CaptureSummary | undefined
+): PrebuiltReportData | null {
+  const hasCaptures = summary && (summary.captured > 0 || summary.skipped.length > 0);
+  if (!manifest && !hasCaptures) return null;
+
+  const components: PrebuiltComponentStats[] = [];
+  let totalEntries = 0;
+  let totalBytes = 0;
+
+  if (manifest) {
+    for (const [componentId, component] of Object.entries(manifest)) {
+      let entryCount = 0;
+      let componentBytes = 0;
+      for (const entry of Object.values(component.entries)) {
+        entryCount++;
+        componentBytes += entry.bytes ?? 0;
+      }
+      components.push({ componentId, entryCount, totalBytes: componentBytes });
+      totalEntries += entryCount;
+      totalBytes += componentBytes;
+    }
+    components.sort((a, b) => a.componentId.localeCompare(b.componentId));
+  }
+
+  const skippedCount = summary?.skipped.length ?? 0;
+  const skippedReasons = (summary?.skipped ?? []).map((s) => ({
+    componentId: s.componentId,
+    route: s.routeUrlPath,
+    message: s.message,
+  }));
+
+  return { components, totalEntries, totalBytes, skippedCount, skippedReasons };
+}
+
+export function buildPrebuiltReport(data: PrebuiltReportData): string[] {
+  const lines: string[] = [];
+
+  const total = data.totalEntries + data.skippedCount;
+  lines.push(
+    `Prebuilt ${data.totalEntries}/${total} entries across ` +
+      `${data.components.length} component${data.components.length !== 1 ? 's' : ''}` +
+      (data.totalBytes > 0 ? ` (${formatSize(data.totalBytes)} total)` : '') +
+      '.' +
+      (data.skippedCount > 0 ? ` ${data.skippedCount} skipped due to errors.` : '')
+  );
+
+  if (data.components.length > 0) {
+    lines.push('');
+    const nameHeader = 'Component';
+    const entriesHeader = 'Entries';
+    const sizeHeader = 'Size';
+
+    const nameW = Math.max(
+      nameHeader.length + 2,
+      ...data.components.map((c) => c.componentId.length + 4)
+    );
+    const entriesW = Math.max(entriesHeader.length, 8);
+    const sizeW = Math.max(sizeHeader.length, 10);
+    const totalW = nameW + entriesW + sizeW + 4;
+    const sep = '─'.repeat(totalW);
+
+    lines.push(
+      `${pad(nameHeader, nameW)}  ${pad(entriesHeader, entriesW, 'left')}  ${pad(sizeHeader, sizeW, 'left')}`
+    );
+    lines.push(sep);
+
+    for (const comp of data.components) {
+      const nameStr = `  ◆ ${comp.componentId}`;
+      const entriesStr = String(comp.entryCount);
+      const sizeStr = formatSize(comp.totalBytes);
+      lines.push(
+        `${pad(nameStr, nameW)}  ${pad(entriesStr, entriesW, 'left')}  ${pad(sizeStr, sizeW, 'left')}`
+      );
+    }
+  }
+
+  if (data.skippedReasons.length > 0) {
+    lines.push('');
+    lines.push('Skipped entries:');
+    for (const s of data.skippedReasons) {
+      lines.push(`  ⚠ ${s.componentId} (${s.route}) — ${s.message}`);
+    }
+  }
+
+  return lines;
+}
+
 // ─── Bundle analysis ──────────────────────────────────────────────────────
 
 interface ChunkSize {
@@ -189,6 +307,7 @@ interface ChunkSize {
 interface OutputChunkLike {
   type: 'chunk' | 'asset';
   fileName: string;
+  name?: string;
   code?: string;
   source?: string | Uint8Array;
   modules?: Record<string, unknown>;
@@ -228,13 +347,62 @@ export function findChunkForFile(
   return null;
 }
 
+// ─── Route → chunk group matching ────────────────────────────────────────
+
+/**
+ * Derive the expected client chunk group prefix for a route.
+ *
+ * Mirrors the `clientChunkGroup` logic: extract the first non-group segment
+ * from the route's file path under appDir. Routes at the root level or
+ * without a matching segment return null (their JS is in client-shared).
+ */
+function routeChunkGroupPrefix(entryFilePath: string, appDir: string, root: string): string | null {
+  const appPrefix = relative(root, appDir).replace(/\\/g, '/') + '/';
+  const relPath = relative(root, entryFilePath).replace(/\\/g, '/');
+  if (!relPath.startsWith(appPrefix)) return null;
+
+  const withinApp = relPath.slice(appPrefix.length);
+  const segments = withinApp.split('/');
+  for (const seg of segments) {
+    if (seg.includes('.')) break;
+    if (seg.startsWith('(') && seg.endsWith(')')) continue;
+    return `client-${seg}`;
+  }
+  return null;
+}
+
+/**
+ * Find all client bundle chunks belonging to a chunk group.
+ *
+ * Uses the chunk's `name` property (set by Rolldown from the `clientChunks`
+ * callback's return value) for exact matching. The `name` is the group name
+ * itself (e.g. `client-docs`), not the hashed filename.
+ */
+export function findChunksForGroup(
+  groupName: string,
+  chunkSizes: Map<string, ChunkSize>,
+  bundle?: Record<string, OutputChunkLike>
+): string[] {
+  if (!bundle) return [];
+  const matched: string[] = [];
+  for (const [fileName, item] of Object.entries(bundle)) {
+    if (item.type !== 'chunk') continue;
+    if (item.name === groupName && chunkSizes.has(fileName)) {
+      matched.push(fileName);
+    }
+  }
+  return matched;
+}
+
 // ─── Build route entries from collected data ──────────────────────────────
 
 function buildEntries(
   routeTree: RouteTree,
   chunkSizes: Map<string, ChunkSize>,
   bundle: Record<string, OutputChunkLike>,
-  outputMode: 'server' | 'static'
+  outputMode: 'server' | 'static',
+  appDir?: string,
+  root?: string
 ): { entries: RouteEntry[]; sharedGzip: number } {
   const routeInfos = collectRoutes(routeTree);
 
@@ -242,7 +410,7 @@ function buildEntries(
   let totalGzip = 0;
   for (const s of chunkSizes.values()) totalGzip += s.gzip;
 
-  // Per-route sizes and track route-specific chunks
+  // Per-route sizes. Track route-specific chunks to compute shared size.
   const routeChunkFiles = new Set<string>();
   const entries: RouteEntry[] = [];
 
@@ -251,14 +419,36 @@ function buildEntries(
     let gzip = 0;
 
     if (info.entryFilePath) {
-      const chunk = findChunkForFile(info.entryFilePath, bundle);
-      if (chunk) {
-        const s = chunkSizes.get(chunk);
-        if (s) {
-          raw = s.raw;
-          gzip = s.gzip;
+      // Try chunk group matching first (works for server component routes
+      // whose client JS is in client-<segment> chunks, not in the route's
+      // own page.tsx chunk). Falls back to direct chunk lookup.
+      let matched = false;
+      if (appDir && root) {
+        const groupPrefix = routeChunkGroupPrefix(info.entryFilePath, appDir, root);
+        if (groupPrefix) {
+          const chunks = findChunksForGroup(groupPrefix, chunkSizes, bundle);
+          for (const chunk of chunks) {
+            const s = chunkSizes.get(chunk);
+            if (s) {
+              raw += s.raw;
+              gzip += s.gzip;
+            }
+            routeChunkFiles.add(chunk);
+          }
+          if (chunks.length > 0) matched = true;
+        }
+      }
+
+      if (!matched) {
+        const chunk = findChunkForFile(info.entryFilePath, bundle);
+        if (chunk) {
+          const s = chunkSizes.get(chunk);
+          if (s) {
+            raw = s.raw;
+            gzip = s.gzip;
+          }
+          routeChunkFiles.add(chunk);
         }
-        routeChunkFiles.add(chunk);
       }
     }
 
@@ -357,17 +547,39 @@ export function timberBuildReport(ctx: PluginContext): Plugin {
             })),
             sharedGzip: 0,
           }
-        : buildEntries(ctx.routeTree, chunkSizes, clientBundle, outputMode);
+        : buildEntries(ctx.routeTree, chunkSizes, clientBundle, outputMode, ctx.appDir, ctx.root);
       const elapsed = ((performance.now() - buildStart) / 1000).toFixed(2);
       const lines = buildRouteReport(entries, sharedGzip);
 
       logger.info('');
       for (const line of lines) logger.info(line);
+
+      const warnings = buildWarnings(entries, ctx.config.budget);
+      if (warnings.length > 0) {
+        logger.info('');
+        for (const w of warnings) logger.warn(w);
+      }
+
       logger.info('');
       logger.info(
         `✓ built ${entries.length} routes for all three environments (rsc, ssr, client) in ${elapsed}s`
       );
       logger.info('');
     },
+
+    buildApp: {
+      order: 'post' as const,
+      async handler() {
+        if (ctx.dev || !logger) return;
+        const manifest = loadPrebuiltManifest(ctx.buildDir);
+        const prebuiltData = buildPrebuiltReportData(manifest, ctx.captureSummary);
+        if (!prebuiltData) return;
+
+        logger.info('');
+        const prebuiltLines = buildPrebuiltReport(prebuiltData);
+        for (const line of prebuiltLines) logger.info(line);
+        logger.info('');
+      },
+    },
   };
 }

package/src/plugins/cache.ts

@@ -0,0 +1,243 @@
+/**
+ * timber-cache-transform — Vite plugin that injects stable callsite IDs
+ * into `cache.data()` calls imported from `@timber-js/app/cache`.
+ *
+ * Detected callsite forms (TIM-1054):
+ *   - named imports, including aliases: `import { cache as c }` + `c.data(fn, opts)`
+ *   - namespace imports: `import * as ns` + `ns.cache.data(fn, opts)`
+ * Forms a per-module transform cannot trace — local variable aliases
+ * (`const c = cache`), user re-export wrapper modules, computed access
+ * (`cache['data']`) — fall back to the runtime fnId derived from
+ * fnv1a(fn.toString()) (see cache/timber-cache.ts), which is deterministic
+ * across instances and cold starts of the same build. Without either
+ * mechanism, an ordinal counter would collide across instances with a shared
+ * CacheHandler (Redis/KV) — cache key poisoning, serving one route's cached
+ * data to another.
+ *
+ * The plugin transforms:
+ *   cache.data(fn, opts)          →  cache.data(fn, opts, "stable-id")
+ *   ns.cache.data(fn, opts)       →  ns.cache.data(fn, opts, "stable-id")
+ *
+ * where stable-id =
+ *   fnv1a(relPath + ":cache:" + fnv1a(stmtText) + ":" + fnv1a(callSpanText) + ":" + occurrence)
+ *
+ * stmtText is the source text of the enclosing *top-level statement* and
+ * callSpanText is the source text of the cache(...) call expression itself.
+ *
+ * The ID is derived from the *content* of the call, not its ordinal position
+ * in the file. A position-based index (the original TIM-997 scheme) was stable
+ * within one build but shifted across builds: inserting, deleting, or
+ * reordering a cache() call changed the index of every call below it, so with
+ * a persistent shared CacheHandler (Redis/KV) a new function could inherit
+ * another function's old ID and serve its persisted data — cross-deploy cache
+ * poisoning (TIM-1053). Content hashing makes IDs immune to reordering and
+ * unrelated edits, while a changed call gets a fresh ID — which is exactly
+ * when invalidation is wanted.
+ *
+ * The enclosing-statement text is included so that byte-identical cache.data()
+ * calls in different scopes — e.g. two factory helpers that each `return
+ * cache.data(fn, { ttl: 60 })` — get distinct, insertion-stable IDs: their
+ * enclosing declarations differ by name/body even when the call spans are
+ * identical. Without it, a source-order occurrence counter alone would shift
+ * when an identical span is inserted above, reassigning IDs across deploys.
+ * Calls that are byte-identical INCLUDING their enclosing top-level statement
+ * are disambiguated by a source-order occurrence index. That residue is safe:
+ * identical top-level declarations are a redeclaration error, so fully
+ * identical (statement, call) pairs can only be expression statements
+ * referencing the same bindings — the same function, where an ID swap is
+ * harmless.
+ *
+ * AST helpers and the ID derivation are shared with timber-prebuilt
+ * (plugins/prebuilt.ts) via plugins/callsite-ast.ts.
+ *
+ * See TIM-997, TIM-1053, design/06-caching.md §"Cache Key Security".
+ */
+
+import { relative } from 'node:path';
+import MagicString from 'magic-string';
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+import {
+  CACHE_MODULE_SOURCES,
+  collectShadowRanges,
+  findCallSites,
+  findImportBindings,
+  generateStableCallsiteId,
+} from './callsite-ast.js';
+import type {
+  CallExpressionNode,
+  IdentifierNode,
+  ImportBindings,
+  MemberExpressionNode,
+  PositionedNode,
+  ProgramNode,
+  ShadowRange,
+} from './callsite-ast.js';
+
+/**
+ * Is this callee a `cache.data(...)` call? Matches two forms:
+ *   - Named import: `cache.data(fn, opts)` where `cache` is the imported binding
+ *   - Namespace import: `ns.cache.data(fn, opts)` where `ns` is the namespace
+ * Computed access (`cache['data']`) is deliberately not matched; it falls back
+ * to the runtime fnId derivation.
+ */
+function isCacheDataCallee(callee: PositionedNode, bindings: ImportBindings): boolean {
+  if (callee.type !== 'MemberExpression') return false;
+  const member = callee as unknown as MemberExpressionNode;
+  if (member.computed) return false;
+  if (member.property.type !== 'Identifier' || (member.property as IdentifierNode).name !== 'data')
+    return false;
+
+  const obj = member.object;
+  // Named import: `cache.data(...)` — obj is the imported `cache` identifier
+  if (obj.type === 'Identifier') {
+    return bindings.named.has((obj as IdentifierNode).name);
+  }
+  // Namespace import: `ns.cache.data(...)` — obj is `ns.cache`
+  if (obj.type === 'MemberExpression') {
+    const outer = obj as unknown as MemberExpressionNode;
+    return (
+      !outer.computed &&
+      outer.object.type === 'Identifier' &&
+      bindings.namespaces.has((outer.object as IdentifierNode).name) &&
+      outer.property.type === 'Identifier' &&
+      (outer.property as IdentifierNode).name === 'cache'
+    );
+  }
+  return false;
+}
+
+/**
+ * Extract the local binding name that a cache.data callee resolves to — the
+ * `cache` identifier for named imports, or the namespace object for `ns.cache.data()`.
+ */
+function calleeBindingName(callee: PositionedNode, bindings: ImportBindings): string | null {
+  if (callee.type !== 'MemberExpression') return null;
+  const member = callee as unknown as MemberExpressionNode;
+  const obj = member.object;
+  // Named import: `cache.data(...)` — binding is `cache`
+  if (obj.type === 'Identifier') {
+    const name = (obj as IdentifierNode).name;
+    return bindings.named.has(name) ? name : null;
+  }
+  // Namespace import: `ns.cache.data(...)` — binding is `ns`
+  if (obj.type === 'MemberExpression') {
+    const outer = obj as unknown as MemberExpressionNode;
+    if (outer.object.type === 'Identifier') {
+      const name = (outer.object as IdentifierNode).name;
+      return bindings.namespaces.has(name) ? name : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Generate a stable callsite ID for a cache() call. See callsite-ast.ts for
+ * the derivation properties.
+ */
+function generateStableId(
+  relativeModulePath: string,
+  statementText: string,
+  callSpanText: string,
+  occurrence: number
+): string {
+  return generateStableCallsiteId(
+    relativeModulePath,
+    'cache',
+    statementText,
+    callSpanText,
+    occurrence
+  );
+}
+
+export function timberCacheTransform(ctx: PluginContext): Plugin {
+  return {
+    name: 'timber-cache-transform',
+
+    transform(code, id) {
+      if (!code.includes('@timber-js/app/cache') && !code.includes('timber/cache')) return;
+      // Skip node_modules (don't transform third-party code)
+      if (id.includes('node_modules')) return;
+
+      let program: ProgramNode;
+      try {
+        program = ctx.parseCached!.parse(code);
+      } catch {
+        return;
+      }
+
+      const cacheBindings = findImportBindings(program, CACHE_MODULE_SOURCES, 'cache');
+      if (cacheBindings.named.size === 0 && cacheBindings.namespaces.size === 0) return;
+
+      // Collect byte ranges where tracked binding names are shadowed by
+      // function/arrow parameters or catch bindings (TIM-1141). Calls inside
+      // these ranges are NOT rewritten — they fall back to the runtime fnId.
+      const trackedNames = new Set([...cacheBindings.named, ...cacheBindings.namespaces]);
+      const shadowRanges: ShadowRange[] = [];
+      collectShadowRanges(program, trackedNames, shadowRanges);
+
+      // Check whether the specific binding name a callee resolves to is
+      // shadowed at the call position. Only that name is blocked — other
+      // tracked imports from the same module remain valid (codex review
+      // on PR #876).
+      const isCalleeShadowed = (call: CallExpressionNode): boolean => {
+        const name = calleeBindingName(call.callee, cacheBindings);
+        if (!name) return false;
+        return shadowRanges.some(
+          (r) => call.start >= r.start && call.start < r.end && r.names.has(name)
+        );
+      };
+
+      // Collect call sites per top-level statement so each call carries its
+      // enclosing statement's source text into the ID hash.
+      const callSites: Array<{ call: CallExpressionNode; stmt: PositionedNode }> = [];
+      for (const stmt of program.body) {
+        const calls: CallExpressionNode[] = [];
+        findCallSites(
+          stmt,
+          (call) =>
+            call.arguments.length === 2 &&
+            isCacheDataCallee(call.callee, cacheBindings) &&
+            !isCalleeShadowed(call),
+          calls
+        );
+        for (const call of calls) callSites.push({ call, stmt });
+      }
+      if (callSites.length === 0) return;
+
+      // Sort by position in file so occurrence indices among byte-identical
+      // (statement, call) pairs are assigned in deterministic source order
+      callSites.sort((a, b) => a.call.start - b.call.start);
+
+      const root = ctx.root || process.cwd();
+      const relPath = relative(root, id);
+      const s = new MagicString(code);
+      const occurrences = new Map<string, number>();
+
+      for (const { call, stmt } of callSites) {
+        const stmtText = code.slice(stmt.start, stmt.end);
+        const spanText = code.slice(call.start, call.end);
+        const dupKey = stmtText + String.fromCharCode(0) + spanText;
+        const occurrence = occurrences.get(dupKey) ?? 0;
+        occurrences.set(dupKey, occurrence + 1);
+        const stableId = generateStableId(relPath, stmtText, spanText, occurrence);
+        // Insert the stable ID as the 3rd argument directly after the last
+        // argument — NOT before the closing ')'. The call may already have a
+        // trailing comma after the options argument (Prettier v3 default for
+        // multiline calls); inserting before ')' would emit `,, "id"`, a
+        // parse error (TIM-1021). A trailing comma after the inserted
+        // argument remains valid JS.
+        const lastArg = call.arguments[call.arguments.length - 1];
+        s.appendLeft(lastArg.end, `, "${stableId}"`);
+      }
+
+      return {
+        code: s.toString(),
+        map: s.generateMap({ hires: 'boundary' }),
+      };
+    },
+  };
+}
+
+// Exported for testing
+export { generateStableId };