@optave/codegraph 3.11.0 → 3.11.2

package/src/graph/algorithms/leiden/optimiser.ts

@@ -88,12 +88,10 @@ export function runLouvainUndirectedModularity(
   optionsInput: LeidenOptions = {},
 ): LouvainResult {
   const options: NormalizedOptions = normalizeOptions(optionsInput);
-  let currentGraph: CodeGraph = graph;
-  const levels: LevelEntry[] = [];
   const rngSource = createRng(options.randomSeed);
   const random: () => number = () => rngSource.nextDouble();
 
-  const baseGraphAdapter: GraphAdapter = makeGraphAdapter(currentGraph, {
+  const baseGraphAdapter: GraphAdapter = makeGraphAdapter(graph, {
     directed: options.directed,
     ...optionsInput,
   });
@@ -101,98 +99,27 @@ export function runLouvainUndirectedModularity(
   const originalToCurrent = new Int32Array(origN);
   for (let i = 0; i < origN; i++) originalToCurrent[i] = i;
 
-  let fixedNodeMask: Uint8Array | null = null;
-  if (options.fixedNodes) {
-    const fixed = new Uint8Array(origN);
-    const asSet: Set<string> =
-      options.fixedNodes instanceof Set ? options.fixedNodes : new Set(options.fixedNodes);
-    for (const id of asSet) {
-      const idx = baseGraphAdapter.idToIndex.get(String(id));
-      if (idx != null) fixed[idx] = 1;
-    }
-    fixedNodeMask = fixed;
-  }
+  const fixedNodeMask: Uint8Array | null = buildFixedNodeMask(baseGraphAdapter, options.fixedNodes);
 
+  const levels: LevelEntry[] = [];
+  let currentGraph: CodeGraph = graph;
   for (let level = 0; level < options.maxLevels; level++) {
     const graphAdapter: GraphAdapter =
       level === 0
         ? baseGraphAdapter
         : makeGraphAdapter(currentGraph, { directed: options.directed, ...optionsInput });
-    const partition: Partition = makePartition(graphAdapter);
-    partition.graph = graphAdapter;
-    partition.initializeAggregates();
-
-    const order = new Int32Array(graphAdapter.n);
-    for (let i = 0; i < graphAdapter.n; i++) order[i] = i;
-
-    let improved: boolean = true;
-    let localPasses: number = 0;
-    const strategyCode: CandidateStrategyCode = options.candidateStrategyCode;
-    while (improved) {
-      improved = false;
-      localPasses++;
-      shuffleArrayInPlace(order, random);
-      for (let idx = 0; idx < order.length; idx++) {
-        const nodeIndex: number = order[idx]!;
-        if (level === 0 && fixedNodeMask && fixedNodeMask[nodeIndex]) continue;
-        const candidateCount: number = partition.accumulateNeighborCommunityEdgeWeights(nodeIndex);
-        const { bestCommunityId, bestGain } = findBestCommunityMove(
-          partition,
-          graphAdapter,
-          nodeIndex,
-          candidateCount,
-          strategyCode,
-          options,
-          random,
-        );
-        if (bestCommunityId !== partition.nodeCommunity[nodeIndex]! && bestGain > GAIN_EPSILON) {
-          partition.moveNodeToCommunity(nodeIndex, bestCommunityId);
-          improved = true;
-        }
-      }
-      if (localPasses >= options.maxLocalPasses) break;
-    }
-
-    renumberCommunities(partition, options.preserveLabels);
-
-    let effectivePartition: Partition = partition;
-    if (options.refine) {
-      const refined: Partition = refineWithinCoarseCommunities(
-        graphAdapter,
-        partition,
-        random,
-        options,
-        level === 0 ? fixedNodeMask : null,
-      );
-      // Post-refinement: split any disconnected communities into their
-      // connected components. This is the cheap O(V+E) alternative to
-      // checking gamma-connectedness on every candidate during refinement.
-      // A disconnected community violates even basic connectivity, so
-      // splitting is always correct.
-      splitDisconnectedCommunities(graphAdapter, refined);
-      renumberCommunities(refined, options.preserveLabels);
-      effectivePartition = refined;
-    }
+    const levelOutcome = runLevel(
+      graphAdapter,
+      options,
+      random,
+      level === 0 ? fixedNodeMask : null,
+    );
 
-    levels.push({ graph: graphAdapter, partition: effectivePartition });
-    const fineToCoarse: Int32Array = effectivePartition.nodeCommunity;
-    for (let i = 0; i < originalToCurrent.length; i++) {
-      originalToCurrent[i] = fineToCoarse[originalToCurrent[i]!]!;
-    }
+    levels.push({ graph: graphAdapter, partition: levelOutcome.effectivePartition });
+    applyFineToCoarseMapping(originalToCurrent, levelOutcome.effectivePartition.nodeCommunity);
 
-    // Terminate when no further coarsening is possible. Check both the
-    // move-phase partition (did the greedy phase find merges?) and the
-    // effective partition that feeds buildCoarseGraph (would coarsening
-    // actually reduce the graph?). When refine is enabled the refined
-    // partition starts from singletons and may have more communities than
-    // the move phase found, so checking only effectivePartition would
-    // cause premature termination.
-    if (
-      partition.communityCount === graphAdapter.n &&
-      effectivePartition.communityCount === graphAdapter.n
-    )
-      break;
-    currentGraph = buildCoarseGraph(graphAdapter, effectivePartition);
+    if (levelOutcome.terminate) break;
+    currentGraph = buildCoarseGraph(graphAdapter, levelOutcome.effectivePartition);
   }
 
   const last: LevelEntry = levels[levels.length - 1]!;
@@ -206,6 +133,134 @@ export function runLouvainUndirectedModularity(
   };
 }
 
+/**
+ * Build a fixed-node mask aligned with the base graph adapter's node indices.
+ * Returns null when no fixed nodes are configured.
+ */
+function buildFixedNodeMask(
+  baseGraphAdapter: GraphAdapter,
+  fixedNodes: Set<string> | string[] | undefined,
+): Uint8Array | null {
+  if (!fixedNodes) return null;
+  const mask = new Uint8Array(baseGraphAdapter.n);
+  const asSet: Set<string> = fixedNodes instanceof Set ? fixedNodes : new Set(fixedNodes);
+  for (const id of asSet) {
+    const idx = baseGraphAdapter.idToIndex.get(String(id));
+    if (idx != null) mask[idx] = 1;
+  }
+  return mask;
+}
+
+interface LevelOutcome {
+  effectivePartition: Partition;
+  terminate: boolean;
+}
+
+/**
+ * Run one level of the Louvain/Leiden pipeline: greedy local-move phase,
+ * optional Leiden refinement, and a termination check. Returns the
+ * partition that feeds the next coarse graph plus a `terminate` flag set
+ * when no further coarsening is possible.
+ */
+function runLevel(
+  graphAdapter: GraphAdapter,
+  options: NormalizedOptions,
+  random: () => number,
+  fixedNodeMask: Uint8Array | null,
+): LevelOutcome {
+  const partition: Partition = makePartition(graphAdapter);
+  partition.graph = graphAdapter;
+  partition.initializeAggregates();
+
+  runLocalMovePhase(graphAdapter, partition, options, random, fixedNodeMask);
+  renumberCommunities(partition, options.preserveLabels);
+
+  let effectivePartition: Partition = partition;
+  if (options.refine) {
+    const refined: Partition = refineWithinCoarseCommunities(
+      graphAdapter,
+      partition,
+      random,
+      options,
+      fixedNodeMask,
+    );
+    // Post-refinement: split any disconnected communities into their
+    // connected components. This is the cheap O(V+E) alternative to
+    // checking gamma-connectedness on every candidate during refinement.
+    // A disconnected community violates even basic connectivity, so
+    // splitting is always correct.
+    splitDisconnectedCommunities(graphAdapter, refined);
+    renumberCommunities(refined, options.preserveLabels);
+    effectivePartition = refined;
+  }
+
+  // Terminate when no further coarsening is possible. Check both the
+  // move-phase partition (did the greedy phase find merges?) and the
+  // effective partition that feeds buildCoarseGraph (would coarsening
+  // actually reduce the graph?). When refine is enabled the refined
+  // partition starts from singletons and may have more communities than
+  // the move phase found, so checking only effectivePartition would
+  // cause premature termination.
+  const terminate =
+    partition.communityCount === graphAdapter.n &&
+    effectivePartition.communityCount === graphAdapter.n;
+  return { effectivePartition, terminate };
+}
+
+/**
+ * Greedy local-move phase: iterate randomly over nodes, moving each to the
+ * best community among the candidate set. Loops until no improvement or
+ * `maxLocalPasses` is reached.
+ */
+function runLocalMovePhase(
+  graphAdapter: GraphAdapter,
+  partition: Partition,
+  options: NormalizedOptions,
+  random: () => number,
+  fixedNodeMask: Uint8Array | null,
+): void {
+  const order = new Int32Array(graphAdapter.n);
+  for (let i = 0; i < graphAdapter.n; i++) order[i] = i;
+
+  const strategyCode: CandidateStrategyCode = options.candidateStrategyCode;
+  let improved: boolean = true;
+  let localPasses: number = 0;
+  while (improved) {
+    improved = false;
+    localPasses++;
+    shuffleArrayInPlace(order, random);
+    for (let idx = 0; idx < order.length; idx++) {
+      const nodeIndex: number = order[idx]!;
+      if (fixedNodeMask?.[nodeIndex]) continue;
+      const candidateCount: number = partition.accumulateNeighborCommunityEdgeWeights(nodeIndex);
+      const { bestCommunityId, bestGain } = findBestCommunityMove(
+        partition,
+        graphAdapter,
+        nodeIndex,
+        candidateCount,
+        strategyCode,
+        options,
+        random,
+      );
+      if (bestCommunityId !== partition.nodeCommunity[nodeIndex]! && bestGain > GAIN_EPSILON) {
+        partition.moveNodeToCommunity(nodeIndex, bestCommunityId);
+        improved = true;
+      }
+    }
+    if (localPasses >= options.maxLocalPasses) break;
+  }
+}
+
+/**
+ * Compose the running `originalToCurrent` mapping with this level's
+ * fine→coarse community labels, in place.
+ */
+function applyFineToCoarseMapping(originalToCurrent: Int32Array, fineToCoarse: Int32Array): void {
+  for (let i = 0; i < originalToCurrent.length; i++) {
+    originalToCurrent[i] = fineToCoarse[originalToCurrent[i]!]!;
+  }
+}
+
 /**
  * Evaluate all candidate communities for a node and return the best move.
  * Encapsulates the four candidate-selection strategies (All, RandomAny,

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);
   }
 }