/**
 * 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.
 *
 * **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.
 *
 * 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
 *
 * Three module-level maps populated per pipeline invocation, cleared via
 * `clearCppAdlState()` (called from `clearFileLocalNames`):
 *
 *   - `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)
 *
 * 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.
 */
import type { ParsedFile, SymbolDefinition } from '../../../../_shared/index.js';
import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
/**
 * Per-argument shape information collected at capture time. ADL fires for
 * arguments where `simpleClassName !== ''`, including class pointers and
 * references whose declarator chain resolves to a named class type.
 * Free-function reference arguments use `functionRefText`.
 */
export interface CppAdlArgInfo {
    /** Simple class-like type name (last segment of qualified name); empty
     *  for primitives, literals, function pointers, etc. */
    readonly simpleClassName: string;
    /** Template's own simple class-like name (e.g. `vector` for
     *  `std::vector<N::T>`), empty when arg type is not a template spec. */
    readonly templateSimpleClassName: string;
    /** Template's own enclosing namespace (dot-qualified, e.g. `std`), empty
     *  when unavailable / unqualified. */
    readonly templateNamespace: string;
    /** Class-like names extracted from explicit type template arguments,
     *  recursively bounded. */
    readonly templateArgClassNames: readonly string[];
    /** Enclosing namespaces extracted from explicit type template arguments,
     *  recursively bounded. */
    readonly templateArgNamespaces: readonly string[];
    /** 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. */
    readonly functionRefText?: string;
}
/** Record per-call-site argument info. Called once per call site from
 *  `emitCppScopeCaptures`. */
export declare function markCppAdlSiteArgs(filePath: string, line: number, col: number, args: readonly CppAdlArgInfo[]): void;
/** Mark a call site as ADL-suppressed (function child wrapped in
 *  `parenthesized_expression`, e.g. `(f)(s)`). */
export declare function markCppAdlSiteNoAdl(filePath: string, line: number, col: number): void;
/** Clear ADL state. Called from `clearFileLocalNames` so all C++ resolver
 *  per-pipeline state is reset together. */
export declare function clearCppAdlState(): void;
/**
 * 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).
 */
export declare function populateCppAssociatedNamespaces(parsed: ParsedFile): void;
/**
 * 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).
 */
export declare function pickCppAdlCandidates(site: {
    readonly name: string;
    readonly atRange: {
        startLine: number;
        startCol: number;
    };
}, callerParsed: ParsedFile, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[]): readonly SymbolDefinition[] | undefined;
