gitnexus 1.6.5-rc.8 → 1.6.5

package/dist/core/ingestion/languages/cpp/range-bindings.js

@@ -0,0 +1,212 @@
+import { getCppParser } from './query.js';
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
+/**
+ * Populate range-for loop variable type bindings for C++.
+ *
+ * Handles three patterns:
+ *   1. `for (auto& user : users)` — simple range-for
+ *   2. `for (auto& [key, user] : userMap)` — structured binding
+ *   3. `for (auto& user : *usersPtr)` — dereference range-for
+ *
+ * Strategy: look up the range source variable's type in scope
+ * typeBindings, extract the last template argument as the element
+ * type, and inject a typeBinding for the loop variable.
+ */
+export function populateCppRangeBindings(parsedFiles, _indexes, ctx) {
+    const parser = getCppParser();
+    for (const parsed of parsedFiles) {
+        const sourceText = ctx.fileContents.get(parsed.filePath);
+        if (sourceText === undefined)
+            continue;
+        const cachedTree = ctx.treeCache?.get(parsed.filePath);
+        const tree = cachedTree ??
+            parseSourceSafe(parser, sourceText, undefined, {
+                bufferSize: getTreeSitterBufferSize(sourceText),
+            });
+        const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');
+        if (moduleScope === undefined)
+            continue;
+        const scopeMap = new Map(parsed.scopes.map((s) => [s.id, s]));
+        // Build a map from parameter name → AST parameter_declaration node
+        // so we can extract the un-normalized template type from the AST.
+        const paramTypeMap = buildParamTemplateMap(tree.rootNode);
+        for (const rangeNode of tree.rootNode.descendantsOfType('for_range_loop')) {
+            // Get the declarator (loop variable)
+            const declarator = rangeNode.childForFieldName('declarator');
+            if (declarator === null)
+                continue;
+            // Get the range source expression (right side of ':')
+            const right = rangeNode.childForFieldName('right');
+            if (right === null)
+                continue;
+            // Determine the loop variable name(s) and whether this is a structured binding
+            const varNames = extractLoopVarNames(declarator);
+            if (varNames.length === 0)
+                continue;
+            // Determine the range source variable name (handle dereference)
+            const sourceVarName = extractSourceVarName(right);
+            if (sourceVarName === null)
+                continue;
+            // Look up the source variable's full template type from the AST
+            // (scope typeBindings have been normalized and lost template params)
+            const fullType = paramTypeMap.get(sourceVarName);
+            if (fullType === undefined)
+                continue;
+            // Extract element type from the container type
+            const elementType = extractCppElementType(fullType);
+            if (elementType === null)
+                continue;
+            // Find the enclosing function scope
+            const functionScope = findEnclosingFunctionScope(rangeNode, scopeMap);
+            const targetScope = functionScope ?? moduleScope;
+            const mutable = targetScope.typeBindings;
+            // For structured binding [key, user], bind the last identifier to the element type
+            // For simple range-for, bind the single variable
+            const bindVar = varNames[varNames.length - 1];
+            mutable.set(bindVar, {
+                rawName: elementType,
+                declaredAtScope: targetScope.id,
+                source: 'annotation',
+            });
+        }
+    }
+}
+/**
+ * Build a map from parameter name → full (un-normalized) type text
+ * by walking the AST for all `parameter_declaration` nodes.
+ *
+ * This bypasses `normalizeCppTypeName` which strips template params,
+ * giving us the raw `std::vector<User>` text needed for element-type
+ * extraction.
+ */
+function buildParamTemplateMap(rootNode) {
+    const map = new Map();
+    for (const paramNode of rootNode.descendantsOfType('parameter_declaration')) {
+        const typeNode = paramNode.childForFieldName('type');
+        if (typeNode === null)
+            continue;
+        // Extract the parameter name from the declarator subtree.
+        // The declarator may be: identifier, reference_declarator > identifier,
+        // or pointer_declarator > identifier.
+        const declNode = paramNode.childForFieldName('declarator');
+        if (declNode === null)
+            continue;
+        const idents = declNode.descendantsOfType('identifier');
+        if (idents.length === 0)
+            continue;
+        const paramName = idents[idents.length - 1].text;
+        // Use the full type node text (preserving template params)
+        map.set(paramName, typeNode.text);
+    }
+    return map;
+}
+/**
+ * Extract loop variable name(s) from the declarator node.
+ * Handles both simple `identifier` and `structured_binding_declarator`.
+ */
+function extractLoopVarNames(declarator) {
+    // The declarator is typically reference_declarator or pointer_declarator wrapping
+    // either an identifier or a structured_binding_declarator.
+    const structBindings = declarator.descendantsOfType('structured_binding_declarator');
+    if (structBindings.length > 0) {
+        // structured_binding_declarator contains identifiers like [key, user]
+        const idents = structBindings[0].descendantsOfType('identifier');
+        return idents.map((id) => id.text).filter((t) => t !== '_');
+    }
+    // Simple case: reference_declarator > identifier or just identifier
+    const idents = declarator.descendantsOfType('identifier');
+    if (idents.length > 0) {
+        return [idents[idents.length - 1].text];
+    }
+    return [];
+}
+/**
+ * Extract the source variable name from the range expression.
+ * Handles plain identifiers and dereference expressions (*ptr).
+ */
+function extractSourceVarName(right) {
+    if (right.type === 'identifier') {
+        return right.text;
+    }
+    if (right.type === 'pointer_expression') {
+        // *usersPtr → get the argument (usersPtr)
+        const arg = right.childForFieldName('argument');
+        if (arg !== null)
+            return arg.text;
+    }
+    return null;
+}
+/**
+ * Extract the element type from a C++ container type string.
+ *
+ * Examples:
+ *   - `vector<User>` → `User`
+ *   - `std::vector<User>` → `User`
+ *   - `map<std::string, User>` → `User` (last template arg)
+ *   - `map<string, User>` → `User`
+ *
+ * For structured bindings with maps, the last template arg is the value type.
+ * For vectors/sets, the first (and only) template arg is the element type.
+ */
+function extractCppElementType(rawType) {
+    // Find the outermost template argument list
+    const ltIdx = rawType.indexOf('<');
+    if (ltIdx === -1)
+        return null;
+    // Extract the template argument string (handle nested templates)
+    let depth = 0;
+    let lastCommaOrStart = ltIdx + 1;
+    let lastArg = '';
+    for (let i = ltIdx; i < rawType.length; i++) {
+        const ch = rawType[i];
+        if (ch === '<') {
+            depth++;
+        }
+        else if (ch === '>') {
+            depth--;
+            if (depth === 0) {
+                lastArg = rawType.slice(lastCommaOrStart, i).trim();
+                break;
+            }
+        }
+        else if (ch === ',' && depth === 1) {
+            lastCommaOrStart = i + 1;
+        }
+    }
+    if (lastArg === '')
+        return null;
+    // Strip pointer/reference qualifiers and const
+    let elementType = lastArg
+        .replace(/^const\s+/, '')
+        .replace(/\s*[*&]+\s*$/, '')
+        .trim();
+    // Strip namespace prefix (std::string → string)
+    const lastColon = elementType.lastIndexOf('::');
+    if (lastColon !== -1) {
+        elementType = elementType.slice(lastColon + 2);
+    }
+    return elementType || null;
+}
+/**
+ * Find the enclosing Function scope for a tree-sitter node by
+ * walking up the AST and matching source positions.
+ */
+function findEnclosingFunctionScope(node, scopeMap) {
+    const tsNode = node;
+    let current = tsNode;
+    while (current !== null) {
+        if (current.type === 'function_definition') {
+            for (const scope of scopeMap.values()) {
+                if (scope.kind === 'Function' &&
+                    scope.range.startLine === current.startPosition.row &&
+                    scope.range.startCol === current.startPosition.column) {
+                    return scope;
+                }
+            }
+            break;
+        }
+        current = current.parent ?? null;
+    }
+    return null;
+}

