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

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

@@ -0,0 +1,447 @@
+/**
+ * Per-module syntactic facts for request-dependency analysis.
+ *
+ * This module is deliberately dumb: it records *what the source says*, with no
+ * knowledge of which specifiers or names are interesting. Every judgement —
+ * "is this an accessor", "is this a definition object" — lives in `origin.ts`,
+ * which resolves a binding to the module it actually came from.
+ *
+ * That split is the point. The previous shape asked each module in isolation
+ * "do you import `getSearchParams` from `@timber-js/app/server` and call it",
+ * which any indirection defeats: a barrel re-export, a namespace import, a
+ * factory reached through the app's own `_lib`. Each of those was a separate
+ * hole and each was found separately (TIM-1291). Recording bindings and edges
+ * here, and resolving them across the graph there, closes the family instead of
+ * its members.
+ *
+ * See design/19-client-navigation.md §"Why the slot comparison ignores the query".
+ */
+
+import type {
+  ProgramNode,
+  PositionedNode,
+  IdentifierNode,
+  CallExpressionNode,
+  MemberExpressionNode,
+} from '../callsite-ast.ts';
+
+/**
+ * One module-graph edge introduced by an `import` or `export … from`.
+ *
+ * `imported` is the name as it exists in the *source* module: an export name,
+ * `'default'`, or `'*'` for a namespace/star form.
+ */
+export interface ImportEdge {
+  source: string;
+  imported: string;
+}
+
+/** The callee of `const x = f()` / `const x = ns.f()`. */
+export type CalleeRef =
+  | { kind: 'local'; name: string }
+  | { kind: 'member'; object: string; property: string };
+
+export interface ModuleFacts {
+  /** Local name → the edge that bound it (`import { a as b } from 'x'`). */
+  importedBindings: Map<string, ImportEdge>;
+  /** Exported name → edge, for `export { a as b } from 'x'`. */
+  reExports: Map<string, ImportEdge>;
+  /** Sources of anonymous `export * from 'x'`, in source order. */
+  starReExports: string[];
+  /** Exported name → local name, for `export { x }`, `export const x = …`. */
+  localExports: Map<string, string>;
+  /** Local variable name → the callee that produced its value. */
+  factoryCalls: Map<string, CalleeRef>;
+  /** Local names invoked directly: `f()`. */
+  calledLocals: Set<string>;
+  /** `ns.f()` → `ns` → `{ f }`. */
+  calledMembers: Map<string, Set<string>>;
+  /** Base identifier of a `.get()` chain: `x.get()`, `x().get()`, `x.p.get()`. */
+  getterLocals: Set<string>;
+  /** `ns.defs.get()` → `ns` → `{ defs }`. */
+  getterMembers: Map<string, Set<string>>;
+  /** Every name the module *body* mentions — import/export clauses excluded. */
+  referencedLocals: Set<string>;
+  /** Specifier → resolved module id, filled by the plugin via `this.resolve`. */
+  resolvedSources: Map<string, string>;
+  /** Specifiers that failed to resolve — treated as request-dependent. */
+  unresolvedSources: Set<string>;
+}
+
+/** `export default` has no local name of its own; this stands in for one. */
+export const DEFAULT_EXPORT = 'default';
+
+export function createModuleFacts(): ModuleFacts {
+  return {
+    importedBindings: new Map(),
+    reExports: new Map(),
+    starReExports: [],
+    localExports: new Map(),
+    factoryCalls: new Map(),
+    calledLocals: new Set(),
+    calledMembers: new Map(),
+    getterLocals: new Set(),
+    getterMembers: new Map(),
+    referencedLocals: new Set(),
+    resolvedSources: new Map(),
+    unresolvedSources: new Set(),
+  };
+}
+
+/**
+ * Specifiers the origin walk can actually reach, so the plugin resolves those
+ * and not every import in the file.
+ *
+ * A re-export edge is always reachable — a downstream module can ask for any
+ * name it forwards. An `import` edge is reachable through any local name the
+ * module body mentions, or that it re-exports.
+ *
+ * The name set must be **the same one the taint rules consult**. Deriving it
+ * from the call shapes instead (called, `.get()`d, member-called, minted from)
+ * left `read(filters)` — a definition passed as an argument — with its
+ * specifier unresolved, so the origin walk reported it inert and the page read
+ * as request-independent. Two hand-maintained lists of "names that matter" is
+ * one list too many; this is the one, and `referencedLocals` is a superset of
+ * every call shape by construction, since each of them is an identifier the
+ * walk visits. (Codex review round 1 on PR #991.)
+ */
+export function usedSources(facts: ModuleFacts): Set<string> {
+  const sources = new Set<string>(facts.starReExports);
+  for (const edge of facts.reExports.values()) sources.add(edge.source);
+
+  for (const local of facts.referencedLocals) {
+    const edge = facts.importedBindings.get(local);
+    if (edge) sources.add(edge.source);
+  }
+  for (const local of facts.localExports.values()) {
+    const edge = facts.importedBindings.get(local);
+    if (edge) sources.add(edge.source);
+  }
+  return sources;
+}
+
+/**
+ * True when the module cannot affect any answer, so its facts need not be kept.
+ *
+ * Every judgement bottoms out at a module edge: a call site resolves through
+ * `importedBindings`, a chain link through `reExports` / `starReExports`. A
+ * module with none of those can only ever resolve to `none` — its exports lead
+ * to locals that lead nowhere — which is exactly what a *missing* entry
+ * produces. Dropping it is behaviour-preserving and keeps the dev-time map from
+ * holding an entry for every leaf module in the graph.
+ */
+export function contributesNothing(facts: ModuleFacts): boolean {
+  return (
+    facts.importedBindings.size === 0 &&
+    facts.reExports.size === 0 &&
+    facts.starReExports.length === 0
+  );
+}
+
+function addToMapSet(map: Map<string, Set<string>>, key: string, value: string): void {
+  const existing = map.get(key);
+  if (existing) existing.add(value);
+  else map.set(key, new Set([value]));
+}
+
+// ─── Declaration collection ──────────────────────────────────────────────
+
+/**
+ * A module-export name slot: `Identifier`, or the string-literal form ESTree
+ * allows (`export { x as "a-b" } from './m'`) — a valid export name that is not
+ * a valid identifier.
+ */
+type NameNode = PositionedNode | undefined;
+
+interface SpecifierNode extends PositionedNode {
+  local?: NameNode;
+  imported?: NameNode;
+  exported?: NameNode;
+}
+
+function nameOf(node: NameNode): string | null {
+  if (!node) return null;
+  if (node.type === 'Identifier') return (node as IdentifierNode).name;
+  if (node.type === 'Literal' && typeof node.value === 'string') return node.value;
+  return null;
+}
+
+/**
+ * `import type { … }` needs no handling here. Vite's TypeScript transform is a
+ * core plugin and runs before this one, so types are already erased by the time
+ * the analysis parses — and the parser it runs on is JavaScript-only, so
+ * unerased TypeScript would throw rather than be silently misread.
+ * `tests/request-dep-plugin.test.ts` pins the resulting property through the
+ * real pipeline: a type-only accessor import is not request-dependent.
+ */
+function collectImportDeclaration(stmt: PositionedNode, facts: ModuleFacts): void {
+  const source = (stmt.source as { value: string } | undefined)?.value;
+  if (typeof source !== 'string') return;
+  for (const spec of (stmt.specifiers as SpecifierNode[] | undefined) ?? []) {
+    const local = nameOf(spec.local);
+    if (!local) continue;
+    if (spec.type === 'ImportNamespaceSpecifier') {
+      facts.importedBindings.set(local, { source, imported: '*' });
+    } else if (spec.type === 'ImportDefaultSpecifier') {
+      facts.importedBindings.set(local, { source, imported: DEFAULT_EXPORT });
+    } else if (spec.type === 'ImportSpecifier') {
+      facts.importedBindings.set(local, { source, imported: nameOf(spec.imported) ?? local });
+    }
+  }
+}
+
+function collectDeclaredNames(decl: PositionedNode, out: Set<string>): void {
+  if (decl.type === 'VariableDeclaration') {
+    for (const d of (decl.declarations as PositionedNode[] | undefined) ?? []) {
+      const id = d.id as PositionedNode | undefined;
+      if (id?.type === 'Identifier') out.add((id as IdentifierNode).name);
+    }
+  } else if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
+    const id = decl.id as PositionedNode | undefined;
+    if (id?.type === 'Identifier') out.add((id as IdentifierNode).name);
+  }
+}
+
+function collectExportNamed(stmt: PositionedNode, facts: ModuleFacts): void {
+  const source = (stmt.source as { value: string } | undefined)?.value;
+  const specifiers = (stmt.specifiers as SpecifierNode[] | undefined) ?? [];
+
+  if (typeof source === 'string') {
+    // `export { a as b } from './m'` — `local` names the export in './m'.
+    for (const spec of specifiers) {
+      const imported = nameOf(spec.imported) ?? nameOf(spec.local);
+      const exported = nameOf(spec.exported);
+      if (imported && exported) facts.reExports.set(exported, { source, imported });
+    }
+    return;
+  }
+
+  // `export { x }` / `export { x as y }` — `local` is a binding in this module.
+  for (const spec of specifiers) {
+    const local = nameOf(spec.local);
+    const exported = nameOf(spec.exported);
+    if (local && exported) facts.localExports.set(exported, local);
+  }
+
+  // `export const x = …`, `export function f() {}`
+  const declaration = stmt.declaration as PositionedNode | undefined;
+  if (declaration) {
+    const names = new Set<string>();
+    collectDeclaredNames(declaration, names);
+    for (const name of names) facts.localExports.set(name, name);
+  }
+}
+
+function collectExportAll(stmt: PositionedNode, facts: ModuleFacts): void {
+  const source = (stmt.source as { value: string } | undefined)?.value;
+  if (typeof source !== 'string') return;
+  const exported = nameOf(stmt.exported as NameNode);
+  if (exported) {
+    // `export * as ns from './m'` — a namespace object under one name.
+    facts.reExports.set(exported, { source, imported: '*' });
+  } else {
+    facts.starReExports.push(source);
+  }
+}
+
+function collectExportDefault(stmt: PositionedNode, facts: ModuleFacts): void {
+  const declaration = stmt.declaration as PositionedNode | undefined;
+  if (!declaration) return;
+  facts.localExports.set(DEFAULT_EXPORT, DEFAULT_EXPORT);
+  if (declaration.type === 'Identifier') {
+    // `export default x` — alias the default onto the existing binding.
+    facts.localExports.set(DEFAULT_EXPORT, (declaration as IdentifierNode).name);
+  } else if (declaration.type === 'CallExpression') {
+    const ref = calleeRef(declaration as unknown as CallExpressionNode);
+    if (ref) facts.factoryCalls.set(DEFAULT_EXPORT, ref);
+  }
+}
+
+// ─── Expression collection ───────────────────────────────────────────────
+
+function calleeRef(call: CallExpressionNode): CalleeRef | null {
+  const callee = call.callee;
+  if (callee.type === 'Identifier') {
+    return { kind: 'local', name: (callee as IdentifierNode).name };
+  }
+  if (callee.type === 'MemberExpression') {
+    const member = callee as MemberExpressionNode;
+    if (
+      !member.computed &&
+      member.object.type === 'Identifier' &&
+      member.property.type === 'Identifier'
+    ) {
+      return {
+        kind: 'member',
+        object: (member.object as IdentifierNode).name,
+        property: (member.property as IdentifierNode).name,
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Walk down a `.get()` receiver to the identifier it is ultimately rooted in,
+ * along with the first property accessed on that identifier.
+ *
+ * `x.get()` → `x`, no property. `x(a).get()` → `x`. `ns.defs.get()` → `ns`
+ * plus `defs`, which is both the namespace-member shape and the
+ * `cookies.theme.get()` shape — the resolver tries the base binding and the
+ * member, so one walk covers both.
+ */
+function chainRoot(node: PositionedNode): { base: string; property: string | null } | null {
+  let current = node;
+  let property: string | null = null;
+  for (;;) {
+    if (current.type === 'Identifier') {
+      return { base: (current as IdentifierNode).name, property };
+    }
+    if (current.type === 'MemberExpression') {
+      const member = current as MemberExpressionNode;
+      if (!member.computed && member.property.type === 'Identifier') {
+        property = (member.property as IdentifierNode).name;
+      } else {
+        property = null;
+      }
+      current = member.object;
+      continue;
+    }
+    if (current.type === 'CallExpression') {
+      property = null;
+      current = (current as CallExpressionNode).callee;
+      continue;
+    }
+    return null;
+  }
+}
+
+function collectExpression(node: PositionedNode, facts: ModuleFacts): void {
+  if (node.type === 'VariableDeclarator') {
+    const id = node.id as PositionedNode | undefined;
+    const init = node.init as PositionedNode | undefined;
+    if (id?.type === 'Identifier' && init?.type === 'CallExpression') {
+      const ref = calleeRef(init as unknown as CallExpressionNode);
+      if (ref) facts.factoryCalls.set((id as IdentifierNode).name, ref);
+    }
+    return;
+  }
+
+  if (node.type !== 'CallExpression') return;
+  const call = node as unknown as CallExpressionNode;
+  const callee = call.callee;
+
+  if (callee.type === 'Identifier') {
+    facts.calledLocals.add((callee as IdentifierNode).name);
+    return;
+  }
+  if (callee.type !== 'MemberExpression') return;
+  const member = callee as MemberExpressionNode;
+  if (member.computed || member.property.type !== 'Identifier') return;
+  const propertyName = (member.property as IdentifierNode).name;
+
+  if (propertyName === 'get') {
+    const root = chainRoot(member.object);
+    if (root) {
+      facts.getterLocals.add(root.base);
+      if (root.property) addToMapSet(facts.getterMembers, root.base, root.property);
+    }
+    return;
+  }
+  if (member.object.type === 'Identifier') {
+    addToMapSet(facts.calledMembers, (member.object as IdentifierNode).name, propertyName);
+  }
+}
+
+/**
+ * Statements whose whole subtree is an import/export *clause* rather than code.
+ *
+ * The walk skips them so `referencedLocals` means "the module body mentions
+ * this name". Without the skip every imported name would count as referenced,
+ * and a pure barrel — which mentions its names only in the clauses — would be
+ * indistinguishable from a module that uses them.
+ */
+function isClauseOnly(node: PositionedNode): boolean {
+  if (node.type === 'ImportDeclaration' || node.type === 'ExportAllDeclaration') return true;
+  if (node.type === 'ExportNamedDeclaration') return !node.declaration;
+  // `export default someBinding` forwards; `export default f()` is code.
+  if (node.type === 'ExportDefaultDeclaration') {
+    return (node.declaration as PositionedNode | undefined)?.type === 'Identifier';
+  }
+  return false;
+}
+
+/**
+ * Keys holding *binding* positions rather than references: the name being
+ * declared, not a mention of one.
+ *
+ * `referencedLocals` must exclude these or `export const filters =
+ * defineSearchParams({})` would count as referencing `filters`, and possession
+ * would then taint every definition module — and through it every page that
+ * imports one, whether or not it reads the request. Skipping only these keys
+ * keeps a shadowing parameter's *body* uses as references, which over-reports
+ * in the safe direction.
+ */
+const BINDING_KEYS: Readonly<Record<string, readonly string[]>> = {
+  VariableDeclarator: ['id'],
+  FunctionDeclaration: ['id', 'params'],
+  FunctionExpression: ['id', 'params'],
+  ArrowFunctionExpression: ['params'],
+  ClassDeclaration: ['id'],
+  ClassExpression: ['id'],
+  CatchClause: ['param'],
+};
+
+function walk(node: PositionedNode, facts: ModuleFacts): void {
+  if (isClauseOnly(node)) return;
+  if (node.type === 'Identifier') facts.referencedLocals.add((node as IdentifierNode).name);
+  collectExpression(node, facts);
+  const bindingKeys = BINDING_KEYS[node.type];
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'start' || key === 'end') continue;
+    if (bindingKeys?.includes(key)) continue;
+    const value = node[key];
+    if (!value || typeof value !== 'object') continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item && typeof item === 'object' && typeof item.type === 'string') {
+          walk(item as PositionedNode, facts);
+        }
+      }
+    } else if (typeof (value as PositionedNode).type === 'string') {
+      walk(value as PositionedNode, facts);
+    }
+  }
+}
+
+/**
+ * Record every binding, module edge, and call shape in one module.
+ *
+ * Names are recorded without scope analysis, so a parameter that shadows an
+ * imported name is credited to the import. That direction is deliberate: a
+ * needlessly request-dependent segment costs a re-render, a wrongly static one
+ * serves stale content.
+ */
+export function analyzeModule(program: ProgramNode): ModuleFacts {
+  const facts = createModuleFacts();
+
+  for (const stmt of program.body) {
+    switch (stmt.type) {
+      case 'ImportDeclaration':
+        collectImportDeclaration(stmt, facts);
+        break;
+      case 'ExportNamedDeclaration':
+        collectExportNamed(stmt, facts);
+        break;
+      case 'ExportAllDeclaration':
+        collectExportAll(stmt, facts);
+        break;
+      case 'ExportDefaultDeclaration':
+        collectExportDefault(stmt, facts);
+        break;
+    }
+  }
+
+  walk(program, facts);
+  return facts;
+}