gitnexus 1.6.3 → 1.6.4-rc.10

package/dist/core/ingestion/registry-primary-flag.js

@@ -56,7 +56,9 @@ import { SupportedLanguages } from '../../_shared/index.js';
  *      so this set also controls what gets silenced in the legacy DAG.
  *
  * Add a language here ONLY after shadow parity ≥ 99% fixtures / ≥ 98%
- * corpus per RFC §6.4. The parity CI gate will block the PR otherwise.
+ * corpus per RFC §6.4. TypeScript is temporarily accepted under the
+ * Ring 3 CI parity gate while corpus-level shadow-mode wiring is tracked
+ * in #927 for this migration.
  *
  * The set is intentionally a static TypeScript literal (not a JSON import,
  * not an env lookup) so CI can discover it via `tsx` without a build step
@@ -65,6 +67,7 @@ import { SupportedLanguages } from '../../_shared/index.js';
 export const MIGRATED_LANGUAGES = new Set([
     SupportedLanguages.Python,
     SupportedLanguages.CSharp,
+    SupportedLanguages.TypeScript,
 ]);
 /**
  * Return the env-var name that controls a given language's registry-

package/dist/core/ingestion/scope-extractor-bridge.d.ts

@@ -13,8 +13,11 @@
  *      `emitScopeCaptures`. Returns `undefined`; zero work done. This is
  *      the state of every language today — `ParsedFile` production stays
  *      dormant until a language migrates.
- *   2. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
- *   3. **Swallows exceptions from either side.** A failure here returns
+ *   2. Short-circuits empty / whitespace-only files. There is no scope
+ *      content to extract, and some tree-sitter queries do not match an
+ *      otherwise valid empty root node.
+ *   3. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
+ *   4. **Swallows exceptions from either side.** A failure here returns
  *      `undefined` and emits a warning via `onWarn`; legacy parsing on
  *      the same file continues unaffected by the scope-extraction miss.
  *      Scope-based resolution is the new path under construction — it

package/dist/core/ingestion/scope-extractor-bridge.js

@@ -13,8 +13,11 @@
  *      `emitScopeCaptures`. Returns `undefined`; zero work done. This is
  *      the state of every language today — `ParsedFile` production stays
  *      dormant until a language migrates.
- *   2. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
- *   3. **Swallows exceptions from either side.** A failure here returns
+ *   2. Short-circuits empty / whitespace-only files. There is no scope
+ *      content to extract, and some tree-sitter queries do not match an
+ *      otherwise valid empty root node.
+ *   3. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
+ *   4. **Swallows exceptions from either side.** A failure here returns
  *      `undefined` and emits a warning via `onWarn`; legacy parsing on
  *      the same file continues unaffected by the scope-extraction miss.
  *      Scope-based resolution is the new path under construction — it
@@ -29,6 +32,8 @@ import { extract as extractScope } from './scope-extractor.js';
 export function extractParsedFile(provider, sourceText, filePath, onWarn, cachedTree) {
     if (provider.emitScopeCaptures === undefined)
         return undefined;
+    if (sourceText.trim().length === 0)
+        return undefined;
     try {
         const captures = provider.emitScopeCaptures(sourceText, filePath, cachedTree);
         return extractScope(captures, filePath, provider);

package/dist/core/ingestion/scope-extractor.js

@@ -58,7 +58,7 @@
  *   - `ParsedFile.localDefs`     — flattened union of `Scope.ownedDefs`.
  *   - `ParsedFile.referenceSites` — pre-resolution usage facts.
  */
