@optave/codegraph 3.3.0 → 3.4.0

package/src/ast-analysis/visitors/{complexity-visitor.js → complexity-visitor.ts}

@@ -1,65 +1,74 @@
-/**
- * Visitor: Compute cognitive/cyclomatic complexity, max nesting, and Halstead metrics.
- *
- * Replaces the computeAllMetrics() DFS walk in complexity.js with a visitor that
- * plugs into the unified walkWithVisitors framework. Operates per-function:
- * resets accumulators on enterFunction, emits results on exitFunction.
- */
-
+import type { EnterNodeResult, TreeSitterNode, Visitor, VisitorContext } from '../../types.js';
 import {
   computeHalsteadDerived,
   computeLOCMetrics,
   computeMaintainabilityIndex,
 } from '../metrics.js';
 
-// ── Halstead classification ─────────────────────────────────────────────
+// biome-ignore lint/suspicious/noExplicitAny: complexity/halstead rules are opaque language-specific objects
+type AnyRules = any;
+
+interface ComplexityAcc {
+  cognitive: number;
+  cyclomatic: number;
+  maxNesting: number;
+  operators: Map<string, number> | null;
+  operands: Map<string, number> | null;
+  halsteadSkipDepth: number;
+}
+
+interface PerFunctionResult {
+  funcNode: TreeSitterNode;
+  funcName: string | null;
+  metrics: ReturnType<typeof collectResult>;
+}
 
