fix(ingestion): qualify Ruby same-tail nested mixin modules + route IMPLEMENTS by scope (#1991)

[magyargergo]

Stacked PR 4/5 — base fix/1993-cpp-ns-qualified-inheritance (#2005). Auto-retargets when #2005 merges.

Summary

Follow-up to #1981 / #1982. A Ruby module maps to the Trait label but is not a typeDeclaration, so the structure phase never qualified its node id. Two same-tail nested mixin modules (App::Loggable + Web::Loggable) collapsed onto one Trait:f.rb:Loggable node, and the bare-name include Loggable reference cross-wired IMPLEMENTS via the first-wins tail fallback (dangle-free but wrong).

Fix

Structure phase (node identity). Exposed buildQualifiedName as a qualifyScopeName ClassExtractor hook and threaded it for Trait nodes in parsing-processor.ts + parse-worker.ts (lockstep), so a module node keys by its qualified scope path (App.Loggable). This is not Option A — Trait is not in CLASS_LIKE_LABELS and the qualified-id selection gates it out, and extractQualifiedName bails on non-typeDeclarations; qualifyScopeName bypasses that gate. getQualifiedOwnerName also falls back to qualifyScopeName, so methods inside a nested module own through the same qualified Trait id (no dangling HAS_METHOD).

Resolution (cross-wire). emitRubyMixinEdges now resolves a bare mixin reference lexically by the including class's enclosing scope (App::S + Loggable → App::Loggable), and the simple-tail fallback is delete-on-collision (refuse to guess on a same-tail tie) instead of first-wins.

Module → Trait is preserved; Trait is not added to CLASS_LIKE_LABELS. No language-specific names in shared code — qualifyScopeName is a neutral hook gated on qualifiedNodeId + the Trait label.

Tests

New single-file ruby-nested-mixin-tail-collision fixture + tests:

• Two distinct Trait nodes (App.Loggable / Web.Loggable).
• S IMPLEMENTS App.Loggable only, T IMPLEMENTS Web.Loggable only; one edge each; no dangling IMPLEMENTS / HAS_METHOD.
• Worker-path parity block.

Verification

• ruby resolver suite: registry-primary 149/149, legacy 137 + 12 by-design skips (the registry-primary-only mixin routing is listed in LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES, like the Qualified nested-type node identity — resolution-side follow-up (Ruby same-tail routed-props/mixins + Rust inherent impls) #1982 mixin tests) — both green, including the worker path.
• Fixed a regression the suite caught: methods inside a namespaced module now own through the qualified Trait id (the fix: scoped class/module/impl declarations don't materialize a graph node (dangling HAS_METHOD edges) — PR #1972 P2 follow-up #1975 "no dangling HAS_METHOD" test).
• tsc --noEmit clean; prettier clean; ruby-captures-golden regenerated additively (4 insertions — the new fixture only); ruby-scope-capture-tripwire unaffected; ruby-nested-mixin-shortname / ruby-qualified-mixin / ruby-nested-tail-collision stay green.

Closes #1991.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
gitnexus	Ready	Preview, Comment	Jun 4, 2026 10:19am

[magyargergo]

Tri-review — approve-with-nits

Method: per-PR multi-lens review → independent adversarial re-verification → static-analysis alignment (tsc/eslint/prettier, all clean) → cross-stack synthesis + critic gate.

Review: PR #2006 — Ruby same-tail nested mixin-module Trait qualification (#1991)

Verdict: Approve with nits. This is a clean, well-scoped fix that lands on the real runtime path, holds the language-neutrality line, and ships the right tests (positive node+edge identity, not dangle-only, with worker-parity and exact-match legacy-parity skips). tsc --noEmit is clean and the golden is additive; CHANGELOG is untouched.

What I verified

• Correctness (structure phase). A Ruby module is labeled Trait and is not a typeDeclaration (ruby.ts typeDeclarationNodes: ['class']), so extractQualifiedName bails. The new qualifyScopeName hook reuses buildQualifiedName, which walks ancestorScopeNodeTypes ['module','class'] from node.parent upward → App.Loggable / Web.Loggable, anchored on the @declaration.trait module node. Both qualifiedTypeName and qualifiedName gate the new branch on qualifiedNodeId === true.
• Correctness (resolution). emitRubyMixinEdges now resolves the bare mixin via full-qn → qualifyMixinByOwnerScope (innermost-enclosing-scope-first, matching Ruby constant lookup) → tail map, with the tail map carrying a null collision sentinel so the trailing ?? undefined correctly refuses to guess on a same-tail tie (replacing the old cross-wiring first-wins). The __heritage__ owner is the full qualified name (App.S), and isClassLike includes Trait so module defs populate graphIdByName.
• Cross-language safety. The new getQualifiedOwnerName ?? qualifyScopeName fallback is reachable only when extractQualifiedName returns null. For C++ (the only other qualifiedNodeId language) every owner-container type is a typeDeclaration and there is no bare module AST node, so the fallback is Ruby-active-only and C++ owner ids are unchanged.
• Neutrality. No language names in executable shared code — only in comments. Gating is on the generic Trait registry label + the qualifiedNodeId flag via the optional qualifyScopeName? hook. Trait is correctly kept out of CLASS_LIKE_LABELS and the inheritance machinery (explicitly not Option A).
• Tests. Distinct-Trait-node assertion runs on both legs (structure-phase fix is leg-independent); routing tests resolve rel.targetId and assert the target's qualifiedName + exactly-one-edge-per-source; worker-parity block re-runs through the pool with a usedWorkerPool guard; the three registry-primary-only test names match the LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES['ruby'] registrations byte-for-byte.
• Sequential ↔ worker paths are a faithful lockstep.

Strengths

• Reuses the existing C++/Rust scoped-declaration method ownership + pre-existing tail-keyed nested-type node collision (#1975 / #1977 follow-up) #1978/Qualified nested-type node identity — resolution-side follow-up (Ruby same-tail routed-props/mixins + Rust inherent impls) #1982 qualified-id plumbing instead of forking a new mechanism; the qualifyScopeName hook is the right neutral seam.
• Delete-on-collision sentinel is a genuinely better invariant than first-wins (refuses to guess rather than cross-wire).
• Fixture comment explains why it must be single-file (bare id embeds file.path).

Findings (all minor/nit)

1. [minor] Persisted node-id keyspace split — parsing-processor.ts:682-694. Ruby Trait node ids change to the qualified form; CachedEmbedding is keyed by nodeId, so a default (non-clean) re-analyze skips embedding regen for the split nodes until a full reindex. Same property as the rest of the stack, but Trait/module is a new node class crossing the split — worth a one-line reindex note in the PR/issue.
2. [nit] nodeLabel === 'Trait' hardcoded in 4 spots across two files — parsing-processor.ts:657,688 + parse-worker.ts:1865,1890. Ruby-only today (only Ruby/C++ set qualifiedNodeId, C++ emits no Trait), but if PHP/Dart/Rust adopt the flag their Traits auto-qualify. Consider a shared isQualifiableScopeLabel() predicate + a one-line comment. Readability only.
3. [nit] qualifyMixinByOwnerScope doc — scope-resolver.ts:22-36. Resolves against the full-qn map only; a note that graphIdByName is per-scope-path unique (so the lexical walk can't itself produce a same-tail tie — that's the graphIdByTail null sentinel's job) would aid the next reader.

Note on verification limits

The worker tests in this worktree would run against a stale compiled dist/.../parse-worker.js (src is newer), and rebuilding dist is out of scope for a read-only review, so I verified the worker path by static lockstep comparison against the sequential path rather than executing it. The PR's claimed 149/149 registry-primary + worker-green is consistent with the code I read.

[magyargergo]

Operational note: embedding reindex after this stack lands

CachedEmbedding is keyed by nodeId (embeddings/types.ts), and this lane changes structure-phase node identity — #1991 gives Ruby Trait/module ids a scope qualifier, so same-tail nested mixin modules now carry distinct ids. A default incremental re-analyze regenerates embeddings for the renamed nodes, but a clean re-analyze (or stale-embedding sweep) after the stack merges is the safe call, consistent with the #1978/#1981/#1982 precedent.
For contrast in this stack: #1993 (#2005) is resolution-side only and does not re-key; #1994 (#2007) is a byte-identical refactor.

[github-actions]

CI Report

✅ All checks passed

Pipeline Status

Stage	Status	Details
✅ Typecheck	success	tsc --noEmit
✅ Tests	success	unit tests, 3 platforms
✅ E2E	success	gitnexus-web changes only

Test Results

Tests	Passed	Failed	Skipped	Duration
10589	10573	0	16	599s

✅ All 10573 tests passed

16 test(s) skipped — expand for details

• COBOL pipeline benchmark > scales with file count
• C++ ADL emit benchmark > emit phase scales sub-quadratically with co-scaled files and sites
• C++ pipeline benchmark > scales with file count
• C# pipeline benchmark > scales with file count — namespaces spread across the solution
• C# pipeline benchmark > scales with file count — all types in one (global) namespace bucket
• C# pipeline benchmark > scales with file count — all types in one (named) namespace bucket
• Go pipeline benchmark > scales with file count (workers enabled)
• Go pipeline benchmark — worker pool (issue Worker idle timeout kills long Go scope extraction and surfaces as Napi::Error during analyze #1848) > does not quarantine the large generated Go file on sub-batch idle timeout
• Go structural interface detection benchmark > scales linearly with interface × struct count
• Go structural interface detection split-phase benchmark > separates index-build and detection time
• PHP pipeline benchmark > scales with file count (workers enabled)
• Ruby pipeline benchmark > scales with file count (workers enabled)
• Rust pipeline benchmark > scales with file count (workers enabled)
• Vue pipeline benchmark > scales with component count
• run.cjs direct-exec entrypoint (fix(cli): steer docs, skills, and hooks through a CLI-neutral project-local runner (#1939) #1945) > resolves a .cmd shim via the Windows shell branch, passing args and exit code
• buildTypeEnv > known limitations (documented skip tests) > Ruby block parameter: users.each { |user| } — closure param inference, different feature

Code Coverage

Tests

Metric	Coverage	Covered	Base	Delta	Status
Statements	80.36%	37343/46464	N/A%	—	🟢 ████████████████░░░░
Branches	69.03%	23740/34389	N/A%	—	🟢 █████████████░░░░░░░
Functions	85.59%	3915/4574	N/A%	—	🟢 █████████████████░░░
Lines	84.03%	33611/39998	N/A%	—	🟢 ████████████████░░░░

---

_{📋 View full run · Generated by CI}