gitnexus 1.6.11 → 1.6.12-rc.10

package/README.md

@@ -631,7 +631,7 @@ results until you re-run `gitnexus analyze --repair-fts` from a shell where the
 
 ### Installation fails with native module errors
 
-Some optional language grammars (Dart, Proto, Swift, Kotlin) require native compilation. If they fail, GitNexus still works — those languages will be skipped. To skip them intentionally (no C++ toolchain needed), set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before installing. Zig (`@tree-sitter-grammars/tree-sitter-zig`, an npm `optionalDependency`) behaves the same way: if its native binding fails to install, `.zig` files are skipped.
+Some optional language grammars (Dart, Proto, Swift, Kotlin, Zig) ship vendored native prebuilds. If a prebuild is missing and a source build is not possible, GitNexus still works — those languages will be skipped. To skip them intentionally (no C++ toolchain needed), set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before installing.
 
 If `npm install -g gitnexus` fails on native modules:
 

package/dist/cli/analyze-config.d.ts

@@ -41,8 +41,8 @@ export declare class GitNexusRcError extends Error {
 }
 /**
  * Validate a user-supplied branch name (from CLI or `.gitnexusrc`). Returns the
- * trimmed name or throws {@link GitNexusRcError}. Conservative but accepts the
- * shapes real branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ * trimmed name or throws {@link GitNexusRcError}. Rules live in
+ * `core/git-ref.ts`; this wrapper keeps the CLI / `.gitnexusrc` error type.
  */
 export declare function validateBranchName(value: string, source: string): string;
 /**

package/dist/cli/analyze-config.js

@@ -30,11 +30,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readRepoControlFile } from '../config/repo-control-file.js';
+import { InvalidBranchError, validateBranchName as validateBranchNameCore, } from '../core/git-ref.js';
 export const GITNEXUS_RC_FILENAME = '.gitnexusrc';
 /** Final fallback when no branch is configured or detectable. */
 export const DEFAULT_BRANCH_FALLBACK = 'main';
