@optave/codegraph 3.1.0 → 3.1.1

package/src/ast-analysis/rules/ruby.js

@@ -0,0 +1,204 @@
+/**
+ * Ruby — AST analysis rules.
+ */
+
+import { makeCfgRules, makeDataflowRules } from '../shared.js';
+
+// ─── Complexity ───────────────────────────────────────────────────────────
+
+export const complexity = {
+  branchNodes: new Set([
+    'if',
+    'elsif',
+    'else',
+    'unless',
+    'case',
+    'for',
+    'while',
+    'until',
+    'rescue',
+    'conditional',
+  ]),
+  caseNodes: new Set(['when']),
+  logicalOperators: new Set(['and', 'or', '&&', '||']),
+  logicalNodeType: 'binary',
+  optionalChainType: null,
+  nestingNodes: new Set(['if', 'unless', 'case', 'for', 'while', 'until', 'rescue', 'conditional']),
+  functionNodes: new Set(['method', 'singleton_method', 'lambda', 'do_block']),
+  ifNodeType: 'if',
+  elseNodeType: 'else',
+  elifNodeType: 'elsif',
+  elseViaAlternative: false,
+  switchLikeNodes: new Set(['case']),
+};
+
+// ─── Halstead ─────────────────────────────────────────────────────────────
+
+export const halstead = {
+  operatorLeafTypes: new Set([
+    '+',
+    '-',
+    '*',
+    '/',
+    '%',
+    '**',
+    '=',
+    '+=',
+    '-=',
+    '*=',
+    '/=',
+    '%=',
+    '**=',
+    '&=',
+    '|=',
+    '^=',
+    '<<=',
+    '>>=',
+    '==',
+    '!=',
+    '<',
+    '>',
+    '<=',
+    '>=',
+    '<=>',
+    '===',
+    '=~',
+    '!~',
+    '&&',
+    '||',
+    '!',
+    'and',
+    'or',
+    'not',
+    '&',
+    '|',
+    '^',
+    '~',
+    '<<',
+    '>>',
+    'if',
+    'else',
+    'elsif',
+    'unless',
+    'case',
+    'when',
+    'for',
+    'while',
+    'until',
+    'do',
+    'begin',
+    'end',
+    'return',
+    'raise',
+    'break',
+    'next',
+    'redo',
+    'retry',
+    'rescue',
+    'ensure',
+    'yield',
+    'def',
+    'class',
+    'module',
+    '.',
+    ',',
+    ':',
+    '::',
+    '=>',
+    '->',
+  ]),
+  operandLeafTypes: new Set([
+    'identifier',
+    'constant',
+    'instance_variable',
+    'class_variable',
+    'global_variable',
+    'integer',
+    'float',
+    'string_content',
+    'symbol',
+    'true',
+    'false',
+    'nil',
+    'self',
+  ]),
+  compoundOperators: new Set(['call', 'element_reference']),
+  skipTypes: new Set([]),
+};
+
+// ─── CFG ──────────────────────────────────────────────────────────────────
+
+export const cfg = makeCfgRules({
+  ifNode: 'if',
+  elifNode: 'elsif',
+  elseClause: 'else',
+  forNodes: new Set(['for']),
+  whileNode: 'while',
+  unlessNode: 'unless',
+  untilNode: 'until',
+  switchNode: 'case',
+  caseNode: 'when',
+  defaultNode: 'else',
+  tryNode: 'begin',
+  catchNode: 'rescue',
+  finallyNode: 'ensure',
+  returnNode: 'return',
+  breakNode: 'break',
+  continueNode: 'next',
+  blockNodes: new Set(['then', 'do', 'body_statement']),
+  functionNodes: new Set(['method', 'singleton_method']),
+});
+
+// ─── Dataflow ─────────────────────────────────────────────────────────────
+
+export const dataflow = makeDataflowRules({
+  functionNodes: new Set(['method', 'singleton_method', 'lambda']),
+  paramListField: 'parameters',
+  returnNode: 'return',
+  varDeclaratorNode: null,
+  assignmentNode: 'assignment',
+  assignLeftField: 'left',
+  assignRightField: 'right',
+  callNode: 'call',
+  callFunctionField: 'method',
+  callArgsField: 'arguments',
+  spreadType: 'splat_parameter',
+  memberNode: 'call',
+  memberObjectField: 'receiver',
+  memberPropertyField: 'method',
+  mutatingMethods: new Set([
+    'push',
+    'pop',
+    'shift',
+    'unshift',
+    'delete',
+    'clear',
+    'sort!',
+    'reverse!',
+    'map!',
+    'select!',
+    'reject!',
+    'compact!',
+    'flatten!',
+    'concat',
+    'replace',
+    'insert',
+  ]),
+  extractParamName(node) {
+    if (node.type === 'identifier') return [node.text];
+    if (
+      node.type === 'optional_parameter' ||
+      node.type === 'keyword_parameter' ||
+      node.type === 'splat_parameter' ||
+      node.type === 'hash_splat_parameter'
+    ) {
+      const nameNode = node.childForFieldName('name');
+      return nameNode ? [nameNode.text] : null;
+    }
+    return null;
+  },
+});
+
+// ─── AST Node Types ───────────────────────────────────────────────────────
+
+export const astTypes = null;

