gitnexus 1.6.2-rc.21 → 1.6.2-rc.22

package/dist/core/ingestion/model/resolve.js

@@ -233,35 +233,112 @@ const buildParentMapFromHeritage = (startNodeId, heritageMap) => {
 // MRO-aware method lookup
 // ---------------------------------------------------------------------------
 /**
- * Look up a method on an owner class, walking the parent chain via HeritageMap
- * when the method isn't found on the direct owner.
+ * DAG stage 5 helper: look up a method on an owner class via MRO walk.
  *
- * Respects the 5 per-language MRO strategies:
- * - `first-wins`:       BFS ancestor walk, first match wins (default)
- * - `leftmost-base`:    BFS ancestor walk, leftmost base in declaration order wins (C++);
- *                        HeritageMap preserves insertion order matching source declaration,
- *                        so BFS order is equivalent to leftmost-base semantics
- * - `c3`:               C3-linearized ancestor order, first match wins (Python)
- * - `implements-split`: BFS ancestor walk, first match wins (Java/C#) —
- *                        full ambiguity detection for multiple interface defaults
- *                        is handled by computeMRO at graph level
- * - `qualified-syntax`: No auto-resolution (Rust) — returns undefined
+ * Low-level resolver; no dependency on SymbolTable, language registry, or
+ * resolution-context (keeps model/ layer free of cross-layer imports).
+ * All strategies respect `argCount` for overload narrowing.
+ * `ancestryOverride` replaces the default walk; caller must compute it correctly.
  *
- * Uses the `c3Linearize` defined in this file (also consumed by
- * mro-processor.ts for graph-level MRO emission) for the `c3` strategy.
+ * Strategy summary (full docs in gitnexus-shared/mro-strategy.ts):
+ * - `first-wins` / `leftmost-base` / `implements-split`: BFS, first match wins.
+ * - `c3`: C3-linearized order; falls back to BFS on cycle/inconsistency.
+ * - `qualified-syntax`: returns undefined immediately (Rust requires explicit syntax).
+ * - `ruby-mixin`: kind-aware walk — see inline comments below.
  *
- * Depends only on {@link SemanticModel} + {@link HeritageMap} + an
- * {@link MroStrategy} literal — NO dependency on SymbolTable, the language
- * registry, or resolution-context, which keeps the `model/` module free of
- * cross-layer imports. Callers derive the strategy from their language
- * provider before invoking this function.
+ * Internal API: exported for call-processor resolvers and tests.
+ * External callers should use resolveMemberCall instead.
  *
- * @internal This is the low-level MRO walker. Exported so call-processor's
- * higher-level resolvers (and unit tests) can invoke it directly. Callers
- * outside `core/ingestion/` should use the higher-level resolvers in
- * call-processor.ts instead of depending on this function.
+ * @see gitnexus-shared/mro-strategy.ts § 'ruby-mixin'
+ * @see call-processor.ts § resolveMemberCall
  */
-export const lookupMethodByOwnerWithMRO = (ownerNodeId, methodName, heritageMap, model, strategy, argCount) => {
+export const lookupMethodByOwnerWithMRO = (ownerNodeId, methodName, heritageMap, model, strategy, argCount, 
+/**
+ * Optional pre-computed ancestry list. When provided, overrides the default
+ * per-strategy ancestry source. Primarily used by Ruby singleton dispatch:
+ * the caller supplies `heritageMap.getSingletonAncestry(ownerNodeId)` as
+ * node-id array so this walker resolves against `extend` providers only.
+ *
+ * For `ruby-mixin` strategy, passing an override switches the walker into
+ * a no-prepend-no-direct linear scan (the caller has already decided the
+ * order), which is the correct semantics for singleton dispatch.
+ */
+ancestryOverride) => {
+    // ── Ruby mixin strategy ───────────────────────────────────────────
+    // Kind-aware walk — does NOT short-circuit on direct owner first (prepend beats direct).
+    // Instance dispatch: prepend (reverse) → direct → include (reverse) → transitive BFS.
+    // Singleton dispatch: caller supplies ancestryOverride (extend providers only);
+    //   simple left-to-right scan. Miss NEVER falls through to file-scoped fallback.
+    // See gitnexus-shared/mro-strategy.ts § 'ruby-mixin' for full strategy docs.
+    if (strategy === 'ruby-mixin') {
+        if (ancestryOverride) {
+            // Singleton dispatch: scan pre-computed ancestry only. Miss null-routes.
+            for (const ancestorId of ancestryOverride) {
+                const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+                if (method)
+                    return method;
+            }
+            return undefined;
+        }
+        // Instance dispatch — kind-aware walk per the pseudocode above.
+        const instanceEntries = heritageMap.getInstanceAncestry(ownerNodeId);
+        // Partition into prepend parents vs other parents (extends / include /
+        // implements / trait-impl), preserving declaration order within each.
+        const prependParents = [];
+        const otherParents = [];
+        for (const e of instanceEntries) {
+            if (e.kind === 'prepend')
+                prependParents.push(e.parentId);
+            else
+                otherParents.push(e.parentId);
+        }
+        // Step 1: Walk prepend parents in REVERSE declaration order (last-prepended wins).
+        for (let i = prependParents.length - 1; i >= 0; i--) {
+            const method = model.methods.lookupMethodByOwner(prependParents[i], methodName, argCount);
+            if (method)
+                return method;
+        }
+        // Step 2: Direct owner lookup (the class's own method).
+        // This is the only difference from other strategies — prepend beats direct.
+        const direct = model.methods.lookupMethodByOwner(ownerNodeId, methodName, argCount);
+        if (direct)
+            return direct;
+        // Step 3: Walk extends + include parents in REVERSE declaration order.
+        // (Ruby `include A; include B` puts B ahead of A in MRO.)
+        for (let i = otherParents.length - 1; i >= 0; i--) {
+            const method = model.methods.lookupMethodByOwner(otherParents[i], methodName, argCount);
+            if (method)
+                return method;
+        }
+        // Step 4: Transitive ancestors (a mixin that itself mixes in another module).
+        // Fall back to the BFS ancestor walk for depth > 1. Order is best-effort;
+        // Ruby's actual MRO for transitive mixins is rare and under-specified
+        // (documented in architecture docs as deferred work).
+        //
+        // O(1) skip-check via Sets:
+        //   - `walkedDirect` covers parents already visited in steps 1-3.
+        //   - `singletonOnly` covers direct `extend` providers: they belong to
+        //     the singleton MRO and must NEVER appear in instance dispatch.
+        // Building Sets once before the BFS loop avoids O(n²) `Array.includes`
+        // on large mixin hierarchies.
+        const walkedDirect = new Set(prependParents);
+        for (const id of otherParents)
+            walkedDirect.add(id);
+        const singletonOnly = new Set(heritageMap.getSingletonAncestry(ownerNodeId).map((e) => e.parentId));
+        for (const ancestorId of heritageMap.getAncestors(ownerNodeId)) {
+            if (ancestorId === ownerNodeId)
+                continue;
+            if (walkedDirect.has(ancestorId))
+                continue;
+            if (singletonOnly.has(ancestorId))
+                continue;
+            const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+            if (method)
+                return method;
+        }
+        return undefined;
+    }
+    // ── Non-Ruby strategies: direct-owner-first short-circuit ─────────
     // Direct lookup first (child override — no walk needed).
     // argCount is threaded through so arity-differing overloads on the direct
     // owner can be disambiguated before the MRO walk starts.
@@ -274,7 +351,10 @@ export const lookupMethodByOwnerWithMRO = (ownerNodeId, methodName, heritageMap,
     // Determine ancestor walk order based on MRO strategy.
     // readonly to accept the cached (frozen) c3 linearization without copying.
     let ancestors;
-    if (strategy === 'c3') {
+    if (ancestryOverride) {
+        ancestors = ancestryOverride;
+    }
+    else if (strategy === 'c3') {
         // C3 linearization (memoized per HeritageMap
         // so repeated calls for the same owner within an ingestion run reuse the
         // linearization instead of rebuilding the parent map and re-running C3).

package/dist/core/ingestion/pipeline-phases/parse-impl.d.ts

@@ -43,5 +43,6 @@ export declare function runChunkedParseAndResolve(graph: KnowledgeGraph, scanned
     allORMQueries: ExtractedORMQuery[];
     bindingAccumulator: BindingAccumulator;
     resolutionContext: ReturnType<typeof createResolutionContext>;
+    usedWorkerPool: boolean;
 }>;
 export {};

package/dist/core/ingestion/pipeline-phases/parse-impl.js

@@ -98,9 +98,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         message: `Parsing ${totalParseable} files in ${numChunks} chunk${numChunks !== 1 ? 's' : ''}...`,
         stats: { filesProcessed: 0, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
     });
-    // Don't spawn workers for tiny repos — overhead exceeds benefit
-    const MIN_FILES_FOR_WORKERS = 15;
-    const MIN_BYTES_FOR_WORKERS = 512 * 1024;
+    // Don't spawn workers for tiny repos — overhead exceeds benefit.
+    // Test suites may lower the thresholds via `options.workerThresholdsForTest`
+    // to exercise the worker-pool path with small fixtures; see PipelineOptions.
+    const MIN_FILES_FOR_WORKERS = options?.workerThresholdsForTest?.minFiles ?? 15;
+    const MIN_BYTES_FOR_WORKERS = options?.workerThresholdsForTest?.minBytes ?? 512 * 1024;
     const totalBytes = parseableScanned.reduce((s, f) => s + f.size, 0);
     // Create worker pool once, reuse across chunks
     let workerPool;
@@ -433,5 +435,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         allORMQueries,
         bindingAccumulator,
         resolutionContext: ctx,
+        // Whether a worker pool was actually live for this run. False means the
+        // sequential fallback handled every chunk (either due to `skipWorkers`,
+        // the file-count/byte thresholds, or a pool-creation failure).
+        usedWorkerPool: workerPool !== undefined,
     };
 }

package/dist/core/ingestion/pipeline-phases/parse.d.ts

@@ -45,5 +45,12 @@ export interface ParseOutput {
     readonly allPathSet: ReadonlySet<string>;
     /** Pass-through: total file count for progress reporting. */
     totalFiles: number;
+    /**
+     * True if the parse phase spawned a live worker pool for this run.
+     * False means every chunk ran through the sequential fallback (skipWorkers,
+     * thresholds not met, or pool-creation failure). Primarily a test affordance:
+     * see `PipelineOptions.workerThresholdsForTest`.
+     */
+    readonly usedWorkerPool: boolean;
 }
 export declare const parsePhase: PipelinePhase<ParseOutput>;

package/dist/core/ingestion/pipeline.d.ts

@@ -21,5 +21,16 @@ export interface PipelineOptions {
     skipGraphPhases?: boolean;
     /** Force sequential parsing (no worker pool). Useful for testing the sequential path. */
     skipWorkers?: boolean;
+    /**
+     * @internal Test-only override for worker-pool gating thresholds.
+     * When unset, production defaults apply (15 files OR 512 KB total bytes).
+     * Setting either field lowers the corresponding threshold so small test
+     * fixtures can still exercise the worker-pool path. Do not use from
+     * production call sites.
+     */
+    workerThresholdsForTest?: {
+        minFiles?: number;
+        minBytes?: number;
+    };
 }
 export declare const runPipelineFromRepo: (repoPath: string, onProgress: (progress: PipelineProgress) => void, options?: PipelineOptions) => Promise<PipelineResult>;

package/dist/core/ingestion/pipeline.js

@@ -58,7 +58,7 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
         pipelineStart,
     });
     // Extract final results for the PipelineResult contract
-    const { totalFiles } = getPhaseOutput(results, 'parse');
+    const { totalFiles, usedWorkerPool } = getPhaseOutput(results, 'parse');
     let communityResult;
     let processResult;
     if (!options?.skipGraphPhases) {
@@ -77,5 +77,12 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
             nodesCreated: graph.nodeCount,
         },
     });
