@optave/codegraph 3.11.0 → 3.11.1

package/src/graph/classifiers/roles.ts

@@ -78,6 +78,68 @@ export interface RoleClassificationNode {
   hasActiveFileSiblings?: boolean;
 }
 
+/**
+ * Compute median fan-in and fan-out across nodes with non-zero values.
+ * Used as thresholds for "high" fan-in/out classification.
+ */
+function computeFanMedians(nodes: RoleClassificationNode[]): { fanIn: number; fanOut: number } {
+  const nonZeroFanIn = nodes
+    .filter((n) => n.fanIn > 0)
+    .map((n) => n.fanIn)
+    .sort((a, b) => a - b);
+  const nonZeroFanOut = nodes
+    .filter((n) => n.fanOut > 0)
+    .map((n) => n.fanOut)
+    .sort((a, b) => a - b);
+  return { fanIn: median(nonZeroFanIn), fanOut: median(nonZeroFanOut) };
+}
+
+/**
+ * Classify a node with `fanIn === 0` that is not exported.
+ * Covers framework-active constants, test-only callables, and the dead-* family.
+ */
+function classifyUnreferencedNode(node: RoleClassificationNode): Role {
+  if (node.kind === 'constant' && node.hasActiveFileSiblings) {
+    // Constants consumed via identifier reference (not calls) have no
+    // inbound call edges. If the same file has active callables, the
+    // constant is almost certainly used locally — classify as leaf.
+    return 'leaf';
+  }
+  if (node.testOnlyFanIn != null && node.testOnlyFanIn > 0) return 'test-only';
+  return classifyDeadSubRole(node);
+}
+
+/**
+ * Pick a role from fan-in/fan-out shape: core/utility/adapter/leaf.
+ * Called after entry/test-only/dead cases have been ruled out.
+ */
+function classifyByFanShape(highIn: boolean, highOut: boolean): Role {
+  if (highIn && !highOut) return 'core';
+  if (highIn && highOut) return 'utility';
+  if (!highIn && highOut) return 'adapter';
+  return 'leaf';
+}
+
+/**
+ * Apply role-classification rules to a single node.
+ * Order matters — framework entries are tagged first, then dead/test cases,
+ * then the fan-in/fan-out shape decides among the structural roles.
+ */
+function classifyNodeRole(node: RoleClassificationNode, medFanIn: number, medFanOut: number): Role {
+  if (FRAMEWORK_ENTRY_PREFIXES.some((p) => node.name.startsWith(p))) return 'entry';
+
+  if (node.fanIn === 0) {
+    return node.isExported ? 'entry' : classifyUnreferencedNode(node);
+  }
+
+  const hasProdFanIn = typeof node.productionFanIn === 'number';
+  if (hasProdFanIn && node.productionFanIn === 0 && !node.isExported) return 'test-only';
+
+  const highIn = node.fanIn >= medFanIn;
+  const highOut = node.fanOut >= medFanOut && node.fanOut > 0;
+  return classifyByFanShape(highIn, highOut);
+}
+
 /**
  * Classify nodes into architectural roles based on fan-in/fan-out metrics.
  */