package/src/ast-analysis/rules/rust.js

@@ -0,0 +1,173 @@
+/**
+ * Rust — AST analysis rules.
+ */
+
+import { makeCfgRules, makeDataflowRules } from '../shared.js';
+
+// ─── Complexity ───────────────────────────────────────────────────────────
+
+export const complexity = {
+  branchNodes: new Set([
+    'if_expression',
+    'else_clause',
+    'for_expression',
+    'while_expression',
+    'loop_expression',
+    'if_let_expression',
+    'while_let_expression',
+    'match_expression',
+  ]),
+  caseNodes: new Set(['match_arm']),
+  logicalOperators: new Set(['&&', '||']),
+  logicalNodeType: 'binary_expression',
+  optionalChainType: null,
+  nestingNodes: new Set([
+    'if_expression',
+    'for_expression',
+    'while_expression',
+    'loop_expression',
+    'if_let_expression',
+    'while_let_expression',
+    'match_expression',
+  ]),
+  functionNodes: new Set(['function_item', 'closure_expression']),
+  ifNodeType: 'if_expression',
+  elseNodeType: 'else_clause',
+  elifNodeType: null,
+  elseViaAlternative: false,
+  switchLikeNodes: new Set(['match_expression']),
+};
+
+// ─── Halstead ─────────────────────────────────────────────────────────────
+
+export const halstead = {
+  operatorLeafTypes: new Set([
+    '+',
+    '-',
+    '*',
+    '/',
+    '%',
+    '=',
+    '+=',
+    '-=',
+    '*=',
+    '/=',
+    '%=',
+    '&=',
+    '|=',
+    '^=',
+    '<<=',
+    '>>=',
+    '==',
+    '!=',
+    '<',
+    '>',
+    '<=',
+    '>=',
+    '&&',
+    '||',
+    '!',
+    '&',
+    '|',
+    '^',
+    '<<',
+    '>>',
+    'if',
+    'else',
+    'for',
+    'while',
+    'loop',
+    'match',
+    'return',
+    'break',
+    'continue',
+    'let',
+    'mut',
+    'ref',
+    'as',
+    'in',
+    'move',
+    'fn',
+    'struct',
+    'enum',
+    'trait',
+    'impl',
+    'pub',
+    'mod',
+    'use',
+    '.',
+    ',',
+    ';',
+    ':',
+    '::',
+    '=>',
+    '->',
+    '?',
+  ]),
+  operandLeafTypes: new Set([
+    'identifier',
+    'field_identifier',
+    'type_identifier',
+    'integer_literal',
+    'float_literal',
+    'string_content',
+    'char_literal',
+    'true',
+    'false',
+    'self',
+    'Self',
+  ]),
+  compoundOperators: new Set(['call_expression', 'index_expression', 'field_expression']),
+  skipTypes: new Set([]),
+};
+
+// ─── CFG ──────────────────────────────────────────────────────────────────
+
+export const cfg = makeCfgRules({
+  ifNode: 'if_expression',
+  ifNodes: new Set(['if_let_expression']),
+  elseClause: 'else_clause',
+  forNodes: new Set(['for_expression']),
+  whileNode: 'while_expression',
+  whileNodes: new Set(['while_let_expression']),
+  infiniteLoopNode: 'loop_expression',
+  switchNode: 'match_expression',
+  caseNode: 'match_arm',
+  returnNode: 'return_expression',
+  breakNode: 'break_expression',
+  continueNode: 'continue_expression',
+  blockNode: 'block',
+  functionNodes: new Set(['function_item', 'closure_expression']),
+});
+
+// ─── Dataflow ─────────────────────────────────────────────────────────────
+
+export const dataflow = makeDataflowRules({
+  functionNodes: new Set(['function_item', 'closure_expression']),
+  returnNode: 'return_expression',
+  varDeclaratorNode: 'let_declaration',
+  varNameField: 'pattern',
+  varValueField: 'value',
+  assignmentNode: 'assignment_expression',
+  callNode: 'call_expression',
+  callFunctionField: 'function',
+  callArgsField: 'arguments',
+  memberNode: 'field_expression',
+  memberObjectField: 'value',
+  memberPropertyField: 'field',
+  awaitNode: 'await_expression',
+  mutatingMethods: new Set(['push', 'pop', 'insert', 'remove', 'clear', 'sort', 'reverse']),
+  extractParamName(node) {
+    if (node.type === 'parameter') {
+      const pat = node.childForFieldName('pattern');
+      if (pat?.type === 'identifier') return [pat.text];
+      return null;
+    }
+    if (node.type === 'identifier') return [node.text];
+    return null;
+  },
+});
+
+// ─── AST Node Types ───────────────────────────────────────────────────────
+
+export const astTypes = null;

