Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

Parallelize the --deep wiring LLM pass (default 5 files in flight, --concurrency flag)

anirudhkumar-nanonetsdf6bae9c71e6
diff --git a/src/cli.ts b/src/cli.ts
index e87422b9..8c2b5a60 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -38,7 +38,13 @@ program
.argument("[dir]", "repository root", ".")
.option("--deep", "run the LLM pass: concept nodes (graft/*.md) + per-symbol summary/crux")
.option("-e, --extensions <exts...>", 'code extensions to include (e.g. ".ts" ".py")')
- .action(async (dir: string, opts: { deep?: boolean; extensions?: string[] }) => {
+ .option("-j, --concurrency <n>", "files summarized in parallel during --deep (default 5)")
+ .action(async (dir: string, opts: { deep?: boolean; extensions?: string[]; concurrency?: string }) => {
+ const concurrency = opts.concurrency ? Math.max(1, Number(opts.concurrency)) : undefined;
+ if (opts.concurrency && !Number.isFinite(concurrency)) {
+ console.error(`✗ --concurrency must be a number, got "${opts.concurrency}"`);
+ process.exit(1);
+ }
const engine = engineFrom();
const fmt = (o: Record<string, number>) =>
Object.entries(o)
@@ -78,6 +84,7 @@ program
// Wiring graph (Tier-2 cards + Tier-3 wiring.json) — always. LLM meaning only with --deep.
const g = await engine.graph(dir, {
llm: deep,
+ concurrency,
onProgress: ({ phase, index, total, file }) =>
process.stderr.write(
`\r${phase === "enrich" ? "summarizing" : "parsing"} ${index + 1}/${total}: ${file.slice(0, 50).padEnd(50)}`,
diff --git a/src/engine.ts b/src/engine.ts
index 74aa240a..4adc7ce5 100644
--- a/src/engine.ts
+++ b/src/engine.ts
@@ -37,6 +37,8 @@ export interface CheckRunOptions {
export interface GraphRunOptions {
/** Run the Tier-2 LLM meaning pass (summary + crux). Absent → Tier-1 only. */
llm?: boolean;
+ /** Max files summarized in parallel during the LLM pass. */
+ concurrency?: number;
onProgress?: GraphBuildOptions["onProgress"];
}
@@ -78,6 +80,7 @@ export class Graft {
return buildGraph(dir, {
contextDir: this.cfg.contextDir,
summarizer: opts.llm ? this.cruxSummarizer() : undefined,
+ concurrency: opts.concurrency,
onProgress: opts.onProgress,
});
}
diff --git a/src/graph/build.ts b/src/graph/build.ts
index 1e388dc8..fbcd0dbe 100644
--- a/src/graph/build.ts
+++ b/src/graph/build.ts
@@ -24,6 +24,8 @@ export interface GraphBuildOptions {
contextDir?: string;
/** Run the Tier-2 LLM meaning pass. Absent → Tier-1 only (cache is still preserved). */
summarizer?: CruxSummarizer;
+ /** Max files summarized in parallel during the Tier-2 pass. Default is set in enrich. */
+ concurrency?: number;
onProgress?: (info: {
phase: "parse" | "enrich";
index: number;
@@ -96,6 +98,7 @@ export async function buildGraph(
const priorById = new Map((prior?.nodes ?? []).map((n) => [n.id, n]));
const meaning = await enrichGraph(nodes, priorById, sources, {
summarizer: opts.summarizer,
+ concurrency: opts.concurrency,
onProgress: ({ index, total, node }) =>
opts.onProgress?.({ phase: "enrich", index, total, file: node }),
});
diff --git a/src/graph/enrich.ts b/src/graph/enrich.ts
index 9d91fc61..3f7157a1 100644
--- a/src/graph/enrich.ts
+++ b/src/graph/enrich.ts
@@ -25,10 +25,15 @@ import type { Crux, NodeV1 } from "./types.js";
/** Cap on the stored crux: an over-long pick is trimmed to its leading slice. */
const MAX_CRUX_LINES = 12;
+/** Files summarized at once. Each is an independent LLM call; order is preserved. */
+const DEFAULT_CONCURRENCY = 5;
+
export interface EnrichOptions {
/** When present, (re)compute meaning for stale/pending nodes. Absent → cache only. */
summarizer?: CruxSummarizer;
- /** Progress is reported per file (one LLM call each), not per node. */
+ /** Max files summarized in parallel (each is one LLM call). Default {@link DEFAULT_CONCURRENCY}. */
+ concurrency?: number;
+ /** Progress is reported per file (one LLM call each), as files finish — not per node. */
onProgress?: (info: { index: number; total: number; node: string }) => void;
}
@@ -86,34 +91,33 @@ export async function enrichGraph(
else byFile.set(node.path, [node]);
}
+ // Each file is an independent LLM call, so run several in flight at once —
+ // the slow part is the round-trip, not local work. Files never share state:
+ // one file's nodes and source stand alone, so parallelism can't corrupt the
+ // per-file line numbers the crux slicing depends on. `stats` mutation is safe
+ // because JS is single-threaded — increments run between awaits, never during.
+ const summarizer = opts.summarizer;
const files = [...byFile.keys()];
- for (let i = 0; i < files.length; i++) {
- const path = files[i];
+ const limit = Math.max(1, opts.concurrency ?? DEFAULT_CONCURRENCY);
+ let done = 0;
+
+ await mapWithConcurrency(files, limit, async (path) => {
const fileNodes = byFile.get(path)!;
const source = sources.get(path)!;
const lineCount = source.split("\n").length;
- opts.onProgress?.({ index: i, total: files.length, node: path });
const refs: NodeRef[] = fileNodes.map((n) => {
const [startLine, endLine] = spanLines(n.span, lineCount);
return { id: n.id, kind: n.kind, signature: n.signature, startLine, endLine };
});
- const { results, error } = await collectFileCrux(opts.summarizer, path, source, refs);
+ const { results, error } = await collectFileCrux(summarizer, path, source, refs);
if (error) stats.errors.push(`${path}: ${error}`);
- if (results.size === 0) {
- // whole-file call failed: leave every node as-is (stale hint or pending).
- for (const node of fileNodes) {
- if (node.summary_state === "stale") stats.stale++;
- else stats.pending++;
- }
- continue;
- }
for (const node of fileNodes) {
- const r = results.get(node.id);
+ const r = results.size > 0 ? results.get(node.id) : undefined;
if (!r) {
- // model skipped this symbol; keep whatever it had.
+ // whole-file call failed, or the model skipped this symbol: keep what it had.
if (node.summary_state === "stale") stats.stale++;
else stats.pending++;
continue;
@@ -123,10 +127,32 @@ export async function enrichGraph(
node.summary_state = "ready";
stats.computed++;
}
- }
+
+ // Report on completion so the counter climbs monotonically under concurrency.
+ opts.onProgress?.({ index: done++, total: files.length, node: path });
+ });
+
return stats;
}
+/** Run `fn` over `items` with at most `limit` in flight, preserving result order. */
+async function mapWithConcurrency<T, R>(
+ items: T[],
+ limit: number,
+ fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+ const results: R[] = new Array(items.length);
+ let next = 0;
+ const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+ while (next < items.length) {
+ const i = next++;
+ results[i] = await fn(items[i], i);
+ }
+ });
+ await Promise.all(workers);
+ return results;
+}
+
/**
* Describe every requested definition in a file, re-asking for any the model
* omits (it sometimes drops entries from a batch). Returns whatever it collected