@timber-js/app 0.2.0-alpha.160 → 0.2.0-alpha.163

package/src/plugins/cache.ts

@@ -60,6 +60,7 @@ import type { Plugin } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
 import {
   CACHE_MODULE_SOURCES,
+  collectShadowRanges,
   findCallSites,
   findImportBindings,
   generateStableCallsiteId,
@@ -71,6 +72,7 @@ import type {
   MemberExpressionNode,
   PositionedNode,
   ProgramNode,
+  ShadowRange,
 } from './callsite-ast.js';
 
 /**
@@ -96,6 +98,25 @@ function isCacheCallee(callee: PositionedNode, bindings: ImportBindings): boolea
   return false;
 }
 
+/**
+ * Extract the local binding name that a cache callee resolves to — the
+ * identifier for named imports, or the namespace object for `ns.cache()`.
+ */
+function calleeBindingName(callee: PositionedNode, bindings: ImportBindings): string | null {
+  if (callee.type === 'Identifier') {
+    const name = (callee as IdentifierNode).name;
+    return bindings.named.has(name) ? name : null;
+  }
+  if (callee.type === 'MemberExpression') {
+    const member = callee as unknown as MemberExpressionNode;
+    if (member.object.type === 'Identifier') {
+      const name = (member.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.
@@ -134,6 +155,25 @@ export function timberCacheTransform(ctx: PluginContext): Plugin {
       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 }> = [];
@@ -141,7 +181,10 @@ export function timberCacheTransform(ctx: PluginContext): Plugin {
         const calls: CallExpressionNode[] = [];
         findCallSites(
           stmt,
-          (call) => call.arguments.length === 2 && isCacheCallee(call.callee, cacheBindings),
+          (call) =>
+            call.arguments.length === 2 &&
+            isCacheCallee(call.callee, cacheBindings) &&
+            !isCalleeShadowed(call),
           calls
         );
         for (const call of calls) callSites.push({ call, stmt });

package/src/plugins/callsite-ast.ts

@@ -95,16 +95,321 @@ export function findImportBindings(
   return { named, namespaces };
 }
 
+/** Extract all bound identifier names from a parameter/binding pattern. */
+function collectPatternNames(node: PositionedNode, out: Set<string>): void {
+  switch (node.type) {
+    case 'Identifier':
+      out.add((node as IdentifierNode).name);
+      break;
+    case 'AssignmentPattern':
+      collectPatternNames(node.left as PositionedNode, out);
+      break;
+    case 'RestElement':
+      collectPatternNames(node.argument as PositionedNode, out);
+      break;
+    case 'ArrayPattern':
+      for (const el of (node.elements as (PositionedNode | null)[] | undefined) ?? []) {
+        if (el) collectPatternNames(el, out);
+      }
+      break;
+    case 'ObjectPattern':
+      for (const prop of (node.properties as PositionedNode[] | undefined) ?? []) {
+        if (prop.type === 'RestElement') {
+          collectPatternNames(prop, out);
+        } else {
+          collectPatternNames(prop.value as PositionedNode, out);
+        }
+      }
+      break;
+    case 'TSParameterProperty':
+      // TS constructor parameter properties: `constructor(private cache)`
+      if (node.parameter) collectPatternNames(node.parameter as PositionedNode, out);
+      break;
+  }
+}
+
+/** Return the intersection of param names with `tracked`, or null if none. */
+function shadowedParamNames(
+  params: PositionedNode[] | undefined,
+  tracked: ReadonlySet<string>
+): Set<string> | null {
+  if (!params) return null;
+  const names = new Set<string>();
+  for (const p of params) collectPatternNames(p, names);
+  const hit = new Set<string>();
+  for (const n of names) {
+    if (tracked.has(n)) hit.add(n);
+  }
+  return hit.size > 0 ? hit : null;
+}
+
+/**
+ * Collect names declared by `VariableDeclaration`, `FunctionDeclaration`,
+ * and `ClassDeclaration` in a statement list. Only scans direct children
+ * (not nested blocks). For-loop bindings are NOT included — they are
+ * scoped to the loop statement and handled separately in
+ * `collectShadowRanges` (codex review round 4 on PR #876).
+ */
+function collectLexicalDeclNames(stmts: PositionedNode[], out: Set<string>): void {
+  for (const stmt of stmts) {
+    if (stmt.type === 'VariableDeclaration') {
+      for (const decl of (stmt.declarations as PositionedNode[] | undefined) ?? []) {
+        if (decl.id) collectPatternNames(decl.id as PositionedNode, out);
+      }
+    } else if (stmt.type === 'FunctionDeclaration' || stmt.type === 'ClassDeclaration') {
+      if (stmt.id && (stmt.id as PositionedNode).type === 'Identifier') {
+        out.add((stmt.id as IdentifierNode).name);
+      }
+    }
+  }
+}
+
+/**
+ * Extract binding names from a for-loop's init/left clause, but ONLY for
+ * `const`/`let` (block-scoped). `var` bindings hoist to the enclosing
+ * function and are handled by `collectVarDeclNames` instead (codex review
+ * round 5 on PR #876).
+ */
+function collectForLoopBlockBindingNames(loop: PositionedNode, out: Set<string>): void {
+  const init = (loop.init ?? loop.left) as PositionedNode | undefined;
+  if (init?.type === 'VariableDeclaration' && init.kind !== 'var') {
+    for (const decl of (init.declarations as PositionedNode[] | undefined) ?? []) {
+      if (decl.id) collectPatternNames(decl.id as PositionedNode, out);
+    }
+  }
+}
+
+/**
+ * Recursively collect `var` declaration names from a statement tree.
+ * `var` hoists to the enclosing function regardless of block nesting,
+ * so we must scan nested blocks, loops, switch cases, etc.
+ */
+function collectVarDeclNames(stmts: PositionedNode[], out: Set<string>): void {
+  for (const stmt of stmts) {
+    if (stmt.type === 'VariableDeclaration' && stmt.kind === 'var') {
+      for (const decl of (stmt.declarations as PositionedNode[] | undefined) ?? []) {
+        if (decl.id) collectPatternNames(decl.id as PositionedNode, out);
+      }
+    }
+    // Recurse into blocks, loops, if/else, switch, etc.
+    if (stmt.type === 'BlockStatement' || stmt.type === 'StaticBlock') {
+      collectVarDeclNames((stmt.body as PositionedNode[] | undefined) ?? [], out);
+    } else if (stmt.type === 'IfStatement') {
+      if (stmt.consequent) collectVarDeclNames([stmt.consequent as PositionedNode], out);
+      if (stmt.alternate) collectVarDeclNames([stmt.alternate as PositionedNode], out);
+    } else if (stmt.type === 'SwitchStatement') {
+      for (const c of (stmt.cases as PositionedNode[] | undefined) ?? []) {
+        collectVarDeclNames((c.consequent as PositionedNode[] | undefined) ?? [], out);
+      }
+    } else if (
+      stmt.type === 'ForStatement' ||
+      stmt.type === 'ForInStatement' ||
+      stmt.type === 'ForOfStatement' ||
+      stmt.type === 'WhileStatement' ||
+      stmt.type === 'DoWhileStatement'
+    ) {
+      const init = (stmt.init ?? stmt.left) as PositionedNode | undefined;
+      if (init?.type === 'VariableDeclaration' && init.kind === 'var') {
+        for (const decl of (init.declarations as PositionedNode[] | undefined) ?? []) {
+          if (decl.id) collectPatternNames(decl.id as PositionedNode, out);
+        }
+      }
+      if (stmt.body) collectVarDeclNames([stmt.body as PositionedNode], out);
+    } else if (stmt.type === 'WithStatement' || stmt.type === 'LabeledStatement') {
+      if (stmt.body) collectVarDeclNames([stmt.body as PositionedNode], out);
+    } else if (stmt.type === 'TryStatement') {
+      if (stmt.block) collectVarDeclNames([stmt.block as PositionedNode], out);
+      const handler = stmt.handler as PositionedNode | undefined;
+      if (handler?.body) collectVarDeclNames([handler.body as PositionedNode], out);
+      if (stmt.finalizer) collectVarDeclNames([stmt.finalizer as PositionedNode], out);
+    }
+  }
+}
+
+export interface ShadowRange {
+  start: number;
+  end: number;
+  /** Which tracked binding names are shadowed in this range. */
+  names: ReadonlySet<string>;
+}
+
+/**
+ * Collect byte ranges where any name in `tracked` is shadowed by a
+ * function/arrow parameter, catch clause binding, or lexical declaration
+ * (`const`/`let`/`var`, `function`, `class`, for-loop binding). Calls
+ * inside these ranges must NOT be rewritten — the name resolves to the
+ * local binding, not the import (TIM-1141).
+ *
+ * Each range records WHICH names are shadowed so the consumer can skip
+ * only calls to the shadowed name, not unrelated imports (codex review
+ * on PR #876).
+ *
+ * When a scope shadows some-but-not-all tracked names, the walker
+ * continues descending to find inner scopes that shadow remaining names
+ * (codex review round 2 on PR #876).
+ */
+export function collectShadowRanges(
+  node: PositionedNode,
+  tracked: ReadonlySet<string>,
+  ranges: ShadowRange[]
+): void {
+  if (tracked.size === 0) return;
+
+  const isFn =
+    node.type === 'FunctionDeclaration' ||
+    node.type === 'FunctionExpression' ||
+    node.type === 'ArrowFunctionExpression';
+
+  let remainingTracked = tracked;
+
+  // ── Function/arrow parameters + named function expression id ───────
+  if (isFn) {
+    const paramNames = new Set<string>();
+    for (const p of (node.params as PositionedNode[] | undefined) ?? []) {
+      collectPatternNames(p, paramNames);
+    }
+    // Named function expressions: `const w = function cache() { ... }`
+    // — the name is in scope inside the body (codex review round 5).
+    if (node.type === 'FunctionExpression' && node.id) {
+      const fnId = node.id as PositionedNode;
+      if (fnId.type === 'Identifier') paramNames.add((fnId as IdentifierNode).name);
+    }
+    const shadowed = new Set<string>();
+    for (const n of paramNames) {
+      if (tracked.has(n)) shadowed.add(n);
+    }
+    if (shadowed.size > 0) {
+      ranges.push({ start: node.start, end: node.end, names: shadowed });
+      if (shadowed.size === tracked.size) return;
+      remainingTracked = new Set([...tracked].filter((n) => !shadowed.has(n)));
+    }
+  }
+
+  // ── Catch clause binding ───────────────────────────────────────────
+  if (node.type === 'CatchClause') {
+    const param = node.param as PositionedNode | undefined;
+    if (param) {
+      const shadowed = shadowedParamNames([param], tracked);
+      if (shadowed) {
+        ranges.push({ start: node.start, end: node.end, names: shadowed });
+        if (shadowed.size === tracked.size) return;
+        remainingTracked = new Set([...tracked].filter((n) => !shadowed.has(n)));
+      }
+    }
+  }
+
+  // ── Named class expressions ───────────────────────────────────────
+  // `const C = class cache { ... }` — the class name is in scope inside
+  // the class body (codex review round 6 on PR #876).
+  if (node.type === 'ClassExpression' && node.id) {
+    const clsId = node.id as PositionedNode;
+    if (clsId.type === 'Identifier' && remainingTracked.has((clsId as IdentifierNode).name)) {
+      const names = new Set([(clsId as IdentifierNode).name]);
+      ranges.push({ start: node.start, end: node.end, names });
+      if (names.size === remainingTracked.size) return;
+      remainingTracked = new Set([...remainingTracked].filter((n) => !names.has(n)));
+    }
+  }
+
+  // ── For-loop bindings (scoped to the loop, not the enclosing body) ─
+  // `for (const cache of items) { ... }` shadows `cache` only inside
+  // the loop statement, not in the rest of the function. Codex review
+  // round 4 on PR #876.
+  if (
+    node.type === 'ForStatement' ||
+    node.type === 'ForInStatement' ||
+    node.type === 'ForOfStatement'
+  ) {
+    const loopNames = new Set<string>();
+    collectForLoopBlockBindingNames(node, loopNames);
+    const loopShadowed = new Set<string>();
+    for (const n of loopNames) {
+      if (remainingTracked.has(n)) loopShadowed.add(n);
+    }
+    if (loopShadowed.size > 0) {
+      ranges.push({ start: node.start, end: node.end, names: loopShadowed });
+      if (loopShadowed.size === remainingTracked.size) return;
+      remainingTracked = new Set([...remainingTracked].filter((n) => !loopShadowed.has(n)));
+    }
+  }
+
+  // ── Lexical declarations in function/block/switch bodies ────────────
+  // `const cache = ...`, `function cache() {}`, `class cache {}` inside
+  // a function body, block, or switch shadow the tracked name for the
+  // enclosing scope. `var` hoists to the enclosing function — scanned
+  // recursively. Codex review rounds 3 & 5 on PR #876.
+  const isScope =
+    isFn ||
+    node.type === 'BlockStatement' ||
+    node.type === 'SwitchStatement' ||
+    node.type === 'StaticBlock';
+  if (isScope) {
+    let bodyStmts: PositionedNode[] | null = null;
+    if (isFn) {
+      const body = node.body as PositionedNode | undefined;
+      if (body?.type === 'BlockStatement') {
+        bodyStmts = (body.body as PositionedNode[] | undefined) ?? null;
+      }
+    } else if (node.type === 'SwitchStatement') {
+      // Switch cases: declarations in unbraced cases are scoped to the switch block
+      const caseStmts: PositionedNode[] = [];
+      for (const c of (node.cases as PositionedNode[] | undefined) ?? []) {
+        for (const s of (c.consequent as PositionedNode[] | undefined) ?? []) {
+          caseStmts.push(s);
+        }
+      }
+      bodyStmts = caseStmts;
+    } else {
+      bodyStmts = (node.body as PositionedNode[] | undefined) ?? null;
+    }
+    if (bodyStmts) {
+      const declNames = new Set<string>();
+      collectLexicalDeclNames(bodyStmts, declNames);
+      // For function scopes, also collect hoisted `var` declarations
+      // from the entire body tree (var hoists past blocks).
+      if (isFn) {
+        collectVarDeclNames(bodyStmts, declNames);
+      }
+      const lexShadowed = new Set<string>();
+      for (const n of declNames) {
+        if (remainingTracked.has(n)) lexShadowed.add(n);
+      }
+      if (lexShadowed.size > 0) {
+        ranges.push({ start: node.start, end: node.end, names: lexShadowed });
+        if (lexShadowed.size === remainingTracked.size) return;
+        remainingTracked = new Set([...remainingTracked].filter((n) => !lexShadowed.has(n)));
+      }
+    }
+  }
+
+  // ── Recurse into children ──────────────────────────────────────────
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'start' || key === 'end') continue;
+    const val = node[key];
+    if (val && typeof val === 'object') {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          if (item && typeof item === 'object' && typeof item.type === 'string') {
+            collectShadowRanges(item as PositionedNode, remainingTracked, ranges);
+          }
+        }
+      } else if (typeof (val as PositionedNode).type === 'string') {
+        collectShadowRanges(val as PositionedNode, remainingTracked, ranges);
+      }
+    }
+  }
+}
+
 /**
  * Recursively walk AST nodes collecting call expressions accepted by
  * `matches`. Calls are typically at module scope, but calls inside
  * functions/blocks are handled for completeness.
  *
- * NOTE: matching is by binding NAME, so nested scopes that shadow a tracked
- * import can produce false positives for consumers of this walker (see
- * TIM-1141 for the cache transform). The prebuilt transform avoids the
- * class entirely by not using this walker — it allowlists top-level
- * declarator positions instead (plugins/prebuilt.ts).
+ * Consumers that match by binding NAME should pair this with
+ * `collectShadowRanges` to filter out calls in scopes where the tracked
+ * name is shadowed (TIM-1141). The prebuilt transform avoids the class
+ * entirely by allowlisting top-level declarator positions
+ * (plugins/prebuilt.ts).
  */
 export function findCallSites(
   node: PositionedNode,

package/src/plugins/fonts.ts

@@ -74,6 +74,14 @@ export function timberFonts(ctx: PluginContext): Plugin {
     configResolved(config: ResolvedConfig) {
       resolvedBase = config.base;
       pipeline.setBase(config.base);
+
+      // Font binaries are emitted in generateBundle, after Vite's CSS
+      // url() resolution runs. The warnings are benign — suppress them.
+      const originalWarnOnce = config.logger.warnOnce.bind(config.logger);
+      config.logger.warnOnce = (msg, options) => {
+        if (msg.includes('_timber/fonts/') && msg.includes("didn't resolve at build time")) return;
+        originalWarnOnce(msg, options);
+      };
     },
 
     /**

package/src/plugins/prebuilt-capture.ts

@@ -158,6 +158,13 @@ export async function runPrebuiltCapture(ctx: PluginContext): Promise<CaptureSum
 
   console.log('[timber] cache.component: capturing prebuilt flight payloads…');
 
+  // Tell the RSC entry to skip createRequestHandler — the capture pass
+  // only needs __timber_capturePrebuilt + the route manifest. Running the
+  // full production startup (instrumentation, cache handler, CDN purge,
+  // OTEL tracing, route matchers) is wasted work that can take 100+ seconds
+  // on large apps.
+  g.__TIMBER_CAPTURE_MODE__ = true;
+
   let mod: CaptureModule;
   try {
     // Cache-busting query: in a long-lived build process (vite build

package/src/plugins/shims.ts

@@ -240,6 +240,14 @@ export function timberShims(_ctx: PluginContext): Plugin {
       //
       // In Vite, we intercept them here to resolve to src/ for dev/build
       // correctness (same rationale as the @timber-js/app/* remap above).
+      if (cleanId === '#server-only-guard') {
+        const env = envName(this);
+        if (env === 'client') {
+          return SERVER_ONLY_VIRTUAL;
+        }
+        return resolve(PKG_ROOT, 'src', 'server', 'server-only-guard-noop.js');
+      }
+
       if (cleanId === '#server-internal') {
         const env = envName(this);
         if (env === 'client') {
@@ -288,6 +296,22 @@ export function timberShims(_ctx: PluginContext): Plugin {
         return resolve(PKG_ROOT, 'src', 'server', 'index.ts');
       }
 
+      // Alias hardening: monorepo dev configs (tests/shared-vite-config.ts,
+      // packages/website) alias @timber-js/app/server to the absolute
+      // src/server path for vitest compatibility. Vite's resolve.alias runs
+      // before every plugin, so the bare-specifier branch above never sees
+      // the import in those apps — the real server barrel (and its
+      // AsyncLocalStorage) would be bundled into the browser. Catch the
+      // already-aliased absolute path here and return the same stub.
+      if (
+        cleanId === resolve(PKG_ROOT, 'src', 'server', 'index.ts') ||
+        cleanId === resolve(PKG_ROOT, 'src', 'server', 'internal.ts')
+      ) {
+        if (envName(this) === 'client') {
+          return '\0timber:server-empty';
+        }
+      }
+
       if (cleanId === '@timber-js/app/client') {
         const env = envName(this);
         // RSC: return null — needs dist/ for 'use client' boundary detection.

package/src/server/actions.ts

@@ -167,7 +167,16 @@ export async function executeAction(
     // cache.invalidate handles both data-cache clearing AND component-seed
     // tombstone writes (design/45 §ISR mechanics) — no separate tombstone
     // step needed here.
-    await Promise.all(state.tags.map((tag) => cache.invalidate({ tag })));
+    // Best-effort: the action body already executed and its mutation committed.
+    // Use allSettled so all tags settle before proceeding — Promise.all would
+    // short-circuit on the first rejection, leaving other invalidations (including
+    // component-seed tombstone writes) in-flight during revalidatePath rendering.
+    const results = await Promise.allSettled(state.tags.map((tag) => cache.invalidate({ tag })));
+    for (const r of results) {
+      if (r.status === 'rejected') {
+        console.error('[timber] revalidateTag invalidation failed:', r.reason);
+      }
+    }
   }
 
   // Process path revalidation — build element tree (not yet serialized)

package/src/server/als-registry.ts

@@ -31,6 +31,7 @@
  * `tests/als-registry-singleton.test.ts`.
  */
 
+import '#server-only-guard';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { DebugComponentEntry } from './rsc-entry/helpers.js';
 

package/src/server/index.ts

@@ -33,7 +33,7 @@ export {
 // RenderError removed from public exports per TIM-724.
 // Use deny({ status: 500, data: ... }) instead. RenderError stays in
 // #server-internal for pipeline catch logic.
-export type { RenderErrorDigest, WaitUntilAdapter } from './primitives';
+export type { RenderErrorDigest } from './primitives';
 // JsonSerializable moved to @timber-js/app/codec as the single canonical path.
 // Re-export removed per TIM-721.