@optave/codegraph 3.3.1 → 3.4.1

package/src/presentation/queries-cli/{overview.js → overview.ts}

@@ -2,7 +2,116 @@ import path from 'node:path';
 import { kindIcon, moduleMapData, rolesData, statsData } from '../../domain/queries.js';
 import { outputResult } from '../../infrastructure/result-formatter.js';
 
-function printCountGrid(entries, padWidth) {
+interface OutputOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  csv?: boolean;
+  table?: boolean;
+  noTests?: boolean;
+  role?: string | null;
+  file?: string;
+  kind?: string;
+  limit?: number;
+  offset?: number;
+  [key: string]: unknown;
+}
+
+interface StatsNodes {
+  total: number;
+  byKind: Record<string, number>;
+}
+
+interface StatsEdges {
+  total: number;
+  byKind: Record<string, number>;
+}
+
+interface StatsFiles {
+  total: number;
+  languages: number;
+  byLanguage: Record<string, number>;
+}
+
+interface StatsCycles {
+  fileLevel: number;
+  functionLevel: number;
+}
+
+interface Hotspot {
+  file: string;
+  fanIn: number;
+  fanOut: number;
+}
+
+interface EmbeddingsInfo {
+  count: number;
+  model?: string;
+  dim?: number;
+  builtAt?: string;
+}
+
+interface QualityInfo {
+  score: number;
+  callerCoverage: { ratio: number; covered: number; total: number };
+  callConfidence: { ratio: number; highConf: number; total: number };
+  falsePositiveWarnings: { name: string; callerCount: number; file: string; line: number }[];
+}
+
+interface ComplexityInfo {
+  analyzed: number;
+  avgCognitive: number;
+  avgCyclomatic: number;
+  maxCognitive: number;
+  avgMI?: number;
+  minMI?: number;
+}
+
+interface CommunityInfo {
+  communityCount: number;
+  modularity: number;
+  driftScore: number;
+}
+
+interface StatsData {
+  nodes: StatsNodes;
+  edges: StatsEdges;
+  files: StatsFiles;
+  cycles: StatsCycles;
+  hotspots: Hotspot[];
+  embeddings?: EmbeddingsInfo;
+  quality?: QualityInfo;
+  roles?: Record<string, number>;
+  complexity?: ComplexityInfo;
+  communities?: CommunityInfo;
+}
+
+interface TopNode {
+  dir: string;
+  file: string;
+  inEdges: number;
+  outEdges: number;
+}
+
+interface ModuleMapData {
+  topNodes: TopNode[];
+  stats: { totalFiles: number; totalNodes: number; totalEdges: number };
+}
+
+interface RoleSymbol {
+  kind: string;
+  name: string;
+  file: string;
+  line: number;
+  role: string;
+}
+
+interface RolesData {
+  count: number;
+  summary: Record<string, number>;
+  symbols: RoleSymbol[];
+}
+
+function printCountGrid(entries: [string, number][], padWidth: number): void {
   const parts = entries.map(([k, v]) => `${k} ${v}`);
   for (let i = 0; i < parts.length; i += 3) {
     const row = parts
@@ -13,35 +122,44 @@ function printCountGrid(entries, padWidth) {
   }
 }
 
-function printNodes(data) {
+function printNodes(data: StatsData): void {
   console.log(`Nodes:     ${data.nodes.total} total`);
-  const kindEntries = Object.entries(data.nodes.byKind).sort((a, b) => b[1] - a[1]);
+  const kindEntries = Object.entries(data.nodes.byKind).sort((a, b) => b[1] - a[1]) as [
+    string,
+    number,
+  ][];
   printCountGrid(kindEntries, 18);
 }
 
-function printEdges(data) {
+function printEdges(data: StatsData): void {
   console.log(`\nEdges:     ${data.edges.total} total`);
-  const edgeEntries = Object.entries(data.edges.byKind).sort((a, b) => b[1] - a[1]);
+  const edgeEntries = Object.entries(data.edges.byKind).sort((a, b) => b[1] - a[1]) as [
+    string,
+    number,
+  ][];
   printCountGrid(edgeEntries, 18);
 }
 
-function printFiles(data) {
+function printFiles(data: StatsData): void {
   console.log(`\nFiles:     ${data.files.total} (${data.files.languages} languages)`);
-  const langEntries = Object.entries(data.files.byLanguage).sort((a, b) => b[1] - a[1]);
+  const langEntries = Object.entries(data.files.byLanguage).sort((a, b) => b[1] - a[1]) as [
+    string,
+    number,
+  ][];
   printCountGrid(langEntries, 18);
 }
 
-function printCycles(data) {
+function printCycles(data: StatsData): void {
   console.log(
     `\nCycles:    ${data.cycles.fileLevel} file-level, ${data.cycles.functionLevel} function-level`,
   );
 }
 
-function printHotspots(data) {
+function printHotspots(data: StatsData): void {
   if (data.hotspots.length > 0) {
     console.log(`\nTop ${data.hotspots.length} coupling hotspots:`);
     for (let i = 0; i < data.hotspots.length; i++) {
-      const h = data.hotspots[i];
+      const h = data.hotspots[i]!;
       console.log(
         `  ${String(i + 1).padStart(2)}. ${h.file.padEnd(35)} fan-in: ${String(h.fanIn).padStart(3)}  fan-out: ${String(h.fanOut).padStart(3)}`,
       );
@@ -49,7 +167,7 @@ function printHotspots(data) {
   }
 }
 
-function printEmbeddings(data) {
+function printEmbeddings(data: StatsData): void {
   if (data.embeddings) {
     const e = data.embeddings;
     console.log(
@@ -60,7 +178,7 @@ function printEmbeddings(data) {
   }
 }
 
-function printQuality(data) {
+function printQuality(data: StatsData): void {
   if (data.quality) {
     const q = data.quality;
     const cc = q.callerCoverage;
@@ -81,16 +199,19 @@ function printQuality(data) {
   }
 }
 
-function printRoles(data) {
+function printRoles(data: StatsData): void {
   if (data.roles && Object.keys(data.roles).length > 0) {
     const total = Object.values(data.roles).reduce((a, b) => a + b, 0);
     console.log(`\nRoles:     ${total} classified symbols`);
-    const roleEntries = Object.entries(data.roles).sort((a, b) => b[1] - a[1]);
+    const roleEntries = Object.entries(data.roles).sort((a, b) => b[1] - a[1]) as [
+      string,
+      number,
+    ][];
     printCountGrid(roleEntries, 18);
   }
 }
 
-function printComplexity(data) {
+function printComplexity(data: StatsData): void {
   if (data.complexity) {
     const cx = data.complexity;
     const miPart = cx.avgMI != null ? ` | avg MI: ${cx.avgMI} | min MI: ${cx.minMI}` : '';
@@ -100,7 +221,7 @@ function printComplexity(data) {
   }
 }
 
-function printCommunities(data) {
+function printCommunities(data: StatsData): void {
   if (data.communities) {
     const cm = data.communities;
     console.log(
@@ -109,17 +230,17 @@ function printCommunities(data) {
   }
 }
 
-export async function stats(customDbPath, opts = {}) {
-  const data = statsData(customDbPath, { noTests: opts.noTests });
+export async function stats(customDbPath: string, opts: OutputOpts = {}): Promise<void> {
+  const data = statsData(customDbPath, { noTests: opts.noTests }) as StatsData;
 
   try {
     const { communitySummaryForStats } = await import('../../features/communities.js');
     data.communities = communitySummaryForStats(customDbPath, { noTests: opts.noTests });
   } catch {
-    /* graphology may not be available */
+    /* community detection is optional; silently skip on any error */
   }
 
-  if (outputResult(data, null, opts)) return;
+  if (outputResult(data as unknown as Record<string, unknown>, null, opts)) return;
 
   console.log('\n# Codegraph Stats\n');
   printNodes(data);
@@ -135,15 +256,15 @@ export async function stats(customDbPath, opts = {}) {
   console.log();
 }
 
-export function moduleMap(customDbPath, limit = 20, opts = {}) {
-  const data = moduleMapData(customDbPath, limit, { noTests: opts.noTests });
-  if (outputResult(data, 'topNodes', opts)) return;
+export function moduleMap(customDbPath: string, limit = 20, opts: OutputOpts = {}): void {
+  const data = moduleMapData(customDbPath, limit, { noTests: opts.noTests }) as ModuleMapData;
+  if (outputResult(data as unknown as Record<string, unknown>, 'topNodes', opts)) return;
 
   console.log(`\nModule map (top ${limit} most-connected nodes):\n`);
-  const dirs = new Map();
+  const dirs = new Map<string, TopNode[]>();
   for (const n of data.topNodes) {
     if (!dirs.has(n.dir)) dirs.set(n.dir, []);
-    dirs.get(n.dir).push(n);
+    dirs.get(n.dir)!.push(n);
   }
   for (const [dir, files] of [...dirs].sort()) {
     console.log(`  [${dir}/]`);
@@ -160,9 +281,9 @@ export function moduleMap(customDbPath, limit = 20, opts = {}) {
   );
 }
 
-export function roles(customDbPath, opts = {}) {
-  const data = rolesData(customDbPath, opts);
-  if (outputResult(data, 'symbols', opts)) return;
+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;
 
   if (data.count === 0) {
     console.log('No classified symbols found. Run "codegraph build" first.');
@@ -177,10 +298,10 @@ export function roles(customDbPath, opts = {}) {
     .map(([role, count]) => `${role}: ${count}`);
   console.log(`  ${summaryParts.join('  ')}\n`);
 
-  const byRole = {};
+  const byRole: Record<string, RoleSymbol[]> = {};
   for (const s of data.symbols) {
     if (!byRole[s.role]) byRole[s.role] = [];
-    byRole[s.role].push(s);
+    byRole[s.role]!.push(s);
   }
 
   for (const [role, symbols] of Object.entries(byRole)) {

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

@@ -0,0 +1,179 @@
+import { filePathData, kindIcon, pathData } from '../../domain/queries.js';
+import { outputResult } from '../../infrastructure/result-formatter.js';
+
+interface PathCandidate {
+  name: string;
+  file: string;
+  line: number;
+}
+
+interface PathStep {
+  kind: string;
+  name: string;
+  file: string;
+  line: number;
+  edgeKind?: string;
+}
+
+interface PathDataResult {
+  error?: string;
+  found?: boolean;
+  hops?: number;
+  reverse?: boolean;
+  maxDepth?: number;
+  path: PathStep[];
+  fromCandidates: PathCandidate[];
+  toCandidates: PathCandidate[];
+  alternateCount: number;
+}
+
+interface PathOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  csv?: boolean;
+  table?: boolean;
+  noTests?: boolean;
+  reverse?: boolean;
+  maxDepth?: number;
+  file?: string;
+  kind?: string;
+  [key: string]: unknown;
+}
+
+function printNotFound(from: string, to: string, data: PathDataResult): void {
+  const dir = data.reverse ? 'reverse ' : '';
+  console.log(`No ${dir}path from "${from}" to "${to}" within ${data.maxDepth} hops.`);
+  if (data.fromCandidates.length > 1) {
+    console.log(
+      `\n  "${from}" matched ${data.fromCandidates.length} symbols — using top match: ${data.fromCandidates[0]!.name} (${data.fromCandidates[0]!.file}:${data.fromCandidates[0]!.line})`,
+    );
+  }
+  if (data.toCandidates.length > 1) {
+    console.log(
+      `  "${to}" matched ${data.toCandidates.length} symbols — using top match: ${data.toCandidates[0]!.name} (${data.toCandidates[0]!.file}:${data.toCandidates[0]!.line})`,
+    );
+  }
+}
+
+function printPathSteps(data: PathDataResult): void {
+  for (let i = 0; i < data.path.length; i++) {
+    const n = data.path[i]!;
+    const indent = '  '.repeat(i + 1);
+    if (i === 0) {
+      console.log(`${indent}${kindIcon(n.kind)} ${n.name} (${n.kind}) -- ${n.file}:${n.line}`);
+    } else {
+      console.log(
+        `${indent}--[${n.edgeKind}]--> ${kindIcon(n.kind)} ${n.name} (${n.kind}) -- ${n.file}:${n.line}`,
+      );
+    }
+  }
+  if (data.alternateCount > 0) {
+    console.log(
+      `\n  (${data.alternateCount} alternate shortest ${data.alternateCount === 1 ? 'path' : 'paths'} at same depth)`,
+    );
+  }
+}
+
+export function symbolPath(
+  from: string,
+  to: string,
+  customDbPath: string,
+  opts: PathOpts = {},
+): void {
+  if (opts.file) {
+    filePath(from, to, customDbPath, opts);
+    return;
+  }
+
+  const data = pathData(from, to, customDbPath, opts) as PathDataResult;
+  if (outputResult(data as unknown as Record<string, unknown>, null, opts)) return;
+
+  if (data.error) {
+    console.log(data.error);
+    return;
+  }
+
+  if (!data.found) {
+    printNotFound(from, to, data);
+    return;
+  }
+
+  if (data.hops === 0) {
+    console.log(`\n"${from}" and "${to}" resolve to the same symbol (0 hops):`);
+    const n = data.path[0]!;
+    console.log(`  ${kindIcon(n.kind)} ${n.name} (${n.kind}) -- ${n.file}:${n.line}\n`);
+    return;
+  }
+
+  const dir = data.reverse ? ' (reverse)' : '';
+  console.log(
+    `\nPath from ${from} to ${to} (${data.hops} ${data.hops === 1 ? 'hop' : 'hops'})${dir}:\n`,
+  );
+  printPathSteps(data);
+  console.log();
+}
+
+// ── File-level path ──────────────────────────────────────────────────────
+
+interface FilePathDataResult {
+  error?: string;
+  found?: boolean;
+  hops?: number | null;
+  reverse?: boolean;
+  maxDepth?: number;
+  path: string[];
+  fromCandidates: string[];
+  toCandidates: string[];
+  alternateCount: number;
+}
+
+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;
+
+  if (data.error) {
+    console.log(data.error);
+    return;
+  }
+
+  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]}`,
+      );
+    }
+    return;
+  }
+
+  if (data.hops === 0) {
+    console.log(`\n"${from}" and "${to}" resolve to the same file (0 hops):`);
+    console.log(`  ${data.path[0]}\n`);
+    return;
+  }
+
+  const dir = data.reverse ? ' (reverse)' : '';
+  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)`,
+    );
+  }
+  console.log();
+}

package/src/presentation/{query.js → query.ts}

@@ -1,7 +1,3 @@
-/**
- * Re-export all query CLI wrappers from queries-cli.js.
- * This barrel file provides the standard src/commands/ import path.
- */
 export {
   children,
   context,

package/src/presentation/{result-formatter.js → result-formatter.ts}

@@ -2,16 +2,8 @@ import { loadConfig } from '../infrastructure/config.js';
 import { printNdjson } from '../shared/paginate.js';
 import { formatTable, truncEnd } from './table.js';
 
-/**
- * Flatten a nested object into dot-notation keys.
- * Arrays are JSON-stringified; nested objects are recursed.
- *
- * Note: this assumes input objects do not contain literal dot-notation keys
- * (e.g. `{ "a.b": 1 }`). If they do, flattened keys will silently collide
- * with nested paths (e.g. `{ a: { b: 2 } }` also produces `"a.b"`).
- */
-function flattenObject(obj, prefix = '') {
-  const result = {};
+function flattenObject(obj: Record<string, unknown>, prefix = ''): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(obj)) {
     const fullKey = prefix ? `${prefix}.${key}` : key;
     if (
@@ -20,7 +12,7 @@ function flattenObject(obj, prefix = '') {
       !Array.isArray(value) &&
       Object.getPrototypeOf(value) === Object.prototype
     ) {
-      Object.assign(result, flattenObject(value, fullKey));
+      Object.assign(result, flattenObject(value as Record<string, unknown>, fullKey));
     } else if (Array.isArray(value)) {
       result[fullKey] = JSON.stringify(value);
     } else {
@@ -30,22 +22,20 @@ function flattenObject(obj, prefix = '') {
   return result;
 }
 
-/**
- * Flatten items array and derive column names.
- * Shared by printCsv and printAutoTable.
- * @returns {{ flatItems: object[], columns: string[] } | null}
- */
-function prepareFlatItems(data, field) {
-  const items = field ? data[field] : data;
+function prepareFlatItems(
+  data: Record<string, unknown>,
+  field: string | null,
+): { flatItems: Record<string, unknown>[]; columns: string[] } | null {
+  const items = field ? (data[field] as unknown) : data;
   if (!Array.isArray(items)) return null;
 
-  const flatItems = items.map((item) =>
+  const flatItems = items.map((item: unknown) =>
     typeof item === 'object' && item !== null && !Array.isArray(item)
-      ? flattenObject(item)
+      ? flattenObject(item as Record<string, unknown>)
       : { value: item },
   );
   const columns = (() => {
-    const keys = new Set();
+    const keys = new Set<string>();
     for (const item of flatItems) for (const key of Object.keys(item)) keys.add(key);
     return [...keys];
   })();
@@ -54,8 +44,7 @@ function prepareFlatItems(data, field) {
   return { flatItems, columns };
 }
 
-/** Escape a value for CSV output (LF line endings). */
-function escapeCsv(val) {
+function escapeCsv(val: unknown): string {
   const str = val == null ? '' : String(val);
   if (str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r')) {
     return `"${str.replace(/"/g, '""')}"`;
@@ -63,12 +52,7 @@ function escapeCsv(val) {
   return str;
 }
 
-/**
- * Print data as CSV to stdout.
- * @param {object} data - Result object from a *Data() function
- * @param {string} field - Array field name (e.g. 'results')
- */
-function printCsv(data, field) {
+function printCsv(data: Record<string, unknown>, field: string | null): boolean {
   const prepared = prepareFlatItems(data, field);
   if (!prepared) return false;
   const { flatItems, columns } = prepared;
@@ -82,13 +66,15 @@ function printCsv(data, field) {
 
 const MAX_COL_WIDTH = 40;
 
-/**
- * Print data as an aligned table to stdout.
- * @param {object} data - Result object from a *Data() function
- * @param {string} field - Array field name (e.g. 'results')
- * @param {{ maxColWidth?: number }} [displayOpts]
- */
-function printAutoTable(data, field, displayOpts = {}) {
+interface DisplayOpts {
+  maxColWidth?: number;
+}
+
+function printAutoTable(
+  data: Record<string, unknown>,
+  field: string | null,
+  displayOpts: DisplayOpts = {},
+): boolean {
   const prepared = prepareFlatItems(data, field);
   if (!prepared) return false;
   const { flatItems, columns } = prepared;
@@ -108,7 +94,7 @@ function printAutoTable(data, field, displayOpts = {}) {
     return {
       header: col,
       width: Math.min(maxLen, colWidth),
-      align: isNumeric ? 'right' : 'left',
+      align: isNumeric ? ('right' as const) : ('left' as const),
     };
   });
 
@@ -120,17 +106,26 @@ function printAutoTable(data, field, displayOpts = {}) {
   return true;
 }
 
-/**
- * Shared JSON / NDJSON / table / CSV output dispatch for CLI wrappers.
- *
- * @param {object} data   - Result object from a *Data() function
- * @param {string} field  - Array field name for NDJSON streaming (e.g. 'results')
- * @param {object} opts   - CLI options ({ json?, ndjson?, table?, csv?, display?: { maxColWidth? } })
- * @returns {boolean} true if output was handled (caller should return early)
- */
-export function outputResult(data, field, opts) {
+export interface OutputOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  table?: boolean;
+  csv?: boolean;
+  display?: DisplayOpts;
+}
+
+export function outputResult(
+  data: Record<string, any>,
+  field: string | null,
+  opts: OutputOpts,
+): boolean {
   if (opts.ndjson) {
-    printNdjson(data, field);
+    if (field === null) {
+      // No field key — emit the whole object as a single NDJSON line
+      console.log(JSON.stringify(data));
+    } else {
+      printNdjson(data, field);
+    }
     return true;
   }
   if (opts.json) {
@@ -141,7 +136,7 @@ export function outputResult(data, field, opts) {
     return printCsv(data, field) !== false;
   }
   if (opts.table) {
-    const displayOpts = opts.display ?? loadConfig().display;
+    const displayOpts = opts.display ?? (loadConfig() as { display: DisplayOpts }).display;
     return printAutoTable(data, field, displayOpts) !== false;
   }
   return false;

package/src/presentation/sequence-renderer.ts

@@ -0,0 +1,46 @@
+interface Participant {
+  id: string;
+  label: string;
+}
+
+interface SequenceMessage {
+  from: string;
+  to: string;
+  type: string;
+  label: string;
+}
+
+interface SequenceRenderData {
+  participants: Participant[];
+  messages: SequenceMessage[];
+  truncated: boolean;
+  depth: number;
+}
+
+function escapeMermaid(str: string): string {
+  return str
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/:/g, '#colon;')
+    .replace(/"/g, '#quot;');
+}
+
+export function sequenceToMermaid(seqResult: SequenceRenderData): string {
+  const lines = ['sequenceDiagram'];
+
+  for (const p of seqResult.participants) {
+    lines.push(`    participant ${p.id} as ${escapeMermaid(p.label)}`);
+  }
+
+  for (const msg of seqResult.messages) {
+    const arrow = msg.type === 'return' ? '-->>' : '->>';
+    lines.push(`    ${msg.from}${arrow}${msg.to}: ${escapeMermaid(msg.label)}`);
+  }
+
+  if (seqResult.truncated && seqResult.participants.length > 0) {
+    const firstParticipant = seqResult.participants[0]!;
+    lines.push(`    note right of ${firstParticipant.id}: Truncated at depth ${seqResult.depth}`);
+  }
+
+  return lines.join('\n');
+}