gitnexus 1.5.3 → 1.6.0

package/dist/core/ingestion/model/resolve.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Deterministic Resolution Functions
+ *
+ * Pure functions that resolve methods across the inheritance hierarchy
+ * using only the SemanticModel registries and HeritageMap — NO dependency
+ * on resolution-context.ts (circular dependency risk).
+ */
+import type { SymbolDefinition } from './symbol-table.js';
+import type { SemanticModel } from './semantic-model.js';
+import type { HeritageMap } from './heritage-map.js';
+import type { MroStrategy } from '../../../_shared/index.js';
+/**
+ * Gather all ancestor IDs in BFS / topological order.
+ * Returns the linearized list of ancestor IDs (excluding the class itself).
+ */
+declare function gatherAncestors(classId: string, parentMap: Map<string, string[]>): string[];
+/**
+ * Compute C3 linearization for a class given a parentMap.
+ * Returns an array of ancestor IDs in C3 order (excluding the class itself),
+ * or null if linearization fails (inconsistent or cyclic hierarchy).
+ *
+ * Used internally by `lookupMethodByOwnerWithMRO` for the Python MRO
+ * strategy and re-exported for mro-processor.ts (graph-level MRO emission).
+ */
+export declare function c3Linearize(classId: string, parentMap: Map<string, string[]>, cache: Map<string, string[] | null>, inProgress?: Set<string>): string[] | null;
+export { gatherAncestors };
+/**
+ * Look up a method on an owner class, walking the parent chain via HeritageMap
+ * when the method isn't found on the direct owner.
+ *
+ * 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
+ *
+ * Uses the `c3Linearize` defined in this file (also consumed by
+ * mro-processor.ts for graph-level MRO emission) for the `c3` strategy.
+ *
+ * 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 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.
+ */
+export declare const lookupMethodByOwnerWithMRO: (ownerNodeId: string, methodName: string, heritageMap: HeritageMap, model: SemanticModel, strategy: MroStrategy, argCount?: number) => SymbolDefinition | undefined;

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

