feat(cpp): disambiguate template specializations in class graph IDs and receiver routing

[Copilot]

C++ template specializations were being collapsed to a single class identity (List<User> and List<Order> both treated as List), which made member ownership and CALLS targets ambiguous. This change introduces specialization-aware class identity so receiver-bound resolution can route to the correct specialization.

• Graph identity: add specialization fingerprinting for class-like symbols

  • Extended symbol metadata with templateArguments.
  • Added class ID suffixing (~arg1,arg2,...) for class-like nodes when template args are present.
  • Updated graph-bridge lookup/ID resolution to use class template fingerprints, mirroring existing method overload disambiguation (parameterTypes).

• C++ capture + extraction: preserve specialization arguments

  • Added template-argument extraction utilities for nested templates and partial/explicit specialization forms.
  • Extended C++ query captures to include template argument lists for class/struct template names.
  • Wired extraction into worker + sequential parse paths and scope extraction, so templateArguments flow into graph nodes and symbol definitions.

• Receiver-bound routing: specialization-aware class binding fallback

  • In simple type-binding resolution, added template-aware class lookup fallback (List<User> → class def with templateArguments=['User']), with guarded qualified-name fallback behavior.

• Integration coverage: cross-file specialization-specific dispatch

  • Added a new C++ fixture with distinct List<User> / List<Order> behaviors.
  • Added resolver assertions that specialization-specific methods route to their own bodies/sibling calls (no cross-specialization bleed).

// graph-bridge class disambiguation keying (conceptual)
qualifiedKey(filePath, 'Class', `${qualifiedName}~${templateArguments.join(',')}`);

// e.g. Class:file.h:List~User vs Class:file.h:List~Order

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
gitnexus	Ready	Preview, Comment	May 14, 2026 1:35pm

