gitnexus 1.6.3-rc.2 → 1.6.3-rc.21

package/dist/_shared/scope-resolution/resolve-type-ref.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `resolveTypeRef` — strict single-return resolver for `TypeRef`s
+ * (RFC §4.6; Ring 2 SHARED #916).
+ *
+ * Narrower contract than `Registry.lookup`: no name-only global fallback, no
+ * confidence ranking, no arity check. Used by `Registry.lookup` Step 2 (type-
+ * binding propagation) and by any caller that wants the single best type-
+ * target for an annotation without paying for the full evidence pipeline.
+ *
+ * **Algorithm (strict).** Walk the scope chain from `ref.declaredAtScope`:
+ *
+ *   1. At each scope, inspect `bindings.get(ref.rawName)`:
+ *      - If one of the bindings is a **type-kind** def with a **strict origin**
+ *        (`'local' | 'import' | 'namespace' | 'reexport'`), return it.
+ *      - If any binding for this name exists at this scope but none qualifies
+ *        (e.g., a local variable named `User` shadows an outer import of class
+ *        `User`), return `null`. The nearer binding shadows; we do NOT fall
+ *        through to the global qualified-name index.
+ *      - Otherwise continue to the parent scope.
+ *   2. If the raw name is a dotted path (e.g., `'models.User'`) and the scope
+ *      walk produced no match, consult `QualifiedNameIndex.byQualifiedName`.
+ *      Only accept **exactly one** type-kind hit — anything ambiguous returns
+ *      `null` rather than a guess.
+ *   3. Return `null`.
+ *
+ * **What `'strict' origins' means.** `'wildcard'` is intentionally excluded.
+ * A wildcard-expanded name (`from x import *`) is too loose to use as an
+ * anchor for type resolution — it gives no signal about whether the name was
+ * actually imported. `Registry.lookup` may accept wildcard bindings at its
+ * own discretion (with lower evidence weight); `resolveTypeRef` does not.
+ *
+ * **What 'type-kind' means.** The subset of `NodeLabel` that a type annotation
+ * may legitimately reference: class-like, interface-like, enum-like, and
+ * alias-like kinds. See `TYPE_KINDS` below.
+ *
+ * Pure function — safe to call repeatedly; no side effects.
+ */
+import type { SymbolDefinition } from './symbol-definition.js';
+import type { ScopeLookup, TypeRef } from './types.js';
+import type { DefIndex } from './def-index.js';
+import type { QualifiedNameIndex } from './qualified-name-index.js';
+/**
+ * All inputs `resolveTypeRef` needs from the semantic model. Bundled into a
+ * context object so the call site stays short and the interface is stable as
+ * additional indexes get threaded through in later rings.
+ */
+export interface ResolveTypeRefContext {
+    readonly scopes: ScopeLookup;
+    readonly defIndex: DefIndex;
+    readonly qualifiedNameIndex: QualifiedNameIndex;
+}
+export declare function resolveTypeRef(ref: TypeRef, ctx: ResolveTypeRefContext): SymbolDefinition | null;
+//# sourceMappingURL=resolve-type-ref.d.ts.map

package/dist/_shared/scope-resolution/resolve-type-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-type-ref.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/resolve-type-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAuB,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAIpE;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;CACjD;AA4CD,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,qBAAqB,GAAG,gBAAgB,GAAG,IAAI,CAgDhG"}

package/dist/_shared/scope-resolution/resolve-type-ref.js

@@ -0,0 +1,126 @@
+/**
+ * `resolveTypeRef` — strict single-return resolver for `TypeRef`s
+ * (RFC §4.6; Ring 2 SHARED #916).
+ *
+ * Narrower contract than `Registry.lookup`: no name-only global fallback, no
+ * confidence ranking, no arity check. Used by `Registry.lookup` Step 2 (type-
+ * binding propagation) and by any caller that wants the single best type-
+ * target for an annotation without paying for the full evidence pipeline.
+ *
+ * **Algorithm (strict).** Walk the scope chain from `ref.declaredAtScope`:
+ *
+ *   1. At each scope, inspect `bindings.get(ref.rawName)`:
+ *      - If one of the bindings is a **type-kind** def with a **strict origin**
+ *        (`'local' | 'import' | 'namespace' | 'reexport'`), return it.
+ *      - If any binding for this name exists at this scope but none qualifies
+ *        (e.g., a local variable named `User` shadows an outer import of class
+ *        `User`), return `null`. The nearer binding shadows; we do NOT fall
+ *        through to the global qualified-name index.
+ *      - Otherwise continue to the parent scope.
+ *   2. If the raw name is a dotted path (e.g., `'models.User'`) and the scope
+ *      walk produced no match, consult `QualifiedNameIndex.byQualifiedName`.
+ *      Only accept **exactly one** type-kind hit — anything ambiguous returns
+ *      `null` rather than a guess.
+ *   3. Return `null`.
+ *
+ * **What `'strict' origins' means.** `'wildcard'` is intentionally excluded.
+ * A wildcard-expanded name (`from x import *`) is too loose to use as an
+ * anchor for type resolution — it gives no signal about whether the name was
+ * actually imported. `Registry.lookup` may accept wildcard bindings at its
+ * own discretion (with lower evidence weight); `resolveTypeRef` does not.
+ *
+ * **What 'type-kind' means.** The subset of `NodeLabel` that a type annotation
+ * may legitimately reference: class-like, interface-like, enum-like, and
+ * alias-like kinds. See `TYPE_KINDS` below.
+ *
+ * Pure function — safe to call repeatedly; no side effects.
+ */
+// ─── Strict policy constants ────────────────────────────────────────────────
+/** `'wildcard'` is deliberately absent. See file header. */
+const STRICT_ORIGINS = new Set([
+    'local',
+    'import',
+    'namespace',
+    'reexport',
+]);
+/**
+ * `NodeLabel` values that may appear on the RHS of a type annotation.
+ *
+ * Includes the usual class-like and interface-like kinds plus the alias-like
+ * ones (`TypeAlias`, `Typedef`). `Namespace` is excluded — it is a scope
+ * container, not a value type. `Function` / `Method` / `Variable` are
+ * excluded by design: a `rawName` bound to them at a strict origin is a
+ * *shadowing* binding, which the algorithm short-circuits to `null`.
+ *
+ * `'Type'` (the generic `NodeLabel` value) is also excluded — verified
+ * against `gitnexus/src/core/ingestion/` at the time of writing, no
+ * production extractor emits `type: 'Type'` for annotation-relevant
+ * symbols. Should a future extractor start emitting it, add `'Type'`
+ * here and add a test asserting the new path.
+ */
+const TYPE_KINDS = new Set([
+    'Class',
+    'Interface',
+    'Enum',
+    'Struct',
+    'Union',
+    'Trait',
+    'TypeAlias',
+    'Typedef',
+    'Record',
+    'Delegate',
+    'Annotation',
+    'Template',
+]);
+// ─── Main entry point ──────────────────────────────────────────────────────
+export function resolveTypeRef(ref, ctx) {
+    // Phase 1: scope-chain walk anchored at the declaration site.
+    let currentId = ref.declaredAtScope;
+    const visited = new Set();
+    while (currentId !== null) {
+        // Cycle guard — a well-formed scope tree never loops, but a bug in the
+        // construction path should fail fast here rather than hanging.
+        if (visited.has(currentId))
+            return null;
+        visited.add(currentId);
+        const scope = ctx.scopes.getScope(currentId);
+        if (scope === undefined)
+            return null; // broken chain = unresolvable
+        const bindings = scope.bindings.get(ref.rawName);
+        if (bindings !== undefined && bindings.length > 0) {
+            // At least one binding exists at this scope → it is the shadowing site.
+            // Either one of them qualifies, or the name is shadowed by a non-type.
+            for (const binding of bindings) {
+                if (!STRICT_ORIGINS.has(binding.origin))
+                    continue;
+                if (TYPE_KINDS.has(binding.def.type)) {
+                    return binding.def;
+                }
+            }
+            // Shadowed by a non-type / non-strict-origin binding. Fail fast — no
+            // global fallback, no walk to the parent.
+            return null;
+        }
+        currentId = scope.parent;
+    }
+    // Phase 2: dotted fallback via `QualifiedNameIndex`. Only accept a unique
+    // type-kind hit; anything ambiguous returns null (strict: no guesses).
+    if (ref.rawName.includes('.')) {
+        const candidates = ctx.qualifiedNameIndex.get(ref.rawName);
+        let onlyTypeDef = null;
+        for (const defId of candidates) {
+            const def = ctx.defIndex.get(defId);
+            if (def === undefined)
+                continue;
+            if (!TYPE_KINDS.has(def.type))
+                continue;
+            if (onlyTypeDef !== null)
+                return null; // ambiguous
+            onlyTypeDef = def;
+        }
+        if (onlyTypeDef !== null)
+            return onlyTypeDef;
+    }
+    return null;
+}
+//# sourceMappingURL=resolve-type-ref.js.map

package/dist/_shared/scope-resolution/resolve-type-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-type-ref.js","sourceRoot":"","sources":["../../src/scope-resolution/resolve-type-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAqBH,+EAA+E;AAE/E,4DAA4D;AAC5D,MAAM,cAAc,GAAsC,IAAI,GAAG,CAAuB;IACtF,OAAO;IACP,QAAQ;IACR,WAAW;IACX,UAAU;CACX,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,GAA2B,IAAI,GAAG,CAAY;IAC5D,OAAO;IACP,WAAW;IACX,MAAM;IACN,QAAQ;IACR,OAAO;IACP,OAAO;IACP,WAAW;IACX,SAAS;IACT,QAAQ;IACR,UAAU;IACV,YAAY;IACZ,UAAU;CACX,CAAC,CAAC;AAEH,8EAA8E;AAE9E,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,GAA0B;IACrE,8DAA8D;IAC9D,IAAI,SAAS,GAAmB,GAAG,CAAC,eAAe,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAW,CAAC;IAEnC,OAAO,SAAS,KAAK,IAAI,EAAE,CAAC;QAC1B,uEAAuE;QACvE,+DAA+D;QAC/D,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAEvB,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,CAAC,8BAA8B;QAEpE,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,wEAAwE;YACxE,uEAAuE;YACvE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC;oBAAE,SAAS;gBAClD,IAAI,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBACrC,OAAO,OAAO,CAAC,GAAG,CAAC;gBACrB,CAAC;YACH,CAAC;YACD,qEAAqE;YACrE,0CAA0C;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;QAED,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,0EAA0E;IAC1E,uEAAuE;IACvE,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,GAAG,CAAC,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,WAAW,GAA4B,IAAI,CAAC;QAChD,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;YAC/B,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACpC,IAAI,GAAG,KAAK,SAAS;gBAAE,SAAS;YAChC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YACxC,IAAI,WAAW,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC,CAAC,YAAY;YACnD,WAAW,GAAG,GAAG,CAAC;QACpB,CAAC;QACD,IAAI,WAAW,KAAK,IAAI;YAAE,OAAO,WAAW,CAAC;IAC/C,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/_shared/scope-resolution/scope-id.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `ScopeId` canonical constructor + string intern pool
+ * (RFC §2.2; Ring 2 SHARED #912).
+ *
+ * `ScopeId` is a deterministic string derived from the scope's file path,
+ * byte range, and kind:
+ *
+ *   scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}
+ *
+ * Two scopes produced by reparsing the same file at the same positions are
+ * `===`-equal as strings. Beyond the canonical shape, `makeScopeId` also
+ * **interns** the string through a process-local pool, so repeated calls
+ * with structurally identical inputs return the same string reference —
+ * making `Map<ScopeId, ...>` lookups and cache keys identity-fast.
+ *
+ * The intern pool is unbounded. The number of distinct `ScopeId`s across a
+ * single indexing run is O(total scopes in workspace), which is bounded by
+ * source-text size and already in memory; interning adds no asymptotic
+ * pressure. `clearScopeIdInternPool` is exported for test isolation.
+ */
+import type { Range } from './types.js';
+import type { ScopeId, ScopeKind } from './types.js';
+/** Inputs required to construct a canonical `ScopeId`. */
+export interface ScopeIdInput {
+    readonly filePath: string;
+    readonly range: Range;
+    readonly kind: ScopeKind;
+}
+/**
+ * Build a canonical `ScopeId` from its structural parts and intern it.
+ *
+ * Pure + referentially transparent: given the same input shape, always
+ * returns the same string reference for the lifetime of the pool.
+ */
+export declare function makeScopeId(input: ScopeIdInput): ScopeId;
+/**
+ * Drop the intern pool. Intended for test setup/teardown — production code
+ * should not need this, since the pool's memory usage is bounded by the
+ * number of live scopes and cleaning it mid-run would break identity
+ * equality for existing scope ids.
+ */
+export declare function clearScopeIdInternPool(): void;
+//# sourceMappingURL=scope-id.d.ts.map

package/dist/_shared/scope-resolution/scope-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-id.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/scope-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAErD,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAMxD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/_shared/scope-resolution/scope-id.js

@@ -0,0 +1,46 @@
+/**
+ * `ScopeId` canonical constructor + string intern pool
+ * (RFC §2.2; Ring 2 SHARED #912).
+ *
+ * `ScopeId` is a deterministic string derived from the scope's file path,
+ * byte range, and kind:
+ *
+ *   scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}
+ *
+ * Two scopes produced by reparsing the same file at the same positions are
+ * `===`-equal as strings. Beyond the canonical shape, `makeScopeId` also
+ * **interns** the string through a process-local pool, so repeated calls
+ * with structurally identical inputs return the same string reference —
+ * making `Map<ScopeId, ...>` lookups and cache keys identity-fast.
+ *
+ * The intern pool is unbounded. The number of distinct `ScopeId`s across a
+ * single indexing run is O(total scopes in workspace), which is bounded by
+ * source-text size and already in memory; interning adds no asymptotic
+ * pressure. `clearScopeIdInternPool` is exported for test isolation.
+ */
+/**
+ * Build a canonical `ScopeId` from its structural parts and intern it.
+ *
+ * Pure + referentially transparent: given the same input shape, always
+ * returns the same string reference for the lifetime of the pool.
+ */
+export function makeScopeId(input) {
+    const raw = `scope:${input.filePath}#${input.range.startLine}:${input.range.startCol}-${input.range.endLine}:${input.range.endCol}:${input.kind}`;
+    const existing = INTERN_POOL.get(raw);
+    if (existing !== undefined)
+        return existing;
+    INTERN_POOL.set(raw, raw);
+    return raw;
+}
+/**
+ * Drop the intern pool. Intended for test setup/teardown — production code
+ * should not need this, since the pool's memory usage is bounded by the
+ * number of live scopes and cleaning it mid-run would break identity
+ * equality for existing scope ids.
+ */
+export function clearScopeIdInternPool() {
+    INTERN_POOL.clear();
+}
+/** Internal: shared intern pool (process-local). */
+const INTERN_POOL = new Map();
+//# sourceMappingURL=scope-id.js.map

package/dist/_shared/scope-resolution/scope-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-id.js","sourceRoot":"","sources":["../../src/scope-resolution/scope-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAYH;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC7C,MAAM,GAAG,GAAG,SAAS,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;IAClJ,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC1B,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,WAAW,CAAC,KAAK,EAAE,CAAC;AACtB,CAAC;AAED,oDAAoD;AACpD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC"}

package/dist/_shared/scope-resolution/scope-tree.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `ScopeTree` — the lexical-scope spine of the `SemanticModel`
+ * (RFC §2.2 + §3.1; Ring 2 SHARED #912).
+ *
+ * Generalizes the `enclosingFunctions` pattern from closed PR #902 to
+ * arbitrary `ScopeKind`s. Owns the (parent ↔ children) relationship
+ * derived from each `Scope.parent` pointer, and validates the structural
+ * invariants a well-formed scope tree must satisfy.
+ *
+ * Invariants enforced at build time (throw on violation):
+ *
+ *   - Every non-`Module` scope has a non-null parent.
+ *   - Every parent pointer references a scope that was also supplied to
+ *     `buildScopeTree`.
+ *   - Parent range **strictly contains** child range.
+ *   - Sibling ranges under the same parent do not overlap.
+ *   - Parent and child live in the same `filePath`. (Cross-file parent
+ *     pointers would be a category error — a `File` scope is not the
+ *     parent of another file's scopes; imports do that job.)
+ *
+ * Satisfies the `ScopeLookup` contract (defined in `./types.js`), so
+ * `resolveTypeRef` (#916) and the scope-aware registries (#917) can take a
+ * `ScopeTree` directly without adapters.
+ *
+ * Immutable surface: `byId` is a `ReadonlyMap`; children arrays are
+ * `Object.freeze`d; miss lookups return a shared frozen empty array.
+ */
+import type { Scope, ScopeId, ScopeLookup } from './types.js';
+export interface ScopeTree extends ScopeLookup {
+    readonly size: number;
+    readonly byId: ReadonlyMap<ScopeId, Scope>;
+    getScope(id: ScopeId): Scope | undefined;
+    getParent(id: ScopeId): Scope | undefined;
+    /** Child `ScopeId`s of `id`, in input order. Frozen empty array on miss. */
+    getChildren(id: ScopeId): readonly ScopeId[];
+    /**
+     * Ancestor chain from the immediate parent up to (and including) the
+     * root module scope. Excludes the starting scope itself. Frozen empty
+     * array on miss / for a root scope.
+     */
+    getAncestors(id: ScopeId): readonly ScopeId[];
+    has(id: ScopeId): boolean;
+}
+/**
+ * Thrown by `buildScopeTree` when the input violates a structural
+ * invariant. Carries the offending ids + the invariant name so failed
+ * extraction pipelines can report actionable diagnostics.
+ */
+export declare class ScopeTreeInvariantError extends Error {
+    readonly invariant: 'non-module-requires-parent' | 'parent-not-found' | 'parent-must-contain-child' | 'sibling-ranges-overlap' | 'parent-must-share-filepath' | 'duplicate-scope-id';
+    constructor(invariant: 'non-module-requires-parent' | 'parent-not-found' | 'parent-must-contain-child' | 'sibling-ranges-overlap' | 'parent-must-share-filepath' | 'duplicate-scope-id', message: string);
+}
+/**
+ * Build an immutable `ScopeTree` from a flat list of `Scope` records.
+ *
+ * Throws `ScopeTreeInvariantError` on the first invariant violation; a
+ * malformed tree is a bug in the extraction pipeline, not a data case for
+ * consumers to handle, so fail-fast is the correct posture.
+ */
+export declare function buildScopeTree(scopes: readonly Scope[]): ScopeTree;
+//# sourceMappingURL=scope-tree.d.ts.map

package/dist/_shared/scope-resolution/scope-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-tree.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/scope-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAS,MAAM,YAAY,CAAC;AAIrE,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAE3C,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;IACzC,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;IAC1C,4EAA4E;IAC5E,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC7C;;;;OAIG;IACH,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC9C,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC;CAC3B;AAID;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,SAAS,EACd,4BAA4B,GAC5B,kBAAkB,GAClB,2BAA2B,GAC3B,wBAAwB,GACxB,4BAA4B,GAC5B,oBAAoB;gBANf,SAAS,EACd,4BAA4B,GAC5B,kBAAkB,GAClB,2BAA2B,GAC3B,wBAAwB,GACxB,4BAA4B,GAC5B,oBAAoB,EACxB,OAAO,EAAE,MAAM;CAKlB;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAiFlE"}

package/dist/_shared/scope-resolution/scope-tree.js

@@ -0,0 +1,186 @@
+/**
+ * `ScopeTree` — the lexical-scope spine of the `SemanticModel`
+ * (RFC §2.2 + §3.1; Ring 2 SHARED #912).
+ *
+ * Generalizes the `enclosingFunctions` pattern from closed PR #902 to
+ * arbitrary `ScopeKind`s. Owns the (parent ↔ children) relationship
+ * derived from each `Scope.parent` pointer, and validates the structural
+ * invariants a well-formed scope tree must satisfy.
+ *
+ * Invariants enforced at build time (throw on violation):
+ *
+ *   - Every non-`Module` scope has a non-null parent.
+ *   - Every parent pointer references a scope that was also supplied to
+ *     `buildScopeTree`.
+ *   - Parent range **strictly contains** child range.
+ *   - Sibling ranges under the same parent do not overlap.
+ *   - Parent and child live in the same `filePath`. (Cross-file parent
+ *     pointers would be a category error — a `File` scope is not the
+ *     parent of another file's scopes; imports do that job.)
+ *
+ * Satisfies the `ScopeLookup` contract (defined in `./types.js`), so
+ * `resolveTypeRef` (#916) and the scope-aware registries (#917) can take a
+ * `ScopeTree` directly without adapters.
+ *
+ * Immutable surface: `byId` is a `ReadonlyMap`; children arrays are
+ * `Object.freeze`d; miss lookups return a shared frozen empty array.
+ */
+// ─── Build errors ───────────────────────────────────────────────────────────
+/**
+ * Thrown by `buildScopeTree` when the input violates a structural
+ * invariant. Carries the offending ids + the invariant name so failed
+ * extraction pipelines can report actionable diagnostics.
+ */
+export class ScopeTreeInvariantError extends Error {
+    invariant;
+    constructor(invariant, message) {
+        super(message);
+        this.invariant = invariant;
+        this.name = 'ScopeTreeInvariantError';
+    }
+}
+// ─── Builder ───────────────────────────────────────────────────────────────
+/**
+ * Build an immutable `ScopeTree` from a flat list of `Scope` records.
+ *
+ * Throws `ScopeTreeInvariantError` on the first invariant violation; a
+ * malformed tree is a bug in the extraction pipeline, not a data case for
+ * consumers to handle, so fail-fast is the correct posture.
+ */
+export function buildScopeTree(scopes) {
+    const byId = new Map();
+    const childrenById = new Map();
+    // ── Pass 1: collect by id + duplicate check ───────────────────────────
+    for (const scope of scopes) {
+        if (byId.has(scope.id)) {
+            throw new ScopeTreeInvariantError('duplicate-scope-id', `Two scopes share id '${scope.id}'. Scope ids must be unique per tree.`);
+        }
+        byId.set(scope.id, scope);
+    }
+    // ── Pass 2: validate parent pointers + build children buckets ─────────
+    for (const scope of scopes) {
+        if (scope.parent === null) {
+            if (scope.kind !== 'Module') {
+                throw new ScopeTreeInvariantError('non-module-requires-parent', `Scope '${scope.id}' has kind '${scope.kind}' but no parent. Only 'Module' scopes may be root-level.`);
+            }
+            continue;
+        }
+        const parent = byId.get(scope.parent);
+        if (parent === undefined) {
+            throw new ScopeTreeInvariantError('parent-not-found', `Scope '${scope.id}' references parent '${scope.parent}' which is not part of this tree.`);
+        }
+        if (parent.filePath !== scope.filePath) {
+            throw new ScopeTreeInvariantError('parent-must-share-filepath', `Scope '${scope.id}' (${scope.filePath}) has parent '${parent.id}' in a different file (${parent.filePath}). Parent/child scopes must share filePath.`);
+        }
+        if (!rangeStrictlyContains(parent.range, scope.range)) {
+            throw new ScopeTreeInvariantError('parent-must-contain-child', `Parent scope '${parent.id}' at ${formatRange(parent.range)} does not strictly contain child '${scope.id}' at ${formatRange(scope.range)}.`);
+        }
+        let bucket = childrenById.get(parent.id);
+        if (bucket === undefined) {
+            bucket = [];
+            childrenById.set(parent.id, bucket);
+        }
+        bucket.push(scope.id);
+    }
+    // ── Pass 3: sibling-overlap check ─────────────────────────────────────
+    for (const [parentId, childIds] of childrenById) {
+        if (childIds.length < 2)
+            continue;
+        // Sort siblings by (startLine, startCol) for an O(n log n) pairwise
+        // scan instead of O(n²) all-pairs.
+        const children = childIds.map((id) => byId.get(id)).slice();
+        children.sort((a, b) => comparePosition(a.range, b.range));
+        for (let i = 1; i < children.length; i++) {
+            const prev = children[i - 1];
+            const curr = children[i];
+            if (rangesOverlap(prev.range, curr.range)) {
+                throw new ScopeTreeInvariantError('sibling-ranges-overlap', `Sibling scopes under parent '${parentId}' overlap: '${prev.id}' ${formatRange(prev.range)} and '${curr.id}' ${formatRange(curr.range)}.`);
+            }
+        }
+    }
+    // Freeze children arrays so the surface is truly read-only.
+    const frozenChildren = new Map();
+    for (const [parentId, childIds] of childrenById) {
+        frozenChildren.set(parentId, Object.freeze(childIds.slice()));
+    }
+    return freezeTree(byId, frozenChildren);
+}
+// ─── Internals ──────────────────────────────────────────────────────────────
+const EMPTY_CHILDREN = Object.freeze([]);
+function freezeTree(byId, childrenById) {
+    return {
+        byId,
+        get size() {
+            return byId.size;
+        },
+        getScope(id) {
+            return byId.get(id);
+        },
+        getParent(id) {
+            const scope = byId.get(id);
+            if (scope === undefined || scope.parent === null)
+                return undefined;
+            return byId.get(scope.parent);
+        },
+        getChildren(id) {
+            return childrenById.get(id) ?? EMPTY_CHILDREN;
+        },
+        getAncestors(id) {
+            const start = byId.get(id);
+            if (start === undefined || start.parent === null)
+                return EMPTY_CHILDREN;
+            const out = [];
+            const visited = new Set([id]);
+            let cursor = start.parent;
+            while (cursor !== null && !visited.has(cursor)) {
+                visited.add(cursor);
+                out.push(cursor);
+                const next = byId.get(cursor);
+                cursor = next === undefined ? null : next.parent;
+            }
+            return Object.freeze(out);
+        },
+        has(id) {
+            return byId.has(id);
+        },
+    };
+}
+/**
+ * `outer` strictly contains `inner` when `outer`'s start is at or before
+ * `inner`'s start, `outer`'s end is at or after `inner`'s end, and they are
+ * not the exact same range. Equal ranges are rejected — a child cannot
+ * occupy the exact same span as its parent.
+ */
+function rangeStrictlyContains(outer, inner) {
+    if (outer.startLine === inner.startLine &&
+        outer.startCol === inner.startCol &&
+        outer.endLine === inner.endLine &&
+        outer.endCol === inner.endCol) {
+        return false;
+    }
+    const outerStartsAtOrBefore = outer.startLine < inner.startLine ||
+        (outer.startLine === inner.startLine && outer.startCol <= inner.startCol);
+    const outerEndsAtOrAfter = outer.endLine > inner.endLine ||
+        (outer.endLine === inner.endLine && outer.endCol >= inner.endCol);
+    return outerStartsAtOrBefore && outerEndsAtOrAfter;
+}
+/**
+ * Two ranges overlap when neither finishes before the other begins. Ranges
+ * that merely touch at a single boundary point (`a.end === b.start`) do
+ * NOT overlap — this matches tree-sitter's half-open-like range semantics
+ * and the typical "sibling blocks meet but don't overlap" pattern.
+ */
+function rangesOverlap(a, b) {
+    const aEndsBeforeB = a.endLine < b.startLine || (a.endLine === b.startLine && a.endCol <= b.startCol);
+    const bEndsBeforeA = b.endLine < a.startLine || (b.endLine === a.startLine && b.endCol <= a.startCol);
+    return !(aEndsBeforeB || bEndsBeforeA);
+}
+function comparePosition(a, b) {
+    if (a.startLine !== b.startLine)
+        return a.startLine - b.startLine;
+    return a.startCol - b.startCol;
+}
+function formatRange(r) {
+    return `${r.startLine}:${r.startCol}-${r.endLine}:${r.endCol}`;
+}
+//# sourceMappingURL=scope-tree.js.map

package/dist/_shared/scope-resolution/scope-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-tree.js","sourceRoot":"","sources":["../../src/scope-resolution/scope-tree.ts"],"names":[],"mappings":"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"}

package/dist/_shared/scope-resolution/shadow/aggregate.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shadow-mode aggregation — per-language parity %, per-evidence-kind
+ * breakdown of divergences. Consumed by the parity dashboard (RING2-PKG-5).
+ *
+ * Pure functions; no I/O. The harness persists per-run JSON; the dashboard
+ * reads `.gitnexus/shadow-parity/latest.json` and renders.
+ *
+ * Related types — `ShadowAgreement`, `ShadowCallsite`, `ShadowDiff` — are
+ * defined alongside `diffResolutions` in `./diff.ts` and re-exported
+ * through the top-level `gitnexus-shared` barrel. Consumers import all
+ * three from `gitnexus-shared`, not from this module.
+ *
+ * Part of RFC #909 Ring 2 SHARED — #918.
+ */
+import type { SupportedLanguages } from '../../languages.js';
+import type { ResolutionEvidence } from '../types.js';
+import type { ShadowDiff } from './diff.js';
+export interface LanguageParityRow {
+    readonly language: SupportedLanguages;
+    readonly totalCalls: number;
+    readonly bothAgree: number;
+    readonly onlyLegacy: number;
+    readonly onlyNew: number;
+    readonly bothDisagree: number;
+    readonly bothEmpty: number;
+    /**
+     * Fraction in [0, 1]. Numerator = `bothAgree`; denominator = "calls where
+     * at least one side resolved" = `totalCalls - bothEmpty`.
+     *
+     * When the denominator is 0 (all calls for this language were
+     * `both-empty`), returns 0. Callers rendering the dashboard should treat
+     * a 0 parity alongside `totalCalls === bothEmpty` as "no signal" rather
+     * than "total disagreement".
+     */
+    readonly parity: number;
+    /**
+     * Divergence signals broken down by `ResolutionEvidence.kind`. Sourced
+     * from `ShadowDiff.evidenceDelta` on non-agreeing rows only — `both-agree`
+     * and `both-empty` do not contribute.
+     */
+    readonly evidenceBreakdown: ReadonlyMap<ResolutionEvidence['kind'], number>;
+}
+export interface ShadowParityReport {
+    readonly generatedAt: string;
+    readonly perLanguage: readonly LanguageParityRow[];
+    readonly overall: Omit<LanguageParityRow, 'language' | 'evidenceBreakdown'>;
+}
+/**
+ * Aggregate a stream of `ShadowDiff` records into a `ShadowParityReport`,
+ * bucketed by language. Pure function.
+ *
+ * - `perLanguage` rows are sorted alphabetically by `SupportedLanguages`
+ *   value for stable JSON output (the dashboard reads
+ *   `.gitnexus/shadow-parity/latest.json` and diffing snapshots is useful).
+ * - `overall` is the column-wise sum across languages.
+ * - `generatedAt` is injected via the `now` parameter so tests stay
+ *   deterministic; production callers let it default to `new Date()`.
+ */
+export declare function aggregateDiffs(diffs: readonly {
+    readonly language: SupportedLanguages;
+    readonly diff: ShadowDiff;
+}[], now?: Date): ShadowParityReport;
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/_shared/scope-resolution/shadow/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../../src/scope-resolution/shadow/aggregate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,WAAW,CAAC;AAI7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,UAAU,GAAG,mBAAmB,CAAC,CAAC;CAC7E;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,EAAE,EACtF,GAAG,GAAE,IAAiB,GACrB,kBAAkB,CAuBpB"}