package/dist/core/ingestion/languages/cpp/scope-resolver.d.ts

@@ -0,0 +1,17 @@
+import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
+/**
+ * C++ `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by
+ * the generic `runScopeResolution` orchestrator (RFC #909 Ring 3).
+ *
+ * C++ extends C's scope resolution with:
+ *   - Namespaces (`namespace foo { ... }`)
+ *   - Classes with methods and multiple inheritance
+ *   - `using namespace` (wildcard import from namespace)
+ *   - `using X::name` (named import from namespace)
+ *   - Anonymous namespace (file-local linkage, like C `static`)
+ *   - Default parameters (requiredParameterCount < parameterCount)
+ *   - Overloading (arity-based disambiguation)
+ *   - Templates (V1: generic-ignored, `List<User>` ≡ `List`)
+ *   - Leftmost-base MRO for multiple inheritance
+ */
+export declare const cppScopeResolver: ScopeResolver;

package/dist/core/ingestion/languages/cpp/scope-resolver.js

@@ -0,0 +1,246 @@
+import { findClassBindingInScope, findEnclosingClassDef, } from '../../scope-resolution/scope/walkers.js';
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
+import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
+import { cppProvider } from '../c-cpp.js';
+import { cppArityCompatibility } from './arity.js';
+import { cppConversionRank } from './conversion-rank.js';
+import { cppMergeBindings } from './merge-bindings.js';
+import { resolveCppImportTarget } from './import-target.js';
+import { scanCppHeaderFiles } from './header-scan.js';
+import { expandCppWildcardNames, isFileLocal, clearFileLocalNames, populateCppAnonymousNamespaceScopes, populateCppNonGloballyVisible, isCppDefGloballyVisible, } from './file-local-linkage.js';
+import { populateCppDependentBases, clearCppDependentBases, isCppDependentBaseMember, } from './two-phase-lookup.js';
+import { populateCppAssociatedNamespaces, clearCppAdlState, pickCppAdlCandidates } from './adl.js';
+import { clearCppInlineNamespaces, populateCppInlineNamespaceScopes, resolveCppQualifiedNamespaceMember, } from './inline-namespaces.js';
+import { populateCppRangeBindings } from './range-bindings.js';
+/**
+ * C++ `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by
+ * the generic `runScopeResolution` orchestrator (RFC #909 Ring 3).
+ *
+ * C++ extends C's scope resolution with:
+ *   - Namespaces (`namespace foo { ... }`)
+ *   - Classes with methods and multiple inheritance
+ *   - `using namespace` (wildcard import from namespace)
+ *   - `using X::name` (named import from namespace)
+ *   - Anonymous namespace (file-local linkage, like C `static`)
+ *   - Default parameters (requiredParameterCount < parameterCount)
+ *   - Overloading (arity-based disambiguation)
+ *   - Templates (V1: generic-ignored, `List<User>` ≡ `List`)
+ *   - Leftmost-base MRO for multiple inheritance
+ */
+export const cppScopeResolver = {
+    language: SupportedLanguages.CPlusPlus,
+    languageProvider: cppProvider,
+    importEdgeReason: 'cpp-scope: include',
+    loadResolutionConfig: (repoPath) => {
+        // Clear stale per-pipeline state from any previous invocation.
+        clearFileLocalNames();
+        clearCppDependentBases();
+        clearCppAdlState();
+        clearCppInlineNamespaces();
+        return scanCppHeaderFiles(repoPath);
+    },
+    resolveImportTarget: (targetRaw, fromFile, allFilePaths, resolutionConfig) => {
+        // Augment allFilePaths with header files discovered via loadResolutionConfig.
+        // C++ .h/.hpp/.hxx/.hh files may be classified differently by language
+        // detection but are importable from .cpp files via #include.
+        const headerPaths = resolutionConfig;
+        if (headerPaths !== undefined && headerPaths.size > 0) {
+            const augmented = new Set(allFilePaths);
+            for (const h of headerPaths)
+                augmented.add(h);
+            return resolveCppImportTarget(targetRaw, fromFile, augmented);
+        }
+        return resolveCppImportTarget(targetRaw, fromFile, allFilePaths);
+    },
+    expandsWildcardTo: (targetModuleScope, parsedFiles) => expandCppWildcardNames(targetModuleScope, parsedFiles),
+    mergeBindings: (existing, incoming, scopeId) => cppMergeBindings(existing, incoming, scopeId),
+    // Adapter: cppArityCompatibility predates ScopeResolver and uses
+    // (def, callsite). ScopeResolver contract is (callsite, def).
+    arityCompatibility: (callsite, def) => cppArityCompatibility(def, callsite),
+    buildMro: (graph, parsedFiles, nodeLookup) => buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
+    populateOwners: (parsed) => {
+        populateClassOwnedMembers(parsed);
+        // Resolve inline- and anonymous-namespace ranges (recorded at capture
+        // time) to ScopeIds BEFORE `populateCppNonGloballyVisible` runs, so
+        // both exemptions see the populated Sets.
+        populateCppInlineNamespaceScopes(parsed);
+        populateCppAnonymousNamespaceScopes(parsed);
+        // Track namespace-nested and class-nested defs so the global free-call
+        // fallback and wildcard expansion can suppress them as unqualified
+        // cross-file callables.
+        populateCppNonGloballyVisible(parsed);
+        // Build the class-def → enclosing-namespace-qualified-name map used
+        // by ADL (U2 of plan 2026-05-13-001) to identify each argument type's
+        // associated namespace for Koenig lookup.
+        populateCppAssociatedNamespaces(parsed);
+    },
+    // Resolve recorded template-class → dependent-base simple names to
+    // class nodeIds for two-phase template lookup (U3 of plan
+    // 2026-05-13-001). Runs AFTER all files have had `populateOwners`
+    // applied so that cross-file base classes (e.g. Base in base.h,
+    // Derived in derived.h) are reachable in the workspace index.
+    populateWorkspaceOwners: (parsedFiles) => {
+        populateCppDependentBases(parsedFiles);
+    },
+    // Simple `isSuperReceiver` returns false for C++. Real super
+    // classification is caller-context-dependent and lives in
+    // `isSuperReceiverInContext` below — without scope context the
+    // previous regex `/^[A-Z]\w*::/` misclassified namespace-qualified
+    // calls (e.g., `Singleton::getInstance()`) as super calls and routed
+    // them through the wrong resolution branch.
+    isSuperReceiver: () => false,
+    isSuperReceiverInContext: (text, callerScope, scopes) => {
+        // The receiver text comes from the LHS of `::` in `qualified_identifier`
+        // (e.g., for `Base<T>::method()`, text is `Base<T>`). Strip template
+        // arguments (V1: name-only matching, generics ignored) and any leading
+        // namespace qualifier so the lookup matches the bare class def's
+        // simple name. `Base<T>::method()` → `Base`; `outer::v1::Base<T>` →
+        // `Base`. This handles the Phase 5 cross-unit composition where
+        // qualified base-method calls appear inside template bodies.
+        let lhs = text;
+        const sepIdx = lhs.indexOf('::');
+        if (sepIdx > 0)
+            lhs = lhs.slice(0, sepIdx).trim();
+        // Strip trailing template-argument list (greedy: drop everything from
+        // the first `<` onward — V1 ignores generics).
+        const lt = lhs.indexOf('<');
+        if (lt > 0)
+            lhs = lhs.slice(0, lt).trim();
+        // Strip nested namespace prefix from the receiver text itself (the
+        // `outer::v1::Base` shape that appears in derived-list `base_class_clause`).
+        const lastDoubleColon = lhs.lastIndexOf('::');
+        if (lastDoubleColon >= 0)
+            lhs = lhs.slice(lastDoubleColon + 2).trim();
+        if (lhs.length === 0)
+            return false;
+        // Resolve the LHS in the caller's scope chain. Only class-like
+        // resolutions can be super receivers; Namespace and unresolved
+        // names are not super calls.
+        const lhsDef = findClassBindingInScope(callerScope, lhs, scopes);
+        if (lhsDef === undefined)
+            return false;
+        // The caller must have an enclosing class — super calls only make
+        // sense inside a class body. Free functions can use `ClassName::`
+        // for namespace-qualified calls but those are not super.
+        const enclosing = findEnclosingClassDef(callerScope, scopes);
+        if (enclosing === undefined)
+            return false;
+        // `lhsDef` must be in the caller's MRO (i.e., the caller's enclosing
+        // class derives from it). The class itself counts as its own MRO
+        // root — `Self::method()` is a qualified self-call, not a super
+        // call, so exclude the caller's own class.
+        if (lhsDef.nodeId === enclosing.nodeId)
+            return false;
+        const mro = scopes.methodDispatch.mroFor(enclosing.nodeId);
+        return mro.includes(lhsDef.nodeId);
+    },
+    // C++ is statically typed — disable field fallback heuristic
+    fieldFallbackOnMethodLookup: false,
+    // C++ needs return type propagation across #include boundaries
+    propagatesReturnTypesAcrossImports: true,
+    // C++ #include brings in all symbols — enable global free call fallback
+    allowGlobalFreeCallFallback: true,
+    // C++ standard-conversion-sequence ranking for overload resolution (#1578).
+    // Disambiguates `f(int)` vs `f(double)` called with `f(2.5)` by scoring
+    // each candidate's conversion cost; exact match wins over standard conversion.
+    conversionRankFn: cppConversionRank,
+    // Range-for element type inference: for (auto& user : users) → bind user to User
+    populateRangeBindings: populateCppRangeBindings,
+    // C++ method return-type bindings need to be visible from module scope
+    // for cross-file propagation and compound-receiver chain resolution.
+    // cppBindingScopeFor hoists @type-binding.return to Module scope.
+    hoistTypeBindingsToModule: true,
+    // Enable receiver-bound explicit-`this` fallback only for C++.
+    resolveThisViaEnclosingClass: true,
+    // The `isFileLocalDef` hook on the global free-call fallback names
+    // file-local linkage historically, but semantically gates "logically
+    // invisible cross-file" defs. C++ extends this to also reject class-
+    // owned methods/fields and namespace-nested symbols — an unqualified
+    // call from a free function MUST NOT resolve to `User::save` or
+    // `ns::foo` (Cppreference, "Unqualified name lookup"). Without this
+    // gate, the global fallback walks every callable in the workspace
+    // registry and matches any class method or namespace function by
+    // simple name.
+    isFileLocalDef: (def) => {
+        const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
+        if (isFileLocal(def.filePath, simple))
+            return true;
+        // Class-owned (Method/Field) — `populateClassOwnedMembers` already
+        // stamps `ownerId`; cheap fast-path before consulting the scope map.
+        if (def.ownerId !== undefined)
+            return true;
+        // Namespace-nested defs — require qualification cross-file. Scope-
+        // walked at `populateOwners` time into a per-file nodeId set.
+        if (!isCppDefGloballyVisible(def.filePath, def.nodeId))
+            return true;
+        return false;
+    },
+    // C++ two-phase template lookup: inside a class template body,
+    // unqualified calls MUST NOT bind to members of a dependent base
+    // class. The standard requires `this->name()` or `Base<T>::name()`
+    // forms to make the lookup dependent. Without this gate the global
+    // free-call fallback walks the workspace registry and silently binds
+    // unqualified calls to dependent-base members, producing CALLS edges
+    // the compiler would reject. See plan 2026-05-13-001 U3.
+    isCallableVisibleFromCaller: ({ candidate, callerScope, scopes }) => {
+        if (callerScope === undefined || scopes === undefined)
+            return true;
+        // Reject when the candidate is a member of a dependent base of the
+        // caller's enclosing template class. Otherwise allow.
+        return !isCppDependentBaseMember(callerScope, candidate, scopes);
+    },
+    // C++ argument-dependent / Koenig lookup (U2 of plan 2026-05-13-001).
+    // Contributes candidates from associated namespaces of class-typed
+    // arguments; caller merges with ordinary unqualified lookup candidates.
+    // Current boundary: class-typed value/pointer/reference args and template
+    // specializations with explicit type arguments contribute associated
+    // namespaces. Function-pointer args and full conversion-ranking remain
+    // excluded.
+    resolveAdlCandidates: (site, callerParsed, scopes, parsedFiles) => {
+        // `using ns::name;` introduces `name` into ordinary unqualified lookup.
+        // For template-class method bodies, lexical scope walks can miss this
+        // named-using visibility; recover by resolving the imported namespace
+        // member directly when the local call name matches a named using import.
+        const usingNamedHits = [];
+        const seenUsing = new Set();
+        for (const imp of callerParsed.parsedImports) {
+            if (imp.kind !== 'named')
+                continue;
+            if (imp.localName !== site.name)
+                continue;
+            const member = resolveCppQualifiedNamespaceMember(imp.targetRaw, imp.importedName, parsedFiles, scopes);
+            if (member === undefined || member === 'ambiguous')
+                continue;
+            if (seenUsing.has(member.nodeId))
+                continue;
+            seenUsing.add(member.nodeId);
+            usingNamedHits.push(member);
+        }
+        const adlHits = pickCppAdlCandidates(site, callerParsed, scopes, parsedFiles);
+        if (usingNamedHits.length === 0)
+            return adlHits;
+        if (adlHits === undefined || adlHits.length === 0)
+            return usingNamedHits;
+        const merged = [];
+        const seen = new Set();
+        for (const hit of usingNamedHits) {
+            seen.add(hit.nodeId);
+            merged.push(hit);
+        }
+        for (const hit of adlHits) {
+            if (seen.has(hit.nodeId))
+                continue;
+            seen.add(hit.nodeId);
+            merged.push(hit);
+        }
+        return merged;
+    },
+    // C++ qualified namespace-member resolution (U5 of plan 2026-05-13-001).
+    // Handles `outer::foo()` where `outer` is a namespace (not a class).
+    // Walks each parsed file's namespace scopes by simple name, then
+    // descends transitively through inline-namespace children when
+    // searching for the called member. Returns undefined for non-namespace
+    // receivers so receiver-bound-calls Case 2 still gets a chance.
+    resolveQualifiedReceiverMember: (receiverName, memberName, _callerScope, scopes, parsedFiles) => resolveCppQualifiedNamespaceMember(receiverName, memberName, parsedFiles, scopes),
+};

