@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/plugins/request-dep/index.ts

@@ -0,0 +1,376 @@
+/**
+ * timber-request-dep — Static module-graph analysis for request-dependency.
+ *
+ * Replaces runtime ALS-based taint tracking with a build/dev-time computed
+ * map: segment entry file → statically request-dependent?
+ *
+ * A segment/slot is request-dependent iff any module reachable from its
+ * layout/page/default in the RSC module graph (stopping at client-reference
+ * boundaries) reads the request: it calls a request accessor (`getHeaders`,
+ * `getSearchParams`, `cookies`, …) or calls `.get()` on a value minted by
+ * `defineSearchParams` / `defineCookie`.
+ *
+ * "Calls a request accessor" is decided by resolving the call site's binding
+ * back through import and re-export edges (`origin.ts`), not by matching the
+ * calling module's own import declarations. That distinction is the whole
+ * ticket: a barrel, an alias, or a namespace import used to make a page that
+ * reads the query look static, and a static slot is cached and skipped on a
+ * query-only navigation — serving stale content (TIM-1273, TIM-1291).
+ *
+ * This is deterministic, covers children/barrels/node_modules/Suspense-
+ * deferred code, and is computed before any byte is flushed.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ */
+
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../../plugin-context.ts';
+import type { ProgramNode } from '../callsite-ast.ts';
+import { analyzeModule, usedSources, contributesNothing, type ModuleFacts } from './analysis.ts';
+import { createOriginResolver, FRAMEWORK_SOURCES } from './origin.ts';
+
+export type { ModuleFacts } from './analysis.ts';
+export { analyzeModule, usedSources } from './analysis.ts';
+export { createOriginResolver } from './origin.ts';
+
+// ─── Framework module detection ─────────────────────────────────────────
+
+export function isFrameworkModule(id: string): boolean {
+  return (
+    /[\\/]node_modules[\\/]@timber-js[\\/]app[\\/]/.test(id) ||
+    /[\\/]packages[\\/]timber-app[\\/]src[\\/]/.test(id)
+  );
+}
+
+// ─── Pre-filter ──────────────────────────────────────────────────────────
+
+/**
+ * Cheap gate before parsing.
+ *
+ * This used to be a substring match on the accessor and factory names, which
+ * was sound only for the analysis it served: when a call site had to name the
+ * framework binding in its own import declaration, a module with no such name
+ * could not be a call site. Resolving bindings across the graph removes that
+ * guarantee — with
+ *
+ *     // _lib/index.ts
+ *     export { getSearchParams as query } from '@timber-js/app/server';
+ *     // page.tsx
+ *     import { query } from './_lib';
+ *     export default function Page() { return query(); }
+ *
+ * the page contains no accessor name, no `.get(`, and no re-export syntax, and
+ * skipping it would have put the rename right back where the barrel was. So the
+ * gate is now structural: a module matters if it has any module-level binding
+ * to follow. What it skips is source with no `import` and no `export` at all —
+ * data blobs, generated constants, side-effect scripts — none of which can name
+ * a framework binding or forward one.
+ */
+function hasModuleBindings(code: string): boolean {
+  return code.includes('import') || code.includes('export');
+}
+
+// ─── Module graph reachability ───────────────────────────────────────────
+
+export interface ReachabilityInput {
+  factsMap: ReadonlyMap<string, ModuleFacts>;
+  getImports: (id: string) => string[];
+  /**
+   * Does the graph this walk runs over contain this module at all?
+   *
+   * Only the entry needs asking. Every other id the walk visits comes out of
+   * `getImports`, which enumerates edges the graph already resolved, so those
+   * are known by construction. The entry comes from outside — the route
+   * manifest's `filePath`, produced by the scanner from the filesystem — and
+   * nothing guarantees it is spelled the way the graph spells it, or that the
+   * module has been pulled through the pipeline yet.
+   */
+  isKnownModule: (id: string) => boolean;
+}
+
+/**
+ * Walk the module graph from an entry, returning true if any module reachable
+ * from it reads the request.
+ *
+ * Two passes, and the second is a deliberately blunt backstop:
+ *
+ * 1. **Binding origins.** For each reachable module, resolve every call site's
+ *    binding to its origin. This is precise and indifferent to indirection.
+ * 2. **Definition reachability.** A module that calls `.get()` on *something*
+ *    it imported, with a module holding a definition factory reachable behind
+ *    that import, counts too. The origin walk cannot see through a value that
+ *    is computed rather than bound — `getFilterCookie(key).get()`, where the
+ *    helper returns a definition — and this pass can.
+ *
+ * The second pass over-reports by construction, which is the safe direction: a
+ * needlessly request-dependent segment costs a re-render, a wrongly static one
+ * serves stale content.
+ *
+ * An entry the graph does not contain is an edge we failed to walk, not the
+ * absence of one — the same rule an unresolvable specifier gets. Without the
+ * check it reads as an entry with no imports and no facts, and both passes fall
+ * through to `false`: confidently request-INdependent, for a module nothing
+ * ever looked at. In the build that answer is worse than no answer, because it
+ * is written into `requestDep` as a definite `false` and the runtime's own
+ * "absent key → conservative" fallback never fires.
+ */
+export function isReachableTaintSource(entryId: string, input: ReachabilityInput): boolean {
+  const { factsMap, getImports, isKnownModule } = input;
+  if (!isKnownModule(entryId)) return true;
+  const resolver = createOriginResolver(factsMap);
+
+  const visited = new Set<string>();
+  const stack = [entryId];
+
+  while (stack.length > 0) {
+    const id = stack.pop()!;
+    if (visited.has(id)) continue;
+    visited.add(id);
+
+    if (resolver.isTainted(id)) return true;
+
+    for (const imp of getImports(id)) {
+      // Stop at client boundaries — 'use client' modules in the RSC graph
+      // resolve to generated proxy stubs with no further imports.
+      // Also stop at virtual modules (they're framework internals).
+      if (!imp.startsWith('\0') && !visited.has(imp)) {
+        stack.push(imp);
+      }
+    }
+  }
+
+  const reachesDefinition = makeDefinitionReachability(resolver.isDefinitionModule, getImports);
+  for (const id of visited) {
+    if (!resolver.callsGetterOnImport(id)) continue;
+    if (reachesDefinition(id)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * "Can a definition module be reached from this module's imports?", memoized
+ * across the queries one entry makes.
+ *
+ * Walks the graph rather than testing direct imports, because `export … from`
+ * is an ordinary module edge and a barrel is the common way an app shares one
+ * `defineSearchParams` across routes.
+ *
+ * Cycles terminate on the memo seeded with `false`; a module already being
+ * resolved contributes nothing, which is correct — anything it could reach is
+ * reachable on the path that is still unwinding.
+ */
+function makeDefinitionReachability(
+  isDefinitionModule: (id: string) => boolean,
+  getImports: (id: string) => string[]
+): (id: string) => boolean {
+  const cache = new Map<string, boolean>();
+
+  return function reaches(id: string): boolean {
+    const cached = cache.get(id);
+    if (cached !== undefined) return cached;
+    cache.set(id, false); // cycle guard: assume false while resolving
+
+    let result = false;
+    for (const imp of getImports(id)) {
+      if (imp.startsWith('\0')) continue;
+      if (isDefinitionModule(imp) || reaches(imp)) {
+        result = true;
+        break;
+      }
+    }
+    cache.set(id, result);
+    return result;
+  };
+}
+
+// ─── Plugin ──────────────────────────────────────────────────────────────
+
+const BRIDGE_KEY = Symbol.for('timber:request-dep');
+
+interface ResolvePluginContext {
+  parse(code: string): ProgramNode;
+  resolve(source: string, importer: string): Promise<{ id: string } | null>;
+}
+
+/**
+ * Resolve every specifier the module has an edge to, so the origin walk can
+ * follow them later without a module graph.
+ *
+ * Framework specifiers are classified by name and never resolved — that is what
+ * keeps the terminal check independent of how `@timber-js/app` happens to be
+ * installed. A specifier that fails to resolve is recorded as unresolved rather
+ * than dropped, so the walk can take the conservative branch on it.
+ */
+async function resolveEdgeSources(
+  pluginCtx: ResolvePluginContext,
+  facts: ModuleFacts,
+  importer: string
+): Promise<void> {
+  for (const source of usedSources(facts)) {
+    if (FRAMEWORK_SOURCES.has(source)) continue;
+    try {
+      const resolved = await pluginCtx.resolve(source, importer);
+      if (resolved?.id) facts.resolvedSources.set(source, resolved.id);
+      else facts.unresolvedSources.add(source);
+    } catch {
+      facts.unresolvedSources.add(source);
+    }
+  }
+}
+
+export function timberRequestDep(ctx: PluginContext): Plugin {
+  const factsMap = new Map<string, ModuleFacts>();
+  const cache = new Map<string, boolean>();
+
+  return {
+    name: 'timber-request-dep',
+    // Only run in RSC environment — that's where server components render.
+    applyToEnvironment(env) {
+      return env.name === 'rsc';
+    },
+
+    async transform(code, id) {
+      // Skip non-JS (include .mdx/.md — compiled to JS by timber-mdx before this runs)
+      if (!/\.[mc]?[jt]sx?$/.test(id) && !/\.mdx?$/.test(id)) return;
+      // Skip virtual modules
+      if (id.startsWith('\0') || id.startsWith('virtual:')) return;
+      // Skip framework modules — their internal accessor calls (e.g.,
+      // getCookieJar in define-cookie.ts) are implementation details.
+      // In dev they're externalized and never reach transform; in prod
+      // they would cause false positives (any module importing defineCookie
+      // would be tainted). Analysis relies on user-code call patterns.
+      if (isFrameworkModule(id)) return;
+      // Cheap structural gate
+      if (!hasModuleBindings(code)) return;
+
+      const pluginCtx = this as unknown as ResolvePluginContext;
+      const facts = analyzeModule(pluginCtx.parse(code));
+      if (contributesNothing(facts)) {
+        factsMap.delete(id);
+        return undefined;
+      }
+      await resolveEdgeSources(pluginCtx, facts, id);
+      factsMap.set(id, facts);
+
+      // No code transform needed — this is analysis only.
+      return undefined;
+    },
+
+    configureServer(server) {
+      // Register the bridge so runtime can query request-dep status.
+      const resolver = (filePath: string): boolean => {
+        if (cache.has(filePath)) return cache.get(filePath)!;
+
+        const rscEnv = server.environments?.rsc;
+        if (!rscEnv?.moduleGraph) {
+          return true; // Unknown → conservative
+        }
+
+        const getImports = (moduleId: string): string[] => {
+          const mod = rscEnv.moduleGraph.getModuleById(moduleId);
+          if (!mod) return [];
+          const result: string[] = [];
+          for (const imp of mod.importedModules) {
+            if (imp.id) result.push(imp.id);
+          }
+          return result;
+        };
+
+        const isKnownModule = (moduleId: string): boolean =>
+          rscEnv.moduleGraph.getModuleById(moduleId) !== undefined;
+
+        const result = isReachableTaintSource(filePath, { factsMap, getImports, isKnownModule });
+
+        // Do not memoize the conservative answer for an entry the graph has
+        // not seen. Dev loads modules on demand, so "unknown" is a statement
+        // about *now*, and the cache is only invalidated by file events —
+        // caching it would pin the segment request-dependent for the rest of
+        // the session even after the module is pulled in.
+        if (isKnownModule(filePath)) cache.set(filePath, result);
+        return result;
+      };
+
+      (globalThis as Record<symbol, unknown>)[BRIDGE_KEY] = resolver;
+
+      // Clear cache on file changes
+      const clearCache = () => cache.clear();
+      server.watcher.on('change', clearCache);
+      server.watcher.on('add', clearCache);
+      server.watcher.on('unlink', clearCache);
+    },
+
+    buildEnd() {
+      // Prod: compute the full map and register on globalThis for the
+      // build manifest plugin to pick up.
+      if (ctx.dev) return;
+
+      const getModuleInfo = (
+        this as unknown as {
+          getModuleInfo: (
+            id: string
+          ) => { importedIds?: string[]; dynamicallyImportedIds?: string[] } | null;
+        }
+      ).getModuleInfo;
+
+      const getImports = (moduleId: string): string[] => {
+        const info = getModuleInfo(moduleId);
+        if (!info) return [];
+        return [...(info.importedIds ?? []), ...(info.dynamicallyImportedIds ?? [])];
+      };
+
+      // `!= null` rather than `!== null`: the declared return type is
+      // `… | null`, but a bundler that hands back `undefined` for an unknown
+      // id would otherwise read as "known" and put us right back on the
+      // confidently-wrong `false`.
+      const isKnownModule = (moduleId: string): boolean => getModuleInfo(moduleId) != null;
+
+      const requestDepMap: Record<string, boolean> = {};
+
+      // Walk the route tree to find all segment entry files
+      if (ctx.routeTree) {
+        walkSegmentTree(ctx.routeTree.root as unknown as WalkableNode, (filePath: string) => {
+          requestDepMap[filePath] = isReachableTaintSource(filePath, {
+            factsMap,
+            getImports,
+            isKnownModule,
+          });
+        });
+      }
+
+      // Store on ctx for build-manifest plugin to serialize into the manifest.
+      // Prod runtime reads from __TIMBER_BUILD_MANIFEST__.requestDep.
+      //
+      // Assigned unconditionally, including when there is no route tree to
+      // walk: the field's presence is what tells the build-manifest plugin the
+      // analysis ran at all, so leaving it undefined on the empty-tree path
+      // would report "the RSC environment never analysed anything" for an app
+      // that genuinely has no segments.
+      ctx.requestDepMap = requestDepMap;
+    },
+  };
+}
+
+interface WalkableNode {
+  layout?: { filePath: string };
+  page?: { filePath: string };
+  default?: { filePath: string };
+  children?: unknown[];
+  slots?: Record<string, unknown>;
+}
+
+function walkSegmentTree(node: WalkableNode, fn: (filePath: string) => void): void {
+  if (node.layout) fn(node.layout.filePath);
+  if (node.page) fn(node.page.filePath);
+  if (node.default) fn((node.default as { filePath: string }).filePath);
+  if (node.children) {
+    for (const child of node.children) {
+      walkSegmentTree(child as typeof node, fn);
+    }
+  }
+  if (node.slots) {
+    for (const slot of Object.values(node.slots)) {
+      walkSegmentTree(slot as typeof node, fn);
+    }
+  }
+}

package/src/plugins/request-dep/origin.ts

@@ -0,0 +1,310 @@
+/**
+ * Binding-origin resolution across the module graph.
+ *
+ * Given a local name at a call site, walk import and re-export edges until the
+ * binding lands somewhere that can be classified: a framework request accessor,
+ * a definition factory, a definition object minted by one, or nothing of
+ * interest. The walk is what makes the analysis indifferent to how the app
+ * organises its own code — a barrel, an alias, a namespace import, and a
+ * re-export chain five hops deep all reach the same origin (TIM-1291).
+ *
+ * The asymmetry that governs every judgement here: over-reporting costs a
+ * re-render, under-reporting serves stale content to a client that cached a
+ * slot whose render varies with the query. So an edge we cannot follow resolves
+ * to `unknown`, and `unknown` counts as request-dependent.
+ *
+ * See design/19-client-navigation.md §"Why the slot comparison ignores the query".
+ */
+
+import type { CalleeRef, ImportEdge, ModuleFacts } from './analysis.ts';
+
+// ─── What counts as a request accessor ───────────────────────────────────
+
+const ACCESSOR_SOURCES = new Set(['@timber-js/app/server', 'next/headers', 'next/headers.js']);
+
+const ACCESSOR_NAMES = new Set([
+  'getHeaders',
+  'getHeader',
+  'getSearchParams',
+  'getCookieJar',
+  'getCookie',
+  // next/headers shim names
+  'headers',
+  'cookies',
+]);
+
+const DEFINITION_FACTORY_SOURCES = new Set([
+  '@timber-js/app/search-params',
+  '@timber-js/app/cookies',
+]);
+
+const DEFINITION_FACTORY_NAMES = new Set(['defineSearchParams', 'defineCookie']);
+
+/** Every specifier the classifier recognises without resolving it. */
+export const FRAMEWORK_SOURCES: ReadonlySet<string> = new Set([
+  ...ACCESSOR_SOURCES,
+  ...DEFINITION_FACTORY_SOURCES,
+]);
+
+// ─── Origins ─────────────────────────────────────────────────────────────
+
+export type Origin =
+  /** A request accessor: `getSearchParams`, `cookies`, … */
+  | { kind: 'accessor' }
+  /** A definition factory: `defineSearchParams`, `defineCookie`. */
+  | { kind: 'factory' }
+  /** A value minted by a definition factory — `.get()` on it reads the request. */
+  | { kind: 'definition' }
+  /** A namespace object for a framework module (`import * as h from 'next/headers'`). */
+  | { kind: 'framework-namespace'; source: string }
+  /** A namespace object for an app module. */
+  | { kind: 'namespace'; moduleId: string }
+  /** An edge that could not be followed. Treated as request-dependent. */
+  | { kind: 'unknown' }
+  /** Resolved, and not interesting. */
+  | { kind: 'none' };
+
+const NONE: Origin = { kind: 'none' };
+const UNKNOWN: Origin = { kind: 'unknown' };
+
+/**
+ * Classify an edge that points at a framework module, without resolving it.
+ *
+ * Returns `null` when the specifier is not a framework source, which is the
+ * signal to keep walking. Both name sets are consulted for either source so a
+ * specifier that grows a second role does not silently stop matching.
+ */
+function classifySpecifier(source: string, imported: string): Origin | null {
+  const isAccessorSource = ACCESSOR_SOURCES.has(source);
+  const isFactorySource = DEFINITION_FACTORY_SOURCES.has(source);
+  if (!isAccessorSource && !isFactorySource) return null;
+  if (imported === '*') return { kind: 'framework-namespace', source };
+  if (isAccessorSource && ACCESSOR_NAMES.has(imported)) return { kind: 'accessor' };
+  if (isFactorySource && DEFINITION_FACTORY_NAMES.has(imported)) return { kind: 'factory' };
+  return NONE;
+}
+
+/** An origin whose *call* reads the request. */
+function callReadsRequest(origin: Origin): boolean {
+  return origin.kind === 'accessor' || origin.kind === 'unknown';
+}
+
+/** An origin whose `.get()` reads the request. */
+function getterReadsRequest(origin: Origin): boolean {
+  return origin.kind === 'definition' || origin.kind === 'unknown';
+}
+
+// ─── Resolver ────────────────────────────────────────────────────────────
+
+export interface OriginResolver {
+  /** Does this module itself read the request? */
+  isTainted(moduleId: string): boolean;
+  /** Does this module hold a definition factory binding? */
+  isDefinitionModule(moduleId: string): boolean;
+  /** Does this module call `.get()` on a binding it imported? */
+  callsGetterOnImport(moduleId: string): boolean;
+}
+
+export function createOriginResolver(factsMap: ReadonlyMap<string, ModuleFacts>): OriginResolver {
+  /**
+   * Cycle guard. A `(module, export)` pair already being resolved contributes
+   * `none`: anything it could reach is reachable on the path still unwinding.
+   */
+  const resolving = new Map<string, Set<string>>();
+
+  function enter(moduleId: string, name: string): boolean {
+    const names = resolving.get(moduleId);
+    if (!names) {
+      resolving.set(moduleId, new Set([name]));
+      return true;
+    }
+    if (names.has(name)) return false;
+    names.add(name);
+    return true;
+  }
+
+  function leave(moduleId: string, name: string): void {
+    resolving.get(moduleId)?.delete(name);
+  }
+
+  /** Follow one `import`/`export … from` edge out of `moduleId`. */
+  function resolveEdge(moduleId: string, edge: ImportEdge): Origin {
+    const classified = classifySpecifier(edge.source, edge.imported);
+    if (classified) return classified;
+
+    const facts = factsMap.get(moduleId);
+    const targetId = facts?.resolvedSources.get(edge.source);
+    if (!targetId) {
+      // An unresolvable specifier is an edge we cannot follow, not an absence
+      // of one. A specifier the plugin never tried to resolve (module not
+      // analysed) lands here too, and both take the conservative branch.
+      return facts?.unresolvedSources.has(edge.source) ? UNKNOWN : NONE;
+    }
+    if (edge.imported === '*') return { kind: 'namespace', moduleId: targetId };
+    return resolveExport(targetId, edge.imported);
+  }
+
+  /** What does `moduleId` export under `name`? */
+  function resolveExport(moduleId: string, name: string): Origin {
+    const facts = factsMap.get(moduleId);
+    if (!facts) return NONE;
+    if (!enter(moduleId, `export:${name}`)) return NONE;
+    try {
+      const reExport = facts.reExports.get(name);
+      if (reExport) return resolveEdge(moduleId, reExport);
+
+      const local = facts.localExports.get(name);
+      if (local !== undefined) return resolveLocal(moduleId, local);
+
+      // `export * from './m'` does not name what it forwards, so every star
+      // source is a candidate. Ambiguity is resolved conservatively: the first
+      // source that classifies as anything wins.
+      for (const source of facts.starReExports) {
+        const viaStar = resolveEdge(moduleId, { source, imported: name });
+        if (viaStar.kind !== 'none') return viaStar;
+      }
+      return NONE;
+    } finally {
+      leave(moduleId, `export:${name}`);
+    }
+  }
+
+  /** What is the local binding `name` in `moduleId`? */
+  function resolveLocal(moduleId: string, name: string): Origin {
+    const facts = factsMap.get(moduleId);
+    if (!facts) return NONE;
+    if (!enter(moduleId, `local:${name}`)) return NONE;
+    try {
+      const imported = facts.importedBindings.get(name);
+      if (imported) return resolveEdge(moduleId, imported);
+
+      const factoryCall = facts.factoryCalls.get(name);
+      if (factoryCall) {
+        // `const filters = defineSearchParams(…)` — the *result* is a
+        // definition, and `.get()` on it reads the request.
+        const callee = resolveCallee(moduleId, factoryCall);
+        if (callee.kind === 'factory') return { kind: 'definition' };
+        if (callee.kind === 'unknown') return UNKNOWN;
+      }
+      return NONE;
+    } finally {
+      leave(moduleId, `local:${name}`);
+    }
+  }
+
+  function resolveCallee(moduleId: string, ref: CalleeRef): Origin {
+    if (ref.kind === 'local') return resolveLocal(moduleId, ref.name);
+    return resolveMember(moduleId, ref.object, ref.property);
+  }
+
+  /** `ns.name` where `ns` is a local binding in `moduleId`. */
+  function resolveMember(moduleId: string, object: string, name: string): Origin {
+    const base = resolveLocal(moduleId, object);
+    if (base.kind === 'framework-namespace') {
+      return classifySpecifier(base.source, name) ?? NONE;
+    }
+    if (base.kind === 'namespace') return resolveExport(base.moduleId, name);
+    if (base.kind === 'unknown') return UNKNOWN;
+    return NONE;
+  }
+
+  const taintCache = new Map<string, boolean>();
+
+  function computeTainted(moduleId: string, facts: ModuleFacts): boolean {
+    for (const local of facts.calledLocals) {
+      if (callReadsRequest(resolveLocal(moduleId, local))) return true;
+    }
+    for (const [object, members] of facts.calledMembers) {
+      for (const member of members) {
+        if (callReadsRequest(resolveMember(moduleId, object, member))) return true;
+      }
+    }
+    for (const local of facts.getterLocals) {
+      if (getterReadsRequest(resolveLocal(moduleId, local))) return true;
+    }
+    for (const [object, members] of facts.getterMembers) {
+      for (const member of members) {
+        if (getterReadsRequest(resolveMember(moduleId, object, member))) return true;
+      }
+    }
+    return holdsRequestBinding(moduleId, facts);
+  }
+
+  /**
+   * Possession, not use: a module that binds a request accessor or a definition
+   * value under a local name is request-dependent whether or not the call is
+   * one this analysis can see.
+   *
+   * The call-shape rules above only find a read that happens through the
+   * binding itself. A value can leave the binding first — `const read = flag ?
+   * getSearchParams : noop`, `const { get } = filters`, a prop handed to a
+   * helper — and every one of those is a fresh way to be missed, which is the
+   * shape of bug this ticket exists to stop enumerating. Nothing distinguishes
+   * those from an honest unused import except intent, so importing the accessor
+   * at all is treated as reading it.
+   *
+   * The rule is scoped by *reference*, not by export shape, and that scoping is
+   * what keeps it from being useless: `import { getSearchParams } from
+   * '@timber-js/app/server'; export { getSearchParams }` is a barrel whose body
+   * never mentions the name, and tainting it would taint every page that
+   * imports anything from that barrel. The forwarded name stays resolvable
+   * through `resolveExport`, so the page that actually calls it is still caught
+   * one hop later, in the module that uses it.
+   *
+   * Scoping on "the module only forwards it" would have been the natural
+   * phrasing and is wrong: a barrel can forward a name *and* use it
+   * (`export { getSearchParams }` beside `const read = flag ? getSearchParams
+   * : noop`), and that module is exactly the one this rule exists to catch.
+   * `referencedLocals` excludes import/export clauses and nothing else, so
+   * forwarding is exempt only when it is all the module does with the name.
+   *
+   * `unknown` is deliberately not included: an unresolvable specifier taints
+   * only when something is actually called or read on it, or every module with
+   * one broken import would go request-dependent.
+   */
+  function holdsRequestBinding(moduleId: string, facts: ModuleFacts): boolean {
+    for (const local of facts.referencedLocals) {
+      const origin = resolveLocal(moduleId, local);
+      if (origin.kind === 'accessor' || origin.kind === 'definition') return true;
+    }
+    return false;
+  }
+
+  return {
+    isTainted(moduleId) {
+      const cached = taintCache.get(moduleId);
+      if (cached !== undefined) return cached;
+      const facts = factsMap.get(moduleId);
+      const result = facts ? computeTainted(moduleId, facts) : false;
+      taintCache.set(moduleId, result);
+      return result;
+    },
+
+    isDefinitionModule(moduleId) {
+      const facts = factsMap.get(moduleId);
+      if (!facts) return false;
+      for (const edge of facts.importedBindings.values()) {
+        const origin = resolveEdge(moduleId, edge);
+        if (origin.kind === 'factory') return true;
+        // `import * as sp from '@timber-js/app/search-params'` — the factory is
+        // behind a member access, so the whole namespace counts.
+        if (
+          origin.kind === 'framework-namespace' &&
+          DEFINITION_FACTORY_SOURCES.has(origin.source)
+        ) {
+          return true;
+        }
+      }
+      return false;
+    },
+
+    callsGetterOnImport(moduleId) {
+      const facts = factsMap.get(moduleId);
+      if (!facts) return false;
+      for (const local of facts.getterLocals) {
+        if (facts.importedBindings.has(local)) return true;
+      }
+      return false;
+    },
+  };
+}