@@ -87,63 +149,11 @@ export function classifyRoles(
 ): Map<string, Role> {
   if (nodes.length === 0) return new Map();
 
-  let medFanIn: number;
-  let medFanOut: number;
-  if (medianOverrides) {
-    medFanIn = medianOverrides.fanIn;
-    medFanOut = medianOverrides.fanOut;
-  } else {
-    const nonZeroFanIn = nodes
-      .filter((n) => n.fanIn > 0)
-      .map((n) => n.fanIn)
-      .sort((a, b) => a - b);
-    const nonZeroFanOut = nodes
-      .filter((n) => n.fanOut > 0)
-      .map((n) => n.fanOut)
-      .sort((a, b) => a - b);
-    medFanIn = median(nonZeroFanIn);
-    medFanOut = median(nonZeroFanOut);
-  }
+  const { fanIn: medFanIn, fanOut: medFanOut } = medianOverrides ?? computeFanMedians(nodes);
 
   const result = new Map<string, Role>();
-
   for (const node of nodes) {
-    const highIn = node.fanIn >= medFanIn && node.fanIn > 0;
-    const highOut = node.fanOut >= medFanOut && node.fanOut > 0;
-    const hasProdFanIn = typeof node.productionFanIn === 'number';
-
-    let role: Role;
-    const isFrameworkEntry = FRAMEWORK_ENTRY_PREFIXES.some((p) => node.name.startsWith(p));
-    if (isFrameworkEntry) {
-      role = 'entry';
-    } else if (node.fanIn === 0 && !node.isExported) {
-      if (node.kind === 'constant' && node.hasActiveFileSiblings) {
-        // Constants consumed via identifier reference (not calls) have no
-        // inbound call edges. If the same file has active callables, the
-        // constant is almost certainly used locally — classify as leaf.
-        role = 'leaf';
-      } else {
-        role =
-          node.testOnlyFanIn != null && node.testOnlyFanIn > 0
-            ? 'test-only'
-            : classifyDeadSubRole(node);
-      }
-    } else if (node.fanIn === 0 && node.isExported) {
-      role = 'entry';
-    } else if (hasProdFanIn && node.fanIn > 0 && node.productionFanIn === 0 && !node.isExported) {
-      role = 'test-only';
-    } else if (highIn && !highOut) {
-      role = 'core';
-    } else if (highIn && highOut) {
-      role = 'utility';
-    } else if (!highIn && highOut) {
-      role = 'adapter';
-    } else {
-      role = 'leaf';
-    }
-
-    result.set(node.id, role);
+    result.set(node.id, classifyNodeRole(node, medFanIn, medFanOut));
   }
-
   return result;
 }

package/src/infrastructure/config.ts

@@ -30,7 +30,7 @@ export const DEFAULTS = {
     defaultLimit: 20,
     excludeTests: false,
   },
