@optave/codegraph 3.1.5 → 3.2.0

package/src/ast-analysis/visitors/dataflow-visitor.js

@@ -21,254 +21,280 @@ import {
   truncate,
 } from '../visitor-utils.js';
 
-/**
- * Create a dataflow visitor for use with walkWithVisitors.
- *
- * @param {object} rules - DATAFLOW_RULES for the language
- * @returns {Visitor}
- */
-export function createDataflowVisitor(rules) {
-  const isCallNode = rules.callNodes ? (t) => rules.callNodes.has(t) : (t) => t === rules.callNode;
-
-  const parameters = [];
-  const returns = [];
-  const assignments = [];
-  const argFlows = [];
-  const mutations = [];
+// ── Scope helpers ───────────────────────────────────────────────────────
 
-  const scopeStack = [];
+function currentScope(scopeStack) {
+  return scopeStack.length > 0 ? scopeStack[scopeStack.length - 1] : null;
+}
 
-  function currentScope() {
-    return scopeStack.length > 0 ? scopeStack[scopeStack.length - 1] : null;
+function findBinding(name, scopeStack) {
+  for (let i = scopeStack.length - 1; i >= 0; i--) {
+    const scope = scopeStack[i];
+    if (scope.params.has(name))
+      return { type: 'param', index: scope.params.get(name), funcName: scope.funcName };
+    if (scope.locals.has(name))
+      return { type: 'local', source: scope.locals.get(name), funcName: scope.funcName };
   }
+  return null;
+}
 
-  function findBinding(name) {
-    for (let i = scopeStack.length - 1; i >= 0; i--) {
-      const scope = scopeStack[i];
-      if (scope.params.has(name))
-        return { type: 'param', index: scope.params.get(name), funcName: scope.funcName };
-      if (scope.locals.has(name))
-        return { type: 'local', source: scope.locals.get(name), funcName: scope.funcName };
-    }
-    return null;
+function bindingConfidence(binding) {
+  if (!binding) return 0.5;
+  if (binding.type === 'param') return 1.0;
+  if (binding.type === 'local') {
+    if (binding.source?.type === 'call_return') return 0.9;
+    if (binding.source?.type === 'destructured') return 0.8;
+    return 0.9;
   }
+  return 0.5;
+}
 
-  function bindingConfidence(binding) {
-    if (!binding) return 0.5;
-    if (binding.type === 'param') return 1.0;
-    if (binding.type === 'local') {
-      if (binding.source?.type === 'call_return') return 0.9;
-      if (binding.source?.type === 'destructured') return 0.8;
-      return 0.9;
-    }
-    return 0.5;
-  }
+// ── Node helpers ────────────────────────────────────────────────────────
 
-  function unwrapAwait(node) {
-    if (rules.awaitNode && node.type === rules.awaitNode) {
-      return node.namedChildren[0] || node;
-    }
-    return node;
+function unwrapAwait(node, rules) {
+  if (rules.awaitNode && node.type === rules.awaitNode) {
+    return node.namedChildren[0] || node;
   }
+  return node;
+}
 
-  function isCall(node) {
-    return node && isCallNode(node.type);
-  }
+function isCall(node, isCallNode) {
+  return node && isCallNode(node.type);
+}
 
-  function handleVarDeclarator(node) {
-    let nameNode = node.childForFieldName(rules.varNameField);
-    let valueNode = rules.varValueField ? node.childForFieldName(rules.varValueField) : null;
+// ── Node handlers ───────────────────────────────────────────────────────
 
-    if (!valueNode && rules.equalsClauseType) {
-      for (const child of node.namedChildren) {
-        if (child.type === rules.equalsClauseType) {
-          valueNode = child.childForFieldName('value') || child.namedChildren[0];
-          break;
-        }
-      }
-    }
+function handleVarDeclarator(node, rules, scopeStack, assignments, isCallNode) {
+  let nameNode = node.childForFieldName(rules.varNameField);
+  let valueNode = rules.varValueField ? node.childForFieldName(rules.varValueField) : null;
 
-    if (!valueNode) {
-      for (const child of node.namedChildren) {
-        if (child !== nameNode && isCall(unwrapAwait(child))) {
-          valueNode = child;
-          break;
-        }
+  if (!valueNode && rules.equalsClauseType) {
+    for (const child of node.namedChildren) {
+      if (child.type === rules.equalsClauseType) {
+        valueNode = child.childForFieldName('value') || child.namedChildren[0];
+        break;
       }
     }
+  }
 
-    if (rules.expressionListType) {
-      if (nameNode?.type === rules.expressionListType) nameNode = nameNode.namedChildren[0];
-      if (valueNode?.type === rules.expressionListType) valueNode = valueNode.namedChildren[0];
+  if (!valueNode) {
+    for (const child of node.namedChildren) {
+      if (child !== nameNode && isCall(unwrapAwait(child, rules), isCallNode)) {
+        valueNode = child;
+        break;
+      }
     }
+  }
 
-    const scope = currentScope();
-    if (!nameNode || !valueNode || !scope) return;
-
-    const unwrapped = unwrapAwait(valueNode);
-    const callExpr = isCall(unwrapped) ? unwrapped : null;
+  if (rules.expressionListType) {
+    if (nameNode?.type === rules.expressionListType) nameNode = nameNode.namedChildren[0];
+    if (valueNode?.type === rules.expressionListType) valueNode = valueNode.namedChildren[0];
+  }
 
-    if (callExpr) {
-      const callee = resolveCalleeName(callExpr, rules);
-      if (callee && scope.funcName) {
-        if (
-          (rules.objectDestructType && nameNode.type === rules.objectDestructType) ||
-          (rules.arrayDestructType && nameNode.type === rules.arrayDestructType)
-        ) {
-          const names = extractParamNames(nameNode, rules);
-          for (const n of names) {
-            assignments.push({
-              varName: n,
-              callerFunc: scope.funcName,
-              sourceCallName: callee,
-              expression: truncate(node.text),
-              line: node.startPosition.row + 1,
-            });
-            scope.locals.set(n, { type: 'destructured', callee });
-          }
-        } else {
-          const varName =
-            nameNode.type === 'identifier' || nameNode.type === rules.paramIdentifier
-              ? nameNode.text
-              : nameNode.text;
+  const scope = currentScope(scopeStack);
+  if (!nameNode || !valueNode || !scope) return;
+
+  const unwrapped = unwrapAwait(valueNode, rules);
+  const callExpr = isCall(unwrapped, isCallNode) ? unwrapped : null;
+
+  if (callExpr) {
+    const callee = resolveCalleeName(callExpr, rules);
+    if (callee && scope.funcName) {
+      if (
+        (rules.objectDestructType && nameNode.type === rules.objectDestructType) ||
+        (rules.arrayDestructType && nameNode.type === rules.arrayDestructType)
+      ) {
+        const names = extractParamNames(nameNode, rules);
+        for (const n of names) {
           assignments.push({
-            varName,
+            varName: n,
             callerFunc: scope.funcName,
             sourceCallName: callee,
             expression: truncate(node.text),
             line: node.startPosition.row + 1,
           });
-          scope.locals.set(varName, { type: 'call_return', callee });
+          scope.locals.set(n, { type: 'destructured', callee });
         }
+      } else {
+        const varName =
+          nameNode.type === 'identifier' || nameNode.type === rules.paramIdentifier
+            ? nameNode.text
+            : nameNode.text;
+        assignments.push({
+          varName,
+          callerFunc: scope.funcName,
+          sourceCallName: callee,
+          expression: truncate(node.text),
+          line: node.startPosition.row + 1,
+        });
+        scope.locals.set(varName, { type: 'call_return', callee });
       }
     }
   }
+}
 
-  function handleAssignment(node) {
-    const left = node.childForFieldName(rules.assignLeftField);
-    const right = node.childForFieldName(rules.assignRightField);
-    const scope = currentScope();
-    if (!scope?.funcName) return;
-
-    if (left && rules.memberNode && left.type === rules.memberNode) {
-      const receiver = memberReceiver(left, rules);
-      if (receiver) {
-        const binding = findBinding(receiver);
-        if (binding) {
-          mutations.push({
-            funcName: scope.funcName,
-            receiverName: receiver,
-            binding,
-            mutatingExpr: truncate(node.text),
-            line: node.startPosition.row + 1,
-          });
-        }
+function handleAssignment(node, rules, scopeStack, assignments, mutations, isCallNode) {
+  const left = node.childForFieldName(rules.assignLeftField);
+  const right = node.childForFieldName(rules.assignRightField);
+  const scope = currentScope(scopeStack);
+  if (!scope?.funcName) return;
+
+  if (left && rules.memberNode && left.type === rules.memberNode) {
+    const receiver = memberReceiver(left, rules);
+    if (receiver) {
+      const binding = findBinding(receiver, scopeStack);
+      if (binding) {
+        mutations.push({
+          funcName: scope.funcName,
+          receiverName: receiver,
+          binding,
+          mutatingExpr: truncate(node.text),
+          line: node.startPosition.row + 1,
+        });
       }
     }
+  }
 
-    if (left && isIdent(left.type, rules) && right) {
-      const unwrapped = unwrapAwait(right);
-      const callExpr = isCall(unwrapped) ? unwrapped : null;
-      if (callExpr) {
-        const callee = resolveCalleeName(callExpr, rules);
-        if (callee) {
-          assignments.push({
-            varName: left.text,
-            callerFunc: scope.funcName,
-            sourceCallName: callee,
-            expression: truncate(node.text),
-            line: node.startPosition.row + 1,
-          });
-          scope.locals.set(left.text, { type: 'call_return', callee });
-        }
+  if (left && isIdent(left.type, rules) && right) {
+    const unwrapped = unwrapAwait(right, rules);
+    const callExpr = isCall(unwrapped, isCallNode) ? unwrapped : null;
+    if (callExpr) {
+      const callee = resolveCalleeName(callExpr, rules);
+      if (callee) {
+        assignments.push({
+          varName: left.text,
+          callerFunc: scope.funcName,
+          sourceCallName: callee,
+          expression: truncate(node.text),
+          line: node.startPosition.row + 1,
+        });
+        scope.locals.set(left.text, { type: 'call_return', callee });
       }
     }
   }
+}
 
-  function handleCallExpr(node) {
-    const callee = resolveCalleeName(node, rules);
-    const argsNode = node.childForFieldName(rules.callArgsField);
-    const scope = currentScope();
-    if (!callee || !argsNode || !scope?.funcName) return;
+function handleCallExpr(node, rules, scopeStack, argFlows) {
+  const callee = resolveCalleeName(node, rules);
+  const argsNode = node.childForFieldName(rules.callArgsField);
+  const scope = currentScope(scopeStack);
+  if (!callee || !argsNode || !scope?.funcName) return;
 
-    let argIndex = 0;
-    for (let arg of argsNode.namedChildren) {
-      if (rules.argumentWrapperType && arg.type === rules.argumentWrapperType) {
-        arg = arg.namedChildren[0] || arg;
-      }
-      const unwrapped =
-        rules.spreadType && arg.type === rules.spreadType ? arg.namedChildren[0] || arg : arg;
-      if (!unwrapped) {
-        argIndex++;
-        continue;
-      }
+  let argIndex = 0;
+  for (let arg of argsNode.namedChildren) {
+    if (rules.argumentWrapperType && arg.type === rules.argumentWrapperType) {
+      arg = arg.namedChildren[0] || arg;
+    }
+    const unwrapped =
+      rules.spreadType && arg.type === rules.spreadType ? arg.namedChildren[0] || arg : arg;
+    if (!unwrapped) {
+      argIndex++;
+      continue;
+    }
 
-      const argName = isIdent(unwrapped.type, rules) ? unwrapped.text : null;
-      const argMember =
-        rules.memberNode && unwrapped.type === rules.memberNode
-          ? memberReceiver(unwrapped, rules)
-          : null;
-      const trackedName = argName || argMember;
-
-      if (trackedName) {
-        const binding = findBinding(trackedName);
-        if (binding) {
-          argFlows.push({
-            callerFunc: scope.funcName,
-            calleeName: callee,
-            argIndex,
-            argName: trackedName,
-            binding,
-            confidence: bindingConfidence(binding),
-            expression: truncate(arg.text),
-            line: node.startPosition.row + 1,
-          });
-        }
+    const argName = isIdent(unwrapped.type, rules) ? unwrapped.text : null;
+    const argMember =
+      rules.memberNode && unwrapped.type === rules.memberNode
+        ? memberReceiver(unwrapped, rules)
+        : null;
+    const trackedName = argName || argMember;
+
+    if (trackedName) {
+      const binding = findBinding(trackedName, scopeStack);
+      if (binding) {
+        argFlows.push({
+          callerFunc: scope.funcName,
+          calleeName: callee,
+          argIndex,
+          argName: trackedName,
+          binding,
+          confidence: bindingConfidence(binding),
+          expression: truncate(arg.text),
+          line: node.startPosition.row + 1,
+        });
       }
-      argIndex++;
     }
+    argIndex++;
   }
+}
 
-  function handleExprStmtMutation(node) {
-    if (rules.mutatingMethods.size === 0) return;
-    const expr = node.namedChildren[0];
-    if (!expr || !isCall(expr)) return;
+function handleExprStmtMutation(node, rules, scopeStack, mutations, isCallNode) {
+  if (rules.mutatingMethods.size === 0) return;
+  const expr = node.namedChildren[0];
+  if (!expr || !isCall(expr, isCallNode)) return;
 
-    let methodName = null;
-    let receiver = null;
+  let methodName = null;
+  let receiver = null;
 
-    const fn = expr.childForFieldName(rules.callFunctionField);
-    if (fn && fn.type === rules.memberNode) {
-      const prop = fn.childForFieldName(rules.memberPropertyField);
-      methodName = prop ? prop.text : null;
-      receiver = memberReceiver(fn, rules);
-    }
+  const fn = expr.childForFieldName(rules.callFunctionField);
+  if (fn && fn.type === rules.memberNode) {
+    const prop = fn.childForFieldName(rules.memberPropertyField);
+    methodName = prop ? prop.text : null;
+    receiver = memberReceiver(fn, rules);
+  }
 
-    if (!receiver && rules.callObjectField) {
-      const obj = expr.childForFieldName(rules.callObjectField);
-      const name = expr.childForFieldName(rules.callFunctionField);
-      if (obj && name) {
-        methodName = name.text;
-        receiver = isIdent(obj.type, rules) ? obj.text : null;
-      }
+  if (!receiver && rules.callObjectField) {
+    const obj = expr.childForFieldName(rules.callObjectField);
+    const name = expr.childForFieldName(rules.callFunctionField);
+    if (obj && name) {
+      methodName = name.text;
+      receiver = isIdent(obj.type, rules) ? obj.text : null;
     }
+  }
 
-    if (!methodName || !rules.mutatingMethods.has(methodName)) return;
+  if (!methodName || !rules.mutatingMethods.has(methodName)) return;
 
-    const scope = currentScope();
-    if (!receiver || !scope?.funcName) return;
+  const scope = currentScope(scopeStack);
+  if (!receiver || !scope?.funcName) return;
 
-    const binding = findBinding(receiver);
-    if (binding) {
-      mutations.push({
-        funcName: scope.funcName,
-        receiverName: receiver,
-        binding,
-        mutatingExpr: truncate(expr.text),
-        line: node.startPosition.row + 1,
-      });
-    }
+  const binding = findBinding(receiver, scopeStack);
+  if (binding) {
+    mutations.push({
+      funcName: scope.funcName,
+      receiverName: receiver,
+      binding,
+      mutatingExpr: truncate(expr.text),
+      line: node.startPosition.row + 1,
+    });
   }
+}
+
+// ── Return statement handler ────────────────────────────────────────────
+
+function handleReturn(node, rules, scopeStack, returns) {
+  if (node.parent?.type === rules.returnNode) return; // keyword token, not statement
+
+  const scope = currentScope(scopeStack);
+  if (scope?.funcName) {
+    const expr = node.namedChildren[0];
+    const referencedNames = [];
+    if (expr) collectIdentifiers(expr, referencedNames, rules);
+    returns.push({
+      funcName: scope.funcName,
+      expression: truncate(expr ? expr.text : ''),
+      referencedNames,
+      line: node.startPosition.row + 1,
+    });
+  }
+}
+
+// ── Visitor factory ─────────────────────────────────────────────────────
+
+/**
+ * Create a dataflow visitor for use with walkWithVisitors.
+ *
+ * @param {object} rules - DATAFLOW_RULES for the language
+ * @returns {Visitor}
+ */
+export function createDataflowVisitor(rules) {
+  const isCallNode = rules.callNodes ? (t) => rules.callNodes.has(t) : (t) => t === rules.callNode;
+
+  const parameters = [];
+  const returns = [];
+  const assignments = [];
+  const argFlows = [];
+  const mutations = [];
+  const scopeStack = [];
 
   return {
     name: 'dataflow',
@@ -300,54 +326,34 @@ export function createDataflowVisitor(rules) {
     enterNode(node, _context) {
       const t = node.type;
 
-      // Skip function nodes — handled by enterFunction/exitFunction
       if (rules.functionNodes.has(t)) return;
 
-      // Return statements (skip keyword tokens inside return statements, e.g. Ruby's
-      // `return` node nests a `return` keyword child with the same type string)
       if (rules.returnNode && t === rules.returnNode) {
-        if (node.parent?.type === rules.returnNode) return; // keyword token, not statement
-
-        const scope = currentScope();
-        if (scope?.funcName) {
-          const expr = node.namedChildren[0];
-          const referencedNames = [];
-          if (expr) collectIdentifiers(expr, referencedNames, rules);
-          returns.push({
-            funcName: scope.funcName,
-            expression: truncate(expr ? expr.text : ''),
-            referencedNames,
-            line: node.startPosition.row + 1,
-          });
-        }
+        handleReturn(node, rules, scopeStack, returns);
         return;
       }
 
-      // Variable declarations
       if (rules.varDeclaratorNode && t === rules.varDeclaratorNode) {
-        handleVarDeclarator(node);
+        handleVarDeclarator(node, rules, scopeStack, assignments, isCallNode);
         return;
       }
       if (rules.varDeclaratorNodes?.has(t)) {
-        handleVarDeclarator(node);
+        handleVarDeclarator(node, rules, scopeStack, assignments, isCallNode);
         return;
       }
 
-      // Call expressions
       if (isCallNode(t)) {
-        handleCallExpr(node);
+        handleCallExpr(node, rules, scopeStack, argFlows);
         return;
       }
 
-      // Assignment expressions
       if (rules.assignmentNode && t === rules.assignmentNode) {
-        handleAssignment(node);
+        handleAssignment(node, rules, scopeStack, assignments, mutations, isCallNode);
         return;
       }
 
-      // Mutation detection via expression_statement
       if (rules.expressionStmtNode && t === rules.expressionStmtNode) {
-        handleExprStmtMutation(node);
+        handleExprStmtMutation(node, rules, scopeStack, mutations, isCallNode);
       }
     },
 

package/src/cli/commands/ast.js

@@ -1,3 +1,4 @@
+import { collectFile } from '../../db/query-builder.js';
 import { ConfigError } from '../../shared/errors.js';
 
 export const command = {
@@ -6,7 +7,7 @@ export const command = {
   queryOpts: true,
   options: [
     ['-k, --kind <kind>', 'Filter by AST node kind (call, new, string, regex, throw, await)'],
-    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-f, --file <path>', 'Scope to file (partial match, repeatable)', collectFile],
   ],
   async execute([pattern], opts, ctx) {
     const { AST_NODE_KINDS, astQuery } = await import('../../ast.js');

package/src/cli/commands/audit.js

@@ -1,3 +1,4 @@
+import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { audit } from '../../presentation/audit.js';
 import { explain } from '../../presentation/queries-cli.js';
@@ -10,7 +11,7 @@ export const command = {
     ['-d, --db <path>', 'Path to graph.db'],
     ['--quick', 'Structural summary only (skip impact analysis and health metrics)'],
     ['--depth <n>', 'Impact/explain depth', '3'],
-    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-f, --file <path>', 'Scope to file (partial match, repeatable)', collectFile],
     ['-k, --kind <kind>', 'Filter by symbol kind'],
     ['-T, --no-tests', 'Exclude test/spec files from results'],
     ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],

package/src/cli/commands/batch.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { BATCH_COMMANDS, multiBatchData, splitTargets } from '../../features/batch.js';
 import { batch } from '../../presentation/batch.js';
@@ -12,7 +13,7 @@ export const command = {
     ['--from-file <path>', 'Read targets from file (JSON array or newline-delimited)'],
     ['--stdin', 'Read targets from stdin (JSON array)'],
     ['--depth <n>', 'Traversal depth passed to underlying command'],
-    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-f, --file <path>', 'Scope to file (partial match, repeatable)', collectFile],
     ['-k, --kind <kind>', 'Filter by symbol kind'],
     ['-T, --no-tests', 'Exclude test/spec files from results'],
     ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],

package/src/cli/commands/brief.js

@@ -0,0 +1,12 @@
+import { brief } from '../../presentation/brief.js';
+
+export const command = {
+  name: 'brief <file>',
+  description: 'Token-efficient file summary: symbols with roles, caller counts, risk tier',
+  queryOpts: true,
+  execute([file], opts, ctx) {
+    brief(file, opts.db, {
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/cfg.js

@@ -1,3 +1,4 @@
+import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 
 export const command = {
@@ -6,7 +7,7 @@ export const command = {
   queryOpts: true,
   options: [
     ['--format <fmt>', 'Output format: text, dot, mermaid', 'text'],
-    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-f, --file <path>', 'Scope to file (partial match, repeatable)', collectFile],
     ['-k, --kind <kind>', 'Filter by symbol kind'],
   ],
   validate([_name], opts) {