optave-codegraph 3.13.0

package/src/ast-analysis/visitor-utils.ts

@@ -0,0 +1,278 @@
+/**
+ * Shared AST helper functions used by multiple visitors (dataflow, etc.).
+ *
+ * Extracted from dataflow.js to be reusable across the visitor framework.
+ */
+
+import type { TreeSitterNode } from '../types.js';
+
+interface ParamInfo {
+  name: string;
+  index: number;
+}
+
+interface LanguageRules {
+  nameField: string;
+  nameExtractor?: ((node: TreeSitterNode) => string | null) | null;
+  varAssignedFnParent?: string;
+  pairFnParent?: string;
+  assignmentFnParent?: string;
+  assignLeftField?: string;
+  paramIdentifier: string;
+  paramWrapperTypes: Set<string>;
+  defaultParamType?: string;
+  restParamType?: string;
+  objectDestructType?: string;
+  shorthandPropPattern?: string;
+  pairPatternType?: string;
+  arrayDestructType?: string;
+  extraIdentifierTypes?: Set<string>;
+  callFunctionField: string;
+  memberNode: string;
+  memberPropertyField: string;
+  memberObjectField: string;
+  optionalChainNode?: string;
+  extractParamName?(node: TreeSitterNode): string[] | null;
+}
+
+/**
+ * Truncate a string to a maximum length.
+ */
+export function truncate(str: string, max = 120): string {
+  if (!str) return '';
+  return str.length > max ? `${str.slice(0, max)}…` : str;
+}
+
+/**
+ * Get the name of a function node from the AST using rules.
+ */
+export function functionName(fnNode: TreeSitterNode | null, rules: LanguageRules): string | null {
+  if (!fnNode) return null;
+  if (rules.nameExtractor) {
+    const extracted = rules.nameExtractor(fnNode);
+    if (extracted) return extracted;
+  }
+  const nameNode = fnNode.childForFieldName(rules.nameField);
+  if (nameNode) return nameNode.text;
+
+  const parent = fnNode.parent;
+  if (parent) {
+    if (rules.varAssignedFnParent && parent.type === rules.varAssignedFnParent) {
+      const n = parent.childForFieldName('name');
+      return n ? n.text : null;
+    }
+    if (rules.pairFnParent && parent.type === rules.pairFnParent) {
+      const keyNode = parent.childForFieldName('key');
+      return keyNode ? keyNode.text : null;
+    }
+    if (rules.assignmentFnParent && parent.type === rules.assignmentFnParent) {
+      const left = parent.childForFieldName(rules.assignLeftField!);
+      return left ? left.text : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract parameter names and indices from a formal_parameters node.
+ */
+export function extractParams(
+  paramsNode: TreeSitterNode | null,
+  rules: LanguageRules,
+): ParamInfo[] {
+  if (!paramsNode) return [];
+  const result: ParamInfo[] = [];
+  let index = 0;
+  for (const child of paramsNode.namedChildren) {
+    const names = extractParamNames(child, rules);
+    for (const name of names) {
+      result.push({ name, index });
+    }
+    index++;
+  }
+  return result;
+}
+
+/**
+ * Resolve a single parameter node to either a direct list of names (base case)
+ * or a list of child nodes that still need processing. Returns `null` if the
+ * node yields nothing.
+ *
+ * This base case keeps destructuring helpers from recursing back into
+ * `extractParamNames`, breaking the 3-node mutual recursion cycle between
+ * `extractParamNames`, `extractObjectDestructNames`, and `extractArrayDestructNames`.
+ */
+function resolveParamNode(
+  node: TreeSitterNode,
+  rules: LanguageRules,
+): { names?: string[]; next?: TreeSitterNode[] } | null {
+  const t = node.type;
+
+  if (rules.extractParamName) {
+    const result = rules.extractParamName(node);
+    if (result) return { names: result };
+  }
+
+  if (t === rules.paramIdentifier) return { names: [node.text] };
+
+  if (rules.paramWrapperTypes.has(t)) {
+    const pattern = node.childForFieldName('pattern') || node.childForFieldName('name');
+    return pattern ? { next: [pattern] } : null;
+  }
+
+  if (rules.defaultParamType && t === rules.defaultParamType) {
+    const left = node.childForFieldName('left') || node.childForFieldName('name');
+    return left ? { next: [left] } : null;
+  }
+
+  if (rules.restParamType && t === rules.restParamType) {
+    const nameNode = node.childForFieldName('name');
+    if (nameNode) return { names: [nameNode.text] };
+    for (const child of node.namedChildren) {
+      if (child.type === rules.paramIdentifier) return { names: [child.text] };
+    }
+    return null;
+  }
+
+  if (rules.objectDestructType && t === rules.objectDestructType) {
+    return { next: collectObjectDestructChildren(node, rules) };
+  }
+
+  if (rules.arrayDestructType && t === rules.arrayDestructType) {
+    return { next: [...node.namedChildren] };
+  }
+
+  return null;
+}
+
+/**
+ * Collect child nodes from an object destructuring pattern that should be
+ * processed for further name extraction. Returns nodes (not names) so the
+ * caller drives traversal via a worklist instead of recursion.
+ */
+function collectObjectDestructChildren(
+  node: TreeSitterNode,
+  rules: LanguageRules,
+): TreeSitterNode[] {
+  const next: TreeSitterNode[] = [];
+  for (const child of node.namedChildren) {
+    if (rules.shorthandPropPattern && child.type === rules.shorthandPropPattern) {
+      // Shorthand prop is a direct identifier — handled by the shorthand
+      // guard in the `extractParamNames` worklist loop (before `resolveParamNode`).
+      next.push(child);
+    } else if (rules.pairPatternType && child.type === rules.pairPatternType) {
+      const value = child.childForFieldName('value');
+      if (value) next.push(value);
+    } else if (rules.restParamType && child.type === rules.restParamType) {
+      next.push(child);
+    }
+  }
+  return next;
+}
+
+/**
+ * Extract parameter names from a single parameter node.
+ *
+ * Uses an iterative worklist to handle nested destructuring (objects, arrays,
+ * defaults, rest, wrappers) without mutual recursion through helper functions.
+ */
+export function extractParamNames(node: TreeSitterNode | null, rules: LanguageRules): string[] {
+  if (!node) return [];
+
+  const names: string[] = [];
+  const stack: TreeSitterNode[] = [node];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current) continue;
+
+    // Shorthand identifier inside an object destructuring is just the node's text.
+    if (rules.shorthandPropPattern && current.type === rules.shorthandPropPattern) {
+      names.push(current.text);
+      continue;
+    }
+
+    const resolved = resolveParamNode(current, rules);
+    if (!resolved) continue;
+    if (resolved.names) names.push(...resolved.names);
+    if (resolved.next) {
+      // Push in reverse so traversal order matches the previous recursive order.
+      for (let i = resolved.next.length - 1; i >= 0; i--) {
+        const child = resolved.next[i];
+        if (child) stack.push(child);
+      }
+    }
+  }
+
+  return names;
+}
+
+/**
+ * Check if a node type is identifier-like for this language.
+ */
+export function isIdent(nodeType: string, rules: LanguageRules): boolean {
+  if (nodeType === 'identifier' || nodeType === rules.paramIdentifier) return true;
+  return rules.extraIdentifierTypes ? rules.extraIdentifierTypes.has(nodeType) : false;
+}
+
+/** Resolve callee name from an optional chain node (e.g. `obj?.method()`). */
+function resolveOptionalChainCallee(fn: TreeSitterNode, rules: LanguageRules): string | null {
+  const target = fn.namedChildren[0];
+  if (!target) return null;
+  if (target.type === rules.memberNode) {
+    const prop = target.childForFieldName(rules.memberPropertyField);
+    return prop ? prop.text : null;
+  }
+  if (target.type === 'identifier') return target.text;
+  const prop = fn.childForFieldName(rules.memberPropertyField);
+  return prop ? prop.text : null;
+}
+
+/**
+ * Resolve the name a call expression is calling using rules.
+ */
+export function resolveCalleeName(callNode: TreeSitterNode, rules: LanguageRules): string | null {
+  const fn = callNode.childForFieldName(rules.callFunctionField);
+  if (!fn) {
+    const nameNode = callNode.childForFieldName('name') || callNode.childForFieldName('method');
+    return nameNode ? nameNode.text : null;
+  }
+  if (isIdent(fn.type, rules)) return fn.text;
+  if (fn.type === rules.memberNode) {
+    const prop = fn.childForFieldName(rules.memberPropertyField);
+    return prop ? prop.text : null;
+  }
+  if (rules.optionalChainNode && fn.type === rules.optionalChainNode) {
+    return resolveOptionalChainCallee(fn, rules);
+  }
+  return null;
+}
+
+/**
+ * Get the receiver (object) of a member expression using rules.
+ */
+export function memberReceiver(memberExpr: TreeSitterNode, rules: LanguageRules): string | null {
+  const obj = memberExpr.childForFieldName(rules.memberObjectField);
+  if (!obj) return null;
+  if (isIdent(obj.type, rules)) return obj.text;
+  if (obj.type === rules.memberNode) return memberReceiver(obj, rules);
+  return null;
+}
+
+/**
+ * Collect all identifier names referenced within a node.
+ */
+export function collectIdentifiers(
+  node: TreeSitterNode | null,
+  out: string[],
+  rules: LanguageRules,
+): void {
+  if (!node) return;
+  if (isIdent(node.type, rules)) {
+    out.push(node.text);
+    return;
+  }
+  for (const child of node.namedChildren) {
+    collectIdentifiers(child, out, rules);
+  }
+}

package/src/ast-analysis/visitor.ts

@@ -0,0 +1,266 @@
+/**
+ * Shared DFS walker with pluggable visitors for AST analysis.
+ *
+ * Provides a single tree traversal that multiple analysis visitors can hook into,
+ * avoiding redundant walks over the same AST. Two hook styles:
+ *
+ *  - Node-level: enterNode / exitNode (called for every node)
+ *  - Function-level: enterFunction / exitFunction (called at function boundaries)
+ *
+ * The walker maintains shared context (nestingLevel, scopeStack, currentFunction)
+ * so individual visitors don't need to track traversal state themselves.
+ */
+
+import { debug } from '../infrastructure/logger.js';
+import type {
+  ScopeEntry,
+  TreeSitterNode,
+  Visitor,
+  VisitorContext,
+  WalkOptions,
+  WalkResults,
+} from '../types.js';
+
+/** Merge each visitor's custom functionNodeTypes into the master set. */
+function mergeFunctionNodeTypes(visitors: Visitor[], base: Set<string>): Set<string> {
+  const merged = new Set(base);
+  for (const v of visitors) {
+    if (v.functionNodeTypes) {
+      for (const t of v.functionNodeTypes) merged.add(t);
+    }
+  }
+  return merged;
+}
+
+/** Initialize all visitors for a given language. */
+function initVisitors(visitors: Visitor[], langId: string): void {
+  for (const v of visitors) {
+    if (v.init) v.init(langId);
+  }
+}
+
+/** Check whether a visitor should be skipped at the current depth. */
+function isSkipped(
+  skipDepths: Map<number, number>,
+  visitorIndex: number,
+  currentDepth: number,
+): boolean {
+  const skipAt = skipDepths.get(visitorIndex);
+  // Skipped if skip was requested at a shallower (or equal) depth
+  // We skip descendants, not the node itself, so skip when currentDepth > skipAt
+  return skipAt !== undefined && currentDepth > skipAt;
+}
+
+/** Dispatch enterFunction hooks to all non-skipped visitors. */
+function dispatchEnterFunction(
+  visitors: Visitor[],
+  skipDepths: Map<number, number>,
+  node: TreeSitterNode,
+  funcName: string | null,
+  context: VisitorContext,
+  depth: number,
+): void {
+  for (let i = 0; i < visitors.length; i++) {
+    const v = visitors[i]!;
+    if (v.enterFunction && !isSkipped(skipDepths, i, depth)) {
+      v.enterFunction(node, funcName, context);
+    }
+  }
+}
+
+/** Dispatch enterNode hooks and track skipChildren requests. */
+function dispatchEnterNode(
+  visitors: Visitor[],
+  skipDepths: Map<number, number>,
+  node: TreeSitterNode,
+  context: VisitorContext,
+  depth: number,
+): void {
+  for (let i = 0; i < visitors.length; i++) {
+    const v = visitors[i]!;
+    if (v.enterNode && !isSkipped(skipDepths, i, depth)) {
+      const result = v.enterNode(node, context);
+      if (result?.skipChildren) {
+        skipDepths.set(i, depth);
+      }
+    }
+  }
+}
+
+/** Dispatch exitNode hooks to all non-skipped visitors. */
+function dispatchExitNode(
+  visitors: Visitor[],
+  skipDepths: Map<number, number>,
+  node: TreeSitterNode,
+  context: VisitorContext,
+  depth: number,
+): void {
+  for (let i = 0; i < visitors.length; i++) {
+    const v = visitors[i]!;
+    if (v.exitNode && !isSkipped(skipDepths, i, depth)) {
+      v.exitNode(node, context);
+    }
+  }
+}
+
+/** Clear skip flags for visitors that started skipping at this depth. */
+function clearSkipFlags(
+  skipDepths: Map<number, number>,
+  visitorCount: number,
+  depth: number,
+): void {
+  for (let i = 0; i < visitorCount; i++) {
+    if (skipDepths.get(i) === depth) {
+      skipDepths.delete(i);
+    }
+  }
+}
+
+/** Dispatch exitFunction hooks to all non-skipped visitors. */
+function dispatchExitFunction(
+  visitors: Visitor[],
+  skipDepths: Map<number, number>,
+  node: TreeSitterNode,
+  funcName: string | null,
+  context: VisitorContext,
+  depth: number,
+): void {
+  for (let i = 0; i < visitors.length; i++) {
+    const v = visitors[i]!;
+    if (v.exitFunction && !isSkipped(skipDepths, i, depth)) {
+      v.exitFunction(node, funcName, context);
+    }
+  }
+}
+
+/**
+ * Maximum AST depth before walk() bails out.  WASM-backed tree-sitter parsers
+ * have a smaller stack than native V8 (~64-256 KB).  Deep recursion in
+ * generated code, deeply nested object literals, or pathologically large
+ * switch statements can exhaust that stack, causing a V8 fatal error /
+ * segfault (#931).  500 levels is well beyond any realistic hand-written
+ * code while staying safely inside the WASM stack budget.
+ */
+const MAX_WALK_DEPTH = 500;
+
+/** Collect finish() results from all visitors into a name-keyed map. */
+function collectResults(visitors: Visitor[]): WalkResults {
+  const results: WalkResults = {};
+  for (const v of visitors) {
+    results[v.name] = v.finish ? v.finish() : undefined;
+  }
+  return results;
+}
+
+interface WalkState {
+  visitors: Visitor[];
+  allFuncTypes: Set<string>;
+  nestingNodeTypes: Set<string>;
+  getFunctionName: (node: TreeSitterNode) => string | null;
+  context: VisitorContext;
+  scopeStack: ScopeEntry[];
+  skipDepths: Map<number, number>;
+}
+
+/** Build walk state from options: resolve function types, init visitors, create shared context. */
+function buildWalkState(visitors: Visitor[], langId: string, options: WalkOptions): WalkState {
+  const {
+    functionNodeTypes = new Set<string>(),
+    nestingNodeTypes = new Set<string>(),
+    getFunctionName = () => null,
+  } = options;
+
+  const allFuncTypes = mergeFunctionNodeTypes(visitors, functionNodeTypes);
+  initVisitors(visitors, langId);
+
+  const scopeStack: ScopeEntry[] = [];
+  const context: VisitorContext = {
+    nestingLevel: 0,
+    currentFunction: null,
+    langId,
+    scopeStack,
+  };
+
+  return {
+    visitors,
+    allFuncTypes,
+    nestingNodeTypes,
+    getFunctionName,
+    context,
+    scopeStack,
+    skipDepths: new Map<number, number>(),
+  };
+}
+
+/** Single DFS step: dispatch enter/exit hooks and recurse into children. */
+function walkNode(state: WalkState, node: TreeSitterNode | null, depth: number): void {
+  if (!node) return;
+  if (depth > MAX_WALK_DEPTH) {
+    debug(`walkWithVisitors: AST depth limit (${MAX_WALK_DEPTH}) hit — subtree truncated`);
+    return;
+  }
+
+  const {
+    visitors,
+    allFuncTypes,
+    nestingNodeTypes,
+    getFunctionName,
+    context,
+    scopeStack,
+    skipDepths,
+  } = state;
+  const type = node.type;
+  const isFuncBoundary = allFuncTypes.has(type);
+  let funcName: string | null = null;
+
+  if (isFuncBoundary) {
+    funcName = getFunctionName(node);
+    context.currentFunction = node;
+    scopeStack.push({ funcName, funcNode: node, params: new Map(), locals: new Map() });
+    dispatchEnterFunction(visitors, skipDepths, node, funcName, context, depth);
+  }
+
+  dispatchEnterNode(visitors, skipDepths, node, context, depth);
+
+  const addsNesting = nestingNodeTypes.has(type);
+  if (addsNesting) context.nestingLevel++;
+
+  for (let i = 0; i < node.childCount; i++) {
+    walkNode(state, node.child(i), depth + 1);
+  }
+
+  if (addsNesting) context.nestingLevel--;
+
+  dispatchExitNode(visitors, skipDepths, node, context, depth);
+  clearSkipFlags(skipDepths, visitors.length, depth);
+
+  if (isFuncBoundary) {
+    dispatchExitFunction(visitors, skipDepths, node, funcName, context, depth);
+    scopeStack.pop();
+    context.currentFunction =
+      scopeStack.length > 0 ? scopeStack[scopeStack.length - 1]!.funcNode : null;
+  }
+}
+
+/**
+ * Walk an AST root with multiple visitors in a single DFS pass.
+ *
+ * @param {object} rootNode   - tree-sitter root node to walk
+ * @param {Visitor[]} visitors - array of visitor objects
+ * @param {string} langId     - language identifier
+ * @param {object} [options]
+ * @param {Set}    [options.functionNodeTypes] - set of node types that are function boundaries
+ * @param {Set}    [options.nestingNodeTypes]  - set of node types that increase nesting depth
+ * @param {function} [options.getFunctionName] - (funcNode) => string|null
+ * @returns {object} Map of visitor.name → finish() result
+ */
+export function walkWithVisitors(
+  rootNode: TreeSitterNode,
+  visitors: Visitor[],
+  langId: string,
+  options: WalkOptions = {},
+): WalkResults {
+  const state = buildWalkState(visitors, langId, options);
+  walkNode(state, rootNode, 0);
+  return collectResults(visitors);
+}