-  embeddings: { model: 'nomic-v1.5', llmProvider: null as string | null },
+  embeddings: { model: null as string | null, llmProvider: null as string | null },
   llm: {
     provider: null as string | null,
     model: null as string | null,

package/src/presentation/cfg.ts

@@ -1,6 +1,8 @@
 import { cfgData, cfgToDOT, cfgToMermaid } from '../features/cfg.js';
 import { outputResult } from '../infrastructure/result-formatter.js';
 
+type CfgData = ReturnType<typeof cfgData>;
+
 interface CfgCliOpts {
   json?: boolean;
   ndjson?: boolean;
@@ -36,13 +38,56 @@ interface CfgResultEntry {
   edges: CfgEdge[];
 }
 
+function renderBlockLocation(b: CfgBlock): string {
+  if (!b.startLine) return '';
+  const endSuffix = b.endLine && b.endLine !== b.startLine ? `-${b.endLine}` : '';
+  return ` L${b.startLine}${endSuffix}`;
+}
+
+function printCfgBlocks(blocks: CfgBlock[]): void {
+  if (blocks.length === 0) return;
+  console.log('\n  Blocks:');
+  for (const b of blocks) {
+    const label = b.label ? ` (${b.label})` : '';
+    console.log(`    [${b.index}] ${b.type}${label}${renderBlockLocation(b)}`);
+  }
+}
+
+function printCfgEdges(edges: CfgEdge[]): void {
+  if (edges.length === 0) return;
+  console.log('\n  Edges:');
+  for (const e of edges) {
+    console.log(`    B${e.source} → B${e.target}  [${e.kind}]`);
+  }
+}
+
+function printCfgEntry(r: CfgResultEntry): void {
+  console.log(`\n${r.kind} ${r.name}  (${r.file}:${r.line})`);
+  console.log('─'.repeat(60));
+  console.log(`  Blocks: ${r.summary.blockCount}  Edges: ${r.summary.edgeCount}`);
+  printCfgBlocks(r.blocks);
+  printCfgEdges(r.edges);
+}
+
+function tryRenderGraphFormat(format: string, data: CfgData): boolean {
+  if (format === 'dot') {
+    console.log(cfgToDOT(data));
+    return true;
+  }
+  if (format === 'mermaid') {
+    console.log(cfgToMermaid(data));
+    return true;
+  }
+  return false;
+}
+
 export function cfg(name: string, customDbPath: string | undefined, opts: CfgCliOpts = {}): void {
   const data = cfgData(name, customDbPath, opts);
 
   if (outputResult(data, 'results', opts)) return;
 
   if (data.warning) {
-    console.log(`\u26A0  ${data.warning}`);
+    console.log(`⚠  ${data.warning}`);
     return;
   }
   if (data.results.length === 0) {
@@ -50,38 +95,9 @@ export function cfg(name: string, customDbPath: string | undefined, opts: CfgCli
     return;
   }
 
-  const format = opts.format || 'text';
-  if (format === 'dot') {
-    console.log(cfgToDOT(data));
-    return;
-  }
-  if (format === 'mermaid') {
-    console.log(cfgToMermaid(data));
-    return;
-  }
+  if (tryRenderGraphFormat(opts.format || 'text', data)) return;
 
-  // Text format
   for (const r of data.results as CfgResultEntry[]) {
-    console.log(`\n${r.kind} ${r.name}  (${r.file}:${r.line})`);
-    console.log('\u2500'.repeat(60));
-    console.log(`  Blocks: ${r.summary.blockCount}  Edges: ${r.summary.edgeCount}`);
-
-    if (r.blocks.length > 0) {
-      console.log('\n  Blocks:');
-      for (const b of r.blocks) {
-        const loc = b.startLine
-          ? ` L${b.startLine}${b.endLine && b.endLine !== b.startLine ? `-${b.endLine}` : ''}`
-          : '';
-        const label = b.label ? ` (${b.label})` : '';
-        console.log(`    [${b.index}] ${b.type}${label}${loc}`);
-      }
-    }
-
-    if (r.edges.length > 0) {
-      console.log('\n  Edges:');
-      for (const e of r.edges) {
-        console.log(`    B${e.source} \u2192 B${e.target}  [${e.kind}]`);
-      }
-    }
+    printCfgEntry(r);
   }
 }

package/src/presentation/flow.ts

@@ -16,54 +16,65 @@ interface FlowOpts {
   csv?: boolean;
 }
 
-export function flow(
-  name: string | undefined,
-  dbPath: string | undefined,
-  opts: FlowOpts = {},
-): void {
-  if (opts.list) {
-    const data = listEntryPointsData(dbPath, {
-      noTests: opts.noTests,
-      limit: opts.limit,
-      offset: opts.offset,
-    }) as any;
-    if (outputResult(data, 'entries', opts)) 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 as Record<
-        string,
-        Array<{ kind: string; name: string; file: string; line: number }>
-      >,
-    )) {
-      console.log(`  ${type} (${entries.length}):`);
-      for (const e of entries) {
-        console.log(`    [${kindIcon(e.kind)}] ${e.name}  ${e.file}:${e.line}`);
-      }
-      console.log();
-    }
-    return;
-  }
+interface EntryPoint {
+  kind: string;
+  name: string;
+  file: string;
+  line: number;
+}
 
-  if (!name) {
-    console.log(
-      'Please provide a function or entry-point name. Use --list to see available entry points.',
-    );
-    return;
-  }
+interface FlowNode {
+  kind: string;
+  name: string;
+  file: string;
+  line: number;
+}
 
-  const data = flowData(name, dbPath, opts) as any;
-  if (outputResult(data, 'steps', opts)) return;
+interface FlowStep {
+  depth: number;
+  nodes: FlowNode[];
+}
 
-  if (!data.entry) {
-    console.log(`No matching entry point or function found for "${name}".`);
+interface FlowCycle {
+  from: string;
+  to: string;
+  depth: number;
+}
+
+interface FlowResult {
+  entry?: { kind: string; name: string; type: string; file: string; line: number };
+  depth: number;
+  totalReached: number;
+  leaves: Array<{ name: string; file: string }>;
+  steps: FlowStep[];
+  cycles: FlowCycle[];
+  truncated?: boolean;
+}
+
+function runListEntryPoints(dbPath: string | undefined, opts: FlowOpts): void {
+  const data = listEntryPointsData(dbPath, {
+    noTests: opts.noTests,
+    limit: opts.limit,
+    offset: opts.offset,
+  }) as { count: number; byType: Record<string, EntryPoint[]> };
+  if (outputResult(data, 'entries', opts)) 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}`);
+    }
+    console.log();
+  }
+}
 
+function printFlowHeader(data: FlowResult): void {
   const e = data.entry;
+  if (!e) return;
   const typeTag = e.type !== 'exported' ? ` (${e.type})` : '';
   console.log(`\nFlow from: [${kindIcon(e.kind)}] ${e.name}${typeTag}  ${e.file}:${e.line}`);
   console.log(
@@ -73,27 +84,64 @@ export function flow(
     console.log(`  (truncated at depth ${data.depth})`);
   }
   console.log();
+}
+
+function isLeafNode(n: FlowNode, leaves: Array<{ name: string; file: string }>): boolean {
+  return leaves.some((l) => l.name === n.name && l.file === n.file);
+}
 
+/** Returns true when the node is a leaf (no steps); caller should skip cycle output. */
+function printFlowSteps(data: FlowResult): boolean {
   if (data.steps.length === 0) {
     console.log('  (leaf node — no callees)');
-    return;
+    return true;
   }
-
   for (const step of data.steps) {
     console.log(`  depth ${step.depth}:`);
     for (const n of step.nodes) {
-      const isLeaf = data.leaves.some(
-        (l: { name: string; file: string }) => l.name === n.name && l.file === n.file,
-      );
-      const leafTag = isLeaf ? ' [leaf]' : '';
+      const leafTag = isLeafNode(n, data.leaves) ? ' [leaf]' : '';
       console.log(`    [${kindIcon(n.kind)}] ${n.name}  ${n.file}:${n.line}${leafTag}`);
     }
   }
+  return false;
+}
+
+function printFlowCycles(cycles: FlowCycle[]): void {
+  if (cycles.length === 0) return;
+  console.log('\n  Cycles detected:');
+  for (const c of cycles) {
+    console.log(`    ${c.from} -> ${c.to} (at depth ${c.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})`);
-    }
+export function flow(
+  name: string | undefined,
+  dbPath: string | undefined,
+  opts: FlowOpts = {},
+): void {
+  if (opts.list) {
+    runListEntryPoints(dbPath, opts);
+    return;
+  }
+
+  if (!name) {
+    console.log(
+      'Please provide a function or entry-point name. Use --list to see available entry points.',
+    );
+    return;
+  }
+
+  const data = flowData(name, dbPath, opts) as unknown as FlowResult;
+  if (outputResult(data, 'steps', opts)) return;
+
+  if (!data.entry) {
+    console.log(`No matching entry point or function found for "${name}".`);
+    return;
+  }
+
+  printFlowHeader(data);
+  const isLeaf = printFlowSteps(data);
+  if (!isLeaf) {
+    printFlowCycles(data.cycles);
   }
 }

package/src/types.ts

@@ -1128,7 +1128,7 @@ export interface CodegraphConfig {
   };
 
   embeddings: {
-    model: string;
+    model: string | null;
     llmProvider: string | null;
   };