cgraphx 2.0.2 → 2.0.6

package/dist/core/code/engine/core/ingestion/languages/cpp/inline-namespaces.js

@@ -0,0 +1,379 @@
+"use strict";
+/**
+ * C++ inline namespace support (U5 of plan 2026-05-13-001).
+ *
+ * `inline namespace v1 { void foo(); }` has two ISO C++ semantics that
+ * GitNexus must model:
+ *
+ *   1. **Transitive unqualified visibility.** Names declared in an inline
+ *      namespace are reachable by unqualified lookup from the enclosing
+ *      namespace's scope, as if they were declared directly there.
+ *      `populateCppNonGloballyVisible` (file-local-linkage.ts) treats
+ *      inline-namespace members as globally visible for cross-file
+ *      unqualified lookup.
+ *
+ *   2. **Transitive qualified visibility.** `outer::foo()` resolves to
+ *      `outer::v1::foo()` when `v1` is inline. The qualified-namespace
+ *      receiver resolver (`resolveCppQualifiedNamespaceMember`) walks
+ *      inline-namespace children transitively when collecting candidates —
+ *      once per pipeline run, into {@link QualifiedNsMemberIndex} (#2788).
+ *
+ * State lifecycle: capture-time `markCppInlineNamespaceRange` records each
+ * inline namespace's source range; `populateCppInlineNamespaceScopes`
+ * resolves ranges to `ScopeId`s during `populateOwners`. Cleared via
+ * `clearCppInlineNamespaces`, called from
+ * `cppScopeResolver.loadResolutionConfig` at the start of every pass.
+ *
+ * STL idiom this enables: `std::__1::vector` (libc++) and `std::__cxx11`
+ * (libstdc++) are inline namespaces of `std`. With this support,
+ * `std::vector` qualified calls resolve to the inline-namespace
+ * declaration transparently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.markCppInlineNamespaceRange = markCppInlineNamespaceRange;
+exports.collectCppInlineNamespaceSideChannel = collectCppInlineNamespaceSideChannel;
+exports.applyCppInlineNamespaceSideChannel = applyCppInlineNamespaceSideChannel;
+exports.clearCppInlineNamespaces = clearCppInlineNamespaces;
+exports.populateCppInlineNamespaceScopes = populateCppInlineNamespaceScopes;
+exports.isCppInlineNamespaceScope = isCppInlineNamespaceScope;
+exports.resolveCppQualifiedNamespaceMember = resolveCppQualifiedNamespaceMember;
+const overload_narrowing_js_1 = require("../../scope-resolution/passes/overload-narrowing.js");
+const callable_labels_js_1 = require("../../utils/callable-labels.js");
+const env_js_1 = require("../../utils/env.js");
+const conversion_rank_js_1 = require("./conversion-rank.js");
+const inlineNamespaceRangesByFile = new Map();
+const inlineNamespaceScopeIds = new Set();
+/** Bumped by every writer of {@link inlineNamespaceScopeIds}. The qualified-ns
+ *  index is a function of both `parsedFiles` and that Set; its WeakMap key sees
+ *  only the first, so the memo stamps this epoch and a missed
+ *  {@link clearCppInlineNamespaces} degrades to a rebuild, not a stale answer. */
+let inlineNamespaceEpoch = 0;
+function rangeKey(r) {
+    return `${r.startLine}:${r.startCol}:${r.endLine}:${r.endCol}`;
+}
+/** Capture-time: record a namespace_definition's range as inline.
+ *  Called from `emitCppScopeCaptures` when the tree-sitter AST shows an
+ *  `inline` keyword child on `namespace_definition`. */
+function markCppInlineNamespaceRange(filePath, range) {
+    let set = inlineNamespaceRangesByFile.get(filePath);
+    if (set === undefined) {
+        set = new Set();
+        inlineNamespaceRangesByFile.set(filePath, set);
+    }
+    set.add(rangeKey(range));
+}
+/** Snapshot this file's captured inline-namespace ranges for the worker→main
+ *  side-channel (#1983). `populateCppInlineNamespaceScopes` (in `populateOwners`)
+ *  later resolves these range keys to ScopeIds on the main thread, so only the
+ *  capture-time ranges need to cross the boundary. Returns the rangeKey strings
+ *  as a plain array (empty when this file recorded none). */
+function collectCppInlineNamespaceSideChannel(filePath) {
+    const set = inlineNamespaceRangesByFile.get(filePath);
+    return set === undefined ? [] : [...set];
+}
+/** Restore this file's captured inline-namespace ranges from the side-channel. */
+function applyCppInlineNamespaceSideChannel(filePath, ranges) {
+    if (ranges.length === 0)
+        return;
+    let set = inlineNamespaceRangesByFile.get(filePath);
+    if (set === undefined) {
+        set = new Set();
+        inlineNamespaceRangesByFile.set(filePath, set);
+    }
+    for (const r of ranges)
+        set.add(r);
+}
+/** Clear all inline-namespace state. Called from
+ *  `cppScopeResolver.loadResolutionConfig` at the start of every pass.
+ *
+ *  The qualified-namespace index is dropped by REASSIGNING a fresh `WeakMap`
+ *  (`WeakMap` has no `.clear()`) so its entries — and the `SymbolDefinition`
+ *  references they hold — are released here rather than waiting on the key.
+ *  Correctness does not rest on that: {@link inlineNamespaceEpoch} invalidates
+ *  any surviving entry. */
+function clearCppInlineNamespaces() {
+    inlineNamespaceRangesByFile.clear();
+    inlineNamespaceScopeIds.clear();
+    inlineNamespaceEpoch++;
+    qualifiedNsIndexByPass = new WeakMap();
+}
+/** Resolve captured ranges to actual ScopeIds by matching scope ranges
+ *  against the inline-namespace ranges recorded for this file. Run from
+ *  the cpp resolver's `populateOwners` hook so the per-pipeline Set is
+ *  populated before any resolution pass consults it. */
+function populateCppInlineNamespaceScopes(parsed) {
+    const ranges = inlineNamespaceRangesByFile.get(parsed.filePath);
+    if (ranges === undefined || ranges.size === 0)
+        return;
+    inlineNamespaceEpoch++;
+    for (const scope of parsed.scopes) {
+        if (scope.kind !== 'Namespace')
+            continue;
+        if (ranges.has(rangeKey(scope.range))) {
+            inlineNamespaceScopeIds.add(scope.id);
+        }
+    }
+}
+/** Predicate consumed by `populateCppNonGloballyVisible` to exempt
+ *  inline-namespace members from cross-file unqualified-lookup
+ *  exclusion (they remain reachable as if declared at the enclosing
+ *  namespace's level). */
+function isCppInlineNamespaceScope(scopeId) {
+    return inlineNamespaceScopeIds.has(scopeId);
+}
+/**
+ * Dev/test-only mutation tripwire on the arrays this module shares across call
+ * sites ({@link NO_DEFS} and every `membersByReceiver` memo entry): an in-place
+ * `.sort()`/`.splice()` ever added to `overload-narrowing.ts` would corrupt
+ * every LATER resolution of the same pair, not just its own call, and freezing
+ * makes that a loud `TypeError` instead. DEV-ONLY because the types already
+ * reject it — the memo and `narrowOverloadCandidates`' parameter are both
+ * `readonly SymbolDefinition[]`, so only a cast gets past — while the freeze is
+ * not free: V8 moves a frozen array to `PACKED_FROZEN_ELEMENTS`, off the
+ * builtin fast path for the `.filter`/`.map`/`.some` narrowing runs over it at
+ * every multi-candidate call site (measured 4.6×; large bench arm 100.3 → 70.6ms
+ * with it off). Gated on `isSemanticModelValidatorEnabled()` — the OPT-IN form,
+ * not `adl.ts`'s opt-out `NODE_ENV !== 'production'`: `NODE_ENV` is unset in a
+ * CLI `analyze`, so the opt-out form would keep paying the freeze exactly where
+ * the cost lands. Read once at load because this one is per-call-site.
+ */
+const FREEZE_SHARED_CANDIDATES = (0, env_js_1.isSemanticModelValidatorEnabled)();
+/** Shared empties: most namespace scopes declare no callables, and most
+ *  qualified receivers name no namespace at all. `NO_DEFS` is process-wide, so
+ *  it gets the same dev-only freeze the memoized arrays do. */
+const NO_MEMBERS = new Map();
+const NO_DEFS = FREEZE_SHARED_CANDIDATES ? Object.freeze([]) : [];
+/** Simple (last-segment) name of a def, matching the legacy scan exactly —
+ *  including the empty-string fallback for a def with no `qualifiedName`, and
+ *  the empty last segment of a trailing-dot name. `lastIndexOf` + `slice`
+ *  rather than `split('.').pop()`: same result, no intermediate array, and this
+ *  runs per callable def and per namespace scope at build. */
+function simpleNameOf(def) {
+    const qualified = def.qualifiedName;
+    if (qualified == null)
+        return '';
+    const lastDot = qualified.lastIndexOf('.');
+    return lastDot === -1 ? qualified : qualified.slice(lastDot + 1);
+}
+/**
+ * Per-pass memo: `parsedFiles` array identity → the built index. `WeakMap`-keyed
+ * so the entry lives only as long as the caller's `parsedFiles` array does, and
+ * is reclaimed with the pass — mirrors `moduleScopeIndexByPass` in
+ * `file-local-linkage.ts`.
+ *
+ * Weak keying is load-bearing, not stylistic: the index holds
+ * `SymbolDefinition` references reaching into every ParsedFile's scopes, so a
+ * module-level strong `let` pair (index + source array) kept the whole C/C++
+ * ParsedFile set alive past the point `scope-resolution/pipeline/phase.ts`
+ * evicts `files`/`contents`/`preExtractedByPath` and calls `forceGc()` to
+ * reclaim it — C++ is 7th of 16 `SCOPE_RESOLVERS` entries, so the retention
+ * survived nine later language passes plus emit (104.2 MB measured).
+ */
+let qualifiedNsIndexByPass = new WeakMap();
+/** Build the index in two linear passes per file: one to make a node per
+ *  `Namespace` scope, one to link inline children and register receivers.
+ *  Linking needs both endpoints to exist and `parsed.scopes` does not promise
+ *  parents precede children, hence two passes rather than one — but only the
+ *  first pass filters `parsed.scopes`; it hands the second the `[scope, node]`
+ *  pairs it already found. */
+function buildQualifiedNsMemberIndex(parsedFiles) {
+    const rootsByReceiver = new Map();
+    for (const parsed of parsedFiles) {
+        const nodesByScope = new Map();
+        const namespaces = [];
+        for (const sc of parsed.scopes) {
+            if (sc.kind !== 'Namespace')
+                continue;
+            const node = { ownMembers: bucketOwnMembers(sc), inlineChildren: [] };
+            nodesByScope.set(sc.id, node);
+            namespaces.push([sc, node]);
+        }
+        for (const [sc, node] of namespaces) {
+            // A non-`Namespace` parent (a Module scope, say) has no node, so the
+            // inline child links to nothing — hence the `?.` below.
+            if (sc.parent !== null && inlineNamespaceScopeIds.has(sc.id)) {
+                nodesByScope.get(sc.parent)?.inlineChildren.push(node);
+            }
+            const nsDef = findNamespaceDefInScope(sc);
+            if (nsDef === undefined)
+                continue;
+            const nsName = simpleNameOf(nsDef);
+            let roots = rootsByReceiver.get(nsName);
+            if (roots === undefined) {
+                roots = [];
+                rootsByReceiver.set(nsName, roots);
+            }
+            roots.push(node);
+        }
+    }
+    return { rootsByReceiver, membersByReceiver: new Map() };
+}
+/** Bucket a namespace scope's own callable `ownedDefs` by member simple name.
+ *  No descent: inline children are separate nodes reached by the walk. */
+function bucketOwnMembers(scope) {
+    let members;
+    for (const def of scope.ownedDefs) {
+        if (!(0, callable_labels_js_1.isOverloadableCallable)(def.type))
+            continue;
+        const simple = simpleNameOf(def);
+        members ??= new Map();
+        let arr = members.get(simple);
+        if (arr === undefined) {
+            arr = [];
+            members.set(simple, arr);
+        }
+        arr.push(def);
+    }
+    return members ?? NO_MEMBERS;
+}
+/** Candidates for `receiver::member`, memoized on the index per pair so a
+ *  repeated call site costs two Map lookups. */
+function qualifiedNsMembers(index, receiverName, memberName) {
+    const roots = index.rootsByReceiver.get(receiverName);
+    // No namespace by that name — the most common outcome in real source. Left
+    // unmemoized deliberately: it is already O(1), and memoizing would grow the
+    // index by an entry per unresolved receiver name in the workspace.
+    if (roots === undefined)
+        return NO_DEFS;
+    let byMember = index.membersByReceiver.get(receiverName);
+    if (byMember === undefined) {
+        byMember = new Map();
+        index.membersByReceiver.set(receiverName, byMember);
+    }
+    let hits = byMember.get(memberName);
+    if (hits === undefined) {
+        // Memoization makes this array shared by every call site in the pass rather
+        // than rebuilt per call, so it carries the dev-only mutation tripwire (see
+        // {@link FREEZE_SHARED_CANDIDATES}).
+        hits = gatherQualifiedNsMember(roots, memberName);
+        if (FREEZE_SHARED_CANDIDATES)
+            hits = Object.freeze(hits);
+        byMember.set(memberName, hits);
+    }
+    return hits;
+}
+/** Pre-order depth-first walk of every scope named `receiverName` and its
+ *  transitive inline-namespace children, collecting callables named
+ *  `memberName` — the index twin of the legacy
+ *  `findMemberInNamespaceTransitive`.
+ *
+ *  Iterative, not recursive: nesting depth is whatever the input file says, and
+ *  a recursive descent threw `RangeError` past ~8k levels (see
+ *  {@link QualifiedNsMemberIndex}). */
+function gatherQualifiedNsMember(roots, memberName) {
+    const hits = [];
+    const stack = [];
+    // `visited` spans ALL roots, reproducing the legacy per-receiver `seenNodeId`
+    // dedup: `namespace ns { inline namespace ns { … } }` registers both scopes
+    // under receiver `ns`, and the outer walk already collected the inner's defs.
+    // Node identity is equivalent to the legacy nodeId key because a node always
+    // contributes the same defs. It doubles as the guard that a malformed parent
+    // cycle terminates instead of spinning — the one regression an explicit stack
+    // could otherwise introduce over recursion's `RangeError`.
+    const visited = new Set();
+    for (const root of roots) {
+        stack.push(root);
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (visited.has(node))
+                continue;
+            visited.add(node);
+            const own = node.ownMembers.get(memberName);
+            if (own !== undefined)
+                for (const def of own)
+                    hits.push(def);
+            // Reverse push so children pop in declaration order — the legacy walk's
+            // pre-order depth-first candidate order (see
+            // {@link QualifiedNsMemberIndex.rootsByReceiver}).
+            const kids = node.inlineChildren;
+            for (let i = kids.length - 1; i >= 0; i--)
+                stack.push(kids[i]);
+        }
+    }
+    return hits.length === 0 ? NO_DEFS : hits;
+}
+/** Build the index on first use of a given `parsedFiles` set; reuse it for
+ *  every subsequent call site that passes the same array reference AND the same
+ *  {@link inlineNamespaceEpoch}.
+ *
+ *  Both keys are needed because the index is a function of TWO inputs:
+ *  `parsedFiles` and the module-level `inlineNamespaceScopeIds` (which inline
+ *  children get descended into). A later pass may hand back the same
+ *  `parsedFiles` reference with different inline-namespace state, so identity
+ *  alone would serve a stale index — the epoch is what makes that a checked
+ *  rebuild instead of a documented obligation on the clear site.
+ *
+ *  Lifetime: the entry is reachable only while the caller still holds the
+ *  `parsedFiles` array; nothing here pins it (see {@link qualifiedNsIndexByPass}).
+ *
+ *  Same STALENESS contract as `ensureAdlIndex` in `adl.ts`, minus that
+ *  sibling's dev-gated `validateAdlSeqCoverage` guard: this index has no `?? 0`
+ *  defaulting read to silently collide on, so there is nothing for such a guard
+ *  to catch. */
+function qualifiedNsMemberIndex(parsedFiles) {
+    const memo = qualifiedNsIndexByPass.get(parsedFiles);
+    if (memo !== undefined && memo.epoch === inlineNamespaceEpoch)
+        return memo.index;
+    const index = buildQualifiedNsMemberIndex(parsedFiles);
+    qualifiedNsIndexByPass.set(parsedFiles, { epoch: inlineNamespaceEpoch, index });
+    return index;
+}
+/** Constant narrowing hooks for the C++ qualified-receiver path — hoisted so
+ *  the literal is not reallocated at every multi-candidate call site. */
+const CPP_NARROWING_HOOKS = {
+    conversionRankFn: conversion_rank_js_1.cppConversionRank,
+    conversionOnlyArgTypePrefixes: conversion_rank_js_1.CPP_CONVERSION_ONLY_ARG_TYPE_PREFIXES,
+};
+/**
+ * Find the Namespace scopes whose simple name matches `receiverName` and
+ * return their callable members matching `memberName`, transitively
+ * including inline-namespace children (since they're members of the
+ * enclosing namespace under ISO C++). Served from a per-pipeline index
+ * ({@link QualifiedNsMemberIndex}), not a per-call-site workspace scan.
+ *
+ * Returns the most specific (innermost) match — for `outer::foo()`
+ * where `inline namespace v1` declares `foo`, returns `v1::foo`. When
+ * multiple inline-namespace children declare the same name, ISO C++
+ * leaves the call ambiguous; returns `'ambiguous'` so the caller
+ * suppresses edge emission rather than picking arbitrarily (#1564).
+ *
+ * Two production call sites, both in `scope-resolver.ts`:
+ *   - `resolveQualifiedReceiverMember` — the `outer::foo()` qualified-receiver
+ *     hook. Passes `callsite`, so a multi-candidate set can be narrowed by
+ *     arity and argument types.
+ *   - `resolveAdlCandidates` — resolving a `using ns::name;` named import back
+ *     to its namespace member, for template-class method bodies where the
+ *     lexical walk misses that visibility. Passes NO `callsite`, which makes
+ *     the narrowing filters below pass-throughs: on that path any receiver
+ *     whose member has more than one candidate returns `'ambiguous'` (and the
+ *     caller then skips it) rather than being disambiguated.
+ */
+function resolveCppQualifiedNamespaceMember(receiverName, memberName, parsedFiles, _scopes, callsite) {
+    const allHits = qualifiedNsMembers(qualifiedNsMemberIndex(parsedFiles), receiverName, memberName);
+    if (allHits.length === 0)
+        return undefined;
+    if (allHits.length === 1)
+        return allHits[0];
+    // Multi-candidate: thread call-site arity/argument-types through the
+    // `resolveQualifiedReceiverMember` contract so `narrowOverloadCandidates`
+    // can disambiguate via exact-type match and, when available, conversion-rank
+    // scoring (`cppConversionRank`). Same-signature ambiguity is still detected
+    // by `isOverloadAmbiguousAfterNormalization` below.
+    const narrowed = (0, overload_narrowing_js_1.narrowOverloadCandidates)(allHits, callsite?.arity, callsite?.argumentTypes, callsite !== undefined ? CPP_NARROWING_HOOKS : undefined);
+    if (narrowed.length === 1)
+        return narrowed[0];
+    if (narrowed.length === 0)
+        return undefined;
+    if ((0, overload_narrowing_js_1.isOverloadAmbiguousAfterNormalization)(narrowed, undefined))
+        return 'ambiguous';
+    // Multiple surviving candidates (distinct signatures) — conservative
+    // suppress because we lack call-site info to disambiguate.
+    return 'ambiguous';
+}
+function findNamespaceDefInScope(scope) {
+    for (const def of scope.ownedDefs) {
+        if (def.type === 'Namespace')
+            return def;
+    }
+    return undefined;
+}

