@optave/codegraph 3.1.4 → 3.2.0

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

@@ -0,0 +1,329 @@
+import {
+  childrenData,
+  contextData,
+  explainData,
+  kindIcon,
+  queryNameData,
+  whereData,
+} from '../../domain/queries.js';
+import { outputResult } from '../../infrastructure/result-formatter.js';
+
+export function where(target, customDbPath, opts = {}) {
+  const data = whereData(target, customDbPath, opts);
+  if (outputResult(data, 'results', opts)) return;
+
+  if (data.results.length === 0) {
+    console.log(
+      data.mode === 'file'
+        ? `No file matching "${target}" in graph`
+        : `No symbol matching "${target}" in graph`,
+    );
+    return;
+  }
+
+  if (data.mode === 'symbol') {
+    for (const r of data.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');
+      }
+    }
+  } else {
+    for (const r of data.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(', ')}`);
+      }
+    }
+  }
+  console.log();
+}
+
+export function queryName(name, customDbPath, opts = {}) {
+  const data = queryNameData(name, customDbPath, {
+    noTests: opts.noTests,
+    limit: opts.limit,
+    offset: opts.offset,
+  });
+  if (outputResult(data, 'results', opts)) return;
+
+  if (data.results.length === 0) {
+    console.log(`No results for "${name}"`);
+    return;
+  }
+
+  console.log(`\nResults for "${name}":\n`);
+  for (const r of data.results) {
+    console.log(`  ${kindIcon(r.kind)} ${r.name} (${r.kind}) -- ${r.file}:${r.line}`);
+    if (r.callees.length > 0) {
+      console.log(`    -> calls/uses:`);
+      for (const c of r.callees.slice(0, 15))
+        console.log(`      -> ${c.name} (${c.edgeKind}) ${c.file}:${c.line}`);
+      if (r.callees.length > 15) console.log(`      ... and ${r.callees.length - 15} more`);
+    }
+    if (r.callers.length > 0) {
+      console.log(`    <- called by:`);
+      for (const c of r.callers.slice(0, 15))
+        console.log(`      <- ${c.name} (${c.edgeKind}) ${c.file}:${c.line}`);
+      if (r.callers.length > 15) console.log(`      ... and ${r.callers.length - 15} more`);
+    }
+    console.log();
+  }
+}
+
+export function context(name, customDbPath, opts = {}) {
+  const data = contextData(name, customDbPath, opts);
+  if (outputResult(data, 'results', opts)) return;
+
+  if (data.results.length === 0) {
+    console.log(`No function/method/class matching "${name}"`);
+    return;
+  }
+
+  for (const r of data.results) {
+    renderContextResult(r);
+  }
+}
+
+export function children(name, customDbPath, opts = {}) {
+  const data = childrenData(name, customDbPath, opts);
+  if (outputResult(data, 'results', opts)) return;
+
+  if (data.results.length === 0) {
+    console.log(`No symbol matching "${name}"`);
+    return;
+  }
+  for (const r of data.results) {
+    console.log(`\n${kindIcon(r.kind)} ${r.name}  ${r.file}:${r.line}`);
+    if (r.children.length === 0) {
+      console.log('  (no children)');
+    } else {
+      for (const c of r.children) {
+        console.log(`  ${kindIcon(c.kind)} ${c.name}  :${c.line}`);
+      }
+    }
+  }
+}
+
+function renderContextResult(r) {
+  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.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();
+  }
+
+  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.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();
+  }
+
+  if (r.source) {
+    console.log('## Source');
+    for (const line of r.source.split('\n')) {
+      console.log(`  ${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}`);
+        }
+      }
+    }
+    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();
+  }
+
+  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.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)');
+    console.log();
+  }
+}
+
+function renderFileExplain(r) {
+  const publicCount = r.publicApi.length;
+  const internalCount = r.internal.length;
+  const lineInfo = r.lineCount ? `${r.lineCount} lines, ` : '';
+  console.log(`\n# ${r.file}`);
+  console.log(
+    `  ${lineInfo}${r.symbolCount} symbols (${publicCount} exported, ${internalCount} internal)`,
+  );
+
+  if (r.imports.length > 0) {
+    console.log(`  Imports: ${r.imports.map((i) => i.file).join(', ')}`);
+  }
+  if (r.importedBy.length > 0) {
+    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}`);
+    }
+  }
+
+  if (r.dataFlow.length > 0) {
+    console.log(`\n## Data Flow`);
+    for (const df of r.dataFlow) {
+      console.log(`  ${df.caller} -> ${df.callees.join(', ')}`);
+    }
+  }
+  console.log();
+}
+
+function renderFunctionExplain(r, indent = '') {
+  const lineRange = r.endLine ? `${r.line}-${r.endLine}` : `${r.line}`;
+  const lineInfo = r.lineCount ? `${r.lineCount} lines` : '';
+  const summaryPart = r.summary ? ` | ${r.summary}` : '';
+  const roleTag = r.role ? ` [${r.role}]` : '';
+  const depthLevel = r._depth || 0;
+  const heading = depthLevel === 0 ? '#' : '##'.padEnd(depthLevel + 2, '#');
+  console.log(`\n${indent}${heading} ${r.name} (${r.kind})${roleTag}  ${r.file}:${lineRange}`);
+  if (lineInfo || r.summary) {
+    console.log(`${indent}  ${lineInfo}${summaryPart}`);
+  }
+  if (r.signature) {
+    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}`,
+    );
+  }
+
+  if (r.callees.length > 0) {
+    console.log(`\n${indent}  Calls (${r.callees.length}):`);
+    for (const c of r.callees) {
+      console.log(`${indent}    ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}`);
+    }
+  }
+
+  if (r.callers.length > 0) {
+    console.log(`\n${indent}  Called by (${r.callers.length}):`);
+    for (const c of r.callers) {
+      console.log(`${indent}    ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}`);
+    }
+  }
+
+  if (r.relatedTests.length > 0) {
+    const label = r.relatedTests.length === 1 ? 'file' : 'files';
+    console.log(`\n${indent}  Tests (${r.relatedTests.length} ${label}):`);
+    for (const t of r.relatedTests) {
+      console.log(`${indent}    ${t.file}`);
+    }
+  }
+
+  if (r.callees.length === 0 && r.callers.length === 0) {
+    console.log(`${indent}  (no call edges found -- may be invoked dynamically or via re-exports)`);
+  }
+
+  if (r.depDetails && r.depDetails.length > 0) {
+    console.log(`\n${indent}  --- Dependencies (depth ${depthLevel + 1}) ---`);
+    for (const dep of r.depDetails) {
+      renderFunctionExplain(dep, `${indent}  `);
+    }
+  }
+  console.log();
+}
+
+export function explain(target, customDbPath, opts = {}) {
+  const data = explainData(target, customDbPath, opts);
+  if (outputResult(data, 'results', opts)) return;
+
+  if (data.results.length === 0) {
+    console.log(`No ${data.kind === 'file' ? 'file' : 'function/symbol'} matching "${target}"`);
+    return;
+  }
+
+  if (data.kind === 'file') {
+    for (const r of data.results) {
+      renderFileExplain(r);
+    }
+  } else {
+    for (const r of data.results) {
+      renderFunctionExplain(r);
+    }
+  }
+}

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

@@ -0,0 +1,196 @@
+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) {
+  const parts = entries.map(([k, v]) => `${k} ${v}`);
+  for (let i = 0; i < parts.length; i += 3) {
+    const row = parts
+      .slice(i, i + 3)
+      .map((p) => p.padEnd(padWidth))
+      .join('');
+    console.log(`  ${row}`);
+  }
+}
+
+function printNodes(data) {
+  console.log(`Nodes:     ${data.nodes.total} total`);
+  const kindEntries = Object.entries(data.nodes.byKind).sort((a, b) => b[1] - a[1]);
+  printCountGrid(kindEntries, 18);
+}
+
+function printEdges(data) {
+  console.log(`\nEdges:     ${data.edges.total} total`);
+  const edgeEntries = Object.entries(data.edges.byKind).sort((a, b) => b[1] - a[1]);
+  printCountGrid(edgeEntries, 18);
+}
+
+function printFiles(data) {
+  console.log(`\nFiles:     ${data.files.total} (${data.files.languages} languages)`);
+  const langEntries = Object.entries(data.files.byLanguage).sort((a, b) => b[1] - a[1]);
+  printCountGrid(langEntries, 18);
+}
+
+function printCycles(data) {
+  console.log(
+    `\nCycles:    ${data.cycles.fileLevel} file-level, ${data.cycles.functionLevel} function-level`,
+  );
+}
+
+function printHotspots(data) {
+  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];
+      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)}`,
+      );
+    }
+  }
+}
+
+function printEmbeddings(data) {
+  if (data.embeddings) {
+    const e = data.embeddings;
+    console.log(
+      `\nEmbeddings: ${e.count} vectors (${e.model || 'unknown'}, ${e.dim || '?'}d) built ${e.builtAt || 'unknown'}`,
+    );
+  } else {
+    console.log('\nEmbeddings: not built');
+  }
+}
+
+function printQuality(data) {
+  if (data.quality) {
+    const q = data.quality;
+    const cc = q.callerCoverage;
+    const cf = q.callConfidence;
+    console.log(`\nGraph Quality: ${q.score}/100`);
+    console.log(
+      `  Caller coverage:  ${(cc.ratio * 100).toFixed(1)}% (${cc.covered}/${cc.total} functions have >=1 caller)`,
+    );
+    console.log(
+      `  Call confidence:  ${(cf.ratio * 100).toFixed(1)}% (${cf.highConf}/${cf.total} call edges are high-confidence)`,
+    );
+    if (q.falsePositiveWarnings.length > 0) {
+      console.log('  False-positive warnings:');
+      for (const fp of q.falsePositiveWarnings) {
+        console.log(`    ! ${fp.name} (${fp.callerCount} callers) -- ${fp.file}:${fp.line}`);
+      }
+    }
+  }
+}
+
+function printRoles(data) {
+  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]);
+    printCountGrid(roleEntries, 18);
+  }
+}
+
+function printComplexity(data) {
+  if (data.complexity) {
+    const cx = data.complexity;
+    const miPart = cx.avgMI != null ? ` | avg MI: ${cx.avgMI} | min MI: ${cx.minMI}` : '';
+    console.log(
+      `\nComplexity: ${cx.analyzed} functions | avg cognitive: ${cx.avgCognitive} | avg cyclomatic: ${cx.avgCyclomatic} | max cognitive: ${cx.maxCognitive}${miPart}`,
+    );
+  }
+}
+
+function printCommunities(data) {
+  if (data.communities) {
+    const cm = data.communities;
+    console.log(
+      `\nCommunities: ${cm.communityCount} detected | modularity: ${cm.modularity} | drift: ${cm.driftScore}%`,
+    );
+  }
+}
+
+export async function stats(customDbPath, opts = {}) {
+  const data = statsData(customDbPath, { noTests: opts.noTests });
+
+  try {
+    const { communitySummaryForStats } = await import('../../features/communities.js');
+    data.communities = communitySummaryForStats(customDbPath, { noTests: opts.noTests });
+  } catch {
+    /* graphology may not be available */
+  }
+
+  if (outputResult(data, null, opts)) return;
+
+  console.log('\n# Codegraph Stats\n');
+  printNodes(data);
+  printEdges(data);
+  printFiles(data);
+  printCycles(data);
+  printHotspots(data);
+  printEmbeddings(data);
+  printQuality(data);
+  printRoles(data);
+  printComplexity(data);
+  printCommunities(data);
+  console.log();
+}
+
+export function moduleMap(customDbPath, limit = 20, opts = {}) {
+  const data = moduleMapData(customDbPath, limit, { noTests: opts.noTests });
+  if (outputResult(data, 'topNodes', opts)) return;
+
+  console.log(`\nModule map (top ${limit} most-connected nodes):\n`);
+  const dirs = new Map();
+  for (const n of data.topNodes) {
+    if (!dirs.has(n.dir)) dirs.set(n.dir, []);
+    dirs.get(n.dir).push(n);
+  }
+  for (const [dir, files] of [...dirs].sort()) {
+    console.log(`  [${dir}/]`);
+    for (const f of files) {
+      const coupling = f.inEdges + f.outEdges;
+      const bar = '#'.repeat(Math.min(coupling, 40));
+      console.log(
+        `    ${path.basename(f.file).padEnd(35)} <-${String(f.inEdges).padStart(3)} ->${String(f.outEdges).padStart(3)}  =${String(coupling).padStart(3)}  ${bar}`,
+      );
+    }
+  }
+  console.log(
+    `\n  Total: ${data.stats.totalFiles} files, ${data.stats.totalNodes} symbols, ${data.stats.totalEdges} edges\n`,
+  );
+}
+
+export function roles(customDbPath, opts = {}) {
+  const data = rolesData(customDbPath, opts);
+  if (outputResult(data, 'symbols', opts)) return;
+
+  if (data.count === 0) {
+    console.log('No classified symbols found. Run "codegraph build" first.');
+    return;
+  }
+
+  const total = data.count;
+  console.log(`\nNode roles (${total} symbols):\n`);
+
+  const summaryParts = Object.entries(data.summary)
+    .sort((a, b) => b[1] - a[1])
+    .map(([role, count]) => `${role}: ${count}`);
+  console.log(`  ${summaryParts.join('  ')}\n`);
+
+  const byRole = {};
+  for (const s of data.symbols) {
+    if (!byRole[s.role]) byRole[s.role] = [];
+    byRole[s.role].push(s);
+  }
+
+  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();
+  }
+}

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