package/dist/core/ingestion/languages/cpp/simple-hooks.d.ts

@@ -0,0 +1,24 @@
+import type { CaptureMatch, ParsedImport, Scope, ScopeId, ScopeTree, TypeRef } from '../../../../_shared/index.js';
+/**
+ * C++ binding scope: default auto-hoist (null) for most declarations.
+ *
+ * For `for` statement init-scope variables (e.g. `for (int i = 0; ...)`),
+ * the variable is scoped to the for-block, not the enclosing function.
+ * The tree-sitter scope query already captures for_statement as @scope.block,
+ * so tree-sitter's scope nesting handles this automatically — we return null
+ * to let the default auto-hoist apply.
+ */
+export declare function cppBindingScopeFor(decl: CaptureMatch, innermost: Scope, tree: ScopeTree): ScopeId | null;
+/**
+ * C++ import owning scope: default (null).
+ * #include and using declarations are file-scoped in C++.
+ */
+export declare function cppImportOwningScope(_imp: ParsedImport, _innermost: Scope, _tree: ScopeTree): ScopeId | null;
+/**
+ * C++ receiver binding: return `this` TypeRef for methods inside a class.
+ *
+ * When a function scope is inside a class scope, the implicit `this` pointer
+ * refers to the enclosing class. This enables `this->method()` and implicit
+ * `this` member access resolution.
+ */
+export declare function cppReceiverBinding(functionScope: Scope): TypeRef | null;

