@optave/codegraph 3.3.0 → 3.4.0

package/src/domain/analysis/{brief.js → brief.ts}

@@ -9,6 +9,7 @@ import {
 } from '../../db/index.js';
 import { loadConfig } from '../../infrastructure/config.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
+import type { BetterSqlite3Database, ImportEdgeRow, NodeRow, RelatedNodeRow } from '../../types.js';
 
 /** Symbol kinds meaningful for a file brief — excludes parameters, properties, constants. */
 const BRIEF_KINDS = new Set([
@@ -26,10 +27,12 @@ const BRIEF_KINDS = new Set([
 
 /**
  * Compute file risk tier from symbol roles and max fan-in.
- * @param {{ role: string|null, callerCount: number }[]} symbols
- * @returns {'high'|'medium'|'low'}
  */
-function computeRiskTier(symbols, highThreshold = 10, mediumThreshold = 3) {
+function computeRiskTier(
+  symbols: Array<{ role: string | null; callerCount: number }>,
+  highThreshold = 10,
+  mediumThreshold = 3,
+): 'high' | 'medium' | 'low' {
   let maxCallers = 0;
   let hasCoreRole = false;
   for (const s of symbols) {
@@ -45,14 +48,19 @@ function computeRiskTier(symbols, highThreshold = 10, mediumThreshold = 3) {
  * BFS to count transitive callers for a single node.
  * Lightweight variant — only counts, does not collect details.
  */
-function countTransitiveCallers(db, startId, noTests, maxDepth = 5) {
+function countTransitiveCallers(
+  db: BetterSqlite3Database,
+  startId: number,
+  noTests: boolean,
+  maxDepth = 5,
+): number {
   const visited = new Set([startId]);
   let frontier = [startId];
 
   for (let d = 1; d <= maxDepth; d++) {
-    const nextFrontier = [];
+    const nextFrontier: number[] = [];
     for (const fid of frontier) {
-      const callers = findDistinctCallers(db, fid);
+      const callers = findDistinctCallers(db, fid) as RelatedNodeRow[];
       for (const c of callers) {
         if (!visited.has(c.id) && (!noTests || !isTestFile(c.file))) {
           visited.add(c.id);
@@ -71,14 +79,19 @@ function countTransitiveCallers(db, startId, noTests, maxDepth = 5) {
  * Count transitive file-level import dependents via BFS.
  * Depth-bounded to match countTransitiveCallers and keep hook latency predictable.
  */
-function countTransitiveImporters(db, fileNodeIds, noTests, maxDepth = 5) {
+function countTransitiveImporters(
+  db: BetterSqlite3Database,
+  fileNodeIds: number[],
+  noTests: boolean,
+  maxDepth = 5,
+): number {
   const visited = new Set(fileNodeIds);
   let frontier = [...fileNodeIds];
 
   for (let d = 1; d <= maxDepth; d++) {
-    const nextFrontier = [];
+    const nextFrontier: number[] = [];
     for (const current of frontier) {
-      const dependents = findImportDependents(db, current);
+      const dependents = findImportDependents(db, current) as RelatedNodeRow[];
       for (const dep of dependents) {
         if (!visited.has(dep.id) && (!noTests || !isTestFile(dep.file))) {
           visited.add(dep.id);
@@ -96,13 +109,13 @@ function countTransitiveImporters(db, fileNodeIds, noTests, maxDepth = 5) {
 /**
  * Produce a token-efficient file brief: symbols with roles and caller counts,
  * importer info with transitive count, and file risk tier.
- *
- * @param {string} file - File path (partial match)
- * @param {string} customDbPath - Path to graph.db
- * @param {{ noTests?: boolean }} opts
- * @returns {{ file: string, results: object[] }}
  */
-export function briefData(file, customDbPath, opts = {}) {
+export function briefData(
+  file: string,
+  customDbPath: string,
+  // biome-ignore lint/suspicious/noExplicitAny: config shape is dynamic
+  opts: { noTests?: boolean; config?: any } = {},
+) {
   const db = openReadonlyOrFail(customDbPath);
   try {
     const noTests = opts.noTests || false;
@@ -111,14 +124,14 @@ export function briefData(file, customDbPath, opts = {}) {
     const importerDepth = config.analysis?.briefImporterDepth ?? 5;
     const highRiskCallers = config.analysis?.briefHighRiskCallers ?? 10;
     const mediumRiskCallers = config.analysis?.briefMediumRiskCallers ?? 3;
-    const fileNodes = findFileNodes(db, `%${file}%`);
+    const fileNodes = findFileNodes(db, `%${file}%`) as NodeRow[];
     if (fileNodes.length === 0) {
       return { file, results: [] };
     }
 
     const results = fileNodes.map((fn) => {
       // Direct importers
-      let importedBy = findImportSources(db, fn.id);
+      let importedBy = findImportSources(db, fn.id) as ImportEdgeRow[];
       if (noTests) importedBy = importedBy.filter((i) => !isTestFile(i.file));
       const directImporters = [...new Set(importedBy.map((i) => i.file))];
 
@@ -126,11 +139,13 @@ export function briefData(file, customDbPath, opts = {}) {
       const totalImporterCount = countTransitiveImporters(db, [fn.id], noTests, importerDepth);
 
       // Direct imports
-      let importsTo = findImportTargets(db, fn.id);
+      let importsTo = findImportTargets(db, fn.id) as ImportEdgeRow[];
       if (noTests) importsTo = importsTo.filter((i) => !isTestFile(i.file));
 
       // Symbol definitions with roles and caller counts
-      const defs = findNodesByFile(db, fn.file).filter((d) => BRIEF_KINDS.has(d.kind));
+      const defs = (findNodesByFile(db, fn.file) as NodeRow[]).filter((d) =>
+        BRIEF_KINDS.has(d.kind),
+      );
       const symbols = defs.map((d) => {
         const callerCount = countTransitiveCallers(db, d.id, noTests, callerDepth);
         return {

package/src/domain/analysis/{context.js → context.ts}

@@ -13,8 +13,11 @@ import {
   findNodeChildren,
   findNodesByFile,
   getComplexityForNode,
+  getLineCountForNode,
+  getMaxEndLineForFile,
   openReadonlyOrFail,
 } from '../../db/index.js';
+import { cachedStmt } from '../../db/repository/cached-stmt.js';
 import { loadConfig } from '../../infrastructure/config.js';
 import { debug } from '../../infrastructure/logger.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
@@ -28,19 +31,50 @@ import {
 import { resolveMethodViaHierarchy } from '../../shared/hierarchy.js';
 import { normalizeSymbol } from '../../shared/normalize.js';
 import { paginateResult } from '../../shared/paginate.js';
+import type {
+  BetterSqlite3Database,
+  ChildNodeRow,
+  ImportEdgeRow,
+  IntraFileCallEdge,
+  NodeRow,
+  RelatedNodeRow,
+  StmtCache,
+} from '../../types.js';
 import { findMatchingNodes } from './symbol-lookup.js';
 
-function buildCallees(db, node, repoRoot, getFileLines, opts) {
+interface DisplayOpts {
+  maxLines?: number;
+  excerptLines?: number;
+  jsdocEndScanLines?: number;
+  jsdocOpenScanLines?: number;
+  summaryMaxChars?: number;
+  signatureGatherLines?: number;
+  [key: string]: unknown;
+}
+
+function buildCallees(
+  db: BetterSqlite3Database,
+  node: NodeRow,
+  repoRoot: string,
+  getFileLines: (file: string) => string[] | null,
+  opts: { noTests: boolean; depth: number; displayOpts: DisplayOpts },
+) {
   const { noTests, depth, displayOpts } = opts;
-  const calleeRows = findCallees(db, node.id);
+  const calleeRows = findCallees(db, node.id) as RelatedNodeRow[];
   const filteredCallees = noTests ? calleeRows.filter((c) => !isTestFile(c.file)) : calleeRows;
 
   const callees = filteredCallees.map((c) => {
     const cLines = getFileLines(c.file);
     const summary = cLines ? extractSummary(cLines, c.line, displayOpts) : null;
-    let calleeSource = null;
+    let calleeSource: string | null = null;
     if (depth >= 1) {
-      calleeSource = readSourceRange(repoRoot, c.file, c.line, c.end_line, displayOpts);
+      calleeSource = readSourceRange(
+        repoRoot,
+        c.file,
+        c.line,
+        c.end_line ?? undefined,
+        displayOpts,
+      );
     }
     return {
       name: c.name,
@@ -59,9 +93,9 @@ function buildCallees(db, node, repoRoot, getFileLines, opts) {
     let frontier = filteredCallees.map((c) => c.id);
     const maxDepth = Math.min(depth, 5);
     for (let d = 2; d <= maxDepth; d++) {
-      const nextFrontier = [];
+      const nextFrontier: number[] = [];
       for (const fid of frontier) {
-        const deeper = findCallees(db, fid);
+        const deeper = findCallees(db, fid) as RelatedNodeRow[];
         for (const c of deeper) {
           if (!visited.has(c.id) && (!noTests || !isTestFile(c.file))) {
             visited.add(c.id);
@@ -74,7 +108,13 @@ function buildCallees(db, node, repoRoot, getFileLines, opts) {
               line: c.line,
               endLine: c.end_line || null,
               summary: cLines ? extractSummary(cLines, c.line, displayOpts) : null,
-              source: readSourceRange(repoRoot, c.file, c.line, c.end_line, displayOpts),
+              source: readSourceRange(
+                repoRoot,
+                c.file,
+                c.line,
+                c.end_line ?? undefined,
+                displayOpts,
+              ),
             });
           }
         }
@@ -87,21 +127,31 @@ function buildCallees(db, node, repoRoot, getFileLines, opts) {
   return callees;
 }
 
-function buildCallers(db, node, noTests) {
-  let callerRows = findCallers(db, node.id);
+function fetchCallerRows(db: BetterSqlite3Database, node: NodeRow) {
+  const callerRows: Array<RelatedNodeRow & { viaHierarchy?: string }> = findCallers(
+    db,
+    node.id,
+  ) as RelatedNodeRow[];
 
   if (node.kind === 'method' && node.name.includes('.')) {
-    const methodName = node.name.split('.').pop();
+    const methodName = node.name.split('.').pop() ?? '';
     const relatedMethods = resolveMethodViaHierarchy(db, methodName);
     for (const rm of relatedMethods) {
       if (rm.id === node.id) continue;
-      const extraCallers = findCallers(db, rm.id);
+      const extraCallers = findCallers(db, rm.id) as RelatedNodeRow[];
       callerRows.push(...extraCallers.map((c) => ({ ...c, viaHierarchy: rm.name })));
     }
   }
-  if (noTests) callerRows = callerRows.filter((c) => !isTestFile(c.file));
+  return callerRows;
+}
+
+function buildCallers(
+  callerRows: Array<RelatedNodeRow & { viaHierarchy?: string }>,
+  noTests: boolean,
+) {
+  const filtered = noTests ? callerRows.filter((c) => !isTestFile(c.file)) : callerRows;
 
-  return callerRows.map((c) => ({
+  return filtered.map((c) => ({
     name: c.name,
     kind: c.kind,
     file: c.file,
@@ -113,10 +163,10 @@ function buildCallers(db, node, noTests) {
 const INTERFACE_LIKE_KINDS = new Set(['interface', 'trait']);
 const IMPLEMENTOR_KINDS = new Set(['class', 'struct', 'record', 'enum']);
 
-function buildImplementationInfo(db, node, noTests) {
+function buildImplementationInfo(db: BetterSqlite3Database, node: NodeRow, noTests: boolean) {
   // For interfaces/traits: show who implements them
   if (INTERFACE_LIKE_KINDS.has(node.kind)) {
-    let impls = findImplementors(db, node.id);
+    let impls = findImplementors(db, node.id) as RelatedNodeRow[];
     if (noTests) impls = impls.filter((n) => !isTestFile(n.file));
     return {
       implementors: impls.map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line })),
@@ -124,7 +174,7 @@ function buildImplementationInfo(db, node, noTests) {
   }
   // For classes/structs: show what they implement
   if (IMPLEMENTOR_KINDS.has(node.kind)) {
-    let ifaces = findInterfaces(db, node.id);
+    let ifaces = findInterfaces(db, node.id) as RelatedNodeRow[];
     if (noTests) ifaces = ifaces.filter((n) => !isTestFile(n.file));
     if (ifaces.length > 0) {
       return {
@@ -135,24 +185,32 @@ function buildImplementationInfo(db, node, noTests) {
   return {};
 }
 
-function buildRelatedTests(db, node, getFileLines, includeTests) {
-  const testCallerRows = findCallers(db, node.id);
-  const testCallers = testCallerRows.filter((c) => isTestFile(c.file));
+function buildRelatedTests(
+  callerRows: RelatedNodeRow[],
+  getFileLines: (file: string) => string[] | null,
+  includeTests: boolean,
+) {
+  const testCallers = callerRows.filter((c) => isTestFile(c.file));
 
-  const testsByFile = new Map();
+  const testsByFile = new Map<string, RelatedNodeRow[]>();
   for (const tc of testCallers) {
     if (!testsByFile.has(tc.file)) testsByFile.set(tc.file, []);
-    testsByFile.get(tc.file).push(tc);
+    testsByFile.get(tc.file)!.push(tc);
   }
 
-  const relatedTests = [];
+  const relatedTests: Array<{
+    file: string;
+    testCount: number;
+    testNames: string[];
+    source?: string;
+  }> = [];
   for (const [file] of testsByFile) {
     const tLines = getFileLines(file);
-    const testNames = [];
+    const testNames: string[] = [];
     if (tLines) {
       for (const tl of tLines) {
         const tm = tl.match(/(?:it|test|describe)\s*\(\s*['"`]([^'"`]+)['"`]/);
-        if (tm) testNames.push(tm[1]);
+        if (tm) testNames.push(tm[1]!);
       }
     }
     const testSource = includeTests && tLines ? tLines.join('\n') : undefined;
@@ -167,7 +225,7 @@ function buildRelatedTests(db, node, getFileLines, includeTests) {
   return relatedTests;
 }
 
-function getComplexityMetrics(db, nodeId) {
+function getComplexityMetrics(db: BetterSqlite3Database, nodeId: number) {
   try {
     const cRow = getComplexityForNode(db, nodeId);
     if (!cRow) return null;
@@ -178,38 +236,43 @@ function getComplexityMetrics(db, nodeId) {
       maintainabilityIndex: cRow.maintainability_index || 0,
       halsteadVolume: cRow.halstead_volume || 0,
     };
-  } catch (e) {
-    debug(`complexity lookup failed for node ${nodeId}: ${e.message}`);
+  } catch (e: unknown) {
+    debug(`complexity lookup failed for node ${nodeId}: ${(e as Error).message}`);
     return null;
   }
 }
 
-function getNodeChildrenSafe(db, nodeId) {
+function getNodeChildrenSafe(db: BetterSqlite3Database, nodeId: number) {
   try {
-    return findNodeChildren(db, nodeId).map((c) => ({
+    return (findNodeChildren(db, nodeId) as ChildNodeRow[]).map((c) => ({
       name: c.name,
       kind: c.kind,
       line: c.line,
       endLine: c.end_line || null,
     }));
-  } catch (e) {
-    debug(`findNodeChildren failed for node ${nodeId}: ${e.message}`);
+  } catch (e: unknown) {
+    debug(`findNodeChildren failed for node ${nodeId}: ${(e as Error).message}`);
     return [];
   }
 }
 
-function explainFileImpl(db, target, getFileLines, displayOpts) {
-  const fileNodes = findFileNodes(db, `%${target}%`);
+function explainFileImpl(
+  db: BetterSqlite3Database,
+  target: string,
+  getFileLines: (file: string) => string[] | null,
+  displayOpts: DisplayOpts,
+) {
+  const fileNodes = findFileNodes(db, `%${target}%`) as NodeRow[];
   if (fileNodes.length === 0) return [];
 
   return fileNodes.map((fn) => {
-    const symbols = findNodesByFile(db, fn.file);
+    const symbols = findNodesByFile(db, fn.file) as NodeRow[];
 
     // IDs of symbols that have incoming calls from other files (public)
-    const publicIds = findCrossFileCallTargets(db, fn.file);
+    const publicIds = findCrossFileCallTargets(db, fn.file) as Set<number>;
 
     const fileLines = getFileLines(fn.file);
-    const mapSymbol = (s) => ({
+    const mapSymbol = (s: NodeRow) => ({
       name: s.name,
       kind: s.kind,
       line: s.line,
@@ -221,28 +284,28 @@ function explainFileImpl(db, target, getFileLines, displayOpts) {
     const publicApi = symbols.filter((s) => publicIds.has(s.id)).map(mapSymbol);
     const internal = symbols.filter((s) => !publicIds.has(s.id)).map(mapSymbol);
 
-    const imports = findImportTargets(db, fn.id).map((r) => ({ file: r.file }));
-    const importedBy = findImportSources(db, fn.id).map((r) => ({ file: r.file }));
+    const imports = (findImportTargets(db, fn.id) as ImportEdgeRow[]).map((r) => ({
+      file: r.file,
+    }));
+    const importedBy = (findImportSources(db, fn.id) as ImportEdgeRow[]).map((r) => ({
+      file: r.file,
+    }));
 
-    const intraEdges = findIntraFileCallEdges(db, fn.file);
-    const dataFlowMap = new Map();
+    const intraEdges = findIntraFileCallEdges(db, fn.file) as IntraFileCallEdge[];
+    const dataFlowMap = new Map<string, string[]>();
     for (const edge of intraEdges) {
       if (!dataFlowMap.has(edge.caller_name)) dataFlowMap.set(edge.caller_name, []);
-      dataFlowMap.get(edge.caller_name).push(edge.callee_name);
+      dataFlowMap.get(edge.caller_name)!.push(edge.callee_name);
     }
     const dataFlow = [...dataFlowMap.entries()].map(([caller, callees]) => ({
       caller,
       callees,
     }));
 
-    const metric = db
-      .prepare(`SELECT nm.line_count FROM node_metrics nm WHERE nm.node_id = ?`)
-      .get(fn.id);
-    let lineCount = metric?.line_count || null;
+    const metric = getLineCountForNode(db, fn.id) as { line_count: number } | undefined;
+    let lineCount: number | null = metric?.line_count || null;
     if (!lineCount) {
-      const maxLine = db
-        .prepare(`SELECT MAX(end_line) as max_end FROM nodes WHERE file = ?`)
-        .get(fn.file);
+      const maxLine = getMaxEndLineForFile(db, fn.file) as { max_end: number | null } | undefined;
       lineCount = maxLine?.max_end || null;
     }
 
@@ -259,12 +322,18 @@ function explainFileImpl(db, target, getFileLines, displayOpts) {
   });
 }
 
-function explainFunctionImpl(db, target, noTests, getFileLines, displayOpts) {
-  let nodes = db
-    .prepare(
-      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function','method','class','interface','type','struct','enum','trait','record','module','constant') ORDER BY file, line`,
-    )
-    .all(`%${target}%`);
+const _explainNodeStmtCache: StmtCache<NodeRow> = new WeakMap();
+const _EXPLAIN_NODE_SQL = `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function','method','class','interface','type','struct','enum','trait','record','module','constant') ORDER BY file, line`;
+
+function explainFunctionImpl(
+  db: BetterSqlite3Database,
+  target: string,
+  noTests: boolean,
+  getFileLines: (file: string) => string[] | null,
+  displayOpts: DisplayOpts,
+) {
+  const stmt = cachedStmt(_explainNodeStmtCache, db, _EXPLAIN_NODE_SQL);
+  let nodes = stmt.all(`%${target}%`) as NodeRow[];
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
   if (nodes.length === 0) return [];
 
@@ -275,14 +344,16 @@ function explainFunctionImpl(db, target, noTests, getFileLines, displayOpts) {
     const summary = fileLines ? extractSummary(fileLines, node.line, displayOpts) : null;
     const signature = fileLines ? extractSignature(fileLines, node.line, displayOpts) : null;
 
-    const callees = findCallees(db, node.id).map((c) => ({
+    const callees = (findCallees(db, node.id) as RelatedNodeRow[]).map((c) => ({
       name: c.name,
       kind: c.kind,
       file: c.file,
       line: c.line,
     }));
 
-    let callers = findCallers(db, node.id).map((c) => ({
+    const allCallerRows = findCallers(db, node.id) as RelatedNodeRow[];
+
+    let callers = allCallerRows.map((c) => ({
       name: c.name,
       kind: c.kind,
       file: c.file,
@@ -290,9 +361,8 @@ function explainFunctionImpl(db, target, noTests, getFileLines, displayOpts) {
     }));
     if (noTests) callers = callers.filter((c) => !isTestFile(c.file));
 
-    const testCallerRows = findCallers(db, node.id);
-    const seenFiles = new Set();
-    const relatedTests = testCallerRows
+    const seenFiles = new Set<string>();
+    const relatedTests = allCallerRows
       .filter((r) => isTestFile(r.file) && !seenFiles.has(r.file) && seenFiles.add(r.file))
       .map((r) => ({ file: r.file }));
 
@@ -309,18 +379,19 @@ function explainFunctionImpl(db, target, noTests, getFileLines, displayOpts) {
   });
 }
 
+// biome-ignore lint/suspicious/noExplicitAny: explainFunctionImpl results have dynamic shape with _depth
 function explainCallees(
-  parentResults,
-  currentDepth,
-  visited,
-  db,
-  noTests,
-  getFileLines,
-  displayOpts,
-) {
+  parentResults: any[],
+  currentDepth: number,
+  visited: Set<string>,
+  db: BetterSqlite3Database,
+  noTests: boolean,
+  getFileLines: (file: string) => string[] | null,
+  displayOpts: DisplayOpts,
+): void {
   if (currentDepth <= 0) return;
   for (const r of parentResults) {
-    const newCallees = [];
+    const newCallees: typeof parentResults = [];
     for (const callee of r.callees) {
       const key = `${callee.name}:${callee.file}:${callee.line}`;
       if (visited.has(key)) continue;
@@ -334,7 +405,8 @@ function explainCallees(
       );
       const exact = calleeResults.find((cr) => cr.file === callee.file && cr.line === callee.line);
       if (exact) {
-        exact._depth = (r._depth || 0) + 1;
+        (exact as Record<string, unknown>)['_depth'] =
+          (((r as Record<string, unknown>)['_depth'] as number) || 0) + 1;
         newCallees.push(exact);
       }
     }
@@ -345,9 +417,24 @@ function explainCallees(
   }
 }
 
-// ─── Exported functions ──────────────────────────────────────────────────
-
-export function contextData(name, customDbPath, opts = {}) {
+// --- Exported functions ---
+
+export function contextData(
+  name: string,
+  customDbPath: string,
+  opts: {
+    depth?: number;
+    noSource?: boolean;
+    noTests?: boolean;
+    includeTests?: boolean;
+    file?: string;
+    kind?: string;
+    limit?: number;
+    offset?: number;
+    // biome-ignore lint/suspicious/noExplicitAny: config shape is dynamic
+    config?: any;
+  } = {},
+) {
   const db = openReadonlyOrFail(customDbPath);
   try {
     const depth = opts.depth || 0;
@@ -356,7 +443,7 @@ export function contextData(name, customDbPath, opts = {}) {
     const includeTests = opts.includeTests || false;
 
     const config = opts.config || loadConfig();
-    const displayOpts = config.display || {};
+    const displayOpts: DisplayOpts = config.display || {};
 
     const dbPath = findDbPath(customDbPath);
     const repoRoot = path.resolve(path.dirname(dbPath), '..');
@@ -373,7 +460,7 @@ export function contextData(name, customDbPath, opts = {}) {
 
       const source = noSource
         ? null
-        : readSourceRange(repoRoot, node.file, node.line, node.end_line, displayOpts);
+        : readSourceRange(repoRoot, node.file, node.line, node.end_line ?? undefined, displayOpts);
 
       const signature = fileLines ? extractSignature(fileLines, node.line, displayOpts) : null;
 
@@ -382,8 +469,9 @@ export function contextData(name, customDbPath, opts = {}) {
         depth,
         displayOpts,
       });
-      const callers = buildCallers(db, node, noTests);
-      const relatedTests = buildRelatedTests(db, node, getFileLines, includeTests);
+      const allCallerRows = fetchCallerRows(db, node);
+      const callers = buildCallers(allCallerRows, noTests);
+      const relatedTests = buildRelatedTests(allCallerRows, getFileLines, includeTests);
       const complexityMetrics = getComplexityMetrics(db, node.id);
       const nodeChildren = getNodeChildrenSafe(db, node.id);
       const implInfo = buildImplementationInfo(db, node, noTests);
@@ -413,7 +501,18 @@ export function contextData(name, customDbPath, opts = {}) {
   }
 }
 
-export function explainData(target, customDbPath, opts = {}) {
+export function explainData(
+  target: string,
+  customDbPath?: string,
+  opts: {
+    noTests?: boolean;
+    depth?: number;
+    limit?: number;
+    offset?: number;
+    // biome-ignore lint/suspicious/noExplicitAny: config shape is dynamic
+    config?: any;
+  } = {},
+) {
   const db = openReadonlyOrFail(customDbPath);
   try {
     const noTests = opts.noTests || false;
@@ -421,7 +520,7 @@ export function explainData(target, customDbPath, opts = {}) {
     const kind = isFileLikeTarget(target) ? 'file' : 'function';
 
     const config = opts.config || loadConfig();
-    const displayOpts = config.display || {};
+    const displayOpts: DisplayOpts = config.display || {};
 
     const dbPath = findDbPath(customDbPath);
     const repoRoot = path.resolve(path.dirname(dbPath), '..');
@@ -434,7 +533,8 @@ export function explainData(target, customDbPath, opts = {}) {
         : explainFunctionImpl(db, target, noTests, getFileLines, displayOpts);
 
     if (kind === 'function' && depth > 0 && results.length > 0) {
-      const visited = new Set(results.map((r) => `${r.name}:${r.file}:${r.line}`));
+      // biome-ignore lint/suspicious/noExplicitAny: results are function results when kind === 'function'
+      const visited = new Set(results.map((r: any) => `${r.name}:${r.file}:${r.line ?? ''}`));
       explainCallees(results, depth, visited, db, noTests, getFileLines, displayOpts);
     }