-import { buildPositionIndex, buildScopeTree, makeScopeId } from '../../_shared/index.js';
+import { buildPositionIndex, buildScopeTree, canParentScope, makeScopeId } from '../../_shared/index.js';
 // ─── Public entry point ─────────────────────────────────────────────────────
 /**
  * Drive the five extraction passes and return a `ParsedFile`.
@@ -210,7 +210,11 @@ function pass1BuildScopes(matches, filePath, provider) {
         candidates.push({ match, range: anchor.range, kind, id });
     }
     // Sort by (startLine, startCol) ASC, (endLine, endCol) DESC so outer
-    // scopes appear before their children for parent-resolution.
+    // scopes appear before their children for parent-resolution. When two
+    // candidates have exactly equal ranges (e.g. a `compilation_unit` and
+    // the only top-level scope in the file — see `canParentScope`), Module
+    // sorts first so it lands on the stack ahead of the candidate that will
+    // claim it as parent.
     candidates.sort((a, b) => {
         if (a.range.startLine !== b.range.startLine)
             return a.range.startLine - b.range.startLine;
@@ -218,13 +222,23 @@ function pass1BuildScopes(matches, filePath, provider) {
             return a.range.startCol - b.range.startCol;
         if (a.range.endLine !== b.range.endLine)
             return b.range.endLine - a.range.endLine;
-        return b.range.endCol - a.range.endCol;
+        if (a.range.endCol !== b.range.endCol)
+            return b.range.endCol - a.range.endCol;
+        if (a.kind === b.kind)
+            return 0;
+        if (a.kind === 'Module')
+            return -1;
+        if (b.kind === 'Module')
+            return 1;
+        return 0;
     });
     const drafts = [];
     const stack = []; // enclosing real scopes, outermost at [0]
     for (const cand of candidates) {
-        // Pop the stack until the top strictly contains this candidate.
-        while (stack.length > 0 && !rangeStrictlyContains(stack[stack.length - 1].range, cand.range)) {
+        // Pop the stack until the top can parent this candidate (strict
+        // containment, plus the equal-range Module carve-out).
+        while (stack.length > 0 &&
+            !canParentScope(stack[stack.length - 1].range, cand.range, stack[stack.length - 1].kind, cand.kind)) {
             stack.pop();
         }
         const parent = stack.length > 0 ? stack[stack.length - 1].id : null;
@@ -692,19 +706,6 @@ function rangesEqual(a, b) {
         a.endLine === b.endLine &&
         a.endCol === b.endCol);
 }
-function rangeStrictlyContains(outer, inner) {
-    if (outer.startLine === inner.startLine &&
-        outer.startCol === inner.startCol &&
-        outer.endLine === inner.endLine &&
-        outer.endCol === inner.endCol) {
-        return false;
-    }
-    const startsBefore = outer.startLine < inner.startLine ||
-        (outer.startLine === inner.startLine && outer.startCol <= inner.startCol);
-    const endsAfter = outer.endLine > inner.endLine ||
-        (outer.endLine === inner.endLine && outer.endCol >= inner.endCol);
-    return startsBefore && endsAfter;
-}
 /**
  * Capture names that are never anchors — they are sub-tags nested inside a
  * larger anchor (e.g., the receiver expression inside a `@reference.call`

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.d.ts

@@ -88,14 +88,21 @@
  *     per-(caller, target) collapse semantics require multiple call
  *     sites in the same caller body not produce multiple edges.
  *
- *   - **I3 — `propagateImportedReturnTypes` mutation timing.** The
- *     pass mutates `Scope.typeBindings` (a plain `new Map(...)` from
+ *   - **I3 — `propagateImportedReturnTypes` mutation timing + ordering.**
+ *     The pass mutates `Scope.typeBindings` (a plain `new Map(...)` from
  *     `draftToScope`, NOT frozen). It MUST run AFTER `finalizeScopeModel`
  *     (so `indexes.bindings` is populated) and BEFORE
  *     `resolveReferenceSites` (so resolution sees the propagated types).
  *     The pass also re-runs `followChainPostFinalize` on every scope's
  *     typeBindings because scope-extractor's pass-4 already ran and
  *     missed any chain whose terminal lives in a foreign file.
+ *     Within the pass, files are walked in `indexes.sccs` reverse-
+ *     topological order (leaves first) so multi-hop alias chains
+ *     (e.g. `models.User → service.user → app.user`) collapse to the
+ *     terminal class in a single pass — every importer sees its
+ *     source's already-chain-followed typeBindings. Cyclic SCCs reach
+ *     a partial fixpoint within a single pass without iterating to
+ *     convergence; `ts-circular` only asserts pipeline-no-throw.
  *
  *   - **I4 — `emitReceiverBoundCalls` case order.** Cases are evaluated
  *     in this order; the FIRST that emits an edge wins:
@@ -129,14 +136,45 @@
  *     once per workspace at resolve time), and merging would create a
  *     god-interface that complicates future migrations.
  *
- *   - **I8 — Post-finalize hooks may mutate `Scope.typeBindings` and
- *     `indexes.bindings`.** `propagateImportedReturnTypes` and
- *     `populateNamespaceSiblings` both write to these structures via
- *     `as Map<...>` casts through `ReadonlyMap` facades. Downstream
- *     consumers MUST NOT freeze or snapshot these maps before all
- *     post-finalize hooks have run. The `ReadonlyMap<...>` type on
- *     `ScopeResolutionIndexes` is a read-guidance surface for
- *     consumers, NOT an immutability promise during the resolve phase.
+ *   - **I8 — Two-channel binding lifecycle.**
+ *     `indexes.bindings` is the **finalize-output channel**. After
+ *     `finalizeScopeModel` returns, its inner `BindingRef[]` arrays
+ *     are deep-frozen by `materializeBindings` and MUST NOT be
+ *     mutated by any post-finalize hook. Treat `indexes.bindings` as
+ *     immutable from the moment `finalizeScopeModel` returns.
+ *
+ *     `indexes.bindingAugmentations` is the **post-finalize
+ *     append-only channel**. Hooks like `populateNamespaceSiblings`
+ *     append cross-file bindings synthesized after finalize (C#
+ *     same-namespace visibility, `using static` member exposure)
+ *     into this channel, NOT into `indexes.bindings`. Inner arrays
+ *     here are NEVER frozen — hooks `push()` directly. Any consumer
+ *     that reads post-finalize workspace bindings MUST query both
+ *     index channels via `lookupBindingsAt`
+ *     (`scope-resolution/scope/walkers.ts`); the helper returns
+ *     finalized refs first, appends unique augmentation refs after,
+ *     and dedupes by `def.nodeId` so finalized metadata wins on
+ *     duplicate defs. Per-`Scope.bindings` local declarations are the
+ *     lexical extraction channel and remain a separate first-tier
+ *     lookup for local shadowing.
+ *
+ *     `Scope.typeBindings` remains mutable post-finalize per I6 (it
+ *     is intentionally not frozen at any point).
+ *
+ *     The `ReadonlyMap<...>` types on `ScopeResolutionIndexes` are
+ *     compile-time read-guidance for consumers; structural mutation
+ *     of `bindingAugmentations` is performed via a deliberate
+ *     `as Map<...>` cast inside the hook implementations and is the
+ *     ONLY sanctioned channel for post-finalize binding fanout.
+ *
+ *     The dev-mode runtime validator
+ *     (`validateBindingsImmutability` in
+ *     `scope-resolution/validate-bindings-immutability.ts`) surfaces
+ *     any drift — i.e. a hook writing to `indexes.bindings` instead
+ *     of `bindingAugmentations`, or producing a non-frozen finalized
+ *     bucket — via `onWarn` when explicitly enabled by
+ *     `NODE_ENV === 'development' || VALIDATE_SEMANTIC_MODEL === '1'`
+ *     (`VALIDATE_SEMANTIC_MODEL=0` is an explicit off switch).
  *
  *   - **I9 — `SemanticModel` is the single authoritative symbol store.**
  *     Every symbol-indexed lookup (key = `nodeId | simpleName |
@@ -244,8 +282,32 @@ export interface ScopeResolver {
      * resolvers that must distinguish "this module exists in the repo"
      * from "this module is external" (Python's fallback resolver, for
      * example).
+     *
+     * `resolutionConfig` is the opaque value returned by
+     * `loadResolutionConfig` (loaded once per workspace pass by the
+     * orchestrator). TypeScript uses this to thread `tsconfig.json` path
+     * aliases through to the standard resolver. Languages that don't
+     * need any extra config ignore the parameter.
+     */
+    resolveImportTarget(targetRaw: string, fromFile: string, allFilePaths: ReadonlySet<string>, resolutionConfig?: unknown): string | null;
+    /**
+     * Optional one-shot loader for cross-file import-resolution config
+     * (e.g. tsconfig path aliases for TypeScript, go.mod paths for Go,
+     * composer.json autoload for PHP). The orchestrator calls this once
+     * per workspace pass with the repo root and threads the result into
+     * every subsequent `resolveImportTarget` call as the
+     * `resolutionConfig` parameter.
+     *
+     * Languages that don't need any per-workspace config leave this
+     * undefined; the orchestrator threads `undefined` to
+     * `resolveImportTarget` in that case. Returning `null` is also
+     * supported and equivalent to "no config available".
+     *
+     * May be sync or async — the orchestrator awaits the result. The
+     * shape is opaque to the orchestrator (`unknown`); the per-language
+     * `resolveImportTarget` casts it to the language's expected shape.
      */