-function classifyHalstead(node, hRules, acc) {
+function classifyHalstead(node: TreeSitterNode, hRules: AnyRules, acc: ComplexityAcc): void {
   const type = node.type;
   if (hRules.skipTypes.has(type)) acc.halsteadSkipDepth++;
   if (acc.halsteadSkipDepth > 0) return;
 
-  if (hRules.compoundOperators.has(type)) {
+  if (hRules.compoundOperators.has(type) && acc.operators) {
     acc.operators.set(type, (acc.operators.get(type) || 0) + 1);
   }
   if (node.childCount === 0) {
-    if (hRules.operatorLeafTypes.has(type)) {
+    if (hRules.operatorLeafTypes.has(type) && acc.operators) {
       acc.operators.set(type, (acc.operators.get(type) || 0) + 1);
-    } else if (hRules.operandLeafTypes.has(type)) {
+    } else if (hRules.operandLeafTypes.has(type) && acc.operands) {
       const text = node.text;
       acc.operands.set(text, (acc.operands.get(text) || 0) + 1);
     }
   }
 }
 
-// ── Branch complexity classification ────────────────────────────────────
-
-function classifyBranchNode(node, type, nestingLevel, cRules, acc) {
-  // Pattern A: else clause wraps if (JS/C#/Rust)
+function classifyBranchNode(
+  node: TreeSitterNode,
+  type: string,
+  nestingLevel: number,
+  cRules: AnyRules,
+  acc: ComplexityAcc,
+): void {
   if (cRules.elseNodeType && type === cRules.elseNodeType) {
     const firstChild = node.namedChild(0);
     if (firstChild && firstChild.type === cRules.ifNodeType) {
-      // else-if: the if_statement child handles its own increment
       return;
     }
     acc.cognitive++;
     return;
   }
 
-  // Pattern B: explicit elif node (Python/Ruby/PHP)
   if (cRules.elifNodeType && type === cRules.elifNodeType) {
     acc.cognitive++;
     acc.cyclomatic++;
     return;
   }
 
-  // Detect else-if via Pattern A or C
   let isElseIf = false;
   if (type === cRules.ifNodeType) {
     if (cRules.elseViaAlternative) {
       isElseIf =
         node.parent?.type === cRules.ifNodeType &&
-        node.parent.childForFieldName('alternative')?.id === node.id;
+        node.parent?.childForFieldName('alternative')?.id === node.id;
     } else if (cRules.elseNodeType) {
       isElseIf = node.parent?.type === cRules.elseNodeType;
     }
@@ -71,7 +80,6 @@ function classifyBranchNode(node, type, nestingLevel, cRules, acc) {
     return;
   }
 
-  // Regular branch node
   acc.cognitive += 1 + nestingLevel;
   acc.cyclomatic++;
 
@@ -80,27 +88,40 @@ function classifyBranchNode(node, type, nestingLevel, cRules, acc) {
   }
 }
 
-// ── Plain-else detection (Pattern C: Go/Java) ──────────────────────────
-
-function classifyPlainElse(node, type, cRules, acc) {
+function classifyPlainElse(
+  node: TreeSitterNode,
+  type: string,
+  cRules: AnyRules,
+  acc: ComplexityAcc,
+): void {
   if (
     cRules.elseViaAlternative &&
     type !== cRules.ifNodeType &&
     node.parent?.type === cRules.ifNodeType &&
-    node.parent.childForFieldName('alternative')?.id === node.id
+    node.parent?.childForFieldName('alternative')?.id === node.id
   ) {
     acc.cognitive++;
   }
 }
 
-// ── Result collection ───────────────────────────────────────────────────
-
-function collectResult(funcNode, acc, hRules, langId) {
+function collectResult(
+  funcNode: TreeSitterNode | { text: string },
+  acc: ComplexityAcc,
+  hRules: AnyRules | null | undefined,
+  langId: string | null,
+): {
+  cognitive: number;
+  cyclomatic: number;
+  maxNesting: number;
+  halstead: ReturnType<typeof computeHalsteadDerived> | null;
+  loc: ReturnType<typeof computeLOCMetrics>;
+  mi: number;
+} {
   const halstead =
     hRules && acc.operators && acc.operands
       ? computeHalsteadDerived(acc.operators, acc.operands)
       : null;
-  const loc = computeLOCMetrics(funcNode, langId);
+  const loc = computeLOCMetrics(funcNode as TreeSitterNode, langId ?? undefined);
   const volume = halstead ? halstead.volume : 0;
   const commentRatio = loc.loc > 0 ? loc.commentLines / loc.loc : 0;
   const mi = computeMaintainabilityIndex(volume, acc.cyclomatic, loc.sloc, commentRatio);
@@ -115,7 +136,7 @@ function collectResult(funcNode, acc, hRules, langId) {
   };
 }
 
-function resetAccumulators(hRules) {
+function resetAccumulators(hRules: AnyRules | null | undefined): ComplexityAcc {
   return {
     cognitive: 0,
     cyclomatic: 1,
@@ -126,35 +147,28 @@ function resetAccumulators(hRules) {
   };
 }
 
-// ── Visitor factory ─────────────────────────────────────────────────────
-
-/**
- * Create a complexity visitor for use with walkWithVisitors.
- *
- * When used in file-level mode (walking an entire file), this visitor collects
- * per-function metrics using enterFunction/exitFunction hooks. When used in
- * function-level mode (walking a single function node), it collects one result.
- *
- * @param {object} cRules  - COMPLEXITY_RULES for the language
- * @param {object} [hRules] - HALSTEAD_RULES for the language (null if unavailable)
- * @param {object} [options]
- * @param {boolean} [options.fileLevelWalk=false] - true when walking an entire file
- * @returns {Visitor}
- */
-export function createComplexityVisitor(cRules, hRules, options = {}) {
+export function createComplexityVisitor(
+  cRules: AnyRules,
+  hRules?: AnyRules | null,
+  options: { fileLevelWalk?: boolean; langId?: string | null } = {},
+): Visitor {
   const { fileLevelWalk = false, langId = null } = options;
 
   let acc = resetAccumulators(hRules);
-  let activeFuncNode = null;
-  let activeFuncName = null;
+  let activeFuncNode: TreeSitterNode | null = null;
+  let activeFuncName: string | null = null;
   let funcDepth = 0;
-  const results = [];
+  const results: PerFunctionResult[] = [];
 
   return {
     name: 'complexity',
     functionNodeTypes: cRules.functionNodes,
 
-    enterFunction(funcNode, funcName, _context) {
+    enterFunction(
+      funcNode: TreeSitterNode,
+      funcName: string | null,
+      _context: VisitorContext,
+    ): void {
       if (fileLevelWalk) {
         if (!activeFuncNode) {
           acc = resetAccumulators(hRules);
@@ -169,7 +183,11 @@ export function createComplexityVisitor(cRules, hRules, options = {}) {
       }
     },
 
-    exitFunction(funcNode, _funcName, _context) {
+    exitFunction(
+      funcNode: TreeSitterNode,
+      _funcName: string | null,
+      _context: VisitorContext,
+    ): void {
       if (fileLevelWalk) {
         if (funcNode === activeFuncNode) {
           results.push({
@@ -187,7 +205,7 @@ export function createComplexityVisitor(cRules, hRules, options = {}) {
       }
     },
 
-    enterNode(node, context) {
+    enterNode(node: TreeSitterNode, context: VisitorContext): EnterNodeResult | undefined {
       if (fileLevelWalk && !activeFuncNode) return;
 
       const type = node.type;
@@ -197,7 +215,6 @@ export function createComplexityVisitor(cRules, hRules, options = {}) {
 
       if (nestingLevel > acc.maxNesting) acc.maxNesting = nestingLevel;
 
-      // Logical operators in binary expressions
       if (type === cRules.logicalNodeType) {
         const op = node.child(1)?.type;
         if (op && cRules.logicalOperators.has(op)) {
@@ -212,28 +229,24 @@ export function createComplexityVisitor(cRules, hRules, options = {}) {
         }
       }
 
-      // Optional chaining (cyclomatic only)
       if (type === cRules.optionalChainType) acc.cyclomatic++;
 
-      // Branch/control flow nodes (skip keyword leaf tokens)
       if (cRules.branchNodes.has(type) && node.childCount > 0) {
         classifyBranchNode(node, type, nestingLevel, cRules, acc);
       }
 
-      // Pattern C plain else (Go/Java)
       classifyPlainElse(node, type, cRules, acc);
 
-      // Case nodes (cyclomatic only, skip keyword leaves)
       if (cRules.caseNodes.has(type) && node.childCount > 0) acc.cyclomatic++;
     },
 
-    exitNode(node) {
+    exitNode(node: TreeSitterNode): void {
       if (hRules?.skipTypes.has(node.type)) acc.halsteadSkipDepth--;
     },
 
-    finish() {
+    finish(): PerFunctionResult[] | ReturnType<typeof collectResult> {
       if (fileLevelWalk) return results;
-      return collectResult({ text: '' }, acc, hRules, langId);
+      return collectResult({ text: '' } as TreeSitterNode, acc, hRules, langId);
     },
   };
 }

package/src/ast-analysis/visitors/{dataflow-visitor.js → dataflow-visitor.ts}

@@ -1,15 +1,4 @@
-/**
- * Visitor: Extract dataflow information (define-use chains, arg flows, mutations).
- *
- * Replaces the standalone extractDataflow() visit logic in dataflow.js with a
- * visitor that plugs into the unified walkWithVisitors framework.
- *
- * NOTE: The original dataflow walk uses `node.namedChildren` while the visitor
- * framework uses `node.child(i)` (all children). This visitor handles both
- * named and unnamed children correctly since the classification logic only
- * cares about specific node types/fields, not about traversal order.
- */
-
+import type { EnterNodeResult, TreeSitterNode, Visitor, VisitorContext } from '../../types.js';
 import {
   collectIdentifiers,
   extractParamNames,
@@ -21,24 +10,92 @@ import {
   truncate,
 } from '../visitor-utils.js';
 
-// ── Scope helpers ───────────────────────────────────────────────────────
+// biome-ignore lint/suspicious/noExplicitAny: dataflow rules are opaque language-specific objects
+type AnyRules = any;
+
+interface ScopeEntry {
+  funcName: string | null;
+  funcNode: TreeSitterNode;
+  params: Map<string, number>;
+  locals: Map<string, { type: string; callee?: string }>;
+}
+
+interface Binding {
+  type: string;
+  index?: number;
+  source?: { type: string; callee?: string } | null;
+  funcName: string | null;
+}
+
+interface DataflowParam {
+  funcName: string;
+  paramName: string;
+  paramIndex: number;
+  line: number;
+}
+
+interface DataflowReturnEntry {
+  funcName: string;
+  expression: string;
+  referencedNames: string[];
+  line: number;
+}
+
+interface DataflowAssignment {
+  varName: string;
+  callerFunc: string;
+  sourceCallName: string;
+  expression: string;
+  line: number;
+}
 
-function currentScope(scopeStack) {
-  return scopeStack.length > 0 ? scopeStack[scopeStack.length - 1] : null;
+interface DataflowArgFlow {
+  callerFunc: string;
+  calleeName: string;
+  argIndex: number;
+  argName: string;
+  binding: Binding;
+  confidence: number;
+  expression: string;
+  line: number;
 }
 
-function findBinding(name, scopeStack) {
+interface DataflowMutation {
+  funcName: string;
+  receiverName: string;
+  binding: Binding;
+  mutatingExpr: string;
+  line: number;
+}
+
+interface DataflowResultInternal {
+  parameters: DataflowParam[];
+  returns: DataflowReturnEntry[];
+  assignments: DataflowAssignment[];
+  argFlows: DataflowArgFlow[];
+  mutations: DataflowMutation[];
+}
+
+function currentScope(scopeStack: ScopeEntry[]): ScopeEntry | undefined {
+  return scopeStack[scopeStack.length - 1];
+}
+
+function findBinding(name: string, scopeStack: ScopeEntry[]): Binding | null {
   for (let i = scopeStack.length - 1; i >= 0; i--) {
-    const scope = scopeStack[i];
+    const scope = scopeStack[i]!;
     if (scope.params.has(name))
-      return { type: 'param', index: scope.params.get(name), funcName: scope.funcName };
+      return { type: 'param', index: scope.params.get(name) as number, funcName: scope.funcName };
     if (scope.locals.has(name))
-      return { type: 'local', source: scope.locals.get(name), funcName: scope.funcName };
+      return {
+        type: 'local',
+        source: scope.locals.get(name) as { type: string; callee?: string },
+        funcName: scope.funcName,
+      };
   }
   return null;
 }
 
-function bindingConfidence(binding) {
+function bindingConfidence(binding: Binding | null): number {
   if (!binding) return 0.5;
   if (binding.type === 'param') return 1.0;
   if (binding.type === 'local') {
@@ -49,29 +106,33 @@ function bindingConfidence(binding) {
   return 0.5;
 }
 
-// ── Node helpers ────────────────────────────────────────────────────────
-
-function unwrapAwait(node, rules) {
+function unwrapAwait(node: TreeSitterNode, rules: AnyRules): TreeSitterNode {
   if (rules.awaitNode && node.type === rules.awaitNode) {
     return node.namedChildren[0] || node;
   }
   return node;
 }
 
-function isCall(node, isCallNode) {
-  return node && isCallNode(node.type);
+function isCall(node: TreeSitterNode | null, isCallNode: (t: string) => boolean): boolean {
+  return node != null && isCallNode(node.type);
 }
 
-// ── Node handlers ───────────────────────────────────────────────────────
-
-function handleVarDeclarator(node, rules, scopeStack, assignments, isCallNode) {
+function handleVarDeclarator(
+  node: TreeSitterNode,
+  rules: AnyRules,
+  scopeStack: ScopeEntry[],
+  assignments: DataflowAssignment[],
+  isCallNode: (t: string) => boolean,
+): void {
   let nameNode = node.childForFieldName(rules.varNameField);
-  let valueNode = rules.varValueField ? node.childForFieldName(rules.varValueField) : null;
+  let valueNode: TreeSitterNode | null = rules.varValueField
+    ? node.childForFieldName(rules.varValueField)
+    : null;
 
   if (!valueNode && rules.equalsClauseType) {
     for (const child of node.namedChildren) {
       if (child.type === rules.equalsClauseType) {
-        valueNode = child.childForFieldName('value') || child.namedChildren[0];
+        valueNode = child.childForFieldName('value') || child.namedChildren[0] || null;
         break;
       }
     }
@@ -87,8 +148,10 @@ function handleVarDeclarator(node, rules, scopeStack, assignments, isCallNode) {
   }
 
   if (rules.expressionListType) {
-    if (nameNode?.type === rules.expressionListType) nameNode = nameNode.namedChildren[0];
-    if (valueNode?.type === rules.expressionListType) valueNode = valueNode.namedChildren[0];
+    if (nameNode && nameNode.type === rules.expressionListType)
+      nameNode = nameNode.namedChildren[0] ?? null;
+    if (valueNode && valueNode.type === rules.expressionListType)
+      valueNode = valueNode.namedChildren[0] ?? null;
   }
 
   const scope = currentScope(scopeStack);
@@ -133,7 +196,14 @@ function handleVarDeclarator(node, rules, scopeStack, assignments, isCallNode) {
   }
 }
 
-function handleAssignment(node, rules, scopeStack, assignments, mutations, isCallNode) {
+function handleAssignment(
+  node: TreeSitterNode,
+  rules: AnyRules,
+  scopeStack: ScopeEntry[],
+  assignments: DataflowAssignment[],
+  mutations: DataflowMutation[],
+  isCallNode: (t: string) => boolean,
+): void {
   const left = node.childForFieldName(rules.assignLeftField);
   const right = node.childForFieldName(rules.assignRightField);
   const scope = currentScope(scopeStack);
@@ -174,7 +244,12 @@ function handleAssignment(node, rules, scopeStack, assignments, mutations, isCal
   }
 }
 
-function handleCallExpr(node, rules, scopeStack, argFlows) {
+function handleCallExpr(
+  node: TreeSitterNode,
+  rules: AnyRules,
+  scopeStack: ScopeEntry[],
+  argFlows: DataflowArgFlow[],
+): void {
   const callee = resolveCalleeName(node, rules);
   const argsNode = node.childForFieldName(rules.callArgsField);
   const scope = currentScope(scopeStack);
@@ -218,13 +293,19 @@ function handleCallExpr(node, rules, scopeStack, argFlows) {
   }
 }
 
-function handleExprStmtMutation(node, rules, scopeStack, mutations, isCallNode) {
+function handleExprStmtMutation(
+  node: TreeSitterNode,
+  rules: AnyRules,
+  scopeStack: ScopeEntry[],
+  mutations: DataflowMutation[],
+  isCallNode: (t: string) => boolean,
+): void {
   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: string | null = null;
+  let receiver: string | null = null;
 
   const fn = expr.childForFieldName(rules.callFunctionField);
   if (fn && fn.type === rules.memberNode) {
@@ -259,15 +340,18 @@ function handleExprStmtMutation(node, rules, scopeStack, mutations, isCallNode)
   }
 }
 
-// ── Return statement handler ────────────────────────────────────────────
-
-function handleReturn(node, rules, scopeStack, returns) {
-  if (node.parent?.type === rules.returnNode) return; // keyword token, not statement
+function handleReturn(
+  node: TreeSitterNode,
+  rules: AnyRules,
+  scopeStack: ScopeEntry[],
+  returns: DataflowReturnEntry[],
+): void {
+  if (node.parent?.type === rules.returnNode) return;
 
   const scope = currentScope(scopeStack);
   if (scope?.funcName) {
     const expr = node.namedChildren[0];
-    const referencedNames = [];
+    const referencedNames: string[] = [];
     if (expr) collectIdentifiers(expr, referencedNames, rules);
     returns.push({
       funcName: scope.funcName,
@@ -278,33 +362,31 @@ function handleReturn(node, rules, scopeStack, returns) {
   }
 }
 
-// ── 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;
+export function createDataflowVisitor(rules: AnyRules): Visitor {
+  const isCallNode: (t: string) => boolean = rules.callNodes
+    ? (t: string) => rules.callNodes.has(t)
+    : (t: string) => t === rules.callNode;
 
-  const parameters = [];
-  const returns = [];
-  const assignments = [];
-  const argFlows = [];
-  const mutations = [];
-  const scopeStack = [];
+  const parameters: DataflowParam[] = [];
+  const returns: DataflowReturnEntry[] = [];
+  const assignments: DataflowAssignment[] = [];
+  const argFlows: DataflowArgFlow[] = [];
+  const mutations: DataflowMutation[] = [];
+  const scopeStack: ScopeEntry[] = [];
 
   return {
     name: 'dataflow',
     functionNodeTypes: rules.functionNodes,
 
-    enterFunction(funcNode, _funcName, _context) {
+    enterFunction(
+      funcNode: TreeSitterNode,
+      _funcName: string | null,
+      _context: VisitorContext,
+    ): void {
       const name = functionName(funcNode, rules);
       const paramsNode = funcNode.childForFieldName(rules.paramListField);
       const paramList = extractParams(paramsNode, rules);
-      const paramMap = new Map();
+      const paramMap = new Map<string, number>();
       for (const p of paramList) {
         paramMap.set(p.name, p.index);
         if (name) {
@@ -319,11 +401,15 @@ export function createDataflowVisitor(rules) {
       scopeStack.push({ funcName: name, funcNode, params: paramMap, locals: new Map() });
     },
 
-    exitFunction(_funcNode, _funcName, _context) {
+    exitFunction(
+      _funcNode: TreeSitterNode,
+      _funcName: string | null,
+      _context: VisitorContext,
+    ): void {
       scopeStack.pop();
     },
 
-    enterNode(node, _context) {
+    enterNode(node: TreeSitterNode, _context: VisitorContext): EnterNodeResult | undefined {
       const t = node.type;
 
       if (rules.functionNodes.has(t)) return;
@@ -357,7 +443,7 @@ export function createDataflowVisitor(rules) {
       }
     },
 
-    finish() {
+    finish(): DataflowResultInternal {
       return { parameters, returns, assignments, argFlows, mutations };
     },
   };

package/src/cli/commands/{ast.js → ast.ts}

@@ -1,7 +1,8 @@
 import { collectFile } from '../../db/query-builder.js';
 import { ConfigError } from '../../shared/errors.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'ast [pattern]',
   description: 'Search stored AST nodes (calls, new, string, regex, throw, await) by pattern',
   queryOpts: true,
@@ -10,8 +11,8 @@ export const command = {
     ['-f, --file <path>', 'Scope to file (partial match, repeatable)', collectFile],
   ],
   async execute([pattern], opts, ctx) {
-    const { AST_NODE_KINDS, astQuery } = await import('../../ast.js');
-    if (opts.kind && !AST_NODE_KINDS.includes(opts.kind)) {
+    const { AST_NODE_KINDS, astQuery } = await import('../../features/ast.js');
+    if (opts.kind && !(AST_NODE_KINDS as readonly string[]).includes(opts.kind)) {
       throw new ConfigError(`Invalid AST kind "${opts.kind}". Valid: ${AST_NODE_KINDS.join(', ')}`);
     }
     astQuery(pattern, opts.db, {

package/src/cli/commands/{audit.js → audit.ts}

@@ -3,8 +3,9 @@ import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { audit } from '../../presentation/audit.js';
 import { explain } from '../../presentation/queries-cli.js';
 import { config } from '../shared/options.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'audit <target>',
   description: 'Composite report: explain + impact + health metrics per function',
   options: [
@@ -21,21 +22,21 @@ export const command = {
     ['--ndjson', 'Newline-delimited JSON output (quick mode)'],
   ],
   validate([_target], opts) {
-    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
       return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
     }
   },
   execute([target], opts, ctx) {
     const qOpts = ctx.resolveQueryOpts(opts);
     if (opts.quick) {
-      explain(target, opts.db, {
-        depth: parseInt(opts.depth, 10),
+      explain(target!, opts.db, {
+        depth: parseInt(opts.depth as string, 10),
         ...qOpts,
       });
       return;
     }
-    audit(target, opts.db, {
-      depth: parseInt(opts.depth, 10),
+    audit(target!, opts.db, {
+      depth: parseInt(opts.depth as string, 10),
       file: opts.file,
       kind: opts.kind,
       noTests: qOpts.noTests,