@optave/codegraph 3.10.0 → 3.11.1

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/mcp/tool-registry.ts

@@ -322,6 +322,11 @@ const BASE_TOOLS: ToolSchema[] = [
           description:
             'Search mode: hybrid (BM25 + semantic, default), semantic (embeddings only), keyword (BM25 only)',
         },
+        file_pattern: {
+          oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+          description:
+            'Restrict results to files matching one or more glob or substring patterns (e.g. "db/", "src/**/*.ts", or ["db/", "src/"])',
+        },
         ...PAGINATION_PROPS,
       },
       required: ['query'],

package/src/mcp/tools/semantic-search.ts

@@ -9,6 +9,7 @@ interface SemanticSearchArgs {
   limit?: number;
   offset?: number;
   min_score?: number;
+  file_pattern?: string | string[];
 }
 
 export async function handler(args: SemanticSearchArgs, ctx: McpToolContext): Promise<unknown> {
@@ -17,6 +18,7 @@ export async function handler(args: SemanticSearchArgs, ctx: McpToolContext): Pr
     limit: Math.min(args.limit ?? MCP_DEFAULTS.semantic_search ?? 100, ctx.MCP_MAX_LIMIT),
     offset: effectiveOffset(args),
     minScore: args.min_score,
+    filePattern: args.file_pattern,
   };
 
   if (mode === 'keyword') {

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