-    resolveImportTarget(targetRaw: string, fromFile: string, allFilePaths: ReadonlySet<string>): string | null;
+    loadResolutionConfig?(repoPath: string): Promise<unknown> | unknown;
     /**
      * Per-scope binding-merge precedence. The shared finalize pass
      * collects bindings from multiple sources (local declarations,

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.js

@@ -88,14 +88,21 @@
  *     per-(caller, target) collapse semantics require multiple call
  *     sites in the same caller body not produce multiple edges.
  *
- *   - **I3 — `propagateImportedReturnTypes` mutation timing.** The
- *     pass mutates `Scope.typeBindings` (a plain `new Map(...)` from
+ *   - **I3 — `propagateImportedReturnTypes` mutation timing + ordering.**
+ *     The pass mutates `Scope.typeBindings` (a plain `new Map(...)` from
  *     `draftToScope`, NOT frozen). It MUST run AFTER `finalizeScopeModel`
  *     (so `indexes.bindings` is populated) and BEFORE
  *     `resolveReferenceSites` (so resolution sees the propagated types).
  *     The pass also re-runs `followChainPostFinalize` on every scope's
  *     typeBindings because scope-extractor's pass-4 already ran and
  *     missed any chain whose terminal lives in a foreign file.
+ *     Within the pass, files are walked in `indexes.sccs` reverse-
+ *     topological order (leaves first) so multi-hop alias chains
+ *     (e.g. `models.User → service.user → app.user`) collapse to the
+ *     terminal class in a single pass — every importer sees its
+ *     source's already-chain-followed typeBindings. Cyclic SCCs reach
+ *     a partial fixpoint within a single pass without iterating to
+ *     convergence; `ts-circular` only asserts pipeline-no-throw.
  *
  *   - **I4 — `emitReceiverBoundCalls` case order.** Cases are evaluated
  *     in this order; the FIRST that emits an edge wins:
@@ -129,14 +136,45 @@
  *     once per workspace at resolve time), and merging would create a
  *     god-interface that complicates future migrations.
  *
- *   - **I8 — Post-finalize hooks may mutate `Scope.typeBindings` and
- *     `indexes.bindings`.** `propagateImportedReturnTypes` and
- *     `populateNamespaceSiblings` both write to these structures via
- *     `as Map<...>` casts through `ReadonlyMap` facades. Downstream
- *     consumers MUST NOT freeze or snapshot these maps before all
- *     post-finalize hooks have run. The `ReadonlyMap<...>` type on
- *     `ScopeResolutionIndexes` is a read-guidance surface for
- *     consumers, NOT an immutability promise during the resolve phase.
+ *   - **I8 — Two-channel binding lifecycle.**
+ *     `indexes.bindings` is the **finalize-output channel**. After
+ *     `finalizeScopeModel` returns, its inner `BindingRef[]` arrays
+ *     are deep-frozen by `materializeBindings` and MUST NOT be
+ *     mutated by any post-finalize hook. Treat `indexes.bindings` as
+ *     immutable from the moment `finalizeScopeModel` returns.
+ *
+ *     `indexes.bindingAugmentations` is the **post-finalize
+ *     append-only channel**. Hooks like `populateNamespaceSiblings`
+ *     append cross-file bindings synthesized after finalize (C#
+ *     same-namespace visibility, `using static` member exposure)
+ *     into this channel, NOT into `indexes.bindings`. Inner arrays
+ *     here are NEVER frozen — hooks `push()` directly. Any consumer
+ *     that reads post-finalize workspace bindings MUST query both
+ *     index channels via `lookupBindingsAt`
+ *     (`scope-resolution/scope/walkers.ts`); the helper returns
+ *     finalized refs first, appends unique augmentation refs after,
+ *     and dedupes by `def.nodeId` so finalized metadata wins on
+ *     duplicate defs. Per-`Scope.bindings` local declarations are the
+ *     lexical extraction channel and remain a separate first-tier
+ *     lookup for local shadowing.
+ *
+ *     `Scope.typeBindings` remains mutable post-finalize per I6 (it
+ *     is intentionally not frozen at any point).
+ *
+ *     The `ReadonlyMap<...>` types on `ScopeResolutionIndexes` are
+ *     compile-time read-guidance for consumers; structural mutation
+ *     of `bindingAugmentations` is performed via a deliberate
+ *     `as Map<...>` cast inside the hook implementations and is the
+ *     ONLY sanctioned channel for post-finalize binding fanout.
+ *
+ *     The dev-mode runtime validator
+ *     (`validateBindingsImmutability` in
+ *     `scope-resolution/validate-bindings-immutability.ts`) surfaces
+ *     any drift — i.e. a hook writing to `indexes.bindings` instead
+ *     of `bindingAugmentations`, or producing a non-frozen finalized
+ *     bucket — via `onWarn` when explicitly enabled by
+ *     `NODE_ENV === 'development' || VALIDATE_SEMANTIC_MODEL === '1'`
+ *     (`VALIDATE_SEMANTIC_MODEL=0` is an explicit off switch).
  *
  *   - **I9 — `SemanticModel` is the single authoritative symbol store.**
  *     Every symbol-indexed lookup (key = `nodeId | simpleName |