@optave/codegraph 3.1.0 → 3.1.2

package/src/flow.js

@@ -6,8 +6,9 @@
  */
 
 import { openReadonlyOrFail } from './db.js';
-import { paginateResult, printNdjson } from './paginate.js';
-import { findMatchingNodes, isTestFile, kindIcon } from './queries.js';
+import { isTestFile } from './infrastructure/test-filter.js';
+import { paginateResult } from './paginate.js';
+import { CORE_SYMBOL_KINDS, findMatchingNodes } from './queries.js';
 import { FRAMEWORK_ENTRY_PREFIXES } from './structure.js';
 
 /**
@@ -35,46 +36,49 @@ export function entryPointType(name) {
  */
 export function listEntryPointsData(dbPath, opts = {}) {
   const db = openReadonlyOrFail(dbPath);
-  const noTests = opts.noTests || false;
+  try {
+    const noTests = opts.noTests || false;
 
-  // Find all framework-prefixed nodes
-  const prefixConditions = FRAMEWORK_ENTRY_PREFIXES.map(() => 'n.name LIKE ?').join(' OR ');
-  const prefixParams = FRAMEWORK_ENTRY_PREFIXES.map((p) => `${p}%`);
+    // Find all framework-prefixed nodes
+    const prefixConditions = FRAMEWORK_ENTRY_PREFIXES.map(() => 'n.name LIKE ?').join(' OR ');
+    const prefixParams = FRAMEWORK_ENTRY_PREFIXES.map((p) => `${p}%`);
 
-  let rows = db
-    .prepare(
-      `SELECT n.name, n.kind, n.file, n.line, n.role
-       FROM nodes n
-       WHERE (
-         (${prefixConditions})
-         OR n.role = 'entry'
-       )
-         AND n.kind NOT IN ('file', 'directory')
-       ORDER BY n.name`,
-    )
-    .all(...prefixParams);
-
-  if (noTests) rows = rows.filter((r) => !isTestFile(r.file));
-
-  const entries = rows.map((r) => ({
-    name: r.name,
-    kind: r.kind,
-    file: r.file,
-    line: r.line,
-    role: r.role,
-    type: entryPointType(r.name) || (r.role === 'entry' ? 'exported' : null),
-  }));
+    let rows = db
+      .prepare(
+        `SELECT n.name, n.kind, n.file, n.line, n.role
+         FROM nodes n
+         WHERE (
+           (${prefixConditions})
+           OR n.role = 'entry'
+         )
+           AND n.kind NOT IN ('file', 'directory')
+         ORDER BY n.name`,
+      )
+      .all(...prefixParams);
+
+    if (noTests) rows = rows.filter((r) => !isTestFile(r.file));
+
+    const entries = rows.map((r) => ({
+      name: r.name,
+      kind: r.kind,
+      file: r.file,
+      line: r.line,
+      role: r.role,
+      type: entryPointType(r.name) || (r.role === 'entry' ? 'exported' : null),
+    }));
+
+    const byType = {};
+    for (const e of entries) {
+      const t = e.type || 'other';
+      if (!byType[t]) byType[t] = [];
+      byType[t].push(e);
+    }
 
-  const byType = {};
-  for (const e of entries) {
-    const t = e.type || 'other';
-    if (!byType[t]) byType[t] = [];
-    byType[t].push(e);
+    const base = { entries, byType, count: entries.length };
+    return paginateResult(base, 'entries', { limit: opts.limit, offset: opts.offset });
+  } finally {
+    db.close();
   }
-
-  db.close();
-  const base = { entries, byType, count: entries.length };
-  return paginateResult(base, 'entries', { limit: opts.limit, offset: opts.offset });
 }
 
 /**
@@ -91,207 +95,134 @@ export function listEntryPointsData(dbPath, opts = {}) {
  */
 export function flowData(name, dbPath, opts = {}) {
   const db = openReadonlyOrFail(dbPath);
-  const maxDepth = opts.depth || 10;
-  const noTests = opts.noTests || false;
-
-  // Phase 1: Direct LIKE match on full name
-  let matchNode = findMatchingNodes(db, name, opts)[0] ?? null;
+  try {
+    const maxDepth = opts.depth || 10;
+    const noTests = opts.noTests || false;
+    const flowOpts = { ...opts, kinds: opts.kind ? [opts.kind] : CORE_SYMBOL_KINDS };
+
+    // Phase 1: Direct LIKE match on full name (use all 10 core symbol kinds,
+    // not just FUNCTION_KINDS, so flow can trace from interfaces/types/structs/etc.)
+    let matchNode = findMatchingNodes(db, name, flowOpts)[0] ?? null;
+
+    // Phase 2: Prefix-stripped matching — try adding framework prefixes
+    if (!matchNode) {
+      for (const prefix of FRAMEWORK_ENTRY_PREFIXES) {
+        matchNode = findMatchingNodes(db, `${prefix}${name}`, flowOpts)[0] ?? null;
+        if (matchNode) break;
+      }
+    }
 
-  // Phase 2: Prefix-stripped matching — try adding framework prefixes
-  if (!matchNode) {
-    for (const prefix of FRAMEWORK_ENTRY_PREFIXES) {
-      matchNode = findMatchingNodes(db, `${prefix}${name}`, opts)[0] ?? null;
-      if (matchNode) break;
+    if (!matchNode) {
+      return {
+        entry: null,
+        depth: maxDepth,
+        steps: [],
+        leaves: [],
+        cycles: [],
+        totalReached: 0,
+        truncated: false,
+      };
     }
-  }
 
-  if (!matchNode) {
-    db.close();
-    return {
-      entry: null,
-      depth: maxDepth,
-      steps: [],
-      leaves: [],
-      cycles: [],
-      totalReached: 0,
-      truncated: false,
+    const epType = entryPointType(matchNode.name);
+    const entry = {
+      name: matchNode.name,
+      kind: matchNode.kind,
+      file: matchNode.file,
+      line: matchNode.line,
+      type: epType || 'exported',
+      role: matchNode.role,
     };
-  }
-
-  const epType = entryPointType(matchNode.name);
-  const entry = {
-    name: matchNode.name,
-    kind: matchNode.kind,
-    file: matchNode.file,
-    line: matchNode.line,
-    type: epType || 'exported',
-    role: matchNode.role,
-  };
-
-  // Forward BFS through callees
-  const visited = new Set([matchNode.id]);
-  let frontier = [matchNode.id];
-  const steps = [];
-  const cycles = [];
-  let truncated = false;
 
-  // Track which nodes are at each depth and their depth for leaf detection
-  const nodeDepths = new Map();
-  const idToNode = new Map();
-  idToNode.set(matchNode.id, entry);
-
-  for (let d = 1; d <= maxDepth; d++) {
-    const nextFrontier = [];
-    const levelNodes = [];
-
-    for (const fid of frontier) {
-      const callees = db
-        .prepare(
-          `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line, n.role
-           FROM edges e JOIN nodes n ON e.target_id = n.id
-           WHERE e.source_id = ? AND e.kind = 'calls'`,
-        )
-        .all(fid);
-
-      for (const c of callees) {
-        if (noTests && isTestFile(c.file)) continue;
-
-        if (visited.has(c.id)) {
-          // Cycle detected
-          const fromNode = idToNode.get(fid);
-          if (fromNode) {
-            cycles.push({ from: fromNode.name, to: c.name, depth: d });
+    // Forward BFS through callees
+    const visited = new Set([matchNode.id]);
+    let frontier = [matchNode.id];
+    const steps = [];
+    const cycles = [];
+    let truncated = false;
+
+    // Track which nodes are at each depth and their depth for leaf detection
+    const nodeDepths = new Map();
+    const idToNode = new Map();
+    idToNode.set(matchNode.id, entry);
+
+    for (let d = 1; d <= maxDepth; d++) {
+      const nextFrontier = [];
+      const levelNodes = [];
+
+      for (const fid of frontier) {
+        const callees = db
+          .prepare(
+            `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line, n.role
+             FROM edges e JOIN nodes n ON e.target_id = n.id
+             WHERE e.source_id = ? AND e.kind = 'calls'`,
+          )
+          .all(fid);
+
+        for (const c of callees) {
+          if (noTests && isTestFile(c.file)) continue;
+
+          if (visited.has(c.id)) {
+            // Cycle detected
+            const fromNode = idToNode.get(fid);
+            if (fromNode) {
+              cycles.push({ from: fromNode.name, to: c.name, depth: d });
+            }
+            continue;
           }
-          continue;
-        }
 
-        visited.add(c.id);
-        nextFrontier.push(c.id);
-        const nodeInfo = { name: c.name, kind: c.kind, file: c.file, line: c.line };
-        levelNodes.push(nodeInfo);
-        nodeDepths.set(c.id, d);
-        idToNode.set(c.id, nodeInfo);
+          visited.add(c.id);
+          nextFrontier.push(c.id);
+          const nodeInfo = { name: c.name, kind: c.kind, file: c.file, line: c.line };
+          levelNodes.push(nodeInfo);
+          nodeDepths.set(c.id, d);
+          idToNode.set(c.id, nodeInfo);
+        }
       }
-    }
-
-    if (levelNodes.length > 0) {
-      steps.push({ depth: d, nodes: levelNodes });
-    }
-
-    frontier = nextFrontier;
-    if (frontier.length === 0) break;
 
-    if (d === maxDepth && frontier.length > 0) {
-      truncated = true;
-    }
-  }
-
-  // Identify leaves: visited nodes that have no outgoing 'calls' edges to other visited nodes
-  // (or no outgoing calls at all)
-  const leaves = [];
-  for (const [id, depth] of nodeDepths) {
-    const outgoing = db
-      .prepare(
-        `SELECT DISTINCT n.id
-         FROM edges e JOIN nodes n ON e.target_id = n.id
-         WHERE e.source_id = ? AND e.kind = 'calls'`,
-      )
-      .all(id);
-
-    if (outgoing.length === 0) {
-      const node = idToNode.get(id);
-      if (node) {
-        leaves.push({ ...node, depth });
+      if (levelNodes.length > 0) {
+        steps.push({ depth: d, nodes: levelNodes });
       }
-    }
-  }
 
-  db.close();
-  const base = {
-    entry,
-    depth: maxDepth,
-    steps,
-    leaves,
-    cycles,
-    totalReached: visited.size - 1, // exclude the entry node itself
-    truncated,
-  };
-  return paginateResult(base, 'steps', { limit: opts.limit, offset: opts.offset });
-}
+      frontier = nextFrontier;
+      if (frontier.length === 0) break;
 
-/**
- * CLI formatter — text or JSON output.
- */
-export function flow(name, dbPath, opts = {}) {
-  if (opts.list) {
-    const data = listEntryPointsData(dbPath, {
-      noTests: opts.noTests,
-      limit: opts.limit,
-      offset: opts.offset,
-    });
-    if (opts.ndjson) {
-      printNdjson(data, 'entries');
-      return;
-    }
-    if (opts.json) {
-      console.log(JSON.stringify(data, null, 2));
-      return;
-    }
-    if (data.count === 0) {
-      console.log('No entry points found. Run "codegraph build" first.');
-      return;
-    }
-    console.log(`\nEntry points (${data.count} total):\n`);
-    for (const [type, entries] of Object.entries(data.byType)) {
-      console.log(`  ${type} (${entries.length}):`);
-      for (const e of entries) {
-        console.log(`    [${kindIcon(e.kind)}] ${e.name}  ${e.file}:${e.line}`);
+      if (d === maxDepth && frontier.length > 0) {
+        truncated = true;
       }
-      console.log();
     }
-    return;
-  }
-
-  const data = flowData(name, dbPath, opts);
-  if (opts.json) {
-    console.log(JSON.stringify(data, null, 2));
-    return;
-  }
 
-  if (!data.entry) {
-    console.log(`No matching entry point or function found for "${name}".`);
-    return;
-  }
-
-  const e = data.entry;
-  const typeTag = e.type !== 'exported' ? ` (${e.type})` : '';
-  console.log(`\nFlow from: [${kindIcon(e.kind)}] ${e.name}${typeTag}  ${e.file}:${e.line}`);
-  console.log(
-    `Depth: ${data.depth}  Reached: ${data.totalReached} nodes  Leaves: ${data.leaves.length}`,
-  );
-  if (data.truncated) {
-    console.log(`  (truncated at depth ${data.depth})`);
-  }
-  console.log();
-
-  if (data.steps.length === 0) {
-    console.log('  (leaf node — no callees)');
-    return;
-  }
+    // Identify leaves: visited nodes that have no outgoing 'calls' edges to other visited nodes
+    // (or no outgoing calls at all)
+    const leaves = [];
+    for (const [id, depth] of nodeDepths) {
+      const outgoing = db
+        .prepare(
+          `SELECT DISTINCT n.id
+           FROM edges e JOIN nodes n ON e.target_id = n.id
+           WHERE e.source_id = ? AND e.kind = 'calls'`,
+        )
+        .all(id);
 
-  for (const step of data.steps) {
-    console.log(`  depth ${step.depth}:`);
-    for (const n of step.nodes) {
-      const isLeaf = data.leaves.some((l) => l.name === n.name && l.file === n.file);
-      const leafTag = isLeaf ? ' [leaf]' : '';
-      console.log(`    [${kindIcon(n.kind)}] ${n.name}  ${n.file}:${n.line}${leafTag}`);
+      if (outgoing.length === 0) {
+        const node = idToNode.get(id);
+        if (node) {
+          leaves.push({ ...node, depth });
+        }
+      }
     }
-  }
 
-  if (data.cycles.length > 0) {
-    console.log('\n  Cycles detected:');
-    for (const c of data.cycles) {
-      console.log(`    ${c.from} -> ${c.to} (at depth ${c.depth})`);
-    }
+    const base = {
+      entry,
+      depth: maxDepth,
+      steps,
+      leaves,
+      cycles,
+      totalReached: visited.size - 1, // exclude the entry node itself
+      truncated,
+    };
+    return paginateResult(base, 'steps', { limit: opts.limit, offset: opts.offset });
+  } finally {
+    db.close();
   }
 }

package/src/index.js

@@ -8,13 +8,11 @@
 // AST node queries
 export { AST_NODE_KINDS, astQuery, astQueryData } from './ast.js';
 // Audit (composite report)
-export { audit, auditData } from './audit.js';
+export { auditData } from './audit.js';
 // Batch querying
 export {
   BATCH_COMMANDS,
-  batch,
   batchData,
-  batchQuery,
   multiBatchData,
   splitTargets,
 } from './batch.js';
@@ -29,13 +27,12 @@ export {
   buildCFGData,
   buildFunctionCFG,
   CFG_RULES,
-  cfg,
   cfgData,
   cfgToDOT,
   cfgToMermaid,
 } from './cfg.js';
 // Check (CI validation predicates)
-export { check, checkData } from './check.js';
+export { checkData } from './check.js';
 // Co-change analysis
 export {
   analyzeCoChanges,
@@ -45,12 +42,23 @@ export {
   computeCoChanges,
   scanGitHistory,
 } from './cochange.js';
+export { audit } from './commands/audit.js';
+export { batch, batchQuery } from './commands/batch.js';
+export { cfg } from './commands/cfg.js';
+export { check } from './commands/check.js';
+export { communities } from './commands/communities.js';
+export { complexity } from './commands/complexity.js';
+export { dataflow } from './commands/dataflow.js';
+export { manifesto } from './commands/manifesto.js';
+export { owners } from './commands/owners.js';
+export { sequence } from './commands/sequence.js';
+export { formatHotspots, formatModuleBoundaries, formatStructure } from './commands/structure.js';
+export { triage } from './commands/triage.js';
 // Community detection
-export { communities, communitiesData, communitySummaryForStats } from './communities.js';
+export { communitiesData, communitySummaryForStats } from './communities.js';
 // Complexity metrics
 export {
   COMPLEXITY_RULES,
-  complexity,
   complexityData,
   computeFunctionComplexity,
   computeHalsteadMetrics,
@@ -69,7 +77,6 @@ export { findCycles, formatCycles } from './cycles.js';
 // Dataflow analysis
 export {
   buildDataflowEdges,
-  dataflow,
   dataflowData,
   dataflowImpactData,
   dataflowPathData,
@@ -77,12 +84,24 @@ export {
 } from './dataflow.js';
 // Database utilities
 export {
+  countEdges,
+  countFiles,
+  countNodes,
+  fanInJoinSQL,
+  fanOutJoinSQL,
   findDbPath,
+  findNodesForTriage,
+  findNodesWithFanIn,
   getBuildMeta,
   initSchema,
+  iterateFunctionNodes,
+  kindInClause,
+  listFunctionNodes,
+  NodeQuery,
   openDb,
   openReadonlyOrFail,
   setBuildMeta,
+  testFilterSQL,
 } from './db.js';
 // Embeddings
 export {
@@ -111,14 +130,18 @@ export {
 } from './export.js';
 // Execution flow tracing
 export { entryPointType, flowData, listEntryPointsData } from './flow.js';
+// Result formatting
+export { outputResult } from './infrastructure/result-formatter.js';
+// Test file detection
+export { isTestFile, TEST_PATTERN } from './infrastructure/test-filter.js';
 // Logger
 export { setVerbose } from './logger.js';
 // Manifesto rule engine
-export { manifesto, manifestoData, RULE_DEFS } from './manifesto.js';
+export { manifestoData, RULE_DEFS } from './manifesto.js';
 // Native engine
 export { isNativeAvailable } from './native.js';
 // Ownership (CODEOWNERS)
-export { matchOwners, owners, ownersData, ownersForFiles, parseCodeowners } from './owners.js';
+export { matchOwners, ownersData, ownersForFiles, parseCodeowners } from './owners.js';
 // Pagination utilities
 export { MCP_DEFAULTS, MCP_MAX_LIMIT, paginate, paginateResult, printNdjson } from './paginate.js';
 // Unified parser API
@@ -140,7 +163,6 @@ export {
   FALSE_POSITIVE_CALLER_THRESHOLD,
   FALSE_POSITIVE_NAMES,
   fileDepsData,
-  fileExports,
   fnDepsData,
   fnImpactData,
   impactAnalysisData,
@@ -158,6 +180,24 @@ export {
   VALID_ROLES,
   whereData,
 } from './queries.js';
+// Query CLI display wrappers
+export {
+  children,
+  context,
+  diffImpact,
+  explain,
+  fileDeps,
+  fileExports,
+  fnDeps,
+  fnImpact,
+  impactAnalysis,
+  moduleMap,
+  queryName,
+  roles,
+  stats,
+  symbolPath,
+  where,
+} from './queries-cli.js';
 // Registry (multi-repo)
 export {
   listRepos,
@@ -170,7 +210,7 @@ export {
   unregisterRepo,
 } from './registry.js';
 // Sequence diagram generation
-export { sequence, sequenceData, sequenceToMermaid } from './sequence.js';
+export { sequenceData, sequenceToMermaid } from './sequence.js';
 // Snapshot management
 export {
   snapshotDelete,
@@ -185,15 +225,12 @@ export {
   buildStructure,
   classifyNodeRoles,
   FRAMEWORK_ENTRY_PREFIXES,
-  formatHotspots,
-  formatModuleBoundaries,
-  formatStructure,
   hotspotsData,
   moduleBoundariesData,
   structureData,
 } from './structure.js';
 // Triage — composite risk audit
-export { triage, triageData } from './triage.js';
+export { triageData } from './triage.js';
 // Interactive HTML viewer
 export { generatePlotHTML, loadPlotConfig } from './viewer.js';
 // Watch mode

package/src/infrastructure/result-formatter.js

@@ -0,0 +1,21 @@
+import { printNdjson } from '../paginate.js';
+
+/**
+ * Shared JSON / NDJSON 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? })
+ * @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;
+  }
+  return false;
+}

package/src/infrastructure/test-filter.js

@@ -0,0 +1,7 @@
+/** Pattern matching test/spec/stories files. */
+export const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
+
+/** Check whether a file path looks like a test file. */
+export function isTestFile(filePath) {
+  return TEST_PATTERN.test(filePath);
+}

package/src/kinds.js

@@ -0,0 +1,50 @@
+// ── Symbol kind constants ───────────────────────────────────────────
+// Original 10 kinds — used as default query scope
+export const CORE_SYMBOL_KINDS = [
+  'function',
+  'method',
+  'class',
+  'interface',
+  'type',
+  'struct',
+  'enum',
+  'trait',
+  'record',
+  'module',
+];
+
+// Sub-declaration kinds (Phase 1)
+export const EXTENDED_SYMBOL_KINDS = [
+  'parameter',
+  'property',
+  'constant',
+  // Phase 2 (reserved, not yet extracted):
+  // 'constructor', 'namespace', 'decorator', 'getter', 'setter',
+];
+
+// Full set for --kind validation and MCP enum
+export const EVERY_SYMBOL_KIND = [...CORE_SYMBOL_KINDS, ...EXTENDED_SYMBOL_KINDS];
+
+// Backward compat: ALL_SYMBOL_KINDS stays as the core 10
+export const ALL_SYMBOL_KINDS = CORE_SYMBOL_KINDS;
+
+// ── Edge kind constants ─────────────────────────────────────────────
+// Core edge kinds — coupling and dependency relationships
+export const CORE_EDGE_KINDS = [
+  'imports',
+  'imports-type',
+  'dynamic-imports',
+  'reexports',
+  'calls',
+  'extends',
+  'implements',
+  'contains',
+];
+
+// Structural edge kinds — parent/child and type relationships
+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'];