@optave/codegraph 3.1.0 → 3.1.2

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

@@ -0,0 +1,243 @@
+/**
+ * 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 {
+  computeHalsteadDerived,
+  computeLOCMetrics,
+  computeMaintainabilityIndex,
+} from '../metrics.js';
+
+/**
+ * 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 = {}) {
+  const { fileLevelWalk = false, langId = null } = options;
+
+  // Per-function accumulators
+  let cognitive = 0;
+  let cyclomatic = 1;
+  let maxNesting = 0;
+  let operators = hRules ? new Map() : null;
+  let operands = hRules ? new Map() : null;
+  let halsteadSkipDepth = 0;
+
+  // In file-level mode, we only count when inside a function
+  let activeFuncNode = null;
+  let activeFuncName = null;
+  // Nesting depth relative to the active function (for nested functions)
+  let funcDepth = 0;
+
+  // Collected results (one per function)
+  const results = [];
+
+  function reset() {
+    cognitive = 0;
+    cyclomatic = 1;
+    maxNesting = 0;
+    operators = hRules ? new Map() : null;
+    operands = hRules ? new Map() : null;
+    halsteadSkipDepth = 0;
+  }
+
+  function collectResult(funcNode) {
+    const halstead =
+      hRules && operators && operands ? computeHalsteadDerived(operators, operands) : null;
+    const loc = computeLOCMetrics(funcNode, langId);
+    const volume = halstead ? halstead.volume : 0;
+    const commentRatio = loc.loc > 0 ? loc.commentLines / loc.loc : 0;
+    const mi = computeMaintainabilityIndex(volume, cyclomatic, loc.sloc, commentRatio);
+
+    return { cognitive, cyclomatic, maxNesting, halstead, loc, mi };
+  }
+
+  return {
+    name: 'complexity',
+    functionNodeTypes: cRules.functionNodes,
+
+    enterFunction(funcNode, funcName, _context) {
+      if (fileLevelWalk) {
+        if (!activeFuncNode) {
+          // Top-level function: start fresh
+          reset();
+          activeFuncNode = funcNode;
+          activeFuncName = funcName;
+          funcDepth = 0;
+        } else {
+          // Nested function: increase nesting for complexity
+          funcDepth++;
+        }
+      } else {
+        // Function-level mode: track nested functions for correct nesting depth
+        funcDepth++;
+      }
+    },
+
+    exitFunction(funcNode, _funcName, _context) {
+      if (fileLevelWalk) {
+        if (funcNode === activeFuncNode) {
+          // Leaving the top-level function: emit result
+          results.push({
+            funcNode,
+            funcName: activeFuncName,
+            metrics: collectResult(funcNode),
+          });
+          activeFuncNode = null;
+          activeFuncName = null;
+        } else {
+          funcDepth--;
+        }
+      } else {
+        funcDepth--;
+      }
+    },
+
+    enterNode(node, context) {
+      // In file-level mode, skip nodes outside any function
+      if (fileLevelWalk && !activeFuncNode) return;
+
+      const type = node.type;
+      const nestingLevel = fileLevelWalk ? context.nestingLevel + funcDepth : context.nestingLevel;
+
+      // ── Halstead classification ──
+      if (hRules) {
+        if (hRules.skipTypes.has(type)) halsteadSkipDepth++;
+        if (halsteadSkipDepth === 0) {
+          if (hRules.compoundOperators.has(type)) {
+            operators.set(type, (operators.get(type) || 0) + 1);
+          }
+          if (node.childCount === 0) {
+            if (hRules.operatorLeafTypes.has(type)) {
+              operators.set(type, (operators.get(type) || 0) + 1);
+            } else if (hRules.operandLeafTypes.has(type)) {
+              const text = node.text;
+              operands.set(text, (operands.get(text) || 0) + 1);
+            }
+          }
+        }
+      }
+
+      // ── Complexity: track nesting depth ──
+      if (nestingLevel > maxNesting) maxNesting = nestingLevel;
+
+      // Handle logical operators in binary expressions
+      if (type === cRules.logicalNodeType) {
+        const op = node.child(1)?.type;
+        if (op && cRules.logicalOperators.has(op)) {
+          cyclomatic++;
+          const parent = node.parent;
+          let sameSequence = false;
+          if (parent && parent.type === cRules.logicalNodeType) {
+            const parentOp = parent.child(1)?.type;
+            if (parentOp === op) sameSequence = true;
+          }
+          if (!sameSequence) cognitive++;
+          // Don't skip children — walker handles recursion
+        }
+      }
+
+      // Handle optional chaining (cyclomatic only)
+      if (type === cRules.optionalChainType) {
+        cyclomatic++;
+      }
+
+      // Handle branch/control flow nodes (skip keyword leaf tokens)
+      if (cRules.branchNodes.has(type) && node.childCount > 0) {
+        // Pattern A: else clause wraps if (JS/C#/Rust)
+        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;
+          }
+          cognitive++;
+          return;
+        }
+
+        // Pattern B: explicit elif node (Python/Ruby/PHP)
+        if (cRules.elifNodeType && type === cRules.elifNodeType) {
+          cognitive++;
+          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;
+          } else if (cRules.elseNodeType) {
+            isElseIf = node.parent?.type === cRules.elseNodeType;
+          }
+        }
+
+        if (isElseIf) {
+          cognitive++;
+          cyclomatic++;
+          return;
+        }
+
+        // Regular branch node
+        cognitive += 1 + nestingLevel;
+        cyclomatic++;
+
+        if (cRules.switchLikeNodes?.has(type)) {
+          cyclomatic--;
+        }
+
+        // Nesting nodes are handled by the walker's nestingNodeTypes option
+        // But we still need them to count in complexity — they already do above
+      }
+
+      // Pattern C plain else: block that is the alternative of an if_statement (Go/Java)
+      if (
+        cRules.elseViaAlternative &&
+        type !== cRules.ifNodeType &&
+        node.parent?.type === cRules.ifNodeType &&
+        node.parent.childForFieldName('alternative')?.id === node.id
+      ) {
+        cognitive++;
+      }
+
+      // Handle case nodes (cyclomatic only, skip keyword leaves)
+      if (cRules.caseNodes.has(type) && node.childCount > 0) {
+        cyclomatic++;
+      }
+
+      // Handle nested function definitions (increase nesting)
+      // In file-level mode funcDepth handles this; in function-level mode the
+      // nestingNodeTypes option should include function nodes
+    },
+
+    exitNode(node) {
+      // Decrement skip depth when leaving a skip-type subtree
+      if (hRules?.skipTypes.has(node.type)) {
+        halsteadSkipDepth--;
+      }
+    },
+
+    finish() {
+      if (fileLevelWalk) {
+        return results;
+      }
+      // Function-level mode: return single result (no funcNode reference needed)
+      return collectResult({ text: '' });
+    },
+  };
+}

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

@@ -0,0 +1,358 @@
+/**
+ * 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 {
+  collectIdentifiers,
+  extractParamNames,
+  extractParams,
+  functionName,
+  isIdent,
+  memberReceiver,
+  resolveCalleeName,
+  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 = [];
+
+  const scopeStack = [];
+
+  function currentScope() {
+    return scopeStack.length > 0 ? scopeStack[scopeStack.length - 1] : 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 unwrapAwait(node) {
+    if (rules.awaitNode && node.type === rules.awaitNode) {
+      return node.namedChildren[0] || node;
+    }
+    return node;
+  }
+
+  function isCall(node) {
+    return node && isCallNode(node.type);
+  }
+
+  function handleVarDeclarator(node) {
+    let nameNode = node.childForFieldName(rules.varNameField);
+    let valueNode = 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];
+          break;
+        }
+      }
+    }
+
+    if (!valueNode) {
+      for (const child of node.namedChildren) {
+        if (child !== nameNode && isCall(unwrapAwait(child))) {
+          valueNode = child;
+          break;
+        }
+      }
+    }
+
+    if (rules.expressionListType) {
+      if (nameNode?.type === rules.expressionListType) nameNode = nameNode.namedChildren[0];
+      if (valueNode?.type === rules.expressionListType) valueNode = valueNode.namedChildren[0];
+    }
+
+    const scope = currentScope();
+    if (!nameNode || !valueNode || !scope) return;
+
+    const unwrapped = unwrapAwait(valueNode);
+    const callExpr = isCall(unwrapped) ? 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: 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;
+          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,
+          });
+        }
+      }
+    }
+
+    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 });
+        }
+      }
+    }
+  }
+
+  function handleCallExpr(node) {
+    const callee = resolveCalleeName(node, rules);
+    const argsNode = node.childForFieldName(rules.callArgsField);
+    const scope = currentScope();
+    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;
+      }
+
+      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,
+          });
+        }
+      }
+      argIndex++;
+    }
+  }
+
+  function handleExprStmtMutation(node) {
+    if (rules.mutatingMethods.size === 0) return;
+    const expr = node.namedChildren[0];
+    if (!expr || !isCall(expr)) return;
+
+    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);
+    }
+
+    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;
+
+    const scope = currentScope();
+    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,
+      });
+    }
+  }
+
+  return {
+    name: 'dataflow',
+    functionNodeTypes: rules.functionNodes,
+
+    enterFunction(funcNode, _funcName, _context) {
+      const name = functionName(funcNode, rules);
+      const paramsNode = funcNode.childForFieldName(rules.paramListField);
+      const paramList = extractParams(paramsNode, rules);
+      const paramMap = new Map();
+      for (const p of paramList) {
+        paramMap.set(p.name, p.index);
+        if (name) {
+          parameters.push({
+            funcName: name,
+            paramName: p.name,
+            paramIndex: p.index,
+            line: (paramsNode?.startPosition?.row ?? funcNode.startPosition.row) + 1,
+          });
+        }
+      }
+      scopeStack.push({ funcName: name, funcNode, params: paramMap, locals: new Map() });
+    },
+
+    exitFunction(_funcNode, _funcName, _context) {
+      scopeStack.pop();
+    },
+
+    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,
+          });
+        }
+        return;
+      }
+
+      // Variable declarations
+      if (rules.varDeclaratorNode && t === rules.varDeclaratorNode) {
+        handleVarDeclarator(node);
+        return;
+      }
+      if (rules.varDeclaratorNodes?.has(t)) {
+        handleVarDeclarator(node);
+        return;
+      }
+
+      // Call expressions
+      if (isCallNode(t)) {
+        handleCallExpr(node);
+        return;
+      }
+
+      // Assignment expressions
+      if (rules.assignmentNode && t === rules.assignmentNode) {
+        handleAssignment(node);
+        return;
+      }
+
+      // Mutation detection via expression_statement
+      if (rules.expressionStmtNode && t === rules.expressionStmtNode) {
+        handleExprStmtMutation(node);
+      }
+    },
+
+    finish() {
+      return { parameters, returns, assignments, argFlows, mutations };
+    },
+  };
+}