@@ -0,0 +1,65 @@
+import { kindIcon, pathData } from '../../domain/queries.js';
+import { outputResult } from '../../infrastructure/result-formatter.js';
+
+function printNotFound(from, to, data) {
+  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) {
+  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, to, customDbPath, opts = {}) {
+  const data = pathData(from, to, customDbPath, opts);
+  if (outputResult(data, 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();
+}

package/src/presentation/queries-cli.js

@@ -0,0 +1,27 @@
+/**
+ * queries-cli.js — barrel re-export for backward compatibility.
+ *
+ * The actual implementations live in queries-cli/ split by concern:
+ *   path.js     — symbolPath
+ *   overview.js — stats, moduleMap, roles
+ *   inspect.js  — where, queryName, context, children, explain
+ *   impact.js   — fileDeps, fnDeps, impactAnalysis, fnImpact, diffImpact
+ *   exports.js  — fileExports
+ */
+export {
+  children,
+  context,
+  diffImpact,
+  explain,
+  fileDeps,
+  fileExports,
+  fnDeps,
+  fnImpact,
+  impactAnalysis,
+  moduleMap,
+  queryName,
+  roles,
+  stats,
+  symbolPath,
+  where,
+} from './queries-cli/index.js';

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

@@ -18,4 +18,4 @@ export {
   stats,
   symbolPath,
   where,
-} from '../queries-cli.js';
+} from './queries-cli/index.js';