package/src/ast-analysis/shared.js

@@ -0,0 +1,223 @@
+/**
+ * Shared utilities for AST analysis modules (complexity, CFG, dataflow, AST nodes).
+ */
+
+import { LANGUAGE_REGISTRY } from '../parser.js';
+
+// ─── Generic Rule Factory ─────────────────────────────────────────────────
+
+/**
+ * Merge defaults with overrides, validating that all keys are known.
+ *
+ * @param {object} defaults - Default rule values (defines the valid key set)
+ * @param {object} overrides - Language-specific overrides
+ * @param {string} label - Label for error messages (e.g. "CFG", "Dataflow")
+ * @returns {object} Merged rules
+ */
+export function makeRules(defaults, overrides, label) {
+  const validKeys = new Set(Object.keys(defaults));
+  for (const key of Object.keys(overrides)) {
+    if (!validKeys.has(key)) {
+      throw new Error(`${label} rules: unknown key "${key}"`);
+    }
+  }
+  return { ...defaults, ...overrides };
+}
+
+// ─── CFG Defaults + Factory ───────────────────────────────────────────────
+
+export const CFG_DEFAULTS = {
+  ifNode: null,
+  ifNodes: null,
+  elifNode: null,
+  elseClause: null,
+  elseViaAlternative: false,
+  ifConsequentField: null,
+  forNodes: new Set(),
+  whileNode: null,
+  whileNodes: null,
+  doNode: null,
+  infiniteLoopNode: null,
+  unlessNode: null,
+  untilNode: null,
+  switchNode: null,
+  switchNodes: null,
+  caseNode: null,
+  caseNodes: null,
+  defaultNode: null,
+  tryNode: null,
+  catchNode: null,
+  finallyNode: null,
+  returnNode: null,
+  throwNode: null,
+  breakNode: null,
+  continueNode: null,
+  blockNode: null,
+  blockNodes: null,
+  labeledNode: null,
+  functionNodes: new Set(),
+};
+
+export function makeCfgRules(overrides) {
+  const rules = makeRules(CFG_DEFAULTS, overrides, 'CFG');
+  if (!(rules.functionNodes instanceof Set) || rules.functionNodes.size === 0) {
+    throw new Error('CFG rules: functionNodes must be a non-empty Set');
+  }
+  if (!(rules.forNodes instanceof Set)) {
+    throw new Error('CFG rules: forNodes must be a Set');
+  }
+  return rules;
+}
+
+// ─── Dataflow Defaults + Factory ──────────────────────────────────────────
+
+export const DATAFLOW_DEFAULTS = {
+  // Scope entry
+  functionNodes: new Set(), // REQUIRED: non-empty
+
+  // Function name extraction
+  nameField: 'name',
+  varAssignedFnParent: null, // parent type for `const fn = ...` (JS only)
+  assignmentFnParent: null, // parent type for `x = function...` (JS only)
+  pairFnParent: null, // parent type for `{ key: function }` (JS only)
+
+  // Parameters
+  paramListField: 'parameters',
+  paramIdentifier: 'identifier',
+  paramWrapperTypes: new Set(),
+  defaultParamType: null,
+  restParamType: null,
+  objectDestructType: null,
+  arrayDestructType: null,
+  shorthandPropPattern: null,
+  pairPatternType: null,
+  extractParamName: null, // override: (node) => string[]
+
+  // Return
+  returnNode: null,
+
+  // Variable declarations
+  varDeclaratorNode: null,
+  varDeclaratorNodes: null,
+  varNameField: 'name',
+  varValueField: 'value',
+  assignmentNode: null,
+  assignLeftField: 'left',
+  assignRightField: 'right',
+
+  // Calls
+  callNode: null,
+  callNodes: null,
+  callFunctionField: 'function',
+  callArgsField: 'arguments',
+  spreadType: null,
+
+  // Member access
+  memberNode: null,
+  memberObjectField: 'object',
+  memberPropertyField: 'property',
+  optionalChainNode: null,
+
+  // Await
+  awaitNode: null,
+
+  // Mutation
+  mutatingMethods: new Set(),
+  expressionStmtNode: 'expression_statement',
+  callObjectField: null, // Java: combined call+member has [object] field on call node
+
+  // Structural wrappers
+  expressionListType: null, // Go: expression_list wraps LHS/RHS of short_var_declaration
+  equalsClauseType: null, // C#: equals_value_clause wraps variable initializer
+  argumentWrapperType: null, // PHP: individual args wrapped in 'argument' nodes
+  extraIdentifierTypes: null, // Set of additional identifier-like types (PHP: variable_name, name)
+};
+
+export function makeDataflowRules(overrides) {
+  const rules = makeRules(DATAFLOW_DEFAULTS, overrides, 'Dataflow');
+  if (!(rules.functionNodes instanceof Set) || rules.functionNodes.size === 0) {
+    throw new Error('Dataflow rules: functionNodes must be a non-empty Set');
+  }
+  return rules;
+}
+
+// ─── AST Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Find the function body node in a parse tree that matches a given line range.
+ */
+export function findFunctionNode(rootNode, startLine, _endLine, rules) {
+  // tree-sitter lines are 0-indexed
+  const targetStart = startLine - 1;
+
+  let best = null;
+
+  function search(node) {
+    const nodeStart = node.startPosition.row;
+    const nodeEnd = node.endPosition.row;
+
+    // Prune branches outside range
+    if (nodeEnd < targetStart || nodeStart > targetStart + 1) return;
+
+    if (rules.functionNodes.has(node.type) && nodeStart === targetStart) {
+      // Found a function node at the right position — pick it
+      if (!best || nodeEnd - nodeStart < best.endPosition.row - best.startPosition.row) {
+        best = node;
+      }
+    }
+
+    for (let i = 0; i < node.childCount; i++) {
+      search(node.child(i));
+    }
+  }
+
+  search(rootNode);
+  return best;
+}
+
+/**
+ * Truncate a string to a maximum length, appending an ellipsis if truncated.
+ *
+ * @param {string} str - Input string
+ * @param {number} [max=200] - Maximum length
+ * @returns {string}
+ */
+export function truncate(str, max = 200) {
+  if (!str) return '';
+  return str.length > max ? `${str.slice(0, max)}…` : str;
+}
+
+// ─── Extension / Language Mapping ─────────────────────────────────────────
+
+/**
+ * Build a Map from file extension → language ID using the parser registry.
+ *
+ * @param {Iterable} [registry=LANGUAGE_REGISTRY] - Language registry entries
+ * @returns {Map<string, string>}
+ */
+export function buildExtToLangMap(registry = LANGUAGE_REGISTRY) {
+  const map = new Map();
+  for (const entry of registry) {
+    for (const ext of entry.extensions) {
+      map.set(ext, entry.id);
+    }
+  }
+  return map;
+}
+
+/**
+ * Build a Set of file extensions for languages that have entries in the given rules Map.
+ *
+ * @param {Map<string, any>} rulesMap - e.g. COMPLEXITY_RULES, CFG_RULES
+ * @param {Iterable} [registry=LANGUAGE_REGISTRY] - Language registry entries
+ * @returns {Set<string>}
+ */
+export function buildExtensionSet(rulesMap, registry = LANGUAGE_REGISTRY) {
+  const extensions = new Set();
+  for (const entry of registry) {
+    if (rulesMap.has(entry.id)) {
+      for (const ext of entry.extensions) extensions.add(ext);
+    }
+  }
+  return extensions;
+}