package/dist/core/code/engine/core/ingestion/languages/cpp/interpret.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interpretCppImport = interpretCppImport;
+exports.interpretCppTypeBinding = interpretCppTypeBinding;
+exports.stripCppSpecifiers = stripCppSpecifiers;
+exports.normalizeCppTypeName = normalizeCppTypeName;
+/**
+ * Interpret a C++ import capture into a ParsedImport.
+ *
+ * C++ has three import forms:
+ *   1. #include "file.h"  → wildcard import (all symbols from header)
+ *   2. using namespace X; → wildcard import (all symbols from namespace X)
+ *   3. using X::name;     → named import (single symbol from namespace X)
+ *
+ * System headers (#include <...>) are not resolved to local files.
+ */
+function interpretCppImport(captures) {
+    const source = captures['@import.source']?.text;
+    if (source === undefined)
+        return null;
+    // System headers are not resolved to local files
+    if (captures['@import.system'] !== undefined)
+        return null;
+    const kind = captures['@import.kind']?.text;
+    if (kind === 'named') {
+        // using X::name — named import
+        const importedName = captures['@import.name']?.text;
+        if (importedName === undefined)
+            return null;
+        return { kind: 'named', targetRaw: source, localName: importedName, importedName };
+    }
+    // #include or using namespace — wildcard import
+    return { kind: 'wildcard', targetRaw: source };
+}
+/**
+ * Interpret a C++ type-binding capture into a ParsedTypeBinding.
+ *
+ * Source classification (strongest → weakest):
+ *   - `'parameter-annotation'` — function parameter type
+ *   - `'annotation'`          — explicit type declaration (`User user;`)
+ *   - `'assignment-inferred'` — typed init (`User user = ...`)
+ *   - `'constructor'`         — constructor call (`auto u = User(...)` / `User{}`)
+ *   - `'return'`              — function return type
+ *   - `'field'`               — class field type
+ *   - `'alias'`               — `auto x = existingVar`
+ */
+function interpretCppTypeBinding(captures) {
+    const name = captures['@type-binding.name']?.text;
+    const type = captures['@type-binding.type']?.text;
+    if (name === undefined || type === undefined)
+        return null;
+    let source = 'annotation';
+    if (captures['@type-binding.parameter'] !== undefined) {
+        source = 'parameter-annotation';
+    }
+    else if (captures['@type-binding.constructor'] !== undefined) {
+        source = 'constructor-inferred';
+    }
+    else if (captures['@type-binding.return'] !== undefined) {
+        source = 'return-annotation';
+    }
+    else if (captures['@type-binding.field'] !== undefined) {
+        // Field types are structurally equivalent to annotations — the type
+        // is explicitly written, not inferred.
+        source = 'annotation';
+    }
+    else if (captures['@type-binding.member-access'] !== undefined) {
+        // auto addr = user.address — the type is inferred from the member access.
+        // Synthesize a dotted rawName ("receiver.field") so compound-receiver
+        // can resolve the chain: look up receiver's class, then field's type.
+        const receiver = captures['@type-binding.member-access-receiver']?.text;
+        if (receiver !== undefined) {
+            return { boundName: name, rawTypeName: `${receiver}.${type}`, source: 'assignment-inferred' };
+        }
+        source = 'assignment-inferred';
+    }
+    else if (captures['@type-binding.alias'] !== undefined) {
+        // auto alias = existingVar — the type is inferred from the RHS variable.
+        source = 'assignment-inferred';
+    }
+    else if (captures['@type-binding.assignment'] !== undefined) {
+        source = 'assignment-inferred';
+    }
+    else if (captures['@type-binding.annotation'] !== undefined) {
+        source = 'annotation';
+    }
+    // A member field's type is captured AS WRITTEN, qualifier and all
+    // (`ns::Repo<User>`), because the query matches the outer
+    // `qualified_identifier` — one depth-agnostic pattern per declarator shape
+    // instead of one per qualifier depth. The qualifier is dropped HERE; see the
+    // "Field type, QUALIFIED" block in query.ts for why the qualified spelling
+    // resolves to nothing and the tail resolves like the bare one.
+    //
+    // FIELDS ONLY. `@type-binding.parameter` and `@type-binding.assignment` also
+    // capture qualified spellings (their patterns use `type: (_)`), and reducing
+    // THOSE would newly bind every qualified local and parameter in the workspace
+    // — a far wider change than the member-field miss this closes, and not one
+    // anything here has measured.
+    const effectiveType = captures['@type-binding.field'] === undefined ? type : cppQualifiedTail(type);
+    // The reduced spelling is also the AS-WRITTEN one, and saying so is load
+    // bearing. `collectTypeBindings` derives `TypeRef.declaredSpelling` from
+    // `@type-binding.type` whenever that text differs from `rawTypeName`, and it
+    // now does for every qualified member. `declaredSpelling` exists to keep a
+    // CONTAINER distinguishable from a class of the same name after capture
+    // reduced it; a qualifier is not a container — `ns::Address` and `Address`
+    // have the identical member set — so recording one here would answer
+    // "container, as written" for a plain member and hand `elementTypeOf` a
+    // spelling it never sees for the bare form.
+    const declaredSpelling = cppPointerSpelling(captures, effectiveType, name) ??
+        (effectiveType === type ? undefined : effectiveType);
+    return declaredSpelling === undefined
+        ? { boundName: name, rawTypeName: normalizeCppTypeName(effectiveType), source }
+        : {
+            boundName: name,
+            rawTypeName: normalizeCppTypeName(effectiveType),
+            declaredSpelling,
+            source,
+        };
+}
+/**
+ * The tail of a `::`-qualified type spelling — `a::b::Repo<User>` → `Repo<User>`,
+ * `ns::Address` → `Address`, an unqualified spelling unchanged.
+ *
+ * Only TOP-LEVEL separators count, so a qualified TYPE ARGUMENT survives:
+ * `std::vector<std::string>` reduces to `vector<std::string>`, not to `string`.
+ * That is the same string the old per-depth rules produced by capturing the
+ * inner node, so the reduction is textual where it used to be structural and
+ * the result is identical for every depth they covered.
+ */
+function cppQualifiedTail(text) {
+    let angleDepth = 0;
+    let lastSeparator = -1;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '<')
+            angleDepth++;
+        else if (ch === '>') {
+            if (angleDepth > 0)
+                angleDepth--;
+        }
+        else if (angleDepth === 0 && ch === ':' && text[i + 1] === ':') {
+            lastSeparator = i;
+            i++;
+        }
+    }
+    if (lastSeparator === -1)
+        return text;
+    const tail = text.slice(lastSeparator + 2).trim();
+    // A spelling that ends in `::` has no tail to reduce to. Cannot arise from a
+    // parsed `qualified_identifier`, but returning an empty type name would make
+    // the binding claim a type of `""`, so the written spelling is kept instead.
+    return tail.length === 0 ? text : tail;
+}
+/** Anchors whose capture spans a whole declaration, so the declarator — and
+ *  with it the pointer — is inside the captured text. */
+const CPP_WHOLE_DECLARATION_ANCHORS = [
+    '@type-binding.parameter',
+    '@type-binding.annotation',
+    '@type-binding.assignment',
+];
+const squeezeWhitespace = (text) => text.replace(/\s+/g, '');
+/**
+ * `User* repos` — the written spelling, when tree-sitter-cpp hangs the pointer
+ * off the DECLARATOR rather than the type.
+ *
+ * `@type-binding.type` is a bare `User` there, so the binding records `User` and
+ * nothing downstream can tell `repos[0]` (pointer subscript, element `User`)
+ * from `grid[0]` on a class with `operator[]` (element: whatever the operator
+ * returns). The index step needs that distinction and declines without it, so
+ * the pointer is reconstructed here — at the capture layer, from the anchor,
+ * which spans the whole declaration.
+ *
+ * EXACT SHAPE ONLY: the declaration must be precisely `<type> * <name>` once
+ * whitespace is removed. `const T*`, `T**`, an array declarator, a reference,
+ * a function pointer — none match, and none get a spelling, so the index step
+ * declines for them. A loose match would hand back container evidence that is
+ * not there and re-mint the confidently wrong edge this exists to prevent.
+ */
+function cppPointerSpelling(captures, typeText, nameText) {
+    // The target below always contains a literal `*`, so an anchor whose text has
+    // none can never equal it. Testing that FIRST is the whole optimisation: this
+    // runs on every C++ type binding and the overwhelming majority declare no
+    // pointer, so the squeezes (three `replace` passes over the declaration, the
+    // type and the name) are skipped entirely for them. `target` is built lazily
+    // on the first star-bearing anchor for the same reason.
+    let target;
+    for (const anchor of CPP_WHOLE_DECLARATION_ANCHORS) {
+        const text = captures[anchor]?.text;
+        if (text === undefined || !text.includes('*'))
+            continue;
+        if (target === undefined) {
+            const type = squeezeWhitespace(typeText);
+            const name = squeezeWhitespace(nameText);
+            if (type.length === 0 || name.length === 0)
+                return undefined;
+            target = `${type}*${name}`;
+        }
+        if (squeezeWhitespace(text) === target)
+            return `${typeText.trim()}*`;
+    }
+    return undefined;
+}
+/** Declaration specifiers that carry no type identity. Held in ONE place so
+ *  every consumer agrees on the keyword list — the resolver's element-type
+ *  hook strips exactly the same set before deciding whether a spelling is a
+ *  pointer, and a silently diverging copy there would make the two disagree
+ *  about what `const T*` is. */
+const CPP_SPECIFIER_RE = /\b(const|volatile|restrict|static|extern|inline|mutable|constexpr|consteval)\b/g;
+/** Remove C++ declaration specifiers from `text` and trim the result. */
+function stripCppSpecifiers(text) {
+    return text.replace(CPP_SPECIFIER_RE, '').trim();
+}
+/**
+ * Normalize a C++ type name: strip pointer/array/reference syntax,
+ * qualifiers, while preserving template arguments for specialization-aware
+ * receiver binding (`List<User>` vs `List<Order>`).
+ *
+ * Keeping template arguments here allows receiver-bound fallback to match
+ * specialization-specific class defs first; non-template behavior is preserved
+ * by base-name fallback in resolveClassBindingForName.
+ */
+function normalizeCppTypeName(text) {
+    let t = stripCppSpecifiers(text);
+    // Strip pointer stars
+    while (t.endsWith('*'))
+        t = t.slice(0, -1).trim();
+    while (t.startsWith('*'))
+        t = t.slice(1).trim();
+    // Strip reference markers
+    while (t.endsWith('&'))
+        t = t.slice(0, -1).trim();
+    // Strip array brackets
+    t = t.replace(/\[.*?\]/g, '').trim();
+    // Strip struct/union/enum/class prefixes
+    t = t.replace(/^(struct|union|enum|class)\s+/, '');
+    // Strip leading :: (global namespace qualifier)
+    t = t.replace(/^::/, '');
+    return t;
+}