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

package/dist/core/ingestion/heritage-extractors/configs/ruby.d.ts

@@ -0,0 +1,18 @@
+import type { HeritageExtractionConfig } from '../../heritage-types.js';
+/**
+ * Ruby heritage extraction config.
+ *
+ * Ruby expresses inheritance in two ways, and only one of them has
+ * dedicated tree-sitter heritage captures:
+ *
+ * 1. Class inheritance (`class A < B`) produces standard
+ *    `@heritage.extends` captures and flows through the generic
+ *    capture-based `extract` hook (not defined here — the factory
+ *    handles it).
+ * 2. Mixin calls (`include`/`extend`/`prepend`) have no dedicated
+ *    heritage captures; they surface as ordinary call sites. The
+ *    `callBasedHeritage` hook below intercepts them before the call
+ *    router, absorbing the mixin routing logic that previously lived
+ *    in call-routing.ts (routeRubyCall).
+ */
+export declare const rubyHeritageConfig: HeritageExtractionConfig;

package/dist/core/ingestion/heritage-extractors/configs/ruby.js

@@ -0,0 +1,65 @@
+// gitnexus/src/core/ingestion/heritage-extractors/configs/ruby.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+/**
+ * Maximum parent depth for enclosing class/module walk.
+ * Prevents runaway walks on malformed/deeply-nested ASTs.
+ */
+const MAX_PARENT_DEPTH = 50;
+/**
+ * Walk up the AST from a call node to find the enclosing class or module name.
+ * Ruby include/extend/prepend calls must be inside a class or module body.
+ */
+function findEnclosingClassName(callNode) {
+    let current = callNode.parent;
+    let depth = 0;
+    while (current && ++depth <= MAX_PARENT_DEPTH) {
+        if (current.type === 'class' || current.type === 'module') {
+            const nameNode = current.childForFieldName?.('name');
+            if (nameNode)
+                return nameNode.text;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/** Ruby heritage call names that express mixin inclusion. */
+const RUBY_HERITAGE_CALL_NAMES = new Set(['include', 'extend', 'prepend']);
+/**
+ * Ruby heritage extraction config.
+ *
+ * Ruby expresses inheritance in two ways, and only one of them has
+ * dedicated tree-sitter heritage captures:
+ *
+ * 1. Class inheritance (`class A < B`) produces standard
+ *    `@heritage.extends` captures and flows through the generic
+ *    capture-based `extract` hook (not defined here — the factory
+ *    handles it).
+ * 2. Mixin calls (`include`/`extend`/`prepend`) have no dedicated
+ *    heritage captures; they surface as ordinary call sites. The
+ *    `callBasedHeritage` hook below intercepts them before the call
+ *    router, absorbing the mixin routing logic that previously lived
+ *    in call-routing.ts (routeRubyCall).
+ */
+export const rubyHeritageConfig = {
+    language: SupportedLanguages.Ruby,
+    callBasedHeritage: {
+        callNames: RUBY_HERITAGE_CALL_NAMES,
+        extract(calledName, callNode, _filePath) {
+            const enclosingClass = findEnclosingClassName(callNode);
+            if (!enclosingClass)
+                return [];
+            const results = [];
+            const argList = callNode.childForFieldName?.('arguments');
+            for (const arg of argList?.children ?? []) {
+                if (arg.type === 'constant' || arg.type === 'scope_resolution') {
+                    results.push({
+                        className: enclosingClass,
+                        parentName: arg.text,
+                        kind: calledName, // 'include' | 'extend' | 'prepend'
+                    });
+                }
+            }
+            return results;
+        },
+    },
+};

package/dist/core/ingestion/heritage-extractors/generic.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generic table-driven heritage extractor factory.
+ *
+ * Follows the same config+factory pattern as method-extractors/generic.ts,
+ * field-extractors/generic.ts, call-extractors/generic.ts, and
+ * variable-extractors/generic.ts.
+ *
+ * Languages with custom extraction hooks (Go: shouldSkipExtends, Ruby:
+ * callBasedHeritage) pass a full HeritageExtractionConfig.  Languages
+ * that use the default capture-based extraction can pass just the
+ * SupportedLanguages enum value — no per-language config file needed.
+ */
+import type { SupportedLanguages } from '../../../_shared/index.js';
+import type { HeritageExtractionConfig, HeritageExtractor } from '../heritage-types.js';
+/**
+ * Create a HeritageExtractor from a declarative config or a language enum.
+ *
+ * When a full HeritageExtractionConfig is provided, custom hooks
+ * (shouldSkipExtends, callBasedHeritage) drive the extraction.
+ * When only a SupportedLanguages value is provided, the factory produces
+ * a default extractor that handles the standard @heritage.* captures.
+ */
+export declare function createHeritageExtractor(config: HeritageExtractionConfig | SupportedLanguages): HeritageExtractor;

package/dist/core/ingestion/heritage-extractors/generic.js

@@ -0,0 +1,47 @@
+// gitnexus/src/core/ingestion/heritage-extractors/generic.ts
+/**
+ * Create a HeritageExtractor from a declarative config or a language enum.
+ *
+ * When a full HeritageExtractionConfig is provided, custom hooks
+ * (shouldSkipExtends, callBasedHeritage) drive the extraction.
+ * When only a SupportedLanguages value is provided, the factory produces
+ * a default extractor that handles the standard @heritage.* captures.
+ */
+export function createHeritageExtractor(config) {
+    const actualConfig = typeof config === 'string' ? { language: config } : config;
+    const callNameSet = actualConfig.callBasedHeritage?.callNames;
+    return {
+        language: actualConfig.language,
+        extract(captureMap, context) {
+            const classNode = captureMap['heritage.class'];
+            if (!classNode)
+                return [];
+            const className = classNode.text;
+            const results = [];
+            const extendsNode = captureMap['heritage.extends'];
+            if (extendsNode) {
+                if (!actualConfig.shouldSkipExtends?.(extendsNode)) {
+                    results.push({ className, parentName: extendsNode.text, kind: 'extends' });
+                }
+            }
+            const implementsNode = captureMap['heritage.implements'];
+            if (implementsNode) {
+                results.push({ className, parentName: implementsNode.text, kind: 'implements' });
+            }
+            const traitNode = captureMap['heritage.trait'];
+            if (traitNode) {
+                results.push({ className, parentName: traitNode.text, kind: 'trait-impl' });
+            }
+            return results;
+        },
+        ...(callNameSet
+            ? {
+                extractFromCall(calledName, callNode, context) {
+                    if (!callNameSet.has(calledName))
+                        return null;
+                    return actualConfig.callBasedHeritage.extract(calledName, callNode, context.filePath);
+                },
+            }
+            : {}),
+    };
+}

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

@@ -38,6 +38,15 @@ export declare const processHeritageFromExtracted: (graph: KnowledgeGraph, extra
  * {@link ExtractedHeritage} rows without mutating the graph. Used on the
  * sequential pipeline path so `buildHeritageMap(..., ctx)` can run before
  * `processCalls` (worker path defers calls until heritage from all chunks exists).
+ *
+ * This prepass extracts BOTH capture-based heritage (`@heritage.*` — extends /
+ * implements / trait-impl) AND call-based heritage (`@call.name` routed through
+ * `heritageExtractor.extractFromCall` — Ruby `include` / `extend` / `prepend`).
+ * Without the second pass, sequential-mode `sequentialHeritageMap` would not
+ * know about Ruby mixin ancestry before `processCalls` resolves calls against
+ * it, silently dropping mixed-in methods from the graph. This function stays
+ * read-only — `processCalls` still owns emission of heritage graph edges via
+ * its `rubyHeritage` return path.
  */
 export declare function extractExtractedHeritageFromFiles(files: {
     path: string;

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

@@ -54,6 +54,69 @@ const resolveHeritageId = (name, filePath, ctx, fallbackLabel, fallbackKey) => {
         confidence: TIER_CONFIDENCE['global'],
     };
 };
+/**
+ * Resolve a single HeritageInfo to a graph edge, using the same resolution
+ * logic as processHeritageFromExtracted.  This bridges the heritage extractor
+ * output format to the graph-resolution side.
+ */
+const resolveAndAddHeritageEdge = (graph, item, filePath, language, ctx) => {
+    if (item.kind === 'extends') {
+        const { type: relType, idPrefix } = resolveExtendsType(item.parentName, filePath, ctx, getHeritageStrategyForLanguage(language));
+        const child = resolveHeritageId(item.className, filePath, ctx, 'Class', `${filePath}:${item.className}`);
+        const parent = resolveHeritageId(item.parentName, filePath, ctx, idPrefix);
+        if (child.id && parent.id && child.id !== parent.id) {
+            graph.addRelationship({
+                id: generateId(relType, `${child.id}->${parent.id}`),
+                sourceId: child.id,
+                targetId: parent.id,
+                type: relType,
+                confidence: Math.sqrt(child.confidence * parent.confidence),
+                reason: '',
+            });
+        }
+    }
+    else if (item.kind === 'implements') {
+        const cls = resolveHeritageId(item.className, filePath, ctx, 'Class', `${filePath}:${item.className}`);
+        const iface = resolveHeritageId(item.parentName, filePath, ctx, 'Interface');
+        if (cls.id && iface.id) {
+            graph.addRelationship({
+                id: generateId('IMPLEMENTS', `${cls.id}->${iface.id}`),
+                sourceId: cls.id,
+                targetId: iface.id,
+                type: 'IMPLEMENTS',
+                confidence: Math.sqrt(cls.confidence * iface.confidence),
+                reason: '',
+            });
+        }
+    }
+    else if (item.kind === 'trait-impl' ||
+        item.kind === 'include' ||
+        item.kind === 'extend' ||
+        item.kind === 'prepend') {
+        // Fallback label for an unresolved child name. Rust `trait-impl` children
+        // are structs; Ruby mixin children are classes or modules (Trait). For
+        // Ruby mixin kinds the common case resolves through the type registry
+        // post-plan-001, so the fallback only fires for true-unresolved references
+        // (e.g. mixin inside a singleton_class). `Class` is strictly better than
+        // `Struct` there because it matches the label the structure phase would
+        // emit for a Ruby `class` — the dominant shape. Ruby modules that fail
+        // to resolve still lose their `Trait` label in the synthesized id, but
+        // they fail to resolve rarely and the tradeoff is documented.
+        const childFallbackLabel = item.kind === 'trait-impl' ? 'Struct' : 'Class';
+        const strct = resolveHeritageId(item.className, filePath, ctx, childFallbackLabel, `${filePath}:${item.className}`);
+        const trait = resolveHeritageId(item.parentName, filePath, ctx, 'Trait');
+        if (strct.id && trait.id) {
+            graph.addRelationship({
+                id: generateId('IMPLEMENTS', `${strct.id}->${trait.id}:${item.kind}`),
+                sourceId: strct.id,
+                targetId: trait.id,
+                type: 'IMPLEMENTS',
+                confidence: Math.sqrt(strct.confidence * trait.confidence),
+                reason: item.kind,
+            });
+        }
+    }
+};
 export const processHeritage = async (graph, files, astCache, ctx, onProgress) => {
     const parser = await loadParser();
     const logSkipped = isVerboseIngestionEnabled();
@@ -98,78 +161,31 @@ export const processHeritage = async (graph, files, astCache, ctx, onProgress) =
         let query;
         let matches;
         try {
-            const language = parser.getLanguage();
-            query = new Parser.Query(language, queryStr);
+            const treeSitterLang = parser.getLanguage();
+            query = new Parser.Query(treeSitterLang, queryStr);
             matches = query.matches(tree.rootNode);
         }
         catch (queryError) {
             console.warn(`Heritage query error for ${file.path}:`, queryError);
             continue;
         }
-        // 4. Process heritage matches
+        // 4. Process heritage matches via provider heritage extractor
+        const heritageExtractor = provider.heritageExtractor;
         matches.forEach((match) => {
             const captureMap = {};
             match.captures.forEach((c) => {
                 captureMap[c.name] = c.node;
             });
-            // EXTENDS or IMPLEMENTS: resolve via symbol table for languages where
-            // the tree-sitter query can't distinguish classes from interfaces (C#, Java)
-            if (captureMap['heritage.class'] && captureMap['heritage.extends']) {
-                // Go struct embedding: skip named fields (only anonymous fields are embedded)
-                const extendsNode = captureMap['heritage.extends'];
-                const fieldDecl = extendsNode.parent;
-                if (fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName('name')) {
-                    return; // Named field, not struct embedding
-                }
-                const className = captureMap['heritage.class'].text;
-                const parentClassName = captureMap['heritage.extends'].text;
-                const { type: relType, idPrefix } = resolveExtendsType(parentClassName, file.path, ctx, getHeritageStrategyForLanguage(language));
-                const child = resolveHeritageId(className, file.path, ctx, 'Class', `${file.path}:${className}`);
-                const parent = resolveHeritageId(parentClassName, file.path, ctx, idPrefix);
-                if (child.id && parent.id && child.id !== parent.id) {
-                    graph.addRelationship({
-                        id: generateId(relType, `${child.id}->${parent.id}`),
-                        sourceId: child.id,
-                        targetId: parent.id,
-                        type: relType,
-                        confidence: Math.sqrt(child.confidence * parent.confidence),
-                        reason: '',
-                    });
-                }
-            }
-            // IMPLEMENTS: Class implements Interface (TypeScript only)
-            if (captureMap['heritage.class'] && captureMap['heritage.implements']) {
-                const className = captureMap['heritage.class'].text;
-                const interfaceName = captureMap['heritage.implements'].text;
-                const cls = resolveHeritageId(className, file.path, ctx, 'Class', `${file.path}:${className}`);
-                const iface = resolveHeritageId(interfaceName, file.path, ctx, 'Interface');
-                if (cls.id && iface.id) {
-                    graph.addRelationship({
-                        id: generateId('IMPLEMENTS', `${cls.id}->${iface.id}`),
-                        sourceId: cls.id,
-                        targetId: iface.id,
-                        type: 'IMPLEMENTS',
-                        confidence: Math.sqrt(cls.confidence * iface.confidence),
-                        reason: '',
-                    });
-                }
-            }
-            // IMPLEMENTS (Rust): impl Trait for Struct
-            if (captureMap['heritage.trait'] && captureMap['heritage.class']) {
-                const structName = captureMap['heritage.class'].text;
-                const traitName = captureMap['heritage.trait'].text;
-                const strct = resolveHeritageId(structName, file.path, ctx, 'Struct', `${file.path}:${structName}`);
-                const trait = resolveHeritageId(traitName, file.path, ctx, 'Trait');
-                if (strct.id && trait.id) {
-                    graph.addRelationship({
-                        id: generateId('IMPLEMENTS', `${strct.id}->${trait.id}`),
-                        sourceId: strct.id,
-                        targetId: trait.id,
-                        type: 'IMPLEMENTS',
-                        confidence: Math.sqrt(strct.confidence * trait.confidence),
-                        reason: 'trait-impl',
-                    });
-                }
+            if (!captureMap['heritage.class'])
+                return;
+            if (!heritageExtractor)
+                return;
+            const heritageItems = heritageExtractor.extract(captureMap, {
+                filePath: file.path,
+                language,
+            });
+            for (const item of heritageItems) {
+                resolveAndAddHeritageEdge(graph, item, file.path, language, ctx);
             }
         });
         // Tree is now owned by the LRU cache — no manual delete needed
@@ -228,7 +244,11 @@ export const processHeritageFromExtracted = async (graph, extractedHeritage, ctx
             h.kind === 'include' ||
             h.kind === 'extend' ||
             h.kind === 'prepend') {
-            const strct = resolveHeritageId(h.className, h.filePath, ctx, 'Struct', `${h.filePath}:${h.className}`);
+            // See the per-item call above (processHeritageFromExtractedItem) for
+            // rationale: `Class` is the correct fallback for Ruby mixin kinds,
+            // `Struct` stays the Rust `trait-impl` default.
+            const childFallbackLabel = h.kind === 'trait-impl' ? 'Struct' : 'Class';
+            const strct = resolveHeritageId(h.className, h.filePath, ctx, childFallbackLabel, `${h.filePath}:${h.className}`);
             const trait = resolveHeritageId(h.parentName, h.filePath, ctx, 'Trait');
             if (strct.id && trait.id) {
                 graph.addRelationship({
@@ -249,6 +269,15 @@ export const processHeritageFromExtracted = async (graph, extractedHeritage, ctx
  * {@link ExtractedHeritage} rows without mutating the graph. Used on the
  * sequential pipeline path so `buildHeritageMap(..., ctx)` can run before
  * `processCalls` (worker path defers calls until heritage from all chunks exists).
+ *
+ * This prepass extracts BOTH capture-based heritage (`@heritage.*` — extends /
+ * implements / trait-impl) AND call-based heritage (`@call.name` routed through
+ * `heritageExtractor.extractFromCall` — Ruby `include` / `extend` / `prepend`).
+ * Without the second pass, sequential-mode `sequentialHeritageMap` would not
+ * know about Ruby mixin ancestry before `processCalls` resolves calls against
+ * it, silently dropping mixed-in methods from the graph. This function stays
+ * read-only — `processCalls` still owns emission of heritage graph edges via
+ * its `rubyHeritage` return path.
  */
 export async function extractExtractedHeritageFromFiles(files, astCache) {
     const parser = await loadParser();
@@ -283,40 +312,46 @@ export async function extractExtractedHeritageFromFiles(files, astCache) {
         catch {
             continue;
         }
+        const callBasedEnabled = !!provider.heritageExtractor?.extractFromCall;
         for (const match of matches) {
             const captureMap = {};
             match.captures.forEach((c) => {
                 captureMap[c.name] = c.node;
             });
             if (captureMap['heritage.class']) {
-                if (captureMap['heritage.extends']) {
-                    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) {
                         out.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,
                         });
                     }
                 }
-                if (captureMap['heritage.implements']) {
-                    out.push({
-                        filePath: file.path,
-                        className: captureMap['heritage.class'].text,
-                        parentName: captureMap['heritage.implements'].text,
-                        kind: 'implements',
-                    });
-                }
-                if (captureMap['heritage.trait']) {
-                    out.push({
-                        filePath: file.path,
-                        className: captureMap['heritage.class'].text,
-                        parentName: captureMap['heritage.trait'].text,
-                        kind: 'trait-impl',
-                    });
+                continue;
+            }
+            // Call-based heritage (e.g. Ruby include/extend/prepend). Matches the
+            // routing the worker path performs inline in parse-worker.ts — see the
+            // `provider.heritageExtractor?.extractFromCall` branch there. We only
+            // need call-based records here; other @call captures are consumed by
+            // processCalls later in the sequential loop.
+            if (callBasedEnabled && captureMap['call'] && captureMap['call.name']) {
+                const calledName = captureMap['call.name'].text;
+                const heritageItems = provider.heritageExtractor.extractFromCall(calledName, captureMap['call'], { filePath: file.path, language });
+                if (heritageItems) {
+                    for (const item of heritageItems) {
+                        out.push({
+                            filePath: file.path,
+                            className: item.className,
+                            parentName: item.parentName,
+                            kind: item.kind,
+                        });
+                    }
                 }
             }
         }

package/dist/core/ingestion/heritage-types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Types for the language-agnostic heritage extraction pipeline.
+ *
+ * Follows the same pattern as call-types.ts, variable-types.ts, and
+ * method-types.ts: defines the domain interfaces consumed by
+ * createHeritageExtractor() and the per-language configs.
+ *
+ * Heritage extraction handles extends/implements/trait-impl captures from
+ * tree-sitter queries, plus call-based heritage for languages like Ruby
+ * (include/extend/prepend expressed as method calls).
+ */
+import type { SupportedLanguages } from '../../_shared/index.js';
+import type { SyntaxNode } from './utils/ast-helpers.js';
+import type { CaptureMap } from './language-provider.js';
+/**
+ * Per-match heritage extraction result.  The parse worker adds filePath to
+ * produce the final {@link ExtractedHeritage} that enters the resolution
+ * pipeline (heritage-processor.ts / heritage-map.ts).
+ */
+export interface HeritageInfo {
+    className: string;
+    parentName: string;
+    /** 'extends' | 'implements' | 'trait-impl' | 'include' | 'extend' | 'prepend' */
+    kind: string;
+}
+export interface HeritageExtractorContext {
+    filePath: string;
+    language: SupportedLanguages;
+}
+export interface HeritageExtractor {
+    readonly language: SupportedLanguages;
+    /**
+     * Extract heritage records from tree-sitter @heritage.* captures.
+     *
+     * @param captureMap  The capture map from a single tree-sitter match
+     * @param context     File path and language context
+     * @returns Array of heritage records (may be empty if captures don't match)
+     */
+    extract(captureMap: CaptureMap, context: HeritageExtractorContext): HeritageInfo[];
+    /**
+     * Extract heritage from a call node (for languages where heritage is
+     * expressed as method calls, e.g., Ruby include/extend/prepend).
+     *
+     * @param calledName  The method name (e.g. 'include', 'extend', 'prepend')
+     * @param callNode    The tree-sitter call AST node
+     * @param context     File path and language context
+     * @returns Heritage records if the call is heritage-related, or null to
+     *          fall through to the call router / normal call handling.
+     */
+    extractFromCall?(calledName: string, callNode: SyntaxNode, context: HeritageExtractorContext): HeritageInfo[] | null;
+}
+export interface HeritageExtractionConfig {
+    language: SupportedLanguages;
+    /**
+     * Called for heritage.extends captures.  Return true to skip this extends
+     * capture.  Used by Go to skip named struct fields that match the
+     * field_declaration pattern but are not anonymous embeddings.
+     *
+     * Default: never skip (all extends captures are valid).
+     */
+    shouldSkipExtends?: (extendsNode: SyntaxNode) => boolean;
+    /**
+     * Call-based heritage extraction for languages where heritage is expressed
+     * as method calls (e.g., Ruby include/extend/prepend).
+     *
+     * callNames: set of method names that trigger heritage extraction.
+     * extract:   extract heritage items from the call node + method name.
+     */
+    callBasedHeritage?: {
+        readonly callNames: ReadonlySet<string>;
+        extract(calledName: string, callNode: SyntaxNode, filePath: string): HeritageInfo[];
+    };
+}

package/dist/core/ingestion/heritage-types.js

@@ -0,0 +1,2 @@
+// gitnexus/src/core/ingestion/heritage-types.ts
+export {};

package/dist/core/ingestion/language-provider.d.ts

@@ -11,10 +11,11 @@
 import type { SupportedLanguages, MroStrategy } from '../../_shared/index.js';
 import type { LanguageTypeConfig } from './type-extractors/types.js';
 import type { CallRouter } from './call-routing.js';
-import type { CallExtractor } from './call-types.js';
+import type { CallExtractor, DispatchDecision, ImplicitReceiverOverride, ReceiverEnriched } from './call-types.js';
 import type { ClassExtractor } from './class-types.js';
 import type { ExportChecker } from './export-detection.js';
 import type { FieldExtractor } from './field-extractor.js';
+import type { HeritageExtractor } from './heritage-types.js';
 import type { MethodExtractor } from './method-types.js';
 import type { VariableExtractor } from './variable-types.js';
 import type { ImportResolverFn } from './import-resolvers/types.js';
@@ -143,6 +144,13 @@ interface LanguageProviderConfig {
      *  Uses the same provider-driven strategy pattern as method/field extraction so
      *  namespace/package/module rules stay language-specific. */
     readonly classExtractor?: ClassExtractor;
+    /** Heritage extractor for extracting extends/implements/trait-impl relationships
+     *  from tree-sitter @heritage.* captures and call-based heritage (e.g., Ruby
+     *  include/extend/prepend). Produced by createHeritageExtractor() — pass a
+     *  SupportedLanguages value for default behaviour or a full
+     *  HeritageExtractionConfig for languages with custom hooks (Go, Ruby).
+     *  All tree-sitter providers MUST supply this. */
+    readonly heritageExtractor?: HeritageExtractor;
     /** Extract a semantic description for a definition node (e.g., PHP Eloquent
      *  property arrays, relation method descriptions).
      *  Default: undefined (no description extraction). */
@@ -151,6 +159,66 @@ interface LanguageProviderConfig {
      *  When true, the worker extracts routes via the language's route extraction logic.
      *  Default: undefined (no route files). */
     readonly isRouteFile?: (filePath: string) => boolean;
+    /**
+     * DAG stage 3 hook: synthesize an implicit receiver when the call site omits one.
+     *
+     * Runs after shared inference (TypeEnv → constructor-map → class-as-receiver →
+     * mixed-chain). Return an `ImplicitReceiverOverride` to overlay all fields onto
+     * `ReceiverEnriched`; return null to keep current state and proceed to stage 4.
+     *
+     * Constraints: MUST return null when an explicit receiver is already set, at
+     * top-level scope, or for built-in methods. Do not mutate input params.
+     * `hint` is opaque to shared stages; consumed by this language's `selectDispatch`.
+     *
+     * Ruby example: bare `serialize` in `Account#call_serialize` →
+     * `{ callForm: 'member', receiverName: 'self', receiverTypeName: 'Account',
+     *    receiverSource: 'implicit-self', hint: 'instance' }`
+     *
+     * @see call-types.ts § ImplicitReceiverOverride
+     * @see selectDispatch (stage 4, reads the hint)
+     *
+     * Default: undefined (no implicit-receiver inference).
+     */
+    readonly inferImplicitReceiver?: (params: {
+        readonly calledName: string;
+        readonly callForm: 'free' | 'member' | 'constructor' | undefined;
+        readonly receiverName: string | undefined;
+        readonly receiverTypeName: string | undefined;
+        readonly callNode: SyntaxNode;
+        readonly filePath: string;
+    }) => ImplicitReceiverOverride | null;
+    /**
+     * DAG stage 4 hook: decide dispatch strategy (primary path, fallback, MRO view).
+     *
+     * Runs after stage 3. Return a `DispatchDecision` to override shared defaults;
+     * return null to use `defaultDispatchDecision` (constructor→`'constructor'`,
+     * member→`'owner-scoped'`, free→`'free'`). Most languages return null.
+     *
+     * The hook is responsible for its own gating. `ancestryView` only affects
+     * `'ruby-mixin'` strategy. Singleton-ancestry miss NEVER falls through to
+     * file-scoped fallback in stage 5 (enforced in resolveCallTarget).
+     *
+     * Ruby examples:
+     * - `receiverSource='implicit-self', hint='instance'` →
+     *   `{primary: 'owner-scoped', fallback: 'free-arity-narrowed', ancestryView: 'instance'}`
+     * - `receiverSource='class-as-receiver'` →
+     *   `{primary: 'owner-scoped', ancestryView: 'singleton'}` (miss null-routes)
+     * - `receiverSource='implicit-self', hint='singleton'` →
+     *   `{primary: 'owner-scoped', fallback: 'free-arity-narrowed', ancestryView: 'singleton'}`
+     *
+     * @see call-types.ts § DispatchDecision
+     * @see call-processor.ts § defaultDispatchDecision, resolveCallTarget
+     *
+     * Default: undefined (use `defaultDispatchDecision`).
+     */
+    readonly selectDispatch?: (params: {
+        readonly calledName: string;
+        readonly callForm: 'free' | 'member' | 'constructor' | undefined;
+        readonly receiverName: string | undefined;
+        readonly receiverTypeName: string | undefined;
+        readonly receiverSource: ReceiverEnriched['receiverSource'];
+        readonly hint: string | undefined;
+    }) => DispatchDecision | null;
     /** Built-in/stdlib names that should be filtered from the call graph for this language.
      *  Default: undefined (no language-specific filtering). */
     readonly builtInNames?: ReadonlySet<string>;

package/dist/core/ingestion/languages/c-cpp.js

@@ -35,6 +35,7 @@ import { createVariableExtractor } from '../variable-extractors/generic.js';
 import { cVariableConfig, cppVariableConfig } from '../variable-extractors/configs/c-cpp.js';
 import { createCallExtractor } from '../call-extractors/generic.js';
 import { cCallConfig, cppCallConfig } from '../call-extractors/configs/c-cpp.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 const C_BUILT_INS = new Set([
     'printf',
     'fprintf',
@@ -301,6 +302,7 @@ export const cProvider = defineLanguage({
     }),
     variableExtractor: createVariableExtractor(cVariableConfig),
     classExtractor: cClassExtractor,
+    heritageExtractor: createHeritageExtractor(SupportedLanguages.C),
     labelOverride: cppLabelOverride,
     builtInNames: C_BUILT_INS,
 });
@@ -321,6 +323,7 @@ export const cppProvider = defineLanguage({
     }),
     variableExtractor: createVariableExtractor(cppVariableConfig),
     classExtractor: cppClassExtractor,
+    heritageExtractor: createHeritageExtractor(SupportedLanguages.CPlusPlus),
     labelOverride: cppLabelOverride,
     builtInNames: C_BUILT_INS,
 });

package/dist/core/ingestion/languages/csharp.js

@@ -23,6 +23,7 @@ import { createMethodExtractor } from '../method-extractors/generic.js';
 import { csharpMethodConfig } from '../method-extractors/configs/csharp.js';
 import { createVariableExtractor } from '../variable-extractors/generic.js';
 import { csharpVariableConfig } from '../variable-extractors/configs/csharp.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 const BUILT_INS = new Set([
     'Console',
     'WriteLine',
@@ -132,5 +133,6 @@ export const csharpProvider = defineLanguage({
     methodExtractor: createMethodExtractor(csharpMethodConfig),
     variableExtractor: createVariableExtractor(csharpVariableConfig),
     classExtractor: createClassExtractor(csharpClassConfig),
+    heritageExtractor: createHeritageExtractor(SupportedLanguages.CSharp),
     builtInNames: BUILT_INS,
 });