@optave/codegraph 3.1.3 → 3.1.5

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

@@ -0,0 +1,197 @@
+import path from 'node:path';
+import { kindIcon, moduleMapData, rolesData, statsData } from '../../domain/queries.js';
+import { outputResult } from '../../infrastructure/result-formatter.js';
+
+export async function stats(customDbPath, opts = {}) {
+  const data = statsData(customDbPath, { noTests: opts.noTests });
+
+  // Community detection summary (async import for lazy-loading)
+  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;
+
+  // Human-readable output
+  console.log('\n# Codegraph Stats\n');
+
+  // Nodes
+  console.log(`Nodes:     ${data.nodes.total} total`);
+  const kindEntries = Object.entries(data.nodes.byKind).sort((a, b) => b[1] - a[1]);
+  const kindParts = kindEntries.map(([k, v]) => `${k} ${v}`);
+  for (let i = 0; i < kindParts.length; i += 3) {
+    const row = kindParts
+      .slice(i, i + 3)
+      .map((p) => p.padEnd(18))
+      .join('');
+    console.log(`  ${row}`);
+  }
+
+  // Edges
+  console.log(`\nEdges:     ${data.edges.total} total`);
+  const edgeEntries = Object.entries(data.edges.byKind).sort((a, b) => b[1] - a[1]);
+  const edgeParts = edgeEntries.map(([k, v]) => `${k} ${v}`);
+  for (let i = 0; i < edgeParts.length; i += 3) {
+    const row = edgeParts
+      .slice(i, i + 3)
+      .map((p) => p.padEnd(18))
+      .join('');
+    console.log(`  ${row}`);
+  }
+
+  // Files
+  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 langParts = langEntries.map(([k, v]) => `${k} ${v}`);
+  for (let i = 0; i < langParts.length; i += 3) {
+    const row = langParts
+      .slice(i, i + 3)
+      .map((p) => p.padEnd(18))
+      .join('');
+    console.log(`  ${row}`);
+  }
+
+  // Cycles
+  console.log(
+    `\nCycles:    ${data.cycles.fileLevel} file-level, ${data.cycles.functionLevel} function-level`,
+  );
+
+  // Hotspots
+  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)}`,
+      );
+    }
+  }
+
+  // Embeddings
+  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');
+  }
+
+  // Quality
+  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}`);
+      }
+    }
+  }
+
+  // Roles
+  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 roleParts = Object.entries(data.roles)
+      .sort((a, b) => b[1] - a[1])
+      .map(([k, v]) => `${k} ${v}`);
+    for (let i = 0; i < roleParts.length; i += 3) {
+      const row = roleParts
+        .slice(i, i + 3)
+        .map((p) => p.padEnd(18))
+        .join('');
+      console.log(`  ${row}`);
+    }
+  }
+
+  // Complexity
+  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}`,
+    );
+  }
+
+  // Communities
+  if (data.communities) {
+    const cm = data.communities;
+    console.log(
+      `\nCommunities: ${cm.communityCount} detected | modularity: ${cm.modularity} | drift: ${cm.driftScore}%`,
+    );
+  }
+
+  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,58 @@
+import { kindIcon, pathData } from '../../domain/queries.js';
+import { outputResult } from '../../infrastructure/result-formatter.js';
+
+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) {
+    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})`,
+      );
+    }
+    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`,
+  );
+  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)`,
+    );
+  }
+  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';

package/src/presentation/result-formatter.js

@@ -0,0 +1,144 @@
+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 = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (
+      value !== null &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      Object.getPrototypeOf(value) === Object.prototype
+    ) {
+      Object.assign(result, flattenObject(value, fullKey));
+    } else if (Array.isArray(value)) {
+      result[fullKey] = JSON.stringify(value);
+    } else {
+      result[fullKey] = value;
+    }
+  }
+  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;
+  if (!Array.isArray(items)) return null;
+
+  const flatItems = items.map((item) =>
+    typeof item === 'object' && item !== null && !Array.isArray(item)
+      ? flattenObject(item)
+      : { value: item },
+  );
+  const columns = (() => {
+    const keys = new Set();
+    for (const item of flatItems) for (const key of Object.keys(item)) keys.add(key);
+    return [...keys];
+  })();
+  if (columns.length === 0) columns.push('value');
+
+  return { flatItems, columns };
+}
+
+/** Escape a value for CSV output (LF line endings). */
+function escapeCsv(val) {
+  const str = val == null ? '' : String(val);
+  if (str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  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) {
+  const prepared = prepareFlatItems(data, field);
+  if (!prepared) return false;
+  const { flatItems, columns } = prepared;
+
+  console.log(columns.map(escapeCsv).join(','));
+  for (const row of flatItems) {
+    console.log(columns.map((col) => escapeCsv(row[col])).join(','));
+  }
+  return true;
+}
+
+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')
+ */
+function printAutoTable(data, field) {
+  const prepared = prepareFlatItems(data, field);
+  if (!prepared) return false;
+  const { flatItems, columns } = prepared;
+
+  const colDefs = columns.map((col) => {
+    const maxLen = flatItems.reduce(
+      (max, item) => Math.max(max, String(item[col] ?? '').length),
+      col.length,
+    );
+    const isNumeric =
+      flatItems.length > 0 &&
+      flatItems.every((item) => {
+        const v = item[col];
+        return v == null || v === '' || (typeof v !== 'boolean' && Number.isFinite(Number(v)));
+      });
+    return {
+      header: col,
+      width: Math.min(maxLen, MAX_COL_WIDTH),
+      align: isNumeric ? 'right' : 'left',
+    };
+  });
+
+  const rows = flatItems.map((item) =>
+    columns.map((col) => truncEnd(String(item[col] ?? ''), MAX_COL_WIDTH)),
+  );
+
+  console.log(formatTable({ columns: colDefs, rows }));
+  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? })
+ * @returns {boolean} true if output was handled (caller should return early)
+ */
+export function outputResult(data, field, opts) {
+  if (opts.ndjson) {
+    printNdjson(data, field);
+    return true;
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return true;
+  }
+  if (opts.csv) {
+    return printCsv(data, field) !== false;
+  }
+  if (opts.table) {
+    return printAutoTable(data, field) !== false;
+  }
+  return false;
+}