-    return { graph, repoPath, totalFileCount: totalFiles, communityResult, processResult };
+    return {
+        graph,
+        repoPath,
+        totalFileCount: totalFiles,
+        communityResult,
+        processResult,
+        usedWorkerPool,
+    };
 };

package/dist/core/ingestion/utils/ast-helpers.js

@@ -141,7 +141,14 @@ export const CONTAINER_TYPE_TO_LABEL = {
     mixin_declaration: 'Mixin',
     extension_declaration: 'Extension',
     class: 'Class',
-    module: 'Module',
+    // Ruby `module` declarations map to `Trait` so they participate in the
+    // class-like type registry used by `lookupClassByName` / `buildHeritageMap`.
+    // This lets `include` / `extend` / `prepend` mixin heritage resolve to
+    // the providing module. Safe for non-Ruby languages: the only supported
+    // grammar that uses the bare `module` AST node type as a container is
+    // Ruby (Rust uses `mod_item`). Any new language adding a `module` node
+    // type must explicitly reclassify here.
+    module: 'Trait',
     singleton_class: 'Class', // Ruby: class << self inherits enclosing class name
     object_declaration: 'Class',
     companion_object: 'Class',
@@ -177,8 +184,18 @@ export function getLabelFromCaptures(captureMap, provider) {
         return 'Enum';
     if (captureMap['definition.namespace'])
         return 'Namespace';
-    if (captureMap['definition.module'])
+    if (captureMap['definition.module']) {
+        // Let providers reclassify module captures (e.g. Ruby remaps `Module`→`Trait`
+        // so mixin heritage resolves through `lookupClassByName`). Returning null
+        // from labelOverride means "skip this symbol"; treat it as a no-op here so
+        // we keep the default label rather than dropping a real definition.
+        if (provider.labelOverride) {
+            const override = provider.labelOverride(captureMap['definition.module'], 'Module');
+            if (override && override !== 'Module')
+                return override;
+        }
         return 'Module';
+    }
     if (captureMap['definition.trait'])
         return 'Trait';
     if (captureMap['definition.impl'])

package/dist/core/ingestion/utils/ruby-self-call.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Ruby bare-call self-inference helper.
+ *
+ * Ruby makes `self` implicit for method calls inside instance and class bodies:
+ * `serialize` inside `Account#call_serialize` means `self.serialize`. Other
+ * supported languages make the receiver explicit in source (`this.x`, `self.x`),
+ * so tree-sitter produces a member call directly. Ruby's bare identifier
+ * produces either `callForm === 'free'` or `callForm === undefined` (body_statement
+ * identifier captures where the @call node IS the @call.name node), and
+ * `resolveFreeCall` does a global tiered name lookup — no MRO walk.
+ *
+ * This helper is a pure decision function consumed by the Ruby language
+ * provider's `inferImplicitReceiver` hook. Shared pipeline code never imports
+ * it directly — only `languages/ruby.ts` does.
+ */
+import type { SyntaxNode } from './ast-helpers.js';
+import type { LanguageProvider } from '../language-provider.js';
+/**
+ * Rewrite suggestion returned by `maybeRewriteRubyBareCallToSelf`.
+ *
+ * `callForm` is always `'member'`; `receiverName` is always `'self'`.
+ * `dispatchKind` controls the stage-4 ancestry view:
+ * - `'instance'` → prepend → direct → include (normal MRO)
+ * - `'singleton'` → extend providers only, no file-scoped fallback
+ *
+ * Consumed by `languages/ruby.ts § inferImplicitReceiver` (wraps into
+ * `ImplicitReceiverOverride`; `dispatchKind` becomes the `hint` field).
+ */
+export interface SelfCallRewrite {
+    readonly callForm: 'member';
+    readonly receiverName: 'self';
+    readonly receiverTypeName: string;
+    /** `'singleton'` when the enclosing method is `def self.foo` / inside a
+     *  `singleton_class` body; `'instance'` otherwise. Controls MRO ancestry
+     *  view selection in stage-4 dispatch. */
+    readonly dispatchKind: 'instance' | 'singleton';
+}
+/**
+ * Pure decision function: should a bare Ruby call be rewritten as `self.method`?
+ *
+ * Returns a `SelfCallRewrite` when all gates pass; null otherwise.
+ * Gates (all required): `callForm` is `'free'` or `undefined`, strategy is
+ * `'ruby-mixin'`, `enclosingClassName` is non-null, name is not `'super'`,
+ * name is not a built-in.
+ *
+ * Note: Ruby body-statement identifiers produce `callForm === undefined` because
+ * the @call node IS the @call.name node in tree-sitter-ruby.
+ *
+ * Example: `calledName='serialize'` in `Account` instance method →
+ * `{callForm:'member', receiverName:'self', receiverTypeName:'Account', dispatchKind:'instance'}`
+ */
+export declare function maybeRewriteRubyBareCallToSelf(calledName: string, callForm: 'free' | 'member' | 'constructor' | undefined, callNode: SyntaxNode, enclosingClassName: string | null, provider: Pick<LanguageProvider, 'isBuiltInName' | 'mroStrategy'>): SelfCallRewrite | null;

package/dist/core/ingestion/utils/ruby-self-call.js

@@ -0,0 +1,59 @@
+// gitnexus/src/core/ingestion/utils/ruby-self-call.ts
+/** Maximum parent-walk depth to prevent runaway traversal. */
+const MAX_PARENT_DEPTH = 50;
+/**
+ * Returns true if `callNode` is inside a `singleton_method` or `singleton_class`.
+ * Stops at `class`/`module` boundary or MAX_PARENT_DEPTH (50) to bound traversal.
+ */
+function isInsideSingletonMethod(callNode) {
+    let current = callNode.parent;
+    let depth = 0;
+    while (current && depth++ < MAX_PARENT_DEPTH) {
+        if (current.type === 'singleton_method')
+            return true;
+        if (current.type === 'singleton_class')
+            return true;
+        if (current.type === 'class' || current.type === 'module')
+            return false;
+        current = current.parent;
+    }
+    return false;
+}
+/**
+ * Pure decision function: should a bare Ruby call be rewritten as `self.method`?
+ *
+ * Returns a `SelfCallRewrite` when all gates pass; null otherwise.
+ * Gates (all required): `callForm` is `'free'` or `undefined`, strategy is
+ * `'ruby-mixin'`, `enclosingClassName` is non-null, name is not `'super'`,
+ * name is not a built-in.
+ *
+ * Note: Ruby body-statement identifiers produce `callForm === undefined` because
+ * the @call node IS the @call.name node in tree-sitter-ruby.
+ *
+ * Example: `calledName='serialize'` in `Account` instance method →
+ * `{callForm:'member', receiverName:'self', receiverTypeName:'Account', dispatchKind:'instance'}`
+ */
+export function maybeRewriteRubyBareCallToSelf(calledName, callForm, callNode, enclosingClassName, provider) {
+    // Body-statement bare identifiers produce `callForm === undefined` because
+    // the @call node IS the @call.name node in tree-sitter-ruby. Treat both
+    // undefined and 'free' as qualifying.
+    if (callForm !== 'free' && callForm !== undefined)
+        return null;
+    if (provider.mroStrategy !== 'ruby-mixin')
+        return null;
+    if (!enclosingClassName)
+        return null;
+    if (calledName === 'super')
+        return null;
+    if (provider.isBuiltInName(calledName))
+        return null;
+    const dispatchKind = isInsideSingletonMethod(callNode)
+        ? 'singleton'
+        : 'instance';
+    return {
+        callForm: 'member',
+        receiverName: 'self',
+        receiverTypeName: enclosingClassName,
+        dispatchKind,
+    };
+}

package/dist/core/ingestion/workers/parse-worker.js

@@ -1021,33 +1021,36 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         // Heritage edges (EXTENDS/IMPLEMENTS) are created by heritage-processor which runs
         // in PARALLEL with call-processor, so the graph edges don't exist when buildTypeEnv
         // runs. This pre-pass makes parent class information available for type resolution.
+        const provider = getProvider(language);
         const fileParentMap = new Map();
-        for (const match of matches) {
-            const captureMap = {};
-            for (const c of match.captures) {
-                captureMap[c.name] = c.node;
-            }
-            if (captureMap['heritage.class'] && captureMap['heritage.extends']) {
-                const className = captureMap['heritage.class'].text;
-                const parentName = captureMap['heritage.extends'].text;
-                // Skip Go named fields (only anonymous fields are struct embedding)
-                const extendsNode = captureMap['heritage.extends'];
-                const fieldDecl = extendsNode.parent;
-                if (fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName('name'))
-                    continue;
-                let parents = fileParentMap.get(className);
-                if (!parents) {
-                    parents = [];
-                    fileParentMap.set(className, parents);
+        if (provider.heritageExtractor) {
+            for (const match of matches) {
+                const captureMap = {};
+                for (const c of match.captures) {
+                    captureMap[c.name] = c.node;
+                }
+                if (captureMap['heritage.class']) {
+                    const heritageItems = provider.heritageExtractor.extract(captureMap, {
+                        filePath: file.path,
+                        language,
+                    });
+                    for (const item of heritageItems) {
+                        if (item.kind === 'extends') {
+                            let parents = fileParentMap.get(item.className);
+                            if (!parents) {
+                                parents = [];
+                                fileParentMap.set(item.className, parents);
+                            }
+                            if (!parents.includes(item.parentName))
+                                parents.push(item.parentName);
+                        }
+                    }
                 }
-                if (!parents.includes(parentName))
-                    parents.push(parentName);
             }
         }
         // Build per-file type environment + constructor bindings in a single AST walk.
         // Constructor bindings are verified against the SymbolTable in processCallsFromExtracted.
         const parentMap = fileParentMap;
-        const provider = getProvider(language);
         const typeEnv = buildTypeEnv(tree, language, {
             parentMap,
             enclosingFunctionFinder: provider?.enclosingFunctionFinder,
@@ -1291,7 +1294,23 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                     // ── Path 2: Generic extraction via @call.name ────────────────
                     if (callNameNode) {
                         const calledName = callNameNode.text;
-                        // Dispatch: route language-specific calls (heritage, properties, imports)
+                        // Check heritage extractor for call-based heritage (e.g., Ruby include/extend/prepend)
+                        if (provider.heritageExtractor?.extractFromCall) {
+                            const heritageItems = provider.heritageExtractor.extractFromCall(calledName, callNode, { filePath: file.path, language });
+                            if (heritageItems !== null) {
+                                for (const item of heritageItems) {
+                                    result.heritage.push({
+                                        filePath: file.path,
+                                        className: item.className,
+                                        parentName: item.parentName,
+                                        kind: item.kind,
+                                    });
+                                }
+                                continue;
+                            }
+                        }
+                        // Dispatch: route language-specific calls (properties, imports)
+                        // Heritage routing is handled by heritageExtractor.extractFromCall above.
                         const routed = callRouter?.(calledName, captureMap['call']);
                         if (routed) {
                             if (routed.kind === 'skip')
@@ -1304,17 +1323,6 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                                 });
                                 continue;
                             }
-                            if (routed.kind === 'heritage') {
-                                for (const item of routed.items) {
-                                    result.heritage.push({
-                                        filePath: file.path,
-                                        className: item.enclosingClass,
-                                        parentName: item.mixinName,
-                                        kind: item.heritageKind,
-                                    });
-                                }
-                                continue;
-                            }
                             if (routed.kind === 'properties') {
                                 const propEnclosingInfo = cachedFindEnclosingClassInfo(captureMap['call'], file.path, provider.resolveEnclosingOwner);
                                 const propEnclosingClassId = propEnclosingInfo?.classId ?? null;
@@ -1453,40 +1461,29 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 }
                 continue;
             }
-            // Extract heritage (extends/implements)
+            // Extract heritage (extends/implements) via provider heritage extractor
             if (captureMap['heritage.class']) {
-                if (captureMap['heritage.extends']) {
-                    // Go struct embedding: the query matches ALL field_declarations with
-                    // type_identifier, but only anonymous fields (no name) are embedded.
-                    // Named fields like `Breed string` also match — skip them.
-                    const extendsNode = captureMap['heritage.extends'];
-                    const fieldDecl = extendsNode.parent;
-                    const isNamedField = fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName('name');
-                    if (!isNamedField) {
+                if (provider.heritageExtractor) {
+                    const heritageItems = provider.heritageExtractor.extract(captureMap, {
+                        filePath: file.path,
+                        language,
+                    });
+                    for (const item of heritageItems) {
                         result.heritage.push({
                             filePath: file.path,
-                            className: captureMap['heritage.class'].text,
-                            parentName: captureMap['heritage.extends'].text,
-                            kind: 'extends',
+                            className: item.className,
+                            parentName: item.parentName,
+                            kind: item.kind,
                         });
                     }
+                    // When the extractor consumes the match, skip symbol processing below.
+                    if (heritageItems.length > 0) {
+                        continue;
+                    }
                 }
-                if (captureMap['heritage.implements']) {
-                    result.heritage.push({
-                        filePath: file.path,
-                        className: captureMap['heritage.class'].text,
-                        parentName: captureMap['heritage.implements'].text,
-                        kind: 'implements',
-                    });
-                }
-                if (captureMap['heritage.trait']) {
-                    result.heritage.push({
-                        filePath: file.path,
-                        className: captureMap['heritage.class'].text,
-                        parentName: captureMap['heritage.trait'].text,
-                        kind: 'trait-impl',
-                    });
-                }
+                // Fallback: the extractor returned [] (or is absent), but the match still
+                // carries a heritage-specific capture. The match belongs to a heritage
+                // clause and must not fall through to generic symbol processing.
                 if (captureMap['heritage.extends'] ||
                     captureMap['heritage.implements'] ||
                     captureMap['heritage.trait']) {

package/dist/types/pipeline.d.ts

@@ -9,4 +9,10 @@ export interface PipelineResult {
     totalFileCount: number;
     communityResult?: CommunityDetectionResult;
     processResult?: ProcessDetectionResult;
+    /**
+     * True if the parse phase spawned a worker pool for this run. False means
+     * the sequential fallback handled every chunk. Primarily a test affordance
+     * so regression suites can prove which path executed.
+     */
+    usedWorkerPool: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.2-rc.21",
+  "version": "1.6.2-rc.22",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",