@@ -0,0 +1,242 @@
+/**
+ * Deterministic Resolution Functions
+ *
+ * Pure functions that resolve methods across the inheritance hierarchy
+ * using only the SemanticModel registries and HeritageMap — NO dependency
+ * on resolution-context.ts (circular dependency risk).
+ */
+// ---------------------------------------------------------------------------
+// MRO primitives.
+//
+// `c3Linearize` and its BFS helper `gatherAncestors` live here so the model
+// layer stays a pure leaf — mro-processor.ts (graph-level MRO emission)
+// imports `c3Linearize` from this file.
+// ---------------------------------------------------------------------------
+/**
+ * Gather all ancestor IDs in BFS / topological order.
+ * Returns the linearized list of ancestor IDs (excluding the class itself).
+ */
+function gatherAncestors(classId, parentMap) {
+    const visited = new Set();
+    const order = [];
+    const queue = [...(parentMap.get(classId) ?? [])];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        order.push(id);
+        const grandparents = parentMap.get(id);
+        if (grandparents) {
+            for (const gp of grandparents) {
+                if (!visited.has(gp))
+                    queue.push(gp);
+            }
+        }
+    }
+    return order;
+}
+/**
+ * Compute C3 linearization for a class given a parentMap.
+ * Returns an array of ancestor IDs in C3 order (excluding the class itself),
+ * or null if linearization fails (inconsistent or cyclic hierarchy).
+ *
+ * Used internally by `lookupMethodByOwnerWithMRO` for the Python MRO
+ * strategy and re-exported for mro-processor.ts (graph-level MRO emission).
+ */
+export function c3Linearize(classId, parentMap, cache, inProgress) {
+    if (cache.has(classId))
+        return cache.get(classId);
+    // Cycle detection: if we're already computing this class, the hierarchy is cyclic
+    const visiting = inProgress ?? new Set();
+    if (visiting.has(classId)) {
+        cache.set(classId, null);
+        return null;
+    }
+    visiting.add(classId);
+    const directParents = parentMap.get(classId);
+    if (!directParents || directParents.length === 0) {
+        visiting.delete(classId);
+        cache.set(classId, []);
+        return [];
+    }
+    // Compute linearization for each parent first
+    const parentLinearizations = [];
+    for (const pid of directParents) {
+        const pLin = c3Linearize(pid, parentMap, cache, visiting);
+        if (pLin === null) {
+            visiting.delete(classId);
+            cache.set(classId, null);
+            return null;
+        }
+        parentLinearizations.push([pid, ...pLin]);
+    }
+    // Add the direct parents list as the final sequence
+    const sequences = [...parentLinearizations, [...directParents]];
+    const result = [];
+    while (sequences.some((s) => s.length > 0)) {
+        // Find a good head: one that doesn't appear in the tail of any other sequence
+        let head = null;
+        for (const seq of sequences) {
+            if (seq.length === 0)
+                continue;
+            const candidate = seq[0];
+            const inTail = sequences.some((other) => other.length > 1 && other.indexOf(candidate, 1) !== -1);
+            if (!inTail) {
+                head = candidate;
+                break;
+            }
+        }
+        if (head === null) {
+            // Inconsistent hierarchy
+            visiting.delete(classId);
+            cache.set(classId, null);
+            return null;
+        }
+        result.push(head);
+        // Remove the chosen head from all sequences
+        for (const seq of sequences) {
+            if (seq.length > 0 && seq[0] === head) {
+                seq.shift();
+            }
+        }
+    }
+    visiting.delete(classId);
+    cache.set(classId, result);
+    return result;
+}
+// `gatherAncestors` is exported so mro-processor.ts can reuse the same
+// BFS traversal for graph-level MRO emission.
+export { gatherAncestors };
+// ---------------------------------------------------------------------------
+// C3 linearization cache (per HeritageMap, auto-drained via WeakMap)
+// ---------------------------------------------------------------------------
+/**
+ * Per-HeritageMap cache of C3 linearization results keyed by owner nodeId.
+ *
+ * HeritageMap instances are immutable after construction, so C3 output is
+ * stable for the lifetime of a HeritageMap. WeakMap lets the cache auto-drain
+ * when the HeritageMap is garbage collected (end of ingestion run), so we
+ * never need to manually invalidate it.
+ *
+ * `null` is a sentinel for "C3 failed for this owner" (cyclic or inconsistent
+ * hierarchy) so we don't re-run the expensive linearization repeatedly.
+ */
+const c3LinearizationCache = new WeakMap();
+const getCachedC3Linearization = (ownerNodeId, heritageMap) => {
+    let perHmCache = c3LinearizationCache.get(heritageMap);
+    if (!perHmCache) {
+        perHmCache = new Map();
+        c3LinearizationCache.set(heritageMap, perHmCache);
+    }
+    const cached = perHmCache.get(ownerNodeId);
+    if (cached !== undefined)
+        return cached;
+    const parentMap = buildParentMapFromHeritage(ownerNodeId, heritageMap);
+    const result = c3Linearize(ownerNodeId, parentMap, new Map()) ?? null;
+    perHmCache.set(ownerNodeId, result);
+    return result;
+};
+// ---------------------------------------------------------------------------
+// Heritage → parentMap conversion
+// ---------------------------------------------------------------------------
+/**
+ * Build a parentMap from HeritageMap for use with c3Linearize.
+ * Traverses the parent chain starting from startNodeId, collecting all
+ * parent→children relationships into a Map<string, string[]>.
+ *
+ * Uses a head-pointer BFS (queue[head++]) instead of Array.shift() to avoid
+ * O(n) per-dequeue re-indexing. For wide/shallow hierarchies common in
+ * large Java/C# codebases this keeps the walk linear in ancestor count.
+ */
+const buildParentMapFromHeritage = (startNodeId, heritageMap) => {
+    const parentMap = new Map();
+    const visited = new Set();
+    const queue = [startNodeId];
+    let head = 0;
+    while (head < queue.length) {
+        const nodeId = queue[head++];
+        if (visited.has(nodeId))
+            continue;
+        visited.add(nodeId);
+        const parents = heritageMap.getParents(nodeId);
+        if (parents.length > 0) {
+            parentMap.set(nodeId, parents);
+            for (const p of parents) {
+                if (!visited.has(p))
+                    queue.push(p);
+            }
+        }
+    }
+    return parentMap;
+};
+// ---------------------------------------------------------------------------
+// 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.
+ *
+ * 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
+ *
+ * Uses the `c3Linearize` defined in this file (also consumed by
+ * mro-processor.ts for graph-level MRO emission) for the `c3` strategy.
+ *
+ * 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 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.
+ */
+export const lookupMethodByOwnerWithMRO = (ownerNodeId, methodName, heritageMap, model, strategy, argCount) => {
+    // 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.
+    const direct = model.methods.lookupMethodByOwner(ownerNodeId, methodName, argCount);
+    if (direct)
+        return direct;
+    // Rust: requires qualified syntax (<Type as Trait>::method), no auto-resolution
+    if (strategy === 'qualified-syntax')
+        return undefined;
+    // Determine ancestor walk order based on MRO strategy.
+    // readonly to accept the cached (frozen) c3 linearization without copying.
+    let ancestors;
+    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).
+        // c3Linearize returns ancestors only (excludes the owner itself),
+        // matching heritageMap.getAncestors() semantics.
+        const c3Result = getCachedC3Linearization(ownerNodeId, heritageMap);
+        // Fall back to BFS order if C3 fails (cyclic or inconsistent hierarchy).
+        // Note: BFS order may not preserve Python MRO semantics in these edge
+        // cases, but cyclic/inconsistent hierarchies are invalid in Python anyway.
+        ancestors = c3Result ?? heritageMap.getAncestors(ownerNodeId);
+    }
+    else {
+        // first-wins, leftmost-base, implements-split: BFS order via HeritageMap
+        ancestors = heritageMap.getAncestors(ownerNodeId);
+    }
+    // Walk ancestors in MRO order — first match wins.
+    // argCount narrows overloaded ancestors the same way as the direct lookup.
+    for (const ancestorId of ancestors) {
+        const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+        if (method)
+            return method;
+    }
+    return undefined;
+};

