cgraphx 2.0.2 → 2.0.3

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

@@ -0,0 +1,804 @@
+"use strict";
+/**
+ * C++ argument-dependent lookup (ADL / Koenig lookup).
+ *
+ * When ordinary unqualified lookup fails for a free-call site, ADL also
+ * considers candidates declared in the **associated namespaces** of the
+ * call's argument types (ISO C++ `[basic.lookup.argdep]`). The canonical
+ * pattern V1 unlocks:
+ *
+ *   namespace audit { struct Event; void record(Event); }
+ *   namespace app   { void run() { audit::Event e; record(e); } }
+ *
+ * Without ADL: `record(e)` is unresolved because `app::run` doesn't
+ * `using` anything. With V1 ADL: `audit::record` is discovered via
+ * `audit::Event`'s associated namespace.
+ *
+ * ## Current boundary
+ *
+ * The current implementation covers class-typed arguments (value, pointer,
+ * and reference) and template specializations with explicit type arguments:
+ *   - `audit::Event e`, `audit::Event* p`, `audit::Event** pp`
+ *   - `audit::Event& r`, `audit::Event&& rr`
+ *   - `std::vector<audit::Event>` (template namespace + template-arg namespaces)
+ *
+ * V2 additionally walks class ancestors (via MRO), so base-class enclosing
+ * namespaces also contribute associated namespaces.
+ *
+ * Function-reference arguments follow ISO C++ `[basic.lookup.argdep]`:
+ * associated entities come from the parameter types and return type of each
+ * referenced function in the overload set, not from the function's enclosing
+ * namespace. For `void worker()`, the associated set is empty. For
+ * `void worker(api::Token)` or `api::Token make_token()`, `api` is associated
+ * through `Token`.
+ *
+ * For qualified refs (e.g. `utils::worker`) the workspace lookup is restricted
+ * to functions/methods named `worker` in `utils`; for unqualified refs the
+ * workspace is searched for matching functions/methods by simple name. Locally
+ * declared function-pointer variables and function parameters are excluded
+ * from this path.
+ *
+ * ADL candidates are merged with ordinary unqualified-lookup candidates
+ * in the free-call fallback before overload narrowing.
+ *
+ * ## Parenthesized-name suppression
+ *
+ * `(f)(s)` MUST NOT trigger ADL — the parenthesized name forces ordinary
+ * lookup only. `captures.ts` records sites whose `function` child is a
+ * `parenthesized_expression` into `noAdlSites`; `pickCppAdlCandidates`
+ * short-circuits when the site key is present.
+ *
+ * ## State lifecycle
+ *
+ * Five pieces of module-level state populated per pipeline invocation, all
+ * reset together by `clearCppAdlState()` (called from
+ * `cppScopeResolver.loadResolutionConfig`, alongside `clearFileLocalNames` —
+ * NOT from `clearFileLocalNames` itself), grouped by when they fill:
+ *
+ *   - `argInfoBySite` — per-call-site argument shape (capture-time)
+ *   - `noAdlSites` — call sites with parenthesized function (capture-time)
+ *   - `classToNamespaceQualifiedName` — class def → its enclosing namespace
+ *     qualified name (`populateCppAssociatedNamespaces` time)
+ *   - `adlIndexByPass` — the lazily-built candidate index, memoized weakly on
+ *     the `parsedFiles` array it was built from (first-`pickCppAdlCandidates`
+ *     time; see `ensureAdlIndex`)
+ *
+ * The class→namespace map uses qualified names (not scope IDs) because
+ * C++ namespaces are open: `namespace N { ... }` in file A and
+ * `namespace N { ... }` in file B produce two distinct Namespace scopes
+ * but logically share the same namespace. ADL must consider candidates
+ * declared in either file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAdlSeqCoverage = validateAdlSeqCoverage;
+exports.markCppAdlSiteArgs = markCppAdlSiteArgs;
+exports.markCppAdlSiteNoAdl = markCppAdlSiteNoAdl;
+exports.collectCppAdlSideChannel = collectCppAdlSideChannel;
+exports.applyCppAdlSideChannel = applyCppAdlSideChannel;
+exports.clearCppAdlState = clearCppAdlState;
+exports.populateCppAssociatedNamespaces = populateCppAssociatedNamespaces;
+exports.pickCppAdlCandidates = pickCppAdlCandidates;
+const arity_metadata_js_1 = require("./arity-metadata.js");
+const inline_namespaces_js_1 = require("./inline-namespaces.js");
+const argInfoBySite = new Map();
+const noAdlSites = new Set();
+const classToNamespaceQualifiedName = new Map();
+/**
+ * Per-`filePath` index of the site keys this file contributed to
+ * `argInfoBySite` / `noAdlSites`, kept in **strict lockstep** with those two
+ * maps (#1983 perf). Without it, `collectCppAdlSideChannel(filePath)` had to
+ * scan the ENTIRE module-level maps (every site of every file the worker
+ * parsed in the current sub-batch) and `parseSiteKey` each entry just to pick
+ * out one file's slice — O(F²) per sub-batch (~100M `parseSiteKey` calls
+ * across the Linux kernel). These indexes turn collect into
+ * O(entries-for-this-file).
+ *
+ * Lockstep invariant: a key is pushed here at most once, exactly when it is
+ * first inserted into the corresponding map, and both indexes are cleared
+ * wherever `argInfoBySite` / `noAdlSites` are cleared (`clearCppAdlState` and
+ * the per-file restore in `applyCppAdlSideChannel`). The "first insert only"
+ * guard mirrors the maps' own de-dup (`Map.set` / `Set.add` are idempotent on
+ * the key), so iterating an index yields each of this file's keys exactly once
+ * — byte-identical to the old filtered full scan.
+ */
+const argInfoSiteKeysByFile = new Map();
+const noAdlSiteKeysByFile = new Map();
+/** Push `key` into the per-file index `idx[filePath]` (creating the bucket on
+ *  first use). Callers guard against duplicate keys so each key appears once. */
+function pushFileSiteKey(idx, filePath, key) {
+    let keys = idx.get(filePath);
+    if (keys === undefined) {
+        keys = [];
+        idx.set(filePath, keys);
+    }
+    keys.push(key);
+}
+/**
+ * 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 `qualifiedNsIndexByPass` in
+ * `inline-namespaces.ts` and `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 the
+ * previous 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.
+ */
+let adlIndexByPass = new WeakMap();
+function siteKey(filePath, line, col) {
+    return `${filePath}:${line}:${col}`;
+}
+/** Last segment of a dotted qualified name (matches legacy inline expression). */
+function adlSimpleName(def) {
+    return def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
+}
+function isAdlCallableType(type) {
+    return type === 'Function' || type === 'Method' || type === 'Constructor';
+}
+function pushNested(map, outerKey, innerKey, def) {
+    let inner = map.get(outerKey);
+    if (inner === undefined) {
+        inner = new Map();
+        map.set(outerKey, inner);
+    }
+    let arr = inner.get(innerKey);
+    if (arr === undefined) {
+        arr = [];
+        inner.set(innerKey, arr);
+    }
+    arr.push(def);
+}
+function pushFlat(map, key, def) {
+    let arr = map.get(key);
+    if (arr === undefined) {
+        arr = [];
+        map.set(key, arr);
+    }
+    arr.push(def);
+}
+/** Build the ADL candidate index in a single pass over the workspace. The
+ *  visitation order (file-major; per file, all namespace scopes before all
+ *  class scopes; ownedDefs in declaration order) mirrors the legacy push
+ *  order so `seqByNodeId` reconstructs identical candidate ordering. */
+function buildAdlIndex(scopes, parsedFiles) {
+    const idx = {
+        classDefsBySimple: new Map(),
+        nsCandidates: new Map(),
+        friendCandidates: new Map(),
+        nsFunctionsByQName: new Map(),
+        nsFunctionsBySimple: new Map(),
+        seqByNodeId: new Map(),
+    };
+    // (1) class-like defs by simple name — preserve byId order so arr[0] is the
+    //     legacy `firstMatch` and `arr.length > 1` is the legacy `ambiguous`.
+    for (const def of scopes.defs.byId.values()) {
+        if (def.type !== 'Class' &&
+            def.type !== 'Struct' &&
+            def.type !== 'Interface' &&
+            def.type !== 'Enum')
+            continue;
+        pushFlat(idx.classDefsBySimple, adlSimpleName(def), def);
+    }
+    let seq = 0;
+    for (const parsed of parsedFiles) {
+        const scopesById = new Map();
+        for (const sc of parsed.scopes)
+            scopesById.set(sc.id, sc);
+        // parent → children, built once (replaces the legacy O(scopes²) walk).
+        const childrenByParent = new Map();
+        for (const sc of parsed.scopes) {
+            if (sc.parent === null)
+                continue;
+            let kids = childrenByParent.get(sc.parent);
+            if (kids === undefined) {
+                kids = [];
+                childrenByParent.set(sc.parent, kids);
+            }
+            kids.push(sc);
+        }
+        // PASS A — namespace-owned candidates (+ function-reference indexes).
+        for (const scope of parsed.scopes) {
+            if (scope.kind !== 'Namespace')
+                continue;
+            const qName = computeNamespaceQName(scope, scopesById);
+            // Registration keys reproduce the legacy membership test: own QName
+            // always; for an inline namespace child of a Namespace, also the parent
+            // QName (ISO C++ inline-namespace transparency for ADL).
+            const keys = [];
+            if (qName !== '')
+                keys.push(qName);
+            if ((0, inline_namespaces_js_1.isCppInlineNamespaceScope)(scope.id)) {
+                const parentScope = scope.parent !== null ? scopesById.get(scope.parent) : undefined;
+                if (parentScope !== undefined && parentScope.kind === 'Namespace') {
+                    const parentQName = computeNamespaceQName(parentScope, scopesById);
+                    if (parentQName !== '' && parentQName !== qName)
+                        keys.push(parentQName);
+                }
+            }
+            for (const def of scope.ownedDefs) {
+                if (def.type === 'Function' || def.type === 'Method') {
+                    const sn = adlSimpleName(def);
+                    pushFlat(idx.nsFunctionsBySimple, sn, def);
+                    if (qName !== '')
+                        pushNested(idx.nsFunctionsByQName, qName, sn, def);
+                }
+                if (!isAdlCallableType(def.type))
+                    continue;
+                const s = seq++;
+                idx.seqByNodeId.set(def.nodeId, s);
+                const sn = adlSimpleName(def);
+                for (const key of keys)
+                    pushNested(idx.nsCandidates, key, sn, def);
+            }
+        }
+        // PASS B — hidden-friend + class-member candidates for associated classes.
+        for (const scope of parsed.scopes) {
+            if (scope.kind !== 'Class')
+                continue;
+            // Enclosing-namespace QName(s) of the class def(s) in this scope.
+            const classNsKeys = new Set();
+            for (const def of scope.ownedDefs) {
+                if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface')
+                    continue;
+                const nsQName = classToNamespaceQualifiedName.get(def.nodeId);
+                if (nsQName !== undefined)
+                    classNsKeys.add(nsQName);
+            }
+            if (classNsKeys.size === 0)
+                continue;
+            // Friend functions: callable defs in child Function scopes.
+            for (const childScope of childrenByParent.get(scope.id) ?? []) {
+                if (childScope.kind !== 'Function')
+                    continue;
+                for (const def of childScope.ownedDefs) {
+                    if (!isAdlCallableType(def.type))
+                        continue;
+                    const s = seq++;
+                    idx.seqByNodeId.set(def.nodeId, s);
+                    const sn = adlSimpleName(def);
+                    for (const key of classNsKeys)
+                        pushNested(idx.friendCandidates, key, sn, def);
+                }
+            }
+            // Class-member callables.
+            for (const def of scope.ownedDefs) {
+                if (!isAdlCallableType(def.type))
+                    continue;
+                const s = seq++;
+                idx.seqByNodeId.set(def.nodeId, s);
+                const sn = adlSimpleName(def);
+                for (const key of classNsKeys)
+                    pushNested(idx.friendCandidates, key, sn, def);
+            }
+        }
+    }
+    // Dev/test-only invariant guard: every def bucketed into nsCandidates/
+    // friendCandidates must have a seqByNodeId entry, otherwise the `?? 0`
+    // fallback in pickCppAdlCandidates could collapse two seq-0 candidates and
+    // silently drop a CALLS edge. Gated like the rest of the resolver's opt-in
+    // validation (see contract/scope-resolver.ts and reconcile-ownership.ts):
+    // active in dev/test, off in production and when VALIDATE_SEMANTIC_MODEL=0.
+    if (process.env.NODE_ENV !== 'production' && process.env.VALIDATE_SEMANTIC_MODEL !== '0') {
+        const missing = validateAdlSeqCoverage(idx);
+        if (missing.length > 0) {
+            throw new Error(`[cpp-adl] seq-coverage invariant violated: ${missing.length} candidate def(s) ` +
+                `bucketed without a seqByNodeId entry (e.g. ${missing.slice(0, 5).join(', ')}). ` +
+                `Every def pushed into nsCandidates/friendCandidates must be seq-assigned in the ` +
+                `same build block — see pickCppAdlCandidates' \`?? 0\` fallback.`);
+        }
+    }
+    return idx;
+}
+/**
+ * Return the nodeIds present in the index's candidate buckets
+ * (`nsCandidates` + `friendCandidates`) but missing from `seqByNodeId`, each
+ * reported once. Empty array means the seq-coverage invariant holds — which it
+ * must, since `buildAdlIndex` assigns a seq to every callable def in the same
+ * block that buckets it. Exported for the dev-gated guard in `buildAdlIndex`
+ * and its unit test.
+ */
+function validateAdlSeqCoverage(idx) {
+    const missing = new Set();
+    for (const buckets of [idx.nsCandidates, idx.friendCandidates]) {
+        for (const bySimple of buckets.values()) {
+            for (const defs of bySimple.values()) {
+                for (const def of defs) {
+                    if (!idx.seqByNodeId.has(def.nodeId))
+                        missing.add(def.nodeId);
+                }
+            }
+        }
+    }
+    return [...missing];
+}
+/** Build the ADL index on first use of a given `parsedFiles` set; reuse it for
+ *  every subsequent call site in the same pipeline run. Reset by
+ *  `clearCppAdlState`.
+ *
+ *  Lifetime: the memoized entry is reachable only while the caller still holds
+ *  the `parsedFiles` array. Once the pipeline drops it, the entry — and the
+ *  `SymbolDefinition` references it holds into those files' scopes — becomes
+ *  collectable; nothing here pins it (see {@link adlIndexByPass}).
+ *
+ *  Staleness is keyed on `parsedFiles` reference identity ONLY, but the index
+ *  is a function of THREE inputs: `parsedFiles` (namespace/friend candidates),
+ *  `scopes` (`classDefsBySimple`, read from `scopes.defs.byId`), and the
+ *  module-level `classToNamespaceQualifiedName` (friend-candidate keys). The
+ *  WeakMap key covers only the first, so the explicit clear is still REQUIRED
+ *  for the other two: a later pass may hand back the same `parsedFiles`
+ *  reference with different `scopes` / class→namespace state, and identity
+ *  alone would serve the stale index. This is sound for the current pipeline
+ *  because all three are built together once per `runScopeResolution` pass and
+ *  `clearCppAdlState` runs in `loadResolutionConfig` at the start of every
+ *  pass. Callers MUST call `clearCppAdlState` between any two passes that
+ *  change `scopes` or `classToNamespaceQualifiedName` while reusing the same
+ *  `parsedFiles` array reference — otherwise a stale index would be served.
+ *  (No such caller exists today; widening the key to also cover `scopes` is
+ *  deferred until one does.) */
+function ensureAdlIndex(scopes, parsedFiles) {
+    let index = adlIndexByPass.get(parsedFiles);
+    if (index === undefined) {
+        index = buildAdlIndex(scopes, parsedFiles);
+        adlIndexByPass.set(parsedFiles, index);
+    }
+    return index;
+}
+/** Record per-call-site argument info. Called once per call site from
+ *  `emitCppScopeCaptures`. */
+function markCppAdlSiteArgs(filePath, line, col, args) {
+    const key = siteKey(filePath, line, col);
+    // Lockstep with `argInfoSiteKeysByFile`: index the key only on first insert
+    // (a re-mark overwrites the value but must NOT duplicate the index entry).
+    if (!argInfoBySite.has(key))
+        pushFileSiteKey(argInfoSiteKeysByFile, filePath, key);
+    argInfoBySite.set(key, args);
+}
+/** Mark a call site as ADL-suppressed (function child wrapped in
+ *  `parenthesized_expression`, e.g. `(f)(s)`). */
+function markCppAdlSiteNoAdl(filePath, line, col) {
+    const key = siteKey(filePath, line, col);
+    // Lockstep with `noAdlSiteKeysByFile`: index the key only on first insert.
+    if (!noAdlSites.has(key))
+        pushFileSiteKey(noAdlSiteKeysByFile, filePath, key);
+    noAdlSites.add(key);
+}
+const SITE_KEY_RE = /^(.*):(\d+):(\d+)$/;
+/** Split a `filePath:line:col` site key, tolerating colons in the path. */
+function parseSiteKey(key) {
+    const m = SITE_KEY_RE.exec(key);
+    if (m === null)
+        return undefined;
+    return { filePath: m[1], line: Number(m[2]), col: Number(m[3]) };
+}
+/**
+ * Snapshot this file's ADL capture state for the worker→main side-channel.
+ *
+ * Uses the per-file `argInfoSiteKeysByFile` / `noAdlSiteKeysByFile` indexes to
+ * touch only THIS file's entries — O(entries-for-this-file) — instead of the
+ * old O(all-entries) full scan over `argInfoBySite` / `noAdlSites` (#1983).
+ * The output order, and therefore the serialized JSON shape, is byte-identical
+ * to the old filtered scan: the index records keys in the same insertion order
+ * the maps' own iteration would have yielded for this file, and each key is
+ * indexed exactly once (mark guards on first insert), so the same per-file
+ * subsequence is produced.
+ *
+ * `parseSiteKey` is still used to recover `line:col` from each key, but now
+ * only for this file's keys (a bounded handful), never for the whole batch.
+ */
+function collectCppAdlSideChannel(filePath) {
+    const args = [];
+    for (const key of argInfoSiteKeysByFile.get(filePath) ?? []) {
+        const value = argInfoBySite.get(key);
+        const parsed = parseSiteKey(key);
+        if (value !== undefined && parsed !== undefined) {
+            args.push([parsed.line, parsed.col, value]);
+        }
+    }
+    const noAdl = [];
+    for (const key of noAdlSiteKeysByFile.get(filePath) ?? []) {
+        const parsed = parseSiteKey(key);
+        if (parsed !== undefined) {
+            noAdl.push([parsed.line, parsed.col]);
+        }
+    }
+    return { argInfoBySite: args, noAdlSites: noAdl };
+}
+/** Restore this file's ADL capture state from the side-channel (no parse).
+ *  Keeps the per-file site-key indexes in lockstep with `argInfoBySite` /
+ *  `noAdlSites` (first-insert-only) so a later `collectCppAdlSideChannel` on
+ *  the same process would still produce a correct, duplicate-free snapshot. */
+function applyCppAdlSideChannel(filePath, data) {
+    for (const [line, col, value] of data.argInfoBySite) {
+        const key = siteKey(filePath, line, col);
+        if (!argInfoBySite.has(key))
+            pushFileSiteKey(argInfoSiteKeysByFile, filePath, key);
+        argInfoBySite.set(key, value);
+    }
+    for (const [line, col] of data.noAdlSites) {
+        const key = siteKey(filePath, line, col);
+        if (!noAdlSites.has(key))
+            pushFileSiteKey(noAdlSiteKeysByFile, filePath, key);
+        noAdlSites.add(key);
+    }
+}
+/** Clear ADL state. Called from `cppScopeResolver.loadResolutionConfig`
+ *  (alongside `clearFileLocalNames`) so all C++ resolver per-pipeline state is
+ *  reset together at the start of each resolution pass. */
+function clearCppAdlState() {
+    argInfoBySite.clear();
+    noAdlSites.clear();
+    // Lockstep: the per-file site-key indexes mirror argInfoBySite/noAdlSites and
+    // MUST be cleared together — a stale index would resurrect a prior pass's
+    // (or prior file's, after a re-key) keys into the next snapshot.
+    argInfoSiteKeysByFile.clear();
+    noAdlSiteKeysByFile.clear();
+    classToNamespaceQualifiedName.clear();
+    // The candidate index is dropped by REASSIGNING a fresh `WeakMap`: `WeakMap`
+    // has no `.clear()`, and swapping the instance discards every memoized entry
+    // at once — the exact invalidation the previous `adlIndex = undefined` pair
+    // provided. Required even though the map is keyed on `parsedFiles` identity,
+    // because the index also depends on `scopes` and
+    // `classToNamespaceQualifiedName`, which the key cannot observe (see
+    // {@link ensureAdlIndex}).
+    adlIndexByPass = new WeakMap();
+}
+/**
+ * Walk `parsed.scopes` to record each Class def's enclosing namespace
+ * qualified name. Run from the cpp resolver's `populateOwners` hook so
+ * the index is available before any resolution pass consults it.
+ *
+ * Computes the namespace's qualified name by walking parent scope chain
+ * and looking up Namespace defs in each parent's `ownedDefs`. The
+ * resulting name is dot-joined (matching `populateClassOwnedMembers`'s
+ * dotted convention; conversion to `::` is consumer-internal).
+ */
+function populateCppAssociatedNamespaces(parsed) {
+    const scopesById = new Map();
+    for (const scope of parsed.scopes)
+        scopesById.set(scope.id, scope);
+    for (const scope of parsed.scopes) {
+        if (scope.kind !== 'Class')
+            continue;
+        const nsQName = computeEnclosingNamespaceQName(scope, scopesById);
+        if (nsQName === '')
+            continue;
+        for (const def of scope.ownedDefs) {
+            if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface')
+                continue;
+            classToNamespaceQualifiedName.set(def.nodeId, nsQName);
+        }
+    }
+    // Enum defs live in Namespace scopes directly (not inside Class scopes).
+    // Map each Enum def to its enclosing namespace so ADL on enum-typed
+    // arguments contributes the correct associated namespace.
+    for (const scope of parsed.scopes) {
+        if (scope.kind !== 'Namespace')
+            continue;
+        const nsQName = computeNamespaceQName(scope, scopesById);
+        if (nsQName === '')
+            continue;
+        for (const def of scope.ownedDefs) {
+            if (def.type !== 'Enum')
+                continue;
+            classToNamespaceQualifiedName.set(def.nodeId, nsQName);
+        }
+    }
+}
+/**
+ * ADL candidate collector. Returns:
+ *   - `readonly SymbolDefinition[]` — ADL candidates to merge with
+ *     ordinary unqualified lookup candidates.
+ *   - `undefined` — no ADL candidates.
+ *
+ * Fires only when:
+ *   - the call site is not in `noAdlSites` (parenthesized form), AND
+ *   - at least one argument resolves to a named class type (value,
+ *     pointer, or reference; but not function pointer, literal, or primitive).
+ */
+function pickCppAdlCandidates(site, callerParsed, scopes, parsedFiles) {
+    const key = siteKey(callerParsed.filePath, site.atRange.startLine, site.atRange.startCol);
+    if (noAdlSites.has(key))
+        return undefined;
+    const args = argInfoBySite.get(key);
+    if (args === undefined || args.length === 0)
+        return undefined;
+    // Build the workspace-wide ADL candidate index once; reuse for every site.
+    const idx = ensureAdlIndex(scopes, parsedFiles);
+    // Collect associated namespace QNames from every participating class-typed arg
+    // and from function-reference args.
+    const associatedNamespaces = new Set();
+    for (const arg of args) {
+        collectAssociatedNamespacesForAdlArg(arg, scopes, idx, associatedNamespaces);
+        if (arg.functionRefText !== undefined) {
+            collectFunctionTypeAssociatedNamespaces(arg.functionRefText, scopes, idx, associatedNamespaces);
+        }
+    }
+    if (associatedNamespaces.size === 0)
+        return undefined;
+    // Gather candidates from the prebuilt index instead of re-scanning every
+    // parsed file. For each associated namespace, pull:
+    //   - namespace-owned callables (`nsCandidates`, includes inline-namespace
+    //     transparency), AND
+    //   - hidden-friend / class-member callables of associated classes
+    //     (`friendCandidates`, ISO C++ `[basic.lookup.argdep]` §2).
+    // Dedup by nodeId and sort by visitation sequence so the candidate list is
+    // byte-for-byte identical to the legacy file-major scan order.
+    const bySeq = new Map();
+    const seenKey = new Set();
+    const collectFrom = (buckets) => {
+        for (const ns of associatedNamespaces) {
+            const matches = buckets.get(ns)?.get(site.name);
+            if (matches === undefined)
+                continue;
+            for (const def of matches) {
+                if (seenKey.has(def.nodeId))
+                    continue;
+                seenKey.add(def.nodeId);
+                // `?? 0` is unreachable: every bucketed def is seq-assigned in the same
+                // block that buckets it in buildAdlIndex (PASS A / PASS B). The dev-gated
+                // validateAdlSeqCoverage guard in buildAdlIndex fails loudly if that ever
+                // breaks, rather than letting two seq-0 defs collide and drop a candidate.
+                bySeq.set(idx.seqByNodeId.get(def.nodeId) ?? 0, def);
+            }
+        }
+    };
+    collectFrom(idx.nsCandidates);
+    collectFrom(idx.friendCandidates);
+    if (bySeq.size === 0)
+        return undefined;
+    return [...bySeq.entries()].sort((a, b) => a[0] - b[0]).map(([, def]) => def);
+}
+function collectAssociatedNamespacesForAdlArg(arg, scopes, idx, associatedNamespaces) {
+    // For template args this may be the template name itself (e.g. `vector`);
+    // simple-name lookup can match project classes with the same name (known
+    // V1/V2 simplification).
+    addAssociatedNamespaceForClassName(arg.simpleClassName, scopes, idx, associatedNamespaces);
+    // Includes template-owner namespaces (e.g. `std` in std::vector<T>). If
+    // that surfaces extra candidates, merged-candidate overload narrowing in
+    // free-call-fallback suppresses arbitrary edge emission.
+    if (arg.templateNamespace.length > 0)
+        associatedNamespaces.add(arg.templateNamespace);
+    for (const ns of arg.templateArgNamespaces) {
+        if (ns.length > 0)
+            associatedNamespaces.add(ns);
+    }
+    for (const className of arg.templateArgClassNames) {
+        addAssociatedNamespaceForClassName(className, scopes, idx, associatedNamespaces);
+    }
+}
+function addAssociatedNamespaceForClassName(simpleClassName, scopes, idx, associatedNamespaces) {
+    if (simpleClassName.length === 0)
+        return;
+    const classLookup = findCppClassDefBySimpleName(idx, simpleClassName);
+    if (classLookup === undefined)
+        return;
+    const { classDef, ambiguous } = classLookup;
+    const nsQName = classToNamespaceQualifiedName.get(classDef.nodeId);
+    if (nsQName !== undefined)
+        associatedNamespaces.add(nsQName);
+    // Preserve V1 collision behavior for the direct class namespace, but avoid
+    // amplifying a same-simple-name collision by walking an arbitrary class's
+    // full MRO chain.
+    if (ambiguous)
+        return;
+    for (const ancestorDefId of scopes.methodDispatch.mroFor(classDef.nodeId)) {
+        const ancestorNsQName = classToNamespaceQualifiedName.get(ancestorDefId);
+        if (ancestorNsQName !== undefined)
+            associatedNamespaces.add(ancestorNsQName);
+    }
+}
+/** Walk upward from a Class scope, finding the innermost enclosing
+ *  Namespace scope, and return that namespace's qualified name (dot-
+ *  joined, outermost-first). Returns '' when the class has no enclosing
+ *  namespace (e.g., declared at translation-unit scope). */
+function computeEnclosingNamespaceQName(classScope, scopesById) {
+    let parentId = classScope.parent;
+    while (parentId !== null) {
+        const parent = scopesById.get(parentId);
+        if (parent === undefined)
+            return '';
+        if (parent.kind === 'Namespace') {
+            return computeNamespaceQName(parent, scopesById);
+        }
+        parentId = parent.parent;
+    }
+    return '';
+}
+/** Walk upward from a Namespace scope collecting each enclosing
+ *  Namespace's simple name (innermost last). Returns the dot-joined
+ *  qualified name (e.g., `outer.inner`). The namespace's own def lives
+ *  in its OWN scope's `ownedDefs` (the C++ extractor stamps the
+ *  namespace-decl def into the namespace scope itself, not the parent
+ *  module scope). */
+function computeNamespaceQName(nsScope, scopesById) {
+    const segments = [];
+    let currentId = nsScope.parent;
+    let current = nsScope;
+    // Outer guard against pathological cycles in malformed scope trees.
+    let safety = 64;
+    while (current !== undefined && safety-- > 0) {
+        const nsDef = findNamespaceDefInScope(current);
+        if (nsDef === undefined) {
+            // No name found — bail out. Returning a partial QName would risk
+            // false ADL associations.
+            return '';
+        }
+        const simple = nsDef.qualifiedName?.split('.').pop() ?? nsDef.qualifiedName ?? '';
+        segments.unshift(simple);
+        // Walk up to next enclosing namespace (skipping non-namespace parents).
+        let nextId = currentId;
+        let nextNs;
+        while (nextId !== null) {
+            const nx = scopesById.get(nextId);
+            if (nx === undefined)
+                break;
+            if (nx.kind === 'Namespace') {
+                nextNs = nx;
+                currentId = nx.parent;
+                break;
+            }
+            nextId = nx.parent;
+        }
+        current = nextNs;
+    }
+    return segments.join('.');
+}
+/** Find the Namespace def attached to this scope (the namespace's own
+ *  decl, stamped into its own `ownedDefs` by the C++ extractor). Returns
+ *  the first Namespace-type def encountered — for normal C++ the scope
+ *  carries exactly one Namespace-typed self def. */
+function findNamespaceDefInScope(scope) {
+    for (const def of scope.ownedDefs) {
+        if (def.type === 'Namespace')
+            return def;
+    }
+    return undefined;
+}
+/** Find a class-like or enum def by simple name across the workspace.
+ *  V1 still arbitrary-picks the first match on collisions (multiple defs
+ *  share the simple name), but reports the collision so callers can avoid
+ *  amplifying that uncertainty (for example by skipping MRO expansion).
+ *  C++ ADL strictness would require full type-driven lookup.
+ *
+ *  ISO C++ `[basic.lookup.argdep]` §2: enumerations contribute their
+ *  enclosing namespace to the associated set, just like class types. */
+function findCppClassDefBySimpleName(idx, simpleName) {
+    // `classDefsBySimple` preserves `scopes.defs.byId` order, so `[0]` is the
+    // legacy first-match and `length > 1` is the legacy `ambiguous` flag.
+    const matches = idx.classDefsBySimple.get(simpleName);
+    if (matches === undefined)
+        return undefined;
+    const first = matches[0];
+    if (first === undefined)
+        return undefined;
+    return { classDef: first, ambiguous: matches.length > 1 };
+}
+/**
+ * Contribute associated namespaces for a function-reference argument by walking
+ * the referenced overload set's parameter and return types.
+ */
+function collectFunctionTypeAssociatedNamespaces(refText, scopes, idx, out) {
+    const colonIdx = refText.lastIndexOf('::');
+    if (colonIdx !== -1) {
+        // Qualified ref: extract namespace prefix and normalise :: → dot notation.
+        const nsText = refText.slice(0, colonIdx).replace(/::/g, '.');
+        if (nsText === '')
+            return;
+        const simpleName = refText.slice(colonIdx + 2);
+        // Only Function/Method defs named `simpleName` in `nsText` contribute
+        // (the index already restricts to those types); this guards against an
+        // `a::b` arg that names a variable / enum value / type alias blindly
+        // contributing `a` to the associated set (false-positive CALLS edge).
+        const matches = idx.nsFunctionsByQName.get(nsText)?.get(simpleName);
+        if (matches !== undefined) {
+            for (const def of matches)
+                collectAssociatedNamespacesForFunctionDef(def, scopes, idx, out);
+        }
+        return;
+    }
+    // Unqualified function references are approximated workspace-wide, matching
+    // the previous V1 lookup scope. The stricter part of this PR is what each
+    // overload contributes: only namespaces from parameter/return types, never
+    // the function's own enclosing namespace.
+    const matches = idx.nsFunctionsBySimple.get(refText);
+    if (matches !== undefined) {
+        for (const def of matches)
+            collectAssociatedNamespacesForFunctionDef(def, scopes, idx, out);
+    }
+}
+function collectAssociatedNamespacesForFunctionDef(def, scopes, idx, out) {
+    const parameterTypes = def.parameterTypeClasses?.map((typeClass) => typeClass.base);
+    for (const paramType of parameterTypes ?? def.parameterTypes ?? []) {
+        collectAssociatedNamespacesForFunctionTypeText(paramType, scopes, idx, out);
+    }
+    if (def.returnType !== undefined) {
+        collectAssociatedNamespacesForFunctionTypeText(def.returnType, scopes, idx, out);
+    }
+}
+function collectAssociatedNamespacesForFunctionTypeText(typeText, scopes, idx, out) {
+    for (const token of extractCppTypeNameTokens(typeText)) {
+        if (isIgnoredCppAdlNamespace(token.namespaceName))
+            continue;
+        addAssociatedNamespaceForClassName(token.simpleName, scopes, idx, out);
+        if (token.namespaceName !== '')
+            out.add(token.namespaceName);
+    }
+}
+function extractCppTypeNameTokens(typeText) {
+    const cleaned = (0, arity_metadata_js_1.normalizeCppParamType)(typeText);
+    if (cleaned === '' || isPrimitiveCppAdlType(cleaned))
+        return [];
+    const out = [];
+    const seen = new Set();
+    const tokenSource = typeText.includes('<') ? `${cleaned} ${typeText}` : cleaned;
+    for (const rawToken of tokenSource.match(/[A-Za-z_]\w*(?:::[A-Za-z_]\w*)*/g) ?? []) {
+        if (isPrimitiveCppAdlType(rawToken))
+            continue;
+        const segments = rawToken.split('::').filter((part) => part.length > 0);
+        const simpleName = segments.at(-1) ?? '';
+        if (simpleName === '' || isPrimitiveCppAdlType(simpleName))
+            continue;
+        const namespaceName = segments.length > 1 ? segments.slice(0, -1).join('.') : '';
+        const key = `${namespaceName}\0${simpleName}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({
+            simpleName,
+            namespaceName,
+        });
+    }
+    return out;
+}
+const CPP_ADL_PRIMITIVE_OR_KEYWORD_TYPES = new Set([
+    'alignas',
+    'alignof',
+    'auto',
+    'bool',
+    'char',
+    'char8_t',
+    'char16_t',
+    'char32_t',
+    'class',
+    'const',
+    'consteval',
+    'constexpr',
+    'constinit',
+    'decltype',
+    'double',
+    'enum',
+    'explicit',
+    'extern',
+    'float',
+    'inline',
+    'int',
+    'long',
+    'mutable',
+    'noexcept',
+    'null',
+    'register',
+    'short',
+    'signed',
+    'static',
+    'string',
+    'struct',
+    'template',
+    'thread_local',
+    'typename',
+    'union',
+    'unknown',
+    'unsigned',
+    'void',
+    'volatile',
+    'wchar_t',
+    '...',
+]);
+function isPrimitiveCppAdlType(typeText) {
+    return CPP_ADL_PRIMITIVE_OR_KEYWORD_TYPES.has(typeText);
+}
+function isIgnoredCppAdlNamespace(namespaceName) {
+    return namespaceName === 'std' || namespaceName.startsWith('std.');
+}