-/** Git refs longer than this are almost certainly a mistake / injection attempt. */
-const BRANCH_MAX_LENGTH = 255;
 /**
  * Thrown for any `.gitnexusrc` problem (missing-file is NOT an error — it
  * returns `undefined`). The message is user-facing and names the file so the
@@ -126,41 +125,19 @@ const assertNoHiddenChars = (value, source) => {
 };
 /**
  * Validate a user-supplied branch name (from CLI or `.gitnexusrc`). Returns the
- * trimmed name or throws {@link GitNexusRcError}. Conservative but accepts the
- * shapes real branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ * trimmed name or throws {@link GitNexusRcError}. Rules live in
+ * `core/git-ref.ts`; this wrapper keeps the CLI / `.gitnexusrc` error type.
  */
 export function validateBranchName(value, source) {
-    const trimmed = value.trim();
-    if (!trimmed) {
-        throw new GitNexusRcError(`${source}: branch name must not be empty.`);
-    }
-    if (trimmed.length > BRANCH_MAX_LENGTH) {
-        throw new GitNexusRcError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
-    }
-    assertNoHiddenChars(trimmed, source);
-    if (/\s/.test(trimmed)) {
-        throw new GitNexusRcError(`${source}: branch name must not contain whitespace.`);
-    }
-    // git ref-name rules (subset): reject characters git itself forbids in refs.
-    if (/[~^:?*[\\]/.test(trimmed)) {
-        throw new GitNexusRcError(`${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`);
-    }
-    if (trimmed.startsWith('-')) {
-        throw new GitNexusRcError(`${source}: branch name must not start with "-".`);
-    }
-    if (trimmed.includes('..')) {
-        throw new GitNexusRcError(`${source}: branch name must not contain "..".`);
+    try {
+        return validateBranchNameCore(value, source);
     }
-    // Git permits a backtick in a ref, but the branch is embedded inside a
-    // Markdown inline-code span in the generated AGENTS.md/CLAUDE.md regression
-    // example, where a backtick would close the span early and let the rest of
-    // the template render as instruction text. Reject it at this single
-    // chokepoint so all three tiers (CLI flag, .gitnexusrc, auto-detect via
-    // sanitizeDetectedBranch) are covered (#1996 tri-review P1).
-    if (trimmed.includes('`')) {
-        throw new GitNexusRcError(`${source}: branch name must not contain a backtick (it would break the generated Markdown).`);
+    catch (err) {
+        if (err instanceof InvalidBranchError) {
+            throw new GitNexusRcError(err.message);
+        }
+        throw err;
     }
-    return trimmed;
 }
 /**
  * Best-effort validation for an auto-detected branch (from git). Never throws —

package/dist/cli/optional-grammars.d.ts

@@ -1,14 +1,13 @@
 /**
  * Optional grammar availability check.
  *
- * tree-sitter-dart, -proto, -swift, and -kotlin are vendored under vendor/ and
- * loaded from there by absolute path (NEVER copied into node_modules — see
- * core/tree-sitter/vendored-grammars.ts / #2111). Each ships committed platform
- * prebuilds activated via node-gyp-build. All can be skipped via
- * GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or can silently
- * soft-fail when no prebuild matches the host platform (and a source build was
- * unavailable / not attempted). tree-sitter-zig is the one npm-installed
- * optionalDependency in the list; its `probe` overrides the vendored load.
+ * tree-sitter-dart, -proto, -swift, -kotlin, and -zig are vendored under
+ * vendor/ and loaded from there by absolute path (NEVER copied into
+ * node_modules — see core/tree-sitter/vendored-grammars.ts / #2111). Each
+ * ships committed platform prebuilds activated via node-gyp-build. All can
+ * be skipped via GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or
+ * can silently soft-fail when no prebuild matches the host platform (and a
+ * source build was unavailable / not attempted).
  *
  * Either path produces the same observable: the .node binding is absent
  * at runtime. This helper detects that condition and surfaces a single

package/dist/cli/optional-grammars.js

@@ -1,26 +1,23 @@
 /**
  * Optional grammar availability check.
  *
- * tree-sitter-dart, -proto, -swift, and -kotlin are vendored under vendor/ and
- * loaded from there by absolute path (NEVER copied into node_modules — see
- * core/tree-sitter/vendored-grammars.ts / #2111). Each ships committed platform
- * prebuilds activated via node-gyp-build. All can be skipped via
- * GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or can silently
- * soft-fail when no prebuild matches the host platform (and a source build was
- * unavailable / not attempted). tree-sitter-zig is the one npm-installed
- * optionalDependency in the list; its `probe` overrides the vendored load.
+ * tree-sitter-dart, -proto, -swift, -kotlin, and -zig are vendored under
+ * vendor/ and loaded from there by absolute path (NEVER copied into
+ * node_modules — see core/tree-sitter/vendored-grammars.ts / #2111). Each
+ * ships committed platform prebuilds activated via node-gyp-build. All can
+ * be skipped via GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or
+ * can silently soft-fail when no prebuild matches the host platform (and a
+ * source build was unavailable / not attempted).
  *
  * Either path produces the same observable: the .node binding is absent
  * at runtime. This helper detects that condition and surfaces a single
  * stderr line per missing grammar so users learn why .dart/.proto/.swift/.kt/.zig
  * support is unavailable instead of silently getting a degraded index.
  */
-import { createRequire } from 'node:module';
 import { SupportedLanguages } from '../_shared/index.js';
 import { isGrammarRuntimeSkipped } from '../core/tree-sitter/parser-loader.js';
 import { requireVendoredGrammar } from '../core/tree-sitter/vendored-grammars.js';
 import { cliWarn } from './cli-message.js';
-const _require = createRequire(import.meta.url);
 const OPTIONAL_GRAMMARS = [
     {
         name: 'tree-sitter-dart',
@@ -43,11 +40,9 @@ const OPTIONAL_GRAMMARS = [
     },
     {
         name: 'tree-sitter-zig',
-        pkg: '@tree-sitter-grammars/tree-sitter-zig',
+        pkg: 'tree-sitter-zig',
         extensions: ['.zig'],
         language: SupportedLanguages.Zig,
-        // npm optionalDependency, not vendored — probe via plain require.
-        probe: () => _require('@tree-sitter-grammars/tree-sitter-zig'),
     },
 ];
 /**
@@ -84,12 +79,7 @@ export function detectMissingOptionalGrammars() {
             continue;
         }
         try {
-            if (g.probe !== undefined) {
-                g.probe();
-            }
-            else {
-                requireVendoredGrammar(g.pkg);
-            }
+            requireVendoredGrammar(g.pkg);
         }
         catch (err) {
             const code = err?.code;

package/dist/core/git-ref.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Git ref-name validation used by both the CLI and the HTTP analyze route.
+ *
+ * Lives in `core/` so `server/api.ts` does not import `cli/analyze-config`
+ * (that import closed a cli → server → cli cycle: `cli/serve.ts` already
+ * imports `createServer`). The CLI keeps a thin wrapper that rethrows
+ * {@link InvalidBranchError} as `GitNexusRcError`.
+ */
+/**
+ * Thrown when a user-supplied branch name fails {@link validateBranchName}.
+ * Callers at a product boundary map this to their own error type (CLI:
+ * `GitNexusRcError`; HTTP: 400).
+ */
+export declare class InvalidBranchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a user-supplied branch name. Returns the trimmed name or throws
+ * {@link InvalidBranchError}. Conservative but accepts the shapes real
+ * branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ */
+export declare function validateBranchName(value: string, source: string): string;

package/dist/core/git-ref.js

@@ -0,0 +1,114 @@
+/**
+ * Git ref-name validation used by both the CLI and the HTTP analyze route.
+ *
+ * Lives in `core/` so `server/api.ts` does not import `cli/analyze-config`
+ * (that import closed a cli → server → cli cycle: `cli/serve.ts` already
+ * imports `createServer`). The CLI keeps a thin wrapper that rethrows
+ * {@link InvalidBranchError} as `GitNexusRcError`.
+ */
+/** Git refs longer than this are almost certainly a mistake / injection attempt. */
+const BRANCH_MAX_LENGTH = 255;
+/**
+ * Thrown when a user-supplied branch name fails {@link validateBranchName}.
+ * Callers at a product boundary map this to their own error type (CLI:
+ * `GitNexusRcError`; HTTP: 400).
+ */
+export class InvalidBranchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidBranchError';
+    }
+}
+/**
+ * Reject control characters and hidden / bidirectional Unicode in a string
+ * value. These have no legitimate place in a branch name and would otherwise
+ * let a committed config or HTTP body smuggle invisible controls into
+ * generated AGENTS.md / CLAUDE.md content.
+ */
+const isHiddenOrControl = (codePoint) => codePoint < 0x20 ||
+    codePoint === 0x7f ||
+    (codePoint >= 0x200b && codePoint <= 0x200f) || // zero-width + LRM/RLM
+    (codePoint >= 0x202a && codePoint <= 0x202e) || // bidi embeddings/overrides
+    (codePoint >= 0x2060 && codePoint <= 0x2064) || // word-joiner + invisible math
+    (codePoint >= 0x2066 && codePoint <= 0x206f) || // bidi isolates + deprecated
+    codePoint === 0xfeff; // BOM / zero-width no-break space
+const assertNoHiddenChars = (value, source) => {
+    for (const ch of value) {
+        const cp = ch.codePointAt(0);
+        if (cp !== undefined && isHiddenOrControl(cp)) {
+            throw new InvalidBranchError(`${source}: value contains control or hidden/bidirectional characters, which are not allowed.`);
+        }
+    }
+};
+/**
+ * Validate a user-supplied branch name. Returns the trimmed name or throws
+ * {@link InvalidBranchError}. Conservative but accepts the shapes real
+ * branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ */
+export function validateBranchName(value, source) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new InvalidBranchError(`${source}: branch name must not be empty.`);
+    }
+    if (trimmed.length > BRANCH_MAX_LENGTH) {
+        throw new InvalidBranchError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
+    }
+    assertNoHiddenChars(trimmed, source);
+    if (/\s/.test(trimmed)) {
+        throw new InvalidBranchError(`${source}: branch name must not contain whitespace.`);
+    }
+    // git ref-name rules (subset): reject characters git itself forbids in refs.
+    if (/[~^:?*[\\]/.test(trimmed)) {
+        throw new InvalidBranchError(`${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`);
+    }
+    if (trimmed.startsWith('-')) {
+        throw new InvalidBranchError(`${source}: branch name must not start with "-".`);
+    }
+    // Force-refspec prefix (`git fetch origin +main` / `+refs/heads/main:…`).
+    // Rejected here so neither the CLI nor HTTP can pass a force-update refspec
+    // through as a "branch" (#3199 review, defense in depth).
+    if (trimmed.startsWith('+')) {
+        throw new InvalidBranchError(`${source}: branch name must not start with "+".`);
+    }
+    // The symbolic ref HEAD (case-sensitive). A repo can have a branch named
+    // `head`; git itself treats only `HEAD` as the current-commit alias.
+    if (trimmed === 'HEAD') {
+        throw new InvalidBranchError(`${source}: branch name must not be "HEAD".`);
+    }
+    if (trimmed.includes('..')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain "..".`);
+    }
+    // The remaining `git check-ref-format` rules. Without these the validator
+    // accepted refs git itself refuses (`feature.lock`, `/feature`, `feature/`,
+    // `feature//next`, `@`, `.hidden`), so the failure surfaced later from the
+    // git subprocess instead of here. No real branch can violate them — git
+    // could not have created one — so nothing that works today starts failing.
+    if (trimmed.endsWith('.lock') || trimmed.split('/').some((part) => part.endsWith('.lock'))) {
+        throw new InvalidBranchError(`${source}: branch name must not end with ".lock".`);
+    }
+    if (trimmed.startsWith('/') || trimmed.endsWith('/')) {
+        throw new InvalidBranchError(`${source}: branch name must not start or end with "/".`);
+    }
+    if (trimmed.includes('//')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain consecutive slashes.`);
+    }
+    if (trimmed === '@') {
+        throw new InvalidBranchError(`${source}: branch name must not be the single character "@".`);
+    }
+    if (trimmed.includes('@{')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain "@{".`);
+    }
+    if (trimmed.endsWith('.') || trimmed.split('/').some((part) => part.startsWith('.'))) {
+        throw new InvalidBranchError(`${source}: branch name must not end with "." or have a path component starting with ".".`);
+    }
+    // Git permits a backtick in a ref, but the branch is embedded inside a
+    // Markdown inline-code span in the generated AGENTS.md/CLAUDE.md regression
+    // example, where a backtick would close the span early and let the rest of
+    // the template render as instruction text. Reject it at this single
+    // chokepoint so all three tiers (CLI flag, .gitnexusrc, auto-detect via
+    // sanitizeDetectedBranch) are covered (#1996 tri-review P1).
+    if (trimmed.includes('`')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain a backtick (it would break the generated Markdown).`);
+    }
+    return trimmed;
+}

package/dist/core/ingestion/call-extractors/zig-static-gating.d.ts

@@ -11,17 +11,14 @@
  * Conservative by design: we only tag an edge when we can prove the
  * gating expression evaluates to `false`.  Anything ambiguous → live.
  *
- * Scope of v1:
+ * Supported scope:
  *
  *   (a) **File-local** consts (`pub const FOO = false;`, plus const-to-const
  *       aliases up to 5 hops), built once per file by `buildZigBoolConstMap`.
- *   (b) **Cross-file** (`const cfg = @import("./cfg.zig"); if (cfg.FOO)`) is
- *       NOT resolved yet. The evaluator keeps the seam for it (`importAliases`
- *       + `lookupBoolsForPath`, consumed by the `field_expression` case), but
- *       the only caller passes an empty alias map and a lookup that always
- *       returns `undefined`, because the capture emitter runs in the parse
- *       worker and sees only the current file. Tracked in #3162. Until then
- *       every `cfg.FOO` condition folds to unknown, i.e. live.
+ *   (b) **Cross-file** direct imports (`const cfg = @import("./cfg.zig");
+ *       if (cfg.FOO)`) are enriched after per-file extraction. The workspace
+ *       caller supplies `importAliases` and `lookupBoolsForPath`; the parse
+ *       worker still uses empty/undefined inputs and remains file-local.
  *
  * Also out of scope: multi-hop member access (`cfg.sub.FOO`), re-exported
  * consts, runtime-evaluated bools (`const FOO = computeIt();`), and

package/dist/core/ingestion/languages/zig/query.js

@@ -1,14 +1,13 @@
 import Parser from 'tree-sitter';
-import { createRequire } from 'node:module';
-const _require = createRequire(import.meta.url);
+import { requireVendoredGrammar } from '../../../tree-sitter/vendored-grammars.js';
 /**
  * Zig scope-resolution query (RFC #909 Ring 3).
  *
- * The grammar is an optionalDependency (`@tree-sitter-grammars/tree-sitter-zig`),
- * so the language module is required lazily and `getZigParser` /
- * `getZigScopeQuery` throw only when actually invoked without the grammar
- * installed. That is safe: the parse pipeline filters `.zig` files through
- * `parser-loader.isLanguageAvailable` before any scope extraction runs.
+ * The grammar is vendored (`vendor/tree-sitter-zig`) and may be absent on a
+ * platform without a prebuild, so the language module is required lazily and
+ * `getZigParser` / `getZigScopeQuery` throw only when actually invoked without
+ * the grammar installed. That is safe: the parse pipeline filters `.zig` files
+ * through `parser-loader.isLanguageAvailable` before any scope extraction runs.
  *
  * Zig specifics encoded here:
  *   - Containers (struct/enum/union/opaque) are anonymous nodes bound by the
@@ -409,7 +408,7 @@ const ZIG_SCOPE_QUERY = `
 let _parser = null;
 let _query = null;
 function getZigLanguage() {
-    return _require('@tree-sitter-grammars/tree-sitter-zig');
+    return requireVendoredGrammar('tree-sitter-zig');
 }
 export function getZigParser() {
     if (_parser === null) {

package/dist/core/ingestion/languages/zig/scope-resolver.js

@@ -16,6 +16,7 @@ import { resolveZigImportInternal } from '../../import-resolvers/zig.js';
 import { zigProvider } from '../zig.js';
 import { expandZigWildcardNames, zigArityCompatibility, zigMergeBindings } from './index.js';
 import { populateZigRangeBindings } from './range-binding.js';
+import { populateZigWorkspaceStaticGating } from './workspace-static-gating.js';
 export const zigScopeResolver = {
     language: SupportedLanguages.Zig,
     languageProvider: zigProvider,
@@ -48,6 +49,7 @@ export const zigScopeResolver = {
     arityCompatibility: zigArityCompatibility,
     buildMro: (graph, parsedFiles, nodeLookup) => buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
     populateOwners: (parsed) => populateClassOwnedMembers(parsed),
+    populateWorkspaceReferences: populateZigWorkspaceStaticGating,
     // Payload captures — `for (items) |it|`, `if (opt) |v|`, `while (it.next())
     // |x|` — typed from the subject's binding after finalize (F6).
     populateRangeBindings: populateZigRangeBindings,

package/dist/core/ingestion/languages/zig/workspace-static-gating.d.ts

@@ -0,0 +1,8 @@
+import type { ParsedFile } from '../../../../_shared/index.js';
+export declare function populateZigWorkspaceStaticGating(parsedFiles: ParsedFile[], ctx: {
+    readonly fileContents: ReadonlyMap<string, string>;
+    readonly treeCache?: {
+        get(filePath: string): unknown;
+    };
+    readonly resolutionConfig?: unknown;
+}): void;

package/dist/core/ingestion/languages/zig/workspace-static-gating.js

@@ -0,0 +1,76 @@
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { resolveZigImportInternal } from '../../import-resolvers/zig.js';
+import { buildZigBoolConstMap, collectZigStaticGatedRanges, isPositionStaticGated, } from '../../call-extractors/zig-static-gating.js';
+import { parseSourceSafe, ParseTimeoutError } from '../../../tree-sitter/safe-parse.js';
+import { getZigParser } from './query.js';
+export function populateZigWorkspaceStaticGating(parsedFiles, ctx) {
+    const parser = getZigParser();
+    const trees = new Map();
+    const bools = new Map();
+    for (const parsed of parsedFiles) {
+        const source = ctx.fileContents.get(parsed.filePath);
+        if (source === undefined)
+            continue;
+        let tree = ctx.treeCache?.get(parsed.filePath);
+        if (tree === undefined) {
+            try {
+                tree = parseSourceSafe(parser, source, undefined, {
+                    bufferSize: getTreeSitterBufferSize(source),
+                });
+            }
+            catch (err) {
+                if (err instanceof ParseTimeoutError)
+                    continue;
+                throw err;
+            }
+        }
+        trees.set(parsed.filePath, tree);
+        bools.set(parsed.filePath, buildZigBoolConstMap(tree.rootNode));
+    }
+    const knownPaths = new Set(trees.keys());
+    for (const [index, parsed] of parsedFiles.entries()) {
+        const tree = trees.get(parsed.filePath);
+        if (tree === undefined)
+            continue;
+        const aliases = collectImportAliases(tree, parsed.filePath, knownPaths, ctx.resolutionConfig);
+        if (aliases.size === 0)
+            continue;
+        const ranges = collectZigStaticGatedRanges(tree.rootNode, bools.get(parsed.filePath) ?? new Map(), aliases, (filePath) => bools.get(filePath));
+        if (ranges.length === 0)
+            continue;
+        const next = parsed.referenceSites.map((site) => site.kind === 'call' &&
+            site.staticGated !== true &&
+            isPositionStaticGated(site.atRange.startLine, site.atRange.startCol, ranges)
+            ? { ...site, staticGated: true }
+            : site);
+        parsedFiles[index] = Object.freeze({ ...parsed, referenceSites: Object.freeze(next) });
+    }
+}
+function collectImportAliases(tree, fromFile, knownPaths, resolutionConfig) {
+    const candidates = new Map();
+    const declarationCounts = new Map();
+    for (const decl of tree.rootNode.descendantsOfType('variable_declaration')) {
+        const names = decl.namedChildren.filter((node) => node.type === 'identifier');
+        const binding = names[0]?.text;
+        if (binding === undefined)
+            continue;
+        declarationCounts.set(binding, (declarationCounts.get(binding) ?? 0) + 1);
+        const builtin = decl.namedChildren.find((node) => node.type === 'builtin_function' && node.text.startsWith('@import('));
+        const raw = builtin?.descendantsOfType('string').at(0)?.text;
+        if (raw === undefined)
+            continue;
+        const specifier = raw.replace(/^['"]|['"]$/g, '');
+        const target = resolveZigImportInternal(fromFile, specifier, knownPaths, resolutionConfig);
+        if (target !== null)
+            candidates.set(binding, target);
+    }
+    const aliases = new Map();
+    for (const [binding, target] of candidates) {
+        // Alias lookup below is name-based rather than position-aware. If a name
+        // is redeclared in another lexical scope, fail open instead of applying
+        // either module's constants to every use of that spelling.
+        if (declarationCounts.get(binding) === 1)
+            aliases.set(binding, target);
+    }
+    return aliases;
+}

package/dist/core/ingestion/parsing-processor.d.ts

@@ -3,6 +3,7 @@ import type { SymbolTableWriter } from './model/index.js';
 import { type ExportedTypeMap } from './call-processor.js';
 import type { ParsedFile } from '../../_shared/index.js';
 import { WorkerPool } from './workers/worker-pool.js';
+import type { DispatchGroup } from './workers/worker-pool.js';
 import type { ParseWorkerResult, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedModuleConstants, ExtractedToolDef, FileScopeBindings, ExtractedORMQuery, FetchWrapperDef } from './workers/parse-worker.js';
 import type { ExtractedRouterConstructorPrefix, ExtractedRouterImport, ExtractedRouterInclude, ExtractedRouterModuleAlias } from './route-extractors/fastapi-router-bindings.js';
 import type { SharedSpringType } from './route-extractors/spring-shared.js';
@@ -47,12 +48,12 @@ export interface WorkerExtractedData {
  */
 export declare const mergeChunkResults: (graph: KnowledgeGraph, symbolTable: SymbolTableWriter, chunkResults: readonly ParseWorkerResult[], exportedTypeMap?: ExportedTypeMap) => WorkerExtractedData;
 /**
- * Dispatch a chunk's files to the worker pool and return the RAW per-worker
- * results, WITHOUT merging them into the graph. Split out from
- * {@link processParsing} so the parse loop can overlap one chunk's
- * merge (main-thread, via {@link mergeChunkResults}) with the NEXT chunk's
- * worker parse — the merge is the only remaining serial main-thread step once
- * ParsedFile serialization moved into the workers (#worker-idle pipelining).
+ * Dispatch ONE chunk's files to the worker pool and return the RAW per-worker
+ * results, WITHOUT merging them into the graph. A thin single-group wrapper
+ * over {@link dispatchChunkParseRound}, used by {@link processParsing}'s
+ * one-shot path. The chunk-to-chunk overlap this once described now lives in
+ * `parse-impl.ts` at ROUND granularity (`startRound` / `drainRound` /
+ * `closeRound`), which batches several chunks into one dispatch.
  * Returns `[]` for an all-unparseable chunk (the caller merges `[]` → empty).
  */
 export declare const dispatchChunkParse: (files: {
@@ -67,6 +68,21 @@ outRawResults?: ParseWorkerResult[],
  * (#2038). `undefined` ⇒ no durable write (tests / no-cache path).
  */
 chunkHash?: string) => Promise<ParseWorkerResult[]>;
+/**
+ * Dispatch SEVERAL parse-cache chunks as one pool round and return their raw
+ * results, one array per input group in input order.
+ *
+ * `WorkerPool.dispatch` is a barrier, so one round-trip per chunk leaves most
+ * slots idle whenever a chunk is smaller than the pool — which stable
+ * `(language, hash(path) % 128)` packs usually are. Batching chunks into one
+ * `dispatchGroups` call removes those barriers; jobs are still cut at chunk
+ * boundaries, so every result stays attributable to the chunk whose cache key
+ * owns it.
+ */
+export declare const dispatchChunkParseRound: (groups: ReadonlyArray<DispatchGroup<{
+    path: string;
+    content: string;
+}>>, workerPool: WorkerPool, onFileProgress?: FileProgressCallback) => Promise<ParseWorkerResult[][]>;
 export declare const processParsing: (graph: KnowledgeGraph, files: {
     path: string;
     content: string;

package/dist/core/ingestion/parsing-processor.js

@@ -147,12 +147,12 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
     };
 };
 /**
- * Dispatch a chunk's files to the worker pool and return the RAW per-worker
- * results, WITHOUT merging them into the graph. Split out from
- * {@link processParsing} so the parse loop can overlap one chunk's
- * merge (main-thread, via {@link mergeChunkResults}) with the NEXT chunk's
- * worker parse — the merge is the only remaining serial main-thread step once
- * ParsedFile serialization moved into the workers (#worker-idle pipelining).
+ * Dispatch ONE chunk's files to the worker pool and return the RAW per-worker
+ * results, WITHOUT merging them into the graph. A thin single-group wrapper
+ * over {@link dispatchChunkParseRound}, used by {@link processParsing}'s
+ * one-shot path. The chunk-to-chunk overlap this once described now lives in
+ * `parse-impl.ts` at ROUND granularity (`startRound` / `drainRound` /
+ * `closeRound`), which batches several chunks into one dispatch.
  * Returns `[]` for an all-unparseable chunk (the caller merges `[]` → empty).
  */
 export const dispatchChunkParse = async (files, workerPool, onFileProgress, 
@@ -164,23 +164,42 @@ outRawResults,
  * (#2038). `undefined` ⇒ no durable write (tests / no-cache path).
  */
 chunkHash) => {
-    const parseableFiles = [];
-    for (const file of files) {
-        const lang = getLanguageFromFilename(file.path);
-        if (lang)
-            parseableFiles.push({ path: file.path, content: file.content });
-    }
-    if (parseableFiles.length === 0)
-        return [];
-    const total = files.length;
-    const chunkResults = await workerPool.dispatch(parseableFiles, (filesProcessed) => {
-        onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');
-    }, chunkHash);
+    const [chunkResults = []] = await dispatchChunkParseRound([{ items: files, chunkHash }], workerPool, onFileProgress);
     // Capture raw results for the incremental parse cache before merging.
     if (outRawResults) {
         for (const r of chunkResults)
             outRawResults.push(r);
     }
+    return chunkResults;
+};
+/**
+ * Dispatch SEVERAL parse-cache chunks as one pool round and return their raw
+ * results, one array per input group in input order.
+ *
+ * `WorkerPool.dispatch` is a barrier, so one round-trip per chunk leaves most
+ * slots idle whenever a chunk is smaller than the pool — which stable
+ * `(language, hash(path) % 128)` packs usually are. Batching chunks into one
+ * `dispatchGroups` call removes those barriers; jobs are still cut at chunk
+ * boundaries, so every result stays attributable to the chunk whose cache key
+ * owns it.
+ */
+export const dispatchChunkParseRound = async (groups, workerPool, onFileProgress) => {
+    const dispatchGroups = groups.map((group) => {
+        const items = [];
+        for (const file of group.items) {
+            const lang = getLanguageFromFilename(file.path);
+            if (lang)
+                items.push({ path: file.path, content: file.content });
+        }
+        return { items, chunkHash: group.chunkHash };
+    });
+    const total = groups.reduce((sum, group) => sum + group.items.length, 0);
+    if (dispatchGroups.every((group) => group.items.length === 0))
+        return groups.map(() => []);
+    const perGroup = await workerPool.dispatchGroups(dispatchGroups, (filesProcessed) => {
+        onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');
+    });
+    const chunkResults = perGroup.flat();
     // Skipped-language telemetry (worker output, independent of the merge).
     const skippedLanguages = new Map();
     for (const result of chunkResults) {
@@ -238,7 +257,7 @@ chunkHash) => {
         logger.warn(`  Sanitized ${skippedPaths.length} file(s) with non-serializable parse output: ${shown}${more}`);
     }
     onFileProgress?.(total, total, 'done');
-    return chunkResults;
+    return perGroup;
 };
 // ============================================================================
 // Public API