[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
8985	8984	0	1	430s

✅ All 8984 tests passed

1 test(s) skipped — expand for details

• 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	78.14%	28387/36328	N/A%	—	🟢 ███████████████░░░░░
Branches	66.49%	17988/27050	N/A%	—	🟢 █████████████░░░░░░░
Functions	82.96%	2849/3434	N/A%	—	🟢 ████████████████░░░░
Lines	81.43%	25640/31487	N/A%	—	🟢 ████████████████░░░░

---

_{📋 View full run · Generated by CI}

[magyargergo]

@copilot review inline comments from github-actions and fix them!

[Copilot]

@copilot review inline comments from github-actions and fix them!

Addressed the actionable github-actions inline comments in commit 0083058.

• Moved C++-specific class-capture skip/template-arg fallback behavior behind class-extractor hooks (so shared ingestion pipeline no longer hardcodes C++ AST node types).
• Fixed class template fingerprint lookup key registration to first-wins in node-lookup.ts to avoid forward-declaration/definition overwrite behavior.
• Re-ran validation: npx tsc --noEmit and npx vitest run test/integration/resolvers/cpp.test.ts (all passing).

[github-actions]

Claude finished @magyargergo's task in 9m 16s —— View job

---

Second-Pass Production-Readiness Review — PR #1587

Tasks:

• Initialize review
• Read repo docs (AGENTS.md, GUARDRAILS.md, CONTRIBUTING.md, TESTING.md, ARCHITECTURE.md)
• Inspect changed files (all 20)
• Inspect related/targeted files
• Run hygiene checks (Unicode/bidi, git diff --check)
• Verify prior finding closure
• Trace end-to-end example
• Post full review

---

1. Review Bar for This PR

This PR changes how class-like graph node IDs are fingerprinted, how the graph-bridge lookup resolves class defs, and how receiver-bound calls choose member owners. A silent wrong-ID or wrong-fallback silently corrupts Class, HAS_METHOD, and CALLS edges while node names remain plausible. Review bar: adversarial.

---

2. Current PR State

• Head SHA: 0083058d7222f4e3a44c6dd9c94e180754453a9a (2 commits ahead of what the trigger prompt's "latest visible SHA" 1247a3d showed)
• Status: Draft
• CI: ✅ All 8984 tests passed (CI report from github-actions bot, posted at 12:27:50Z)
• Commits on branch beyond main: 6 total (16ce567 → c2b31d3 → c88a2e0 → 1247a3d → b58bc75 → 0083058)
• Unresolved review comments from github-actions: Both addressed in 0083058

---

3. Branch Hygiene Assessment

Verdict: merge-from-main commit present but harmless and merge-safe

Two merge-from-main commits exist (c2b31d3, b58bc75). The second merge (b58bc75) brought in 5 files from PR #1586 (workspace-wide dependent-base name resolution) — all C++-specific. No UI, Docker, CI, dependency, or release churn in the merge. The 0083058 fix commit then further modified two of those files to address the github-actions review findings. The overall diff from main is bounded to C++ ingestion, graph-bridge, and tests. Rebase is not required for correctness, though a rebase before final merge is advisable to linearize history.

---

4. Prior Finding Closure Status

Finding 1 — qualifiedNames.get(...).length crash guard
CLOSED. QualifiedNameIndex.get() is defined in gitnexus-shared/src/scope-resolution/qualified-name-index.ts:85:

get(qualifiedName: string): readonly DefId[] {
  return byQualifiedName.get(qualifiedName) ?? EMPTY;  // EMPTY = Object.freeze([])
}

The return is always an array; .length is safe. Both call sites in receiver-bound-calls.ts (line 96 and line 526) are correct.

Finding 2 — Non-template C++ class extraction regression
CLOSED. cppClassConfig.extractName returns undefined when nameNode.type !== 'template_type' (covers plain class Foo, struct Bar, enum Baz). In generic.ts:149:

const name = config.extractName?.(node) ?? extractTypeNameFromNode(node) ?? fallback?.name;

The fallback to extractTypeNameFromNode is correct and always fires for non-template classes.

Finding 3 — Specialized fallback ambiguity
CLOSED for ODR-compliant code. In resolveClassBindingForName (receiver-bound-calls.ts:81–116): when exactly one def matches wantedArgs, that def is returned. The fallback at line 115 (findClassBindingInScope(scopeId, baseName, scopes)) only fires when matches.length !== 1 (zero matches = no specialization found, or multiple = ODR violation). Both cases are either harmless (returns undefined) or a C++ compile-time violation that is outside V1 scope.

Finding 4 — ID fingerprint consistency
CLOSED. All three paths use the same join(',') format:

• node-lookup.ts:113: ${qualified}~${props.templateArguments.join(',')}
• ids.ts:106: ${qn}~${def.templateArguments.join(',')}
• parsing-processor.ts:655: templateArgumentsIdTag(classTemplateArguments) = ~${args.join(',')}

These produce identical fingerprints. qualifiedKey format is identical in both files.

Finding 5 — Test coverage for closure points
PARTIALLY ADDRESSED — see new Finding A below.

---

5. Understanding of the Change

The PR introduces specialization-aware class graph identity. Template specializations (List<User>, List<Order>) now produce distinct graph nodes via ~arg suffix in node IDs. The change spans:

• SymbolDefinition.templateArguments (shared metadata)
• C++ tree-sitter query patterns (@declaration.template-arguments capture)
• ClassExtractionConfig hook mechanism (shouldSkipClassCapture, extractTemplateArgumentsFromCapture) keeping C++-specific logic out of shared pipeline
• buildGraphNodeLookup first-wins registration for specializations
• resolveDefGraphId template-aware key lookup
• resolveClassBindingForName specialization-matching fallback

---

6. Findings

---

Finding A — DoD Item 3 Unmet: External type-binding for List<User> var; var.method() Not Captured

• Severity: HIGH

• Files: gitnexus/src/core/ingestion/languages/cpp/query.ts, gitnexus/test/integration/resolvers/cpp.test.ts

• Risk: DoD item 3 is explicitly stated as: "Receiver-bound simple type binding such as List<User> users; users.save(); resolves to the matching specialization." This path is not implemented for the no-initializer declaration form.

• Evidence: The @type-binding.annotation pattern in query.ts:249–251:

  (declaration
    type: (type_identifier) @type-binding.type  ← only matches type_identifier, NOT template_type
    declarator: (identifier) @type-binding.name) @type-binding.annotation
  

  For List<User> list;, the type node is template_type (not type_identifier). The wildcard init-declarator pattern at query.ts:241–244 requires init_declarator (an initializer), which List<User> list; does not have. Therefore no typeRef is created for list, findReceiverTypeBinding returns undefined, and Case 4 of emitReceiverBoundCalls never reaches resolveClassBindingForName. The call list.save() in app.cpp produces no CALLS edge to the specialization.

  The test suite cpp-template-specialization-disambiguation does NOT assert this path. All three test assertions target intra-class calls (callSave → save, save → persistUser/persistOrder). The app.cpp fixture demonstrates the pattern but is not tested.

• Recommended fix: Add a @type-binding.annotation pattern for template_type declarations:

  (declaration
    type: (template_type) @type-binding.type
    declarator: (identifier) @type-binding.name) @type-binding.annotation
  

  Then add an assertion in the test for callUserSave → save with target in list_user.h. Alternatively, explicitly document this form as out-of-scope with a follow-up issue number.

• Blocks merge: maybe — blocks merge if DoD item 3 is strictly interpreted; does not block if this form is documented as a known follow-up.

---

Finding B — tKey First-Wins Fix: SymbolDefinition.nodeId vs Graph Node Mismatch Risk (Low)

• Severity: LOW
• Files: gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts:114
• Risk: The tKey first-wins fix is correct for graph-bridge lookup. However, in resolveClassBindingForName at receiver-bound-calls.ts:99–112, the code iterates over scopes.defs for all defs sharing qualifiedName = 'List'. If both a forward-declaration scope-def and a definition scope-def for List<User> exist (possible if forward declarations are captured by other query patterns), matches.length could be 2 and the fallback at line 115 fires. In practice, the @declaration.class scope-query requires body: (field_declaration_list) so forward declarations are not captured — but this assumption is not documented.
• Evidence: query.ts:31–39 requires body: (field_declaration_list) for class captures; scope-extractor.ts:537–539 builds templateArguments from @declaration.template-arguments. Forward declarations are not captured.
• Recommended fix: Add a comment to resolveClassBindingForName documenting why matches.length > 1 is expected to be unreachable for ODR-compliant C++.
• Blocks merge: no

---

Finding C — app.cpp Only Includes list_user.h, Not list_order.h (Low)

• Severity: LOW
• Files: gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/app.cpp
• Risk: app.cpp only includes list_user.h. To exercise the fixture as a shared-include scenario (both specializations in scope simultaneously), list_order.h should also be included, or the test should explicitly describe the single-include intent.
• Evidence:

  // app.cpp
  #include "list_user.h"  // only List<User>; List<Order> NOT in scope

  The test nonetheless asserts both User and Order specializations — these come from the separate header files being in the same fixture directory, not from inclusion.
• Recommended fix: Either include both headers in app.cpp or add a comment explaining the single-header intent. Low priority; tests pass either way.
• Blocks merge: no

---

7. PR-Specific Assessment Sections

Template argument extraction/canonicalization
extractTemplateArguments in template-arguments.ts handles nested templates (Map<string,vector<int>>), pointer args (T*), qualified names, and whitespace normalization (.replace(/\s+/g, '')). The ~ separator is safe — it cannot appear in valid C++ qualified names stored as .-separated identifiers. Map<string,vector<int>> and Map<string,vector<long>> produce distinct fingerprints ~string,vector<int> vs ~string,vector<long>. No collision risk identified.

C++ query/extractor coverage
Query patterns capture explicit specializations (template <>) via template_type in the name field. Primary templates (template <typename T>) are captured without templateArguments. Partial specializations (template <typename T> class List<T*>) are NOT covered by these patterns (would produce a template_type name with a complex argument) — neither tested nor documented as out of scope. For this PR, the fixture only uses explicit specializations. Ordinary class Foo, struct Bar, enum Baz extraction is unaffected (confirmed via extractName fallback chain).

Parse path propagation
Both sequential (parsing-processor.ts:632–642) and worker (parse-worker.ts:2136–2146) paths use the same three-level extraction: extractedClassSymbol?.templateArguments → extractTemplateArgumentsFromCapture hook → captureMap['template-arguments'] fallback → nameNode.text fallback. templateArguments flows into SymbolDefinition in scope-extractor.ts:537–561 via @declaration.template-arguments capture. Parity is confirmed.

Graph ID / lookup contract
Node IDs: generateId('Class', 'file.h:List~User') via templateArgumentsIdTag. Graph-bridge registration (node-lookup.ts:109–115): first-wins tKey = qualifiedKey(fp, label, 'List~User'). Resolution (ids.ts:106): same tKey. All three use identical join(',') — no divergence possible. Class-label guard in both node-lookup.ts:100–115 and ids.ts:97–109 ensures method/function nodes are never fingerprinted with template args.

Receiver-bound routing
resolveClassBindingForName correctly:

1. Tries direct scope binding for List<User> first
2. Falls back to qualifiedNames.get('List') and filters by exact templateArguments match
3. Returns undefined when no match found (no wrong edge emitted)

For Case 4 in emitReceiverBoundCalls, the resolveClassBindingForName call is reached when typeRef.rawName contains <. But typeRef is only populated when a type binding was captured — which requires the type-binding query pattern to match (see Finding A).

Ownership and edge correctness
Tests at cpp.test.ts:1491–1503 verify that each callSave → save edge's source and target are owned by the same class node (via HAS_METHOD), and that the owner has the matching templateArguments fingerprint. Cross-specialization bleed is confirmed absent for the intra-class path.

Cross-file behavior
The fixture uses separate header files (list_user.h, list_order.h) included by different files. The test confirms distinct class nodes are produced across files. Intra-class call routing (callSave → save) works cross-file. External receiver-bound routing from app.cpp is not tested (see Finding A).

Cross-language/shared contract risk
SymbolDefinition.templateArguments is optional (string[] | undefined). Non-C++ languages that don't set it produce no template fingerprint in node IDs. The class-label guards in node-lookup.ts and ids.ts ensure non-class symbols are never affected. Confirmed safe for TypeScript, Java, Go, and other migrated languages.

Tests and CI
CI is green on 0083058 (8984 passing). The cpp-template-specialization-disambiguation suite covers three assertions: distinct class nodes, cross-specialization non-bleed, and owner attribution. Missing: external type-binding resolution for List<User> list; list.save() (Finding A). Existing C++ resolver fixtures (diamond, ambiguous, cross-file, overloads) are confirmed in the same test file.

Hidden Unicode / hygiene

• git diff --check: clean (no trailing whitespace errors)
• Bidi/hidden Unicode scan: clean — no U+202A–U+202E or U+2066–U+2069 found
• Non-ASCII in changed files: all visible — em-dash (—) and box-drawing chars (──) in JSDoc/block comments only. No non-ASCII in executable logic, query strings, or regexes. Acceptable per repo style.

---

8. Final Verdict

not production-ready

The PR is in Draft status, which alone prevents a production-ready verdict per the final verdict rules. Beyond Draft status, DoD item 3 is partially unmet: the advertised "receiver-bound simple type binding" (List<User> list; list.save()) is not implemented for no-initializer C++ variable declarations because @type-binding.annotation only matches type_identifier, not template_type. The app.cpp fixture demonstrates this exact pattern but no test asserts it. The intra-class dispatch path (DoD items 1, 2, 4, 5, 6, 7, 8) is correctly implemented with verified cross-specialization non-bleed. The two github-actions findings (template_type hardcoding in shared pipeline; tKey last-wins) are confirmed closed in 0083058. To reach production-ready, the PR must: (1) document or implement the external type-binding gap (Finding A), (2) be marked Ready for Review.
· Branch

[magyargergo]

Finding 5 — Test coverage for closure points PARTIALLY ADDRESSED — see new Finding A below.

5. Understanding of the Change

The PR introduces specialization-aware class graph identity. Template specializations (List<User>, List<Order>) now produce distinct graph nodes via ~arg suffix in node IDs. The change spans:

• SymbolDefinition.templateArguments (shared metadata)
• C++ tree-sitter query patterns (@declaration.template-arguments capture)
• ClassExtractionConfig hook mechanism (shouldSkipClassCapture, extractTemplateArgumentsFromCapture) keeping C++-specific logic out of shared pipeline
• buildGraphNodeLookup first-wins registration for specializations
• resolveDefGraphId template-aware key lookup
• resolveClassBindingForName specialization-matching fallback

6. Findings

Finding A — DoD Item 3 Unmet: External type-binding for List<User> var; var.method() Not Captured

• Severity: HIGH
• Files: gitnexus/src/core/ingestion/languages/cpp/query.ts, gitnexus/test/integration/resolvers/cpp.test.ts
• Risk: DoD item 3 is explicitly stated as: "Receiver-bound simple type binding such as List<User> users; users.save(); resolves to the matching specialization." This path is not implemented for the no-initializer declaration form.
• Evidence: The @type-binding.annotation pattern in query.ts:249–251:

  (declaration
    type: (type_identifier) @type-binding.type  ← only matches type_identifier, NOT template_type
    declarator: (identifier) @type-binding.name) @type-binding.annotation
  

  For List<User> list;, the type node is template_type (not type_identifier). The wildcard init-declarator pattern at query.ts:241–244 requires init_declarator (an initializer), which List<User> list; does not have. Therefore no typeRef is created for list, findReceiverTypeBinding returns undefined, and Case 4 of emitReceiverBoundCalls never reaches resolveClassBindingForName. The call list.save() in app.cpp produces no CALLS edge to the specialization.
  The test suite cpp-template-specialization-disambiguation does NOT assert this path. All three test assertions target intra-class calls (callSave → save, save → persistUser/persistOrder). The app.cpp fixture demonstrates the pattern but is not tested.
• Recommended fix: Add a @type-binding.annotation pattern for template_type declarations:

  (declaration
    type: (template_type) @type-binding.type
    declarator: (identifier) @type-binding.name) @type-binding.annotation
  

  Then add an assertion in the test for callUserSave → save with target in list_user.h. Alternatively, explicitly document this form as out-of-scope with a follow-up issue number.
• Blocks merge: maybe — blocks merge if DoD item 3 is strictly interpreted; does not block if this form is documented as a known follow-up.

Finding B — tKey First-Wins Fix: SymbolDefinition.nodeId vs Graph Node Mismatch Risk (Low)

• Severity: LOW
• Files: gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts:114
• Risk: The tKey first-wins fix is correct for graph-bridge lookup. However, in resolveClassBindingForName at receiver-bound-calls.ts:99–112, the code iterates over scopes.defs for all defs sharing qualifiedName = 'List'. If both a forward-declaration scope-def and a definition scope-def for List<User> exist (possible if forward declarations are captured by other query patterns), matches.length could be 2 and the fallback at line 115 fires. In practice, the @declaration.class scope-query requires body: (field_declaration_list) so forward declarations are not captured — but this assumption is not documented.
• Evidence: query.ts:31–39 requires body: (field_declaration_list) for class captures; scope-extractor.ts:537–539 builds templateArguments from @declaration.template-arguments. Forward declarations are not captured.
• Recommended fix: Add a comment to resolveClassBindingForName documenting why matches.length > 1 is expected to be unreachable for ODR-compliant C++.
• Blocks merge: no

Finding C — app.cpp Only Includes list_user.h, Not list_order.h (Low)

• Severity: LOW

• Files: gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/app.cpp

• Risk: app.cpp only includes list_user.h. To exercise the fixture as a shared-include scenario (both specializations in scope simultaneously), list_order.h should also be included, or the test should explicitly describe the single-include intent.

• Evidence:

  // app.cpp
  #include "list_user.h"  // only List<User>; List<Order> NOT in scope

  The test nonetheless asserts both User and Order specializations — these come from the separate header files being in the same fixture directory, not from inclusion.

• Recommended fix: Either include both headers in app.cpp or add a comment explaining the single-header intent. Low priority; tests pass either way.

• Blocks merge: no

@copilot address these findings and act as a senior c++ static analysis engineer and ISO c++ compiler engineer and follow DoD.md file.

[Copilot]

Finding 5 — Test coverage for closure points PARTIALLY ADDRESSED — see new Finding A below.

5. Understanding of the Change

...

Addressed in 57ff0e1 (with follow-up clarification in eee7cce).

Implemented:

• Added C++ @type-binding.annotation capture for template_type declarations without initializers.
• Preserved template arguments in C++ type-binding normalization so List<User> var; var.save(); can route to specialization-aware receiver binding.
• Added integration assertion for external call routing: callUserSave -> List<User>::save (target list_user.h).
• Updated fixture app.cpp to include both list_user.h and list_order.h.
• Added defensive/assumption comments in receiver-bound specialization matching.

Validation rerun: npx tsc --noEmit and targeted cpp.test.ts scenarios are passing; parallel validation is clean.