package/src/presentation/sequence-renderer.js

@@ -0,0 +1,43 @@
+/**
+ * Mermaid sequence diagram renderer — pure data → string transform.
+ *
+ * Converts sequenceData() output into Mermaid sequenceDiagram syntax.
+ * No DB access, no I/O — just data in, formatted string out.
+ */
+
+/**
+ * Escape special Mermaid characters in labels.
+ */
+function escapeMermaid(str) {
+  return str
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/:/g, '#colon;')
+    .replace(/"/g, '#quot;');
+}
+
+/**
+ * Convert sequenceData result to Mermaid sequenceDiagram syntax.
+ * @param {{ participants, messages, truncated, depth }} seqResult
+ * @returns {string}
+ */
+export function sequenceToMermaid(seqResult) {
+  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) {
+    lines.push(
+      `    note right of ${seqResult.participants[0].id}: Truncated at depth ${seqResult.depth}`,
+    );
+  }
+
+  return lines.join('\n');
+}

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

@@ -1,6 +1,6 @@
+import { kindIcon } from '../domain/queries.js';
+import { sequenceData, sequenceToMermaid } from '../features/sequence.js';
 import { outputResult } from '../infrastructure/result-formatter.js';
-import { kindIcon } from '../queries.js';
-import { sequenceData, sequenceToMermaid } from '../sequence.js';
 
 /**
  * CLI entry point — format sequence data as mermaid, JSON, or ndjson.

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

@@ -1,7 +1,7 @@
 import path from 'node:path';
-import { hotspotsData, moduleBoundariesData, structureData } from '../structure.js';
+import { hotspotsData, moduleBoundariesData, structureData } from '../features/structure.js';
 
-export { structureData, hotspotsData, moduleBoundariesData };
+export { hotspotsData, moduleBoundariesData, structureData };
 
 export function formatStructure(data) {
   if (data.count === 0) return 'No directory structure found. Run "codegraph build" first.';

package/src/presentation/table.js

@@ -0,0 +1,47 @@
+/**
+ * Shared table formatting utilities for CLI output.
+ *
+ * Pure data → formatted string transforms. No I/O — callers handle printing.
+ */
+
+/**
+ * Format a table with aligned columns.
+ *
+ * @param {object} opts
+ * @param {Array<{ header: string, width: number, align?: 'left'|'right' }>} opts.columns
+ * @param {string[][]} opts.rows - Each row is an array of string cell values
+ * @param {number} [opts.indent=2] - Leading spaces per line
+ * @returns {string} Formatted table string (header + separator + data rows)
+ */
+export function formatTable({ columns, rows, indent = 2 }) {
+  const prefix = ' '.repeat(indent);
+  const header = columns
+    .map((c) => (c.align === 'right' ? c.header.padStart(c.width) : c.header.padEnd(c.width)))
+    .join(' ');
+  const separator = columns.map((c) => '\u2500'.repeat(c.width)).join(' ');
+  const lines = [`${prefix}${header}`, `${prefix}${separator}`];
+  for (const row of rows) {
+    const cells = columns.map((c, i) => {
+      const val = row[i] ?? '';
+      return c.align === 'right' ? val.padStart(c.width) : val.padEnd(c.width);
+    });
+    lines.push(`${prefix}${cells.join(' ')}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Truncate a string from the end, appending '\u2026' if truncated.
+ */
+export function truncEnd(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return `${str.slice(0, maxLen - 1)}\u2026`;
+}
+
+/**
+ * Truncate a string from the start, prepending '\u2026' if truncated.
+ */
+export function truncStart(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return `\u2026${str.slice(-(maxLen - 1))}`;
+}

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

@@ -1,5 +1,5 @@
+import { triageData } from '../features/triage.js';
 import { outputResult } from '../infrastructure/result-formatter.js';
-import { triageData } from '../triage.js';
 
 /**
  * Print triage results to console.