@optave/codegraph 3.1.4 → 3.2.0

package/src/presentation/result-formatter.js

@@ -1,11 +1,128 @@
-import { printNdjson } from '../paginate.js';
+import { printNdjson } from '../shared/paginate.js';
+import { formatTable, truncEnd } from './table.js';
 
 /**
- * Shared JSON / NDJSON output dispatch for CLI wrappers.
+ * 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? })
+ * @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) {
@@ -17,5 +134,11 @@ export function outputResult(data, field, opts) {
     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/{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,5 +1,5 @@
 import path from 'node:path';
-import { hotspotsData, moduleBoundariesData, structureData } from '../structure.js';
+import { hotspotsData, moduleBoundariesData, structureData } from '../features/structure.js';
 
 export { hotspotsData, moduleBoundariesData, structureData };
 

package/src/presentation/table.js

@@ -37,11 +37,3 @@ 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.

package/src/{constants.js → shared/constants.js}

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { SUPPORTED_EXTENSIONS } from './parser.js';
+import { SUPPORTED_EXTENSIONS } from '../domain/parser.js';
 
 export const IGNORE_DIRS = new Set([
   'node_modules',

package/src/shared/file-utils.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { debug } from '../logger.js';
-import { LANGUAGE_REGISTRY } from '../parser.js';
+import { LANGUAGE_REGISTRY } from '../domain/parser.js';
+import { debug } from '../infrastructure/logger.js';
 
 /**
  * Resolve a file path relative to repoRoot, rejecting traversal outside the repo.

package/src/shared/generators.js

@@ -1,6 +1,7 @@
-import { iterateFunctionNodes, openReadonlyOrFail } from '../db.js';
+import { iterateFunctionNodes, openReadonlyOrFail } from '../db/index.js';
+import { buildFileConditionSQL } from '../db/query-builder.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
-import { ALL_SYMBOL_KINDS } from '../kinds.js';
+import { ALL_SYMBOL_KINDS } from './kinds.js';
 
 /**
  * Generator: stream functions one-by-one using .iterate() for memory efficiency.
@@ -52,9 +53,12 @@ export function* iterRoles(customDbPath, opts = {}) {
       conditions.push('role = ?');
       params.push(opts.role);
     }
-    if (opts.file) {
-      conditions.push('file LIKE ?');
-      params.push(`%${opts.file}%`);
+    {
+      const fc = buildFileConditionSQL(opts.file, 'file');
+      if (fc.sql) {
+        conditions.push(fc.sql.replace(/^ AND /, ''));
+        params.push(...fc.params);
+      }
     }
 
     const stmt = db.prepare(

package/src/shared/hierarchy.js

@@ -1,4 +1,4 @@
-import { getClassHierarchy } from '../db.js';
+import { getClassHierarchy } from '../db/index.js';
 
 export function resolveMethodViaHierarchy(db, methodName) {
   const methods = db

package/src/{kinds.js → shared/kinds.js}

@@ -47,4 +47,4 @@ export const STRUCTURAL_EDGE_KINDS = ['parameter_of', 'receiver'];
 // Full set for MCP enum and validation
 export const EVERY_EDGE_KIND = [...CORE_EDGE_KINDS, ...STRUCTURAL_EDGE_KINDS];
 
-export const VALID_ROLES = ['entry', 'core', 'utility', 'adapter', 'dead', 'leaf'];
+export const VALID_ROLES = ['entry', 'core', 'utility', 'adapter', 'dead', 'test-only', 'leaf'];

package/src/analysis/context.js

@@ -1,408 +0,0 @@
-import path from 'node:path';
-import {
-  findCallees,
-  findCallers,
-  findCrossFileCallTargets,
-  findDbPath,
-  findFileNodes,
-  findImportSources,
-  findImportTargets,
-  findIntraFileCallEdges,
-  findNodeChildren,
-  findNodesByFile,
-  getComplexityForNode,
-  openReadonlyOrFail,
-} from '../db.js';
-import { isTestFile } from '../infrastructure/test-filter.js';
-import { paginateResult } from '../paginate.js';
-import {
-  createFileLinesReader,
-  extractSignature,
-  extractSummary,
-  isFileLikeTarget,
-  readSourceRange,
-} from '../shared/file-utils.js';
-import { resolveMethodViaHierarchy } from '../shared/hierarchy.js';
-import { normalizeSymbol } from '../shared/normalize.js';
-import { findMatchingNodes } from './symbol-lookup.js';
-
-function explainFileImpl(db, target, getFileLines) {
-  const fileNodes = findFileNodes(db, `%${target}%`);
-  if (fileNodes.length === 0) return [];
-
-  return fileNodes.map((fn) => {
-    const symbols = findNodesByFile(db, fn.file);
-
-    // IDs of symbols that have incoming calls from other files (public)
-    const publicIds = findCrossFileCallTargets(db, fn.file);
-
-    const fileLines = getFileLines(fn.file);
-    const mapSymbol = (s) => ({
-      name: s.name,
-      kind: s.kind,
-      line: s.line,
-      role: s.role || null,
-      summary: fileLines ? extractSummary(fileLines, s.line) : null,
-      signature: fileLines ? extractSignature(fileLines, s.line) : null,
-    });
-
-    const publicApi = symbols.filter((s) => publicIds.has(s.id)).map(mapSymbol);
-    const internal = symbols.filter((s) => !publicIds.has(s.id)).map(mapSymbol);
-
-    // Imports / importedBy
-    const imports = findImportTargets(db, fn.id).map((r) => ({ file: r.file }));
-
-    const importedBy = findImportSources(db, fn.id).map((r) => ({ file: r.file }));
-
-    // Intra-file data flow
-    const intraEdges = findIntraFileCallEdges(db, fn.file);
-
-    const dataFlowMap = new Map();
-    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);
-    }
-    const dataFlow = [...dataFlowMap.entries()].map(([caller, callees]) => ({
-      caller,
-      callees,
-    }));
-
-    // Line count: prefer node_metrics (actual), fall back to MAX(end_line)
-    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;
-    if (!lineCount) {
-      const maxLine = db
-        .prepare(`SELECT MAX(end_line) as max_end FROM nodes WHERE file = ?`)
-        .get(fn.file);
-      lineCount = maxLine?.max_end || null;
-    }
-
-    return {
-      file: fn.file,
-      lineCount,
-      symbolCount: symbols.length,
-      publicApi,
-      internal,
-      imports,
-      importedBy,
-      dataFlow,
-    };
-  });
-}
-
-function explainFunctionImpl(db, target, noTests, getFileLines) {
-  let nodes = db
-    .prepare(
-      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function','method','class','interface','type','struct','enum','trait','record','module') ORDER BY file, line`,
-    )
-    .all(`%${target}%`);
-  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
-  if (nodes.length === 0) return [];
-
-  const hc = new Map();
-  return nodes.slice(0, 10).map((node) => {
-    const fileLines = getFileLines(node.file);
-    const lineCount = node.end_line ? node.end_line - node.line + 1 : null;
-    const summary = fileLines ? extractSummary(fileLines, node.line) : null;
-    const signature = fileLines ? extractSignature(fileLines, node.line) : null;
-
-    const callees = findCallees(db, node.id).map((c) => ({
-      name: c.name,
-      kind: c.kind,
-      file: c.file,
-      line: c.line,
-    }));
-
-    let callers = findCallers(db, node.id).map((c) => ({
-      name: c.name,
-      kind: c.kind,
-      file: c.file,
-      line: c.line,
-    }));
-    if (noTests) callers = callers.filter((c) => !isTestFile(c.file));
-
-    const testCallerRows = findCallers(db, node.id);
-    const seenFiles = new Set();
-    const relatedTests = testCallerRows
-      .filter((r) => isTestFile(r.file) && !seenFiles.has(r.file) && seenFiles.add(r.file))
-      .map((r) => ({ file: r.file }));
-
-    // Complexity metrics
-    let complexityMetrics = null;
-    try {
-      const cRow = getComplexityForNode(db, node.id);
-      if (cRow) {
-        complexityMetrics = {
-          cognitive: cRow.cognitive,
-          cyclomatic: cRow.cyclomatic,
-          maxNesting: cRow.max_nesting,
-          maintainabilityIndex: cRow.maintainability_index || 0,
-          halsteadVolume: cRow.halstead_volume || 0,
-        };
-      }
-    } catch {
-      /* table may not exist */
-    }
-
-    return {
-      ...normalizeSymbol(node, db, hc),
-      lineCount,
-      summary,
-      signature,
-      complexity: complexityMetrics,
-      callees,
-      callers,
-      relatedTests,
-    };
-  });
-}
-
-// ─── Exported functions ──────────────────────────────────────────────────
-
-export function contextData(name, customDbPath, opts = {}) {
-  const db = openReadonlyOrFail(customDbPath);
-  try {
-    const depth = opts.depth || 0;
-    const noSource = opts.noSource || false;
-    const noTests = opts.noTests || false;
-    const includeTests = opts.includeTests || false;
-
-    const dbPath = findDbPath(customDbPath);
-    const repoRoot = path.resolve(path.dirname(dbPath), '..');
-
-    const nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
-    if (nodes.length === 0) {
-      return { name, results: [] };
-    }
-
-    // No hardcoded slice — pagination handles bounding via limit/offset
-
-    const getFileLines = createFileLinesReader(repoRoot);
-
-    const results = nodes.map((node) => {
-      const fileLines = getFileLines(node.file);
-
-      // Source
-      const source = noSource
-        ? null
-        : readSourceRange(repoRoot, node.file, node.line, node.end_line);
-
-      // Signature
-      const signature = fileLines ? extractSignature(fileLines, node.line) : null;
-
-      // Callees
-      const calleeRows = findCallees(db, node.id);
-      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) : null;
-        let calleeSource = null;
-        if (depth >= 1) {
-          calleeSource = readSourceRange(repoRoot, c.file, c.line, c.end_line);
-        }
-        return {
-          name: c.name,
-          kind: c.kind,
-          file: c.file,
-          line: c.line,
-          endLine: c.end_line || null,
-          summary,
-          source: calleeSource,
-        };
-      });
-
-      // Deep callee expansion via BFS (depth > 1, capped at 5)
-      if (depth > 1) {
-        const visited = new Set(filteredCallees.map((c) => c.id));
-        visited.add(node.id);
-        let frontier = filteredCallees.map((c) => c.id);
-        const maxDepth = Math.min(depth, 5);
-        for (let d = 2; d <= maxDepth; d++) {
-          const nextFrontier = [];
-          for (const fid of frontier) {
-            const deeper = findCallees(db, fid);
-            for (const c of deeper) {
-              if (!visited.has(c.id) && (!noTests || !isTestFile(c.file))) {
-                visited.add(c.id);
-                nextFrontier.push(c.id);
-                const cLines = getFileLines(c.file);
-                callees.push({
-                  name: c.name,
-                  kind: c.kind,
-                  file: c.file,
-                  line: c.line,
-                  endLine: c.end_line || null,
-                  summary: cLines ? extractSummary(cLines, c.line) : null,
-                  source: readSourceRange(repoRoot, c.file, c.line, c.end_line),
-                });
-              }
-            }
-          }
-          frontier = nextFrontier;
-          if (frontier.length === 0) break;
-        }
-      }
-
-      // Callers
-      let callerRows = findCallers(db, node.id);
-
-      // Method hierarchy resolution
-      if (node.kind === 'method' && node.name.includes('.')) {
-        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);
-          callerRows.push(...extraCallers.map((c) => ({ ...c, viaHierarchy: rm.name })));
-        }
-      }
-      if (noTests) callerRows = callerRows.filter((c) => !isTestFile(c.file));
-
-      const callers = callerRows.map((c) => ({
-        name: c.name,
-        kind: c.kind,
-        file: c.file,
-        line: c.line,
-        viaHierarchy: c.viaHierarchy || undefined,
-      }));
-
-      // Related tests: callers that live in test files
-      const testCallerRows = findCallers(db, node.id);
-      const testCallers = testCallerRows.filter((c) => isTestFile(c.file));
-
-      const testsByFile = new Map();
-      for (const tc of testCallers) {
-        if (!testsByFile.has(tc.file)) testsByFile.set(tc.file, []);
-        testsByFile.get(tc.file).push(tc);
-      }
-
-      const relatedTests = [];
-      for (const [file] of testsByFile) {
-        const tLines = getFileLines(file);
-        const testNames = [];
-        if (tLines) {
-          for (const tl of tLines) {
-            const tm = tl.match(/(?:it|test|describe)\s*\(\s*['"`]([^'"`]+)['"`]/);
-            if (tm) testNames.push(tm[1]);
-          }
-        }
-        const testSource = includeTests && tLines ? tLines.join('\n') : undefined;
-        relatedTests.push({
-          file,
-          testCount: testNames.length,
-          testNames,
-          source: testSource,
-        });
-      }
-
-      // Complexity metrics
-      let complexityMetrics = null;
-      try {
-        const cRow = getComplexityForNode(db, node.id);
-        if (cRow) {
-          complexityMetrics = {
-            cognitive: cRow.cognitive,
-            cyclomatic: cRow.cyclomatic,
-            maxNesting: cRow.max_nesting,
-            maintainabilityIndex: cRow.maintainability_index || 0,
-            halsteadVolume: cRow.halstead_volume || 0,
-          };
-        }
-      } catch {
-        /* table may not exist */
-      }
-
-      // Children (parameters, properties, constants)
-      let nodeChildren = [];
-      try {
-        nodeChildren = findNodeChildren(db, node.id).map((c) => ({
-          name: c.name,
-          kind: c.kind,
-          line: c.line,
-          endLine: c.end_line || null,
-        }));
-      } catch {
-        /* parent_id column may not exist */
-      }
-
-      return {
-        name: node.name,
-        kind: node.kind,
-        file: node.file,
-        line: node.line,
-        role: node.role || null,
-        endLine: node.end_line || null,
-        source,
-        signature,
-        complexity: complexityMetrics,
-        children: nodeChildren.length > 0 ? nodeChildren : undefined,
-        callees,
-        callers,
-        relatedTests,
-      };
-    });
-
-    const base = { name, results };
-    return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
-  } finally {
-    db.close();
-  }
-}
-
-export function explainData(target, customDbPath, opts = {}) {
-  const db = openReadonlyOrFail(customDbPath);
-  try {
-    const noTests = opts.noTests || false;
-    const depth = opts.depth || 0;
-    const kind = isFileLikeTarget(target) ? 'file' : 'function';
-
-    const dbPath = findDbPath(customDbPath);
-    const repoRoot = path.resolve(path.dirname(dbPath), '..');
-
-    const getFileLines = createFileLinesReader(repoRoot);
-
-    const results =
-      kind === 'file'
-        ? explainFileImpl(db, target, getFileLines)
-        : explainFunctionImpl(db, target, noTests, getFileLines);
-
-    // Recursive dependency explanation for function targets
-    if (kind === 'function' && depth > 0 && results.length > 0) {
-      const visited = new Set(results.map((r) => `${r.name}:${r.file}:${r.line}`));
-
-      function explainCallees(parentResults, currentDepth) {
-        if (currentDepth <= 0) return;
-        for (const r of parentResults) {
-          const newCallees = [];
-          for (const callee of r.callees) {
-            const key = `${callee.name}:${callee.file}:${callee.line}`;
-            if (visited.has(key)) continue;
-            visited.add(key);
-            const calleeResults = explainFunctionImpl(db, callee.name, noTests, getFileLines);
-            const exact = calleeResults.find(
-              (cr) => cr.file === callee.file && cr.line === callee.line,
-            );
-            if (exact) {
-              exact._depth = (r._depth || 0) + 1;
-              newCallees.push(exact);
-            }
-          }
-          if (newCallees.length > 0) {
-            r.depDetails = newCallees;
-            explainCallees(newCallees, currentDepth - 1);
-          }
-        }
-      }
-
-      explainCallees(results, depth);
-    }
-
-    const base = { target, kind, results };
-    return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
-  } finally {
-    db.close();
-  }
-}