@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/src/plugins/callsite-ast.ts

@@ -0,0 +1,472 @@
+/**
+ * Shared AST helpers for callsite-ID transforms.
+ *
+ * Both timber-cache-transform (plugins/cache.ts) and timber-prebuilt
+ * (plugins/prebuilt.ts) detect calls on bindings imported from the cache
+ * module and stamp them with content-derived stable IDs. The node shapes,
+ * import-binding resolution, recursive call walk, and ID derivation are
+ * identical — only the callee shape and rewrite differ per plugin.
+ *
+ * See TIM-997, TIM-1053, design/06-caching.md §"Cache Key Security".
+ */
+
+import { fnv1aHash } from '../cache/fast-hash.js';
+
+/** Module specifiers whose bindings the transforms track. */
+export const CACHE_MODULE_SOURCES = new Set(['@timber-js/app/cache', 'timber/cache']);
+
+export interface PositionedNode {
+  type: string;
+  start: number;
+  end: number;
+  [key: string]: unknown;
+}
+
+export interface IdentifierNode extends PositionedNode {
+  type: 'Identifier';
+  name: string;
+}
+
+export interface ImportDeclarationNode extends PositionedNode {
+  type: 'ImportDeclaration';
+  source: { value: string };
+  specifiers: Array<
+    PositionedNode & {
+      type: string;
+      local: IdentifierNode;
+      imported?: IdentifierNode;
+    }
+  >;
+}
+
+export interface CallExpressionNode extends PositionedNode {
+  type: 'CallExpression';
+  callee: PositionedNode;
+  arguments: PositionedNode[];
+}
+
+export interface MemberExpressionNode extends PositionedNode {
+  type: 'MemberExpression';
+  object: PositionedNode;
+  property: PositionedNode;
+  computed: boolean;
+}
+
+export interface ProgramNode extends PositionedNode {
+  type: 'Program';
+  body: PositionedNode[];
+}
+
+export interface ImportBindings {
+  /** Local names bound to the named import (`import { cache as c }`). */
+  named: Set<string>;
+  /** Local names of namespace imports (`import * as ns`) of a tracked module. */
+  namespaces: Set<string>;
+}
+
+/**
+ * Find the local binding name(s) for `importedName` imported from one of
+ * `sources` — both named imports (including aliases) and namespace imports
+ * (TIM-1054).
+ */
+export function findImportBindings(
+  program: ProgramNode,
+  sources: ReadonlySet<string>,
+  importedName: string
+): ImportBindings {
+  const named = new Set<string>();
+  const namespaces = new Set<string>();
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ImportDeclaration') continue;
+    const decl = stmt as unknown as ImportDeclarationNode;
+    if (!sources.has(decl.source.value)) continue;
+    for (const spec of decl.specifiers) {
+      if (spec.type === 'ImportNamespaceSpecifier') {
+        namespaces.add(spec.local.name);
+        continue;
+      }
+      if (spec.type !== 'ImportSpecifier') continue;
+      const specImportedName = spec.imported?.name ?? spec.local.name;
+      if (specImportedName === importedName) {
+        named.add(spec.local.name);
+      }
+    }
+  }
+  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.
+ *
+ * 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,
+  matches: (call: CallExpressionNode) => boolean,
+  results: CallExpressionNode[]
+): void {
+  if (node.type === 'CallExpression') {
+    const call = node as unknown as CallExpressionNode;
+    if (matches(call)) {
+      results.push(call);
+    }
+  }
+  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') {
+            findCallSites(item as PositionedNode, matches, results);
+          }
+        }
+      } else if (typeof (val as PositionedNode).type === 'string') {
+        findCallSites(val as PositionedNode, matches, results);
+      }
+    }
+  }
+}
+
+/**
+ * Generate a stable callsite ID from a module path, a kind discriminator
+ * ('cache' | 'component'), the source text of the enclosing top-level
+ * statement, the source text of the call expression, and an occurrence index
+ * among fully byte-identical (statement, call) pairs in the same file.
+ *
+ * The ID is deterministic and:
+ * - Stable across cold starts AND across builds/deploys for unchanged calls —
+ *   inserting, deleting, or reordering other calls does not affect it
+ * - Unique across different modules (relPath component)
+ * - Unique across distinct calls within a module (statement + span hashes),
+ *   with fully identical duplicates disambiguated by source-order occurrence
+ * - Fresh when the wrapped fn, opts, or enclosing statement change, which
+ *   intentionally invalidates the old persisted entries
+ *
+ * The enclosing-statement text is included so that byte-identical calls in
+ * different scopes — e.g. two factory helpers with identical call spans —
+ * get distinct, insertion-stable IDs. See plugins/cache.ts header for the
+ * full derivation rationale (TIM-1053).
+ */
+export function generateStableCallsiteId(
+  relativeModulePath: string,
+  kind: string,
+  statementText: string,
+  callSpanText: string,
+  occurrence: number
+): string {
+  return fnv1aHash(
+    `${relativeModulePath}:${kind}:${fnv1aHash(statementText)}:${fnv1aHash(callSpanText)}:${occurrence}`
+  );
+}