@optave/codegraph 3.8.0 → 3.9.0

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

@@ -294,99 +294,107 @@ export function children(name: string, customDbPath: string, opts: OutputOpts =
   }
 }
 
-function renderContextResult(r: ContextResult): void {
-  const lineRange = r.endLine ? `${r.line}-${r.endLine}` : `${r.line}`;
-  const roleTag = r.role ? ` [${r.role}]` : '';
-  console.log(`\n# ${r.name} (${r.kind})${roleTag} — ${r.file}:${lineRange}\n`);
+function renderSignature(sig: ContextResult['signature']): void {
+  if (!sig) return;
+  console.log('## Type/Shape Info');
+  if (sig.params != null) console.log(`  Parameters: (${sig.params})`);
+  if (sig.returnType) console.log(`  Returns: ${sig.returnType}`);
+  console.log();
+}
 
-  if (r.signature) {
-    console.log('## Type/Shape Info');
-    if (r.signature.params != null) console.log(`  Parameters: (${r.signature.params})`);
-    if (r.signature.returnType) console.log(`  Returns: ${r.signature.returnType}`);
-    console.log();
+function renderComplexity(cx: NonNullable<ContextResult['complexity']>): void {
+  const miPart = cx.maintainabilityIndex ? ` | MI: ${cx.maintainabilityIndex}` : '';
+  console.log('## Complexity');
+  console.log(
+    `  Cognitive: ${cx.cognitive} | Cyclomatic: ${cx.cyclomatic} | Max Nesting: ${cx.maxNesting}${miPart}`,
+  );
+  console.log();
+}
+
+function renderSource(source: string, indent = '  '): void {
+  console.log('## Source');
+  for (const line of source.split('\n')) {
+    console.log(`${indent}${line}`);
   }
+  console.log();
+}
 
-  if (r.children && r.children.length > 0) {
-    console.log(`## Children (${r.children.length})`);
-    for (const c of r.children) {
-      console.log(`  ${kindIcon(c.kind)} ${c.name}  :${c.line}`);
+function renderCallees(callees: CalleeRef[]): void {
+  if (callees.length === 0) return;
+  console.log(`## Direct Dependencies (${callees.length})`);
+  for (const c of callees) {
+    const summary = c.summary ? ` — ${c.summary}` : '';
+    console.log(`  ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}${summary}`);
+    if (c.source) {
+      const maxSourceLines = 10;
+      for (const line of c.source.split('\n').slice(0, maxSourceLines)) {
+        console.log(`    | ${line}`);
+      }
     }
-    console.log();
   }
+  console.log();
+}
 
-  if (r.complexity) {
-    const cx = r.complexity;
-    const miPart = cx.maintainabilityIndex ? ` | MI: ${cx.maintainabilityIndex}` : '';
-    console.log('## Complexity');
-    console.log(
-      `  Cognitive: ${cx.cognitive} | Cyclomatic: ${cx.cyclomatic} | Max Nesting: ${cx.maxNesting}${miPart}`,
-    );
-    console.log();
+function renderCallers(callers: CallerRef[]): void {
+  if (callers.length === 0) return;
+  console.log(`## Callers (${callers.length})`);
+  for (const c of callers) {
+    const via = c.viaHierarchy ? ` (via ${c.viaHierarchy})` : '';
+    console.log(`  ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}${via}`);
   }
+  console.log();
+}
 
-  if (r.source) {
-    console.log('## Source');
-    for (const line of r.source.split('\n')) {
-      console.log(`  ${line}`);
-    }
-    console.log();
+function renderSymbolRefList(label: string, items: SymbolRef[]): void {
+  if (items.length === 0) return;
+  console.log(`## ${label} (${items.length})`);
+  for (const s of items) {
+    console.log(`  ${kindIcon(s.kind)} ${s.name}  ${s.file}:${s.line}`);
   }
+  console.log();
+}
 
-  if (r.callees.length > 0) {
-    console.log(`## Direct Dependencies (${r.callees.length})`);
-    for (const c of r.callees) {
-      const summary = c.summary ? ` — ${c.summary}` : '';
-      console.log(`  ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}${summary}`);
-      if (c.source) {
-        for (const line of c.source.split('\n').slice(0, 10)) {
-          console.log(`    | ${line}`);
-        }
+function renderRelatedTests(tests: ContextResult['relatedTests']): void {
+  if (tests.length === 0) return;
+  console.log('## Related Tests');
+  const maxTestSourceLines = 20;
+  for (const t of tests) {
+    console.log(`  ${t.file} — ${t.testCount} tests`);
+    for (const tn of t.testNames) {
+      console.log(`    - ${tn}`);
+    }
+    if (t.source) {
+      console.log('    Source:');
+      for (const line of t.source.split('\n').slice(0, maxTestSourceLines)) {
+        console.log(`    | ${line}`);
       }
     }
-    console.log();
   }
+  console.log();
+}
 
-  if (r.callers.length > 0) {
-    console.log(`## Callers (${r.callers.length})`);
-    for (const c of r.callers) {
-      const via = c.viaHierarchy ? ` (via ${c.viaHierarchy})` : '';
-      console.log(`  ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}${via}`);
-    }
-    console.log();
-  }
+function renderContextResult(r: ContextResult): void {
+  const lineRange = r.endLine ? `${r.line}-${r.endLine}` : `${r.line}`;
+  const roleTag = r.role ? ` [${r.role}]` : '';
+  console.log(`\n# ${r.name} (${r.kind})${roleTag} — ${r.file}:${lineRange}\n`);
 
-  if (r.implementors && r.implementors.length > 0) {
-    console.log(`## Implementors (${r.implementors.length})`);
-    for (const impl of r.implementors) {
-      console.log(`  ${kindIcon(impl.kind)} ${impl.name}  ${impl.file}:${impl.line}`);
-    }
-    console.log();
-  }
+  renderSignature(r.signature);
 
-  if (r.implements && r.implements.length > 0) {
-    console.log(`## Implements (${r.implements.length})`);
-    for (const iface of r.implements) {
-      console.log(`  ${kindIcon(iface.kind)} ${iface.name}  ${iface.file}:${iface.line}`);
+  if (r.children && r.children.length > 0) {
+    console.log(`## Children (${r.children.length})`);
+    for (const c of r.children) {
+      console.log(`  ${kindIcon(c.kind)} ${c.name}  :${c.line}`);
     }
     console.log();
   }
 
-  if (r.relatedTests.length > 0) {
-    console.log('## Related Tests');
-    for (const t of r.relatedTests) {
-      console.log(`  ${t.file} — ${t.testCount} tests`);
-      for (const tn of t.testNames) {
-        console.log(`    - ${tn}`);
-      }
-      if (t.source) {
-        console.log('    Source:');
-        for (const line of t.source.split('\n').slice(0, 20)) {
-          console.log(`    | ${line}`);
-        }
-      }
-    }
-    console.log();
-  }
+  if (r.complexity) renderComplexity(r.complexity);
+  if (r.source) renderSource(r.source);
+  renderCallees(r.callees);
+  renderCallers(r.callers);
+  renderSymbolRefList('Implementors', r.implementors || []);
+  renderSymbolRefList('Implements', r.implements || []);
+  renderRelatedTests(r.relatedTests);
 
   if (r.callees.length === 0 && r.callers.length === 0 && r.relatedTests.length === 0) {
     console.log('  (no call edges or tests found — may be invoked dynamically or via re-exports)');
@@ -439,7 +447,7 @@ function renderFileExplain(r: FileExplainResult): void {
   console.log();
 }
 
-function renderFunctionExplain(r: FunctionExplainResult, indent = ''): void {
+function renderExplainHeader(r: FunctionExplainResult, indent: string): void {
   const lineRange = r.endLine ? `${r.line}-${r.endLine}` : `${r.line}`;
   const lineInfo = r.lineCount ? `${r.lineCount} lines` : '';
   const summaryPart = r.summary ? ` | ${r.summary}` : '';
@@ -454,15 +462,19 @@ function renderFunctionExplain(r: FunctionExplainResult, indent = ''): void {
     if (r.signature.params != null) console.log(`${indent}  Parameters: (${r.signature.params})`);
     if (r.signature.returnType) console.log(`${indent}  Returns: ${r.signature.returnType}`);
   }
+}
 
-  if (r.complexity) {
-    const cx = r.complexity;
-    const miPart = cx.maintainabilityIndex ? ` MI=${cx.maintainabilityIndex}` : '';
-    console.log(
-      `${indent}  Complexity: cognitive=${cx.cognitive} cyclomatic=${cx.cyclomatic} nesting=${cx.maxNesting}${miPart}`,
-    );
-  }
+function renderExplainComplexity(
+  cx: NonNullable<FunctionExplainResult['complexity']>,
+  indent: string,
+): void {
+  const miPart = cx.maintainabilityIndex ? ` MI=${cx.maintainabilityIndex}` : '';
+  console.log(
+    `${indent}  Complexity: cognitive=${cx.cognitive} cyclomatic=${cx.cyclomatic} nesting=${cx.maxNesting}${miPart}`,
+  );
+}
 
+function renderExplainEdges(r: FunctionExplainResult, indent: string): void {
   if (r.callees.length > 0) {
     console.log(`\n${indent}  Calls (${r.callees.length}):`);
     for (const c of r.callees) {
@@ -488,8 +500,15 @@ function renderFunctionExplain(r: FunctionExplainResult, indent = ''): void {
   if (r.callees.length === 0 && r.callers.length === 0) {
     console.log(`${indent}  (no call edges found -- may be invoked dynamically or via re-exports)`);
   }
+}
+
+function renderFunctionExplain(r: FunctionExplainResult, indent = ''): void {
+  renderExplainHeader(r, indent);
+  if (r.complexity) renderExplainComplexity(r.complexity, indent);
+  renderExplainEdges(r, indent);
 
   if (r.depDetails && r.depDetails.length > 0) {
+    const depthLevel = r._depth || 0;
     console.log(`\n${indent}  --- Dependencies (depth ${depthLevel + 1}) ---`);
     for (const dep of r.depDetails) {
       renderFunctionExplain(dep, `${indent}  `);

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

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { kindIcon, moduleMapData, rolesData, statsData } from '../../domain/queries.js';
+import { debug } from '../../infrastructure/logger.js';
 import { outputResult } from '../../infrastructure/result-formatter.js';
+import { toErrorMessage } from '../../shared/errors.js';
 
 interface OutputOpts {
   json?: boolean;
@@ -236,8 +238,8 @@ export async function stats(customDbPath: string, opts: OutputOpts = {}): Promis
   try {
     const { communitySummaryForStats } = await import('../../features/communities.js');
     data.communities = communitySummaryForStats(customDbPath, { noTests: opts.noTests });
-  } catch {
-    /* community detection is optional; silently skip on any error */
+  } catch (e) {
+    debug(`stats: community detection failed (optional): ${toErrorMessage(e)}`);
   }
 
   if (outputResult(data as unknown as Record<string, unknown>, null, opts)) return;
@@ -281,6 +283,26 @@ export function moduleMap(customDbPath: string, limit = 20, opts: OutputOpts = {
   );
 }
 
+function groupByRole(symbols: RoleSymbol[]): Record<string, RoleSymbol[]> {
+  const byRole: Record<string, RoleSymbol[]> = {};
+  for (const s of symbols) {
+    if (!byRole[s.role]) byRole[s.role] = [];
+    byRole[s.role]!.push(s);
+  }
+  return byRole;
+}
+
+function printRoleGroup(role: string, symbols: RoleSymbol[]): void {
+  console.log(`## ${role} (${symbols.length})`);
+  for (const s of symbols.slice(0, 30)) {
+    console.log(`  ${kindIcon(s.kind)} ${s.name}  ${s.file}:${s.line}`);
+  }
+  if (symbols.length > 30) {
+    console.log(`  ... and ${symbols.length - 30} more`);
+  }
+  console.log();
+}
+
 export function roles(customDbPath: string, opts: OutputOpts = {}): void {
   const data = rolesData(customDbPath, opts) as RolesData;
   if (outputResult(data as unknown as Record<string, unknown>, 'symbols', opts)) return;
@@ -298,20 +320,8 @@ export function roles(customDbPath: string, opts: OutputOpts = {}): void {
     .map(([role, count]) => `${role}: ${count}`);
   console.log(`  ${summaryParts.join('  ')}\n`);
 
-  const byRole: Record<string, RoleSymbol[]> = {};
-  for (const s of data.symbols) {
-    if (!byRole[s.role]) byRole[s.role] = [];
-    byRole[s.role]!.push(s);
-  }
-
+  const byRole = groupByRole(data.symbols);
   for (const [role, symbols] of Object.entries(byRole)) {
-    console.log(`## ${role} (${symbols.length})`);
-    for (const s of symbols.slice(0, 30)) {
-      console.log(`  ${kindIcon(s.kind)} ${s.name}  ${s.file}:${s.line}`);
-    }
-    if (symbols.length > 30) {
-      console.log(`  ... and ${symbols.length - 30} more`);
-    }
-    console.log();
+    printRoleGroup(role, symbols);
   }
 }

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

@@ -127,6 +127,37 @@ interface FilePathDataResult {
   alternateCount: number;
 }
 
+function printFilePathNotFound(from: string, to: string, data: FilePathDataResult): void {
+  const dir = data.reverse ? 'reverse ' : '';
+  console.log(`No ${dir}file path from "${from}" to "${to}" within ${data.maxDepth} hops.`);
+  if (data.fromCandidates.length > 1) {
+    console.log(
+      `\n  "${from}" matched ${data.fromCandidates.length} files — using: ${data.fromCandidates[0]}`,
+    );
+  }
+  if (data.toCandidates.length > 1) {
+    console.log(
+      `  "${to}" matched ${data.toCandidates.length} files — using: ${data.toCandidates[0]}`,
+    );
+  }
+}
+
+function printFilePathSteps(data: FilePathDataResult): void {
+  for (let i = 0; i < data.path.length; i++) {
+    const indent = '  '.repeat(i + 1);
+    if (i === 0) {
+      console.log(`${indent}${data.path[i]}`);
+    } else {
+      console.log(`${indent}→ ${data.path[i]}`);
+    }
+  }
+  if (data.alternateCount > 0) {
+    console.log(
+      `\n  (${data.alternateCount} alternate shortest ${data.alternateCount === 1 ? 'path' : 'paths'} at same depth)`,
+    );
+  }
+}
+
 function filePath(from: string, to: string, customDbPath: string, opts: PathOpts = {}): void {
   const data = filePathData(from, to, customDbPath, opts) as FilePathDataResult;
   if (outputResult(data as unknown as Record<string, unknown>, null, opts)) return;
@@ -137,18 +168,7 @@ function filePath(from: string, to: string, customDbPath: string, opts: PathOpts
   }
 
   if (!data.found) {
-    const dir = data.reverse ? 'reverse ' : '';
-    console.log(`No ${dir}file path from "${from}" to "${to}" within ${data.maxDepth} hops.`);
-    if (data.fromCandidates.length > 1) {
-      console.log(
-        `\n  "${from}" matched ${data.fromCandidates.length} files — using: ${data.fromCandidates[0]}`,
-      );
-    }
-    if (data.toCandidates.length > 1) {
-      console.log(
-        `  "${to}" matched ${data.toCandidates.length} files — using: ${data.toCandidates[0]}`,
-      );
-    }
+    printFilePathNotFound(from, to, data);
     return;
   }
 
@@ -162,18 +182,6 @@ function filePath(from: string, to: string, customDbPath: string, opts: PathOpts
   console.log(
     `\nFile path from ${from} to ${to} (${data.hops} ${data.hops === 1 ? 'hop' : 'hops'})${dir}:\n`,
   );
-  for (let i = 0; i < data.path.length; i++) {
-    const indent = '  '.repeat(i + 1);
-    if (i === 0) {
-      console.log(`${indent}${data.path[i]}`);
-    } else {
-      console.log(`${indent}→ ${data.path[i]}`);
-    }
-  }
-  if (data.alternateCount > 0) {
-    console.log(
-      `\n  (${data.alternateCount} alternate shortest ${data.alternateCount === 1 ? 'path' : 'paths'} at same depth)`,
-    );
-  }
+  printFilePathSteps(data);
   console.log();
 }

package/src/presentation/result-formatter.ts

@@ -1,7 +1,25 @@
 import { loadConfig } from '../infrastructure/config.js';
-import { printNdjson } from '../shared/paginate.js';
+import type { PaginationMeta } from '../shared/paginate.js';
 import { formatTable, truncEnd } from './table.js';
 
+/**
+ * Print data as newline-delimited JSON (NDJSON).
+ *
+ * Emits a `_meta` line with pagination info (if present), then one JSON
+ * line per item in the named array field.
+ */
+export function printNdjson(
+  data: Record<string, unknown> & { _pagination?: PaginationMeta },
+  field: string,
+): void {
+  if (data._pagination) console.log(JSON.stringify({ _meta: data._pagination }));
+  const items = data[field];
+  if (Array.isArray(items)) {
+    // console.log is intentional: NDJSON serialisation must go to stdout, not the structured logger
+    for (const item of items) console.log(JSON.stringify(item));
+  }
+}
+
 function flattenObject(obj: Record<string, unknown>, prefix = ''): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(obj)) {

package/src/presentation/viewer.ts

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { debug } from '../infrastructure/logger.js';
+import { toErrorMessage } from '../shared/errors.js';
 import { COMMUNITY_COLORS, DEFAULT_NODE_COLORS, DEFAULT_ROLE_COLORS } from './colors.js';
 
 // Re-export color constants so existing consumers are unaffected
@@ -74,8 +76,8 @@ export function loadPlotConfig(dir: string): PlotConfig {
             ...(raw.riskThresholds || {}),
           },
         };
-      } catch {
-        // Invalid JSON — use defaults
+      } catch (e) {
+        debug(`loadViewerConfig: invalid JSON in config file: ${toErrorMessage(e)}`);
       }
     }
   }
@@ -179,19 +181,45 @@ export interface ViewerData {
   seedNodeIds: (number | string)[];
 }
 
+interface ResolvedPlotConfig {
+  layoutOpts: LayoutOptions;
+  title: string;
+  layoutAlgorithm: string;
+  layoutDirection: string;
+  physicsEnabled: boolean;
+  sizeBy: string;
+  clusterBy: string;
+  effectiveColorBy: string;
+  effectiveRisk: boolean;
+}
+
+function resolvePlotConfig(cfg: PlotConfig): ResolvedPlotConfig {
+  return {
+    layoutOpts: buildLayoutOptions(cfg),
+    title: cfg.title || 'Codegraph',
+    layoutAlgorithm: cfg.layout?.algorithm || 'hierarchical',
+    layoutDirection: cfg.layout?.direction || 'LR',
+    physicsEnabled: cfg.physics?.enabled !== false,
+    sizeBy: cfg.sizeBy || 'uniform',
+    clusterBy: cfg.clusterBy || 'none',
+    effectiveColorBy:
+      cfg.overlays?.complexity && cfg.colorBy === 'kind' ? 'complexity' : cfg.colorBy || 'kind',
+    effectiveRisk: cfg.overlays?.risk || false,
+  };
+}
+
 export function renderPlotHTML(data: ViewerData, cfg: PlotConfig): string {
-  const layoutOpts = buildLayoutOptions(cfg);
-  const title = cfg.title || 'Codegraph';
-
-  // Resolve effective colorBy (overlays.complexity overrides)
-  const layoutAlgorithm = cfg.layout?.algorithm || 'hierarchical';
-  const layoutDirection = cfg.layout?.direction || 'LR';
-  const physicsEnabled = cfg.physics?.enabled !== false;
-  const sizeBy = cfg.sizeBy || 'uniform';
-  const clusterBy = cfg.clusterBy || 'none';
-  const effectiveColorBy =
-    cfg.overlays?.complexity && cfg.colorBy === 'kind' ? 'complexity' : cfg.colorBy || 'kind';
-  const effectiveRisk = cfg.overlays?.risk || false;
+  const {
+    layoutOpts,
+    title,
+    layoutAlgorithm,
+    layoutDirection,
+    physicsEnabled,
+    sizeBy,
+    clusterBy,
+    effectiveColorBy,
+    effectiveRisk,
+  } = resolvePlotConfig(cfg);
 
   return `<!DOCTYPE html>
 <html lang="en">

package/src/shared/errors.ts

@@ -77,3 +77,9 @@ export class BoundaryError extends CodegraphError {
 export function toErrorMessage(e: unknown): string {
   return e instanceof Error ? e.message : String(e);
 }
+
+/**
+ * Catch-suppression helpers (`suppressError`, `suppressErrorAsync`) live in
+ * `infrastructure/suppress.ts` to avoid a shared→infrastructure layer inversion.
+ * Import them from there instead of from this module.
+ */

package/src/shared/hierarchy.ts

@@ -1,10 +1,58 @@
 import { getClassHierarchy } from '../db/index.js';
-import type { BetterSqlite3Database, NodeRow } from '../types.js';
+import type { BetterSqlite3Database, NodeRow, Repository } from '../types.js';
 
+/**
+ * Resolve all methods in the class hierarchy that share the given method name.
+ *
+ * Accepts either a raw BetterSqlite3Database handle (legacy) or a Repository
+ * instance (preferred — works with both SqliteRepository and NativeRepository).
+ */
 export function resolveMethodViaHierarchy(
-  db: BetterSqlite3Database,
+  dbOrRepo: BetterSqlite3Database | Repository,
   methodName: string,
 ): NodeRow[] {
+  // Detect Repository vs raw DB by duck-typing on findNodesWithFanIn
+  if (
+    typeof (dbOrRepo as Repository).findNodesWithFanIn === 'function' &&
+    typeof (dbOrRepo as Repository).getClassHierarchy === 'function'
+  ) {
+    return resolveViaRepo(dbOrRepo as Repository, methodName);
+  }
+  return resolveViaRawDb(dbOrRepo as BetterSqlite3Database, methodName);
+}
+
+/** Strip fan_in from NodeRowWithFanIn to produce a plain NodeRow. */
+function stripFanIn(rows: Array<{ fan_in: number } & NodeRow>): NodeRow[] {
+  return rows.map(({ fan_in: _, ...rest }) => rest);
+}
+
+function resolveViaRepo(repo: Repository, methodName: string): NodeRow[] {
+  const methods = stripFanIn(repo.findNodesWithFanIn(`%.${methodName}`, { kinds: ['method'] }));
+
+  const results: NodeRow[] = [...methods];
+  for (const m of methods) {
+    const className = m.name.split('.')[0]!;
+    const classNodes = repo.findNodesWithFanIn(className, {
+      kinds: ['class'],
+      file: m.file,
+    });
+    const classNode = classNodes[0];
+    if (!classNode) continue;
+
+    const ancestors = repo.getClassHierarchy(classNode.id);
+    for (const ancestorId of ancestors) {
+      const ancestor = repo.findNodeById(ancestorId);
+      if (!ancestor) continue;
+      const parentMethods = stripFanIn(
+        repo.findNodesWithFanIn(`${ancestor.name}.${methodName}`, { kinds: ['method'] }),
+      );
+      results.push(...parentMethods);
+    }
+  }
+  return results;
+}
+
+function resolveViaRawDb(db: BetterSqlite3Database, methodName: string): NodeRow[] {
   const methods = db
     .prepare(`SELECT * FROM nodes WHERE kind = 'method' AND name LIKE ?`)
     .all(`%.${methodName}`) as NodeRow[];

package/src/shared/normalize.ts

@@ -3,6 +3,15 @@ interface DbHandle {
   prepare(sql: string): { get(...params: unknown[]): unknown };
 }
 
+/** Anything that can look up a file hash — either a raw DB or a Repository. */
+interface HashSource {
+  getFileHash(file: string): string | null;
+}
+
+function isHashSource(x: unknown): x is HashSource {
+  return typeof x === 'object' && x !== null && typeof (x as HashSource).getFileHash === 'function';
+}
+
 export function getFileHash(db: DbHandle, file: string): string | null {
   const row = db.prepare('SELECT hash FROM file_hashes WHERE file = ?').get(file) as
     | { hash: string }
@@ -55,25 +64,35 @@ interface RawSymbolRow {
   role?: string | null;
 }
 
+/**
+ * Resolve a file hash, using the cache when available.
+ * Accepts a raw DB handle (with .prepare) or a Repository (with .getFileHash).
+ */
+function resolveFileHash(
+  db: DbHandle | HashSource,
+  file: string,
+  hashCache?: Map<string, string | null>,
+): string | null {
+  const lookupHash = isHashSource(db)
+    ? (f: string) => db.getFileHash(f)
+    : (f: string) => getFileHash(db as DbHandle, f);
+  if (!hashCache) return lookupHash(file);
+  if (!hashCache.has(file)) {
+    hashCache.set(file, lookupHash(file));
+  }
+  return hashCache.get(file) ?? null;
+}
+
 /**
  * Normalize a raw DB/query row into the stable 7-field symbol shape.
+ * Accepts a raw DB handle (with .prepare), a Repository (with .getFileHash), or null.
  */
 export function normalizeSymbol(
   row: RawSymbolRow,
-  db?: DbHandle | null,
+  db?: DbHandle | HashSource | null,
   hashCache?: Map<string, string | null>,
 ): NormalizedSymbol {
-  let fileHash: string | null = null;
-  if (db) {
-    if (hashCache) {
-      if (!hashCache.has(row.file)) {
-        hashCache.set(row.file, getFileHash(db, row.file));
-      }
-      fileHash = hashCache.get(row.file) ?? null;
-    } else {
-      fileHash = getFileHash(db, row.file);
-    }
-  }
+  const fileHash = db ? resolveFileHash(db, row.file, hashCache) : null;
   return {
     name: row.name,
     kind: row.kind,

package/src/shared/paginate.ts

@@ -105,20 +105,3 @@ export function paginateResult<T extends Record<string, unknown>>(
   const { items, pagination } = paginate(arr, { limit, offset });
   return { ...result, [field]: items, _pagination: pagination };
 }
-
-/**
- * Print data as newline-delimited JSON (NDJSON).
- *
- * Emits a `_meta` line with pagination info (if present), then one JSON
- * line per item in the named array field.
- */
-export function printNdjson(
-  data: Record<string, unknown> & { _pagination?: PaginationMeta },
-  field: string,
-): void {
-  if (data._pagination) console.log(JSON.stringify({ _meta: data._pagination }));
-  const items = data[field];
-  if (Array.isArray(items)) {
-    for (const item of items) console.log(JSON.stringify(item));
-  }
-}