package/dist/core/ingestion/languages/cpp/simple-hooks.js

@@ -0,0 +1,62 @@
+/**
+ * C++ binding scope: default auto-hoist (null) for most declarations.
+ *
+ * For `for` statement init-scope variables (e.g. `for (int i = 0; ...)`),
+ * the variable is scoped to the for-block, not the enclosing function.
+ * The tree-sitter scope query already captures for_statement as @scope.block,
+ * so tree-sitter's scope nesting handles this automatically — we return null
+ * to let the default auto-hoist apply.
+ */
+export function cppBindingScopeFor(decl, innermost, tree) {
+    // Hoist return-type bindings to Module scope so:
+    // 1. propagateImportedReturnTypes can mirror them across files
+    // 2. compound-receiver can find method return types via hoistTypeBindingsToModule
+    if (decl['@type-binding.return'] !== undefined) {
+        let cur = innermost;
+        while (cur !== undefined && cur.kind !== 'Module') {
+            const parentId = cur.parent ?? null;
+            if (parentId === null)
+                break;
+            cur = tree.getScope(parentId);
+        }
+        if (cur !== undefined && cur.kind === 'Module')
+            return cur.id;
+    }
+    return null; // default auto-hoist for other bindings
+}
+/**
+ * C++ import owning scope: default (null).
+ * #include and using declarations are file-scoped in C++.
+ */
+export function cppImportOwningScope(_imp, _innermost, _tree) {
+    return null;
+}
+/**
+ * C++ receiver binding: return `this` TypeRef for methods inside a class.
+ *
+ * When a function scope is inside a class scope, the implicit `this` pointer
+ * refers to the enclosing class. This enables `this->method()` and implicit
+ * `this` member access resolution.
+ */
+export function cppReceiverBinding(functionScope) {
+    // Walk up the scope tree to find an enclosing class scope
+    if (functionScope.parent === null)
+        return null;
+    // The scope tree structure nests function scopes inside class scopes.
+    // The orchestrator provides the function scope; we need to check if
+    // its parent chain contains a class scope.
+    //
+    // However, the ScopeResolver.receiverBinding contract receives only
+    // the function Scope (not the full ScopeTree), and the Scope type
+    // includes `parent` (a ScopeId) but not a reference to the parent
+    // Scope object.
+    //
+    // The orchestrator already handles this by looking up the class owner
+    // via populateOwners. We return null here and let the shared infra
+    // handle receiver resolution through the class-ownership mechanism.
+    //
+    // This is consistent with how C# and Go handle it — the receiver
+    // binding is established through populateOwners + the MRO chain,
+    // not through this hook.
+    return null;
+}