package/src/ast.js

@@ -7,10 +7,13 @@
  */
 
 import path from 'node:path';
+import { AST_TYPE_MAPS } from './ast-analysis/rules/index.js';
+import { buildExtensionSet } from './ast-analysis/shared.js';
 import { openReadonlyOrFail } from './db.js';
 import { debug } from './logger.js';
-import { paginateResult, printNdjson } from './paginate.js';
-import { LANGUAGE_REGISTRY } from './parser.js';
+import { paginateResult } from './paginate.js';
+
+import { outputResult } from './result-formatter.js';
 
 // ─── Constants ────────────────────────────────────────────────────────
 
@@ -28,23 +31,11 @@ const KIND_ICONS = {
 /** Max length for the `text` column. */
 const TEXT_MAX = 200;
 
-/** tree-sitter node types that map to our AST node kinds (JS/TS/TSX). */
-const JS_TS_AST_TYPES = {
-  new_expression: 'new',
-  throw_statement: 'throw',
-  await_expression: 'await',
-  string: 'string',
-  template_string: 'string',
-  regex: 'regex',
-};
+/** tree-sitter node types that map to our AST node kinds — imported from rules. */
+const JS_TS_AST_TYPES = AST_TYPE_MAPS.get('javascript');
 
 /** Extensions that support full AST walk (new/throw/await/string/regex). */
-const WALK_EXTENSIONS = new Set();
-for (const lang of Object.values(LANGUAGE_REGISTRY)) {
-  if (['javascript', 'typescript', 'tsx'].includes(lang.id)) {
-    for (const ext of lang.extensions) WALK_EXTENSIONS.add(ext);
-  }
-}
+const WALK_EXTENSIONS = buildExtensionSet(AST_TYPE_MAPS);
 
 // ─── Helpers ──────────────────────────────────────────────────────────
 
@@ -351,8 +342,12 @@ export function astQueryData(pattern, customDbPath, opts = {}) {
     ORDER BY a.file, a.line
   `;
 
-  const rows = db.prepare(sql).all(...params);
-  db.close();
+  let rows;
+  try {
+    rows = db.prepare(sql).all(...params);
+  } finally {
+    db.close();
+  }
 
   const results = rows.map((r) => ({
     kind: r.kind,
@@ -382,15 +377,7 @@ export function astQueryData(pattern, customDbPath, opts = {}) {
 export function astQuery(pattern, customDbPath, opts = {}) {
   const data = astQueryData(pattern, customDbPath, opts);
 
-  if (opts.ndjson) {
-    printNdjson(data, 'results');
-    return;
-  }
-
-  if (opts.json) {
-    console.log(JSON.stringify(data, null, 2));
-    return;
-  }
+  if (outputResult(data, 'results', opts)) return;
 
   // Human-readable output
   if (data.results.length === 0) {

package/src/audit.js

@@ -10,7 +10,9 @@ import path from 'node:path';
 import { loadConfig } from './config.js';
 import { openReadonlyOrFail } from './db.js';
 import { RULE_DEFS } from './manifesto.js';
-import { explainData, isTestFile, kindIcon } from './queries.js';
+import { explainData, kindIcon } from './queries.js';
+import { outputResult } from './result-formatter.js';
+import { isTestFile } from './test-filter.js';
 
 // ─── Threshold resolution ───────────────────────────────────────────
 
@@ -340,10 +342,7 @@ function defaultHealth() {
 export function audit(target, customDbPath, opts = {}) {
   const data = auditData(target, customDbPath, opts);
 
-  if (opts.json) {
-    console.log(JSON.stringify(data, null, 2));
-    return;
-  }
+  if (outputResult(data, null, opts)) return;
 
   if (data.functions.length === 0) {
     console.log(`No ${data.kind === 'file' ? 'file' : 'function/symbol'} matching "${target}"`);

package/src/boundaries.js

@@ -1,5 +1,5 @@
 import { debug } from './logger.js';
-import { isTestFile } from './queries.js';
+import { isTestFile } from './test-filter.js';
 
 // ─── Glob-to-Regex ───────────────────────────────────────────────────