gitnexus 1.6.6-rc.80 → 1.6.6-rc.82

package/dist/core/group/extractors/http-patterns/python.js

@@ -19,9 +19,13 @@ const FASTAPI_VERBS = {
     delete: 'DELETE',
     patch: 'PATCH',
 };
-// ─── Provider: FastAPI @app.get/... ──────────────────────────────────
-const FASTAPI_PATTERNS = compilePatterns({
-    name: 'python-fastapi',
+// ─── Provider: FastAPI @app.<verb> / @router.<verb> ──────────────────
+// Two separate patterns so we can tag detections by decorator object.
+// Only `@router.*` detections participate in `include_router(prefix=)`
+// path-prefix joining (see `PythonRepoContext` + `joinPrefix`); `@app.*`
+// routes already carry their final path verbatim.
+const FASTAPI_APP_PATTERNS = compilePatterns({
+    name: 'python-fastapi-app',
     language: Python,
     patterns: [
         {
@@ -37,6 +41,133 @@ const FASTAPI_PATTERNS = compilePatterns({
         },
     ],
 });
+const FASTAPI_ROUTER_PATTERNS = compilePatterns({
+    name: 'python-fastapi-router',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (decorator
+          (call
+            function: (attribute
+              object: (identifier) @obj (#eq? @obj "router")
+              attribute: (identifier) @method (#match? @method "^(get|post|put|delete|patch)$"))
+            arguments: (argument_list . (string) @path)))
+      `,
+        },
+    ],
+});
+// ─── include_router(<router_obj>, prefix='/x') across the repo ────────
+// Two shapes are common:
+//   app.include_router(assistant.router, prefix='/ai')
+//   app.include_router(my_router, prefix='/ai')
+// The first names the originating module via `<module>.router`; the second
+// references a name imported into the host file. We capture both.
+const INCLUDE_ROUTER_ATTR_PATTERNS = compilePatterns({
+    name: 'python-fastapi-include-router-attr',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            // Match any `<host>.include_router(<module>.router, ..., prefix='/x')`
+            // call. We deliberately do NOT pin `<host>` to the literal name `app`
+            // — production code routinely uses `api`, `application`, `asgi_app`,
+            // etc. The shape (`include_router` invoked with a router argument and
+            // a `prefix=` keyword) is specific enough on its own; restricting the
+            // host produces false negatives without removing meaningful false
+            // positives.
+            query: `
+        (call
+          function: (attribute
+            attribute: (identifier) @incl (#eq? @incl "include_router"))
+          arguments: (argument_list
+            (attribute
+              object: (identifier) @router_module
+              attribute: (identifier) @router_attr (#eq? @router_attr "router"))
+            (keyword_argument
+              name: (identifier) @kw (#eq? @kw "prefix")
+              value: (string) @prefix)))
+      `,
+        },
+    ],
+});
+const INCLUDE_ROUTER_NAME_PATTERNS = compilePatterns({
+    name: 'python-fastapi-include-router-name',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            // Same `<host>` rationale as INCLUDE_ROUTER_ATTR_PATTERNS — see above.
+            query: `
+        (call
+          function: (attribute
+            attribute: (identifier) @incl (#eq? @incl "include_router"))
+          arguments: (argument_list
+            (identifier) @router_name
+            (keyword_argument
+              name: (identifier) @kw (#eq? @kw "prefix")
+              value: (string) @prefix)))
+      `,
+        },
+    ],
+});
+// `from .api.assistant import router` style — used together with
+// INCLUDE_ROUTER_NAME so we can map a local name back to its module
+// path, then back to the file the router was declared in.
+const FROM_IMPORT_ROUTER_PATTERNS = compilePatterns({
+    name: 'python-fastapi-from-import-router',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (import_from_statement
+          module_name: (_) @module
+          name: (dotted_name (identifier) @imported (#eq? @imported "router")))
+      `,
+        },
+        {
+            meta: {},
+            query: `
+        (import_from_statement
+          module_name: (_) @module
+          name: (aliased_import
+            name: (dotted_name (identifier) @imported (#eq? @imported "router"))
+            alias: (identifier) @alias))
+      `,
+        },
+    ],
+});
+// `from api import users` / `from api import users as u` — module-level
+// imports where the imported name is itself the module that owns
+// `<name>.router`. Lets Shape A (`<host>.include_router(<name>.router, …)`)
+// look up the full package path of `<name>` and pin the prefix onto the
+// exact file (`api/users.py`) rather than every file basenamed `users.py`.
+const FROM_IMPORT_MODULE_PATTERNS = compilePatterns({
+    name: 'python-fastapi-from-import-module',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (import_from_statement
+          module_name: (_) @module
+          name: (dotted_name (identifier) @imported))
+      `,
+        },
+        {
+            meta: {},
+            query: `
+        (import_from_statement
+          module_name: (_) @module
+          name: (aliased_import
+            name: (dotted_name (identifier) @imported)
+            alias: (identifier) @alias))
+      `,
+        },
+    ],
+});
 // ─── Consumer: requests.get/post/... ──────────────────────────────────
 const REQUESTS_VERB_PATTERNS = compilePatterns({
     name: 'python-requests-verb',
@@ -405,14 +536,183 @@ const HTTPX_ASYNC_CLIENT_GENERIC_PATTERNS = compilePatterns({
         },
     ],
 });
+/** Strip `.py` and return the bare basename (e.g. `api/users.py` → `users`). */
+function fileShortKey(rel) {
+    const slash = rel.lastIndexOf('/');
+    const file = slash >= 0 ? rel.slice(slash + 1) : rel;
+    return file.endsWith('.py') ? file.slice(0, -3) : file;
+}
+/**
+ * Long key for a `.py` file: parent directory + stem, joined with `/`.
+ * Files at the repo root return the empty string (no parent), in which
+ * case callers should fall back to the short key.
+ */
+function fileLongKey(rel) {
+    const noExt = rel.endsWith('.py') ? rel.slice(0, -3) : rel;
+    const lastSlash = noExt.lastIndexOf('/');
+    if (lastSlash < 0)
+        return '';
+    const beforeLast = noExt.slice(0, lastSlash);
+    const stem = noExt.slice(lastSlash + 1);
+    const prevSlash = beforeLast.lastIndexOf('/');
+    const parent = prevSlash >= 0 ? beforeLast.slice(prevSlash + 1) : beforeLast;
+    return `${parent}/${stem}`;
+}
+/** Last `.`-separated segment of a (possibly relative) module path. */
+function lastSegmentOfDotted(text) {
+    const stripped = text.replace(/^\.+/, '');
+    if (!stripped)
+        return '';
+    const dot = stripped.lastIndexOf('.');
+    return dot >= 0 ? stripped.slice(dot + 1) : stripped;
+}
+/**
+ * Last two `.`-separated segments of a (possibly relative) module path
+ * joined with `/`, e.g. `api.users` → `api/users`. Single-segment paths
+ * and pure-dot inputs return the empty string; callers should fall back
+ * to the short key in that case.
+ */
+function lastTwoSegmentsAsLongKey(text) {
+    const stripped = text.replace(/^\.+/, '');
+    if (!stripped)
+        return '';
+    const last = stripped.lastIndexOf('.');
+    if (last <= 0)
+        return '';
+    const beforeLast = stripped.slice(0, last);
+    const stem = stripped.slice(last + 1);
+    const prev = beforeLast.lastIndexOf('.');
+    const parent = prev >= 0 ? beforeLast.slice(prev + 1) : beforeLast;
+    return `${parent}/${stem}`;
+}
+function recordPrefix(target, key, prefix) {
+    const set = target.get(key) ?? new Set();
+    set.add(prefix);
+    target.set(key, set);
+}
+function buildPythonRepoContext(files, parser, readFile, parseSource) {
+    const prefixesByLongKey = new Map();
+    const prefixesByShortKey = new Map();
+    // Pre-pass over .py files. We deliberately run this even on files
+    // that don't contain `include_router` — the cost of an extra parse
+    // is bounded by the file count, and detecting `include_router`
+    // beforehand would require its own grep/scan.
+    for (const rel of files) {
+        if (!rel.endsWith('.py'))
+            continue;
+        const src = readFile(rel);
+        if (!src)
+            continue;
+        if (!src.includes('include_router'))
+            continue;
+        parser.setLanguage(Python);
+        const tree = parseSource(parser, src);
+        if (!tree)
+            continue;
+        const localNameToModule = new Map();
+        for (const m of runCompiledPatterns(FROM_IMPORT_ROUTER_PATTERNS, tree)) {
+            const moduleNode = m.captures.module;
+            const aliasNode = m.captures.alias;
+            const importedNode = m.captures.imported;
+            if (!moduleNode || !importedNode)
+                continue;
+            const localName = aliasNode?.text ?? importedNode.text;
+            const moduleShort = lastSegmentOfDotted(moduleNode.text);
+            if (!moduleShort)
+                continue;
+            const moduleLong = lastTwoSegmentsAsLongKey(moduleNode.text);
+            localNameToModule.set(localName, { moduleShort, moduleLong });
+        }
+        // Module-alias map: name imported from a multi-segment package →
+        // long key. Lets Shape A look up the precise file for `<name>.router`
+        // even when `<name>` collides with another package's basename.
+        const localNameToModuleAlias = new Map();
+        for (const m of runCompiledPatterns(FROM_IMPORT_MODULE_PATTERNS, tree)) {
+            const moduleNode = m.captures.module;
+            const importedNode = m.captures.imported;
+            const aliasNode = m.captures.alias;
+            if (!moduleNode || !importedNode)
+                continue;
+            // Skip the `router` shape — already handled by FROM_IMPORT_ROUTER_PATTERNS
+            // above and stored under its router-aware semantics.
+            if (importedNode.text === 'router')
+                continue;
+            const moduleLong = lastTwoSegmentsAsLongKey(`${moduleNode.text}.${importedNode.text}`);
+            if (!moduleLong)
+                continue;
+            const localName = aliasNode?.text ?? importedNode.text;
+            localNameToModuleAlias.set(localName, moduleLong);
+        }
+        // Shape A: `<host>.include_router(<module>.router, prefix='/x')`.
+        // The call site gives us only a short module name. We promote to a
+        // long key when the same file imports `<module>` via either
+        // `from <pkg> import <module>` (recorded in `localNameToModuleAlias`
+        // — the typical pattern) or, less commonly, a router-aware import
+        // statement. Only fall back to the basename short key when neither
+        // alias is available.
+        for (const m of runCompiledPatterns(INCLUDE_ROUTER_ATTR_PATTERNS, tree)) {
+            const modNode = m.captures.router_module;
+            const prefixNode = m.captures.prefix;
+            if (!modNode || !prefixNode)
+                continue;
+            const prefix = unquoteLiteral(prefixNode.text);
+            if (prefix === null)
+                continue;
+            const moduleShort = modNode.text;
+            const aliasLong = localNameToModuleAlias.get(moduleShort);
+            const sameFileImport = localNameToModule.get(moduleShort);
+            const longKey = aliasLong ?? sameFileImport?.moduleLong;
+            if (longKey) {
+                recordPrefix(prefixesByLongKey, longKey, prefix);
+            }
+            else {
+                recordPrefix(prefixesByShortKey, moduleShort, prefix);
+            }
+        }
+        // Shape B: `<host>.include_router(my_router, prefix='/x')` — resolve
+        // `my_router` via the import map built above. Whenever the import
+        // statement supplied a multi-segment module path the long key is
+        // recorded, eliminating cross-package collisions.
+        for (const m of runCompiledPatterns(INCLUDE_ROUTER_NAME_PATTERNS, tree)) {
+            const nameNode = m.captures.router_name;
+            const prefixNode = m.captures.prefix;
+            if (!nameNode || !prefixNode)
+                continue;
+            const localImp = localNameToModule.get(nameNode.text);
+            if (!localImp)
+                continue;
+            const prefix = unquoteLiteral(prefixNode.text);
+            if (prefix === null)
+                continue;
+            if (localImp.moduleLong) {
+                recordPrefix(prefixesByLongKey, localImp.moduleLong, prefix);
+            }
+            else {
+                recordPrefix(prefixesByShortKey, localImp.moduleShort, prefix);
+            }
+        }
+    }
+    return { prefixesByLongKey, prefixesByShortKey };
+}
+function joinPrefix(prefix, route) {
+    // Mirror FastAPI's path joining: trim trailing slash off prefix,
+    // ensure exactly one leading slash on the result.
+    const p = prefix.replace(/\/+$/, '');
+    const r = route.startsWith('/') ? route : `/${route}`;
+    return `${p}${r}`;
+}
 export const PYTHON_HTTP_PLUGIN = {
     name: 'python-http',
     language: Python,
-    scan(tree) {
+    prepareRepo({ files, parser, readFile, parseSource }) {
+        return buildPythonRepoContext(files, parser, readFile, parseSource);
+    },
+    scan(tree, repoContext, fileRel) {
         const out = [];
         const httpxAsyncClients = collectHttpxAsyncClients(tree);
-        // Providers: FastAPI
-        for (const match of runCompiledPatterns(FASTAPI_PATTERNS, tree)) {
+        const ctx = repoContext;
+        // Providers: FastAPI @app.<verb>("/path") — already absolute path.
+        for (const match of runCompiledPatterns(FASTAPI_APP_PATTERNS, tree)) {
             const methodNode = match.captures.method;
             const pathNode = match.captures.path;
             if (!methodNode || !pathNode)
@@ -432,6 +732,45 @@ export const PYTHON_HTTP_PLUGIN = {
                 confidence: 0.8,
             });
         }
+        // Providers: FastAPI @router.<verb>("/path") — must be joined
+        // with the prefix(es) declared at the include_router site. When
+        // no prefix is found we still emit the unprefixed path so this
+        // change is strictly additive vs. the prior @app-only behaviour;
+        // when the same router is mounted under multiple prefixes we emit
+        // one detection per prefix.
+        for (const match of runCompiledPatterns(FASTAPI_ROUTER_PATTERNS, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const httpMethod = FASTAPI_VERBS[methodNode.text];
+            if (!httpMethod)
+                continue;
+            const rawPath = unquoteLiteral(pathNode.text);
+            if (rawPath === null)
+                continue;
+            // Long key first (precise, package-aware), short key as fallback.
+            // Mirrors the ingestion-side resolution in parse-impl.ts so the
+            // graph nodes and group contracts agree on which prefix applies.
+            const longKey = fileRel ? fileLongKey(fileRel) : '';
+            const longPrefixes = longKey ? ctx?.prefixesByLongKey.get(longKey) : undefined;
+            const shortKey = fileRel ? fileShortKey(fileRel) : '';
+            const shortPrefixes = longPrefixes || !shortKey ? undefined : ctx?.prefixesByShortKey.get(shortKey);
+            const prefixSet = longPrefixes ?? shortPrefixes;
+            const paths = prefixSet && prefixSet.size > 0
+                ? [...prefixSet].map((p) => joinPrefix(p, rawPath))
+                : [rawPath];
+            for (const p of paths) {
+                out.push({
+                    role: 'provider',
+                    framework: 'fastapi',
+                    method: httpMethod,
+                    path: p,
+                    name: null,
+                    confidence: 0.8,
+                });
+            }
+        }
         // Consumers: requests.<verb>
         for (const match of runCompiledPatterns(REQUESTS_VERB_PATTERNS, tree)) {
             const methodNode = match.captures.method;

package/dist/core/group/extractors/http-patterns/types.d.ts

@@ -47,15 +47,47 @@ export interface HttpDetection {
  * `LanguagePatterns.language` in `tree-sitter-scanner.ts` — the
  * grammar modules export different shapes.
  */
+/**
+ * Per-repo state a plugin can build during a `prepareRepo` pass before
+ * any per-file `scan` is invoked. The orchestrator threads this opaque
+ * value back into each `scan` call so plugins can resolve cross-file
+ * facts (e.g. FastAPI `app.include_router(prefix=...)` mappings live
+ * in `main.py` but apply to handlers declared in `api/*.py`).
+ *
+ * Plugins that have no cross-file state can omit `prepareRepo` and
+ * receive `undefined`.
+ */
+export type RepoContext = unknown;
 export interface HttpLanguagePlugin {
     /** Human-readable plugin name for diagnostics. */
     name: string;
     /** tree-sitter grammar object (passed to the shared parser). */
     language: unknown;
+    /**
+     * Optional pre-pass: walk the relevant files in the repo and produce
+     * an opaque context that `scan` can use to resolve cross-file facts.
+     * Implementations must not throw — return undefined on any error so
+     * the orchestrator falls back to context-less scanning.
+     */
+    prepareRepo?(args: {
+        repoPath: string;
+        files: string[];
+        parser: Parser;
+        readFile: (rel: string) => string | null;
+        parseSource: (parser: Parser, src: string) => Parser.Tree | null;
+    }): RepoContext | undefined;
     /**
      * Scan a parsed tree and return zero or more HTTP detections. Plugins
      * must not throw — they should swallow per-match errors so a single
      * malformed construct does not abort the whole file.
+     *
+     * `repoContext` is whatever the plugin's `prepareRepo` produced (or
+     * `undefined` if there is no `prepareRepo`).
+     *
+     * `fileRel` is the repo-relative path of the file being scanned;
+     * plugins that resolve cross-file facts (e.g. FastAPI router prefix
+     * joining) need it to key into `repoContext`. Optional so existing
+     * single-file plugins can keep their unary `scan(tree)` shape.
      */
-    scan(tree: Parser.Tree): HttpDetection[];
+    scan(tree: Parser.Tree, repoContext?: RepoContext, fileRel?: string): HttpDetection[];
 }

package/dist/core/group/extractors/http-route-extractor.js

@@ -141,7 +141,35 @@ export class HttpRouteExtractor {
         // both graph-assisted enrichment and source-scan emission.
         const parser = new Parser();
         const cachedDetections = new Map();
-        const getDetections = (rel) => {
+        // Per-plugin cross-file context (e.g. Python's FastAPI router →
+        // include_router(prefix=...) map). Built lazily on first
+        // `getDetections` call for a file the plugin handles, scoped to the
+        // file list returned by `getScannedFiles`. Stored by plugin name so
+        // a repo with multiple languages keeps each plugin's context
+        // independent.
+        const repoContextByPlugin = new Map();
+        const ensureRepoContext = async (plugin) => {
+            if (!plugin || typeof plugin.prepareRepo !== 'function')
+                return undefined;
+            if (repoContextByPlugin.has(plugin.name))
+                return repoContextByPlugin.get(plugin.name);
+            try {
+                const ctx = plugin.prepareRepo({
+                    repoPath,
+                    files: await getScannedFiles(),
+                    parser,
+                    readFile: (rel) => readSafe(repoPath, rel),
+                    parseSource: (p, src) => parseSourceSafe(p, src),
+                });
+                repoContextByPlugin.set(plugin.name, ctx);
+                return ctx;
+            }
+            catch {
+                repoContextByPlugin.set(plugin.name, undefined);
+                return undefined;
+            }
+        };
+        const getDetections = async (rel) => {
             const cached = cachedDetections.get(rel);
             if (cached)
                 return cached;
@@ -150,6 +178,7 @@ export class HttpRouteExtractor {
                 cachedDetections.set(rel, []);
                 return [];
             }
+            const repoContext = await ensureRepoContext(plugin);
             const content = readSafe(repoPath, rel);
             if (!content) {
                 cachedDetections.set(rel, []);
@@ -158,7 +187,7 @@ export class HttpRouteExtractor {
             try {
                 parser.setLanguage(plugin.language);
                 const tree = parseSourceSafe(parser, content);
-                const detections = plugin.scan(tree);
+                const detections = plugin.scan(tree, repoContext, rel);
                 cachedDetections.set(rel, detections);
                 return detections;
             }
@@ -179,9 +208,9 @@ export class HttpRouteExtractor {
         const graphProviders = dbExecutor != null ? await this.extractProvidersGraph(dbExecutor, getDetections) : [];
         // Source scan always runs to capture routes in languages/files not covered
         // by graph edges; the glob and per-file parse results are cached above.
-        const providers = this.mergeGraphAndSourceContracts(graphProviders, this.extractProvidersSourceScan(await getScannedFiles(), getDetections));
+        const providers = this.mergeGraphAndSourceContracts(graphProviders, await this.extractProvidersSourceScan(await getScannedFiles(), getDetections));
         const graphConsumers = dbExecutor != null ? await this.extractConsumersGraph(dbExecutor, getDetections) : [];
-        const consumers = this.mergeGraphAndSourceContracts(graphConsumers, this.extractConsumersSourceScan(await getScannedFiles(), getDetections));
+        const consumers = this.mergeGraphAndSourceContracts(graphConsumers, await this.extractConsumersSourceScan(await getScannedFiles(), getDetections));
         return [...providers, ...consumers];
     }
     async scanFiles(repoPath) {
@@ -219,7 +248,7 @@ export class HttpRouteExtractor {
             // helpers — tree-sitter gives both pieces of information
             // structurally. Always run the lookup: even when method is set by
             // `methodFromRouteReason`, we still need the handler name.
-            const detections = filePath ? getDetections(filePath) : [];
+            const detections = filePath ? await getDetections(filePath) : [];
             const providerDetections = detections.filter((d) => d.role === 'provider');
             let handlerName = null;
             const normalizedRoute = normalizeHttpPath(routePath);
@@ -293,10 +322,10 @@ export class HttpRouteExtractor {
         return out;
     }
     // ─── Source-scan providers ─────────────────────────────────────────
-    extractProvidersSourceScan(files, getDetections) {
+    async extractProvidersSourceScan(files, getDetections) {
         const out = [];
         for (const rel of files) {
-            const detections = getDetections(rel);
+            const detections = await getDetections(rel);
             for (const d of detections) {
                 if (d.role !== 'provider')
                     continue;
@@ -338,7 +367,7 @@ export class HttpRouteExtractor {
             let method = 'GET';
             // Prefer the plugin's detected method if we can find a matching
             // fetch/axios call in the same file.
-            const detections = filePath ? getDetections(filePath) : [];
+            const detections = filePath ? await getDetections(filePath) : [];
             // Symmetric to the provider path: if multiple consumer calls in
             // the same file share the same normalized path (e.g. a GET
             // fetch AND a POST fetch to `/api/orders`), `.find()` silently
@@ -388,10 +417,10 @@ export class HttpRouteExtractor {
         return out;
     }
     // ─── Source-scan consumers ─────────────────────────────────────────
-    extractConsumersSourceScan(files, getDetections) {
+    async extractConsumersSourceScan(files, getDetections) {
         const out = [];
         for (const rel of files) {
-            const detections = getDetections(rel);
+            const detections = await getDetections(rel);
             for (const d of detections) {
                 if (d.role !== 'consumer')
                     continue;

package/dist/core/ingestion/languages/cpp/adl.d.ts

@@ -24,22 +24,18 @@
  * V2 additionally walks class ancestors (via MRO), so base-class enclosing
  * namespaces also contribute associated namespaces.
  *
- * **GitNexus approximation (not strict ISO C++ ADL):** passing a qualified
- * function reference like `utils::worker` contributes `utils` to the associated
- * set, enabling resolution of unqualified calls like `with_callback(utils::worker)`
- * to `utils::with_callback`. Under ISO C++ `[basic.lookup.argdep]`, associated
- * entities for function-type arguments come from the **parameter types and return
- * type** of each function in the overload set — NOT the function's enclosing
- * namespace. For `void worker()`, the standard-compliant associated set is empty.
- * GitNexus instead contributes the enclosing namespace of any Function/Method
- * def whose simple name matches, because it enables the dominant real-world ADL
- * pattern at reasonable precision cost.
- *
- * For qualified refs (e.g. `utils::worker`) the namespace is confirmed via a
- * workspace lookup (only contributed when a Function/Method named `worker` exists
- * in `utils`). For unqualified refs the workspace is searched for any Function
- * def with that simple name. Locally-declared function-pointer variables
- * (e.g. `void (*g)()`) and function parameters are excluded from this path.
+ * 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.
@@ -94,11 +90,8 @@ export interface CppAdlArgInfo {
     /** When set, the arg is a potential free-function reference (not a locally-
      *  declared function-pointer variable or function parameter). Contains the
      *  identifier text as written in source (e.g. `"utils::worker"` or
-     *  `"worker"`). GitNexus approximation: the function's enclosing namespace
-     *  is contributed to the ADL associated set. For qualified refs a workspace
-     *  lookup confirms a Function/Method with that simple name exists in the
-     *  namespace before contributing; for unqualified refs every namespace
-     *  containing a matching Function/Method def is contributed. */
+     *  `"worker"`). Resolution contributes associated namespaces from each
+     *  referenced Function/Method def's parameter and return types. */
     readonly functionRefText?: string;
 }
 /** Record per-call-site argument info. Called once per call site from