@optave/codegraph 3.8.1 → 3.9.1

package/src/presentation/queries-cli/inspect.ts

@@ -182,6 +182,39 @@ interface InterfacesData {
   results: InterfacesResult[];
 }
 
+function renderWhereSymbolResults(results: WhereSymbolResult[]): void {
+  for (const r of results) {
+    const roleTag = r.role ? ` [${r.role}]` : '';
+    const tag = r.exported ? '  (exported)' : '';
+    console.log(`\n${kindIcon(r.kind)} ${r.name}${roleTag}  ${r.file}:${r.line}${tag}`);
+    if (r.uses.length > 0) {
+      const useStrs = r.uses.map((u) => `${u.file}:${u.line}`);
+      console.log(`  Used in: ${useStrs.join(', ')}`);
+    } else {
+      console.log('  No uses found');
+    }
+  }
+}
+
+function renderWhereFileResults(results: WhereFileResult[]): void {
+  for (const r of results) {
+    console.log(`\n# ${r.file}`);
+    if (r.symbols.length > 0) {
+      const symStrs = r.symbols.map((s) => `${s.name}:${s.line}`);
+      console.log(`  Symbols: ${symStrs.join(', ')}`);
+    }
+    if (r.imports.length > 0) {
+      console.log(`  Imports: ${r.imports.join(', ')}`);
+    }
+    if (r.importedBy.length > 0) {
+      console.log(`  Imported by: ${r.importedBy.join(', ')}`);
+    }
+    if (r.exported.length > 0) {
+      console.log(`  Exported: ${r.exported.join(', ')}`);
+    }
+  }
+}
+
 export function where(target: string, customDbPath: string, opts: OutputOpts = {}): void {
   const data = whereData(target, customDbPath, opts as Record<string, unknown>) as WhereData;
   if (outputResult(data as unknown as Record<string, unknown>, 'results', opts)) return;
@@ -196,34 +229,9 @@ export function where(target: string, customDbPath: string, opts: OutputOpts = {
   }
 
   if (data.mode === 'symbol') {
-    for (const r of data.results as WhereSymbolResult[]) {
-      const roleTag = r.role ? ` [${r.role}]` : '';
-      const tag = r.exported ? '  (exported)' : '';
-      console.log(`\n${kindIcon(r.kind)} ${r.name}${roleTag}  ${r.file}:${r.line}${tag}`);
-      if (r.uses.length > 0) {
-        const useStrs = r.uses.map((u) => `${u.file}:${u.line}`);
-        console.log(`  Used in: ${useStrs.join(', ')}`);
-      } else {
-        console.log('  No uses found');
-      }
-    }
+    renderWhereSymbolResults(data.results as WhereSymbolResult[]);
   } else {
-    for (const r of data.results as WhereFileResult[]) {
-      console.log(`\n# ${r.file}`);
-      if (r.symbols.length > 0) {
-        const symStrs = r.symbols.map((s) => `${s.name}:${s.line}`);
-        console.log(`  Symbols: ${symStrs.join(', ')}`);
-      }
-      if (r.imports.length > 0) {
-        console.log(`  Imports: ${r.imports.join(', ')}`);
-      }
-      if (r.importedBy.length > 0) {
-        console.log(`  Imported by: ${r.importedBy.join(', ')}`);
-      }
-      if (r.exported.length > 0) {
-        console.log(`  Exported: ${r.exported.join(', ')}`);
-      }
-    }
+    renderWhereFileResults(data.results as WhereFileResult[]);
   }
   console.log();
 }
@@ -402,6 +410,17 @@ function renderContextResult(r: ContextResult): void {
   }
 }
 