package/dist/core/ingestion/model/semantic-model.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Semantic Model
+ *
+ * Top-level orchestrator for all resolution-time data. Owns:
+ *
+ *   - Three owner-scoped registries (types, methods, fields)
+ *   - A nested SymbolTable (file + callable name indexes) wrapped so
+ *     that `add()` fans out into the registries via the dispatch table
+ *
+ * ## DAG direction
+ *
+ *     gitnexus-shared (NodeLabel)             — leaf
+ *          ↑
+ *     symbol-table.ts                         — pure file/callable index
+ *          ↑
+ *     model/type-registry / method-registry / field-registry
+ *          ↑
+ *     model/registration-table.ts             — dispatch table factory
+ *          ↑
+ *     model/semantic-model.ts                 — THIS FILE (orchestrator)
+ *          ↑
+ *     resolve.ts, call-processor.ts, resolution-context.ts, ...
+ *
+ * `symbol-table.ts` is a leaf — it never imports from `./model/`. This
+ * file (semantic-model.ts) is the ONLY place where SymbolTable and the
+ * owner-scoped registries are composed. Upstream consumers pass around
+ * the `SemanticModel` interface and reach into `.symbols` for file-scoped
+ * operations or `.types` / `.methods` / `.fields` for owner-scoped ones.
+ *
+ * ## Fan-out via wrapped add()
+ *
+ * `createSemanticModel()` creates a pure SymbolTable, creates the three
+ * registries, builds a dispatch table via `createRegistrationTable`, and
+ * exposes a SymbolTable-shaped façade whose `add()`:
+ *
+ *   1. Calls `rawSymbols.add()` — writes the fileIndex + callable index
+ *      and returns the fully-built `SymbolDefinition`.
+ *   2. Runs pre-dispatch normalization (`Function`-with-`ownerId` routes
+ *      as `Method`).
+ *   3. Looks up the dispatch table and invokes the hook, which writes to
+ *      the appropriate owner-scoped registry.
+ *
+ * The wrapper is the only place where the two layers are combined. A
+ * direct `createSymbolTable()` caller (e.g. an isolated unit test) gets
+ * the pure, registry-free behavior — no surprises, no hidden side
+ * effects.
+ */
+import type { TypeRegistry, MutableTypeRegistry } from './type-registry.js';
+import type { MethodRegistry, MutableMethodRegistry } from './method-registry.js';
+import type { FieldRegistry, MutableFieldRegistry } from './field-registry.js';
+import type { SymbolTableReader, SymbolTableWriter } from './symbol-table.js';
+/**
+ * Aggregated read-only view of the semantic registries plus the nested
+ * file/callable SymbolTable.
+ *
+ * `symbols` is typed as {@link SymbolTableReader} — consumers can query
+ * symbols but cannot register new ones or trigger a reset. Callers that
+ * need to register symbols or reset state must hold a
+ * {@link MutableSemanticModel} reference instead, which widens
+ * `symbols` back to {@link SymbolTableWriter} and adds `clear()` on the
+ * model itself.
+ *
+ * This segregation is the runtime half of the principle of least
+ * authority: a resolver that receives `SemanticModel` physically cannot
+ * mutate the index, so it cannot desync the leaf from the owner-scoped
+ * registries even accidentally.
+ */
+export interface SemanticModel {
+    readonly types: TypeRegistry;
+    readonly methods: MethodRegistry;
+    readonly fields: FieldRegistry;
+    readonly symbols: SymbolTableReader;
+}
+/** Mutable variant — exposes the MutableX registries, a Writer-typed
+ *  `symbols` facade, and a full-cascade reset. This is the interface
+ *  held by the lifecycle owner (pipeline, resolution-context); resolvers
+ *  that only query should hold the narrower {@link SemanticModel}. */
+export interface MutableSemanticModel extends SemanticModel {
+    readonly types: MutableTypeRegistry;
+    readonly methods: MutableMethodRegistry;
+    readonly fields: MutableFieldRegistry;
+    readonly symbols: SymbolTableWriter;
+    /** Clear all registries AND the nested SymbolTable. */
+    clear(): void;
+}
+export declare const createSemanticModel: () => MutableSemanticModel;

