@optave/codegraph 3.3.0 → 3.4.0

package/src/ast-analysis/rules/{java.js → java.ts}

@@ -1,12 +1,14 @@
-/**
- * Java — AST analysis rules.
- */
-
+import type {
+  CfgRulesConfig,
+  ComplexityRules,
+  DataflowRulesConfig,
+  HalsteadRules,
+} from '../../types.js';
 import { makeCfgRules, makeDataflowRules } from '../shared.js';
 
 // ─── Complexity ───────────────────────────────────────────────────────────
 
-export const complexity = {
+export const complexity: ComplexityRules = {
   branchNodes: new Set([
     'if_statement',
     'for_statement',
@@ -40,7 +42,7 @@ export const complexity = {
 
 // ─── Halstead ─────────────────────────────────────────────────────────────
 
-export const halstead = {
+export const halstead: HalsteadRules = {
   operatorLeafTypes: new Set([
     '+',
     '-',
@@ -123,7 +125,7 @@ export const halstead = {
 
 // ─── CFG ──────────────────────────────────────────────────────────────────
 
-export const cfg = makeCfgRules({
+export const cfg: CfgRulesConfig = makeCfgRules({
   ifNode: 'if_statement',
   elseViaAlternative: true,
   forNodes: new Set(['for_statement', 'enhanced_for_statement']),
@@ -146,7 +148,7 @@ export const cfg = makeCfgRules({
 
 // ─── Dataflow ─────────────────────────────────────────────────────────────
 
-export const dataflow = makeDataflowRules({
+export const dataflow: DataflowRulesConfig = makeDataflowRules({
   functionNodes: new Set(['method_declaration', 'constructor_declaration', 'lambda_expression']),
   returnNode: 'return_statement',
   varDeclaratorNode: 'variable_declarator',
@@ -172,4 +174,4 @@ export const dataflow = makeDataflowRules({
 
 // ─── AST Node Types ───────────────────────────────────────────────────────
 
-export const astTypes = null;
+export const astTypes: Record<string, string> | null = null;

package/src/ast-analysis/rules/{javascript.js → javascript.ts}

@@ -1,14 +1,14 @@
-/**
- * JavaScript / TypeScript / TSX — AST analysis rules.
- *
- * Shared across: javascript, typescript, tsx language IDs.
- */
-
+import type {
+  CfgRulesConfig,
+  ComplexityRules,
+  DataflowRulesConfig,
+  HalsteadRules,
+} from '../../types.js';
 import { makeCfgRules, makeDataflowRules } from '../shared.js';
 
 // ─── Complexity ───────────────────────────────────────────────────────────
 
-export const complexity = {
+export const complexity: ComplexityRules = {
   branchNodes: new Set([
     'if_statement',
     'else_clause',
@@ -51,7 +51,7 @@ export const complexity = {
 
 // ─── Halstead ─────────────────────────────────────────────────────────────
 
-export const halstead = {
+export const halstead: HalsteadRules = {
   operatorLeafTypes: new Set([
     // Arithmetic
     '+',
@@ -160,7 +160,7 @@ export const halstead = {
 
 // ─── CFG ──────────────────────────────────────────────────────────────────
 
-export const cfg = makeCfgRules({
+export const cfg: CfgRulesConfig = makeCfgRules({
   ifNode: 'if_statement',
   elseClause: 'else_clause',
   forNodes: new Set(['for_statement', 'for_in_statement']),
@@ -205,7 +205,7 @@ const JS_TS_MUTATING = new Set([
   'clear',
 ]);
 
-export const dataflow = makeDataflowRules({
+export const dataflow: DataflowRulesConfig = makeDataflowRules({
   functionNodes: new Set([
     'function_declaration',
     'method_definition',
@@ -236,7 +236,7 @@ export const dataflow = makeDataflowRules({
 
 // ─── AST Node Types ───────────────────────────────────────────────────────
 
-export const astTypes = {
+export const astTypes: Record<string, string> | null = {
   new_expression: 'new',
   throw_statement: 'throw',
   await_expression: 'await',

package/src/ast-analysis/rules/{php.js → php.ts}

@@ -1,12 +1,14 @@
-/**
- * PHP — AST analysis rules.
- */
-
+import type {
+  CfgRulesConfig,
+  ComplexityRules,
+  DataflowRulesConfig,
+  HalsteadRules,
+} from '../../types.js';
 import { makeCfgRules, makeDataflowRules } from '../shared.js';
 
 // ─── Complexity ───────────────────────────────────────────────────────────
 
-export const complexity = {
+export const complexity: ComplexityRules = {
   branchNodes: new Set([
     'if_statement',
     'else_if_clause',
@@ -48,7 +50,7 @@ export const complexity = {
 
 // ─── Halstead ─────────────────────────────────────────────────────────────
 
-export const halstead = {
+export const halstead: HalsteadRules = {
   operatorLeafTypes: new Set([
     '+',
     '-',
@@ -147,7 +149,7 @@ export const halstead = {
 
 // ─── CFG ──────────────────────────────────────────────────────────────────
 
-export const cfg = makeCfgRules({
+export const cfg: CfgRulesConfig = makeCfgRules({
   ifNode: 'if_statement',
   elifNode: 'else_if_clause',
   elseClause: 'else_clause',
@@ -176,7 +178,7 @@ export const cfg = makeCfgRules({
 
 // ─── Dataflow ─────────────────────────────────────────────────────────────
 
-export const dataflow = makeDataflowRules({
+export const dataflow: DataflowRulesConfig = makeDataflowRules({
   functionNodes: new Set([
     'function_definition',
     'method_declaration',
@@ -216,4 +218,4 @@ export const dataflow = makeDataflowRules({
 
 // ─── AST Node Types ───────────────────────────────────────────────────────
 
-export const astTypes = null;
+export const astTypes: Record<string, string> | null = null;

package/src/ast-analysis/rules/{python.js → python.ts}

@@ -1,12 +1,14 @@
-/**
- * Python — AST analysis rules.
- */
-
+import type {
+  CfgRulesConfig,
+  ComplexityRules,
+  DataflowRulesConfig,
+  HalsteadRules,
+} from '../../types.js';
 import { makeCfgRules, makeDataflowRules } from '../shared.js';
 
 // ─── Complexity ───────────────────────────────────────────────────────────
 
-export const complexity = {
+export const complexity: ComplexityRules = {
   branchNodes: new Set([
     'if_statement',
     'elif_clause',
@@ -38,7 +40,7 @@ export const complexity = {
 
 // ─── Halstead ─────────────────────────────────────────────────────────────
 
-export const halstead = {
+export const halstead: HalsteadRules = {
   operatorLeafTypes: new Set([
     '+',
     '-',
@@ -119,7 +121,7 @@ export const halstead = {
 
 // ─── CFG ──────────────────────────────────────────────────────────────────
 
-export const cfg = makeCfgRules({
+export const cfg: CfgRulesConfig = makeCfgRules({
   ifNode: 'if_statement',
   elifNode: 'elif_clause',
   elseClause: 'else_clause',
@@ -140,7 +142,7 @@ export const cfg = makeCfgRules({
 
 // ─── Dataflow ─────────────────────────────────────────────────────────────
 
-export const dataflow = makeDataflowRules({
+export const dataflow: DataflowRulesConfig = makeDataflowRules({
   functionNodes: new Set(['function_definition', 'lambda']),
   defaultParamType: 'default_parameter',
   restParamType: 'list_splat_pattern',
@@ -193,4 +195,4 @@ export const dataflow = makeDataflowRules({
 
 // ─── AST Node Types ───────────────────────────────────────────────────────
 
-export const astTypes = null;
+export const astTypes: Record<string, string> | null = null;

package/src/ast-analysis/rules/{ruby.js → ruby.ts}

@@ -1,12 +1,14 @@
-/**
- * Ruby — AST analysis rules.
- */
-
+import type {
+  CfgRulesConfig,
+  ComplexityRules,
+  DataflowRulesConfig,
+  HalsteadRules,
+} from '../../types.js';
 import { makeCfgRules, makeDataflowRules } from '../shared.js';
 
 // ─── Complexity ───────────────────────────────────────────────────────────
 
-export const complexity = {
+export const complexity: ComplexityRules = {
   branchNodes: new Set([
     'if',
     'elsif',
@@ -34,7 +36,7 @@ export const complexity = {
 
 // ─── Halstead ─────────────────────────────────────────────────────────────
 
-export const halstead = {
+export const halstead: HalsteadRules = {
   operatorLeafTypes: new Set([
     '+',
     '-',
@@ -128,7 +130,7 @@ export const halstead = {
 
 // ─── CFG ──────────────────────────────────────────────────────────────────
 
-export const cfg = makeCfgRules({
+export const cfg: CfgRulesConfig = makeCfgRules({
   ifNode: 'if',
   elifNode: 'elsif',
   elseClause: 'else',
@@ -151,7 +153,7 @@ export const cfg = makeCfgRules({
 
 // ─── Dataflow ─────────────────────────────────────────────────────────────
 
-export const dataflow = makeDataflowRules({
+export const dataflow: DataflowRulesConfig = makeDataflowRules({
   functionNodes: new Set(['method', 'singleton_method', 'lambda']),
   paramListField: 'parameters',
   returnNode: 'return',
@@ -201,4 +203,4 @@ export const dataflow = makeDataflowRules({
 
 // ─── AST Node Types ───────────────────────────────────────────────────────
 
-export const astTypes = null;
+export const astTypes: Record<string, string> | null = null;

package/src/ast-analysis/rules/{rust.js → rust.ts}

@@ -1,12 +1,14 @@
-/**
- * Rust — AST analysis rules.
- */
-
+import type {
+  CfgRulesConfig,
+  ComplexityRules,
+  DataflowRulesConfig,
+  HalsteadRules,
+} from '../../types.js';
 import { makeCfgRules, makeDataflowRules } from '../shared.js';
 
 // ─── Complexity ───────────────────────────────────────────────────────────
 
-export const complexity = {
+export const complexity: ComplexityRules = {
   branchNodes: new Set([
     'if_expression',
     'else_clause',
@@ -40,7 +42,7 @@ export const complexity = {
 
 // ─── Halstead ─────────────────────────────────────────────────────────────
 
-export const halstead = {
+export const halstead: HalsteadRules = {
   operatorLeafTypes: new Set([
     '+',
     '-',
@@ -123,7 +125,7 @@ export const halstead = {
 
 // ─── CFG ──────────────────────────────────────────────────────────────────
 
-export const cfg = makeCfgRules({
+export const cfg: CfgRulesConfig = makeCfgRules({
   ifNode: 'if_expression',
   ifNodes: new Set(['if_let_expression']),
   elseClause: 'else_clause',
@@ -142,7 +144,7 @@ export const cfg = makeCfgRules({
 
 // ─── Dataflow ─────────────────────────────────────────────────────────────
 
-export const dataflow = makeDataflowRules({
+export const dataflow: DataflowRulesConfig = makeDataflowRules({
   functionNodes: new Set(['function_item', 'closure_expression']),
   returnNode: 'return_expression',
   varDeclaratorNode: 'let_declaration',
@@ -170,4 +172,4 @@ export const dataflow = makeDataflowRules({
 
 // ─── AST Node Types ───────────────────────────────────────────────────────
 
-export const astTypes = null;
+export const astTypes: Record<string, string> | null = null;

package/src/ast-analysis/{shared.js → shared.ts}

@@ -1,21 +1,19 @@
-/**
- * Shared utilities for AST analysis modules (complexity, CFG, dataflow, AST nodes).
- */
-
 import { LANGUAGE_REGISTRY } from '../domain/parser.js';
 import { ConfigError } from '../shared/errors.js';
+import type {
+  CfgRulesConfig,
+  DataflowRulesConfig,
+  LanguageRegistryEntry,
+  TreeSitterNode,
+} from '../types.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) {
+export function makeRules(
+  defaults: Record<string, unknown>,
+  overrides: Record<string, unknown>,
+  label: string,
+): Record<string, unknown> {
   const validKeys = new Set(Object.keys(defaults));
   for (const key of Object.keys(overrides)) {
     if (!validKeys.has(key)) {
@@ -27,7 +25,7 @@ export function makeRules(defaults, overrides, label) {
 
 // ─── CFG Defaults + Factory ───────────────────────────────────────────────
 
-export const CFG_DEFAULTS = {
+export const CFG_DEFAULTS: CfgRulesConfig = {
   ifNode: null,
   ifNodes: null,
   elifNode: null,
@@ -59,8 +57,12 @@ export const CFG_DEFAULTS = {
   functionNodes: new Set(),
 };
 
-export function makeCfgRules(overrides) {
-  const rules = makeRules(CFG_DEFAULTS, overrides, 'CFG');
+export function makeCfgRules(overrides: Partial<CfgRulesConfig>): CfgRulesConfig {
+  const rules = makeRules(
+    CFG_DEFAULTS as unknown as Record<string, unknown>,
+    overrides as unknown as Record<string, unknown>,
+    'CFG',
+  ) as unknown as CfgRulesConfig;
   if (!(rules.functionNodes instanceof Set) || rules.functionNodes.size === 0) {
     throw new ConfigError('CFG rules: functionNodes must be a non-empty Set');
   }
@@ -72,7 +74,7 @@ export function makeCfgRules(overrides) {
 
 // ─── Dataflow Defaults + Factory ──────────────────────────────────────────
 
-export const DATAFLOW_DEFAULTS = {
+export const DATAFLOW_DEFAULTS: DataflowRulesConfig = {
   // Scope entry
   functionNodes: new Set(), // REQUIRED: non-empty
 
@@ -134,8 +136,12 @@ export const DATAFLOW_DEFAULTS = {
   extraIdentifierTypes: null, // Set of additional identifier-like types (PHP: variable_name, name)
 };
 
-export function makeDataflowRules(overrides) {
-  const rules = makeRules(DATAFLOW_DEFAULTS, overrides, 'Dataflow');
+export function makeDataflowRules(overrides: Partial<DataflowRulesConfig>): DataflowRulesConfig {
+  const rules = makeRules(
+    DATAFLOW_DEFAULTS as unknown as Record<string, unknown>,
+    overrides as unknown as Record<string, unknown>,
+    'Dataflow',
+  ) as unknown as DataflowRulesConfig;
   if (!(rules.functionNodes instanceof Set) || rules.functionNodes.size === 0) {
     throw new ConfigError('Dataflow rules: functionNodes must be a non-empty Set');
   }
@@ -144,16 +150,18 @@ export function makeDataflowRules(overrides) {
 
 // ─── AST Helpers ──────────────────────────────────────────────────────────
 
-/**
- * Find the function body node in a parse tree that matches a given line range.
- */
-export function findFunctionNode(rootNode, startLine, _endLine, rules) {
+export function findFunctionNode(
+  rootNode: TreeSitterNode,
+  startLine: number,
+  _endLine: number,
+  rules: { functionNodes: Set<string> },
+): TreeSitterNode | null {
   // tree-sitter lines are 0-indexed
   const targetStart = startLine - 1;
 
-  let best = null;
+  let best: TreeSitterNode | null = null;
 
-  function search(node) {
+  function search(node: TreeSitterNode): void {
     const nodeStart = node.startPosition.row;
     const nodeEnd = node.endPosition.row;
 
@@ -168,7 +176,8 @@ export function findFunctionNode(rootNode, startLine, _endLine, rules) {
     }
 
     for (let i = 0; i < node.childCount; i++) {
-      search(node.child(i));
+      // biome-ignore lint/style/noNonNullAssertion: tree-sitter child(i) within childCount is always non-null
+      search(node.child(i)!);
     }
   }
 
@@ -178,14 +187,10 @@ export function findFunctionNode(rootNode, startLine, _endLine, rules) {
 
 // ─── 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();
+export function buildExtToLangMap(
+  registry: LanguageRegistryEntry[] = LANGUAGE_REGISTRY as unknown as LanguageRegistryEntry[],
+): Map<string, string> {
+  const map = new Map<string, string>();
   for (const entry of registry) {
     for (const ext of entry.extensions) {
       map.set(ext, entry.id);
@@ -194,15 +199,11 @@ export function buildExtToLangMap(registry = LANGUAGE_REGISTRY) {
   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();
+export function buildExtensionSet(
+  rulesMap: Map<string, unknown>,
+  registry: LanguageRegistryEntry[] = LANGUAGE_REGISTRY as unknown as LanguageRegistryEntry[],
+): Set<string> {
+  const extensions = new Set<string>();
   for (const entry of registry) {
     if (rulesMap.has(entry.id)) {
       for (const ext of entry.extensions) extensions.add(ext);

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

@@ -4,10 +4,40 @@
  * 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;
+  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, max = 120) {
+export function truncate(str: string, max = 120): string {
   if (!str) return '';
   return str.length > max ? `${str.slice(0, max)}…` : str;
 }
@@ -15,7 +45,7 @@ export function truncate(str, max = 120) {
 /**
  * Get the name of a function node from the AST using rules.
  */
-export function functionName(fnNode, rules) {
+export function functionName(fnNode: TreeSitterNode | null, rules: LanguageRules): string | null {
   if (!fnNode) return null;
   const nameNode = fnNode.childForFieldName(rules.nameField);
   if (nameNode) return nameNode.text;
@@ -31,7 +61,7 @@ export function functionName(fnNode, rules) {
       return keyNode ? keyNode.text : null;
     }
     if (rules.assignmentFnParent && parent.type === rules.assignmentFnParent) {
-      const left = parent.childForFieldName(rules.assignLeftField);
+      const left = parent.childForFieldName(rules.assignLeftField!);
       return left ? left.text : null;
     }
   }
@@ -41,9 +71,12 @@ export function functionName(fnNode, rules) {
 /**
  * Extract parameter names and indices from a formal_parameters node.
  */
-export function extractParams(paramsNode, rules) {
+export function extractParams(
+  paramsNode: TreeSitterNode | null,
+  rules: LanguageRules,
+): ParamInfo[] {
   if (!paramsNode) return [];
-  const result = [];
+  const result: ParamInfo[] = [];
   let index = 0;
   for (const child of paramsNode.namedChildren) {
     const names = extractParamNames(child, rules);
@@ -58,7 +91,7 @@ export function extractParams(paramsNode, rules) {
 /**
  * Extract parameter names from a single parameter node.
  */
-export function extractParamNames(node, rules) {
+export function extractParamNames(node: TreeSitterNode | null, rules: LanguageRules): string[] {
   if (!node) return [];
   const t = node.type;
 
@@ -89,7 +122,7 @@ export function extractParamNames(node, rules) {
   }
 
   if (rules.objectDestructType && t === rules.objectDestructType) {
-    const names = [];
+    const names: string[] = [];
     for (const child of node.namedChildren) {
       if (rules.shorthandPropPattern && child.type === rules.shorthandPropPattern) {
         names.push(child.text);
@@ -104,7 +137,7 @@ export function extractParamNames(node, rules) {
   }
 
   if (rules.arrayDestructType && t === rules.arrayDestructType) {
-    const names = [];
+    const names: string[] = [];
     for (const child of node.namedChildren) {
       names.push(...extractParamNames(child, rules));
     }
@@ -117,7 +150,7 @@ export function extractParamNames(node, rules) {
 /**
  * Check if a node type is identifier-like for this language.
  */
-export function isIdent(nodeType, rules) {
+export function isIdent(nodeType: string, rules: LanguageRules): boolean {
   if (nodeType === 'identifier' || nodeType === rules.paramIdentifier) return true;
   return rules.extraIdentifierTypes ? rules.extraIdentifierTypes.has(nodeType) : false;
 }
@@ -125,7 +158,7 @@ export function isIdent(nodeType, rules) {
 /**
  * Resolve the name a call expression is calling using rules.
  */
-export function resolveCalleeName(callNode, 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');
@@ -153,7 +186,7 @@ export function resolveCalleeName(callNode, rules) {
 /**
  * Get the receiver (object) of a member expression using rules.
  */
-export function memberReceiver(memberExpr, 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;
@@ -164,7 +197,11 @@ export function memberReceiver(memberExpr, rules) {
 /**
  * Collect all identifier names referenced within a node.
  */
-export function collectIdentifiers(node, out, rules) {
+export function collectIdentifiers(
+  node: TreeSitterNode | null,
+  out: string[],
+  rules: LanguageRules,
+): void {
   if (!node) return;
   if (isIdent(node.type, rules)) {
     out.push(node.text);