+function renderExplainSymbolList(label: string, symbols: ExplainSymbol[]): void {
+  if (symbols.length === 0) return;
+  console.log(`\n## ${label}`);
+  for (const s of symbols) {
+    const sig = s.signature?.params != null ? `(${s.signature.params})` : '';
+    const roleTag = s.role ? ` [${s.role}]` : '';
+    const summary = s.summary ? `  -- ${s.summary}` : '';
+    console.log(`  ${kindIcon(s.kind)} ${s.name}${sig}${roleTag} :${s.line}${summary}`);
+  }
+}
+
 function renderFileExplain(r: FileExplainResult): void {
   const publicCount = r.publicApi.length;
   const internalCount = r.internal.length;
@@ -418,25 +437,8 @@ function renderFileExplain(r: FileExplainResult): void {
     console.log(`  Imported by: ${r.importedBy.map((i) => i.file).join(', ')}`);
   }
 
-  if (r.publicApi.length > 0) {
-    console.log(`\n## Exported`);
-    for (const s of r.publicApi) {
-      const sig = s.signature?.params != null ? `(${s.signature.params})` : '';
-      const roleTag = s.role ? ` [${s.role}]` : '';
-      const summary = s.summary ? `  -- ${s.summary}` : '';
-      console.log(`  ${kindIcon(s.kind)} ${s.name}${sig}${roleTag} :${s.line}${summary}`);
-    }
-  }
-
-  if (r.internal.length > 0) {
-    console.log(`\n## Internal`);
-    for (const s of r.internal) {
-      const sig = s.signature?.params != null ? `(${s.signature.params})` : '';
-      const roleTag = s.role ? ` [${s.role}]` : '';
-      const summary = s.summary ? `  -- ${s.summary}` : '';
-      console.log(`  ${kindIcon(s.kind)} ${s.name}${sig}${roleTag} :${s.line}${summary}`);
-    }
-  }
+  renderExplainSymbolList('Exported', r.publicApi);
+  renderExplainSymbolList('Internal', r.internal);
 
   if (r.dataFlow.length > 0) {
     console.log(`\n## Data Flow`);

package/src/shared/file-utils.ts

@@ -45,56 +45,97 @@ interface ExtractSummaryOpts {
   summaryMaxChars?: number;
 }
 
-export function extractSummary(
-  fileLines: string[] | null,
-  line: number | undefined,
-  opts: ExtractSummaryOpts = {},
+/** Truncate text to maxChars, appending "..." if truncated. */
+function truncate(text: string, maxChars: number): string {
+  return text.length > maxChars ? `${text.slice(0, maxChars)}...` : text;
+}
+
+/** Try to extract a single-line comment (// or #) above the definition. */
+function extractSingleLineComment(
+  fileLines: string[],
+  idx: number,
+  scanLines: number,
+  maxChars: number,
 ): string | null {
-  if (!fileLines || !line || line <= 1) return null;
-  const idx = line - 2; // line above the definition (0-indexed)
-  const jsdocEndScanLines = opts.jsdocEndScanLines ?? 10;
-  const jsdocOpenScanLines = opts.jsdocOpenScanLines ?? 20;
-  const summaryMaxChars = opts.summaryMaxChars ?? 100;
-  // Scan up for JSDoc or comment
-  let jsdocEnd = -1;
-  for (let i = idx; i >= Math.max(0, idx - jsdocEndScanLines); i--) {
+  for (let i = idx; i >= Math.max(0, idx - scanLines); i--) {
     const trimmed = fileLines[i]!.trim();
-    if (trimmed.endsWith('*/')) {
-      jsdocEnd = i;
-      break;
-    }
+    if (trimmed.endsWith('*/')) return null; // hit a block comment — defer to JSDoc extractor
     if (trimmed.startsWith('//') || trimmed.startsWith('#')) {
-      // Single-line comment immediately above
       const text = trimmed
         .replace(/^\/\/\s*/, '')
         .replace(/^#\s*/, '')
         .trim();
-      return text.length > summaryMaxChars ? `${text.slice(0, summaryMaxChars)}...` : text;
+      return truncate(text, maxChars);
     }
-    if (trimmed !== '' && !trimmed.startsWith('*') && !trimmed.startsWith('/*')) break;
+    if (trimmed !== '' && !trimmed.startsWith('*') && !trimmed.startsWith('/*')) return null;
   }
-  if (jsdocEnd >= 0) {
-    // Find opening /**
-    for (let i = jsdocEnd; i >= Math.max(0, jsdocEnd - jsdocOpenScanLines); i--) {
-      if (fileLines[i]!.trim().startsWith('/**')) {
-        // Extract first non-tag, non-empty line
-        for (let j = i + 1; j <= jsdocEnd; j++) {
-          const docLine = fileLines[j]!.trim()
-            .replace(/^\*\s?/, '')
-            .trim();
-          if (docLine && !docLine.startsWith('@') && docLine !== '/' && docLine !== '*/') {
-            return docLine.length > summaryMaxChars
-              ? `${docLine.slice(0, summaryMaxChars)}...`
-              : docLine;
-          }
-        }
-        break;
+  return null;
+}
+
+/** Find the line index where a block comment (*​/) ends, scanning upward from idx. */
+function findJsdocEndLine(fileLines: string[], idx: number, scanLines: number): number {
+  for (let i = idx; i >= Math.max(0, idx - scanLines); i--) {
+    const trimmed = fileLines[i]!.trim();
+    if (trimmed.endsWith('*/')) return i;
+    if (
+      trimmed !== '' &&
+      !trimmed.startsWith('*') &&
+      !trimmed.startsWith('/*') &&
+      !trimmed.startsWith('//') &&
+      !trimmed.startsWith('#')
+    ) {
+      break;
+    }
+  }
+  return -1;
+}
+
+/** Extract the first description line from a JSDoc block ending at jsdocEnd. */
+function extractJsdocDescription(
+  fileLines: string[],
+  jsdocEnd: number,
+  openScanLines: number,
+  maxChars: number,
+): string | null {
+  for (let i = jsdocEnd; i >= Math.max(0, jsdocEnd - openScanLines); i--) {
+    if (!fileLines[i]!.trim().startsWith('/**')) continue;
+    for (let j = i + 1; j <= jsdocEnd; j++) {
+      const docLine = fileLines[j]!.trim()
+        .replace(/^\*\s?/, '')
+        .trim();
+      if (docLine && !docLine.startsWith('@') && docLine !== '/' && docLine !== '*/') {
+        return truncate(docLine, maxChars);
       }
     }
+    break;
   }
   return null;
 }
 
+export function extractSummary(
+  fileLines: string[] | null,
+  line: number | undefined,
+  opts: ExtractSummaryOpts = {},
+): string | null {
+  if (!fileLines || !line || line <= 1) return null;
+  const idx = line - 2; // line above the definition (0-indexed)
+  const jsdocEndScanLines = opts.jsdocEndScanLines ?? 10;
+  const jsdocOpenScanLines = opts.jsdocOpenScanLines ?? 20;
+  const summaryMaxChars = opts.summaryMaxChars ?? 100;
+
+  // Try single-line comment first
+  const singleLine = extractSingleLineComment(fileLines, idx, jsdocEndScanLines, summaryMaxChars);
+  if (singleLine) return singleLine;
+
+  // Try JSDoc block comment
+  const jsdocEnd = findJsdocEndLine(fileLines, idx, jsdocEndScanLines);
+  if (jsdocEnd >= 0) {
+    return extractJsdocDescription(fileLines, jsdocEnd, jsdocOpenScanLines, summaryMaxChars);
+  }
+
+  return null;
+}
+
 interface ExtractSignatureOpts {
   signatureGatherLines?: number;
 }
@@ -104,6 +145,38 @@ export interface Signature {
   returnType: string | null;
 }
 
+/** Per-language signature patterns. Each entry has a regex and an extractor for return type. */
+const SIGNATURE_PATTERNS: Array<{
+  regex: RegExp;
+  returnType: (m: RegExpMatchArray) => string | null;
+}> = [
+  // JS/TS: function name(params) or async function
+  {
+    regex: /(?:export\s+)?(?:async\s+)?function\s*\*?\s*\w*\s*\(([^)]*)\)\s*(?::\s*([^\n{]+))?/,
+    returnType: (m) => (m[2] ? m[2].trim().replace(/\s*\{$/, '') : null),
+  },
+  // Arrow: const name = (params) => or (params):ReturnType =>
+  {
+    regex: /=\s*(?:async\s+)?\(([^)]*)\)\s*(?::\s*([^=>\n{]+))?\s*=>/,
+    returnType: (m) => (m[2] ? m[2].trim() : null),
+  },
+  // Python: def name(params) -> return:
+  {
+    regex: /def\s+\w+\s*\(([^)]*)\)\s*(?:->\s*([^:\n]+))?/,
+    returnType: (m) => (m[2] ? m[2].trim() : null),
+  },
+  // Go: func (recv) name(params) (returns)
+  {
+    regex: /func\s+(?:\([^)]*\)\s+)?\w+\s*\(([^)]*)\)\s*(?:\(([^)]+)\)|(\w[^\n{]*))?/,
+    returnType: (m) => (m[2] || m[3] || '').trim() || null,
+  },
+  // Rust: fn name(params) -> ReturnType
+  {
+    regex: /fn\s+\w+\s*\(([^)]*)\)\s*(?:->\s*([^\n{]+))?/,
+    returnType: (m) => (m[2] ? m[2].trim() : null),
+  },
+];
+
 export function extractSignature(
   fileLines: string[] | null,
   line: number | undefined,
@@ -112,52 +185,18 @@ export function extractSignature(
   if (!fileLines || !line) return null;
   const idx = line - 1;
   const signatureGatherLines = opts.signatureGatherLines ?? 5;
-  // Gather lines to handle multi-line params
   const chunk = fileLines
     .slice(idx, Math.min(fileLines.length, idx + signatureGatherLines))
     .join('\n');
 
-  // JS/TS: function name(params) or (params) => or async function
-  let m = chunk.match(
-    /(?:export\s+)?(?:async\s+)?function\s*\*?\s*\w*\s*\(([^)]*)\)\s*(?::\s*([^\n{]+))?/,
-  );
-  if (m) {
-    return {
-      params: m[1]!.trim() || null,
-      returnType: m[2] ? m[2].trim().replace(/\s*\{$/, '') : null,
-    };
-  }
-  // Arrow: const name = (params) => or (params):ReturnType =>
-  m = chunk.match(/=\s*(?:async\s+)?\(([^)]*)\)\s*(?::\s*([^=>\n{]+))?\s*=>/);
-  if (m) {
-    return {
-      params: m[1]!.trim() || null,
-      returnType: m[2] ? m[2].trim() : null,
-    };
-  }
-  // Python: def name(params) -> return:
-  m = chunk.match(/def\s+\w+\s*\(([^)]*)\)\s*(?:->\s*([^:\n]+))?/);
-  if (m) {
-    return {
-      params: m[1]!.trim() || null,
-      returnType: m[2] ? m[2].trim() : null,
-    };
-  }
-  // Go: func (recv) name(params) (returns)
-  m = chunk.match(/func\s+(?:\([^)]*\)\s+)?\w+\s*\(([^)]*)\)\s*(?:\(([^)]+)\)|(\w[^\n{]*))?/);
-  if (m) {
-    return {
-      params: m[1]!.trim() || null,
-      returnType: (m[2] || m[3] || '').trim() || null,
-    };
-  }
-  // Rust: fn name(params) -> ReturnType
-  m = chunk.match(/fn\s+\w+\s*\(([^)]*)\)\s*(?:->\s*([^\n{]+))?/);
-  if (m) {
-    return {
-      params: m[1]!.trim() || null,
-      returnType: m[2] ? m[2].trim() : null,
-    };
+  for (const pattern of SIGNATURE_PATTERNS) {
+    const m = chunk.match(pattern.regex);
+    if (m) {
+      return {
+        params: m[1]!.trim() || null,
+        returnType: pattern.returnType(m),
+      };
+    }
   }
   return null;
 }

package/src/types.ts

@@ -302,6 +302,7 @@ export interface Repository {
   // ── Edge queries ──────────────────────────────────────────────────
   findCallees(nodeId: number): RelatedNodeRow[];
   findCallers(nodeId: number): RelatedNodeRow[];
+  findCallersBatch(nodeIds: number[]): Map<number, RelatedNodeRow[]>;
   findDistinctCallers(nodeId: number): RelatedNodeRow[];
   findAllOutgoingEdges(nodeId: number): AdjacentEdgeRow[];
   findAllIncomingEdges(nodeId: number): AdjacentEdgeRow[];
@@ -333,6 +334,35 @@ export interface Repository {
   getFileHash(file: string): string | null;
   hasImplementsEdges(): boolean;
   hasCoChangesTable(): boolean;
+
+  // ── Composite queries ──────────────────────────────────────────────
+  fnDeps(
+    name: string,
+    opts?: { depth?: number; noTests?: boolean; file?: string; kind?: string },
+  ): {
+    name: string;
+    results: Array<{
+      name: string;
+      kind: string;
+      file: string;
+      line: number | null;
+      endLine: number | null;
+      role: string | null;
+      fileHash: string | null;
+      callees: Array<{ name: string; kind: string; file: string; line: number | null }>;
+      callers: Array<{
+        name: string;
+        kind: string;
+        file: string;
+        line: number | null;
+        viaHierarchy?: string;
+      }>;
+      transitiveCallers: Record<
+        number,
+        Array<{ name: string; kind: string; file: string; line: number | null }>
+      >;
+    }>;
+  } | null;
 }
 
 /**
@@ -408,7 +438,7 @@ export interface DefinitionComplexity {
   cognitive: number;
   cyclomatic: number;
   maxNesting: number;
-  halstead?: HalsteadMetrics;
+  halstead?: HalsteadDerivedMetrics | HalsteadMetrics;
   loc?: LOCMetrics;
   maintainabilityIndex?: number;
 }
@@ -665,6 +695,12 @@ export interface AnalysisTiming {
   complexityMs: number;
   cfgMs: number;
   dataflowMs: number;
+  /**
+   * Diagnostic: total wall-clock time for the unified walk loop (includes
+   * setupVisitors overhead). Walk time is already distributed equally into
+   * the per-phase timers above, so this overlaps — it is not an additive
+   * bucket. Useful for cross-checking that Σ phase timers ≈ this value.
+   */
   _unifiedWalkMs?: number;
 }
 
@@ -1877,6 +1913,7 @@ export interface NativeAddon {
     fileNodeIds: unknown[],
     barrelFiles: string[],
     rootDir: string,
+    symbolNodes?: Array<{ name: string; file: string; nodeId: number }>,
   ): unknown[];
   engineVersion(): string;
   analyzeComplexity(
@@ -2048,6 +2085,46 @@ export interface NativeComplexityMetrics {
   halsteadVolume: number | null;
 }
 
+// ── Native composite query types (fnDeps) ──────────────────────────────
+
+export interface NativeFnDepsNode {
+  name: string;
+  kind: string;
+  file: string;
+  line: number | null;
+}
+
+export interface NativeFnDepsCallerNode {
+  name: string;
+  kind: string;
+  file: string;
+  line: number | null;
+  viaHierarchy: string | null;
+}
+
+export interface NativeFnDepsTransitiveGroup {
+  depth: number;
+  callers: NativeFnDepsNode[];
+}
+
+export interface NativeFnDepsEntry {
+  name: string;
+  kind: string;
+  file: string;
+  line: number | null;
+  endLine: number | null;
+  role: string | null;
+  fileHash: string | null;
+  callees: NativeFnDepsNode[];
+  callers: NativeFnDepsCallerNode[];
+  transitiveCallers: NativeFnDepsTransitiveGroup[];
+}
+
+export interface NativeFnDepsResult {
+  name: string;
+  results: NativeFnDepsEntry[];
+}
+
 /** Native rusqlite database wrapper instance (Phase 6.13 + 6.14 + 6.15). */
 export interface NativeDatabase {
   // ── Lifecycle (6.13) ────────────────────────────────────────────────
@@ -2132,6 +2209,15 @@ export interface NativeDatabase {
   getComplexityForNode(nodeId: number): NativeComplexityMetrics | null;
   getFileHash(file: string): string | null;
 
+  // ── Composite queries ──────────────────────────────────────────────
+  fnDeps(
+    name: string,
+    depth: number | null | undefined,
+    noTests: boolean | null | undefined,
+    file: string | null | undefined,
+    kind: string | null | undefined,
+  ): NativeFnDepsResult;
+
   // ── Build pipeline writes (6.15) ───────────────────────────────────
   bulkInsertNodes(
     batches: Array<{