package/dist/core/ingestion/model/semantic-model.js

@@ -0,0 +1,120 @@
+/**
+ * Semantic Model
+ *
+ * Top-level orchestrator for all resolution-time data. Owns:
+ *
+ *   - Three owner-scoped registries (types, methods, fields)
+ *   - A nested SymbolTable (file + callable name indexes) wrapped so
+ *     that `add()` fans out into the registries via the dispatch table
+ *
+ * ## DAG direction
+ *
+ *     gitnexus-shared (NodeLabel)             — leaf
+ *          ↑
+ *     symbol-table.ts                         — pure file/callable index
+ *          ↑
+ *     model/type-registry / method-registry / field-registry
+ *          ↑
+ *     model/registration-table.ts             — dispatch table factory
+ *          ↑
+ *     model/semantic-model.ts                 — THIS FILE (orchestrator)
+ *          ↑
+ *     resolve.ts, call-processor.ts, resolution-context.ts, ...
+ *
+ * `symbol-table.ts` is a leaf — it never imports from `./model/`. This
+ * file (semantic-model.ts) is the ONLY place where SymbolTable and the
+ * owner-scoped registries are composed. Upstream consumers pass around
+ * the `SemanticModel` interface and reach into `.symbols` for file-scoped
+ * operations or `.types` / `.methods` / `.fields` for owner-scoped ones.
+ *
+ * ## Fan-out via wrapped add()
+ *
+ * `createSemanticModel()` creates a pure SymbolTable, creates the three
+ * registries, builds a dispatch table via `createRegistrationTable`, and
+ * exposes a SymbolTable-shaped façade whose `add()`:
+ *
+ *   1. Calls `rawSymbols.add()` — writes the fileIndex + callable index
+ *      and returns the fully-built `SymbolDefinition`.
+ *   2. Runs pre-dispatch normalization (`Function`-with-`ownerId` routes
+ *      as `Method`).
+ *   3. Looks up the dispatch table and invokes the hook, which writes to
+ *      the appropriate owner-scoped registry.
+ *
+ * The wrapper is the only place where the two layers are combined. A
+ * direct `createSymbolTable()` caller (e.g. an isolated unit test) gets
+ * the pure, registry-free behavior — no surprises, no hidden side
+ * effects.
+ */
+import { createTypeRegistry } from './type-registry.js';
+import { createMethodRegistry } from './method-registry.js';
+import { createFieldRegistry } from './field-registry.js';
+import { createSymbolTable } from './symbol-table.js';
+import { createRegistrationTable } from './registration-table.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+//
+// NodeLabel taxonomy drift detection lives in `registration-table.ts` as a
+// pure compile-time check — the `LABEL_BEHAVIOR` map is
+// `Record<NodeLabel, LabelBehavior>` with `as const satisfies`, which proves
+// coverage, uniqueness, and no-extra-keys at build time. No runtime guard
+// is needed because drift is structurally impossible in the source.
+export const createSemanticModel = () => {
+    // 1. Create the pure, registry-unaware SymbolTable leaf.
+    // rawSymbols is the only handle in the codebase whose type (the
+    // internal createSymbolTable return) includes `.clear()`. cascadeClear
+    // below reaches it here; no external caller receives this variable.
+    const rawSymbols = createSymbolTable();
+    // 2. Create the three owner-scoped registries.
+    const types = createTypeRegistry();
+    const methods = createMethodRegistry();
+    const fields = createFieldRegistry();
+    // 3. Build the dispatch table, closed over THIS instance's registries.
+    const dispatchTable = createRegistrationTable({ types, methods, fields });
+    // 4. Wrap rawSymbols so `add()` fans out into the registries via the
+    //    dispatch table. See module JSDoc for the three-step contract.
+    const wrappedAdd = (filePath, name, nodeId, type, metadata) => {
+        const def = rawSymbols.add(filePath, name, nodeId, type, metadata);
+        // Function-with-ownerId (Python `def` in a class body, Rust trait
+        // method, Kotlin companion method) routes as Method. Keeps the
+        // dispatch table single-purpose.
+        const dispatchKey = type === 'Function' && metadata?.ownerId !== undefined ? 'Method' : type;
+        const hook = dispatchTable.get(dispatchKey);
+        if (hook) {
+            hook(name, def);
+        }
+        return def;
+    };
+    // Cascade clear: single source of truth for "reset the entire model".
+    // Wired into both `model.clear()` AND `model.symbols.clear()` so that a
+    // caller holding only a SymbolTable reference can't leave the
+    // owner-scoped registries populated while the file/callable indexes go
+    // empty (the phantom-resolution failure mode).
+    const cascadeClear = () => {
+        types.clear();
+        methods.clear();
+        fields.clear();
+        rawSymbols.clear();
+    };
+    // Writer-typed facade: exposes reads + add, but NO `clear` field.
+    // Callers holding a `SemanticModel.symbols` reference cannot desync
+    // the leaf indexes from the owner-scoped registries. Consumers that
+    // only query should widen their annotation to SymbolTableReader for
+    // least-authority clarity.
+    const symbols = {
+        add: wrappedAdd,
+        lookupExact: rawSymbols.lookupExact,
+        lookupExactFull: rawSymbols.lookupExactFull,
+        lookupExactAll: rawSymbols.lookupExactAll,
+        lookupCallableByName: rawSymbols.lookupCallableByName,
+        getFiles: rawSymbols.getFiles,
+        getStats: rawSymbols.getStats,
+    };
+    return {
+        types,
+        methods,
+        fields,
+        symbols,
+        clear: cascadeClear,
+    };
+};