25 commits

Author	SHA1	Message	Date
evolution	d14d6602d5	feat(go): implement scope resolution hooks for Go language support (#1302)	2026-05-04 07:29:11 +01:00
vijaygali	aa7c273093	fix(ingestion): index Python repos with empty __init__.py and >32 KB files (#1163) ... * fix(ingestion): index Python repos with empty __init__.py and >32 KB files Two defensive fixes that let `gitnexus analyze` complete on Python codebases that previously failed. scope-extractor: synthesize an empty Module scope when the provider emits zero captures. Previously threw "no Module scope found", which fired for any 0-byte `__init__.py` package marker if the bridge's empty-source guard was bypassed. python/captures: wrap the parser.parse() and getPythonScopeQuery() .matches() calls in try/catch. node-tree-sitter throws "Invalid argument" for sources that overrun internal buffers (observed at the ~32 KB threshold on Windows). Degrade gracefully with a clear "skipping scope extraction for this file" warning instead of the opaque "Invalid argument" surfacing through the bridge. Verified by indexing whittlem/pycryptobot (which has 7 empty __init__.py and 11 Python files between 34 KB and 158 KB): 2,367 nodes / 4,973 edges, no segfault, queries resolve symbols inside the 158 KB controllers/PyCryptoBot.py. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ingestion): harden Python scope extraction fallbacks Keep failed Python scope extraction on the bridge skip path and build synthetic module scopes before extractor indexes are derived. Made-with: Cursor --------- Co-authored-by: Vijay Gali <vgali@vexcelco.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Gergo Magyar <gergomagyar@icloud.com>	2026-04-30 19:24:04 +01:00
Gergő Magyar	2a0c97c178	fix: add platform-aware semantic fallback (#1150) ... * fix: add platform-aware semantic fallback Make VECTOR an optional capability so Windows analysis remains stable while semantic embeddings can fall back to exact scan when native vector indexing is unavailable. Made-with: Cursor * fix: remove stale vector pool import Keep the merge with main lint-clean after VECTOR loading moved out of the read pool.	2026-04-28 12:21:25 +01:00
Gergő Magyar	c4999b02b0	fix(scope-resolution): avoid variadic reference site aggregation (#1112) ... Materialize finalized reference sites without spreading large arrays into push so large repositories do not overflow the JS argument stack.	2026-04-27 12:44:21 +01:00
ManniX-ITA	1e80285c47	fix(scope-resolution): allow same-range Module-as-parent for top-level scopes (closes #1086) (#1087) ... * fix(scope-resolution): allow same-range Module-as-parent for top-level scopes (closes #1086) When a C# file consists of a single top-level `namespace_declaration` that ends exactly at EOF (no trailing newline, no leading content outside the namespace's `{}` body), tree-sitter-c-sharp 0.23.1 reports identical byte ranges for `compilation_unit` and `namespace_declaration`. Pre-fix the scope-extractor parent-finder relied on strict containment, so the Module was popped off the stack and the Namespace ended up with `parent === null` → `ScopeTreeInvariantError: non-module-requires-parent` → `extractParsedFile` swallowed the throw and the whole file was dropped from the registry-primary path. Cross-file IMPORTS / CALLS edges originating in or terminating at that file vanished. Hit on three real-world `*.Designer.cs` files in PersistentWindows (`HotKeyWindow.Designer.cs`, `LaunchProcess.Designer.cs`, `DbKeySelect.Designer.cs`) — all have the byte signature `<BOM><CRLF>namespace ... { ... }<EOF>` (last hex = `... 7D 0D 0A 7D`). The fix is a single carve-out in the parent-validity contract: a `Module` may parent a same-range non-`Module` child. The relationship stays acyclic because the carve-out is direction-asymmetric — only Module-as- outer parents a same-range non-Module, never the reverse. Two coordinated changes: * `gitnexus/src/core/ingestion/scope-extractor.ts` — `pass1BuildScopes` now consults a new `canParentScope` helper instead of `rangeStrictlyContains` directly. Sort tie-breaker added so a same- range Module always sorts before a non-Module candidate, ensuring the Module lands on the parent-stack first regardless of tree-sitter capture iteration order. * `gitnexus-shared/src/scope-resolution/scope-tree.ts` — `buildScopeTree`'s `parent-must-contain-child` check now uses the same `canParentScope` carve-out so the validator agrees with the extractor on what a well-formed parent edge looks like. Error message updated to spell out the new contract. `rangeStrictlyContains` keeps its strict semantics in both files — position-index lookups, hook-side range comparisons, and other call sites are unchanged. * `gitnexus/test/fixtures/lang-resolution/csharp-namespace-as-root-no-trailing-newline/` — minimal regression fixture mirroring the PersistentWindows shape: both `Models/User.cs` and `App/Program.cs` end exactly on the closing `}` of their namespace with no trailing newline. The trigger is shape- driven, not size-driven, so the fixture stays small (~250 bytes total). * New `csharp.test.ts` describe block: scope extraction completes for both files, and the cross-file `IMPORTS` edge resolves through the scope-resolution path with `reason: 'csharp-scope: using'`. * `scope-tree.test.ts`: replaced the prior "rejects child ranges identical to the parent" case with three new ones — non-Module parent still rejected at equal range; Module-as-parent of a same-range non- Module accepted (the #1086 carve-out); Module-as-parent of another Module still rejected (the asymmetry guard). * `npx vitest run test/unit/scope-resolution test/integration/resolvers` → 2514 passed / 77 skipped / 0 failed (52 test files). * `npx tsc --noEmit` clean in both `gitnexus/` and `gitnexus-shared/`. * End-to-end on PersistentWindows (after rebuilding the Docker image with this branch): 3 prior `scope extraction failed for *.Designer.cs` warnings → 0. Pre-fix index numbers will be re-checked here once the branch is built and indexed; the existing post-#1082 baseline is 1113 nodes / 2987 edges / 39 clusters / 97 flows. `canParentScope` is language-agnostic. Other languages whose query emits `(compilation_unit) @scope.module` plus a single same-range top-level scope can naturally hit the same byte shape on minimal files; this fix applies to all of them uniformly. Refs: #1086 (issue with full root-cause analysis + 4-case empirical repro through `extractParsedFile`). * refactor(scope-resolution): export canParentScope from gitnexus-shared Addresses #1087 review (medium): the helper was previously duplicated byte-for-byte in `scope-extractor.ts` and `scope-tree.ts`. Per DoD "single source of truth in shared", the contract piece belongs in gitnexus-shared (Ring 2 SHARED #912) and the consuming layer should import it. Eliminates the silent-drift surface where a future edit to one copy would produce extractor/validator disagreement on what a well-formed parent edge looks like. Changes: - gitnexus-shared/src/scope-resolution/scope-tree.ts: add `export` to `canParentScope`. - gitnexus-shared/src/index.ts: re-export `canParentScope`. - gitnexus/src/core/ingestion/scope-extractor.ts: remove the local `canParentScope` definition (and its now-unused local copy of `rangeStrictlyContains`), import from `gitnexus-shared`. The local `rangesEqual` stays — it's still used in capture-anchor logic at two unrelated sites. Validation (per DoD §4.4 — both CLI and web consumers verified): - npx tsc --noEmit clean in gitnexus/ and gitnexus-shared/ - cd gitnexus-web && npx tsc -b --noEmit clean - gitnexus-shared `npm run build` clean - Targeted: vitest run test/unit/scope-resolution test/integration/resolvers → 2522 passed / 0 failed / 77 skipped (54 files) - Full suite: vitest run → 7238 passed / 1 failed / 97 skipped. The single failure is `test/unit/ignore-service.test.ts > warns on EACCES but does not throw`, which cannot run when uid=0 (root bypasses POSIX permission checks). Pre-existing on this branch before the refactor; unrelated to scope-resolution.	2026-04-27 11:06:54 +01:00
Gergő Magyar	7c3fa5853f	fix(ingestion): classify Python class methods as Method (#1102) ... * fix(ingestion): classify Python class methods as Method * fix(test): align Python large-buffer assertion with Method labels --------- Co-authored-by: gergo <gergo@Galahad.localdomain>	2026-04-27 09:04:50 +01:00
Gergő Magyar	09d78cadec	fix(ingestion): skip empty scope extraction (#1100)	2026-04-27 07:29:37 +01:00
Gergő Magyar	9e62f7c121	fix(ci): allow expected legacy parity failures (#1099) ... Made-with: Cursor	2026-04-27 06:59:18 +01:00
Gergő Magyar	98ee665889	fix(ingestion): two-channel binding lifecycle (closes #1066) + scope-resolution I8 hardening (#1082) ... * fix(csharp): adaptive tree-sitter buffer + frozen-bucket clone for cross-namespace siblings (#1066) Two coupled regressions surfaced when analyzing real-world C# repos with large source files (issue #1066): 1. Tree-sitter `parser.parse()` is hard-coded to a 32 KB buffer by default. Any file exceeding that threshold throws `Invalid argument` on the worker re-parse path of `populateCsharpNamespaceSiblings` (and the analogous Python / TypeScript captures fallbacks). 2. After the buffer fix unblocks the AST walk, the hook tries to `push()` onto the inner `BindingRef[]` array fetched from `indexes.bindings` — but `materializeBindings` froze that array via `Object.freeze(refs.slice())`. Result: `Cannot add property N, object is not extensible`. Fixes: - `csharp/captures.ts`, `python/captures.ts`, `typescript/captures.ts`: pass `bufferSize: getTreeSitterBufferSize(sourceText.length)` to `parser.parse()` on the cache-miss path so multi-MB files parse. - `csharp/namespace-siblings.ts`: introduce `cloneBindingBucket` to copy the frozen array before mutating, then `set()` the new array back. This is a working but architecturally compromised workaround (#1050 follow-up will replace it with an explicit augmentation channel — see docs/plans/2026-04-26-001 plan). Tests: - New `csharp-large-cache-miss-resolution` fixture (Models/Services/ Other layout, ~77 KB padded UserService.cs) drives the buffer-size failure end-to-end through worker mode. - `csharp.test.ts`: 4 new regression assertions covering both the parse-time buffer-size failure and the freeze workaround. - Per-language captures unit tests gain "large cache-miss file uses adaptive buffer" coverage (TS, Python, C#). - `csharp-hooks.test.ts`: in-memory freeze regression test that reproduces the `Cannot add property` crash without invoking the C# parser at all. Made-with: Cursor * refactor(scope-resolution): add bindingAugmentations channel to indexes Step 1 of the binding-augmentation-channel refactor (issue #1066 follow-up). Pure shape change — no consumers yet. Adds a new `readonly bindingAugmentations` field to `ScopeResolutionIndexes` initialized as an empty `Map` by `finalizeScopeModel`. The new channel is the dedicated post-finalize write target for hooks like `populateCsharpNamespaceSiblings`, so `indexes.bindings` can stay frozen and finalize-owned. Behavior unchanged: nothing reads or writes the new field yet. tsc and the full unit suite remain green. Plan: docs/plans/2026-04-26-001-binding-augmentation-channel.md (local only — `docs/plans/` is gitignored). Made-with: Cursor * feat(scope-resolution): add lookupBindingsAt dual-source helper Step 2 of the binding-augmentation-channel refactor. Introduces a single primitive every walker uses to read both the finalize-owned `indexes.bindings` channel and the post-finalize `indexes.bindingAugmentations` channel. Contract: - Finalized refs come first (preserves existing precedence). - Augmented refs append, deduped by `def.nodeId`. - Empty input on both channels returns a shared frozen empty array. - Single-channel hits return the bucket by reference (no allocation). No consumers are wired yet — Step 3 routes the existing walker primitives through this helper. Augmentations remain empty for every language; behavior of the full suite is unchanged. 8 unit tests pin precedence, dedup, identity for single-channel hits, and the shared-empty-frozen-array sentinel. Made-with: Cursor * refactor(scope-resolution): route binding lookups through lookupBindingsAt Step 3 of the binding-augmentation-channel refactor. Every direct `indexes.bindings.get(...)` consumer in the post-finalize phase is now routed through `lookupBindingsAt` (per-name) or `namesAtScope` + `lookupBindingsAt` (bulk iteration). Routed sites: - `findClassBindingInScope` (walkers.ts) — class-receiver lookups. - `findCallableBindingInScope` (walkers.ts) — free-call lookups. - `findExportedDefByName` (walkers.ts) — module-scope-fallback callable lookups. - `propagateImportedReturnTypes` (passes/imported-return-types.ts) — bulk iteration over an importer's binding entries; switched to `namesAtScope` + per-name `lookupBindingsAt` so post-finalize augmentations are visible to import-derived typeBinding mirrors. Behavior unchanged: augmentations are empty across the suite (Step 4 populates them for C# `populateNamespaceSiblings`). 587 scope-resolution unit tests + 50 integration resolver suites green (4 pre-existing Swift method-implements failures unrelated to this work). Adds `namesAtScope` companion helper for the bulk-iteration callers. Made-with: Cursor * refactor(csharp): write namespace siblings to bindingAugmentations channel Step 4 of the binding-augmentation-channel refactor. The C# `populateNamespaceSiblings` hook is the only consumer that needed to inject cross-file bindings post-finalize, and prior to this change it cloned the (frozen) finalized `BindingRef[]` arrays through a `cloneBindingBucket` helper, then `set()`-back the new array — a workaround for the `Object.freeze` applied by `finalize-algorithm.ts` (issue #1066 root cause). Architecturally that violated `ScopeResolver` Invariant I8 (which permits post-finalize modifications but not in-place mutation of finalized buckets). It also forced read-side consumers to be aware of the workaround. This change: * Switches the three C# write sites to append into `indexes.bindingAugmentations` via `getAugmentationBucket`. The augmentation channel was added in Step 1 and is mutable by contract: inner `BindingRef[]` arrays here are NEVER frozen. * Deletes `cloneBindingBucket` and `getMutableScopeBindings` (workaround helpers no longer needed). * `lookupBindingsAt` (Step 2) merges the two channels transparently for every walker (Step 3), so behavior is unchanged for callers. * Updates the unit test to assert against both channels: finalized bucket stays frozen and untouched, cross-file siblings show up in augmentations only. Renamed the test accordingly. Validation: * `npx tsc --noEmit` clean. * csharp hooks unit + walkers-augmentations unit + csharp integration resolver suite all green (236/236). * Wider `test/unit/scope-resolution test/integration/resolvers` suite: 2507 pass, only 4 pre-existing Swift METHOD_IMPLEMENTS failures remain (unrelated to this work, present on baseline). Refs: issue #1066, ADR-pending binding-augmentation-channel. Made-with: Cursor * feat(scope-resolution): tighten I8 + add validateBindingsImmutability dev guard Step 5 of the binding-augmentation-channel refactor. Captures the new two-channel binding lifecycle in the contract docs and adds a dev-mode runtime validator so a future hook cannot silently drift back into mutating `indexes.bindings`. Contract changes: * `contract/scope-resolver.ts` — rewrote Invariant I8 to describe the two channels (`indexes.bindings` is finalize-output and immutable post-finalize; `indexes.bindingAugmentations` is the append-only post-finalize channel populated by hooks like `populateNamespaceSiblings`). Documented `lookupBindingsAt` as the read-side merger and pointed at the new validator as the enforcement mechanism. * `gitnexus-shared/src/scope-resolution/types.ts` — extended the module-header lifecycle contract to call out `bindingAugmentations` alongside `ReferenceIndex` as the two structures populated after the freeze. Validator: * New `pipeline/validate-bindings-immutability.ts` mirrors the shape of `validateOwnershipParity` (#909): runs only when `NODE_ENV !== 'production' && VALIDATE_SEMANTIC_MODEL !== '0'`, emits via `onWarn`, never throws. Asserts (a) every inner `BindingRef[]` in `indexes.bindings` is `Object.isFrozen`, and (b) every inner array in `indexes.bindingAugmentations` is NOT frozen. * Wired into `pipeline/run.ts` after both `populateNamespaceSiblings` and `propagateImportedReturnTypes`, before `resolveReferenceSites`. One sweep covers the full post-finalize surface. Tests: * `validate-bindings-immutability.test.ts` — 6 cases pinning happy path, both drift directions, multi-violation accumulation, and both production no-op gates. All scope-resolution + csharp resolver tests green (242/242 in the focused run; matches the wider Step 4 baseline). Made-with: Cursor * fix(ingestion): size tree-sitter buffers from UTF-8 bytes Tree-sitter buffer sizing is byte-based, so computing adaptive buffers from JavaScript string length under-sized UTF-8-heavy files. Make getTreeSitterBufferSize accept source text directly and compute Buffer.byteLength internally, then update all parse call sites and max-buffer skip checks to use byte length. Add multibyte cache-miss and cap regressions for C#, Python, TypeScript, and the C# namespace-sibling fallback parse path. Made-with: Cursor * test(scope-resolution): pin augmentation read paths Add focused unit coverage for augmented-only binding reads across the routed walker helpers and imported-return-type propagation path. Clarify I8 wording around lexical Scope.bindings versus post-finalize index channels, and document the intentional local-only behavior of findExportedDef. Also switch the immutability validator tests to Vitest env stubs, document one intentional validator blind spot, and split C# namespace-sibling tests so UTF-8 parsing and augmentation-channel behavior are asserted independently. Made-with: Cursor * test(scope-resolution): avoid slow parser stress fixtures Replace high-cardinality large-file capture fixtures with large padding plus a trailing declaration. This still proves adaptive tree-sitter buffers parse beyond large ASCII and UTF-8-heavy input, without making query matching process thousands of declarations and risking timeouts. Made-with: Cursor * test(scope-resolution): add python and typescript cache-miss resolver regressions Add worker-mode resolver integration coverage mirroring the C# #1066 scenario for Python and TypeScript. Each test builds a temp fixture with large ASCII and UTF-8-heavy source padding, then asserts trailing declarations and call edges still resolve after scope-resolution cache-miss reparsing. Made-with: Cursor * refactor(scope-resolution): gate I8 validator and fast-path namesAtScope Addresses SPARC reviewer feedback on the binding-augmentation channel: - Validator gate is now opt-in outside development. Extract isSemanticModelValidatorEnabled() in utils/env.ts as the single predicate; both validateBindingsImmutability and phase.ts's warn handler share it. Default CLI runs no longer pay the O(binding-buckets) scan, and explicit VALIDATE_SEMANTIC_MODEL=1 now emits warnings even when NODE_ENV is unset. - namesAtScope returns Iterable<string> and zero-allocates when at most one channel is populated (returns Map.keys() directly), only materializing a Set when both channels carry names. The caller-side branching and EMPTY_NAMES escape hatch in propagateImportedReturnTypes are gone -- both helpers handle the empty-augmentation case internally. - C# namespace-siblings header/JSDoc, model JSDoc, I8 contract prose, and the #1066 integration-test header rewritten to say post-finalize fanout appends only to bindingAugmentations; finalized refs come first and win duplicate def.nodeId metadata; local lexical Scope.bindings remains the first-tier shadowing channel. Validator unit-test setup deduplicated via beforeEach and extended with default-CLI no-op + explicit-opt-in cases. Made-with: Cursor	2026-04-26 12:16:09 +01:00
Gergő Magyar	ab077b4c29	feat(ingestion): TypeScript registry-primary scope resolution (Ring 3) (#1050) ... * feat(ingestion): TypeScript registry-primary scope resolution (Ring 3) - Add TypeScript ScopeResolver stack (query/captures/interpret, import decomposition, hooks, arity, merge, receiver binding) and register in SCOPE_RESOLVERS. - Harden shared compound receiver and receiver-bound CALLS pass for map for-of tuple bindings, dotted typeRef shapes, and callable-alias fallbacks. - Flip TypeScript into MIGRATED_LANGUAGES; refresh AGENTS.md and type-resolution-system.md. - Shared finalize-algorithm updates for cross-file scope parity. - Tests: TS scope-resolution unit suite; legacy call-processor suite forces REGISTRY_PRIMARY_TYPESCRIPT=0; registry-primary flag test opts out TS in override scenario. Made-with: Cursor * fix(ingestion): SCC-ordered cross-file return-type propagation + multi-hop re-export resolution Fix CI failures on PR #1050 (TypeScript registry-primary migration) by making `propagateImportedReturnTypes` deterministic via reverse- topological SCC ordering and updating the multi-hop re-export contract to match `followReexportChain` behavior. Why: the legacy pass mirrored an intermediate ref instead of the terminal type when an importer was processed before its source module had its own typeBindings chain-followed (4-file alias chain regression in `ts-simple` fixture: `models.User -> service.user -> app.user` collapsed to `getUser` instead of `User`). Reverse-topological walk of `indexes.sccs` (leaves first) lets every importer see the source's already-followed terminal type in a single pass. Changes: - `imported-return-types.ts`: rewrite to walk SCCs leaves-first, chain- follow the source module's typeBindings BEFORE mirroring, and chain- follow the importer's typeBindings AFTER mirroring. Cyclic SCCs reach a partial fixpoint (no convergence guarantee, ts-circular only asserts no-throw). - `finalize-algorithm.ts`: docstring update on `FinalizeFile.localDefs` to reflect that `followReexportChain` resolves multi-hop re-exports through barrels even when intermediates do not surface the name - surfacing is now a static optimization, not a correctness requirement. - `contract/scope-resolver.ts` Invariant I3: explicitly document the SCC ordering requirement. - `pipeline/run.ts`: split PROF timer into `finalize` and `propagate` so the pass's cost is observable independently. - `ARCHITECTURE.md` Performance notes: describe SCC-ordered propagation. - `imported-return-types.ts`: expand chain-depth comment (2x effective depth from pre/post follow), add multi-ref break rationale, add `ts-simple` motivating-fixture pointer. Tests: - `finalize-algorithm.test.ts`: add 4 cases (3-hop chain, cyclic re-export visited-set guard, wildcard re-export fall-through, multi-source first-match-wins); fix misleading shared nodeId in the thick variant; rename and update the multi-hop test for the new contract (transitiveVia assertion on the thin variant). - `imported-return-types.test.ts` (NEW): unit tests for the SCC pass pinning topological collapse, local-annotation guard, missing-source skip, and cyclic-SCC no-throw. - `cross-file-binding.test.ts` + `ts-deep-alias-chain` fixture (NEW): 5-file integration regression guard for SCC-ordered propagation through 4 module boundaries. Validation: 865 scope-resolution + cross-file tests pass on Windows; typecheck clean across both packages; only pre-existing Swift overload failures remain (verified on PR base commit, environmental). Made-with: Cursor * fix(ingestion): address PR #1050 review findings — side-effect imports, resolve-cache perf, adapter signature Three independent fixes surfaced by the production-readiness review of the TypeScript registry-primary scope-resolution migration (RFC #909 Ring 3). All three pass under both REGISTRY_PRIMARY_TYPESCRIPT=0 and =1. 1. Side-effect imports were silently dropped (correctness regression). The legacy DAG emitted IMPORTS edges for `import './polyfill'` because its tree-sitter query matches `(import_statement source: (string))` regardless of clause. The new registry-primary path returned `[]` from `splitImportStatement()` for clause-less imports, so no ParsedImport / ImportEdge was ever produced — silent file-level edge loss. Add a generic 'side-effect' variant to `ParsedImport` and `ImportEdge['kind']` in `gitnexus-shared`; finalize resolves the target file and pre-finalizes the edge (no `targetDefId`, no `BindingRef`) so the SCC fixpoint loop skips it. The TypeScript provider now emits + interprets the new kind end-to-end. The variant is intentionally generic so other languages (Rust `use foo as _`, Python module-init) can adopt it. 2. Per-import re-derivation in `resolveImportTarget` (perf regression). The TS adapter built `new Set(allFilePaths)` on every call and let `resolveTsImportTarget` re-derive `allFileList` / `normalizedFileList` and discard the `resolveCache`. For a workspace with N files and M imports that's O(N × M) work per pass. Wrap the adapter in a closure that memoizes all five derived values keyed on the orchestrator's `ReadonlySet` identity; reset only when the set reference changes (start of new pass). New cost: O(N + M). 3. Misleading fake `ParsedImport` in the adapter (architecture). The adapter constructed `{ kind: 'named', localName: '_', importedName: '_', targetRaw }` to call `resolveTsImportTarget`, even though only `targetRaw` and the structural-typed context are read. Extract `resolveTsTarget(targetRaw, ctx)` so the adapter has an honest signature; `resolveTsImportTarget` still works for other callers. Also extract `narrowTsContext` for the type narrowing. Tests: - New 4-file fixture `typescript-side-effect-imports` with two side-effect imports + one named import. - New "TypeScript side-effect imports" describe in `test/integration/resolvers/typescript.test.ts` (parity-gated by `ci-scope-parity.yml` — runs under both flag states). - Updated 2 unit tests to expect 1 side-effect ParsedImport and 4 `@import.statement` matches (was 0 / 3). - 785 / 785 TS scope-resolution tests pass under both REGISTRY_PRIMARY_TYPESCRIPT=0 and =1. Made-with: Cursor * fix(scope): address Codex adversarial review findings on PR #1050 Four findings from the Codex adversarial review broke registry-primary TypeScript resolution for common patterns. All four now have unit and integration regression coverage that pass under both `REGISTRY_PRIMARY_TYPESCRIPT=0` (legacy DAG) and the default registry-primary path. [high] tsconfig path aliases dropped: Threaded `tsconfigPaths` through ScopeResolver via a new opaque `resolutionConfig` parameter and a `loadResolutionConfig(repoPath)` hook. The orchestrator (`scopeResolutionPhase` + `runScopeResolution`) loads it once per workspace pass and forwards into every `resolveImportTarget` call. TypeScript resolver now resolves `@/services/user` style imports through the standard resolver's alias branch. [high] TSX parsed with the wrong grammar: `emitTsScopeCaptures` now picks the parser/query by `filePath` (`.tsx` -> TSX grammar) and validates cached trees against the expected grammar via the new exported `tsCachedTreeMatchesGrammar` helper. Stale TS-grammar trees for `.tsx` files no longer leak through the scope query. [medium] Literal dynamic imports never linked: Added `kind: 'dynamic-resolved'` to `ParsedImport` and `ImportEdge`. The decomposer emits a synthetic `@import.literal` capture for string-literal dynamic imports; the interpreter maps that to `dynamic-resolved`; finalize pre-finalizes it as a file-level terminal (same shape as `side-effect`). `import('./feature')` now produces a real IMPORTS edge under the registry-primary path. Legacy DAG keeps its existing behavior — the new integration assertion is gated behind the flag. [medium] Namespace re-exports invisible from barrels: The decomposer now emits TWO captures for `export * as ns from './m'` — the existing `reexport-namespace` import draft AND a synthetic `@declaration.namespace` capture (via `buildNamespaceDeclarationMatch`). The latter creates a Namespace `SymbolDefinition` in the barrel's `localDefs`, so downstream `import { ns } from './barrel'` resolves through `findExportByName`. Regression fixtures under `gitnexus/test/fixtures/lang-resolution/`: - typescript-tsconfig-aliases (`@/` alias) - typescript-tsx-jsx (Button.tsx + App.tsx with JSX) - typescript-dynamic-import (`await import('./feature')`) - typescript-reexport-namespace (`export * as Models from './base'`) Validation: - gitnexus-shared builds clean - gitnexus typecheck clean - 385/385 TS scope-resolution tests pass under both `REGISTRY_PRIMARY_TYPESCRIPT=0` and default Made-with: Cursor * perf(scope): O(1) defById lookup + bounded re-export depth (PR #1050 round 3) Addresses the round-3 PR #1050 reviews (Claude adversarial + xkonjin): both flagged the existing O(N²) `findDefById` linear scan in `materializeBindings` and the unbounded recursion in `followReexportChain` as production-readiness blockers for TypeScript monorepos. Both fixes land alongside their regression tests under both `REGISTRY_PRIMARY_TYPESCRIPT=0` and the default registry-primary path. [high] materializeBindings O(N_files × N_defs × N_edges) → O(N_defs + N_edges): Build a `nodeId → SymbolDefinition` index map once at the top of `materializeBindings` (one O(N_defs) pass), then replace the per-edge `findDefById(files, edge.targetDefId)` linear scan with an O(1) `defById.get(edge.targetDefId)` lookup. Also drop the now-unused `findDefById` helper. At realistic TypeScript monorepo scale (~5k files × ~50 defs/file × ~100k linked import edges) this is the difference between ~25 s and a few ms inside finalize. Regression test in `finalize-algorithm.test.ts` builds 200 leaf files + 1 consumer importing one symbol from each, asserts every binding materializes correctly. [medium] followReexportChain unbounded recursion: The existing `visited` set caps depth at `O(N_files)` but allows recursion proportional to barrel-chain depth, mismatching the explicit "Iterative DFS to avoid stack overflow" policy in `tarjanSccs`. Added a `MAX_REEXPORT_DEPTH = 100` constant and a `depth` parameter to `followReexportChain` (defaults to 0); each recursive call passes `depth + 1` and the function returns `null` when the cap is exceeded. 100 is comfortably above any realistic hand-authored barrel chain (typical depth 1-5; auto-generated barrels rarely exceed 20) while staying well below JS engine call stack limits. Regression test wires a 200-link reexport chain and verifies the crawl terminates cleanly with `linkStatus: 'unresolved'` (no terminal def reachable within the budget). [low] synthesizeInstanceofNarrowings bare-identifier-only limitation: xkonjin's review #4 noted that the LHS narrowing only handles bare identifiers (`if (x instanceof Foo)`), not member expressions (`if (user.address instanceof Address)`). Added a JSDoc note explaining the constraint and pointing readers at field-type resolution as the workaround for member-chain receivers. Validation: - gitnexus-shared builds clean - gitnexus typecheck clean - 413/413 tests pass under both flag states for finalize-algorithm + TS unit + TS integration suites - 972/972 tests pass across full scope-resolution + Python + C# integration smoke (no cross-language regression) Made-with: Cursor * refactor(finalize): replace recursive followReexportChain with SCC-condensed iterative closure The legacy `followReexportChain` walked re-export drafts via mutual recursion guarded by a per-call visited set + a `MAX_REEXPORT_DEPTH` ceiling. Recursion is fragile (call-stack ceiling, no bound on depth that's actually meaningful), so this replaces it with a structurally better algorithm: a precomputed per-file re-export closure built by running Tarjan SCC over the re-export sub-graph and propagating names in reverse-topological order with a bounded intra-SCC fixpoint. Algorithm (`buildReexportClosures` in finalize-algorithm.ts): 1. Sub-graph: build the directed graph of `reexport` + `wildcard` drafts only (regular/namespace/dynamic imports do not contribute). 2. SCC condensation: run the same iterative `tarjanSccs` already used for the file-level import graph; output is in reverse-topo order so out-of-SCC neighbors are always already-finalized. 3. Per-SCC propagation: - Acyclic singleton: one pass populates from neighbors' closures. - Cyclic SCC: bounded fixpoint capped at |SCC|+1 iterations. With first-wins precedence the closure map is monotone, so each name needs at most |SCC| hops to traverse the cycle. Precedence (preserved from the recursive crawl): - Named re-exports take precedence over wildcards. - Within each kind, declaration order wins. Lookup at finalize time becomes O(1) (`lookupReexportedName`), down from O(chain_depth × drafts) per consult and recursive at that. Properties vs the legacy implementation: - Stack-safe by construction; no `MAX_REEXPORT_DEPTH` guard needed. - 1000-hop barrel chains now resolve in full (legacy capped at 100 and surfaced anything deeper as `unresolved`). - Cycles handled structurally via SCC, not via per-call visited set. - Same observable semantics: every existing test passes unchanged. Tests: - Replace the obsolete `MAX_REEXPORT_DEPTH (200-hop chain stops cleanly without stack overflow)` test (which asserted the OLD bug — that deep chains failed to resolve) with a positive 1000-hop test that asserts full resolution + accurate `transitiveVia`. Proves both the recursion is gone AND the closure correctly inherits the leaf def across all hops. - Update commentary on adjacent re-export tests to reference the closure mechanism. - Update `FinalizeFile.localDefs` JSDoc + import-decomposer.ts inline doc to point at `buildReexportClosures` instead of the removed function name. Validation: - gitnexus-shared builds cleanly. - gitnexus typechecks cleanly. - 28/28 finalize-algorithm.test.ts tests pass (incl. new 1000-hop). - 801/801 TypeScript scope-resolution tests pass under default (registry-primary) AND `REGISTRY_PRIMARY_TYPESCRIPT=0` (legacy DAG). - 404/404 Python + C# integration tests pass — no regression in cross-language consumers of the shared `finalize`. Made-with: Cursor * fix(scope): remove non-null assertions from scope resolution Made-with: Cursor * fix(scope): address TypeScript review follow-ups Made-with: Cursor * fix(scope): address TypeScript import review follow-ups Add regression coverage for non-binding import edges and circular TypeScript bindings so PR #1050 review concerns stay visible without changing runtime semantics. Made-with: Cursor	2026-04-26 08:23:08 +01:00
Gergő Magyar	a7b3fa1b81	feat(csharp): migrate C# to registry-primary scope-resolution (Closes #934) (#1019) ... * feat(csharp-scope): unit 1 — scope query + captures orchestrator First slice of the C# scope-resolution migration (issue #934, RFC #909 Ring 3). Closes `Unit 1` of docs/plans/2026-04-21-004-feat-csharp-scope-resolution-plan.md. Adds: - src/core/ingestion/languages/csharp/query.ts — tree-sitter scope query covering compilation_unit, namespace (block + file-scoped), class-like (class/interface/struct/record/enum), method-like (method/constructor/destructor/local_function/operator), property and field declarations, using directives, type bindings (parameter annotations, local variable annotations, constructor inference, invocation alias), and references (free call, member call including null-conditional, constructor call, member write). - src/core/ingestion/languages/csharp/captures.ts — pass-through orchestrator mirroring python/captures.ts. Import decomposition (Unit 2), receiver-type-binding synthesis (Unit 3), and arity metadata synthesis (Unit 5) stub out for future units. - src/core/ingestion/languages/csharp/cache-stats.ts — PROF instrumentation mirror of python/cache-stats.ts. Design notes: - Return-type / field-type / property-type captures deferred. tree-sitter-c-sharp does not expose these under a clean named field that pattern-matches. When Unit 7 parity gate surfaces a gap, add positional patterns or a post-hoc extractor lookup. - object_creation_expression with qualified_name type — the qualified name itself is the reference text; captured as a whole via a dedicated tag so interpretation in later units can split namespace + name. - Null-conditional calls use positional descendant patterns because tree-sitter-c-sharp's member_binding_expression and conditional_access_expression don't expose named fields. Coverage: - 23/23 new unit tests in test/unit/scope-resolution/csharp/csharp-captures.test.ts cover every capture tag. Confirmed against tree-sitter-c-sharp via the probe-script loop during development; grammar drift would surface as a capture-shape assertion failure. - tsc --noEmit clean. No changes to shared infrastructure. Resolver wiring + registration land in Unit 6. * fix(csharp-scope): capture null-conditional receiver + operator decls Adversarial review surfaced two Unit 1 bugs that would silently corrupt the graph once C# is flipped on the scope-resolution path: - `obj?.Save()` only emitted @reference.name, so receiver-bound resolution downgraded to the free-call fallback and could mis-link to an imported `Save`. Capture the conditional_access_expression receiver under @reference.receiver. - `operator_declaration` had @scope.function but no @declaration.method owner, so calls inside operator bodies were attributed to the enclosing class and the operator itself disappeared from method lookup. Capture the operator token as @declaration.name (downstream csharpMethodConfig normalizes to op_Addition etc.). - `conversion_operator_declaration` was missing from both scope and declaration sets. Added with the target type as the name anchor. Arity metadata for overload resolution remains deferred to Unit 5 and gated behind Unit 7's parity flip, as documented in captures.ts. * chore(scope-resolution): drop unused python/scopes.scm sibling The file was documentation-only — the authoritative scope query is the embedded `PYTHON_SCOPE_QUERY` constant in `python/query.ts`. Nothing loaded the `.scm` at runtime, so it drifted from the code. Remove it and update the four doc comments that pointed at it: - language-provider.ts: "scopes.scm query" → "scope query (embedded in each language's query.ts)". - languages/python.ts: capture-vocabulary pointer → query.ts. - python/query.ts header: drop the "edit both together" note. - python/receiver-binding.ts: "keeps the .scm declarative" → "keeps the embedded scope query declarative". - scope/walkers.ts: "Python's scopes.scm" → "Python's scope query". Historical plan docs under docs/plans/ still reference scopes.scm but are frozen artifacts, not living documentation. C# never had a .scm sibling, so no action needed there. * feat(csharp-scope): Unit 2 — import interpret + target resolver Adds the three files Unit 2 of the C# scope-resolution plan calls for: - `import-decomposer.ts` — inspects each `using_directive` node and synthesizes `@import.kind/source/name/alias` markers. Kinds: `namespace` — `using X;` / `using X.Y.Z;` `alias` — `using Alias = X.Y.Z;` (generics stripped) `static` — `using static X.Y;` `global using` maps to namespace (plan's deferred decision); the `global::` qualifier is stripped before emitting. - `interpret.ts` — reads the markers and builds `ParsedImport`. Static using maps to `kind: 'wildcard'` since it brings members into unqualified scope; Unit 4's merge-bindings tiers wildcards lowest. Also provides `interpretCsharpTypeBinding` with nullable/single-arg generic/qualifier stripping so receiver-typed resolution sees the concrete class name. - `import-target.ts` — suffix-match adapter returning a single primary file. Cross-file partial-class aggregation runs later at graph-bridge time (Unit 6). The csproj-based `resolveCSharpImportInternal` stays on the legacy path until Unit 7's parity gate surfaces a gap. - `captures.ts` routes `@import.statement` matches through the decomposer so the interpreter sees the markers it needs. Tests cover every using flavor + resolution edge cases. 38/38 scope- resolution C# unit tests pass; tsc clean. * feat(csharp-scope): Unit 3 — simple hooks (binding/import/receiver) Adds simple-hooks.ts mirroring Python's pattern: - `csharpBindingScopeFor` — delegates to innermost (block scope is already captured by @scope.block in the query). - `csharpImportOwningScope` — binds `using` inside a namespace to that namespace's scope so imports don't leak into sibling namespaces. File-level using delegates to module. Function-body using (not legal C# but possible from malformed input) attaches to the function. - `csharpReceiverBinding` — looks up `this` / `base` in the function scope's type bindings; returns null for statics, free functions, and non-Function scopes. `this` / `base` synthesis itself is deferred to a follow-up (matches Python's receiver-binding.ts pattern). 9 new tests pin delegation semantics. 47/47 C# scope-resolution unit tests pass; tsc clean. * feat(csharp-scope): Unit 4 — mergeBindings (using precedence) Three-tier shadowing, same shape as Python's LEGB merge: 0: local — class members, locals, parameters 1: using — namespace / named / reexport (equal tier; compiler requires explicit qualifier if two using collide) 2: wildcard — `using static X.Y;` static-member imports Within the surviving tier, de-dup by DefId (last-write-wins) so a re-declared `using` cleanly replaces its earlier binding. Explicit interface implementations bind under their qualified name in the extractor layer, so they don't collide with plain simple names here. 7 new tests pin precedence + dedup semantics. 54/54 C# scope-resolution unit tests pass. * feat(csharp-scope): Unit 5 — arity metadata synthesis + compatibility Adversarial review flagged overload narrowing as a blocker for the Unit 7 flip. This lands the declaration-side metadata; callsite-side arity synthesis is a separate gap we'll address if the parity gate surfaces overload misresolution. - `arity-metadata.ts` — reads `csharpMethodConfig.extractParameters` and produces `{ parameterCount, requiredParameterCount, parameterTypes }`. `params` variadic collapses parameterCount to undefined (matches Python's `*args` treatment) and appends a literal `'params'` marker to parameterTypes so the compatibility hook can detect it without re-reading the AST. Default-valued parameters contribute to optionalCount → requiredParameterCount = total − optional. - `arity.ts` — `csharpArityCompatibility(def, callsite)` returns compatible / incompatible / unknown. Mirrors Python's three-verdict shape so the central registry's arity filter works without adapter logic per-verdict. - `captures.ts` — on every @declaration.method / @declaration.constructor / @declaration.function match, synthesize @declaration.parameter-count, @declaration.required-parameter-count, and @declaration.parameter-types captures. Covers method_declaration, constructor_declaration, destructor_declaration, operator_declaration, conversion_operator_declaration, and local_function_statement. 12 new tests: 5 on captures-side synthesis (method + params + types + variadic + constructor + local function), 7 on the compatibility hook. 66/66 C# scope-resolution unit tests pass; tsc clean. * feat(csharp-scope): Unit 6 — wire csharpScopeResolver + register Creates the public barrel (index.ts) and ScopeResolver (scope-resolver.ts) and plumbs them into the provider + registry: - `languages/csharp/index.ts` — re-exports the hook entry points and documents the 8 known limitations of the registry-primary path (csproj-driven namespace resolution, multi-file namespace expansion, type-based overload resolution, nested generics, dynamic, preprocessor branches, cross-file global using, expression-bodied members). - `languages/csharp/scope-resolver.ts` — ScopeResolver shape mirroring Python's. `isSuperReceiver` matches the literal `base` keyword. `fieldFallbackOnMethodLookup: false` since C# is statically typed — the type-binding layer already produces precise owner types; `propagatesReturnTypesAcrossImports: true` since signatures are authoritative. - `languages/csharp.ts` — adds the 9 hook entry points to the provider (emitScopeCaptures, interpretImport, interpretTypeBinding, four simple hooks, mergeBindings, arityCompatibility, resolveImportTarget). - `scope-resolution/pipeline/registry.ts` — registers csharpScopeResolver alongside the Python entry. MIGRATED_LANGUAGES stays at {Python} — the resolver sits idle until Unit 7's parity gate confirms ≥99% fixture parity. 368/368 scope-resolution unit tests pass; tsc clean. * feat(csharp-scope): parity Unit 1 — this/base receiver-binding synthesis Closes 3 parity failures (51 → 48). Target bucket: Category C from the parity plan. Changes: - `languages/csharp/receiver-binding.ts` (new): walks up from a function node to the enclosing class/struct/record/interface, synthesizes `@type-binding.self` captures with boundName `'this'` (and `'base'` when the enclosing type is a class/record with an explicit base_list entry). Skips static methods and interface / struct `base` cases. Anchors to the method's `body` block so the scope-extractor's positionIndex places the binding inside the function scope (not the enclosing class scope). - `languages/csharp/captures.ts`: route `@scope.function` matches through the synth, emitting the receiver captures as separate matches. - `languages/csharp/interpret.ts`: map `@type-binding.self` to `source: 'self'` (parity with Python). - `languages/csharp/query.ts`: explicit patterns for `this.X()`, `base.X()`, and `this.X = ...` / `base.X = ...` assignment writes. `this` and `base` are anonymous tokens in tree-sitter-c-sharp so the existing `expression: (_)` pattern (named-only) didn't match. Tests: - 8 new unit tests for receiver-binding synthesis edge cases (class/struct/record/interface, static, nested, constructor, local function inside method). - Parity: 48 failed | 127 passed (175) under REGISTRY_PRIMARY_CSHARP=1; legacy path 175/175 green. * feat(csharp-scope): parity Unit 2a — foreach + pattern + field captures Closes 11 parity failures (48 → 37). Partial Unit 2 progress. Adds type-binding captures for every shape the parity suite exercises whose resolution path is in-file: - Typed foreach `foreach (User u in xs)` — @type-binding.annotation with bindingName `u` and type `User`. - Var foreach `foreach (var u in xs)` — @type-binding.alias so the generic-stripper unwraps `List<User>` / `Dictionary<K,V>.Values` to the element type at chain-follow time. Matches Python's for-loop alias pattern. - `is` pattern `if (obj is User u)` — @type-binding.annotation with scope narrowing simplified to function scope (matches Python's match-case treatment since we don't emit @scope.block). - `switch_section > declaration_pattern` (`case User u:`) — no case_pattern_switch_label wrapper in tree-sitter-c-sharp. - `recursive_pattern` (`is User { Age: 1 } u` / `case User { ... } u:`) — named binding via type+name fields on the pattern node. - Field declaration `private City _city;` — @type-binding.annotation attached to the class scope for `this._city.X` resolution. - Property declaration `public User Owner { get; set; }` — same. - Assignment rebind `alias = Factory()` / `alias = new User()` — @type-binding.alias / @type-binding.constructor so reassignment propagates type info to later receiver-typed resolution. Closed tests: foreach (3), var foreach Tier 1c (2), is-pattern (1), switch pattern (2), recursive_pattern (3). Remaining 37 include tests that need cross-file same-namespace visibility (field chains, assignment chain, cross-file return-type propagation) — deferred to Unit 5 where the IMPORTS/cross-file work lives. 74/74 scope-resolution unit tests pass; legacy path 175/175 green. * feat(csharp-scope): parity Unit 2b — same-namespace cross-file visibility Closes 3 parity failures (37 → 34). Adds the C#-specific implicit import that has no syntactic counterpart: every type declared in `namespace X` is visible to every other file also declaring `namespace X`, without any `using` directive. Changes: - `scope-resolution/contract/scope-resolver.ts` — new optional hook `populateNamespaceSiblings(parsedFiles, indexes, { fileContents })`. Most languages leave it undefined; Python / TypeScript / Java need explicit imports so there's no analogous pass. - `scope-resolution/pipeline/run.ts` — invoke the hook after `buildWorkspaceResolutionIndex` and before `propagateImportedReturnTypes` so the return-type pass sees cross-file sibling class bindings. - `languages/csharp/namespace-siblings.ts` (new) — groups top-level class-like defs by namespace name (extracted from source via regex since `file_scoped_namespace_declaration` scope range covers only the declaration line, not the rest of the file). Injects sibling classes into each file's Module AND Namespace scope bindings with origin='namespace'. Local declarations shadow cross-file siblings via mergeBindings tier precedence. - `languages/csharp/scope-resolver.ts` — wire the hook. 74/74 scope-resolution unit tests pass; legacy path 175/175 green; 34 parity failures remain (was 37) under REGISTRY_PRIMARY_CSHARP=1. * feat(csharp-scope): parity Unit 2c — alias/await/return-type captures Closes 7 parity failures (34 → 27). Adds the remaining type-binding shapes the parity suite exercises: - `var alias = u;` / `alias = u;` — identifier-to-identifier alias. The resolver's chain-follow walks alias → u → u's declared type. - `var u = svc.GetUser();` — chained method call alias. Anchors on the method_access_expression's `name` field; chain-follow picks up GetUser's return type. - `var u = await Factory();` / `await svc.Get();` — await propagation. Strips the `await_expression` wrapper; interpret layer's `stripGeneric` handles `Task<T>` / `ValueTask<T>` unwrapping. - `public User GetUser() { ... }` — method return-type annotation via `@type-binding.return`. Required for `propagateImportedReturnTypes` to see the return type in later cross-file passes. Covers identifier, generic_name, qualified_name, and nullable_type return shapes. 74/74 scope-resolution unit tests pass; legacy path 175/175 green; 27 parity failures remain under REGISTRY_PRIMARY_CSHARP=1. * feat(csharp-scope): parity Unit 3a — cross-namespace `using` binding Closes 2 parity failures (27 → 25). Extends the namespace-siblings pass to resolve `using X;` directives against known namespace buckets: for each `using` that targets a namespace declared somewhere in the workspace, inject that namespace's classes into the importer's module scope with origin='namespace'. This is the scope-resolution analog of legacy's csproj-driven directory↔namespace mapping. Without it, `new User()` in `Services/UserService.cs` (namespace MyApp.Services) can't see the User class in `Models/User.cs` (namespace MyApp.Models) even with `using MyApp.Models;` — the scope-resolver layer doesn't have csproj metadata to translate the dotted namespace path into a directory lookup. Legacy 175/175 green; 25 parity failures remain. * feat(csharp-scope): parity Unit 3b — constructor CALLS emission Closes 3 parity failures (25 → 22). Adds constructor-form CALLS edge emission + C# 12 primary constructor synthesis. Changes: - `scope-resolution/passes/free-call-fallback.ts`: when a site's callForm === 'constructor', look up the class def (not a callable) and pick its explicit Constructor def via workspaceIndex's memberByOwner — or fall back to the Class def itself for implicit constructors. Matches legacy behavior (targetLabel === 'Constructor' when explicit, 'Class' when implicit). - `scope-resolution/pipeline/run.ts`: pass workspaceIndex to the free-call fallback. - `languages/csharp/captures.ts`: synthesize @declaration.constructor for C# 12 primary constructors — `class User(string name, int age)` / `record Person(string First, string Last)`. The parameter_list is a named child of the class_declaration / record_declaration (not a separate constructor_declaration node). Skip the synthesis when the type already has an explicit constructor to avoid duplicates. Emits @declaration.parameter-count + required-parameter-count alongside. Legacy 175/175 green; 376/376 scope-resolution unit tests pass; 22 parity failures remain. * feat(csharp-scope): parity Unit 3c — static call + default-namespace Closes 2 parity failures (22 → 21). - `receiver-bound-calls.ts`: add Case 5 for class-as-receiver. When `Animal.Classify()` has an identifier receiver that resolves to a Class binding (rather than a variable with a typeBinding), look up the member on the class's MRO chain. Covers C#-style static calls and any type-qualified member access. Python doesn't hit this because `ClassName.method()` is syntactically identical to a free call there. - `namespace-siblings.ts`: treat files with no `namespace X;` declaration as living in the default (empty-name) bucket, so types declared in no-namespace files share cross-file visibility. Required for fixtures without explicit namespaces (e.g. the method-enrichment fixture's Animal/App/Dog classes). Legacy 175/175 green; 21 parity failures remain. * feat(csharp-scope): parity Unit 4 — callsite arity synthesis (infra) Synthesize @reference.arity on every invocation_expression and object_creation_expression by counting `argument` named children of the backing `argument_list`. Wires the capture-to-Callsite pipeline shared extractor already consumes (`scope-extractor.ts:878`). No parity-count movement: the remaining arity-adjacent failures (overload disambiguation, optional-parameter dedup, variadic resolution) need type-based argument inference or member-call dedup, both explicitly deferred in the plan's Known Limitations section. This commit is infrastructure — future work lands on top of it. Legacy 175/175 green; 21 parity failures remain. * feat(csharp-scope): parity Unit 5a — IMPORTS edge + static-using mapping Closes 1 parity failure (21 → 20). Fixes cross-file IMPORTS edge emission for C#: - `languages/csharp/interpret.ts`: map `using static X.Y;` to `kind: 'namespace'` rather than `'wildcard'`. The File→File IMPORTS edge needs a non-wildcard kind to survive finalize's Phase 4 (wildcard-expanded edges drop to empty when the provider doesn't implement `expandsWildcardTo`). Unqualified static-member access is a deferred limitation — covered by the namespace-siblings cross-namespace pass for type lookups, and documented under the module's Known Limitations. - `languages/csharp/import-target.ts`: progressive prefix stripping. `using CrossFile.Models;` in a repo laid out `Models/User.cs` (no `CrossFile/` directory) works because the legacy resolver consults csproj; the scope-resolver tries each suffix of the dotted path against `.cs` files. Also handles `using static NS.Type;` by stripping leading segments until a direct match lands. - `test/unit/scope-resolution/csharp/csharp-imports.test.ts`: update the `using static` test to the new namespace-kind shape. 376/376 scope-resolution unit tests pass; legacy 175/175 green; 20 parity failures remain. * feat(csharp-scope): parity Unit 5b — return-type module hoist + chain fallback Closes 1 parity failure (20 → 19) and lays groundwork for Unit 6. Based on investigation-agent findings, addresses cluster of 7 cross-file + chain tests whose return-type bindings were stuck at Class scope and invisible to the chain-follow and propagation passes. Changes: - `languages/csharp/simple-hooks.ts::csharpBindingScopeFor`: when the declaration is a `@type-binding.return`, hoist the binding all the way to the Module scope. The central extractor's auto-hoist only promotes one level (Function → Class); for C# methods the parent is always a Class, so without this override the return binding never reaches Module where chain-follow and cross-file `propagateImportedReturnTypes` read from. - `scope-resolution/passes/compound-receiver.ts`: when the class-scope typeBindings lookup at `objClass.typeBindings.get( methodName)` misses, walk up from the class scope through the parent chain (→ Module) for a return-type binding. Preserves the existing class-scope fast-path while restoring owner-chain lookup for languages that hoist to Module. Python parity suite stays 204/204 green on both flag paths; legacy C# 175/175 green; 19 C# parity failures remain. * feat(csharp-scope): parity Unit 5c — switch-expr + reasons + ACCESSES 1.0 Closes 4 parity failures (19 → 15). - `languages/csharp/query.ts`: add captures for `switch_expression_arm` with `declaration_pattern` and `recursive_pattern`. C# expression- switch (`obj switch { User u => ..., Repo { Name: "x" } r => ... }`) uses a different AST node from classic `switch_statement`'s `switch_section` — needed separate query patterns. - `scope-resolution/passes/receiver-bound-calls.ts`: replace the self-describing `'scope-resolution: *-receiver'` reason strings (which fail legacy-parity consumer filters) with the legacy convention: `'import-resolved'` when the resolved member lives in a different file, `'global'` otherwise. Mirrors `free-call-fallback.ts`'s existing reason logic. - `scope-resolution/passes/receiver-bound-calls.ts`: pass `confidence: 1.0` to `tryEmitEdge` for write/read ACCESSES edges, matching legacy DAG behavior (default 0.85 was legacy-CALLS). Python parity 204/204 on both flag paths; legacy C# 175/175; 15 C# parity failures remain. * feat(csharp-scope): parity Unit 5d — cross-file typeBinding mirror Closes 3 parity failures (15 → 12). `languages/csharp/namespace-siblings.ts`: extend the pass to mirror method return-type bindings from accessible sibling files' Module scopes into the importer's Module scope. "Accessible" = same-namespace siblings + `using namespace X;` targets. Without this mirror, `var u = svc.GetUser()` in App.cs couldn't chain-follow to User even after Unit 5b's module-scope hoist: `GetUser → User` lived on User.cs's Module scope, which isn't on the ancestor chain of App.cs's function scope, and `propagateImportedReturnTypes` only mirrors across explicit ImportEdge targets (not same-namespace implicit visibility). Closes: var-invocation return type, async/await u.Save (ambient namespace), cross-file return-type propagation (via u.Save / u.GetName in Program.cs). Python parity 204/204 on both flag paths; legacy C# 175/175; 12 C# parity failures remain. * feat(csharp-scope): parity Unit 5e — namespace-prefix bucket matching Closes 2 parity failures (12 → 10). `languages/csharp/namespace-siblings.ts`: when matching accessible namespaces against class buckets, also probe every dotted prefix. `using static CrossFile.Models.UserFactory;` parses into the importer's accessible-namespace set as the full type path, but the matching bucket is keyed on the containing namespace (`CrossFile.Models`). Walking back through the dotted segments ensures the static-using importer sees the containing namespace's sibling files' return-type bindings. Legacy 175/175 green; 10 C# parity failures remain. * feat(csharp-scope): parity Unit 6a — class-like owner extension Closes 1 parity failure (10 → 9). Extends `populateClassOwnedMembers` to recognize Interface / Struct / Record / Enum / Trait as class-like owners, not just Class. The C# scope query collapses interface_declaration / struct_declaration / record_declaration / enum_declaration to @scope.class (they share body-scope semantics), but the declaration-side tags produce defs of type Interface / Struct / Record / Enum. `populateClassOwnedMembers` previously only looked for Class-typed defs in class scopes, so interface members (including C# 8+ default methods) never got ownerIds — making them invisible to `findOwnedMember` via `memberByOwner`. With this fix, `user.Validate()` on a variable typed as `IValidator` resolves correctly: receiver-bound-calls Case 4 finds IValidator via findClassBindingInScope (which already accepted Interface), walks the chain, and findOwnedMember locates Validate now that the interface default has a proper ownerId. Legacy C# 175/175 green; Python parity 204/204 on both flag paths; 9 C# parity failures remain. * feat(csharp-scope): parity Unit 6b — member-call dedup + handled-site fix Closes 1 parity failure (9 → 8). Adds the missing legacy-parity behavior: collapse multiple member-call sites from the same caller to the same target into one CALLS edge. Changes: - `scope-resolution/contract/scope-resolver.ts`: new optional `collapseMemberCallsByCallerTarget` flag. Default false (preserves the per-site invariant); C# sets it true. - `scope-resolution/graph-bridge/edges.ts`: dedup key drops `line:col` when `collapseByCallerTarget` is on AND edgeType is `CALLS` (ACCESSES writes keep per-site granularity). - `scope-resolution/passes/receiver-bound-calls.ts`: plumbs `collapse` through every `tryEmitEdge` call, and crucially marks `handledSites.add(siteKey)` whenever a resolved def was found — not only when the edge was freshly emitted. Otherwise the site leaked through to `emitReferencesViaLookup` which re-emitted a per-site edge, defeating the collapse. - `languages/csharp/scope-resolver.ts`: opt in to the collapse. Python parity 204/204 on both flag paths; legacy C# 175/175 green; 8 C# parity failures remain. * feat(csharp-scope): parity Unit 6c — Dictionary.Values / .Keys unwrap Closes 2 parity failures (8 → 6). Dictionary<K,V>.Values in a foreach binds the element to V; .Keys binds to K. Without this, `foreach (var user in data.Values)` where `data: Dictionary<string, User>` couldn't propagate user's type to User, and `user.Save()` stayed unresolved. Changes: - `languages/csharp/interpret.ts`: don't strip the qualifier when the final dotted segment is a known collection accessor (`Values` / `Keys`). Preserves the dotted form so downstream resolvers can unwrap the receiver's generic type based on the suffix. - `scope-resolution/passes/compound-receiver.ts`: new `extractDictionaryArgs` helper splits `Dictionary<K, V>` at the top-level comma. In the dotted-access walk, detect trailing `.Values` / `.Keys` and return V/K via findClassBindingInScope instead of the normal class-walk (Dictionary itself isn't a local class def). - Handles nested cases: `this.data.Values` walks `this.data` recursively (resolving `data` as a field on `this`'s class) before applying the unwrap. - `scope-resolution/passes/receiver-bound-calls.ts` Case 3b: when the typeRef's trailing segment is an accessor, pass the raw dotted path to `resolveCompoundReceiverClass` without appending `()` — the extra parens would misroute to the call-expression branch. Python parity 204/204 on both flag paths; legacy C# 175/175 green; 6 C# parity failures remain. * feat(csharp-scope): parity Unit 6d — using-static member injection Closes 2 parity failures (6 → 4). `using static X.Y.Z;` now injects every public static method of class Z into the importer's module scope, so `Record("hi")` (without `Logger.` qualifier) resolves to `Logger.Record` as a free call. `languages/csharp/namespace-siblings.ts`: regex-scan each file's source for `using static X.Y.Z;` directives. For each, look up the class Z in the `X.Y` namespace bucket, walk its owning file's localDefs for method/function members with `ownerId === Z.nodeId`, and inject them as `origin: 'import'` bindings in the importer's module-scope finalized bindings map. `findCallableBindingInScope` then picks them up via its imported-bindings check. Closes: variadic `Record(params string[])` + heritage arity narrowing `WriteAudit`. Python parity 204/204 on both flag paths; legacy C# 175/175 green; 4 C# parity failures remain (interface-dispatch pass + type-based overload disambiguation). * feat(csharp-scope): parity Unit 6e — overload disambig + interface dispatch + FLAG FLIP Closes the final 4 parity failures (4 → 0). C# now runs the registry-primary scope-resolution path by default — added to MIGRATED_LANGUAGES. Changes: - `scope-resolution/scope/walkers.ts`: was already extended in Unit 6a to recognize Interface/Struct/Record/Enum as class-like owners (interface default methods get ownerIds). - `scope-resolution/passes/receiver-bound-calls.ts`: build IMPLEMENTS edge index → emit secondary `interface-dispatch` CALLS edges to every implementor's same-named member when the primary receiver-typed edge targets an Interface method (closes heritage CreateUser CALLS-count test). - `scope-resolution/passes/receiver-bound-calls.ts`: new `pickOverload` helper narrows multi-valued `membersByOwner.get(owner).get(name)` candidates by arity then argument types. Replaces the first-seen `findOwnedMember` lookup in Case 4 so receiver-typed overloaded calls pick the right def. - `scope-resolution/passes/free-call-fallback.ts`: new `pickImplicitThisOverload` walks up to the enclosing class scope and applies the same arity + argument-type narrowing for free calls inside a class body (`Lookup("alice")` → `Lookup(string)`). - `scope-resolution/workspace-index.ts`: new `membersByOwner` multi-valued index (`Map<owner, Map<name, Def[]>>`) preserves every overload alongside the existing first-seen `memberByOwner`. - `scope-resolution/graph-bridge/node-lookup.ts` + `scope-resolution/graph-bridge/ids.ts`: include parameter-types suffix in the qualified lookup key for Method nodes. Legacy parse-phase encodes the type tag into the node id (`Method:f.cs: UserService.Lookup#1~int`); without this two same-arity overloads collapsed to one lookup entry and routed to the wrong graph node. - `scope-resolution/contract/scope-resolver.ts`: new `collapseMemberCallsByCallerTarget` opt-in flag (was added in Unit 6b for member-call dedup; documented here). - `gitnexus-shared/src/scope-resolution/reference-site.ts`: new `argumentTypes` field carrying inferred per-arg types. - `scope-extractor.ts`: read @reference.parameter-types capture into `site.argumentTypes` and add it + the declaration-arity tags to KNOWN_SUB_TAGS so the anchor-detection picks the right anchor. - `languages/csharp/captures.ts`: synthesize @reference.parameter-types by inferring arg types from literal AST nodes (integer_literal → 'int', string_literal → 'string', constructor_expression → type-name, etc). - `languages/csharp/scope-resolver.ts`: opt in to `collapseMemberCallsByCallerTarget`. - `registry-primary-flag.ts`: **add CSharp to MIGRATED_LANGUAGES**. Final state: - C# parity: 175/175 green on flag-on AND flag-off. - Python parity: 204/204 green on both flag paths (no regression). - TypeScript clean. 51 → 0 failures across 18 commits on `feat/csharp-scope-resolution`. * refactor(scope-resolution): extract language-specific accessor unwrap to provider hook Optimizer pass: move C# Dictionary-family `.Values`/`.Keys` handling out of the shared `compound-receiver.ts` (where it had hardcoded regex + accessor names) into a provider-level `unwrapCollectionAccessor` hook. The shared pass now takes an arbitrary language-specific unwrap function; C# supplies its Dictionary implementation in `languages/csharp/accessor-unwrap.ts`. Related cleanup in `receiver-bound-calls.ts` Case 3b: replace the hardcoded `tail === 'Values' || tail === 'Keys'` accessor check with a try-dotted-walk-first / fall-back-to-call-form strategy. This removes the last C#-specific branch in the shared pass and makes the logic generalize cleanly to other languages that use property-style accessors for collection views (Kotlin `.size`, future languages). Changes: - `scope-resolution/contract/scope-resolver.ts`: new optional `unwrapCollectionAccessor(receiverType, accessor) => string | undefined` hook. Documented as language-specific with examples. - `scope-resolution/passes/compound-receiver.ts`: delete `extractDictionaryArgs`, accept `unwrapCollectionAccessor` via options, call it for trailing accessor segments. - `scope-resolution/passes/receiver-bound-calls.ts`: plumb the hook through to `resolveCompoundReceiverClass`, remove the C#-hardcoded Case 3b accessor check. - `languages/csharp/accessor-unwrap.ts` (new): C# Dictionary-family regex + element-type extraction. - `languages/csharp/scope-resolver.ts`: opt in. Audit outcome: everything else added across the 19 C# migration commits is either correctly scoped to `languages/csharp/` (query, captures, namespace-siblings, receiver-binding, interpret, imports) or correctly generic in shared paths (argumentTypes field, collapseMemberCallsByCallerTarget flag, overload narrowing via parameterTypes, interface-dispatch via IMPLEMENTS edges, class-like owner extension for Interface/Struct/Record/Enum, type-tagged node IDs, module-scope return-type lookup fallback). 175/175 C# green on both flag paths; 204/204 Python green on both flag paths; TypeScript clean. * refactor(scope-resolution): gate module-scope typeBinding walk-up on hook Add optional `hoistTypeBindingsToModule` to the ScopeResolver contract and gate the Module-scope walk-up in `resolveCompoundReceiverClass` on it. Only providers that hoist method return-type bindings to Module scope (C#) opt in; Python and other providers no longer traverse that fallback path. Closes the architectural leak flagged in the production-readiness review: the walk-up was unconditional and therefore widened Python's code path despite existing only for C#. No behavior change for C# (hook=true restores the prior lookup). No behavior change for Python (hook undefined = walk-up skipped, matching pre-PR behavior). Verified: - npx tsc --noEmit clean - C# unit suite 74/74 passing - C# + Python integration 388/388 passing * refactor(csharp-scope): remove as-unknown-as double casts in scope-resolver Tighten three type boundaries that were previously papered over with `as unknown as` casts: * `CsharpResolveContext.allFilePaths`: `Set<string>` → `ReadonlySet<string>`. The orchestrator only hands out a read-only view; drop the widening cast at the resolver-adapter site. * `resolveCsharpImportTarget`: call passes the narrow context directly. `WorkspaceIndex` is `unknown` in the shared contract, so the `as unknown as WorkspaceIndex` cast was gratuitous — structural assignability covers it. * `csharpMergeBindings`: drop unused `_scope: Scope` parameter. The implementation never read it; the cast chain in `scope-resolver.ts` existed only to satisfy an unused slot. LanguageProvider.mergeBindings now wraps with a tiny arrow adapter; ScopeResolver.mergeBindings passes through directly. No runtime behavior change. `grep 'as unknown as' csharp/scope-resolver.ts` returns zero matches. Verified: - npx tsc --noEmit clean - C# unit + integration 462/462 passing (incl. Python integration) * test(csharp-scope): integration fixtures for Units 6c/6d/6e runtime behavior Close the integration-coverage gap flagged in the production-readiness review. Units 6c (collection-accessor unwrap), 6d (using-static member injection), and 6e (overload disambig + interface dispatch) previously had only hook-level unit tests; the end-to-end wiring was exercised only by the parity harness. Three minimal fixtures + four new it() blocks: * csharp-collection-accessor — RenderAll iterates Dictionary<string, Widget>.Values and calls .Render(); asserts the CALLS edge lands on Widget.Render. * csharp-using-static — `using static Helpers.MathUtils;` makes Square(int) a free-callable in the consumer; asserts the CALLS edge lands on MathUtils.Square. * csharp-overload-interface — three assertions: 1. Run → Log binds to the 2-arg overload only (arity narrowing); verified via target Method node's parameterTypes.length === 2. 2. Run → Greet emits one primary edge to IGreeter.Greet plus two reason='interface-dispatch' siblings to En/FrGreeter.Greet. 3. Interface-dispatch fan-out excludes the primary target. Verified: - csharp integration 189/189 passing * docs(scope-resolution): de-c#-ify optional-hook doc-comments on contract Rewrite the doc-comments on four optional hooks so they describe the behavior and when a provider would enable it, rather than naming C# as the sole consumer. Hook names were already generic — only the comments had baked in one-language framing, which risked discouraging future reuse. Affected hooks: * unwrapCollectionAccessor * collapseMemberCallsByCallerTarget * populateNamespaceSiblings * hoistTypeBindingsToModule Language-specific rationale stays where it belongs — next to the hook assignment in `languages/csharp/scope-resolver.ts`. Zero-match grep for `C#|csharp|CSharp` in the contract file confirms the separation. No code change. * docs(csharp-scope): justify regex-based namespace-sibling detection Record why `namespace-siblings.ts` uses regex over AST walks and enumerate the known misses so the next reader has ground to stand on: * `global using static X.Y;` — no plain `using static` token. * Aliased `using static X = Y.Z;` — `=` breaks the pattern. * Attributed namespace declarations between `]` and `{`. * Multi-namespace files — first-wins attribution. * Preprocessor-gated namespace declarations — textual branch only. Rationale: the pass is file-path-driven and the tree-sitter tree isn't available at its call site (the orchestrator feeds raw fileContents); re-parsing to count namespaces would cost more than the regex walk. Refactor to AST-driven detection is deferred to a separate PR. Mirrored the known-miss list into `csharp/index.ts`'s limitations ledger so the operator-visible surface and the in-code justification stay in sync. No code change. * refactor(csharp-scope): AST-driven namespace detection with treeCache reuse Replace regex-over-source-content with tree-sitter AST walks in namespace-siblings.ts; thread the orchestrator's treeCache through the populateNamespaceSiblings hook so the pass reuses the same parse trees `extractParsedFile` already consumed (single-source-of-truth for the AST — no double-parse). Behavior gains (no longer "known misses"): * `global using static X.Y;` is now detected. * Aliased `using static X = Y.Z;` is now detected. * Attributed namespace declarations (`[attr] namespace X`) parse correctly because tree-sitter sees them as one node. * Preprocessor-gated namespace declarations parse via the grammar. Contract change (additive, optional): * `populateNamespaceSiblings` ctx now carries an optional `treeCache?: { get(filePath): unknown }`. Existing providers that don't set it on `RunScopeResolutionInput` see undefined, and the hook falls back to a fresh parse (current behavior preserved on cache miss). Limitation ledger updated in csharp/index.ts: the AST-based detection removes 4 of the 5 prior known misses; only "first-wins multi-namespace file attribution" remains. Verified: - npx tsc --noEmit clean - C# + Python integration 393/393 passing * refactor(python-scope): remove as-unknown-as casts in scope-resolver (mirrors Unit 2) Replay the C# scope-resolver cleanup on the Python side so both providers share a single clean pattern: * Drop `ws as unknown as WorkspaceIndex` — `WorkspaceIndex` is `unknown` in the shared contract, so the narrow context assigns structurally without a cast. * Drop `{ id: scopeId } as unknown as Scope` — `pythonMergeBindings` never read the scope (the parameter was `_scope`), so the stub was a type-only ghost. Signature is now `(bindings)` and the LanguageProvider slot wraps with an arrow adapter. * Drop `allFilePaths as Set<string>` — the orchestrator hands a `ReadonlySet<string>`; we copy it into a `Set` at the resolver adapter so the legacy downstream `resolvePythonImportInternal` chain (typed for mutable `Set<string>`) keeps working. The copy is O(N) once per import, trivial cost. Left intact on purpose: the `(callsite, def) → (def, callsite)` arrow wrapper on `arityCompatibility`. That's a documented shape difference between `LanguageProvider.arityCompatibility(def, callsite)` and `ScopeResolver.arityCompatibility(callsite, def)`; both providers (Python + C#) carry the same wrapper. Reconciling is a separate refactor across both contracts. No runtime behavior change. Verified: - npx tsc --noEmit clean - Python + C# unit + integration suites 529/529 passing * docs(scope-resolution): document I1-I8 invariants, source-of-truth, and same-graph guarantee Promote contract knowledge that was implicit in code into the canonical docs so future migrations and the next reviewer don't have to reverse-engineer it. contract/scope-resolver.ts: * Migration cookbook lists every optional hook (was: only the two booleans), with one-line guidance per hook including when to enable `hoistTypeBindingsToModule`. * Contract Invariants I1-I7 are now spelled out in full (was: only I1/I3/I5 summarized with a pointer to a plan file). Added new I8 "post-finalize hooks may mutate Scope.typeBindings and indexes.bindings; consumers must not freeze or snapshot before all post-finalize hooks have run". * New "Semantic-model source of truth" section: ParsedFile is the single semantic model; passes that need AST-level facts must reuse the orchestrator's treeCache rather than re-parse. * New "Same-graph guarantee" section: legacy DAG and scope-resolution emit indistinguishable edges (node identity, edge vocabulary, confidence). CI parity workflow enforces this. gitnexus-shared/src/scope-resolution/parsed-file.ts: * Added "Source-of-truth invariant" pointer paragraph. ARCHITECTURE.md (Coexistence section): * Updated migrated-language list (Python + C#). * Added "Same-graph guarantee" subsection. * Added "Semantic-model source of truth" subsection. * Filled in the ScopeResolver hook table with the five optional hooks that landed in this branch (unwrapCollectionAccessor, collapseMemberCallsByCallerTarget, populateNamespaceSiblings, hoistTypeBindingsToModule, fieldFallbackOnMethodLookup). * Added C# rows to the code-references table. Verified: - npx tsc --noEmit clean - C# + Python integration 393/393 passing * refactor(scope-resolution): consume SemanticModel as single authoritative store Unify scope-resolution and legacy parse into one symbol index per the industry pattern (Roslyn / tsc / rust-analyzer). Scope-resolution passes now consume `SemanticModel.methods` / `SemanticModel.fields` / `SemanticModel.symbols` for all symbol-keyed lookups. The legacy DAG already read from these; the drift — two parallel owner-keyed indexes populated by two writers with divergent ownerId semantics — is closed. Changes: * `MethodRegistry.lookupAllByOwner(owner, name)`: new API returning every overload without arity narrowing. Powers `findOwnedMember` / `pickOverload`. * `pipeline/run.ts` reconciliation pass: after `provider.populateOwners(parsed)`, iterate `parsed.localDefs[i]` and register methods/fields into the SemanticModel under the corrected ownerId. Idempotent — skips defs already present under `(ownerId, simple)` by nodeId, so unmigrated languages whose legacy extractor already set ownerId (C#) don't double-register. Closes the Python gap where class-body methods were invisible to `MethodRegistry` because the legacy Python method extractor couldn't resolve `enclosingClassId` at parse time. * `WorkspaceResolutionIndex` slimmed to Scope-valued maps only (`classScopeByDefId`, `moduleScopeByFile`). Dropped `memberByOwner`, `membersByOwner`, `defsByFileAndName`, `callablesBySimpleName` — all symbol-keyed duplicates of SemanticModel indexes. * Walker helpers now consume SemanticModel: - `findOwnedMember(owner, name, model)` → methods then fields fallback (ACCESSES writes target Property/Variable defs too). - `findExportedDefByName` fallback walks every Module scope's `origin === 'local'` bindings via `index.moduleScopeByFile` (preserves the module-export-visibility filter that SymbolTable.fileIndex can't cheaply encode). - `findExportedDef` reads `moduleScope.bindings` directly. * `pickOverload` in receiver-bound-calls.ts falls back to `model.fields.lookupFieldByOwner` when method lookup returns empty, fixing ACCESSES write edges that receive a Property target. * `phase.ts` threads `resolutionContext.model` into `RunScopeResolutionInput`. Boundary rule, enforced by file placement: - symbol-indexed lookups (key = nodeId / name / filePath) → `SemanticModel` - Scope-valued lookups (value = `Scope`) → `WorkspaceResolutionIndex` Research synthesized from web-researcher + Explore + best-practices + system-architect agents; canonical references: Roslyn Overview, rust-analyzer architecture, stack-graphs paper. Verified: - npx tsc --noEmit clean - C# + Python integration 393/393 passing * docs(scope-resolution): refresh comments after dropping duplicated indexes Replace references to the now-deleted `memberByOwner` / `callablesBySimpleName` index fields with comments that describe the actual lookup path (`SemanticModel` registries + scope-tied module bindings). Pure doc cleanup; no behavior change. * feat(scope-resolution): extract reconciliation pass + add parity validator Extract the SemanticModel reconciliation pass (previously inline in `pipeline/run.ts`) into a dedicated module with: * `reconcileOwnership(parsedFiles, model)` — pure function returning stats (methodsRegistered / fieldsRegistered / skippedAlreadyPresent). Idempotent; safe to re-run. * `validateOwnershipParity(parsedFiles, model, onWarn)` — dev-mode runtime validator for Contract Invariant I9. Walks every def with an `ownerId` and asserts it is reachable via `model.methods.lookupAllByOwner` or `model.fields.lookupFieldByOwner`. Soft-fails via `onWarn`; never throws. Validator is gated on both `NODE_ENV !== 'production'` and `VALIDATE_SEMANTIC_MODEL !== '0'` so production incurs zero cost but development surfaces any drift between `parsed.localDefs` ownership and the registries. 12 new unit tests cover: * happy path: method, property, Variable registration * edge case: defs without ownerId are skipped * idempotency: second call is a no-op * coexistence: defs the legacy extractor already registered (via `model.symbols.add`) are skipped on reconcile * overloads: multiple methods under the same (owner, name) * validator: no warnings after reconciliation * validator: warns on drift * validator: no-op under NODE_ENV=production * validator: no-op when VALIDATE_SEMANTIC_MODEL=0 * validator: warns on missing Property same as missing Method Verified: - npx tsc --noEmit clean - reconcile-ownership unit tests 12/12 passing - C# + Python integration 393/393 passing * refactor(scope-resolution): narrow handles + tighten required params Two small hygiene fixes that fell out of the unified-model work: * Introduce `readonlyModel: SemanticModel` in `runScopeResolution` immediately after reconciliation so the write/read phase boundary is explicit at the code level. Downstream passes (receiver-bound, free-call) receive the narrowed `SemanticModel` rather than the `MutableSemanticModel` that only the reconciliation pass needs. The type system now rejects accidental writes in the read phase. * Make `emitFreeCallFallback`'s `workspaceIndex` parameter required. It's now always passed (every caller threads it through), and the `workspaceIndex?` guard was dead code. Also drops the `| undefined` branch from `pickConstructorOrClass` which no caller can hit. No behavior change. * docs(semantic-model): document unified single-source-of-truth invariant (I9) Add Contract Invariant I9 to the ScopeResolver contract and write the single-source-of-truth + write/read phase contract into both the SemanticModel file-head and ARCHITECTURE.md. Three landing points so the rule is reachable from every entry: * contract/scope-resolver.ts — new I9 entry in the Contract Invariants list: scope-resolution passes consult SemanticModel exclusively for symbol-keyed lookups; WorkspaceResolutionIndex is reserved for Scope-valued maps. Documents the two-phase write (legacy parse + reconcileOwnership) and the narrowed-handle read posture. Calls out the reconciliation shim as transitional. * model/semantic-model.ts — new "Single-source-of-truth invariant" and "Write / read phase contract" sections in the file-head. Three ordered write phases (parse → reconcile → attachScopeIndexes), then frozen for readers. * ARCHITECTURE.md § "Semantic-model source of truth" — expanded subsection covering both invariants (ParsedFile = AST truth, SemanticModel = symbol truth), the write/read phase diagram, and the reconciliation-shim rationale. No code change. * test(scope-resolution): rewrite workspace-index test for slimmed index The test file previously asserted on \`defsByFileAndName\`, \`callablesBySimpleName\`, and \`memberByOwner\` — fields removed when symbol-keyed lookups moved to \`SemanticModel\`. Rewrite so the same invariants are asserted via the authoritative consumers: * New WorkspaceResolutionIndex shape test (scope-only maps). * \`findExportedDef\` module-export visibility tests: - keeps top-level class and function defs. - excludes class-body Variable defs (MAX_USERS = 100). - excludes class methods from module-export lookup. * \`findExportedDefByName\` fallback excludes class methods when a same-named module function exists. * \`findOwnedMember\` via the reconciled SemanticModel finds Python class methods after populateOwners + reconcileOwnership. Total assertions preserved: every invariant from the old test file is still pinned; the assertion surface shifted from the index shape to the walker helpers. Verified: - workspace-index.test.ts 8/8 passing * fix(tests): update registry-primary-flag test for C# migration The "returns exactly the flipped languages" case expected `enabled.size === 1` after toggling Python off and Go on. After the C# migration lands C# in MIGRATED_LANGUAGES, C# is default-on too — so the size is now 2 (Go + C#) unless C# is also opted out. Turn off C# alongside Python in the test setup. Added a comment noting that future migrations must add their REGISTRY_PRIMARY_<LANG>='false' line here. * refactor(scope-resolution): address PR #1019 review findings Resolves all 5 findings from the automated review on feat/csharp-scope-resolution. Shared ingestion code stays language-agnostic; C# (and every class-like language) benefits. F1 [high] Broaden class-like predicate Hoist `isClassLike` in `scope/walkers.ts` to an exported top-level helper covering Class | Interface | Struct | Record | Enum | Trait. Use it in `findClassBindingInScope`, `findEnclosingClassDef`, and `buildWorkspaceResolutionIndex` so C# records, structs, interfaces, and enums participate in scope chains and receiver binding the same way Python classes do. F2 [medium] Remove stale comment in csharp simple-hooks `csharpReceiverBinding`'s doc claimed this/base synthesis was "planned for a follow-up"; synthesis has been implemented in receiver-binding.ts since the migration landed. Rewrite the doc to describe the actual behavior (non-null TypeRef on instance-method bodies, null on static/free functions). F3 [medium] O(1) reverse lookup for classScopeId -> classDefId Add `classScopeIdToDefId: ReadonlyMap<ScopeId, string>` to `WorkspaceResolutionIndex`, populated as the inverse of `classScopeByDefId`. Replace the O(C) linear scan in `pickImplicitThisOverload` (free-call-fallback.ts) with an O(1) `Map.get` — turns per-site reverse resolution from linear in class count to constant time for every free call. F4 [low] Extract narrowOverloadCandidates shared utility New `passes/overload-narrowing.ts` centralizes the arity + argument- type narrowing previously duplicated across `pickOverload` (receiver-bound-calls.ts) and `pickImplicitThisOverload` (free-call-fallback.ts). Both callsites now share identical narrowing semantics; variadic `params T` handling is preserved. Return type is `readonly SymbolDefinition[]` with no defensive spreads (allocations saved on the hot path). F5 [low] Merge unreachable Case 5 into Case 2 `Case 5` in `receiver-bound-calls.ts` was dead code — `Case 2` pre-empted it for every static/class-name receiver. Delete Case 5 and lift its kind-aware read/write ACCESSES reason/confidence logic into Case 2 so static-style member access (e.g. `Interface.Member`, `TypeName.StaticMember`) gets the correct edge metadata. Tests - New unit tests for `narrowOverloadCandidates` covering empty input, arity filtering, variadic params, type narrowing, and fallback semantics. - New unit tests for `classScopeIdToDefId` verifying inverse invariant and empty index behavior. - New C# integration fixtures and tests: * csharp-record-base — record inheritance + `base.Save()` * csharp-struct-overloads — struct with implicit-this overload narrowing (pinned exact edge count under registry-primary) * csharp-interface-receiver-static — interface-qualified static- style call exercises the merged Case 2. - Full runs green: * scope-resolution unit: 406/406 * csharp integration (registry-primary): 197/197 * csharp integration (legacy DAG): 197/197 * python integration (regression guard): 204/204 Chore - Add `.context/` to root `.gitignore` to prevent agent scratch files from being committed. Made-with: Cursor * test(csharp-scope-resolution): address adversarial review follow-ups on PR #1019 Applies the three actionable follow-ups from the post-commit adversarial review of 5a1bce7f against DoD.md. No runtime code changes. - [medium] Strengthen bounds-only assertion in the struct-overloads suite: `methods.length` is now pinned to `toBe(2)` and the arity list to `toEqual([1, 2])`. Fixture `csharp-struct-overloads/src/Calc.cs` declares exactly two `Add` methods, so a regression that adds, drops, or merges an overload will now fail the test instead of silently passing a `>= 2` gate. - [low] Pin the merged Case 2 kind-aware branch (receiver-bound-calls.ts lines 257-289) with a dedicated fixture and three new assertions: `csharp-class-static-field-access/src/Counters.cs` exercises `ClassName.Field = value` where the receiver resolves via `findClassBindingInScope` (no typeBinding on `Counters`). The test verifies (a) two distinct ACCESSES writes are emitted from a single method (per-site dedup from graph-bridge/edges.ts:80-87), (b) `reason === 'write'`, (c) `confidence === 1.0`, and (d) no spurious CALLS edges are produced for the same sites. This is the semantic upgrade lifted from the deleted Case 5; without a pinning test a future revert of the kind-aware branch would silently drop back to `import-resolved`/`global` at 0.85 for the same sites. Read-side coverage is intentionally not asserted because the C# tree-sitter query currently emits only `write.member` captures (languages/csharp/query.ts:485-501) — a read counterpart would have no reference site today and would give a false sense of coverage. - [info] Left the `?? overloads[0]` fallback in place at receiver-bound-calls.ts:450 unchanged. With the package's current tsconfig (strict: false, no noUncheckedIndexedAccess) both the defensive fallback and a `candidates[0]!` assertion type-check identically, so the finding has no production-readiness impact. Keeping the fallback minimizes churn. Validation (local, Windows PowerShell): - `npx prettier --check test/integration/resolvers/csharp.test.ts` -> clean - `npx tsc --noEmit` -> 0 errors - `REGISTRY_PRIMARY_CSHARP=1 npx vitest run test/integration/resolvers/csharp.test.ts` -> 200/200 - `REGISTRY_PRIMARY_CSHARP=0 npx vitest run test/integration/resolvers/csharp.test.ts` -> 200/200 - `npx vitest run test/integration/resolvers/python.test.ts` -> 204/204 - `npm test` (full gitnexus suite) -> 6967 passed, 6 pre-existing failures (4x Swift overload/dedup, 1x Swift method-extraction unit, 1x Swift type-env unit, 1x LadybugDB lockfile on Windows). All six reproduce on 5a1bce7f with these follow-up changes stashed, confirming they are environment/baseline failures unrelated to this work. Swift is not in MIGRATED_LANGUAGES so the merged Case 2 path cannot affect it. Refs: PR #1019 Made-with: Cursor * refactor(scope-resolution): address full-PR review findings on PR #1019 Resolves the two remaining findings from the code-review-swarm full-PR sweep (verdict: production-ready with minor follow-ups). [low] Complete the csharp/index.ts module-layout JSDoc. `languages/csharp/index.ts` is the discovery surface for the C# scope- resolution module decomposition (per AGENTS.md). The "Module layout" list silently omitted three load-bearing modules — `accessor-unwrap.ts` (`.Values`/`.Keys` receiver-type unwrap), `namespace-siblings.ts` (AST-driven cross-file implicit-namespace visibility), and `receiver-binding.ts` (`this`/`base` type-binding synthesis). Extended the JSDoc list so the "single-concern" decomposition story is honest and the next contributor can locate the right file without grep. No behavior change. [info] Replace the non-standard `'scope-resolution: super-receiver'` edge reason with the canonical `'global'` tier. `passes/receiver-bound-calls.ts` emitted a non-canonical reason string for the super/base branch, which falls outside the vocabulary declared in ARCHITECTURE.md § Scope-Resolution Pipeline (`'import-resolved' | 'global' | 'local-call' | 'same-file' | 'interface-dispatch' | 'read' | 'write'`). Super/base calls resolve through the MRO chain rather than through import directives, so the correct canonical tier is `'global'` (same classification the legacy DAG's `toResolveResult` applies to non-same-file, non-import-scoped resolutions). Locked the contract with `rel.reason === 'global'` assertions on the existing `csharp-super-resolution` and `csharp-generic-parent- resolution` suites, both of which go through the super-branch MRO path. The `csharp-record-base` suite intentionally does not pin a reason (records don't currently emit EXTENDS edges, so the MRO lookup misses and the edge is produced by the reference-index fallback instead of the super-branch). A code comment flags the pre-existing Python-legacy asymmetry (Python legacy tier classifier marks `super()` as `'import-resolved'` because the ancestor arrives via an `import` statement); closing that gap requires realigning the legacy tier classifier and is tracked separately. Validation: - `npx tsc --noEmit` passes. - `npx prettier --check` clean on all four touched files. - `test/integration/resolvers/csharp.test.ts` — 200/200 under both `REGISTRY_PRIMARY_CSHARP=0` (legacy DAG) and `REGISTRY_PRIMARY_CSHARP=1` (registry-primary), preserving same-graph parity on the super branch. - `test/integration/resolvers/python.test.ts` — 204/204 under both `REGISTRY_PRIMARY_PYTHON=0` and `=1`. - `test/unit/scope-resolution/` — 406/406 passing. Unstaged: `gitnexus/package-lock.json` (drift from `npm install` run to resolve the pre-existing missing `jsonc-parser` dependency — not part of this change). Made-with: Cursor * test(ci): raise integration-test timeouts so slow Windows runners stop flaking The `windows-latest` CI runner for this branch was consistently failing two integration suites in ways that had nothing to do with the PR's scope-resolution changes: * `cli-e2e.test.ts` — `analyze command runs pipeline on mini-repo` hit the default 30 s vitest test timeout, which raced the test's own 30 s subprocess timeout and prevented the existing `if (result.status === null) return;` slow-CI tolerance from ever firing. That single timeout then cascaded into the downstream `cypher`/`query`/`impact` tests (which exited non-zero because the mini-repo was never indexed) and the `EPIPE handling` test. * `skills-e2e.test.ts` — `beforeAll` hooks run a full `runSkillsCli(tmpDir)` subprocess that analyzes a fixture repo and generates skills. 50 s was enough on Linux/macOS but not on slow Windows CPUs, producing "Hook timed out in 50000ms" errors and cascading test failures across every language describe block. Fix: * Bump the `analyze` test's vitest test-level timeout to 60 s so it exceeds the 30 s subprocess timeout and the slow-CI tolerance can actually activate. * Bump all 12 `runSkillsCli`-driven `beforeAll` hooks from 50 s to 120 s. No production-code behavior changes. No change to what the tests assert — only the per-test/hook wall-clock budget. Made-with: Cursor	2026-04-23 12:38:13 +01:00
Copilot	ff4ae89aaa	feat(python): scope-based call resolution + registry-primary flip + perf + generalization (RFC #909 Ring 3) (#980) ... * Initial plan * plan: Python scope-based resolution migration Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/0eee6c69-fc17-4df5-9ac6-358ab41f5740 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * feat(python): scope-based resolution provider hooks + 62 tests Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/0eee6c69-fc17-4df5-9ac6-358ab41f5740 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * refactor(python): split scope-hooks monolith into focused modules Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/db76e937-4b0e-4c4d-82b1-265a1fb3673d Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * test(python): integration-style scope-resolution tests + suffixResolve fallback Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/db76e937-4b0e-4c4d-82b1-265a1fb3673d Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * wire python scope-based resolution end-to-end (initial pass) Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/c474dc66-5cf7-445d-8eb4-76501c5e6d67 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * keep legacy IMPORTS for python (heritage needs importMap), scope phase owns CALLS only Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/c474dc66-5cf7-445d-8eb4-76501c5e6d67 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * test(python): remove parallel scope-resolution integration test The new test/integration/python-scope-resolution.test.ts duplicated coverage the reviewer explicitly rejected. The existing test/integration/resolvers/python.test.ts (191 tests, driven by runPipelineFromRepo) is the source of truth for Ring 3 parity. Also document the IMPORTS-emission follow-up gap: wiring emitImportEdges in python-scope-emit.ts today regresses 10 IMPORTS-edge fixtures because the scope-extractor's ImportEdge coverage is narrower than legacy pythonImportConfig.importResolver. Tracked as a follow-up. Baseline with REGISTRY_PRIMARY_PYTHON=1 is unchanged: 109/191 pass. * feat(ingestion): scope-resolution phase owns Python IMPORTS edges (RFC #909 Ring 3) When `REGISTRY_PRIMARY_PYTHON=1`, IMPORTS graph edges for Python files are now emitted exclusively by the new scope-resolution path. The legacy `import-processor` still runs — heritage resolution needs its importMap / namedImportMap / moduleAliasMap population — but its graph edge emission is gated per-language so Python no longer double-emits. This closes the reviewer's second change request on PR #980: "the legacy path must be turned off". Legacy IMPORTS edges for Python are now off by default when the flag is enabled. Three bugs were fixed to make the new path's coverage match legacy: 1. **Root-file bailout** (import-resolvers/python.ts): `resolvePythonImportInternal` returned null immediately when the importer file lived at the repo root (importerDir === ''). The ancestor directory walk further down already handles this case correctly; the early return was the bug. Proximity check now only runs when importerDir is non-empty, and the ancestor walk sees root-level files for the first time. 2. **External dotted imports** (languages/python/import-target.ts): the new path fell straight through to `suffixResolve` for multi-segment imports, which happily matched `django.apps` to a local `accounts/apps.py`. Mirror `pythonImportStrategy`'s `hasRepoCandidate` guard — suffix-match only when the leading segment exists somewhere in-repo as a package, __init__.py, or namespace directory. 3. **suffixResolve ambiguity** (languages/python/import-target.ts): the shared `suffixResolve` helper requires a pre-built `SuffixIndex` to disambiguate ties. Without one it falls back to an O(files) scan that silently picks the first match when the last segment collides across directories (e.g. `accounts.models` matching `billing/models.py`). Replaced with `resolveAbsoluteFromFiles` — exact lookup first, then a deterministic suffix match. Validation: - Flag OFF: 191/191 pass (no regression). - Flag ON: 109/191 pass (82 fail — exact baseline match; remaining 82 are unchanged CALLS-edge provider-feature gaps tracked as Phase B follow-ups). - `tsc --noEmit`: clean. The 82 CALLS failures cluster into 44 describe blocks covering type-inference features (assignment chains, walrus, class-level annotations, constructor inference, C3 MRO, overload dispatch, return-type inference) that need dedicated Ring 3 follow-up work. Each cluster is tracked against the RFC #909 shadow-parity gate (>=99% fixtures / >=98% corpus) in the per-language ticket. * ci(scope-resolution): automatic parity gate driven by MIGRATED_LANGUAGES Adds the Ring 3 parity gate the RFC §6.4 requires: when a language's scope-resolution migration is marked complete, CI runs its resolver integration test twice on every PR (once with the legacy DAG, once with the registry-primary path) and both must pass. The "is this language migrated" signal is a single TypeScript constant: // gitnexus/src/core/ingestion/registry-primary-flag.ts export const MIGRATED_LANGUAGES: ReadonlySet<SupportedLanguages> = new Set([ /* SupportedLanguages.Python when ready */ ]); Adding a language here has three simultaneous effects: 1. `isRegistryPrimary(lang)` defaults to true for that language in production (env-var override still wins if set explicitly). 2. `.github/workflows/ci-scope-parity.yml` auto-discovers the set via `npx tsx scripts/ci-list-migrated-languages.ts`, builds a parity matrix, and runs: - `REGISTRY_PRIMARY_<LANG>=0 npx vitest run resolvers/<slug>.test.ts` - `REGISTRY_PRIMARY_<LANG>=1 npx vitest run resolvers/<slug>.test.ts` Both legs must pass for the job to succeed. 3. Legacy-path gating in call-processor.ts / import-processor.ts kicks in automatically through the same `isRegistryPrimary` lookup. No JSON registry, no manual workflow edit, no second source of truth — contributors update the Set and CI picks it up. Empty Set = parity job is a skipped matrix (workflow still reports success). The new `scope-parity` reusable workflow is added to ci.yml's `needs` graph and ci-status gate. Its result must be `success` (skipped would mean upstream discover job failed and should block). Validation (with empty MIGRATED_LANGUAGES set): - flag OFF: 191/191 pass (no behavior change) - flag ON (manual REGISTRY_PRIMARY_PYTHON=1): 82 fails = baseline exact match - `npx tsc --noEmit`: clean - concurrency-convention script: pass - tsx discovery script: emits `[]` correctly * ci(scope-resolution): keep MIGRATED_LANGUAGES empty; fix linter auto-uncomment Previous commit's example entry got auto-uncommented (linter preferred a type-checkable `SupportedLanguages.Python` over a commented-out reference). That would have triggered the parity CI gate against Python, which today has 82 known flag-on failures — unintended and would block the PR. Use the explicit generic `new Set<SupportedLanguages>([])` so an empty set still type-checks without needing an uncommented-out sample member. Example in the comment now has `// SupportedLanguages.Python,` so it remains illustrative without participating in the set. * feat(python): capture constructor-inferred + annotated type bindings Extends the Python scope-extractor with two new type-binding capture patterns so receiver-typed method dispatch has concrete type bindings to work from: 1. `u: User = ...` / `u: User` — variable annotations. `@type-binding.annotation` anchor, `source: 'annotation'`. 2. `u = User("alice")` — assignment RHS is a bare-identifier call (Python has no `new` keyword; constructor-shaped calls are syntactically identical to function calls). `@type-binding.constructor` anchor, `source: 'constructor-inferred'`. The runtime query lives in `query.ts` (the `.scm` file is documentation per the comment at its top); both are updated. Fixes 19 failures across these resolver fixtures (flag-on 82 → 63): - Python constructor-inferred type resolution (3) - Python class-level annotation resolution (3) - Python nullable receiver resolution (3) - Python member-call / receiver-constrained / constructor-call (3) - Python assignment chain propagation (2) - Python walrus / match-case / chained method (3) - Python member access iterable for-loop (2) * feat(python): strip nullable unions + prefer annotations over inference Two linked changes that together fix the 4 nullable-receiver tests: 1. `stripNullable` in Python's `interpretTypeBinding` unwraps `User | None`, `None | User`, and `Optional[User]` to `User`, so receiver-typed resolution treats nullable receivers identically to non-nullable ones. Three-arm unions (`User | Error | None`) are left unchanged — truly ambiguous for single-receiver inference. 2. Source-strength ordering in `pass4CollectTypeBindings`. When multiple matches fire for the same bound name in the same scope — e.g. the `u: User = find()` idiom where both the annotation and constructor-inferred patterns match — the explicit annotation now wins regardless of query-match arrival order. Rank: explicit (annotation / parameter-annotation / return-annotation / self) > inferred Also reorders the two Python patterns in query.ts / scopes.scm so the constructor-inferred pattern appears first — a belt-and-braces fallback that keeps behavior deterministic if the shared priority ranking is ever revisited. Fixes 4 failures (flag-on 63 → 59): - Python nullable receiver resolution (4 tests) Flag-off regression check: 191/191 still pass. * feat(python): walrus, qualified-call, match-case type bindings Extends the constructor-inferred family of captures with three more assignment-shaped patterns that all bind a variable to a class-like type: - Walrus: `(u := User(...))` → `u: User` via `(named_expression)`. - Qualified call RHS: `u = models.User(...)` → `u: models.User` via `(attribute)` node .text. Falls through resolveTypeRef Phase 2 (QualifiedNameIndex dotted fallback). - Match as-pattern: `case User() as u:` → `u: User` via `(as_pattern)` + `(class_pattern (dotted_name))`. Fixes 2 failures (flag-on 59 → 57): - Python walrus operator type inference - Python match/case as-pattern type binding Qualified-call constructor tests still fail because they require cross-module qualifiedName registration (models.User → models.py's User class) which isn't yet wired in the Python extractor. Tracked as follow-up alongside module-import CALLS (#337) resolution. * feat(python): chain type bindings + strip list[T] generic for for-loop Adds two capture patterns and a shared transitive-closure pass that together handle Python's variable-aliasing and for-loop-over-typed- iterable patterns: 1. `(assignment left: (identifier) right: (identifier))` — `alias = u`. 2. `(for_statement left: (identifier) right: (identifier))` — `for u in users`. Both emit `@type-binding.alias` with the RHS identifier as rawName. The shared `pass4CollectTypeBindings` now runs a final transitive-closure walk that follows identifier-chain TypeRefs through the declaring scope and its ancestors (depth-capped, cycle-guarded) so `alias` ultimately points at the class type instead of another local variable name. Generic stripping in `interpret.ts` unwraps single-arg collection wrappers — `list[User]`, `set[User]`, `Iterable[User]`, etc. — to the element type. Multi-arg generics (`dict[str, User]`, `Callable[...]`) are left alone; their semantics aren't unambiguous. Fixes 8 failures (flag-on 57 → 49): - Python assignment chain propagation (4) - Python nullable + assignment chain (2) - Python walrus operator (:=) assignment chain (2) Flag-off still 191/191. * feat(python): namespace & class receiver resolution + file-level caller fallback Adds a Python-specific post-resolution pass `emitReceiverBoundCalls` that closes two receiver gaps the shared `MethodRegistry.lookup` doesn't cover: 1. **Namespace receivers** — `import models; models.User()` / `import models as m; m.User()`. The shared `lookupReceiverType` only walks `scope.typeBindings`; namespace imports never land there (they're filtered out of `scope.bindings` when the target module has no self-named def, per `finalize-algorithm.ts:540`). The new pass walks `indexes.imports` directly, builds a per-file `localName → targetFilePath` map, and emits CALLS/ACCESSES edges against the target file's `localDefs`. 2. **Class-name receivers** — `Dog.classify("dog")`. The shared resolver requires typeBindings; class bindings in `scope.bindings` are never consulted as receivers. The new pass checks class-kind bindings in the call scope's chain and resolves members via `ownerId`. Also fixes module-level call attribution: `resolveCallerGraphId` now falls back to the File node id (`generateId('File', filePath)`) when no enclosing function/method/class is found. Matches legacy DAG behavior for module-scope calls like `u = models.User()` at the top of app.py. Fixes 4 failures (flag-on 49 → 45): - Python module import CALLS resolution (Issue #337) (4 of 7) Flag-off still 191/191. * feat(python): dotted-typebinding receiver resolution Adds case 3 to `emitReceiverBoundCalls`: when a receiver's typeBinding has a dotted rawName like `u: models.User` (the constructor-inferred form fired by `u = models.User(...)`), walk the namespace map + target file's defs to find the class, then look up the member via ownerId. `resolveTypeRef`'s QualifiedNameIndex fallback can't cover this because the target class's qualifiedName in models.py is just `"User"`, not `"models.User"` — the dotted form only exists in the call-site file's receiver expression. This pass bridges that gap without modifying the shared registry. Fixes 9 more failures (flag-on 45 → 36): - Python qualified constructor inference (2) - Python module import CALLS resolution (Issue #337) (3) - (cluster overlap — several downstream tests in assignment/nullable/ walrus that propagate through qualified-ctor bindings also benefit) Flag-off still 191/191. * feat(python): consult finalized bindings for receiver resolution `findClassBindingInScope` now walks BOTH: 1. `scope.bindings` — pre-finalize local declarations (origin: 'local') 2. `indexes.bindings` — post-finalize cross-file imports/namespaces Without (2) we were blind to any class brought in via `from models import Dog` at the call site's file, because the scope-extractor's Pass 2 only populates local bindings and the cross-file finalize produces a separate bindings map that never lands on `scope.bindings`. Case 2 (`Dog.classify()`) now walks MRO so inherited static/class methods resolve — `Dog.classify()` where `classify` lives on `Animal`. Case 4 (simple typeBinding like `u: U` from aliased import) now uses `findClassBindingInScope` instead of the shared `resolveTypeRef`, because `resolveTypeRef`'s `ctx.scopes` only sees pre-finalize local bindings too. Fixes 4 more failures (flag-on 36 → 32): - Python method enrichment > Dog.classify static (1) - Python static/classmethod class-as-receiver (2) - Python alias import resolution (1) Flag-off still 191/191. * refactor(python-scope): extract language-agnostic emit-core/ Unit 1 of the python migration architectural plan (docs/plans/2026-04-19-001-refactor-python-migration-architectural-plan.md). Splits python-scope-emit.ts (~945 → 481 lines) by lifting 14 generic graph-feeding primitives into emit-core/: - graph-node-lookup, graph-id, emit-edge - emit-references, emit-imports - scope-walkers (findReceiverTypeBinding, findClassBindingInScope, findOwnedMember, findExportedDef) - namespace-targets, method-dispatch-bridge Each file carries a "Next-consumer contract" JSDoc so future language migrations (TS #927, JS #928, Java, Kotlin, Ruby) import from emit-core rather than re-implementing. python-scope-emit.ts keeps only the four Python-specific pieces: runPythonScopeResolution (orchestrator), buildPythonMro, emitReceiverBoundCalls (4 cases), populateMethodOwnerIds — these move to languages/python/emit/ in Unit 11. Pure refactor, zero behavior change: - flag-off: 191/191 python.test.ts pass (identical baseline). - flag-on (REGISTRY_PRIMARY_PYTHON=1): 32 fail / 159 pass (identical baseline — the refactor neither fixes nor regresses any test). - tsc --noEmit clean. * feat(python-scope): arity metadata + bind function decls in parent scope Unit 2 of the python migration architectural plan (docs/plans/2026-04-19-001-refactor-python-migration-architectural-plan.md). Two changes that the registry-primary path needs before any of the arity-sensitive failures can move: 1. Arity metadata on scope-extracted Function/Method defs. - New helper `languages/python/arity-metadata.ts` reuses `pythonMethodConfig.extractParameters` so self/cls stripping, defaults, and *args/**kwargs detection match legacy semantics. - `emit-captures.ts` synthesizes `@declaration.parameter-count` / `@declaration.required-parameter-count` / `@declaration.parameter-types` captures on every `@declaration.function` match. - Generic `scope-extractor.ts buildDefFromDeclarationMatch` reads the three optional captures into `SymbolDefinition`. Absence is still the no-op default for non-Python providers. 2. Hoist function/class declaration bindings to the enclosing scope. The "innermost scope containing the anchor" default placed `def greet(...)` inside greet's OWN body — invisible to other module-level callers, so every flag-on free-call resolved to `unresolved`. The hoist condition (`anchor range == innermost range`) only fires for scope-creating declarations, so variable / for-loop captures whose anchor is a child identifier stay put. Hooks can still override via `bindingScopeFor`. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on (REGISTRY_PRIMARY_PYTHON=1): 31 fail / 160 pass (was 32/159; the hoist unblocks free-call resolution end-to-end). - tsc --noEmit clean. Per-(source,target) edge collapse for multi-call-site cases (default-params, variadic) still pending — landing it without regressing the static-method find_user fixture (which expects two distinct edges through different targets) needs the ownership-aware qualified-id work that lands with Unit 4 / Unit 11. * feat(python-scope): capture function return-type annotations Unit 3 of the python migration architectural plan (docs/plans/2026-04-19-001-refactor-python-migration-architectural-plan.md). Wires the `def get_user() -> User` return-type annotation into the typeBindings stream so the existing constructor-inferred + transitive chain machinery can resolve `u = get_user(); u.save()` to `User#save` without any orchestrator change. Changes: - `query.ts` + `scopes.scm`: new `@type-binding.return` pattern keyed by the function name (matches RFC §5.1 canonical vocabulary). - `interpret.ts`: maps `@type-binding.return` to the existing `'return-annotation'` source label (no shared change needed). - `scope-extractor.ts pass4CollectTypeBindings`: extends the Pass 2 auto-hoist (anchor range == innermost scope range → bind in parent) to type bindings as well — return-type bindings whose anchor IS the function_definition land in the function's enclosing scope so callers see them. Same-file return-type inference is now end-to-end: `def get_user() -> User: ...` + `u = get_user()` produces `u: User (return-annotation)` in the caller's scope via `followChainedRef`. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 31 fail / 160 pass (no change — every remaining return-type test in this fixture set is *cross-file*; carrying `get_user → User` across module boundaries lands with the cross-file typeBinding propagation work in Unit 5/7). - tsc --noEmit clean. * feat(python-scope): resolve dotted receivers via class-scope field types Unit 4 partial — the dotted-receiver case (`user.address.save()`). Class-body annotations like `class User: address: Address` already land in the class scope's typeBindings via the existing `@type-binding.annotation` capture. This commit consumes that signal: - Build a `Map<classDefId, Scope>` from every parsed file's class scopes once per resolution pass. - New Case 0 in `emitReceiverBoundCalls`: when the receiver's name contains a dot, walk the chain — resolve the head's type, then for each remaining segment look up that field's type in the owner class's scope.typeBindings, then emit the call against the final class with MRO walk. - Cross-scope lookups use each TypeRef's `declaredAtScope` so an imported `Address` resolves in the file that owns the field declaration, not the file holding the call site. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 29 fail / 162 pass (was 31/160; both `Field type resolution` fixtures now pass — same-file and cross-file disambig). - tsc --noEmit clean. Remaining Unit 4 work (write ACCESSES, `self.X` for-loop iteration) needs Unit 6's tuple/iterable destructuring before it can land — `for u in self.users` requires the iterable typing path. * feat(python-scope): chain receiver via call-expression return types Unit 5 — extends the compound-receiver case to handle call-expression receivers (`svc.get_user().save()`). `resolveCompoundReceiverClass` is the single recursive entry point for all compound receivers. Three shapes: - bare identifier — typeBinding chain - dotted `obj.field[.field]…` — class-scope field types - call `expr.method()` — recurse into expr, look up method's return-type typeBinding on its class scope Method return-type bindings auto-hoist to the parent (class) scope per Unit 3, so `methodClassScope.typeBindings.get(methodName)` is the canonical lookup. Free-call return types (`get_user()`) walk the caller's scope chain. Depth-capped at 4 hops to bound recursion. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 28 fail / 163 pass (was 29/162; `Python chained method call resolution` now passes). - tsc --noEmit clean. Two related tests (`city.save() via method chain`, `c.greet().save() depth-2 MRO`) still fail because the captures yield typeBindings shaped like `city → user.get_city` (no trailing parens — the capture grabs the attribute text). Resolving those needs a follow step that detects the call-shape rawName and feeds it through the compound recurser. Lands with the chain-typeBinding work in a follow-up. * feat(python-scope): free-call fallback consults finalized bindings Unit 7 — closes the cross-file free-call gap. The shared `MethodRegistry.lookup` walks `scope.bindings` (pre-finalize local-only) for free-call resolution. Cross-file imports land in `indexes.bindings` (post-finalize). Without the dual-source lookup, `from x import f; f()` resolves to "unresolved" and no CALLS edge is emitted. Two changes: - `emit-core/scope-walkers.ts`: new `findCallableBindingInScope` — same dual-source pattern as `findClassBindingInScope`, but accepts Function/Method/Constructor. Promoted to emit-core because every language with cross-file imports needs the same lookup. - `python-scope-emit.ts emitFreeCallFallback`: post-pass that walks every free-call reference site, looks up the callee with the new helper, and emits via `tryEmitEdge`. Pre-seeds `seen` from the shared resolver's emissions so we never double-count. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 22 fail / 169 pass (was 28/163; +6 tests including the Python overload dispatch fixtures, ancestor-directory imports, and same-name module-alias collision). - tsc --noEmit clean. * feat(python-scope): super() receiver dispatches up the MRO Unit 8 — `super().method()` inside a class method walks the enclosing class's MRO chain (skipping self) and resolves to the first ancestor that owns the method. New receiver branch in `emitReceiverBoundCalls` recognizes `super(...)` syntactically (regex-cheap), finds the enclosing class via a new `findEnclosingClassDef` scope-walk helper, then re-uses `scopes.methodDispatch.mroFor` + `findOwnedMember` from the existing class-receiver path. Handled before the compound-receiver case so `super()` doesn't fall into the bare-identifier branch where `super` isn't a binding. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 21 fail / 170 pass (was 22/169; `super().save() inside User to BaseModel.save` now passes). - tsc --noEmit clean. * feat(python-scope): suppress shared resolver on member-call sites Unit 9 — `app_metrics.get_metrics()` (namespace import alias) was emitting two CALLS edges: a wrong self-call from the shared resolver's free-call fallback, plus the correct namespace-receiver edge from the Python post-pass. Mechanism: - `emit-core/emit-references.ts`: new optional `skipSites` parameter (`Set<string>` of `${filePath}:${line}:${col}` keys). When supplied, references at those positions are skipped — the provider has already emitted (or chosen not to emit) for that site. - `python-scope-emit.ts`: reorders Phase 4 — receiver-bound + free- call fallback run FIRST, populating `handledSites`. The shared `emitReferencesViaLookup` then runs with that set so the resolver's fallback can't fight a precise per-receiver emission. Site keys are added only on successful tryEmitEdge (not for sites the post-pass saw but couldn't resolve — those still get a chance from the shared path). Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 20 fail / 171 pass (was 21/170; same-name module-alias collision now resolves correctly). - tsc --noEmit clean. * feat(python-scope): propagate return-type bindings across imports Closes the cross-file return-type propagation gap that left tests like `u = get_user(); u.save()` (where get_user lives in another file) with `u` typed as the function name instead of its return type. The shared finalize pass copies callable bindings (`from x import f` puts `f` in the importer's bindings) but typeBindings stay file-local because they live on `Scope.typeBindings`, not on the index. Mutate post-finalize: - For each module-scope import binding (`origin: 'import'` or `'reexport'`), look up the source file's module-scope typeBinding for the def's simple name. If present (return-annotation source), mirror it under the importer's local alias. Skip when the importer already has its own typeBinding for the name (explicit local always wins). - After propagation, re-run a chain-follow on every scope's typeBindings — pass-4 ran before propagation and missed any chain whose terminal lived in a foreign file. Same algorithm as `followChainedRef` in scope-extractor, but operates on the finalized scopes so propagated entries are visible. Mutating `Scope.typeBindings` is safe — `draftToScope` constructs a plain `new Map(...)`, not a frozen one. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 16 fail / 175 pass (was 20/171; +4 — both cross-file return-type tests, plus two related propagation cases). - tsc --noEmit clean. * feat(python-scope): for-loop call-iterable typeBinding Adds `(for_statement left: (identifier) right: (call function: (identifier)))` to the typeBinding capture set. Combined with Unit 3's return-type capture and the cross-file return-type propagation pass, this makes `for u in get_users(): u.save()` resolve to `User.save` even when `get_users` is imported from another module. Captured as `@type-binding.alias` (rawName = function identifier, without parens) so the existing chain-follow walks the alias to the function's return-type binding without any new code path. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 12 fail / 179 pass (was 16/175; +4 for-loop call-iterable tests across get_users / get_repos fixtures). - tsc --noEmit clean. * feat(python-scope): collapse free-call edges per (caller, target) Free calls (no explicit receiver) now emit a single CALLS edge per (caller, target) pair regardless of how many call sites the caller contains. Mirrors the legacy DAG's per-pair dedup contract — what the `default-params`, `variadic`, and `overload` fixtures expect. Member calls keep position-based dedup so distinct resolved targets (e.g. UserService.find_user vs AdminService.find_user from the same caller) still produce distinct edges. Implementation: bypass `tryEmitEdge` (which dedupes positionally) and hand-roll the relationship with a position-independent rel.id (`rel:CALLS:<caller>-><target>`). Site handling is now unconditional — even when the dedup-collapse skips the actual emit, we mark the site handled so the shared `emit-references` doesn't fight us with its fallback. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 10 fail / 181 pass (was 12/179; +2 — both `default parameter arity` tests now pass). - tsc --noEmit clean. * fix(python-scope): match legacy CALLS reason for import-resolved free calls The arity-narrowing test asserts \`rel.reason === 'import-resolved'\` for cross-file free-call edges. Switch the free-call fallback's reason to mirror legacy DAG semantics: - target-file !== source-file → 'import-resolved' - same file → 'local-call' Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 9 fail / 182 pass (was 10/181; +1 arity-narrowing test). - tsc --noEmit clean. * fix(python-scope): drop dead pre-seeding from receiver-bound pass The pre-seeding loop at the top of \`emitReceiverBoundCalls\` populated \`seen\` with every reference the shared resolver had already resolved. That was useful when emit-references ran FIRST. After Unit 9 reversed the order (emit-references runs after the Python passes and uses \`handledSites\` to skip what we processed), the pre-seed only causes harm: when an MRO walk in Case 0 (compound receiver) and Case 4 (simple typeBinding) both touch the same site at the same position but resolve to different targets, the pre-seed suppresses the second emission because the shared resolver had already entered the wrong target into \`seen\`. Concrete case: \`c.greet().save()\` — Case 0 emits the outer save edge to Greeting.save; Case 4 then resolves the inner \`c.greet()\` to A.greet via MRO walk. With pre-seed both edges should emit (different targets, different rel.ids); without removing the pre-seed the inner emission was being deduped against an already-seeded entry and the A.greet edge was lost. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 8 fail / 183 pass (was 9/182; +1 — \`c.greet() to A#greet via MRO walk\` now passes). - tsc --noEmit clean. * feat(python-scope): enumerate(X) for-loop tuple destructuring Adds two new typeBinding capture patterns for the canonical enumerate pattern: for (i, u) in enumerate(users): ... ; tuple_pattern for i, u in enumerate(users): ... ; pattern_list Both bind the second tuple element (u) to the iterable identifier (users). The chain-follow then unwraps users → its element type via the existing generic-strip in interpret.ts (List[User] → User). The #eq? predicate scopes the pattern to enumerate specifically; generic tuple destructuring of arbitrary callables is left to a future iteration once we have a richer signal for "what does this call yield". Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 7 fail / 184 pass (was 8/183; +1 — `parenthesized tuple: for (i, u) in enumerate(users)` now passes). - tsc --noEmit clean. * feat(python-scope): dict.items() value-type unwrapping Two changes that together resolve `for k, v in data.items(): v.save()`: - `interpret.ts stripGeneric`: extends to `dict[K, V]` / `Dict[K, V]` / `Mapping[K, V]` etc., stripping to the value type V. Previously only single-arg generics (list[User] → User) were stripped; multi-arg ones returned the raw text. - `query.ts` + `scopes.scm`: new typeBinding patterns for `for k, v in X.items()` (both pattern_list and tuple_pattern). The second tuple element binds to X; the chain-follow then unwraps X's dict annotation to V via the new stripGeneric branch. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 6 fail / 185 pass (was 7/184; +1 — `dict.items() loop` test now passes). - tsc --noEmit clean. * feat(python-scope): nested tuple destructuring for enumerate(d.items()) Two more for-loop typeBinding patterns: - `for i, (k, v) in enumerate(d.items())` — nested tuple destructuring where v is the value of the dict's items() yield. - `for v in d.values()` — explicit values() form (companion to items). Both bind the loop var to the dict identifier; the chain-follow unwraps via the dict-aware stripGeneric to the value type. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 5 fail / 186 pass (was 6/185; +1 nested tuple test). - tsc --noEmit clean. * feat(python-scope): 3-var flat destructuring for enumerate(d.items()) Adds the \`for i, k, v in enumerate(d.items())\` shape — flat 3-variable destructuring of the (i, (k, v)) tuple yielded by \`enumerate\` over \`items()\`. Binds v (the last identifier in the pattern_list) to the dict identifier; the existing dict-aware stripGeneric unwraps to the value type. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 4 fail / 187 pass (was 5/186; +1). - tsc --noEmit clean. * feat(python-scope): write ACCESSES edges for attribute assignments Three changes that together produce ACCESSES (write) edges for \`obj.field = value\` assignments: - New \`@reference.write.member\` capture in query.ts and scopes.scm matching \`(assignment left: (attribute object: ... attribute: ...))\`. Reuses the existing receiver/name capture shape so the receiver-bound emit pass can resolve obj's class and look up the field. - \`populateMethodOwnerIds\` now sets ownerId on class-body fields too, not only on methods. Previously it only walked Function scopes whose parent was Class; class-body annotations like \`name: str\` live directly in the Class scope's ownedDefs and were missed, so \`findOwnedMember(User, "name")\` returned undefined. - \`emit-core isLinkableLabel\` extends to Variable and Property so field nodes appear in the graph-node lookup (the legacy parser emits both kinds for class-body annotations). - Case 4 in receiver-bound pass now uses the kind word as the edge reason for read/write sites — matches the legacy DAG convention the test asserts on. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 3 fail / 188 pass (was 4/187; +1 — write-ACCESSES test). - tsc --noEmit clean. * feat(python-scope): chain-typebinding + field-fallback method lookup Reaches the architectural-plan target of >= 189/191 flag-on passing. Two intertwined changes: - Field-fallback in resolveCompoundReceiverClass: when method lookup on the receiver's class (and its MRO) fails, walk the class's fields and try the same lookup on each field's type. Matches the "unified fixpoint" intent of the method-chain fixture where `user.get_city()` reaches `Address.get_city` through User's `address: Address` field. - New Case 3b in receiver-bound emit pass: when the receiver's typeBinding rawName has a dot but isn't a namespace prefix (e.g. `city -> user.get_city` from the constructor-inferred capture for `city = user.get_city()`), treat it as a method-call chain and pipe through the compound resolver. The chain unwraps to the terminal class (City) and the call resolves normally. Verification: - Flag-off: 191/191 (identical baseline). - Flag-on: 2 fail / 189 pass (was 3/188; +1 city.save method chain). - tsc --noEmit clean. Remaining 2 failures are fixture-driven (self.users / self.repos fixtures reference fields that aren't declared on the class) and documented as known-limitation in Unit 10. * feat(python-scope): flip Python to registry-primary (191/191 parity) Adds the \`for u in self.X\` heuristic typeBinding capture (binds u to the attribute name X so the chain-follow can resolve via the enclosing method's parameter typeBinding) — closes the last two failing fixtures whose classes reference \`self.X\` for fields that are actually method parameters. With 191/191 passing on BOTH legacy and registry-primary paths, flips \`MIGRATED_LANGUAGES\` to include \`SupportedLanguages.Python\`. Effects: - Production default for Python files: registry-primary path. - CI parity gate auto-discovers Python via the script + workflow (\`scripts/ci-list-migrated-languages.ts\` / \`.github/workflows/ci-scope-parity.yml\`) and runs the resolver integration test BOTH ways on every PR. - Operators retain the \`REGISTRY_PRIMARY_PYTHON=0\` escape hatch. Verification: - REGISTRY_PRIMARY_PYTHON=0 (legacy): 191/191. - REGISTRY_PRIMARY_PYTHON=1 (registry): 191/191. - Default (unset, post-flip): 191/191 (uses registry). - tsc --noEmit clean. This concludes RFC #909 Ring 3 — Python migration. * refactor(emit-core): EmitProvider interface + promote 5 generic helpers G-Units 1-2 of the emit-pipeline generalization plan. Adds: - emit-core/emit-provider.ts — typed EmitProvider contract (6 required + 2 optional fields). Will be consumed by the generic orchestrator in G-Unit 6. Documents the LanguageProvider vs EmitProvider boundary. - emit-core/emit-free-call.ts — emitFreeCallFallback promoted as-is (drops the unused referenceIndex pre-seed parameter; underscore-prefixed to keep the signature compatible). - emit-core/propagate-return-types.ts — propagateImportedReturnTypes + followChainPostFinalize. Documents the mutation contract (Invariant I3 + I6 from the plan): runs after finalize, before resolve, mutates the non-frozen Scope.typeBindings map. - emit-core/scope-walkers.ts: + findEnclosingClassDef + findExportedDefByName. Both were already generic in the Python source. python-scope-emit.ts shrinks 1055 → 799 lines (–256). Imports the promoted helpers from emit-core. No behavior change. Verification: - REGISTRY_PRIMARY_PYTHON=0 (legacy): 191/191. - REGISTRY_PRIMARY_PYTHON=1 (registry): 191/191. - tsc --noEmit clean. * refactor(emit-core): promote receiver-bound dispatcher + compound resolver G-Unit 3 of the emit-pipeline generalization plan. - emit-core/emit-compound-receiver.ts — resolveCompoundReceiverClass + matchingOpenParen + COMPOUND_RECEIVER_MAX_DEPTH. Field-fallback is now an option (default true) so strictly-typed languages can opt out via EmitProvider.fieldFallbackOnMethodLookup. - emit-core/emit-receiver-bound.ts — the 7-case dispatcher (super, Cases 0/1/2/3/3b/4). Accepts a ReceiverBoundProviderSubset (isSuperReceiver + fieldFallbackOnMethodLookup) so partial wiring works during the rest of the migration. Documents Contract Invariants I4 (case order) and I5 (no pre-seeding). python-scope-emit.ts shrinks 799 → 384 lines. The orchestrator now calls the generic emitReceiverBoundCalls with an inline minimal provider (pythonEmitProviderInline) — full provider lands in G-Unit 6 when the orchestrator itself moves to languages/python/emit/. Verification: - REGISTRY_PRIMARY_PYTHON=0 (legacy): 191/191. - REGISTRY_PRIMARY_PYTHON=1 (registry): 191/191. - tsc --noEmit clean. * refactor(emit-core): promote MRO walk + populateClassOwnedMembers G-Units 4-5 of the emit-pipeline generalization plan. - emit-core/build-mro.ts — generic buildMro takes a LinearizeStrategy hook receiving (classDefId, directParents, parentsByDefId). Three shared steps (collect EXTENDS, build defId-by-graphId, walk per class) + parametric linearization. Default strategy is BFS-with- visited (Python's depth-first first-seen, also correct for single-inheritance languages). - emit-core/scope-walkers.ts: + populateClassOwnedMembers — generic OO ownership rule (methods + class-body fields). Both rules ship together because every OO language migrated so far (Python; planned TS/JS/Java/Kotlin) wants both. Languages that need different rules can compose with this as a base step. python-scope-emit.ts shrinks 384 → 255 lines. Verification: - REGISTRY_PRIMARY_PYTHON=0 (legacy): 191/191. - REGISTRY_PRIMARY_PYTHON=1 (registry): 191/191. - tsc --noEmit clean. * refactor(scope-resolution): generic orchestrator + language-agnostic phase G-Units 6-7 of the emit-pipeline generalization plan, plus the pipeline-phase generalization (the user's observation that the phase itself is generic once the orchestrator is). Changes: - emit-core/orchestrator.ts — runScopeResolution(input, provider). The 180 lines of pipeline glue moved here, parametrized by EmitProvider. Provider supplies LanguageProvider, importEdgeReason, and the 6 emit-side hooks. - emit-core/emit-provider.ts — EmitProvider gains languageProvider and importEdgeReason fields so the orchestrator needs nothing else. resolveImportTarget now takes (targetRaw, fromFile, allFilePaths). - languages/python/emit/index.ts — pythonEmitProvider + thin runPythonScopeResolution wrapper. The first reference impl every next-language migration copies. - emit-providers-registry.ts (NEW) — registry of per-language EmitProviders keyed by SupportedLanguages. Adding a language is one line here + the provider file. - pipeline-phases/scope-resolution.ts (NEW) — language-agnostic phase iterating EMIT_PROVIDERS ∩ MIGRATED_LANGUAGES. Replaces pipeline-phases/python-scope.ts (deleted). - python-scope-emit.ts deleted. - pipeline.ts swaps pythonScopePhase → scopeResolutionPhase. The next language migration is now: implement EmitProvider, register it, add to MIGRATED_LANGUAGES. No new pipeline phase, no orchestrator copy-paste. The Python migration's 700+ lines of glue collapse to ~80 lines per future language. Verification: - REGISTRY_PRIMARY_PYTHON=0 (legacy): 191/191. - REGISTRY_PRIMARY_PYTHON=1 (registry): 191/191. - Default (post MIGRATED_LANGUAGES flip): 191/191. - tsc --noEmit clean. * docs(emit-provider): migration cookbook for next-language porters * refactor(scope-resolution): rename emit-core/ → scope-resolution/, EmitProvider → ScopeResolver Reorganizes the registry-primary resolution layer for clarity and contributor onboarding. Driven by feedback that "emit" was triple- overloaded (graph-edge emission + tree-sitter capture extraction + the provider name itself), and the flat 16-file emit-core/ folder mixed five concerns. External research (rust-analyzer hir-def/nameres, Pyright analyzer/, TypeScript binder/checker, Roslyn Binder, IntelliJ Resolver, swc semantic/, biome semantic/, semgrep naming/, JDT Binding, clangd Sema) consistently uses **the phase name** for this layer, never an output verb. "Scope resolution" matches our pipeline-phase name, the plan, and the RFC. ## Folder rename emit-core/ → scope-resolution/ ├── (16 flat files) → ├── contract/scope-resolver.ts ├── pipeline/{run,registry,phase}.ts ├── passes/{receiver-bound-calls, │ free-call-fallback, │ compound-receiver, │ imported-return-types, │ mro}.ts ├── graph-bridge/{node-lookup,ids, │ edges,references-to-edges, │ imports-to-edges, │ method-dispatch}.ts └── scope/{walkers,namespace-targets}.ts Each subfolder maps to one concern a new contributor needs to find: *the contract I implement / the runner that calls me / the helpers I reuse / the graph layer I shouldn't touch / the scope walkers*. ## Symbol renames EmitProvider → ScopeResolver pythonEmitProvider → pythonScopeResolver runPythonScopeResolution → resolvePythonScope EMIT_PROVIDERS → SCOPE_RESOLVERS getEmitProvider → getScopeResolver RunPythonScopeResolution{Input,Stats} → ResolvePythonScope{Input,Stats} ## File renames (per-language) languages/python/emit/index.ts → languages/python/scope-resolver.ts languages/python/emit-captures.ts → languages/python/captures.ts (kills the parse-side "emit" collision) ## Mechanics - Used `git mv` for all files so blame history is preserved. - Updated ~30 import lines across 18 files plus the pipeline-phases barrel and pipeline.ts. - Updated JSDoc cross-references throughout to match the new vocabulary. Verification: - REGISTRY_PRIMARY_PYTHON=0 (legacy): 191/191. - REGISTRY_PRIMARY_PYTHON=1 (registry): 191/191. - Default (post MIGRATED_LANGUAGES flip): 191/191. - tsc --noEmit clean. Migration cookbook in `scope-resolution/contract/scope-resolver.ts` JSDoc points the next-language porter at all the new names and folder locations. * docs(scope-resolution): finalize phase JSDoc + drop python emoji from generic log line * perf(scope-resolution): O(1) workspace lookup index Introduces `WorkspaceResolutionIndex` — a precomputed bundle of lookup tables built ONCE per resolution run, after `populateOwners` and after finalize, before any pass that needs to find members, exported defs, or class scopes by id. What it replaces (all are pre-existing O(N×D) linear scans of parsedFiles, called inside the receiver-bound MRO chain): - `findOwnedMember(ownerId, name, parsedFiles)` → `Map.get` via `index.memberByOwner.get(ownerId)?.get(name)`. Was the worst offender — receiver-bound dispatcher calls this O(sites × MRO depth) times. - `findExportedDef(filePath, name, parsedFiles)` → `Map.get` via `index.defsByFileAndName`. Hot for namespace-receiver case. - `findExportedDefByName` workspace-wide fallback scan → `Map.get` via `index.callablesBySimpleName`. - `classScopeByDefId` (rebuilt inside `emitReceiverBoundCalls` on every invocation) — moved to one-shot build during finalize, read from `index.classScopeByDefId` everywhere. - `moduleScopeByFile` (rebuilt inside `propagateImportedReturnTypes` on every invocation) — read from `index.moduleScopeByFile`. Findings from a synthetic 100-file Python workload (60 model files each defining 5 classes × 3 methods + 40 user files calling them heavily): scope-resolution wall time: 764ms → 710ms (median, 5 iters) That's a ~7% in-layer win. The smaller-than-expected gain was informative: profiling the synthetic workload shows scope-resolution breakdown is `extract=62% resolve=30% emit=4%`; the index touched the 4% slice (emit + walker calls inside it). Larger O(D) per owner classes will benefit more. Profiling the FULL pipeline (49 fixtures × 3 iters) shows scope-resolution accounts for ~1% of pipeline wall time — the remaining 99% is parse (tree-sitter), heritage, ORM, MRO, processes, and DB writes. So further optimization of this specific layer has marginal pipeline impact; the next-biggest wins live in those phases. Documented as the "double-parse" finding in the audit (captures.ts re-parses each Python file even though the parse phase already produced a tree-sitter Tree) — that's a separate plumbing project across phase boundaries. Bonus: opt-in PROF_SCOPE_RESOLUTION=1 env var prints a per-phase ms breakdown to stderr, so future perf work can measure without extra code changes. Verification: - REGISTRY_PRIMARY_PYTHON=0 (legacy): 191/191. - REGISTRY_PRIMARY_PYTHON=1 (registry): 191/191. - tsc --noEmit clean. * perf(parse/heritage/mro): typed graph iterator + cross-phase tree cache Two structural perf wins targeting the parse / heritage / MRO layers, identified by the post-WorkspaceResolutionIndex profiling (scope-resolution = ~1% of pipeline; the bulk lives upstream). ## 1. KnowledgeGraph.iterRelationshipsByType (PHM-Units 1-2) - Adds a per-type `Map<RelationshipType, Map<id, Relationship>>` index inside `createKnowledgeGraph`, maintained on add / remove / removeNode / removeNodesByFile. - New `iterRelationshipsByType(type)` returns a typed iterator that yields only the requested type. Backwards-compatible: existing `iterRelationships()` / `forEachRelationship()` callers untouched. - Migrated two MRO call sites: - `mro-processor.ts buildAdjacency`: split the single `forEachRelationship` (which scanned every edge in the graph and type-filtered per-iteration) into three typed iterations (EXTENDS, IMPLEMENTS, HAS_METHOD). - `scope-resolution/passes/mro.ts buildMro`: replaced `for (const rel of graph.iterRelationships()) if (rel.type !== 'EXTENDS') continue` with `for (const rel of graph.iterRelationshipsByType('EXTENDS'))`. - Heritage-processor (PHM-Unit 3) was a no-op: it only WRITES EXTENDS/IMPLEMENTS edges, never re-reads. Index is still useful for the seven other graph-iter consumers (community-processor, csv-generator, wildcard-synthesis, process-processor, etc.) — those follow-ups can switch to the typed iterator without touching the graph layer. - Adds 5 unit tests for the new method (add/remove/dedupe semantics, empty-type fresh iterator, removeNode index sync). ## 2. Cross-phase tree cache (PHM-Units 4-5) The audit's #2 finding: Python files are parsed by tree-sitter once in the parse phase, then re-parsed inside scope-resolution's `captures.ts`. Eliminate the second parse by sharing the Tree across phases. - `parse-impl.ts` now maintains TWO ASTCaches with distinct lifetimes: - `astCache` (chunk-local, cleared between chunks) — unchanged; used by call/heritage/import processors during parse. - `scopeTreeCache` (total-parseable-sized, never cleared) — new, exposed via `ParseOutput.astCache` for cross-phase consumption. - `parsing-processor.ts` writes every sequentially-parsed Tree to BOTH caches. Worker-mode parses skip the persistent cache too (Trees can't cross MessageChannels). - `LanguageProvider.emitScopeCaptures` gains an optional `cachedTree` parameter (typed `unknown` to keep the tree-sitter dep out of the contract). - `captures.ts` short-circuits its own `parser.parse(sourceText)` when a cached Tree is supplied. Cache miss falls back to a fresh parse — same correctness path as before. - `runScopeResolution` accepts an optional `treeCache` and forwards per-file `cachedTree` to `extractParsedFile`. - `scope-resolution/pipeline/phase.ts` reads `getPhaseOutput<{astCache}>(deps, 'parse')` and passes through. Verified end-to-end: a small fixture run with PROF_SCOPE_RESOLUTION=1 shows 6/6 cache hits (100% hit rate) on the python-grandparent fixture that exercises the full pipeline below the worker-pool threshold. ## Verification - REGISTRY_PRIMARY_PYTHON=0 (legacy): 191/191. - REGISTRY_PRIMARY_PYTHON=1 (registry): 191/191. - New graph.test.ts: 25/25 (was 20). - tsc --noEmit clean. ## Where the win lands Wall-clock on the 49-fixture integration suite: 14050ms → 14080ms (within noise). Fixtures are 1-3 files each, dominated by per-fixture pipeline overhead (worker-pool init, DB writes, fixture startup). The cache + typed-iterator wins are constant-factor improvements that scale linearly with workload size and visible only on larger repos. The dev-mode `PROF_SCOPE_RESOLUTION` instrumentation + `getPythonCaptureCacheStats()` are kept for future perf work. ## Plan docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md. PHM-Unit 3 (heritage-processor migration) intentionally collapsed to a no-op — heritage only writes, never re-reads. * perf(scope-resolution): bound tree-cache lifetime + gate population Address P1 residuals from ce:review of 8c6f5cee: - Dispose scopeTreeCache at end of scopeResolutionPhase via astCache.clear(). Trees were previously retained for the full pipeline (10-100x memory regression on large repos). Downstream phases (mro, community, csv-generator) never read them. - Gate scopeTreeCache.set on provider.emitScopeCaptures !== undefined. Polyglot repos no longer retain Trees for languages with no scope-resolution consumer. - PROF_SCOPE_RESOLUTION=1 now warns when workers engage, since Trees can't cross MessageChannels so the cache will be empty for worker-parsed files — prevents a silent perf cliff once a repo crosses the worker-pool threshold. Tests: 26/26 graph unit, 299/299 scope-resolution unit, 191/191 python integration both flag paths. * refactor(scope-resolution): clean up P2/P3 review residuals P2: - WASM dual-ownership invariant documented on ASTCache dispose: a Tree must live in AT MOST ONE disposing ASTCache. Native tree-sitter today is unaffected; WASM adoption would require tree.copy() or a non-disposing secondary cache. - mro-processor C3 ordering test: pins EXTENDS-before-IMPLEMENTS parent grouping for classes with interleaved edge additions. Asserts exact MRO ['Base', 'Iface'] — a revert to single-loop insertion-order iteration would produce ['Iface', 'Base'] and fail loudly. - cached-tree parity test: emitPythonScopeCaptures(src, path, T) returns identical CaptureMatch[] to emitPythonScopeCaptures(src, path). Pins the cache-hit path's correctness so a regression that silently returns stale captures would break the test. P3: - Dev-mode cache counters moved from captures.ts to cache-stats.ts. Production hot-path module no longer carries the module-global export surface; PROF gating behavior preserved. - ParseOutput field rename astCache → scopeTreeCache. Clarifies that the surfaced cache is the persistent cross-phase one, not the chunk-local astCache parse-impl clears between chunks. Single consumer (scopeResolutionPhase) updated; no other readers. - ASTCacheReader interface extracted. scopeResolutionPhase now reads the phase dep via a shared type instead of a hand-rolled inline structural shape that could drift from ASTCache's contract. - graph.ts dual-index invariant enforced through writeRel/deleteRel private helpers instead of duplicated add/delete at 3 mutation sites. Adding a new mutation method only needs to call the helpers — forgetting to update one index becomes structurally impossible. Tests: 382/382 unit (incl. 2 new), 191/191 python integration both flag paths. tsc clean. * fix(ci): prettier formatting + Python-migration test adjustments CI run 24666612657 failed on three jobs. Fixes: quality/format: - Prettier --check flagged 3 files after the accumulated branch work. Ran prettier --write from repo root (CI's invocation cwd) to apply: simple-hooks.ts, resolve-references.ts, python-hooks.test.ts. tests/{ubuntu,macos,windows} — 9 assertion failures, all traceable to Python landing in MIGRATED_LANGUAGES (default-on registry-primary): - registry-primary-flag.test.ts (3 tests): the 'returns false by default' / 'primaryLanguages empty' / 'Python mid-process mutation' assertions were written in Ring 2 when MIGRATED_LANGUAGES was empty. Rewrote to assert MIGRATED_LANGUAGES membership is the default, use Java (unmigrated) for the no-stale-cache test, and verify env overrides work in both directions (migrated-off, unmigrated-on). - call-processor.test.ts (6 tests in SM-10 + D2-widen blocks): these exercise the LEGACY call-resolution DAG on .py fixtures. processCalls now gates Python out (isRegistryPrimary === true by default), returning 0 edges. Added REGISTRY_PRIMARY_PYTHON=false override in the relevant beforeEach + restore in afterEach, so the legacy DAG runs for these test-local fixtures without affecting the production-default behavior. Local verification: 4126/4126 unit tests pass, prettier clean. * docs(python): known-limitation block on scope-resolution public API Unit 10 — document what the Python registry-primary path intentionally does not resolve, so reviewers and future maintainers can distinguish conscious trade-offs from latent bugs: - Dynamic attribute access (getattr / setattr) - Dynamic imports (importlib, __import__) - Metaclass-driven dispatch - Union / Optional branch-picking behavior - Arbitrary signature-rewriting decorators - typing.TYPE_CHECKING-guarded imports - *args / **kwargs type flow-through - super() outside a directly-bound method Each item names the file that owns the relevant hook so a future follow-up knows where to start. Shadow-harness corpus parity + the CI parity gate remain the authoritative signal for which of these matter at fleet scale. * docs: record scope-resolution pipeline alongside legacy call DAG Capture what shipped in #980 so future readers don't have to reverse- engineer the coexistence of the legacy call-resolution DAG and the new scope-resolution pipeline: - ARCHITECTURE.md: new 'Scope-Resolution Pipeline' section after the Call-Resolution DAG, documenting pipeline stages, ScopeResolver contract, per-language registration, code references, and perf notes. Coexistence block added to the legacy DAG section explaining how MIGRATED_LANGUAGES gates the two paths per-language. - AGENTS.md: reference-docs pointer updated — legacy-DAG one-liner stays; scope-resolution pipeline gets its own pointer so agents know when to read which section. Changelog bumped. - type-resolution-system.md: callout at the 'call-processor.ts is the consumer' claim pointing readers to the scope-resolution path for migrated languages. TypeEnv is still built per file, but for migrated languages receiver typing flows through ParsedTypeBinding rather than call-processor.ts. CHANGELOG.md intentionally not touched — owned by the release process. * chore: remove obsolete scheduled_tasks.lock file * fix(scope-resolution): qualified-name keys for same-file method collisions Review feedback from PR #980 reviewer flagged a BLOCKING correctness bug: when two classes in the same file define a method with the same simple name (e.g. class User: def save + class Document: def save), every d.save() CALLS edge silently resolved to User.save because the graph node lookup keyed only by (filePath, simpleName) and first-wins took User's method. Three-layer fix: 1. populateClassOwnedMembers now promotes a nested def's qualifiedName from `save` to `ClassName.save` when the def sits inside a class scope. Python's scopes.scm doesn't emit @declaration.qualified_name for methods, so without this the finalized SymbolDefinition carried only the simple name. 2. buildGraphNodeLookup adds a second key per node: (filePath, qualifiedName). For Method/Function nodes the qualifier is parsed deterministically out of the node id (`Method:file.py:User.save#N` → `User.save`), which is robust to Windows-style filePath colons. Simple-name key retained as a fallback for callers that don't know the qualifier. 3. resolveDefGraphId now tries the qualified key first, then falls back to the simple-name lookup. Also addresses the non-blocking review items: - scopeResolutionPhase.deps now includes `crossFile` so the Kahn's runner can't schedule scope-resolution before crossFile finishes writing heritage edges that buildMro consumes. - run.ts no longer mutates the finalized ScopeResolutionIndexes via `as` cast — spreads into a fresh object with the populated methodDispatch field instead. - Doc nits: scope-resolver.ts registry path + phase.ts Ring number. Test coverage: - New fixture test/fixtures/lang-resolution/python-same-file-method-collision with User.save + Document.save in one file and app.py calling both through typed receivers. - Three new integration assertions pin that u.save() and d.save() target the correct qualified node id. Fail before the fix, pass after. Confirmed by running once without populateClassOwnedMembers qualifier promotion — reproduces the original User.save-for-both bug. Verification: 194/194 test/integration/resolvers/python.test.ts pass both REGISTRY_PRIMARY_PYTHON=0 and =1. 523/523 related unit tests. tsc --noEmit clean. * fix(scope-resolution): filter export index to module-level defs + label-prefixed qualified key Codex adversarial review on PR #980 flagged that buildWorkspaceResolutionIndex feeds defsByFileAndName and callablesBySimpleName from parsed.localDefs — the flat set of every def in the file including methods, fields, and nested functions. findExportedDef / findExportedDefByName treat those maps as file-level exports, so `mod.save()` could silently bind to User.save whenever a method's simple name appeared first in parse order. Plan: docs/plans/2026-04-21-001-fix-workspace-index-module-scope-only-plan.md Fix layers: 1. workspace-index.ts: split the single parsed.localDefs loop into two passes: - Module-export pass: iterate moduleScope.ownedDefs PLUS ownedDefs of every child scope whose parent is the module scope. Top-level class and function declarations each live in their own scope with parent=module, not in moduleScope.ownedDefs directly, so the "parent === moduleScope.id" walk is required to reach them. Methods (scope.parent === Class scope) and nested functions (scope.parent === another Function scope) are excluded. - Member-by-owner pass: keeps iterating parsed.localDefs since that map is keyed on ownerId and correctly saw class-owned defs before this change. 2. graph-bridge/node-lookup.ts: qualified keys now live in a separate keyspace (`<q>:filePath::<label>::<qualifiedName>`) and include the node label. Without the label prefix, a top-level `def save` (Function, qualifier `save`) would collide with a class method `User.save` (Method, simple name `save`) in the same simple-key slot because the Function's qualifier happens to equal the Method's simple name. The label differentiates them. 3. graph-bridge/ids.ts: resolveDefGraphId uses the new type-prefixed qualified key when def.type is set. Simple-name fallback retained for languages that don't yet synthesize qualifiers on their defs. Test fixture: python-module-export-vs-method-collision places `class User: def save` BEFORE top-level `def save` — parse order that exposes the bug (class method enters the index first). Three new integration assertions: - `mod.save(x)` resolves to the module-level Function, not User.save - `u.save()` resolves to User.save Method - Exactly two CALLS edges to `save` exist, one per intended target Fixture confirmed failing before the workspace-index fix (bug reproduced), passing after. Verification: 197/197 test/integration/resolvers/python.test.ts pass both REGISTRY_PRIMARY_PYTHON=0 and =1. 523/523 related unit tests. tsc --noEmit clean. * fix(scope-resolution): drive module export index from moduleScope.bindings Codex round-2 adversarial review flagged that the workspace-index module-export pass iterated every def in every direct-child scope of the module, including class-body Variable defs like `class User: MAX_USERS = 100`. `defsByFileAndName[file][MAX_USERS]` silently aliased to the class attribute. Latent today because Python doesn't emit ACCESSES edges for `mod.NAME` member access, but the index-layer leak would surface the moment reference capture widens. Plan: docs/plans/2026-04-21-002-fix-codex-round2-scope-resolution-plan.md Drive the module-export index from the extractor invariant instead of a scope-kind → allowed-label switch: moduleScope.bindings already contains exactly the names visible at module level — top-level class/function declarations, module-level variable assignments, imports. Class methods, class-body attributes, and nested-function defs bind to their containing (Class or Function) scope, not the module, so they're naturally excluded. Filter to `BindingRef.origin === 'local'` so imports and wildcard re-exports stay out of the index (matches the pre-fix invariant when the source was `parsed.localDefs`). No per-kind predicates, no scope-kind / def-kind enumeration, no two-pass merge between moduleScope.ownedDefs and direct-child scope walks — one loop, language-agnostic. Codex also flagged `propagateImportedReturnTypes` as potentially broken for function-local imports, but scope-dump probing showed the finalize algorithm puts `from svc import get_user` into the MODULE scope's finalized bindings even when declared inside a function, so the existing module-scope propagation already handles the case. The new python-function-local-import-chain integration test pins that working behavior as a regression guard; no code change required. Coverage: - test/unit/scope-resolution/workspace-index.test.ts (new, 5 tests) — directly asserts the index shape. The "excludes class-body Variable defs" test fails without this fix and passes after (confirmed via stash-pop probe). - test/integration/resolvers/python.test.ts — 4 new integration assertions across two describe blocks (python-class-attr-export-leak, python-function-local-import-chain) pin end-to-end invariants. - Two new fixtures under test/fixtures/lang-resolution/. Verification: 201/201 test/integration/resolvers/python.test.ts both REGISTRY_PRIMARY_PYTHON=0 and =1. 528/528 related unit tests (was 523). tsc clean. * test(scope-resolution): pin local-namespace-import behavior + document empirical finalize hoisting Codex round-3 adversarial review raised three concerns about scope-resolution passes assuming module-scope semantics that would contradict `pythonImportOwningScope`'s documented per-scope contract. Empirical verification via scope-dump probes resolved each: Plan: docs/plans/2026-04-21-003-fix-codex-round3-scope-aware-resolution-plan.md 1. Function- and class-local namespace imports: VERIFIED WORKING. `def outer(): import svc as s; s.call()` and `class A: import mod; def use(self): mod.helper()` both emit CALLS edges with reason "scope-resolution: namespace-receiver". finalize-algorithm hoists the ImportEdges onto `indexes.imports[moduleScope]` regardless of where the `import` statement appears, so collectNamespaceTargets' module-scope read finds them. 2. Imported return-type propagation module-scope-only: VERIFIED WORKING (already pinned in round 2). `from svc import get_user` inside a function body lands in indexes.bindings[moduleScope], so propagateImportedReturnTypes' module-scope read still finds it. 3. Nested method-local defs stamped as class members: VERIFIED FALSE. The scope extractor creates nested Function scopes for inner `def`s; `def helper` inside `def save` inside `class User` lives in helper's own Function scope whose parent is save's Function scope (NOT the Class scope). populateClassOwnedMembers' `parentScope.kind === 'Class'` branch correctly skips it; helper.ownerId stays undefined. Instead of implementing speculative scope-aware refactors that the tests would pass regardless, this commit: - Adds regression fixtures and integration assertions that pin each working behavior. If finalize routing ever changes to honor the hook's per-scope contract, these assertions flip red and signal the need for the scope-chain-aware refactor. - Adds defensive JSDoc to the three flagged call sites (collectNamespaceTargets, propagateImportedReturnTypes, populateClassOwnedMembers) documenting the empirical invariant so future reviewers don't re-derive Codex's theoretical concern without the benefit of the probe. Files: - Two new fixtures under test/fixtures/lang-resolution/ covering the function-local and class-body namespace-import patterns. - Two new describe blocks in test/integration/resolvers/python.test.ts (3 assertions, positive-pin intent). - Defensive comments in namespace-targets.ts, imported-return-types.ts, and scope-resolution/scope/walkers.ts. Verification: 204/204 test/integration/resolvers/python.test.ts both REGISTRY_PRIMARY_PYTHON=0 and =1. tsc clean. * perf(graph): reverse-adjacency + file indexes drop removeNode/removeNodesByFile from O(N) PR #980 in-line review flagged that `removeNode` iterated the full relationshipMap to find edges touching a node (O(E)), and `removeNodesByFile` called removeNode for every matching node after a full nodeMap scan (O(N × E)). Pre-existing, but worth fixing properly since the writeRel/deleteRel helpers we just added make the index-maintenance story coherent. Two new indexes maintained on every mutation path: - `edgeIdsByNode: Map<nodeId, Set<relId>>` — reverse adjacency. Every edge records both endpoints, so removeNode iterates edgeIdsByNode.get(id) instead of every relationship. Self-edges skip the duplicate-endpoint write to keep the Set dedup explicit. - `nodeIdsByFile: Map<filePath, Set<nodeId>>` — file index. removeNodesByFile reaches its file's nodes directly. Complexity: - removeNode: O(edges-touching-node), was O(total-edges). - removeNodesByFile: O(file-nodes × avg-edges-per-node + scan of the file bucket), was O(total-nodes + file-nodes × total-edges). Index maintenance is centralized in writeRel/deleteRel + new addToBucket/removeFromBucket helpers. Empty buckets are pruned to keep the indexes compact. Existing dual-invariant (relationshipMap ↔ relationshipsByType) preserved. Nodes without a `filePath` property (e.g. Community/Cluster nodes) are intentionally NOT indexed in nodeIdsByFile — they can't belong to any file, so removeNodesByFile correctly leaves them alone. Coverage: 7 new unit tests (33/33 total, was 26). Added cases: - removes only edges touching the removed node - handles self-edges - removes orphan node with no edges - removeNodesByFile removes only matching nodes - returns 0 when no match - also removes edges whose endpoints lived on the removed file - does not index nodes without a filePath property Verification: 204/204 test/integration/resolvers/python.test.ts both REGISTRY_PRIMARY_PYTHON=0 and =1. 4235/4235 unit tests. tsc clean. * refactor(ingestion): merge python/ast-utils into utils/ast-helpers; iterative findNodeAtRange python/ast-utils.ts held three language-agnostic helpers (nodeToCapture, syntheticCapture, findNodeAtRange) plus two duplicates of the shared utils version (findChildOfType == findChild; findIdentifierChild was unused). Consolidating into utils/ast-helpers.ts so the next language migrating to the scope-resolution pipeline imports from one place. findNodeAtRange rewritten iteratively using an explicit stack. Previous implementation was recursive — fine for shallow Python trees today, but a landmine for languages with deeper nesting (Kotlin sealed-hierarchy decomposition, Rust macro expansion, etc.) and the task hooks explicitly call out "no recursion". Children are pushed reverse-index so LIFO pop visits them left-to-right; row-bound pruning preserves the prior early-skip optimization (the `break` shortcut is replaced with `continue` since a stack can't leverage ordered sibling termination). findChildOfType consumers migrated to the existing findChild helper. findIdentifierChild deleted — no callers remained. Coverage: 204/204 test/integration/resolvers/python.test.ts both REGISTRY_PRIMARY_PYTHON=0 and =1. 339/339 scope-resolution + graph unit tests. tsc clean. * refactor(scope-resolution): remove unused shouldShadow / shouldCreateScope hooks Both LanguageProvider hooks were dead weight: - `shouldShadow` had zero call sites — the interface declared it, Python implemented a trivial always-true no-op, but no consumer ever read it. The shadowing decision lives in pythonMergeBindings and the central merge algorithm, not in a per-scope predicate. - `shouldCreateScope` had one call site in pass1BuildScopes but the only language implementing it (Python) always returned true. No producer ever emits a `@scope.block` for Python, so the hook's "declines to create" branch was unreachable. Other languages didn't implement it at all. Removing both: - Drops the interface declarations in language-provider.ts. - Drops `shouldCreateScope` from ScopeExtractorHooks Pick and from the pass1BuildScopes conditional — the stack-based parent-resolve loop becomes unconditional. - Drops pythonShouldShadow / pythonShouldCreateScope from simple-hooks, the Python index barrel, and the python.ts provider wiring. - Drops the tests that exercised the removed hooks: one block- suppression scenario in scope-extractor.test.ts, one shouldCreateScope test in parse-worker-scope-integration.test.ts, and the pythonShouldShadow / pythonShouldCreateScope always-true assertions in python-hooks.test.ts. pythonBindingScopeFor's delegate-to-default test is preserved in its own describe block. Shadowing itself is unchanged: pythonMergeBindings still runs, LEGB ordering still applies, wildcard transparency is still handled via the merge precedence rules. The hook API just no longer has a vestigial per-scope toggle we decided not to use. Verification: 204/204 test/integration/resolvers/python.test.ts both REGISTRY_PRIMARY_PYTHON=0 and =1. 335/335 scope-resolution + graph unit tests (was 339, net -4 after removing the hook-specific assertions). tsc clean. * refactor(scope-resolution): drop dead exports surfaced by knip Knip flagged 44+ dead exports in the PR surface. Cleanup: Barrel deletion: - Remove src/core/ingestion/scope-resolution/index.ts entirely. It re-exported 30+ symbols but only one file (languages/python/scope-resolver.ts) imported from it, and only 7 symbols. Matches the project's "no barrel re-exports" preference and removes a drift surface. scope-resolver.ts now imports from concrete files (passes/mro.ts, scope/walkers.ts, contract/...). Dead functions/interfaces removed: - resolvePythonScope + ResolvePythonScopeInput + ResolvePythonScopeStats in languages/python/scope-resolver.ts — never called. pipelinePhase reaches pythonScopeResolver via SCOPE_RESOLVERS, not via a per-language entry point. - getScopeResolver in scope-resolution/pipeline/registry.ts — had zero callers. Consumers read SCOPE_RESOLVERS directly. Exports demoted to module-internal (used only within their own file): - PYTHON_SCOPE_QUERY (query.ts) + its re-export from python/index.ts - PROF (cache-stats.ts) - PythonArityMetadata (arity-metadata.ts) - ReferenceSiteSkipSet (graph-bridge/references-to-edges.ts) - ReceiverBoundProviderSubset (passes/receiver-bound-calls.ts) - ResolveCompoundReceiverOptions interface (passes/compound-receiver.ts) - matchingOpenParen function (passes/compound-receiver.ts) - followChainPostFinalize function (passes/imported-return-types.ts) - RunScopeResolutionInput + RunScopeResolutionStats (pipeline/run.ts) Also removed: - Redundant `export type { Scope }` re-export from contract/scope-resolver.ts (consumers import Scope directly from gitnexus-shared). Verification: knip reports zero dead exports in PR-touched files. 204/204 test/integration/resolvers/python.test.ts both flag paths. 335/335 scope-resolution + graph unit tests. tsc clean. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> Co-authored-by: Gergo Magyar <gergomagyar@icloud.com>	2026-04-21 15:50:00 +01:00
Gergő Magyar	6222b5be9b	feat(ingestion): emit-references drains ReferenceIndex to graph edges (#925, RFC #909 Ring 2 PKG) (#973)	2026-04-18 23:36:10 +01:00
Gergő Magyar	e2ba4a04c9	feat(ingestion): shadow-mode parity harness + static dashboard (#923, RFC #909 Ring 2 PKG) (#972) ... * feat(ingestion): shadow-mode parity harness + static dashboard (#923, RFC #909 Ring 2 PKG) Side-car observability for the RFC #909 registry rollout. Callers that dual-run legacy-DAG + `Registry.lookup` feed their result pairs into the harness; the harness diffs each pair via shared `diffResolutions` (#918), aggregates via `aggregateDiffs`, and persists a per-language parity report that the static dashboard can render offline. ## Shipped ### `gitnexus/src/core/ingestion/shadow-harness.ts` (new) ```ts createShadowHarness(): ShadowHarness ``` API: - `enabled` — `true` iff `GITNEXUS_SHADOW_MODE` is truthy at construction. Captured once; later env-var mutations don't flip it. - `record({ language, callsite, legacy, newResult, primary })` — accumulator. No-op when `enabled === false` (near-zero overhead). - `size()` — diagnostic counter. - `snapshot(now?)` — deterministic `ShadowParityReport` from the accumulated diffs. - `persist(outputDir, now?)` — writes BOTH a timestamped `<runId>.json` and a `latest.json` pointer. Creates outputDir if absent. Returns the per-run file path. - `clear()` — resets the accumulator; preserves `enabled`. Activation: `GITNEXUS_SHADOW_MODE` accepts `'true'` / `'1'` / `'yes'` (case-insensitive, trimmed); same truthy convention as `REGISTRY_PRIMARY_<LANG>` from #924. Typos → disabled (fail-safe). Persisted payload (`PersistedShadowReport`) is schema-versioned (`v1`): ```jsonc { "schemaVersion": 1, "runId": "YYYYMMDD-HHMMSS-xxxxxxxx", "generatedAt": "ISO 8601", "primaryByLanguage": { "python": "legacy", ... }, "report": { /* ShadowParityReport from #918 aggregateDiffs */ } } ``` `runId` prefix is the timestamp so files sort chronologically; the entropy suffix prevents collisions within a clock-second. ### `gitnexus/shadow-parity-dashboard/index.html` (new) Minimal static dashboard — one HTML file, zero build step, zero runtime deps. Fetches `./latest.json` and renders: - Overall summary cards (total calls, both agree, disagree, overall parity %) - Per-language table: language tag ("primary: legacy" / "primary: registry" pill) + total / agree / only-legacy / only-new / disagree / both-empty / parity% - Parity cells colored by threshold: ≥95% green, ≥80% amber, <80% red - Light / dark via `prefers-color-scheme` - Empty-state message when no records yet File-serving is static: `cp .gitnexus/shadow-parity/latest.json gitnexus/shadow-parity-dashboard/` + open in a browser. ## Tests (14, all passing) - **Flag detection** (5): default off · truthy variants case-insensitive · falsy / typo → off · record() is no-op when disabled · env flip AFTER construction doesn't enable (constructed-once semantics) - **Record + snapshot** (4): multi-language accumulation · per-language rows with correct outcomes · snapshot determinism · `clear()` resets accumulator + `primaryByLanguage` - **Persistence** (5): mkdir-p on missing outputDir · per-run + latest.json match byte-for-byte · schema v1 payload shape · runId timestamp prefix sorts chronologically · empty report persists gracefully Tests use a per-test tmpdir (`fs.mkdtemp`), cleaned in `afterEach`, so parallel vitest runs don't collide. `GITNEXUS_SHADOW_MODE` is saved + restored per-test. ## What's deliberately NOT in this PR (call-out in harness docstring) - **Dual-run dispatch.** The harness is a side-car — it does NOT invoke either resolution path. Call-processor integration that actually runs both legacy + registry paths lands as a follow-up. Without that integration, `record()` is never called in production today. The harness is tested in isolation with synthetic inputs. - **CI artifact publishing.** Config work to upload `latest.json` + the dashboard HTML per CI run. Tracked separately; the harness + dashboard are ready when the CI job wires in. - **Fixture-level drill-down.** The issue mentions per-fixture AST snippet + evidence trace drill-down. MVP dashboard shows per-language rows only; drill-down extends the static JSON format + the dashboard JS in a focused follow-up. ## Verification - `tsc --noEmit` clean (both `gitnexus-shared` and `gitnexus`) - 14/14 new tests pass - Full scope-resolution / shadow / model / flag suite: **335/335 pass** ## Part of - Parent: #909 - Depends on (code): #917 (registries), #918 (diff + aggregate) - Unblocks Ring 3 language flips: the parity dashboard becomes the checkpoint before flipping `REGISTRY_PRIMARY_<LANG>=true` for a language — once per-language parity stabilizes, the flip ships. * chore: prettier format on shadow-parity-dashboard index.html	2026-04-18 21:30:43 +01:00
Gergő Magyar	0c37eda482	feat(ingestion): per-language resolveImportTarget adapter (#922, RFC #909 Ring 2 PKG) (#971) ... Bridges the CLI's existing per-language `ImportResolverFn`s (16 languages already implemented) to the shared `FinalizeHooks.resolveImportTarget` contract consumed by `finalize()` (#915) and `finalizeScopeModel` (#921). No resolver logic is reimplemented — the adapter wraps `provider.importResolver` from each `LanguageProvider` verbatim. ## Shipped ### `import-target-adapter.ts` (new) ```ts buildImportTargetWorkspace(providers, resolveCtx): ImportTargetWorkspace resolveImportTargetAcrossLanguages(targetRaw, fromFile, workspaceIndex): string | null ``` - `ImportTargetWorkspace` is the opaque `workspaceIndex` shape the adapter recognizes: `{ perLanguage: Map<SupportedLanguages, { resolver, ctx }> }`. Callers build it once per ingestion run from the active language providers. - `resolveImportTargetAcrossLanguages` is the `FinalizeHook` implementation. It: 1. Reads `getLanguageFromFilename(fromFile)`. 2. Looks up the per-language entry. 3. Calls the existing `ImportResolverFn` — same signature, same code path the legacy DAG uses today. 4. Picks `result.files[0]` (covers both `'files'` and `'package'` result kinds; the legacy pipeline's richer multi-file + dirSuffix semantics stay accessible through `importResolver` directly). 5. Returns `null` on any null result, empty files[], unknown extension, missing workspace, or resolver exception. - Exceptions from resolvers are swallowed — the finalize algorithm treats `null` as `linkStatus: 'unresolved'`, which is the right fallback for malformed inputs. ### What's deliberately NOT here - **Re-implementation of any per-language resolver.** Wraps the existing `importResolver` field on each provider. - **Dynamic-import handling.** The shared finalize algorithm short- circuits `ParsedImport { kind: 'dynamic-unresolved' }` before calling `resolveImportTarget`, so the adapter never sees them. - **`importPathPreprocessor`.** Preprocessing belongs inside the provider's `interpretImport` hook that produces `ParsedImport.targetRaw`; the adapter forwards that verbatim. ## Tests (12, all passing) - **`buildImportTargetWorkspace`** (3): registers providers with importResolver · skips providers without · threads shared ctx into every entry - **`resolveImportTargetAcrossLanguages`** (9): forwards targetRaw + fromFile · dispatches by extension · null resolver result → null · `package`-kind takes first file · empty files[] → null · no registered resolver → null · unknown extension → null · undefined/malformed workspace → null · resolver throw → null Real per-language resolver correctness is covered by the existing per-language resolver test suites — the adapter is the bridge layer. ## Verification - `tsc --noEmit` clean (both `gitnexus-shared` and `gitnexus`) - `gitnexus-shared` build clean - 12/12 new tests pass - Full scope-resolution / shadow / model / flag suite: **333/333 pass** ## Integration flow ```ts const workspace = buildImportTargetWorkspace(providers, resolveCtx); const indexes = finalizeScopeModel(parsedFiles, { hooks: { resolveImportTarget: resolveImportTargetAcrossLanguages }, workspaceIndex: workspace, }); model.attachScopeIndexes(indexes); ``` ## Closes part of #909. Unblocks - Ring 3 language migrations (#926+): a language flipping to `REGISTRY_PRIMARY_<LANG>=true` now has correct import-target resolution out of the box via its existing `importResolver`. - #923 shadow harness — can run the dual-path comparison knowing both sides use the same per-language resolution semantics.	2026-04-18 21:11:24 +01:00
Gergő Magyar	25520e90a5	feat(ingestion): finalize-orchestrator materializes ScopeResolutionIndexes (#921, RFC #909 Ring 2 PKG) (#970) ... Ties the Ring 2 pipeline together. Takes the `ParsedFile[]` produced by #920's parse-worker integration, feeds them to shared `finalize()` (#915), and bundles every workspace-wide index for attachment onto `MutableSemanticModel`. Thin integration glue per issue #884's boundary — all algorithm lives in `gitnexus-shared`. ## Shipped ### `model/scope-resolution-indexes.ts` (new) ```ts interface ScopeResolutionIndexes { readonly scopeTree: ScopeTree; readonly defs: DefIndex; readonly qualifiedNames: QualifiedNameIndex; readonly moduleScopes: ModuleScopeIndex; readonly methodDispatch: MethodDispatchIndex; readonly imports: ReadonlyMap<ScopeId, readonly ImportEdge[]>; readonly bindings: ReadonlyMap<ScopeId, ReadonlyMap<string, readonly BindingRef[]>>; readonly referenceSites: readonly ReferenceSite[]; readonly sccs: readonly FinalizedScc[]; readonly stats: FinalizeStats; } ``` The bundle produced by the orchestrator, consumed by the resolution phase. `ReferenceIndex` is deliberately NOT here — it's populated in the next phase (#925). ### `model/semantic-model.ts` — extended - `SemanticModel.scopes?: ScopeResolutionIndexes` — undefined until attached; once attached, frozen. - `MutableSemanticModel.attachScopeIndexes(indexes)` — one-shot write. Throws on second call; `Object.freeze`s the bundle on write. `clear()` resets the slot back to `undefined` so re-ingestion can re-attach. ### `finalize-orchestrator.ts` (new) ```ts finalizeScopeModel(parsedFiles, options?): ScopeResolutionIndexes ``` Orchestration steps: 1. Map `ParsedFile[]` → `FinalizeInput` (`FinalizeFile` is a structural subset, so no shape-shifting). 2. Call shared `finalize()` with provider hooks (defaults provided for the zero-provider case today). 3. Build the four workspace indexes (`DefIndex`, `QualifiedNameIndex`, `ModuleScopeIndex`, `ScopeTree`) from per-file unions. 4. Build an empty `MethodDispatchIndex` as a placeholder (owners=[], both callbacks return []). Real MRO wiring lands with the per-language adapters in #922. 5. Bundle + return. **Empty-input safety.** Zero parsedFiles → valid but empty bundle with all zero-sized indexes and `stats.totalFiles === 0`. Downstream code can consult `model.scopes` without branching on presence — only on `stats`. **Hook defaults** (`withDefaultHooks`) for missing provider hooks: - `resolveImportTarget: () => null` — every import goes `unresolved` - `expandsWildcardTo: () => []` — wildcards don't materialize - `mergeBindings: (a, b) => [...a, ...b]` — append without precedence Providers override these in #922 (per-language import adapters). ## Tests (10, all passing) - **Empty input** (1): zero parsedFiles → valid empty bundle - **Single file** (2): all per-file indexes populated · referenceSites aggregated - **Cross-file imports** (3): resolveImportTarget threads through + links · default-null resolver → unresolved · stats reflect graph - **MutableSemanticModel integration** (4): undefined initially · attach once · Object.freeze applied · throws on re-attach · clear() resets ## Verification - `tsc --noEmit` clean in both packages - `gitnexus-shared` build clean - 10/10 new tests pass - Full scope-resolution / shadow / model / flag suite: **321/321 pass** ## What's deferred (not this PR, per RFC #909 scope) - **Per-language hook adapters** (#922): `resolveImportTarget` + `expandsWildcardTo` + `mergeBindings` wired per language. - **MethodDispatchIndex wiring via HeritageMap**: populate MRO + implements via the existing CLI-package HeritageMap strategies. Likely companion to #922 or a focused follow-up. - **Pipeline invocation**: actually calling `finalizeScopeModel` from the real ingestion pipeline. The orchestrator is callable today; the ingestion entry point wiring lands with the shadow harness (#923). - **`ReferenceIndex` population**: RFC §3.2 Phase 4 / #925. ## Closes part of #909. Unblocks - #923 shadow harness — now has a fully materialized `model.scopes` to query against the legacy DAG for parity measurement - #925 ReferenceIndex → LadybugDB emission — consumes `model.scopes` - Ring 3 language migrations (#926+) — a language flipping to `REGISTRY_PRIMARY_<LANG>=true` can now expect `model.scopes` to be populated when the pipeline wires the orchestrator in	2026-04-18 20:51:19 +01:00
Gergő Magyar	39b5d295c7	feat(ingestion): wire ScopeExtractor into parse-worker + processor (#920, RFC #909 Ring 2 PKG) (#969) ... Plumbs the ScopeExtractor (#919) into the real parsing pipeline. `ParsedFile` artifacts now flow from workers to the parsing-processor without changing any legacy-DAG behavior. ## Shipped ### `gitnexus/src/core/ingestion/scope-extractor-bridge.ts` (new) - `extractParsedFile(provider, sourceText, filePath, onWarn?)` - Short-circuits (returns `undefined`) when the provider has not implemented `emitScopeCaptures`. True for every language today — this is the default no-op path. - Invokes the hook + `ScopeExtractor.extract`, returns a `ParsedFile`. - **Swallows exceptions on both sides.** Failures route through the optional `onWarn` callback (or `console.warn`) and return `undefined`. Scope-extraction errors NEVER break legacy parsing on the same file. - Standalone module (not nested in `parse-worker.ts`) so tests can import it directly without triggering the worker's top-level `parentPort!.on(...)`. ### `gitnexus/src/core/ingestion/workers/parse-worker.ts` - `ParseWorkerResult.parsedFiles: ParsedFile[]` added. - `processFileGroup` calls `extractParsedFile` AFTER tree parse, BEFORE legacy extraction. Worker provides an `onWarn` callback that routes bridge warnings through `parentPort.postMessage({ type: 'warning', message })`. - `mergeResult` includes `parsedFiles` in the sub-batch merge. - Initial + reset accumulator templates include `parsedFiles: []`. ### `gitnexus/src/core/ingestion/parsing-processor.ts` - `WorkerExtractedData.parsedFiles: ParsedFile[]` added. - Empty-result branch and the across-chunk aggregation both include `parsedFiles`. Aggregation is tolerant of workers that don't emit the field (older builds / partial rollouts). ### Ring 1 tweak: `emitScopeCaptures` sync return `readonly CaptureMatch[]` (was `Promise<readonly CaptureMatch[]>`). Tree-sitter and COBOL's regex tagger are both synchronous; no foreseeable need for async work inside this hook. Sync lets the already-sync worker pipeline invoke it inline without cascading `async` up through the batch driver + IPC handler. ## Tests (9 new; full suite 311/311) `gitnexus/test/unit/scope-resolution/parse-worker-scope-integration.test.ts`: - Not-migrated (2): undefined-returning hook · never-invokes-extractor - Migrated (3): happy path · argument threading · honors `shouldCreateScope` override - Error resilience (4): hook throws · extractor throws (no Module) · extractor throws (sibling overlap) · `onWarn` gets routed message with filePath + error body ## Verification - `tsc --noEmit` clean in both packages - `gitnexus-shared` build clean - 311/311 combined scope-resolution / shadow / model / flag suite - 9/9 new bridge tests ## What's NOT in this PR (still deferred to #921) - Actually using the `parsedFiles` — that's the finalize orchestrator. - `ModuleScopeIndex.byFilePath` materialization — belongs alongside the rest of the SemanticModel indexes in #921. ## Closes part of #909. Unblocks - #921 finalize-orchestrator — consumes `WorkerExtractedData.parsedFiles`	2026-04-18 20:27:56 +01:00
Gergő Magyar	c6a291de67	feat(ingestion): ScopeExtractor driver — 5-pass CaptureMatch → ParsedFile (#919, RFC #909 Ring 2 PKG) (#965) ... * feat(ingestion): ScopeExtractor driver — 5-pass CaptureMatch → ParsedFile (#919, RFC #909 Ring 2 PKG) Kicks off Ring 2 PKG. Implements RFC §5.3 + §3.2 Phase 1: the central, source-agnostic driver that turns a language provider's `CaptureMatch[]` into a `ParsedFile` — the per-file artifact the finalize orchestrator (#921) feeds into the shared `finalize()` algorithm (#915). ## Files ### New shared contracts - `gitnexus-shared/src/scope-resolution/parsed-file.ts` Per-file extraction artifact: scopes, parsedImports, localDefs, referenceSites. Structural superset of `FinalizeFile` so the finalize orchestrator threads `ParsedFile` through unchanged. - `gitnexus-shared/src/scope-resolution/reference-site.ts` Pre-resolution usage fact: name, atRange, inScope, kind, optional callForm/explicitReceiver/arity. Converted to `Reference` records by the resolution phase (populates `ReferenceIndex`). ### Ring 1 collateral tweak - `language-provider.ts: emitScopeCaptures` now returns `Promise<readonly CaptureMatch[]>` (was `readonly Capture[]`). Pre-grouping per tree-sitter match is the provider's job — the extractor expects coherent matches, not flat captures. No consumers yet (all languages still on legacy DAG), so no breakage. Docstring updated. ### New CLI module - `gitnexus/src/core/ingestion/scope-extractor.ts` Single entry point: `extract(matches, filePath, provider): ParsedFile`. Five-pass pipeline: Pass 1 — Build scope tree. `@scope.*` → `ScopeDraft[]` via range-containment parent derivation. Honors `provider.shouldCreateScope` (skip-but-reparent-children) and `provider.resolveScopeKind`. Throws `ScopeTreeInvariantError` via `buildScopeTree` on malformed input. Pass 2 — Attach declarations + local bindings. `@declaration.*` → `SymbolDefinition` + `BindingRef { origin: 'local' }`. Default attachment: innermost containing scope. Hoisting via `provider.bindingScopeFor`. Pass 3 — Collect raw imports. `@import.*` → `ParsedImport` via `provider.interpretImport`. Attached to ParsedFile (finalize resolves owning scope in Phase 2). Pass 4 — Collect type bindings. `@type-binding.*` → `TypeRef` via `provider.interpretTypeBinding` → `scope.typeBindings`. Hoistable via `bindingScopeFor`. Pass 5 — Collect reference sites. `@reference.*` → `ReferenceSite[]`. Call form from declarative sub-tag (`@reference.call.member`) or `provider.classifyCallForm`. ### Tests - `gitnexus/test/unit/scope-resolution/scope-extractor.test.ts` 23 tests organized by pass + one end-to-end fixture exercising all 5 passes together. MockProvider emits synthetic `CaptureMatch[]` with no AST — extractor is pure given those. ## Design notes - **Source-agnostic.** No `Tree` / `SyntaxNode` types leak into the driver. Works for tree-sitter providers and COBOL's regex tagger. - **One AST walk per language.** Providers do the walk inside `emitScopeCaptures`; this driver does zero traversal. - **Invariants delegated.** `ScopeTree.buildScopeTree` enforces structural rules (non-Module has parent, parent contains child, siblings don't overlap). The extractor doesn't try to repair malformed captures. - **Sub-tag whitelist.** `@reference.receiver`, `@declaration.name`, `@import.source`, etc. are known sub-tags — excluded from anchor selection so the broadest-range heuristic doesn't mis-identify them as anchors for their topic. Bug surfaced in the end-to-end fixture test (member call with a large-range receiver) and was fixed before commit. ## Verification - `tsc --noEmit` clean (both `gitnexus-shared` and `gitnexus`) - `gitnexus-shared` build clean - 23/23 new tests pass - Full scope-resolution / model / shadow suite: **285/285 pass** ## Closes part of #909. Unblocks - #920 parse-worker integration (emit ParsedFile from the worker) - #921 finalize orchestrator (consume ParsedFile[] workspace-wide) - #922 per-language import adapters * chore(ingestion): address #919 review findings on the extractor Addresses all 5 items from the PR #965 review in-PR. ## Structural changes - **Extract `ScopeExtractorHooks` as the narrow dependency surface.** The extractor now declares its dependency on a `Pick`-narrowed subset of `LanguageProvider` (just the 6 scope-resolution hooks it actually reads). Test mocks implement exactly that interface — no more `as unknown as LanguageProvider` cast hiding missing-field bugs. Adding a new hook read becomes a compile error, not a silent test pass. (Finding 3.2) - **Remove dead `ownerDefIdFor` stub + `isOwnerKind` helper.** The function always returned `undefined` with `void innermost; void drafts;` suppressors — an incomplete-implementation signal. The code path was also misleading: creating a clone of the def with `ownerId: undefined` is structurally identical to keeping the original. Pass 2 now keeps the def as-is. Contract is documented in a code comment: providers that need `ownerId` set it from their declaration hook; `finalize` (via #914 `MethodDispatchIndex`) fills in method/field `ownerId` in a post-extraction pass that has full def visibility. (Finding 2.1) - **Standardize `filePath` threading across passes 4 and 5.** Pass 4 was reading `drafts[0]!.filePath`; pass 5 was reading `anyFilePathFromScopeTree(scopeTree)`. Both equivalent but inconsistent. Both now take `filePath` as a parameter from the top-level `extract()` call. The `anyFilePathFromScopeTree` helper is removed. (Finding 2.2) ## Documentation - **Snapshot-semantics comment on `scopeTree` + `positionIndex`.** The hooks called during Passes 2-5 receive a `scopeTree` built BEFORE any bindings/ownedDefs/typeBindings were written. Hooks MUST NOT rely on `scope.bindings` etc. being populated — they're for parent/range/kind queries only. Added a doc block at the `scopeTree`/`positionIndex` construction site so future Ring 3 implementers don't write a `classifyCallForm` that reads bindings. (Finding 2.3) ## Tests - **Regression for the anchor-vs-receiver bug** (Finding 3.1): a member-call match where `@reference.receiver` spans columns 0-10 (wider) and the call name spans 11-15 (narrower). Without the `KNOWN_SUB_TAGS` exclusion, the broadest-range heuristic would have picked the receiver; the test pins that the call name is the one that ends up in `referenceSites[0].name`. - **Mock provider now types exactly `ScopeExtractorHooks`**, no more double-cast. Any future hook added to `extract()` that isn't in `ScopeExtractorHooks` is a compile error. ## Verification - `tsc --noEmit` clean in both `gitnexus-shared` and `gitnexus` - `gitnexus-shared` build clean - 24/24 scope-extractor tests pass (+1 regression) - Full scope-resolution / model / shadow suite: **286/286 pass**	2026-04-18 19:28:51 +01:00
Gergő Magyar	e944f90879	chore(shared): apply Ring 2 SHARED review follow-ups in one diff (#964) ... * chore(shared): apply Ring 2 SHARED review follow-ups in one diff Aggregates all actionable follow-ups from the 9 Ring 2 SHARED PRs (#949–#963) before proceeding to Ring 2 PKG. No behavior changes; docstring edits, test refinements, and one structural cleanup. ## #913 (DefIndex / ModuleScopeIndex / QualifiedNameIndex) - Rename `freezeIndex` → `wrapIndex` across all three index builders. The old name implied `Object.freeze` on the wrapper, which we never applied; `wrapIndex` more accurately describes the lightweight readonly-interface wrap. Safety surface (frozen bucket arrays, frozen miss-empty array, readonly Maps) is unchanged. - Document in `buildModuleScopeIndex` JSDoc that callers must pre-normalize `filePath` keys (no path-separator canonicalization happens here). Prevents silent cross-platform misses. - Add an explicit hit-path freeze assertion in `qualified-name-index.test.ts` (the existing test covered only the miss-path `EMPTY` array). ## #914 (MethodDispatchIndex) - Differentiate the C3 and BFS test cases: both tests now use distinct MRO orderings so they prove the materializer stores whatever order the `computeMro` callback produces (not that C3 and BFS yield identical output). - Add `implementsOfCalls` counter in the first-write-wins test, and document the call-count contract in `MethodDispatchInput.implementsOf` JSDoc: `implementsOf` fires **per occurrence** in `input.owners` (not per unique owner); `computeMro` fires at most once per unique owner. Callers with expensive `implementsOf` implementations should pre-dedupe `owners`. ## #916 (resolveTypeRef) - Document the deliberate exclusion of `'Type'` from `TYPE_KINDS` (verified no extractor in `gitnexus/src/core/ingestion/` emits `type: 'Type'` for annotation-relevant symbols). - Rename the namespace-origin test from `'resolves ...'` to `'returns null for a namespace-origin binding whose def is not a type kind'`, matching the failure-case intent. ## #918 (shadow diff + aggregate) - Remove the partial re-export `export type { ShadowAgreement, ShadowDiff };` from `aggregate.ts` — it omitted `ShadowCallsite` and diverged from the top-level barrel. Consumers import all three from the `gitnexus-shared` entry point. - Fix the invalid `'wildcard'` evidence kind in `diff.test.ts` fixture (that kind is not a valid `ResolutionEvidence.kind`). Replaced with `'global-name'`, a real kind the test treats identically. ## #912 (ScopeTree / PositionIndex / makeScopeId) - Document the touching-boundary semantics on `PositionIndex.atPosition`: when siblings share a boundary point, the right (later-start) sibling wins per the existing innermost-wins sort contract. - Resolve the layer-inversion flagged by review: move `ScopeLookup` from `resolve-type-ref.ts` to `types.ts` (its natural home in the data-model layer). `scope-tree.ts` now imports `ScopeLookup` from `types.js` directly; the old re-export from `resolve-type-ref.ts` is removed per repo convention (`feedback_no_reexport`). Barrel export moved alongside. ## #917 (ClassRegistry / MethodRegistry / FieldRegistry) - Replace the dangling "try a name-match among class-like defs" comment in `lookupReceiverType` with explicit prose that callers must pre-resolve via `resolveTypeRef` if they want richer semantics. No behavior change — the function already returned `undefined` on ambiguous/missing qnames. - Fix `tieBreakKey.origin` default for pure Step-2 candidates. Type-binding-only hits no longer falsely inherit `'local'` from `ensureCandidate`'s neutral default; they now demote to `'import'` on their first type-binding hit, and only a later Step-1 lexical hit can upgrade them back to `'local'`. Keeps the Appendix B cascade faithful to the true origin. - Document `'global-name'` in `evidence.ts`: currently reserved for Ring 3's byName global index; `lookupCore` never emits it today. The weight stays live so `composeEvidence` remains exhaustive over the origin union. - Rename the mislabeled Step-7 test from `'confidence DESC is the primary key'` (which actually tested hard-shadow baseline) to `'inner scope shadows outer, yielding single result'`, and add a separate test that actually exercises multi-candidate confidence ordering (local vs wildcard at the same scope). ## Verification - `tsc --noEmit` clean (both `gitnexus-shared` and `gitnexus`) - `gitnexus-shared` build clean - Combined scope-resolution / model / shadow suite: **260/260 pass** (+1 from the new multi-candidate ordering test in #917) ## Not addressed (non-actionable) - #949 CI "failure with zero failing tests": pre-existing Swift Node 22 grammar flake unrelated to #910 scope. - #950: the two non-blocking findings were already addressed in follow-up commit `cbac32ba` (ParsedImport discriminated union + `ScopeId | null` on the two hooks). - #915: the five in-scope findings were already addressed in follow-up commit `54515a7e` (dead code, unused params, multi-hop docs, cap-hit test, stats granularity). - #915 LanguageProvider.resolveImportTarget signature divergence + `findDefById` O(F×D) perf: tracked separately as follow-up issues for the Ring 3 migration window. * chore(shared): address ce:review findings on the follow-up diff ce:review (interactive) on PR #964 surfaced two P2s and several P3s. This commit applies all `safe_auto` fixes + both manual tests in-line so the PR ships with a cleaner review trail. ## P2 fixes - **Complete `freezeIndex` → `wrapIndex` rename.** The prior commit renamed 3 of 5 sibling index files; `method-dispatch-index.ts` and `position-index.ts` still carried the old name. Now all 5 helpers use the consistent `wrapIndex` naming. (maintainability + project-standards reviewers both flagged this.) - **Add regression tests for the `recordTypeBindingHit` origin demotion.** The prior commit introduced the `tieBreakKey.origin = 'import'` demotion for Step-2-only candidates without a direct test. Added: - `registries.test.ts`: two Step-2-only siblings under the same interface, asserting deterministic DefId.localeCompare tie-break AND the stronger invariant that composeEvidence never emits a where-found signal for Step-2-only candidates (no `signals.origin`). - `position-index.test.ts`: touching-boundary test proving the right-sibling-wins rule documented in the new JSDoc. (testing + kieran-typescript + api-contract reviewers all flagged these gaps.) ## P3 fixes - Fix wrong comment in `recordTypeBindingHit` that claimed Step 1 could later upgrade a demoted origin. Step 1 runs BEFORE Step 2 — the actual upgrade path is Step 3 (`seedFromOwnerScopedContributor`). Comment now describes execution order correctly. - Fix inaccurate "re-exported there" comment in `index.ts`. `types.ts` *defines* ScopeLookup natively; it's not a re-export. Phrasing now says "defined in types.ts and exported from the type-export block above — not from this module." - Update stale `scope-tree.ts` file-header prose that still referenced `ScopeLookup` as living in #916/resolve-type-ref.ts. Now points to `./types.js` with a cross-ref to both #916 and #917 consumers. - Expand `atPosition` touching-boundary JSDoc to name the mechanism (backward scan through start-sorted array) so readers can trace the binary-search code to the claim. - Add breadcrumb to `aggregate.ts` module header pointing future readers to `./diff.ts` / the top-level barrel for `ShadowAgreement`, `ShadowCallsite`, and `ShadowDiff`. - Remove unnecessary non-null assertion in `recordTypeBindingHit`. Local `const existingMroDepth = ...` lets TS narrow to `number` in the else-branch, eliminating the `!` without behavior change. ## Verification - `tsc --noEmit` clean (both `gitnexus-shared` and `gitnexus`) - `gitnexus-shared` build clean - Combined scope-resolution / model / shadow suite: **262/262 pass** (+2 from the new origin-demotion + touching-boundary regression tests)	2026-04-18 18:40:29 +01:00
Gergő Magyar	1bf9fb4ef1	feat(shared): ClassRegistry / MethodRegistry / FieldRegistry + 7-step lookup (#917, RFC #909 Ring 2 SHARED) (#963) ... Capstone of Ring 2 SHARED. Implements RFC §4 — the shared, scope-aware resolution surface the rest of the semantic model feeds into. ## Modules (`gitnexus-shared/src/scope-resolution/registries/`) - `context.ts` — `RegistryContext` bundling ScopeTree / DefIndex / QualifiedNameIndex / ModuleScopeIndex / MethodDispatchIndex + provider hooks. Narrows Ring 1's opaque `RegistryContributor` to concrete `OwnerScopedContributor`. - `tie-breaks.ts` — `compareByConfidenceWithTiebreaks`, the RFC Appendix B cascade: confidence DESC → scope depth ASC → MRO depth ASC → ORIGIN_PRIORITY ASC → DefId.localeCompare. - `evidence.ts` — `composeEvidence(signals)` / `confidenceFromEvidence`. Translates raw walk signals into the typed `ResolutionEvidence[]` using authoritative `EvidenceWeights`. No magic numbers. - `lookup-qualified.ts`— RFC §4.5. Qualified-name fast path consumed by `resolveTypeRef` dotted fallback and by Step 6 of lookup-core. - `lookup-core.ts` — The 7-step canonical algorithm. Pure. Param- eterized by `CoreLookupParams`. - `{class,method,field}-registry.ts` — Thin wrappers over `lookupCore` that fix `acceptedKinds` + `useReceiverTypeBinding` per kind. `buildClassRegistry` / `buildMethodRegistry` / `buildFieldRegistry` factory functions. ## RFC §4.2 algorithm contract (honored verbatim) 1. Lexical scope-chain walk. Hard shadow on any `scope.bindings.has(name)` regardless of kind survivorship. 2. Type-binding resolution (methods/fields only, opt-in via `useReceiverTypeBinding`). MRO walk via `MethodDispatchIndex.mroFor`. MRO-depth-decayed weight via `typeBindingWeightAtDepth`. 3. Owner-scoped contributor — when the caller knows the receiver owner, its direct members merge in as `origin: 'local'`. 4. Kind filter — `acceptedKinds` per registry; `kind-match` evidence at weight 0 is always emitted for debuggability. 5. Arity filter — `provider.arityCompatibility` per candidate. When at least one compatible candidate exists, incompatibles are dropped; otherwise the −0.15 penalty alone disambiguates (they stay in the result, just ranked lower). 6. Global fallback — fires only when Steps 1-3 produced NO candidates AND the name is dotted. Delegates to `lookupQualified`. 7. Rank + tie-break — evidence list sorted by the Appendix B cascade. ## §4.7 invariants asserted in tests - No tier vocabulary in the return type (`Resolution`, not `TierXResult`). - Confidence is per-candidate (not per-tier). - Shadowing is a HARD filter; globals are consulted ONLY when lexically empty. - Caller can read `[0]` for one-shot answers. - `Resolution.confidence` is capped at 1.0. - `kind-match` is always emitted (weight 0). ## Unresolved-import + dynamic-unresolved evidence shape - `BindingRef.via.linkStatus === 'unresolved'` applies the `unlinkedImportMultiplier` (0.5×) to the where-found signal only. Corroborators (`arity-match`, `owner-match`, `type-binding`) remain unaffected — the RFC §4v2 capped-signal rule applies per-signal, not per-candidate. - `BindingRef.via.kind === 'dynamic-unresolved'` adds a degraded `dynamic-import-unresolved` evidence signal at weight 0.02. ## Tests (28 in registries.test.ts, 259/259 combined) Organized per RFC §4.2 step so a regression localizes to the step it broke: - Step 1: local + walk-to-parent + hard-shadow + origin=import - Step 2: explicit receiver type-binding + MRO depth decay on ancestor - Step 3: owner-scoped contributor + owner-match - Step 5: drop-incompatible-when-compatible-exists + soft-penalty-when-all- incompatible + unknown-when-no-provider - Step 6: global-qualified fires only when lexically empty + never for non-dotted names + not consulted when lexical hit exists - Step 7: tie-break cascade (inner shadows outer; defId.localeCompare final) - Corroborators: unresolved-import 0.5× cap per-signal + dynamic- unresolved 0.02 degraded signal - §4.5: lookupQualified kind filter + empty on miss + deterministic defId order for partial classes - §4.7: invariants — confidence per-candidate, capped at 1.0, kind-match always present, [0]-for-one-shot ## Known follow-up optimizations `collectOwnedMembers` in `lookup-core.ts` iterates `defs.byId.values()` for each MRO hop — O(D) per call. Acceptable for Ring 2 fixtures; a by-owner index should land before Ring 3 migrates large-workspace languages. Tracked alongside the existing `findDefById` follow-up from #915 review. ## Module placement All under `gitnexus-shared/src/scope-resolution/registries/` — consistent with the Ring 2 SHARED folder layout (#912/#913/#914/#915/#916/#918). Slight deviation from the issue's `gitnexus-shared/src/registries/` suggestion for consistency with siblings. ## Part of - Parent: #909 - Depends on (code): #910, #911, #912, #913, #914, #915, #916, #918. - Closes the Ring 2 SHARED delivery band. Unblocks Ring 2 PKG (#919–#925 bridges to the gitnexus/ CLI package) and Ring 3 language migrations.	2026-04-18 17:58:26 +01:00
Gergő Magyar	a9a5e1c388	feat(shared): SCC-aware finalize algorithm with bounded fixpoint (#915, RFC #909 Ring 2 SHARED) (#962) ... * feat(shared): SCC-aware finalize algorithm with bounded fixpoint (#915, RFC #909 Ring 2 SHARED) Implements RFC §3.2 Phase 2 as pure logic in `gitnexus-shared`. Takes per-file parse output and returns linked `ImportEdge[]` + materialized module-scope bindings, fully language-agnostic (target resolution, wildcard expansion, and binding precedence all go through caller hooks). Three-phase algorithm: 1. Tarjan SCC over the file-level import graph (iterative, deterministic node order, O(V+E)). Returns SCCs in reverse-topological order so leaves finalize before dependents — and so disjoint SCCs are explicitly surfaced for parallel-processing callers. 2. Per-SCC bounded fixpoint. For each SCC in topo order, iterate up to `N = |intra-SCC edges|`; each pass tries to resolve every still- unlinked edge by looking up the imported name in the target file's local defs. Stops early when no progress. Edges still unlinked after the cap get `linkStatus: 'unresolved'` — keeps malformed inputs bounded and preserves the RFC §4v2 capped-signal contract for unresolved markers. 3. Wildcard expansion + module-scope binding materialization. For each `wildcard` ParsedImport that linked to a module, expand via `expandsWildcardTo` into one `wildcard-expanded` ImportEdge per exported name. Bindings per module scope are the merge of local defs (`origin: 'local'`), named / alias / reexport imports (`origin: 'import' | 'reexport'`), namespace imports (`origin: 'namespace'`), and wildcard expansions (`origin: 'wildcard'`), with precedence delegated to `provider.mergeBindings`. Dynamic imports rule: `kind: 'dynamic-unresolved'` passes through as an ImportEdge with `targetFile: null` and no BindingRef. Re-export flattening: reexport edges land with `transitiveVia: [targetFile]`. Multi-hop chains settle iteratively across the fixpoint. Types: - Adds `'wildcard'` variant to ParsedImport (parse-time signal for `import * from M`). The finalize-only `'wildcard-expanded'` ImportEdge kind is unchanged and remains finalize output only, as documented. - Exports `finalize` + `FinalizeFile` / `FinalizeInput` / `FinalizeHooks` / `FinalizeOutput` / `FinalizedScc` / `FinalizeStats`. Simple-name derivation: `deriveSimpleName` uses `def.qualifiedName` as the authoritative source (tail after the last `.`). Defs without a qualifiedName are not name-resolvable by this algorithm — an explicit design choice that trades strictness for predictability (no heuristic nodeId parsing). Tests (20, all passing): - Trivial: empty workspace · acyclic resolution · unresolvable target (file + name) · dynamic-unresolved passthrough. - Cycles: A↔B two-file cycle linked · cycles packed into SCC with isCycle=true · disjoint cycles produce disjoint SCCs · mixed linked/unresolved edges reported correctly in stats. - Wildcards: one ImportEdge per exported name · unresolved wildcards survive as single edges · expanded bindings carry origin='wildcard'. - Reexports: transitiveVia carries the intermediate file path. - Aliased + namespace: alias preserves targetExportedName under its local name · namespace links to module scope even without a module-def. - Bindings: locals land as origin='local' · imports layer on via mergeBindings · mergeBindings can drop existing (last-write-wins precedence honored). - SCC-DAG: reverse-topological ordering verified (leaf first). Combined scope-resolution / model / shadow suite: 229/229 pass. `tsc --noEmit` clean in both `gitnexus-shared` and `gitnexus`. Closes part of #909. Unblocks #917 (Registry.lookup's import-chain fast path consumes finalized ImportEdges); unblocks Ring 3 language migrations (per-language providers supply FinalizeHooks implementations). * chore(shared): address #915 review findings — dead code, docs, tests Review thread on PR #962. Code changes: - Remove dead `resolvedTargets` map + `keyFor` + `ParsedImportKey` type alias. The map was populated but never read; originally intended to cache / dedup resolutions for later phases but that path was never wired (finding 1.1). - Drop unused params (`_edgeIndex`, `_hooks`, `_workspace`) from `tryFinalize`. No planned fixpoint-state consultation; no reason to keep them reserved (finding 2.1). Documentation: - `FinalizeFile.localDefs` now documents the multi-hop re-export contract explicitly: `finalize` looks names up in the target's static `localDefs`; if B only re-exports from C and doesn't surface the name in its own localDefs, A's import of that name from B will hit the cap and be marked unresolved. Parsers that want multi-hop chains to settle end-to-end must include re-exported names in the intermediate file's localDefs (finding 1.2). - `FinalizeStats` now documents its counting granularity: all edge counters are per-`ParsedImport`, not per-materialized-`ImportEdge`. A wildcard expanding to N exports counts as one linked edge; dynamic-unresolved pass-throughs count as linked. The bindings map is the authoritative "has a BindingRef" source (finding 3.2). Tests (2 added, 22 total in finalize-algorithm.test.ts, 231/231 combined): - Explicit cap-hit → `linkStatus: 'unresolved'` assertion for a cycle where the name-level lookup never succeeds (distinct from `targetFile: null`; cap exhaustion path) (finding 3.1). - Multi-hop re-export contract test: demonstrates both variants — intermediate B WITHOUT X in localDefs → unresolved; B WITH X in localDefs → resolved to the original source DefId (finding 1.2). Not addressed (filed as follow-up issues): - LanguageProvider.resolveImportTarget vs FinalizeHooks signature divergence (finding 1.3) — pre-Ring-3 concern. - findDefById O(F×D) scan in Phase 5 (finding 4.1) — acceptable for Ring 2; optimize before large-workspace Ring 3 migrations.	2026-04-18 17:26:07 +01:00
Gergő Magyar	8cf9ae0e0d	feat(shared): ScopeTree + PositionIndex + makeScopeId (#912, RFC #909 Ring 2 SHARED) (#961) ... Implements the scope-tree spine and position-indexed lookup as pure logic in `gitnexus-shared`. Generalizes the `enclosingFunctions` pattern from closed PR #902 to arbitrary `ScopeKind`s. Three modules under `gitnexus-shared/src/scope-resolution/`: 1. `scope-id.ts` — `makeScopeId({filePath, range, kind})` builds the canonical RFC §2.2 shape `scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}` and interns the result through a process-local pool so repeated calls with structurally identical inputs return the same string reference. `clearScopeIdInternPool()` exported for test isolation. 2. `scope-tree.ts` — `buildScopeTree(scopes)` validates invariants and returns an immutable `ScopeTree`: - `getScope(id)` / `getParent(id)` / `getChildren(id)` / `getAncestors(id)` - Implements the `ScopeLookup` contract from #916, so `resolveTypeRef` can consume a `ScopeTree` directly (test included). Invariants enforced (throw `ScopeTreeInvariantError` on violation): - Non-Module scopes must have a parent. - Parent must exist in the supplied set. - Parent range STRICTLY contains child range (equal ranges rejected). - Sibling ranges under the same parent do not overlap. Ranges that merely touch at the boundary (`a.end == b.start`) are accepted. - Parent and child live in the same filePath. - Duplicate scope ids are rejected. 3. `position-index.ts` — `buildPositionIndex(scopes)` produces a `PositionIndex` with `atPosition(filePath, line, col)`. Per-file sorted array; binary-search the upper bound of `start ≤ query`, scan backward through the prefix, return the first containing hit. Complexity: `O(log N_file + D)` typical (D = lexical depth ≤ ~10); degrades to `O(N_file)` only under pathological inputs (many scopes starting at the same position). "Innermost wins" falls out of the sort + backward-scan contract because `ScopeTree`'s invariants guarantee that scopes containing a point form an ancestor chain. Types: - `ScopeTree` now exported from `scope-tree.ts`. The Ring 1 opaque placeholder in `types.ts` has been removed; LanguageProvider hooks that previously took `ScopeTree = unknown` now receive the concrete interface (CLI `tsc --noEmit` passes — no existing callers rely on the opaque shape). Tests (39, all passing): - scope-id: canonical shape · all six ScopeKinds encoded · identity equality (same inputs → same reference) · distinguished by filePath / range / kind · purity under repeated calls · intern-pool clear preserves canonical shape. - scope-tree: empty tree · single module · nested Module→Class→Function · multiple siblings input-order preserved · ScopeLookup integration with resolveTypeRef · frozen children and ancestor arrays · all six invariant violations (non-Module orphan, parent-not-found, parent doesn't contain, parent == child, siblings overlap, cross-file parent, duplicate id) · boundary-touching siblings accepted. - position-index: empty · unindexed filePath · before/after-file queries · start/end inclusivity · innermost-wins for nested / co- starting / co-ending / same-line scopes · sibling dispatch · multi- file isolation · size · id-dedup. Combined scope-resolution / model / shadow suite: 190/190 pass. `tsc --noEmit` clean in both `gitnexus-shared` and `gitnexus`. Closes part of #909. Unblocks #917 (`Registry.lookup` needs the scope spine); makes `ScopeLookup` in #916 concrete without API churn.	2026-04-18 16:41:38 +01:00
Gergő Magyar	5d76dbcfa2	feat(shared): MethodDispatchIndex materialized view over HeritageMap (#914, RFC #909 Ring 2 SHARED) (#960) ... Implements RFC §3.1 `MethodDispatchIndex`: a two-way materialized view keyed by `DefId` for O(1) method-dispatch resolution: - `mroByOwnerDefId` — owner class → full MRO ancestor chain (excludes self, per-language strategy order) - `implsByInterfaceDefId` — interface/trait → classes that implement it **Not an MRO implementation.** `buildMethodDispatchIndex` is a pure aggregator that calls back into caller-provided `computeMro` and `implementsOf` functions. The five existing strategies (Python C3, Ruby kind-aware, Java/Kotlin linear, Rust qualified-syntax, COBOL none) stay where they are today (`model/resolve.ts`, `languages/ruby.ts`); this index does not reimplement them. Why callbacks rather than a shared registry: the strategies depend on the CLI's `HeritageMap` + `SemanticModel`. Migrating both to `gitnexus-shared` is out of scope for #914; callbacks let the shared build stay pure. Module placement: `gitnexus-shared/src/scope-resolution/method-dispatch-index.ts` for consistency with the other RFC §3.1 indexes (#913 DefIndex / ModuleScopeIndex / QualifiedNameIndex; #916 resolveTypeRef). Safety surface mirrors sibling indexes: - First-write-wins on duplicate owners. - Repeated (interface, owner) pairs deduplicated. - Stored arrays are `Object.freeze`d; caller mutation of the source array does not leak into the index. - Miss returns a shared frozen empty array. Tests (19, all passing): empty input, single-inheritance chain, Python C3 diamond, Java BFS, Ruby kind-aware mixin, Rust qualified-syntax empty, interface inversion (single, multiple, ordered), dedup within and across callback calls, frozen miss + bucket arrays, callback-array isolation, readonly Map iteration. Closes part of #909.	2026-04-18 16:28:46 +01:00
Gergő Magyar	56e32b310b	feat(shared): resolveTypeRef strict single-return type resolver (#916, RFC #909 Ring 2 SHARED) (#959) ... Implements RFC §4.6: a strict, pure resolver for `TypeRef`s 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): 1. Walk the scope chain from `ref.declaredAtScope`: - Return the first binding for `rawName` whose origin is in `{'local','import','namespace','reexport'}` AND whose `def.type` is a type-kind (class-like, interface-like, enum-like, alias-like). - If bindings exist but none qualify (non-type shadow, wildcard-only origin), return null immediately — do NOT fall through to the global qualified-name index. 2. If `rawName` is dotted and the scope walk produced no match, consult `QualifiedNameIndex.byQualifiedName`. Only accept a UNIQUE type-kind hit; ambiguous or non-type results return null. `'wildcard'` is deliberately excluded from strict origins — a wildcard-expanded name is too loose to anchor type resolution. Module placement: `gitnexus-shared/src/scope-resolution/resolve-type-ref.ts` (alongside sibling indexes) rather than the issue's suggested `gitnexus-shared/src/resolve-type-ref.ts`, for consistency with the rest of the RFC §2/§3 surface. A minimal `ScopeLookup` interface is declared inline so #916 ships standalone; #912's `ScopeTree` will satisfy this contract without change. Closes part of #909.	2026-04-18 16:09:54 +01:00
Gergő Magyar	ac2012e5ed	feat(shared): DefIndex / ModuleScopeIndex / QualifiedNameIndex (#913, RFC #909 Ring 2 SHARED) (#958) ... Three flat O(1) indexes + pure build functions over per-file artifacts. Contract-only; no runtime behavior change yet — consumers (#917 Registry lookups, #915 SCC finalize, #919 ScopeExtractor) wire in later. Each index follows the same shape: - build function: flat input list → frozen immutable index - public interface: readonly Map + get/has/size accessors - first-write-wins on id/filePath collisions (upstream bug signal) - pure, side-effect-free, safe to call repeatedly DefIndex — the global "what is this id?" lookup gitnexus-shared/src/scope-resolution/def-index.ts buildDefIndex(defs: readonly SymbolDefinition[]): DefIndex byId: ReadonlyMap<DefId, SymbolDefinition> Consumed by Registry.lookup (#917) to materialize DefId[] hits back to full SymbolDefinition records. ModuleScopeIndex — `filePath → moduleScopeId` for cross-file hops gitnexus-shared/src/scope-resolution/module-scope-index.ts buildModuleScopeIndex(entries): ModuleScopeIndex byFilePath: ReadonlyMap<string, ScopeId> Consumed by the SCC finalize link pass (#915) to resolve ImportEdge.targetFile to a concrete module scope in constant time. QualifiedNameIndex — cross-kind qualified-name fast path gitnexus-shared/src/scope-resolution/qualified-name-index.ts buildQualifiedNameIndex(defs: readonly SymbolDefinition[]): QualifiedNameIndex byQualifiedName: ReadonlyMap<string, readonly DefId[]> Returns DefId[] (not a single DefId) because partial classes, method overloads, and cross-kind collisions can legitimately share a qualifiedName. Callers filter by acceptedKinds at the lookup site. Consumed by Registry.lookup qualified fast path + resolveTypeRef dotted fallback (#916, #917). Barrel re-exports added to gitnexus-shared/src/index.ts so consumers import from 'gitnexus-shared' rather than deep paths. Tests (gitnexus/test/unit/scope-resolution/, 23 total): def-index.test.ts (6): empty, single def, multiple distinct, first-write-wins collision, missing id returns undefined, byId direct iteration module-scope-index.test.ts (6): empty, single entry, multiple files, first-write-wins on duplicate filePath, missing returns undefined, byFilePath direct iteration qualified-name-index.test.ts (11): empty, single qnamed def, partial classes accumulate, input-order preservation, qname separation, skip undefined/empty qname, pair dedup, cross-kind indexing, frozen-empty-array on miss, direct iteration Verification: - gitnexus-shared + gitnexus build clean (tsc + scripts/build.js) - test/unit/scope-resolution: 23/23 pass - model + shadow + scope-resolution combined: 129/129 pass - No runtime consumer wiring yet — indexes are standalone library functions that #915, #917, #919 will import when ready Depends on #910 (SymbolDefinition, DefId, ScopeId types — already on main). Unblocks #915 (finalize algorithm), #917 (Registry.lookup), #919 (ScopeExtractor materialization).	2026-04-18 15:59:34 +01:00