package/dist/core/ingestion/languages/cpp/two-phase-lookup.d.ts

@@ -0,0 +1,76 @@
+/**
+ * C++ two-phase template lookup support.
+ *
+ * Inside a class template body, names from a dependent base class are NOT
+ * found by ordinary unqualified lookup. The standard requires the
+ * `this->name` or `Base<T>::name` forms to make the lookup dependent.
+ * GitNexus's global free-call fallback otherwise binds such names to the
+ * dependent base's members, producing CALLS edges the compiler would
+ * reject.
+ *
+ * This module records — during `emitCppScopeCaptures` — which template
+ * class declarations have which dependent base class names (per file).
+ * `populateCppDependentBases` then resolves those names to class nodeIds
+ * using a workspace-wide registry, building the per-class set the
+ * `isCppDependentBaseMember` predicate consumes.
+ *
+ * Cross-file resolution: `Base<T>` may be declared in a different header
+ * than `Derived<T>`. `populateCppDependentBases` therefore runs as a
+ * workspace-wide pass (`populateWorkspaceOwners` hook) after every file
+ * has had `populateOwners` applied, so all class defs are reachable.
+ *
+ * Namespace disambiguation: when multiple classes share a simple name
+ * (e.g., `Box` in two namespaces), the resolver prefers the candidate
+ * whose qualified-name prefix (namespace path) matches the deriving
+ * class's prefix. If no namespace match is found, a unique simple-name
+ * match is accepted; ambiguous matches (multiple candidates, no
+ * namespace winner) are skipped conservatively.
+ *
+ * NOTE: module-level state, single-process-single-repo use only.
+ * `clearFileLocalNames()` clears this state alongside file-local linkage
+ * (see `file-local-linkage.ts`).
+ */
+import type { ParsedFile, ScopeId, SymbolDefinition } from '../../../../_shared/index.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+/**
+ * Record a dependent-base relationship discovered during scope-capture
+ * emission. `className` is the simple name of the template class;
+ * `baseName` is the simple name of the dependent base class.
+ *
+ * The capture-time recorder uses simple names because the registry
+ * resolution that maps names → nodeIds runs later (in
+ * `populateCppDependentBases`).
+ */
+export declare function markCppDependentBase(filePath: string, className: string, baseName: string): void;
+/** Clear two-phase-lookup state. Called from `clearFileLocalNames`. */
+export declare function clearCppDependentBases(): void;
+/**
+ * Resolve recorded dependent-base simple names to class nodeIds using a
+ * workspace-wide index. Run as `populateWorkspaceOwners` after every
+ * file has had `populateOwners` applied, so class defs from ALL files
+ * are reachable.
+ *
+ * Disambiguation strategy (multiple classes sharing a simple name):
+ *  1. Prefer the candidate whose qualified-name namespace prefix matches
+ *     the deriving class's namespace prefix (same-namespace bias).
+ *  2. Fall back to accepting a unique simple-name match.
+ *  3. Skip when multiple candidates exist and no namespace match is
+ *     found (conservative: avoids false associations).
+ */
+export declare function populateCppDependentBases(parsedFiles: readonly ParsedFile[]): void;
+/**
+ * Two-phase lookup predicate: is the candidate def a member of a
+ * dependent base of the caller's enclosing template class?
+ *
+ * Used as an additional reject-filter in `pickUniqueGlobalCallable` and
+ * the receiver-bound member chain walk. ONLY apply for unqualified
+ * call forms — `this->name` and `Base<T>::name` are dependent lookup
+ * forms that the standard allows.
+ *
+ * Conservative bias: when the caller's enclosing class can't be
+ * identified, return `false` (let normal resolution proceed). Over-
+ * rejection is acceptable for the template case because the standard
+ * itself requires `this->` or qualified forms for dependent base
+ * access; missing edges here match the compiler's diagnostic shape.
+ */
+export declare function isCppDependentBaseMember(callerScopeId: ScopeId, candidateDef: SymbolDefinition, scopes: ScopeResolutionIndexes): boolean;