brokk_bifrost_cpp/graph/

extractor.rs

use crate::call_match::{
    CppArgType, cpp_filter_candidates_by_args_with_parameter_types, cpp_forwarding_call_argument,
    cpp_literal_arg_type, cpp_type_text_pointer_depth, normalize_cpp_type_name,
};
use crate::declarations::{
    CppSentinelRecoveredClass, cpp_active_template_type_parameter, cpp_export_macro_token,
    cpp_sentinel_recovered_scope_for_node, enclosing_cpp_namespace_nodes,
    is_recovered_exported_class_base_type_node, node_text, normalize_cpp_whitespace,
    recovered_macro_return_type_node,
};
use crate::graph::CppGraphSource;
use crate::graph::callable_definitions_share_identity_evidence as cpp_callable_definitions_share_identity_evidence;
use crate::graph::callable_definitions_share_identity_evidence_with_visibility as cpp_callable_definitions_share_identity_evidence_with_visibility;
use crate::graph::hits::{
    enclosing_context, is_member_field_own_declarator, push_declaration_reference_hit,
    push_declared_reference_hit, push_definition_hit, push_hit, push_recovered_definition_hit,
    push_recursive_reference_hit, push_reference_hit_range, push_self_receiver_hit, push_type_hit,
    push_type_hit_range, push_unproven_definition_hit, push_unproven_hit,
    push_unproven_reference_hit_range,
};
use crate::graph::namespace_alias::NamespaceQualifierBinding;
use crate::graph::resolver::*;
use crate::graph::syntax::{
    function_macro_replacement_span, object_macro_replacement_type_references,
    qualified_callable_value, receiver_is_self_like,
};
use crate::graph_support::CppSource;
use brokk_bifrost_core::analyzer::fq_name::segment_interner;
use brokk_bifrost_core::analyzer::prepared_syntax::PreparedSyntaxTree;
use brokk_bifrost_core::analyzer::query_token::QueryToken;
use brokk_bifrost_core::analyzer::semantic_diagnostics::contains_node as node_is_within;
use brokk_bifrost_core::analyzer::tree_walk::{
    ParentIndex, WalkControl, children_iter, first_named_child_of_kind, parent_if_field,
    push_named_children_reversed, root_node, walk_named_tree_preorder,
};
use brokk_bifrost_core::analyzer::usages::common::same_node;
use brokk_bifrost_core::analyzer::usages::inverted_edges::ClassRangeIndex;
use brokk_bifrost_core::analyzer::usages::local_inference::{
    LocalInferenceConfig, LocalInferenceEngine, SymbolResolution,
};
use brokk_bifrost_core::analyzer::usages::model::{UsageHit, UsageHitSurface};
use brokk_bifrost_core::analyzer::{CodeUnit, ProjectFile, Range};
use brokk_bifrost_core::hash::{HashMap, HashSet};
#[cfg(any(test, feature = "test-support"))]
use std::cell::Cell;
use std::cell::RefCell;
use std::collections::BTreeSet;
use std::sync::Arc;
use std::time::Instant;
use tree_sitter::Node;

#[cfg(any(test, feature = "test-support"))]
thread_local! {
    pub static LEXICAL_SCOPE_RECONSTRUCTIONS_FOR_TEST: Cell<usize> = const { Cell::new(0) };
    static TYPE_REFERENCE_CANDIDATE_SCAN_COUNT: Cell<usize> = const { Cell::new(0) };
}

#[cfg(any(test, feature = "test-support"))]
pub fn reset_type_reference_candidate_scan_count_for_test() {
    TYPE_REFERENCE_CANDIDATE_SCAN_COUNT.with(|count| count.set(0));
}

#[cfg(any(test, feature = "test-support"))]
pub fn type_reference_candidate_scan_count_for_test() -> usize {
    TYPE_REFERENCE_CANDIDATE_SCAN_COUNT.with(Cell::get)
}

pub struct ScanState<'a> {
    pub max_usages: usize,
    pub hits: &'a mut BTreeSet<UsageHit>,
    pub unproven_hits: &'a mut BTreeSet<UsageHit>,
    pub raw_match_count: &'a mut usize,
    pub limit_exceeded: &'a mut bool,
}

pub struct ScanCtx<'a> {
    pub analyzer: CppGraphSource<'a>,
    pub visibility: &'a VisibilityIndex<'a>,
    pub file: &'a ProjectFile,
    pub source: &'a str,
    /// The parent of every node in the file being scanned, recorded by one
    /// downward pass when the scan starts. `Node::parent` recovers a parent by
    /// re-descending from the root, so an ancestor climb is quadratic in depth
    /// and the scan climbs from more than a dozen call sites per visited node
    /// (#1927, #3097).
    pub ancestry: ParentIndex<'a>,
    ordinary_type_imports: OrdinaryTypeImportCell,
    recovered_sentinel_classes: &'a [CppSentinelRecoveredClass],
    class_ranges: Option<&'a ClassRangeIndex>,
    pub line_starts: &'a [usize],
    pub spec: &'a TargetSpec,
    pub target_group: &'a HashSet<CodeUnit>,
    pub has_proven_visible_type_target: bool,
    uses_c_semantics: bool,
    type_reference_component_names: HashSet<String>,
    pub target_declaration_ranges: Vec<Range>,
    target_macro_declaration_bytes: Vec<usize>,
    pub bindings: LocalInferenceEngine<CppScanBinding>,
    local_shadows: LocalInferenceEngine<()>,
    using_enum_owners: ScopedUsingEnumOwners,
    semantic_using_enum_owners: SemanticUsingEnumOwners,
    needs_using_enum_member_resolution: bool,
    pub hits: &'a mut BTreeSet<UsageHit>,
    pub unproven_hits: &'a mut BTreeSet<UsageHit>,
    pub raw_match_count: &'a mut usize,
    pub max_usages: usize,
    pub external_hit_count: usize,
    pub limit_exceeded: &'a mut bool,
    pub enclosing_cache: RefCell<HashMap<(usize, usize), EnclosingContext>>,
    pub enclosing_owner_cache: RefCell<HashMap<CodeUnit, Option<CodeUnit>>>,
    lexical_scope_cache: LexicalScopeCache,
    lexical_free_function_cache: RefCell<HashMap<(String, String), bool>>,
    member_owner_cache: RefCell<HashMap<CodeUnit, EnclosingMemberOwnerResolution>>,
    global_field_internal_linkage_cache: RefCell<HashMap<CodeUnit, bool>>,
    receiver_canonical_type_cache: RefCell<HashMap<CodeUnit, Option<CodeUnit>>>,
}

impl ScanCtx<'_> {
    fn recovered_sentinel_scope(&self, node: Node<'_>) -> Option<Vec<String>> {
        cpp_sentinel_recovered_scope_for_node(node, self.source, self.recovered_sentinel_classes)
    }
}

#[derive(Clone, Default)]
pub struct EnclosingContext {
    pub enclosing: Option<CodeUnit>,
    pub owner: Option<CodeUnit>,
}

pub fn prepare_file(
    cpp: &dyn CppSource,
    token: QueryToken<'_>,
    file: &ProjectFile,
) -> Option<Arc<PreparedSyntaxTree>> {
    cpp.prepared_syntax(token, file)
}

#[allow(clippy::too_many_arguments)]
pub fn scan_prepared_file(
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    prepared: &PreparedSyntaxTree,
    recovered_sentinel_classes: &[CppSentinelRecoveredClass],
    class_ranges: Option<&ClassRangeIndex>,
    spec: &TargetSpec,
    target_group: &HashSet<CodeUnit>,
    state: &mut ScanState<'_>,
) {
    if *state.limit_exceeded {
        return;
    }
    let needs_using_enum_member_resolution = spec.enum_owner_kind == EnumOwnerKind::Scoped;
    let has_proven_visible_type_target = spec.kind == TargetKind::Type
        && (target_group.iter().any(|target| {
            same_logical_symbol(target, &spec.target)
                && visibility.is_physically_visible(file, target)
        }) || {
            let candidates = visibility
                .visible_identifier_candidates(file, spec.target.identifier())
                .collect::<Vec<_>>();
            visibility.c_tag_declaration_family_matches_target(
                analyzer,
                file,
                &candidates,
                &spec.target,
            )
        });
    if spec.kind == TargetKind::Type
        && !has_proven_visible_type_target
        && visibility
            .visible_identifier_candidates(file, spec.target.identifier())
            .any(|candidate| {
                candidate != &spec.target
                    && !target_group.contains(candidate)
                    && same_logical_symbol(candidate, &spec.target)
                    && visibility.is_physically_visible(file, candidate)
                    && !visibility.c_tag_declaration_family_matches_target(
                        analyzer,
                        file,
                        std::slice::from_ref(&candidate),
                        &spec.target,
                    )
            })
    {
        return;
    }
    let macro_target_declaration_ranges = if spec.kind == TargetKind::Macro {
        analyzer.ranges(&spec.target)
    } else {
        Vec::new()
    };
    let target_declaration_ranges = if spec.kind == TargetKind::Type {
        target_group
            .iter()
            .filter(|target| target.source() == file && same_logical_symbol(target, &spec.target))
            .flat_map(|target| analyzer.ranges(target))
            .collect()
    } else if spec.target.source() == file {
        if spec.kind == TargetKind::Macro {
            macro_target_declaration_ranges.clone()
        } else {
            analyzer.ranges(&spec.target)
        }
    } else {
        Vec::new()
    };
    let target_macro_declaration_bytes = if spec.kind == TargetKind::Macro {
        visibility.macro_declaration_bytes(&spec.target, &macro_target_declaration_ranges)
    } else {
        Vec::new()
    };
    let type_reference_component_names = if spec.kind == TargetKind::Type {
        visibility.visible_type_reference_component_names_for_target(analyzer, file, &spec.target)
    } else {
        HashSet::default()
    };
    if spec.kind == TargetKind::Type
        && !file_may_reference_type_target(
            prepared.tree().root_node(),
            prepared.source(),
            analyzer,
            visibility,
            file,
            &spec.target,
            &type_reference_component_names,
        )
    {
        return;
    }
    let ordinary_type_imports = initialized_ordinary_type_imports(
        prepared.tree().root_node(),
        analyzer,
        visibility,
        file,
        prepared.source(),
    );
    let external_hit_count = state
        .hits
        .iter()
        .filter(|hit| hit.kind.included_in(UsageHitSurface::ExternalUsages))
        .count();
    let mut ctx = ScanCtx {
        analyzer: *analyzer,
        visibility,
        file,
        source: prepared.source(),
        ancestry: ParentIndex::new(prepared.tree().root_node()),
        ordinary_type_imports,
        recovered_sentinel_classes,
        class_ranges,
        line_starts: prepared.line_starts(),
        spec,
        target_group,
        has_proven_visible_type_target,
        uses_c_semantics: analyzer.reference_uses_c_semantics(file),
        type_reference_component_names,
        target_declaration_ranges,
        target_macro_declaration_bytes,
        bindings: LocalInferenceEngine::new(LocalInferenceConfig::default()),
        local_shadows: LocalInferenceEngine::new(LocalInferenceConfig::default()),
        using_enum_owners: ScopedUsingEnumOwners::new(),
        semantic_using_enum_owners: SemanticUsingEnumOwners::new(),
        needs_using_enum_member_resolution,
        hits: state.hits,
        unproven_hits: state.unproven_hits,
        raw_match_count: state.raw_match_count,
        max_usages: state.max_usages,
        external_hit_count,
        limit_exceeded: state.limit_exceeded,
        enclosing_cache: RefCell::new(HashMap::default()),
        enclosing_owner_cache: RefCell::new(HashMap::default()),
        lexical_scope_cache: LexicalScopeCache::new(visibility, file),
        lexical_free_function_cache: RefCell::new(HashMap::default()),
        member_owner_cache: RefCell::new(HashMap::default()),
        global_field_internal_linkage_cache: RefCell::new(HashMap::default()),
        receiver_canonical_type_cache: RefCell::new(HashMap::default()),
    };
    if needs_using_enum_member_resolution {
        collect_semantic_using_enums(prepared.tree().root_node(), &mut ctx);
    }
    if spec.kind == TargetKind::Macro {
        scan_macro_nodes(prepared.tree().root_node(), &mut ctx);
        return;
    }
    scan_node(prepared.tree().root_node(), &mut ctx);
}

/// Scan a macro target without maintaining the declaration and lexical state
/// required by ordinary C and C++ symbols. Macro activation comes entirely
/// from [`VisibilityIndex`], so rebuilding unrelated binding state at every
/// node makes generated tables needlessly expensive.
fn scan_macro_nodes(root: Node<'_>, ctx: &mut ScanCtx<'_>) {
    walk_named_tree_preorder(root, true, |node| {
        if *ctx.limit_exceeded {
            return WalkControl::Break;
        }
        maybe_record_macro_hit(node, ctx);
        WalkControl::Continue
    });
}

enum UsingEnumDeclarationScope {
    Block,
    Class(CodeUnit),
    Namespace(Vec<String>),
    UnsupportedClass,
}

fn resolved_using_enum_declaration(
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> Option<(CodeUnit, UsingEnumDeclarationScope)> {
    let LexicalTypeResolution::Resolved { unit, .. } = resolve_using_enum_declaration_owner(
        node,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
    ) else {
        return None;
    };
    Some((unit, using_enum_declaration_scope(node, ctx)))
}

fn using_enum_declaration_scope(node: Node<'_>, ctx: &ScanCtx<'_>) -> UsingEnumDeclarationScope {
    let mut current = ctx.ancestry.parent(node);
    while let Some(parent) = current {
        if matches!(
            parent.kind(),
            "compound_statement"
                | "function_definition"
                | "lambda_expression"
                | "for_statement"
                | "while_statement"
                | "if_statement"
        ) {
            return UsingEnumDeclarationScope::Block;
        }
        if matches!(
            parent.kind(),
            "class_specifier" | "struct_specifier" | "union_specifier"
        ) {
            let resolution = enclosing_lexical_scope_components(
                node,
                &ctx.analyzer,
                ctx.visibility,
                ctx.file,
                ctx.source,
            );
            if let LexicalScopeResolution::Resolved(components) = resolution
                && let LexicalTypeResolution::Resolved { unit, .. } =
                    ctx.visibility.resolve_type_components_lexically(
                        &ctx.analyzer,
                        ctx.file,
                        &components,
                        true,
                        &[],
                    )
            {
                return UsingEnumDeclarationScope::Class(unit);
            }
            return UsingEnumDeclarationScope::UnsupportedClass;
        }
        current = ctx.ancestry.parent(parent);
    }
    UsingEnumDeclarationScope::Namespace(enclosing_namespace_components(node, ctx.source))
}

fn collect_semantic_using_enums(root: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let mut stack = vec![root];
    while let Some(node) = stack.pop() {
        if node.kind() == "using_declaration"
            && let Some((unit, scope)) = resolved_using_enum_declaration(node, ctx)
        {
            match scope {
                UsingEnumDeclarationScope::Block => {}
                UsingEnumDeclarationScope::Class(class) => {
                    ctx.semantic_using_enum_owners.import_class(class, unit);
                }
                UsingEnumDeclarationScope::Namespace(namespace) => {
                    ctx.semantic_using_enum_owners.import_namespace(
                        namespace,
                        node.start_byte(),
                        unit,
                    );
                }
                UsingEnumDeclarationScope::UnsupportedClass => {}
            }
        }
        push_named_children_reversed(node, &mut stack);
    }
}

fn scan_node(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    struct Frame<'tree> {
        node: Node<'tree>,
        next_child: Option<Node<'tree>>,
        previous_child: Option<Node<'tree>>,
        entered: bool,
        enters_scope: bool,
        enters_using_enum_scope: bool,
        fractured_function_scope: bool,
    }
    impl<'tree> Frame<'tree> {
        fn new(node: Node<'tree>) -> Self {
            Self {
                node,
                next_child: node.named_child(0),
                previous_child: None,
                entered: false,
                enters_scope: false,
                enters_using_enum_scope: false,
                fractured_function_scope: false,
            }
        }
    }
    if *ctx.limit_exceeded {
        return;
    }
    let mut stack = vec![Frame::new(node)];
    while let Some(current) = stack.last_mut() {
        let node = current.node;
        let translation_unit = node.kind() == "translation_unit";
        if !current.entered {
            current.entered = true;
            current.enters_scope = matches!(
                node.kind(),
                "compound_statement"
                    | "function_definition"
                    | "lambda_expression"
                    | "for_statement"
                    | "for_range_loop"
                    | "while_statement"
                    | "if_statement"
            );
            current.enters_using_enum_scope = ctx.needs_using_enum_member_resolution
                && (current.enters_scope
                    || matches!(
                        node.kind(),
                        "namespace_definition"
                            | "class_specifier"
                            | "struct_specifier"
                            | "union_specifier"
                    ));
            if current.enters_scope {
                ctx.bindings.enter_scope();
                ctx.local_shadows.enter_scope();
            }
            if current.enters_using_enum_scope {
                ctx.using_enum_owners.enter_scope();
            }
            seed_declarations(node, ctx);
            maybe_record_hit(node, ctx);
        }
        if let Some(child) = current.previous_child.take()
            && !*ctx.limit_exceeded
            && translation_unit
            && macro_fractured_function(child)
            && macro_fracture_boundary(child).is_some()
        {
            if current.fractured_function_scope {
                ctx.bindings.exit_scope();
                ctx.local_shadows.exit_scope();
            }
            ctx.bindings.enter_scope();
            ctx.local_shadows.enter_scope();
            seed_fractured_function_prefix(child, ctx);
            current.fractured_function_scope = true;
        }
        // Unwind every entered scope once the hit limit has been reached.
        if !*ctx.limit_exceeded
            && let Some(child) = current.next_child.take()
        {
            current.next_child = child.next_named_sibling();
            if translation_unit && current.fractured_function_scope && child.kind() == "ERROR" {
                ctx.bindings.exit_scope();
                ctx.local_shadows.exit_scope();
                current.fractured_function_scope = false;
            }
            current.previous_child = Some(child);
            stack.push(Frame::new(child));
            continue;
        }
        if current.fractured_function_scope {
            ctx.bindings.exit_scope();
            ctx.local_shadows.exit_scope();
        }
        if current.enters_scope {
            ctx.bindings.exit_scope();
            ctx.local_shadows.exit_scope();
        }
        if current.enters_using_enum_scope {
            ctx.using_enum_owners.exit_scope();
        }
        stack.pop();
    }
}

fn macro_fractured_function(node: Node<'_>) -> bool {
    if node.kind() != "function_definition" {
        return false;
    }
    let Some(body) = node.child_by_field_name("body") else {
        return false;
    };
    let mut stack = vec![body];
    while let Some(current) = stack.pop() {
        if matches!(current.kind(), "preproc_def" | "preproc_function_def") {
            return true;
        }
        let mut cursor = current.walk();
        stack.extend(current.named_children(&mut cursor));
    }
    false
}

/// Return the recovery boundary following a fractured macro-generated callable.
pub fn macro_fracture_boundary(node: Node<'_>) -> Option<usize> {
    let first_orphan = node.next_named_sibling()?;
    if !matches!(
        first_orphan.kind(),
        "expression_statement"
            | "compound_statement"
            | "preproc_if"
            | "preproc_ifdef"
            | "if_statement"
            | "for_statement"
            | "while_statement"
            | "do_statement"
            | "return_statement"
    ) {
        return None;
    }
    let mut sibling = Some(first_orphan);
    while let Some(current) = sibling {
        if current.kind() == "ERROR" {
            return Some(current.end_byte());
        }
        if matches!(
            current.kind(),
            "function_definition" | "declaration" | "type_definition"
        ) {
            return None;
        }
        sibling = current.next_named_sibling();
    }
    None
}

fn seed_fractured_function_prefix(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let cutoff = node.end_byte().saturating_sub(1);
    seed_fractured_active_path(node, cutoff, ctx);
}

fn seed_fractured_active_path(node: Node<'_>, cutoff: usize, ctx: &mut ScanCtx<'_>) {
    let mut stack = vec![node];
    while let Some(node) = stack.pop() {
        if node.start_byte() >= cutoff {
            continue;
        }
        let enters_scope = matches!(
            node.kind(),
            "compound_statement"
                | "function_definition"
                | "lambda_expression"
                | "for_range_loop"
                | "for_statement"
                | "while_statement"
                | "if_statement"
                | "class_specifier"
                | "struct_specifier"
                | "union_specifier"
        );
        if enters_scope && !(node.start_byte() <= cutoff && cutoff < node.end_byte()) {
            continue;
        }
        seed_declarations(node, ctx);
        push_named_children_reversed(node, &mut stack);
    }
}

fn seed_declarations(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if crate::declarations::is_direct_recovered_exported_class_field_declaration(node, ctx.source)
        || (ctx.spec.kind != TargetKind::Type
            && indexed_recovered_class_field_declaration(node, ctx))
    {
        return;
    }
    match node.kind() {
        "parameter_declaration" | "optional_parameter_declaration" => seed_typed_binding(node, ctx),
        "declaration" | "field_declaration" => seed_variable_declaration(node, ctx),
        "for_range_loop" => seed_range_binding(node, ctx),
        "expression_statement" | "macro_type_specifier" => {
            seed_function_macro_local_binding(node, ctx)
        }
        "assignment_expression" => seed_function_macro_container_binding(node, ctx),
        "using_declaration" => seed_using_enum(node, ctx),
        _ => {}
    }
}

fn seed_function_macro_local_binding(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let Some(binding) = ctx
        .visibility
        .function_macro_local_binding(ctx.file, node, ctx.source)
    else {
        return;
    };
    if ctx.spec.kind == TargetKind::Type {
        ctx.bindings.declare_shadow(binding.name);
        return;
    }
    let normalized = normalize_cpp_type_name(&binding.type_name);
    let unit = binding
        .type_node
        .and_then(|type_node| {
            ctx.visibility
                .resolve_type_node_result(ctx.file, type_node, ctx.source)
                .ok()
                .flatten()
        })
        .or_else(|| {
            ctx.visibility
                .canonical_type_for_reference(ctx.file, &normalized)
        })
        .or_else(|| ctx.visibility.resolve_type(ctx.file, &normalized));
    ctx.bindings.seed_symbol(
        binding.name,
        CppScanBinding::from_type_name(
            normalized,
            unit,
            binding.pointer_depth + cpp_type_text_pointer_depth(&binding.type_name),
        ),
    );
}

fn seed_function_macro_container_binding(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let Some(binding) =
        ctx.visibility
            .function_macro_container_binding(&ctx.analyzer, ctx.file, node, ctx.source)
    else {
        return;
    };
    let normalized = normalize_cpp_type_name(&binding.type_name);
    let unit = binding.proven_unit.clone().or_else(|| {
        binding
            .type_node
            .and_then(|type_node| {
                ctx.visibility
                    .resolve_type_node_result(ctx.file, type_node, ctx.source)
                    .ok()
                    .flatten()
            })
            .or_else(|| ctx.visibility.resolve_type(ctx.file, &normalized))
    });
    if let Some(unit) = unit {
        ctx.bindings.seed_symbol(
            binding.name,
            CppScanBinding::from_type_name(normalized, Some(unit), binding.pointer_depth),
        );
    }
}

fn indexed_recovered_class_field_declaration(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    if node.kind() != "declaration"
        || !has_function_scope_ancestor(node)
        || has_ancestor_kind(node, "lambda_expression")
        || !(has_recovered_class_shape_ancestor(node)
            || has_malformed_wrapper_function_definition_ancestor(node))
    {
        return false;
    }
    let context = enclosing_context(node, ctx);
    context.enclosing.as_ref().is_some_and(CodeUnit::is_field)
        && context.owner.as_ref().is_some_and(CodeUnit::is_class)
}

fn seed_using_enum(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if !ctx.needs_using_enum_member_resolution {
        return;
    }
    if let Some((unit, UsingEnumDeclarationScope::Block)) =
        resolved_using_enum_declaration(node, ctx)
    {
        ctx.using_enum_owners.import(unit);
    }
}

fn seed_variable_declaration(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    // Class and local-struct fields are resolved from their enclosing owner
    // when they appear as an unqualified receiver. Seeding them into the
    // function-wide binding scope would make same-spelled fields from sibling
    // owners overwrite one another before the owner-aware path runs.
    if node.kind() == "field_declaration" {
        return;
    }
    let type_node = node
        .child_by_field_name("type")
        .or_else(|| first_type_child(node));
    let type_text = type_node.map(|node| node_text(node, ctx.source).to_string());
    let mut cursor = node.walk();
    for child in node.named_children(&mut cursor) {
        let declarator = declaration_declarator(node, child);
        let Some(declarator) = declarator else {
            continue;
        };
        let Some(name) = extract_variable_name(declarator, ctx.source) else {
            continue;
        };
        if declarator.kind() == "function_declarator"
            && !constructor_style_local_declaration(
                ctx.visibility,
                ctx.file,
                ctx.source,
                declarator,
                type_text.as_deref(),
                &ctx.bindings,
            )
        {
            if node.kind() == "declaration" && has_function_scope_ancestor(node) {
                ctx.local_shadows.declare_shadow(name);
            }
            continue;
        }
        if node.kind() == "declaration" && has_function_scope_ancestor(node) {
            ctx.local_shadows.declare_shadow(name.clone());
        }
        if ctx.spec.kind == TargetKind::Type {
            ctx.bindings.declare_shadow(name);
            continue;
        }
        let value = child.child_by_field_name("value");
        seed_binding_from_type_or_value(&name, type_node, value, ctx);
    }
}

fn seed_typed_binding(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if !parameter_belongs_to_callable_scope(node) {
        return;
    }
    let Some((name, _, type_node)) = cpp_binding_parts(node, ctx.source) else {
        return;
    };
    if has_function_scope_ancestor(node) {
        ctx.local_shadows.declare_shadow(name.clone());
    }
    if ctx.spec.kind == TargetKind::Type {
        ctx.bindings.declare_shadow(name);
        return;
    }
    seed_binding_from_type_or_value(&name, type_node, None, ctx);
}

fn seed_range_binding(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let Some((name, _, type_node)) = cpp_binding_parts(node, ctx.source) else {
        return;
    };
    if has_function_scope_ancestor(node) {
        ctx.local_shadows.declare_shadow(name.clone());
    }
    if ctx.spec.kind == TargetKind::Type {
        ctx.bindings.declare_shadow(name);
        return;
    }
    seed_binding_from_type_or_value(&name, type_node, None, ctx);
}

fn has_function_scope_ancestor(node: Node<'_>) -> bool {
    let mut current = node.parent();
    while let Some(parent) = current {
        // Error recovery can wrap a complete namespace in a bogus outer
        // `function_definition` (for example when an object-like namespace
        // macro is parsed as a return type).  Declarations below that
        // namespace are still namespace-scoped: do not let the malformed
        // callable envelope seed them as local shadows.  A real function
        // body is encountered before its enclosing namespace, so this keeps
        // ordinary local binding detection unchanged.
        if parent.kind() == "namespace_definition" {
            return false;
        }
        if parent.kind() == "function_definition" {
            // The malformed sentinel envelope is not a callable scope. Its
            // body may contain a recovered namespace (or, in a smaller error
            // tree, only an ERROR node standing in for that namespace), so
            // declarations directly below it must remain namespace-scoped.
            // Real nested functions are encountered first and still seed
            // ordinary local bindings.
            return !is_malformed_wrapper_function_definition(parent);
        }
        if parent.kind() == "lambda_expression" {
            return true;
        }
        current = parent.parent();
    }
    false
}

fn seed_binding_from_type_or_value(
    name: &str,
    type_node: Option<Node<'_>>,
    value: Option<Node<'_>>,
    ctx: &mut ScanCtx<'_>,
) {
    if name.is_empty() {
        return;
    }
    let resolved = type_node
        .filter(|node| normalize_type_text(node_text(*node, ctx.source)) != "auto")
        .map(|node| {
            let text = node_text(node, ctx.source);
            let name = normalize_cpp_type_name(text);
            if let Some(unit) = anonymous_aggregate_owner(&ctx.analyzer, ctx.file, node) {
                return CppScanBinding::from_type_name(
                    name,
                    Some(unit),
                    cpp_type_text_pointer_depth(text),
                );
            }
            // Bare type names need lexical ownership before the coarse visible-name
            // fallback (two namespaces can each declare `CopyResult`). Template
            // references keep the specialization-aware resolver first because a
            // component-only lexical lookup cannot rank partial specializations.
            let lexical_scope = ctx.recovered_sentinel_scope(node).or_else(|| {
                if cpp_template_reference_arguments(node, ctx.source).is_some() {
                    return None;
                }
                match enclosing_lexical_scope_components(
                    node,
                    &ctx.analyzer,
                    ctx.visibility,
                    ctx.file,
                    ctx.source,
                ) {
                    LexicalScopeResolution::Resolved(scope) => Some(scope),
                    LexicalScopeResolution::Ambiguous | LexicalScopeResolution::Missing => None,
                }
            });
            let unit = lexical_scope
                .as_deref()
                .and_then(|scope| resolve_seed_type_node_lexically(node, ctx, scope))
                .or_else(|| {
                    match ctx
                        .visibility
                        .resolve_type_node_result(ctx.file, node, ctx.source)
                    {
                        Ok(Some(unit)) => Some(unit),
                        Ok(None) => ctx
                            .visibility
                            .canonical_type_for_reference(ctx.file, &name)
                            .or_else(|| ctx.visibility.resolve_type(ctx.file, &name)),
                        Err(_) => None,
                    }
                });
            CppScanBinding::from_type_name(name.clone(), unit, cpp_type_text_pointer_depth(text))
        })
        .or_else(|| value.and_then(|value| infer_type_from_value(value, ctx)));

    if let Some(resolved) = resolved {
        ctx.bindings.seed_symbol(name.to_string(), resolved);
    } else if let Some(value) = value
        && value.kind() == "identifier"
    {
        ctx.bindings
            .alias_symbol(name.to_string(), node_text(value, ctx.source));
    } else {
        ctx.bindings.declare_shadow(name.to_string());
    }
}

fn resolve_seed_type_node_lexically(
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
    scope: &[String],
) -> Option<CodeUnit> {
    let (components, global) = type_reference_components(node, ctx.source)?;
    let resolution = match scan_owner_type(ctx) {
        Some(target) => ctx.visibility.resolve_type_components_lexically_for_target(
            &ctx.analyzer,
            ctx.file,
            &components,
            global,
            scope,
            target,
        ),
        None => ctx.visibility.resolve_type_components_lexically(
            &ctx.analyzer,
            ctx.file,
            &components,
            global,
            scope,
        ),
    };
    match resolution {
        LexicalTypeResolution::Resolved { unit, .. } => Some(unit),
        LexicalTypeResolution::Ambiguous | LexicalTypeResolution::Missing => None,
    }
}

/// The type this scan is asking about: the owner of a member target, or the
/// target itself when it is a type.
///
/// C headers routinely declare one typedef name once per branch of an
/// `#if`/`#else` pair, for example tinycthread's `mtx_t` as a Win32 struct and
/// as `pthread_mutex_t` (#2996). The branches cannot both be compiled, so they
/// are alternate spellings of one name rather than competing declarations, and
/// canonicalizing without the scan's own type identity picks between them by
/// declaration order. That ordering can bind a receiver to the branch that does
/// not declare the queried member, which drops every reference in the branch
/// that does. Naming the identity keeps the target-preserving rule the forward
/// resolver already applies (`unique_type_candidate_preserving_target`).
fn scan_owner_type<'a>(ctx: &'a ScanCtx<'_>) -> Option<&'a CodeUnit> {
    // Target-preserving lookup can reconcile logical declarations across files.
    // A receiver must not borrow an owner from a header its caller cannot see.
    ctx.spec
        .owner
        .as_ref()
        .filter(|owner| owner.is_class() && ctx.visibility.is_physically_visible(ctx.file, owner))
}

const MAX_RECEIVER_CALL_RESOLUTION_DEPTH: usize = 32;

fn infer_type_from_value(node: Node<'_>, ctx: &ScanCtx<'_>) -> Option<CppScanBinding> {
    infer_type_from_value_with_budget(node, ctx, MAX_RECEIVER_CALL_RESOLUTION_DEPTH)
}

fn infer_type_from_value_with_budget(
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
    remaining_call_depth: usize,
) -> Option<CppScanBinding> {
    match node.kind() {
        "new_expression" | "call_expression" if remaining_call_depth == 0 => {
            infer_cpp_initializer_binding(
                &ctx.analyzer,
                ctx.visibility,
                ctx.file,
                ctx.source,
                node,
                None,
            )
        }
        "new_expression" | "call_expression" => infer_cpp_initializer_binding(
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            ctx.source,
            node,
            Some(&|receiver, source| {
                receiver_type_units_with_budget(receiver, source, ctx, remaining_call_depth - 1)
            }),
        ),
        "initializer_list" => None,
        "identifier" => {
            let resolved = ctx.bindings.resolve_symbol(node_text(node, ctx.source));
            resolved
                .as_precise()?
                .iter()
                .find(|binding| binding.unit.as_ref().is_some_and(CodeUnit::is_class))
                .cloned()
        }
        _ => {
            let text = node_text(node, ctx.source);
            let name = normalize_cpp_type_name(text);
            ctx.visibility
                .resolve_type(ctx.file, &name)
                .map(|unit| CppScanBinding::from_unit(unit, 0))
        }
    }
}

/// Whether a member named `identifier` can be spelled anywhere in this file's
/// syntax.
///
/// Both member scans below -- [`maybe_record_method_hit`] and
/// [`maybe_record_member_field_hit`] -- begin by comparing the terminal name
/// of a syntax node against the target's member name, so a file whose syntax
/// never spells that name yields neither a proven nor an unproven hit. That
/// makes this an exact admission test rather than an approximation: candidate
/// discovery can drop such a file without narrowing what the query proves.
///
/// Only tree-sitter nodes are read. Two node kinds carry text the C++ grammar
/// does not tokenize into identifiers -- a function-like macro's `preproc_arg`
/// replacement, which
/// [`maybe_record_function_macro_replacement_method_hits`] recovers by its own
/// sentinel parse, and an `ERROR` region -- so those admit on containment
/// instead of on a token match. A `comment` is the one subtree no scan reads,
/// so it is skipped.
///
/// Defined only for a plain identifier: [`name_matches_callable`] widens the
/// comparison for an `operator` name to the `operator` token alone, and a
/// destructor or conversion-function name is not spelled the way it is
/// recorded. [`cpp_member_is_spelled_at_references`] is the admission side of
/// that condition.
pub fn cpp_syntax_may_spell_member(root: Node<'_>, source: &str, identifier: &str) -> bool {
    debug_assert!(
        cpp_member_is_spelled_at_references(identifier),
        "member admission is defined only for a plain identifier: {identifier:?}"
    );
    let mut spelled = false;
    walk_named_tree_preorder(root, true, |node| match node.kind() {
        "comment" => WalkControl::SkipChildren,
        "identifier"
        | "field_identifier"
        | "type_identifier"
        | "namespace_identifier"
        | "statement_identifier" => {
            if node_text(node, source).trim() == identifier {
                spelled = true;
                WalkControl::Break
            } else {
                WalkControl::SkipChildren
            }
        }
        "preproc_arg" | "ERROR" => {
            if node_text(node, source).contains(identifier) {
                spelled = true;
                WalkControl::Break
            } else {
                // The node's own text covers every descendant's bytes, so a
                // miss here is a miss for the whole subtree.
                WalkControl::SkipChildren
            }
        }
        _ => WalkControl::Continue,
    });
    spelled
}

/// Whether every reference to a member named `identifier` must spell it.
///
/// An `operator` name is matched by [`name_matches_callable`] through the bare
/// `operator` token, and a destructor or conversion function is recorded under
/// a name its call sites do not write, so neither admits a spelling test.
pub fn cpp_member_is_spelled_at_references(identifier: &str) -> bool {
    let mut characters = identifier.chars();
    characters
        .next()
        .is_some_and(|first| first.is_ascii_alphabetic() || first == '_')
        && characters.all(|character| character.is_ascii_alphanumeric() || character == '_')
        && !identifier.starts_with("operator")
}

fn maybe_record_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    match ctx.spec.kind {
        TargetKind::Type => maybe_record_type_hit(node, ctx),
        TargetKind::Constructor => maybe_record_constructor_hit(node, ctx),
        TargetKind::FreeFunction => maybe_record_free_function_hit(node, ctx),
        TargetKind::Method => maybe_record_method_hit(node, ctx),
        TargetKind::GlobalField => maybe_record_global_field_hit(node, ctx),
        TargetKind::MemberField => maybe_record_member_field_hit(node, ctx),
        TargetKind::Macro => maybe_record_macro_hit(node, ctx),
    }
}

fn maybe_record_macro_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if node_text(node, ctx.source) != ctx.spec.member_name {
        return;
    }
    if is_ordinary_macro_reference_node(node) {
        if ctx.visibility.macro_binding_matches_target_declaration_at(
            ctx.file,
            &ctx.spec.member_name,
            node.start_byte(),
            ctx.spec.target.source(),
            &ctx.target_macro_declaration_bytes,
        ) {
            *ctx.raw_match_count += 1;
            push_hit(node, ctx);
            return;
        }
        match ctx.visibility.resolve_ordinary_macro_reference(
            &ctx.analyzer,
            ctx.file,
            node,
            ctx.source,
        ) {
            OrdinaryMacroReferenceResolution::Resolved(unit)
                if ctx.target_group.contains(&unit) =>
            {
                *ctx.raw_match_count += 1;
                push_hit(node, ctx);
            }
            OrdinaryMacroReferenceResolution::Ambiguous
                if ctx
                    .visibility
                    .macro_target_is_visible_candidate(ctx.file, &ctx.spec.target) =>
            {
                *ctx.raw_match_count += 1;
                push_unproven_hit(node, ctx);
            }
            OrdinaryMacroReferenceResolution::Resolved(_)
            | OrdinaryMacroReferenceResolution::Ambiguous
            | OrdinaryMacroReferenceResolution::Missing => {}
        }
        return;
    }
    if !matches!(
        node.kind(),
        "identifier"
            | "field_identifier"
            | "type_identifier"
            | "namespace_identifier"
            | "preproc_arg"
    ) || ctx.ancestry.parent(node).is_some_and(|parent| {
        matches!(parent.kind(), "preproc_def" | "preproc_function_def")
            && parent
                .child_by_field_name("name")
                .is_some_and(|name| same_node(name, node))
    }) {
        return;
    }
    if ctx.visibility.macro_binding_matches_target_declaration_at(
        ctx.file,
        &ctx.spec.member_name,
        node.start_byte(),
        ctx.spec.target.source(),
        &ctx.target_macro_declaration_bytes,
    ) {
        *ctx.raw_match_count += 1;
        push_hit(node, ctx);
    } else if ctx.visibility.macro_name_may_be_bound_at(
        ctx.file,
        &ctx.spec.member_name,
        node.start_byte(),
    ) && ctx
        .visibility
        .macro_target_is_visible_candidate(ctx.file, &ctx.spec.target)
    {
        *ctx.raw_match_count += 1;
        push_unproven_hit(node, ctx);
    }
}

fn maybe_record_type_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let kind = node.kind();
    if ctx.uses_c_semantics
        && recovered_c_new_expression_argument_at(node, node.start_byte(), node.end_byte(), true)
            .is_some()
    {
        return;
    }
    if kind == "preproc_arg" {
        maybe_record_object_macro_replacement_type_hits(node, ctx);
        return;
    }
    if let Some(type_node) = ctx
        .visibility
        .function_macro_type_argument(ctx.file, node, ctx.source)
    {
        if ctx
            .local_shadows
            .is_shadowed(node_text(type_node, ctx.source))
        {
            return;
        }
        if let LexicalTypeResolution::Resolved {
            unit, candidates, ..
        } = resolve_type_node_lexically_for_target(
            type_node,
            &ctx.analyzer,
            ctx.visibility,
            &ctx.ordinary_type_imports,
            ctx.file,
            ctx.source,
            &ctx.spec.target,
            Some(&ctx.lexical_scope_cache),
            ctx.recovered_sentinel_scope(type_node).as_deref(),
        ) && type_resolution_matches_target(type_node, &unit, &candidates, ctx)
        {
            *ctx.raw_match_count += 1;
            push_type_hit(type_node, ctx);
        }
        return;
    }
    let recovered_exported_class_base =
        matches!(
            kind,
            "qualified_identifier" | "scoped_type_identifier" | "template_type"
        ) && is_recovered_exported_class_base_type_node(node, ctx.source);
    if kind == "field_declaration"
        && let Some(return_type) = recovered_macro_return_type_node(node, ctx.source)
    {
        maybe_record_recovered_macro_return_type_hit(return_type, ctx);
        return;
    }
    if kind == "qualified_identifier"
        && let Some((owner, _member_pointer)) = member_pointer_owner_components(node, ctx.source)
    {
        // A member-pointer owner can itself end in a nested alias, as in
        // `type_identity<T>::type::*`. Resolving the complete owner
        // canonicalizes that alias to its underlying type and loses the alias
        // declaration that inverse lookup is targeting. Retain every
        // structurally proven qualifier component before asking for the
        // canonical owner type.
        if ctx
            .analyzer
            .type_alias_provider()
            .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target))
            && canonical_cpp_scope_components(&ctx.spec.target) == owner.names
            && let Some(terminal) = owner.nodes.last().copied()
        {
            if !member_pointer_alias_owner_prefix_matches(node, &owner, ctx) {
                return;
            }
            if ctx.visibility.external_type_candidate_visible_in_context(
                &ctx.analyzer,
                ctx.file,
                &ctx.spec.target,
                terminal,
            ) || ctx
                .visibility
                .dependent_member_pointer_alias_visible_in_context(
                    &ctx.analyzer,
                    ctx.file,
                    &ctx.spec.target,
                    &owner.names,
                    terminal,
                )
            {
                *ctx.raw_match_count += 1;
                push_type_hit(terminal, ctx);
            } else if ctx
                .visibility
                .is_physically_visible(ctx.file, &ctx.spec.target)
                && ctx.visibility.declaration_guards_compatible_at_reference(
                    &ctx.analyzer,
                    ctx.file,
                    &ctx.spec.target,
                    terminal,
                )
            {
                // The structured owner and terminal identify a candidate, but
                // do not establish its conditional availability.
                *ctx.raw_match_count += 1;
                push_unproven_hit(terminal, ctx);
            }
            return;
        }
        if let Some(scopes) = static_qualifier_type_scopes_for_components(node, owner, ctx) {
            *ctx.raw_match_count += 1;
            for scope in scopes {
                push_type_hit(scope, ctx);
            }
            return;
        }
        return;
    }
    if kind == "pointer_expression"
        && let Some(value) = qualified_callable_value(node)
        && let Some(owner_hit) = target_guided_qualified_value_owner_hit(value.qualified, ctx)
    {
        *ctx.raw_match_count += 1;
        match owner_hit {
            TargetGuidedQualifiedValueOwnerHit::Proven(scope) => push_type_hit(scope, ctx),
            TargetGuidedQualifiedValueOwnerHit::Unproven(scope) => push_unproven_hit(scope, ctx),
        }
        return;
    }
    if kind == "call_expression" {
        maybe_record_direct_temporary_type_hit(node, ctx);
        return;
    }
    if !matches!(
        kind,
        "identifier"
            | "namespace_identifier"
            | "qualified_identifier"
            | "scoped_identifier"
            | "scoped_type_identifier"
            | "template_function"
            | "template_type"
            | "type_descriptor"
            | "type_identifier"
            | "using_declaration"
    ) {
        return;
    }
    let recovered_type = recovered_macro_decorated_declarator_type(node).is_some();
    let template_function_type = cpp_template_function_has_type_owner(node);
    let recovered_qualified_friend =
        is_recovered_qualified_friend_class_type_reference(node, ctx.source);
    if !recovered_type
        && !recovered_qualified_friend
        && !recovered_exported_class_base
        && matches!(
            kind,
            "type_identifier" | "qualified_identifier" | "scoped_type_identifier" | "template_type"
        )
        && !type_reference_components_may_name_target(node, ctx)
    {
        return;
    }
    if ctx.ancestry.parent(node).is_some_and(|parent| {
        parent.kind() == "operator_cast"
            && parent
                .child_by_field_name("type")
                .is_some_and(|target| same_node(target, node))
    }) {
        return;
    }
    if let Some(hit) = target_guided_static_cast_alias_type_descriptor(node, ctx) {
        *ctx.raw_match_count += 1;
        push_type_hit(hit, ctx);
        return;
    }
    if matches!(kind, "identifier" | "template_function")
        && parent_if_field(node, "call_expression", "function").is_some()
    {
        return;
    }
    if kind == "using_declaration" {
        let (resolution, type_node) =
            if let Some(type_node) = using_enum_declaration_type_node(node) {
                (
                    resolve_using_enum_declaration_owner(
                        node,
                        &ctx.analyzer,
                        ctx.visibility,
                        &ctx.ordinary_type_imports,
                        ctx.file,
                        ctx.source,
                    ),
                    type_node,
                )
            } else if let Some(type_node) = ordinary_using_declaration_type_node(node) {
                (
                    resolve_ordinary_using_declaration_owner(
                        node,
                        &ctx.analyzer,
                        ctx.visibility,
                        ctx.file,
                        ctx.source,
                    ),
                    type_node,
                )
            } else {
                return;
            };
        if let LexicalTypeResolution::Resolved { unit, .. } = resolution
            && same_visible_symbol(&unit, &ctx.spec.target)
        {
            *ctx.raw_match_count += 1;
            push_type_hit(type_node, ctx);
        }
        return;
    }
    if ctx.uses_c_semantics && is_c_sizeof_expression_type_candidate(ctx.file, node) {
        if ctx.local_shadows.is_shadowed(node_text(node, ctx.source))
            || local_type_name_shadows(node, ctx)
        {
            return;
        }
        if let LexicalTypeResolution::Resolved {
            unit, candidates, ..
        } = resolve_type_node_lexically_for_target(
            node,
            &ctx.analyzer,
            ctx.visibility,
            &ctx.ordinary_type_imports,
            ctx.file,
            ctx.source,
            &ctx.spec.target,
            Some(&ctx.lexical_scope_cache),
            ctx.recovered_sentinel_scope(node).as_deref(),
        ) && type_resolution_matches_target(node, &unit, &candidates, ctx)
        {
            *ctx.raw_match_count += 1;
            push_type_hit(node, ctx);
        }
        return;
    }
    if let Some((type_node, _)) = recovered_macro_decorated_type_node(node) {
        // A missing `::` can put either the macro or the real type in the
        // recovered scope. Resolve both candidates against this inverse
        // target before choosing one: a unique match is routed through the
        // ordinary target-guided path, while two distinct matches are
        // ambiguous and must not invent a hit. With no target match, retain
        // the existing recovered-scope path below for its conservative
        // fallback behaviour.
        let mut matching = Vec::new();
        for candidate in [node, type_node] {
            if matching
                .iter()
                .any(|existing| same_node(*existing, candidate))
            {
                continue;
            }
            if let LexicalTypeResolution::Resolved {
                unit, candidates, ..
            } = resolve_type_node_lexically_for_target(
                candidate,
                &ctx.analyzer,
                ctx.visibility,
                &ctx.ordinary_type_imports,
                ctx.file,
                ctx.source,
                &ctx.spec.target,
                Some(&ctx.lexical_scope_cache),
                ctx.recovered_sentinel_scope(candidate).as_deref(),
            ) && type_resolution_matches_target(candidate, &unit, &candidates, ctx)
            {
                matching.push(candidate);
            }
        }
        match matching.as_slice() {
            [candidate] if !same_node(*candidate, node) => {
                maybe_record_type_hit(*candidate, ctx);
                return;
            }
            [candidate] if same_node(*candidate, node) => {}
            [] => {}
            _ => return,
        }
    }
    if !recovered_type
        && !template_function_type
        && !matches!(
            kind,
            "type_identifier" | "qualified_identifier" | "scoped_type_identifier" | "template_type"
        )
    {
        return;
    }
    if type_reference_components(node, ctx.source).is_some_and(|(components, global)| {
        components.len() == 1
            && !global
            && (local_type_name_shadows(node, ctx)
                || ctx
                    .analyzer
                    .type_alias_provider()
                    .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target))
                    && nearer_type_name_shadows_structured_reference(node, ctx))
    }) {
        return;
    }
    if !recovered_type
        && !recovered_qualified_friend
        && !recovered_exported_class_base
        && ctx.ancestry.parent(node).is_some_and(|parent| {
            parent.kind() == "alias_declaration"
                && parent
                    .child_by_field_name("name")
                    .is_some_and(|name| same_node(name, node))
        })
    {
        return;
    }
    #[cfg(any(test, feature = "test-support"))]
    TYPE_REFERENCE_CANDIDATE_SCAN_COUNT.with(|count| count.set(count.get() + 1));
    if !recovered_type
        && !recovered_qualified_friend
        && !recovered_exported_class_base
        && matches!(kind, "qualified_identifier" | "scoped_identifier")
        && is_declaration_name(node)
        && let Some(owners) = out_of_line_member_definition_owner(
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            ctx.source,
            node,
        )
    {
        *ctx.raw_match_count += 1;
        let mut matched_owner = false;
        for (owner_node, owner) in owners.owners {
            if same_visible_symbol(&owner, &ctx.spec.target) {
                matched_owner = true;
                push_guarded_owner_hit(owner_node, &owner, node, ctx);
            }
        }
        if !matched_owner && let Some(scopes) = target_guided_qualifier_type_scopes(node, ctx) {
            for scope in scopes {
                push_hit(scope, ctx);
            }
        } else if !matched_owner
            && let Some(scope) = target_guided_unproven_out_of_line_owner(node, ctx)
        {
            push_unproven_hit(scope, ctx);
        }
        return;
    }
    if !recovered_type
        && !recovered_qualified_friend
        && matches!(node.kind(), "qualified_identifier" | "scoped_identifier")
        && is_declaration_name(node)
        && let Some(owner) = indexed_out_of_line_template_owner_hit(node, ctx)
    {
        *ctx.raw_match_count += 1;
        push_type_hit(owner, ctx);
        return;
    }
    // A qualified template-id is represented as a qualified_identifier whose
    // name child is the template_type. Resolve the complete qualified
    // reference from that inner template node below; handling the outer node
    // independently would either lose the qualifier or emit a duplicate,
    // wider hit range.
    if ctx.visibility.is_template_specialization(&ctx.spec.target)
        && matches!(
            node.kind(),
            "qualified_identifier" | "scoped_type_identifier"
        )
        && node
            .child_by_field_name("name")
            .is_some_and(|name| name.kind() == "template_type")
    {
        return;
    }
    if let Some(scope) = target_guided_dependent_alias_qualifier_scope(node, ctx) {
        *ctx.raw_match_count += 1;
        push_unproven_hit(scope, ctx);
        return;
    }
    if !recovered_type
        && !is_nested_type_node(node)
        && matches!(
            node.kind(),
            "qualified_identifier" | "scoped_type_identifier"
        )
        && let Some(scopes) = target_guided_qualifier_type_scopes(node, ctx)
    {
        *ctx.raw_match_count += 1;
        for scope in scopes {
            push_type_hit(scope, ctx);
        }
        return;
    }
    if !recovered_type && is_nested_type_node(node) {
        if let Some(hit) = out_of_line_dependent_return_template_owner(node, ctx) {
            *ctx.raw_match_count += 1;
            push_type_hit(hit, ctx);
            return;
        }
        if let Some(hit) = target_guided_nested_type_terminal_hit(node, ctx) {
            *ctx.raw_match_count += 1;
            push_type_hit(hit, ctx);
            return;
        }
        // A concrete template specialization can be absent from the coarse
        // per-file component-name index: that index contains the primary name
        // while this recovered child may expose only the malformed template
        // leaf.  Resolve the complete enclosing template before applying the
        // component prefilter so an exact target candidate can prove this
        // reference.  Non-specialization targets retain the cheap gate.
        let nested_template = if node.kind() == "template_type" {
            Some(node)
        } else {
            ctx.ancestry.parent(node).filter(|parent| {
                parent.kind() == "template_type" && parent.child_by_field_name("name") == Some(node)
            })
        };
        // Concrete specializations need their nested template-id inspected.
        // An ordinary alias application does too when it is itself the scope
        // of a member-qualified type, because the enclosing node denotes the
        // member rather than the alias. In every other primary/alias shape the
        // enclosing structured type owns the hit range; descending would emit
        // a duplicate terminal subrange.
        let nested_alias_qualifier = nested_template.is_some_and(|template| {
            let enclosing_qualified_type_owns_range =
                ctx.ancestry.parent(template).is_some_and(|parent| {
                    matches!(
                        parent.kind(),
                        "qualified_identifier" | "scoped_identifier" | "scoped_type_identifier"
                    ) && parent.child_by_field_name("name") == Some(template)
                });
            let Some(alias_provider) = ctx.analyzer.type_alias_provider() else {
                return false;
            };
            let Some(name) = template_reference_name_node(template) else {
                return false;
            };
            let alias_candidates = ctx
                .visibility
                .visible_identifier_candidates(ctx.file, node_text(name, ctx.source))
                .filter(|candidate| alias_provider.is_type_alias(candidate))
                .cloned()
                .collect::<Vec<_>>();
            let direct_target_alias_visible = !alias_candidates
                .iter()
                .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target))
                || ctx.visibility.external_type_candidate_visible_in_context(
                    &ctx.analyzer,
                    ctx.file,
                    &ctx.spec.target,
                    template,
                );
            !enclosing_qualified_type_owns_range
                && direct_target_alias_visible
                && template_reference_candidates_select_target(
                    template,
                    &alias_candidates,
                    &ctx.analyzer,
                    ctx.visibility,
                    ctx.file,
                    ctx.source,
                    &ctx.spec.target,
                )
        });
        if !ctx.visibility.is_template_specialization(&ctx.spec.target) && !nested_alias_qualifier {
            return;
        }
        if nested_alias_qualifier {
            let template = nested_template.expect("a nested alias qualifier has a template node");
            *ctx.raw_match_count += 1;
            let hit = target_guided_missing_alias_rhs_type_leaf(template, ctx)
                .unwrap_or_else(|| type_reference_hit_node(template));
            push_type_hit(hit, ctx);
            return;
        }
        // For concrete specializations, the visible identifier index can
        // already contain the exact template spelling even when lexical
        // resolution rejects the recovered child (the child itself has no
        // argument list). Select the name as structured evidence;
        // `push_type_hit` expands it to the complete written template-id.
        if ctx.visibility.is_template_specialization(&ctx.spec.target)
            && let Some(template) = nested_template
            && template_type_component_preserves_target(
                template,
                &ctx.visibility
                    .visible_identifier_candidates(ctx.file, node_text(template, ctx.source))
                    .cloned()
                    .collect::<Vec<_>>(),
                ctx,
            )
        {
            *ctx.raw_match_count += 1;
            let hit = template
                .child_by_field_name("name")
                .filter(|name| name.kind() == "type_identifier")
                .unwrap_or(template);
            push_type_hit(hit, ctx);
            return;
        }
        if let Some(template) = nested_template
            && let Some(_resolution) = resolve_nested_template_type_for_target(template, ctx)
        {
            *ctx.raw_match_count += 1;
            let hit =
                target_guided_missing_alias_rhs_type_leaf(template, ctx).unwrap_or_else(|| {
                    if ctx.visibility.is_template_specialization(&ctx.spec.target) {
                        template
                            .child_by_field_name("name")
                            .filter(|name| name.kind() == "type_identifier")
                            .unwrap_or(template)
                    } else {
                        type_reference_hit_node(template)
                    }
                });
            push_type_hit(hit, ctx);
        }
        return;
    }
    if !recovered_type && let Some(call) = parent_if_field(node, "call_expression", "function") {
        let direct_target = resolve_qualified_call_target(
            call,
            node,
            &ctx.analyzer,
            ctx.visibility,
            &ctx.ordinary_type_imports,
            ctx.file,
            ctx.source,
        );
        if matches!(direct_target, BareCallTargetResolution::Type(_))
            && let LexicalTypeResolution::Resolved {
                unit, candidates, ..
            } = resolve_type_node_lexically_for_target(
                node,
                &ctx.analyzer,
                ctx.visibility,
                &ctx.ordinary_type_imports,
                ctx.file,
                ctx.source,
                &ctx.spec.target,
                Some(&ctx.lexical_scope_cache),
                ctx.recovered_sentinel_scope(node).as_deref(),
            )
            && type_resolution_matches_target(node, &unit, &candidates, ctx)
        {
            *ctx.raw_match_count += 1;
            push_resolved_type_hit(node, &candidates, ctx);
        } else if let Some(scopes) = static_qualifier_type_scopes(node, ctx) {
            *ctx.raw_match_count += 1;
            for scope in scopes {
                push_type_hit(scope, ctx);
            }
        } else if let Some(owner_hit) = target_guided_qualified_value_owner_hit(node, ctx) {
            *ctx.raw_match_count += 1;
            match owner_hit {
                TargetGuidedQualifiedValueOwnerHit::Proven(scope) => push_type_hit(scope, ctx),
                TargetGuidedQualifiedValueOwnerHit::Unproven(scope) => {
                    push_unproven_hit(scope, ctx)
                }
            }
        }
        return;
    }
    if let Some((hit, proven)) = target_guided_alias_template_reference(node, ctx) {
        *ctx.raw_match_count += 1;
        if proven {
            push_type_hit(hit, ctx);
        } else {
            push_unproven_hit(hit, ctx);
        }
        return;
    }
    if !recovered_type
        && !recovered_qualified_friend
        && !recovered_exported_class_base
        && is_declaration_name(node)
    {
        let mut matched_owner = false;
        if let Some(owners) = out_of_line_member_definition_owner(
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            ctx.source,
            node,
        ) {
            for (owner_node, owner) in owners.owners {
                if same_visible_symbol(&owner, &ctx.spec.target) {
                    matched_owner = true;
                    *ctx.raw_match_count += 1;
                    push_guarded_owner_hit(owner_node, &owner, node, ctx);
                }
            }
        }
        if !matched_owner && let Some(scopes) = target_guided_qualifier_type_scopes(node, ctx) {
            *ctx.raw_match_count += 1;
            for scope in scopes {
                push_hit(scope, ctx);
            }
        } else if !matched_owner
            && let Some(scope) = target_guided_unproven_out_of_line_owner(node, ctx)
        {
            *ctx.raw_match_count += 1;
            push_unproven_hit(scope, ctx);
        }
        return;
    }
    let hit_node = node;
    let text = node_text(hit_node, ctx.source);
    let type_resolution = if hit_node.kind() == "template_type"
        && ctx.visibility.is_template_specialization(&ctx.spec.target)
    {
        resolve_nested_template_type_for_target(hit_node, ctx).unwrap_or_else(|| {
            resolve_type_node_lexically_for_target(
                hit_node,
                &ctx.analyzer,
                ctx.visibility,
                &ctx.ordinary_type_imports,
                ctx.file,
                ctx.source,
                &ctx.spec.target,
                Some(&ctx.lexical_scope_cache),
                ctx.recovered_sentinel_scope(hit_node).as_deref(),
            )
        })
    } else {
        resolve_type_node_lexically_for_target(
            hit_node,
            &ctx.analyzer,
            ctx.visibility,
            &ctx.ordinary_type_imports,
            ctx.file,
            ctx.source,
            &ctx.spec.target,
            Some(&ctx.lexical_scope_cache),
            ctx.recovered_sentinel_scope(hit_node).as_deref(),
        )
    };
    match type_resolution {
        LexicalTypeResolution::Resolved {
            unit, candidates, ..
        } if type_resolution_matches_target(node, &unit, &candidates, ctx) => {
            *ctx.raw_match_count += 1;
            if let Some(scopes) = static_qualifier_type_scopes(node, ctx) {
                for scope in scopes {
                    push_type_hit(scope, ctx);
                }
            } else {
                push_resolved_type_hit(hit_node, &candidates, ctx);
            }
            return;
        }
        LexicalTypeResolution::Resolved {
            unit: _,
            candidates,
            ..
        } => {
            if let Some(scopes) = static_qualifier_type_scopes(node, ctx) {
                *ctx.raw_match_count += 1;
                for scope in scopes {
                    push_type_hit(scope, ctx);
                }
            } else if let Some(hit) =
                target_guided_unproven_alias_type_reference(node, &candidates, ctx)
            {
                *ctx.raw_match_count += 1;
                push_unproven_hit(hit, ctx);
            } else if let Some(leaf) = target_guided_missing_alias_rhs_type_leaf(node, ctx)
                .or_else(|| target_guided_missing_member_alias_type_leaf(node, ctx))
            {
                *ctx.raw_match_count += 1;
                push_type_hit(leaf, ctx);
            } else if let Some(leaf) = target_guided_dependent_class_alias_leaf(node, ctx) {
                *ctx.raw_match_count += 1;
                push_unproven_hit(leaf, ctx);
            }
            return;
        }
        LexicalTypeResolution::Ambiguous => {
            if let Some(scopes) = static_qualifier_type_scopes(node, ctx) {
                *ctx.raw_match_count += 1;
                for scope in scopes {
                    push_type_hit(scope, ctx);
                }
            } else if let Some(leaf) = target_guided_dependent_class_alias_leaf(node, ctx) {
                *ctx.raw_match_count += 1;
                push_unproven_hit(leaf, ctx);
            } else if let Some(leaf) = target_guided_missing_alias_rhs_type_leaf(node, ctx)
                .or_else(|| target_guided_missing_member_alias_type_leaf(node, ctx))
                .or_else(|| target_guided_ambiguous_owned_alias_type_leaf(node, ctx))
            {
                *ctx.raw_match_count += 1;
                push_type_hit(leaf, ctx);
            }
            return;
        }
        LexicalTypeResolution::Missing => {
            if let Some(unit) = ctx.visibility.unique_visible_parameter_type_fallback(
                &ctx.analyzer,
                ctx.file,
                hit_node,
                ctx.source,
            ) && same_visible_symbol(&unit, &ctx.spec.target)
            {
                *ctx.raw_match_count += 1;
                push_type_hit(hit_node, ctx);
                return;
            }
            if let Some(leaf) = target_guided_compatible_foreign_import_type_leaf(node, ctx) {
                *ctx.raw_match_count += 1;
                push_unproven_hit(leaf, ctx);
                return;
            }
            if let Some(leaf) = target_guided_dependent_class_alias_leaf(node, ctx) {
                *ctx.raw_match_count += 1;
                push_unproven_hit(leaf, ctx);
                return;
            }
            if let Some(leaf) = target_guided_missing_type_leaf(node, ctx) {
                *ctx.raw_match_count += 1;
                push_type_hit(leaf, ctx);
                return;
            }
            let raw_resolution = resolve_type_node_lexically_for_target_without_visibility(
                hit_node,
                &ctx.analyzer,
                ctx.visibility,
                ctx.file,
                ctx.source,
                &ctx.spec.target,
            );
            let raw_matches = matches!(
                raw_resolution,
                LexicalTypeResolution::Resolved {
                    ref unit,
                    ref candidates,
                    ..
                } if type_resolution_identifies_unit_target(
                    hit_node,
                    unit,
                    candidates,
                    &ctx.spec.target,
                    ctx,
                )
            );
            if raw_matches
                || type_node_has_exact_target_identity_without_visibility(
                    hit_node,
                    &ctx.analyzer,
                    ctx.visibility,
                    ctx.file,
                    ctx.source,
                    &ctx.spec.target,
                )
            {
                *ctx.raw_match_count += 1;
                push_unproven_hit(type_reference_hit_node(hit_node), ctx);
                return;
            }
        }
    }
    // A class-owned alias can be qualified by an owner made visible through a
    // namespace import, including an import in an earlier reopening of the
    // same unnamed namespace. Resolve that owner before requiring an
    // enclosing class for inherited nested-type lookup.
    if ctx
        .visibility
        .parser_alias_resolves_to_type(ctx.file, text, &ctx.spec.target)
    {
        *ctx.raw_match_count += 1;
        push_type_hit(type_reference_hit_node(hit_node), ctx);
        return;
    }
    if let Some(scopes) = static_qualifier_type_scopes(node, ctx) {
        *ctx.raw_match_count += 1;
        for scope in scopes {
            push_type_hit(scope, ctx);
        }
        return;
    }
    if !name_mentions(text, &ctx.spec.member_name) {
        return;
    }
    *ctx.raw_match_count += 1;
    if !ctx.visibility.external_type_candidate_visible_in_context(
        &ctx.analyzer,
        ctx.file,
        &ctx.spec.target,
        hit_node,
    ) {
        let unproven = static_qualifier_name_scope(node, ctx).unwrap_or(hit_node);
        if type_reference_resolves_away_from_target(unproven, ctx) {
            return;
        }
        push_unproven_hit(unproven, ctx);
    }
}

fn maybe_record_object_macro_replacement_type_hits(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    for reference in object_macro_replacement_type_references(node, ctx.source) {
        for component_count in 1..=reference.components.len() {
            let resolution = resolve_type_components_lexically_at_for_target_with_scope_cache(
                node,
                &reference.components[..component_count],
                reference.global,
                &ctx.analyzer,
                ctx.visibility,
                &ctx.ordinary_type_imports,
                ctx.file,
                ctx.source,
                &ctx.spec.target,
                false,
                Some(&ctx.lexical_scope_cache),
            );
            let matches_target = match resolution {
                LexicalTypeResolution::Resolved {
                    unit, candidates, ..
                } => {
                    same_visible_symbol(&unit, &ctx.spec.target)
                        || candidates
                            .iter()
                            .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target))
                }
                LexicalTypeResolution::Missing => unique_macro_replacement_type_candidate(
                    &ctx.analyzer,
                    ctx.visibility,
                    ctx.file,
                    &reference.components[..component_count],
                )
                .is_some_and(|candidate| same_visible_symbol(&candidate, &ctx.spec.target)),
                LexicalTypeResolution::Ambiguous => false,
            };
            if !matches_target {
                continue;
            }
            let range = &reference.component_ranges[component_count - 1];
            *ctx.raw_match_count += 1;
            push_type_hit_range(node, range.start, range.end, ctx);
        }
    }
}

fn target_guided_compatible_foreign_import_type_leaf<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    let (components, global) = type_reference_components(node, ctx.source)?;
    let lexical_scope = ctx.recovered_sentinel_scope(node).or_else(|| {
        match cached_enclosing_lexical_scope_components_with_unresolved_owner(
            node,
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            ctx.source,
            false,
            false,
            Some(&ctx.lexical_scope_cache),
        ) {
            LexicalScopeResolution::Resolved(scope) => Some(scope),
            LexicalScopeResolution::Ambiguous | LexicalScopeResolution::Missing => None,
        }
    })?;
    let OrdinaryTypeImportResolution::Resolved { target, .. } =
        compatible_foreign_type_import_resolution(
            node,
            &components,
            global,
            &ctx.analyzer,
            ctx.visibility,
            &ctx.ordinary_type_imports,
            ctx.file,
            ctx.source,
            &lexical_scope,
            Some(&ctx.spec.target),
        )
    else {
        return None;
    };
    same_visible_symbol(&target, &ctx.spec.target).then(|| type_reference_hit_node(node))
}

/// Resolve `Owner::Nested` when complete type lookup cannot express the owner
/// as its first qualified component. This occurs when a using-directive
/// imports `Owner` and when inherited-type lookup injects it. Resolve the
/// owner prefix independently, then return the terminal node after that owner
/// proves the target's direct nested declaration; hit insertion expands it to
/// the complete written type.
fn target_guided_nested_type_terminal_hit<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    // Returns a node of the caller's tree lifetime, which the context-scoped
    // ancestry index cannot name; this is one question per call.
    let qualified = node.parent().filter(|parent| {
        matches!(
            parent.kind(),
            "qualified_identifier" | "scoped_type_identifier"
        ) && parent.child_by_field_name("name") == Some(node)
    })?;
    let mut complete = qualified;
    while let Some(parent) = complete.parent().filter(|parent| {
        matches!(
            parent.kind(),
            "qualified_identifier" | "scoped_type_identifier"
        )
    }) {
        complete = parent;
    }
    let owner = qualified_owner_components(complete, ctx.source)?;

    if let LexicalTypeResolution::Resolved {
        unit, candidates, ..
    } = resolve_type_node_lexically_for_target(
        complete,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
        &ctx.spec.target,
        Some(&ctx.lexical_scope_cache),
        ctx.recovered_sentinel_scope(complete).as_deref(),
    ) && type_resolution_matches_target(complete, &unit, &candidates, ctx)
        && ctx
            .analyzer
            .parent_of(&ctx.spec.target)
            .is_some_and(|parent| parent.is_class())
        && !ctx
            .analyzer
            .type_alias_provider()
            .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target))
        && is_namespace_scope_type_reference(complete)
        && namespace_import_can_name_nested_target(complete, ctx)
    {
        return Some(node);
    }

    let target_owner = ctx
        .analyzer
        .parent_of(&ctx.spec.target)
        .filter(CodeUnit::is_class);
    let owner_spelling_can_name_target = target_owner.as_ref().is_some_and(|target_owner| {
        let target_components = canonical_cpp_scope_components(target_owner);
        if owner.global {
            target_components == owner.names
        } else {
            target_components.ends_with(&owner.names)
        }
    });
    let target_member_visible = |target_owner: &CodeUnit| {
        ctx.visibility
            .visible_members_for_owner_name(ctx.file, target_owner, node_text(node, ctx.source))
            .into_iter()
            .any(|candidate| {
                same_visible_symbol(candidate, &ctx.spec.target)
                    && (ctx
                        .visibility
                        .external_type_candidate_guard_compatible_in_context(
                            &ctx.analyzer,
                            ctx.file,
                            candidate,
                            complete,
                        )
                        || (ctx
                            .visibility
                            .is_exhaustive_same_fqn_type_declaration_family(
                                &ctx.analyzer,
                                ctx.file,
                                candidate,
                            )
                            && ctx.visibility.external_type_candidate_visible_in_context(
                                &ctx.analyzer,
                                ctx.file,
                                candidate,
                                complete,
                            )))
            })
    };

    if owner_spelling_can_name_target
        && (is_namespace_scope_type_reference(complete)
            || (is_compound_type_reference(complete)
                && namespace_import_can_name_nested_target(complete, ctx)))
        && let Some(target_owner) = target_owner.as_ref()
        && let LexicalTypeResolution::Resolved { unit, .. } =
            resolve_type_components_lexically_at_preserving_alias_with_scope_cache(
                complete,
                &owner.names,
                owner.global,
                &ctx.analyzer,
                ctx.visibility,
                &ctx.ordinary_type_imports,
                ctx.file,
                ctx.source,
                Some(&ctx.lexical_scope_cache),
            )
        && ctx
            .visibility
            .same_template_owner_identity(&unit, target_owner)
        && target_member_visible(target_owner)
    {
        return Some(node);
    }

    let enclosing_owner = structured_enclosing_owner(node, ctx)?;
    let lexical_scope = canonical_cpp_scope_components(&enclosing_owner);
    let owner_resolution = ctx.visibility.resolve_type_components_lexically(
        &ctx.analyzer,
        ctx.file,
        &owner.names,
        owner.global,
        &lexical_scope,
    );
    let owner_unit = match owner_resolution {
        LexicalTypeResolution::Resolved { unit, .. } => unit,
        LexicalTypeResolution::Missing if !owner.global && owner.names.len() == 1 => {
            ctx.visibility.inherited_injected_class_owner(
                &ctx.analyzer,
                ctx.file,
                &enclosing_owner,
                owner.names.first()?,
            )?
        }
        LexicalTypeResolution::Ambiguous | LexicalTypeResolution::Missing => return None,
    };
    let name = node_text(node, ctx.source);
    ctx.visibility
        .visible_members_for_owner_name(ctx.file, &owner_unit, name)
        .into_iter()
        .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target))
        .then_some(complete)
}

fn is_namespace_scope_type_reference(node: Node<'_>) -> bool {
    // Namespace-scope nested classes need a terminal edge when the complete
    // qualified node is the only structured evidence (as in #2213). In
    // parameters, fields, and callable bodies the enclosing type node already
    // owns the exact range; adding its terminal would duplicate that edge.
    let mut current = node.parent();
    while let Some(parent) = current {
        match parent.kind() {
            "call_expression" | "new_expression" => return true,
            "parameter_declaration"
            | "optional_parameter_declaration"
            | "field_declaration"
            | "function_definition"
            | "function_declarator"
            | "class_specifier"
            | "struct_specifier"
            | "union_specifier"
            | "compound_statement" => return false,
            "declaration" => {
                let mut cursor = parent.walk();
                if parent
                    .named_children(&mut cursor)
                    .any(|child| child.kind() == "function_declarator")
                {
                    return false;
                }
            }
            _ => {}
        }
        current = parent.parent();
    }
    true
}

fn is_compound_type_reference(node: Node<'_>) -> bool {
    let mut current = node.parent();
    while let Some(parent) = current {
        match parent.kind() {
            "compound_statement" => return true,
            "namespace_definition" | "translation_unit" => return false,
            _ => current = parent.parent(),
        }
    }
    false
}

fn namespace_import_can_name_nested_target(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let Some(target_owner) = ctx.analyzer.parent_of(&ctx.spec.target) else {
        return false;
    };
    effective_using_bindings_for_name(
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        node,
        ctx.source,
        target_owner.identifier(),
    )
    .iter()
    .any(|binding| matches!(binding.target, EffectiveUsingTarget::Namespace { .. }))
}

/// Recover the class-template qualifier in a dependent leading return type of
/// an out-of-line member definition.
///
/// `typename Owner<T>::Alias Owner<T>::method()` contains two references to
/// `Owner`: one in the return type and one in the callable declarator. The
/// latter already has authoritative indexed owner resolution. Reuse that
/// structured owner evidence for the former when both template names agree;
/// resolving `Owner<T>::Alias` as one type would instead select terminal
/// `Alias` and discard the qualifier.
fn out_of_line_dependent_return_template_owner<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if node.kind() != "template_type" {
        return None;
    }
    let template_name = template_reference_name_node(node)?;
    let mut scope = node;
    while let Some(parent) = ctx.ancestry.parent(scope).filter(|parent| {
        matches!(
            parent.kind(),
            "qualified_identifier" | "scoped_identifier" | "scoped_type_identifier"
        ) && parent.child_by_field_name("name") == Some(scope)
    }) {
        scope = parent;
    }
    let qualified = ctx.ancestry.parent(scope).filter(|parent| {
        matches!(
            parent.kind(),
            "qualified_identifier" | "scoped_identifier" | "scoped_type_identifier"
        ) && parent.child_by_field_name("scope") == Some(scope)
    })?;
    let mut function = ctx.ancestry.parent(qualified);
    let function = loop {
        let candidate = function?;
        if candidate.kind() == "function_definition" {
            break candidate;
        }
        function = ctx.ancestry.parent(candidate);
    };
    let return_type = function.child_by_field_name("type")?;
    if return_type.start_byte() > node.start_byte() || node.end_byte() > return_type.end_byte() {
        return None;
    }
    let declarator_name = function
        .child_by_field_name("declarator")
        .and_then(declarator_name_node)?;
    if node_text(template_name, ctx.source) != ctx.spec.target.identifier() {
        return None;
    }
    let resolved_owner_matches = out_of_line_member_definition_owner(
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        ctx.source,
        declarator_name,
    )
    .is_some_and(|owners| {
        owners
            .owners
            .iter()
            .any(|(_, owner)| same_logical_symbol(owner, &ctx.spec.target))
    });
    let indexed_owner_matches =
        indexed_out_of_line_template_owner_hit(declarator_name, ctx).is_some();
    let target_guided_owner_matches =
        target_guided_qualifier_type_scopes(declarator_name, ctx).is_some();
    (resolved_owner_matches || indexed_owner_matches || target_guided_owner_matches)
        .then_some(template_name)
}

/// Use the indexed callable identity when a malformed namespace sentinel
/// prevents lexical lookup of an out-of-line template owner.
fn indexed_out_of_line_template_owner_hit<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if !matches!(node.kind(), "qualified_identifier" | "scoped_identifier")
        || !is_declaration_name(node)
    {
        return None;
    }
    let mut function = ctx.ancestry.parent(node);
    let function = loop {
        let candidate = function?;
        if candidate.kind() == "function_definition" {
            break candidate;
        }
        function = ctx.ancestry.parent(candidate);
    };
    if function
        .child_by_field_name("declarator")
        .and_then(declarator_name_node)
        != Some(node)
    {
        return None;
    }
    let target = physically_visible_type_target(ctx)?;
    let qualified = qualified_owner_components(node, ctx.source)?;
    if qualified.names.last().map(String::as_str) != Some(target.identifier()) {
        return None;
    }
    if indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, node)?
        != canonical_cpp_scope_components(target)
    {
        return None;
    }
    let owner = qualified.nodes.last().copied()?;
    let template = if owner.kind() == "template_type" {
        owner
    } else {
        owner
            .parent()
            .filter(|parent| parent.kind() == "template_type")?
    };
    template_reference_name_node(template)
}

fn push_guarded_owner_hit(
    owner_node: Node<'_>,
    owner: &CodeUnit,
    reference: Node<'_>,
    ctx: &mut ScanCtx<'_>,
) {
    if ctx
        .visibility
        .external_type_candidate_guard_compatible_in_context(
            &ctx.analyzer,
            ctx.file,
            owner,
            reference,
        )
    {
        push_hit(owner_node, ctx);
    } else {
        push_unproven_hit(owner_node, ctx);
    }
}

/// Preserve a direct template-alias reference when a macro namespace sentinel
/// makes tree-sitter drop the first source path component.
fn target_guided_alias_template_reference<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<(Node<'tree>, bool)> {
    let alias_provider = ctx.analyzer.type_alias_provider()?;
    if !matches!(
        node.kind(),
        "qualified_identifier" | "scoped_type_identifier"
    ) || !alias_provider.is_type_alias(&ctx.spec.target)
    {
        return None;
    }
    cpp_template_reference_arguments(node, ctx.source)?;
    let (components, global) = type_reference_components(node, ctx.source)?;
    if components.last().map(String::as_str) != Some(ctx.spec.target.identifier()) {
        return None;
    }
    let target = physically_visible_type_target(ctx)?;
    let target_components = canonical_cpp_scope_components(target);
    let parser_namespace = enclosing_namespace_components(node, ctx.source);
    let path_matches = if global {
        components == target_components
            || (!parser_namespace.is_empty()
                && target_components.starts_with(&parser_namespace)
                && target_components[parser_namespace.len()..] == components)
    } else {
        let lexical_scope = match enclosing_lexical_scope_components(
            node,
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            ctx.source,
        ) {
            LexicalScopeResolution::Resolved(scope) => scope,
            LexicalScopeResolution::Ambiguous | LexicalScopeResolution::Missing => parser_namespace,
        };
        lexical_component_tiers(&components, false, &lexical_scope)
            .any(|scope| scope == target_components)
    };
    let scoped_candidates = ctx
        .visibility
        .visible_identifier_candidates(ctx.file, target.identifier())
        .filter(|candidate| canonical_cpp_scope_components(candidate) == target_components)
        .collect::<Vec<_>>();
    if !path_matches
        || scoped_candidates.is_empty()
        || scoped_candidates
            .iter()
            .any(|candidate| !same_visible_symbol(candidate, target))
        || !ctx.visibility.structured_alias_primary_preserves_target(
            &ctx.analyzer,
            ctx.file,
            target,
            target,
        )
    {
        return None;
    }
    let proven = ctx.visibility.external_type_candidate_visible_in_context(
        &ctx.analyzer,
        ctx.file,
        target,
        node,
    );
    Some((node, proven))
}

/// Tree-sitter can split a macro-qualified member return type into a phantom
/// field followed by the real function definition.  The declaration visitor
/// discards that phantom field, but its declarator token remains a semantic
/// type reference. Resolve it from the recovered or indexed class scope so an
/// enclosing-class alias remains distinguishable from same-spelled siblings.
fn maybe_record_recovered_macro_return_type_hit(return_type: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let name = node_text(return_type, ctx.source);
    if name != ctx.spec.target.identifier() || ctx.local_shadows.is_shadowed(name) {
        return;
    }
    if physically_visible_type_target(ctx).is_some()
        && type_alias_owner_encloses_structured_reference(return_type, ctx)
        && !nearer_type_name_shadows_structured_reference(return_type, ctx)
        && ctx.visibility.external_type_candidate_visible_in_context(
            &ctx.analyzer,
            ctx.file,
            &ctx.spec.target,
            return_type,
        )
    {
        *ctx.raw_match_count += 1;
        push_type_hit(return_type, ctx);
        return;
    }
    let Some(scope) = ctx
        .recovered_sentinel_scope(return_type)
        .or_else(|| indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, return_type))
    else {
        return;
    };
    let components = [name.to_string()];
    let resolution = ctx.visibility.resolve_type_components_lexically(
        &ctx.analyzer,
        ctx.file,
        &components,
        false,
        &scope,
    );
    if let LexicalTypeResolution::Resolved {
        unit, candidates, ..
    } = resolution
        && (same_visible_symbol(&unit, &ctx.spec.target)
            || candidates
                .iter()
                .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target)))
    {
        *ctx.raw_match_count += 1;
        push_type_hit(return_type, ctx);
    }
}

/// Return the class/struct scope in a C++ pointer-to-member declarator such as
/// `double Owner::*member`. Tree-sitter represents the owner as the `scope` of
/// a `qualified_identifier`, while the `name` is a pointer declarator rather
/// than a type node; ordinary type-reference traversal therefore skips it.
fn member_pointer_owner_components<'tree>(
    node: Node<'tree>,
    source: &str,
) -> Option<(QualifiedOwnerComponents<'tree>, Node<'tree>)> {
    if node.kind() != "qualified_identifier" {
        return None;
    }
    let declarator = node.child_by_field_name("name")?;
    if !matches!(
        declarator.kind(),
        "pointer_type_declarator" | "abstract_pointer_declarator"
    ) {
        return None;
    }
    let scope = node.child_by_field_name("scope")?;
    // Keep this check entirely structural.  C and C++ share the
    // `qualified_identifier` node shape for some recovered declarations, but
    // only the C++ member-pointer form has an actual `::` grammar child
    // between the owner scope and pointer declarator.  Looking at the source
    // slice here would make a recovered C declarator look like a C++ owner
    // merely because its bytes happen to contain the same punctuation.
    let mut saw_scope = false;
    let has_scope_separator = (0..node.child_count()).any(|index| {
        let Some(child) = node.child(index) else {
            return false;
        };
        if same_node(child, scope) {
            saw_scope = true;
            return false;
        }
        saw_scope && !same_node(child, declarator) && child.kind() == "::" && !child.is_missing()
    });
    if !has_scope_separator {
        return None;
    }
    let mut nodes = cpp_name_component_nodes(scope)?;
    let mut outer = node;
    while let Some(parent) = outer.parent()
        && parent.kind() == "qualified_identifier"
        && parent.child_by_field_name("name") == Some(outer)
    {
        let mut prefix = cpp_name_component_nodes(parent.child_by_field_name("scope")?)?;
        prefix.append(&mut nodes);
        nodes = prefix;
        outer = parent;
    }
    let names = nodes
        .iter()
        .map(|component| node_text(*component, source).to_string())
        .collect();
    Some((
        QualifiedOwnerComponents {
            nodes,
            names,
            global: is_globally_qualified_cpp_name(outer),
        },
        outer,
    ))
}

fn member_pointer_alias_owner_prefix_matches(
    node: Node<'_>,
    owner: &QualifiedOwnerComponents<'_>,
    ctx: &ScanCtx<'_>,
) -> bool {
    let Some((_, owner_prefix)) = owner.names.split_last() else {
        return false;
    };
    let Some(parent) = type_owner_of(&ctx.analyzer, &ctx.spec.target) else {
        return false;
    };
    let recovered_scope = ctx.recovered_sentinel_scope(node);
    let resolution = if let Some(recovered_scope) = recovered_scope {
        resolve_type_components_lexically_at_for_target_with_recovered_scope(
            node,
            owner_prefix,
            owner.global,
            &ctx.analyzer,
            ctx.visibility,
            &ctx.ordinary_type_imports,
            ctx.file,
            ctx.source,
            &parent,
            false,
            &recovered_scope,
        )
    } else {
        resolve_type_components_lexically_at_for_target_with_scope_cache(
            node,
            owner_prefix,
            owner.global,
            &ctx.analyzer,
            ctx.visibility,
            &ctx.ordinary_type_imports,
            ctx.file,
            ctx.source,
            &parent,
            false,
            Some(&ctx.lexical_scope_cache),
        )
    };
    let LexicalTypeResolution::Resolved {
        unit, candidates, ..
    } = resolution
    else {
        return false;
    };
    same_member_pointer_owner_identity(&unit, &parent)
        || candidates
            .iter()
            .any(|candidate| same_member_pointer_owner_identity(candidate, &parent))
}

fn same_member_pointer_owner_identity(left: &CodeUnit, right: &CodeUnit) -> bool {
    same_visible_symbol(left, right)
        || (left.kind() == right.kind()
            && left.fq_name() == right.fq_name()
            && left.source() == right.source())
}

/// Resolve a template type nested in a qualified identifier against a concrete
/// type target. The target-guided lexical path intentionally applies a
/// structured candidate prefilter; that prefilter cannot see a partial
/// specialization until the template arguments have selected it. Resolve the
/// complete qualified primary first, then apply the parsed arguments and
/// retain the result only when it is the requested target.
fn resolve_nested_template_type_for_target(
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> Option<LexicalTypeResolution> {
    let reference_node = node
        .parent()
        .filter(|parent| {
            parent.kind() == "qualified_identifier"
                && parent.child_by_field_name("name") == Some(node)
        })
        .unwrap_or(node);
    let target_resolution = resolve_type_node_lexically_for_target(
        reference_node,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
        &ctx.spec.target,
        Some(&ctx.lexical_scope_cache),
        ctx.recovered_sentinel_scope(reference_node).as_deref(),
    );
    if let LexicalTypeResolution::Resolved {
        unit, candidates, ..
    } = target_resolution
        && template_reference_candidates_select_target(
            reference_node,
            &candidates,
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            ctx.source,
            &ctx.spec.target,
        )
    {
        return Some(LexicalTypeResolution::Resolved {
            unit,
            components: Vec::new(),
            candidates,
        });
    }

    let normal_resolution = resolve_type_node_lexically(
        reference_node,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
    );
    let LexicalTypeResolution::Resolved {
        unit,
        components,
        candidates,
    } = normal_resolution
    else {
        return None;
    };
    let arguments = cpp_template_reference_arguments(reference_node, ctx.source)?;
    let specialized = ctx
        .visibility
        .resolve_template_arguments(ctx.file, unit.clone(), &arguments)
        .ok()
        .unwrap_or(unit);
    (same_visible_symbol(&specialized, &ctx.spec.target)
        || template_type_component_preserves_target(reference_node, &candidates, ctx))
    .then_some(LexicalTypeResolution::Resolved {
        unit: specialized,
        components,
        candidates,
    })
}

fn type_reference_components_may_name_target(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let mut reference = node;
    while let Some(parent) = ctx.ancestry.parent(reference) {
        let owns_component = matches!(parent.kind(), "template_type" | "template_function")
            && parent.child_by_field_name("name") == Some(reference)
            || matches!(
                parent.kind(),
                "qualified_identifier" | "scoped_identifier" | "scoped_type_identifier"
            ) && (parent.child_by_field_name("scope") == Some(reference)
                || parent.child_by_field_name("name") == Some(reference));
        if !owns_component {
            break;
        }
        reference = parent;
    }
    let Some((components, global)) = type_reference_components(reference, ctx.source) else {
        return false;
    };
    if !global
        && components.len() > 1
        && let Some(alias_type) = local_receiver_alias_type_node(reference, &components[0], ctx)
    {
        let Ok(Some(owner)) = resolve_receiver_type_node(alias_type, ctx) else {
            return false;
        };
        let mut redirected = canonical_cpp_scope_components(&owner);
        redirected.extend_from_slice(&components[1..]);
        return type_reference_component_list_may_name_target(
            &redirected,
            true,
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            &ctx.spec.target,
            &ctx.type_reference_component_names,
        );
    }
    type_reference_component_list_may_name_target(
        &components,
        global,
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        &ctx.spec.target,
        &ctx.type_reference_component_names,
    )
}

fn type_reference_component_list_may_name_target(
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    target: &CodeUnit,
    reference_component_names: &HashSet<String>,
) -> bool {
    if components.iter().any(|component| {
        visibility.type_reference_component_directly_names_target(component, target)
    }) {
        return true;
    }
    if components.iter().any(|component| {
        visibility.parser_alias_name_may_resolve_to_target(file, component, target)
    }) {
        return true;
    }
    if components.len() > 1 {
        return visibility.qualified_alias_reference_may_reach_target(
            analyzer, file, components, global, target,
        );
    }
    components
        .iter()
        .any(|component| reference_component_names.contains(component))
}

/// Fast structured admission before a type scan builds its parent and lexical
/// indexes. Most inverse candidates merely include the target's header and do
/// not contain a reference spelling; the full stateful scan has no work in
/// those files. Only maximal grammar type names are tested so a common nested
/// alias terminal such as `type` is considered together with its owner.
fn file_may_reference_type_target(
    root: Node<'_>,
    source: &str,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    target: &CodeUnit,
    reference_component_names: &HashSet<String>,
) -> bool {
    visit_file_type_reference_spellings(root, source, |components, global| {
        type_reference_component_list_may_name_target(
            components,
            global,
            analyzer,
            visibility,
            file,
            target,
            reference_component_names,
        )
    })
}

fn visit_file_type_reference_spellings(
    root: Node<'_>,
    source: &str,
    mut visit: impl FnMut(&[String], bool) -> bool,
) -> bool {
    let mut stopped = false;
    walk_named_tree_preorder(root, true, |node| {
        if node.kind() == "comment" {
            return WalkControl::SkipChildren;
        }
        if node.kind() == "preproc_arg" {
            stopped = object_macro_replacement_type_references(node, source)
                .into_iter()
                .any(|reference| visit(&reference.components, reference.global));
            return if stopped {
                WalkControl::Break
            } else {
                WalkControl::SkipChildren
            };
        }
        if node.kind() == "field_declaration"
            && let Some(return_type) = recovered_macro_return_type_node(node, source)
        {
            let components = [node_text(return_type, source).to_string()];
            stopped = visit(&components, false);
            if stopped {
                return WalkControl::Break;
            }
        }
        if let Some((type_node, _)) = recovered_macro_decorated_type_node(node) {
            for candidate in [node, type_node] {
                let Some((components, global)) = type_reference_components(candidate, source)
                else {
                    continue;
                };
                stopped = visit(&components, global);
                if stopped {
                    return WalkControl::Break;
                }
            }
        }
        let Some((components, global)) = type_reference_components(node, source) else {
            return WalkControl::Continue;
        };
        if node.parent().is_some_and(|parent| {
            (matches!(parent.kind(), "template_type" | "template_function")
                && parent.child_by_field_name("name") == Some(node))
                || (matches!(
                    parent.kind(),
                    "qualified_identifier" | "scoped_identifier" | "scoped_type_identifier"
                ) && (parent.child_by_field_name("scope") == Some(node)
                    || parent.child_by_field_name("name") == Some(node)))
        }) {
            return WalkControl::Continue;
        }
        stopped = visit(&components, global);
        if stopped {
            WalkControl::Break
        } else {
            WalkControl::Continue
        }
    });
    stopped
}

/// Whether this file decides the reference against the scan target.
///
/// The last resort of type admission has no structured resolution left: it
/// only knows that the spelling mentions the target's name and that the target
/// itself is not visible here. That is undecidable when nothing else declares
/// the name, but it is a proven negative when the file already makes another
/// declaration of the same name visible, because unqualified lookup binds the
/// reference to that declaration and the include closure never reaches the
/// target. `resolve_type_node_lexically_for_target` asks the visibility index
/// the same question before it resolves; asking it again here keeps the
/// inverse from admitting a site that forward resolution has already decided
/// (#2916).
fn type_reference_resolves_away_from_target(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let Some((components, _global)) = type_reference_components(node, ctx.source) else {
        return false;
    };
    let terminal = components
        .last()
        .expect("type reference components are non-empty");
    if terminal != ctx.spec.target.identifier() {
        return false;
    }
    // A concrete specialization is selected from the template arguments, not
    // from the visible primary name, so the name-level candidate set cannot
    // decide it. `resolve_type_node_lexically_for_target` makes the same
    // exception before its own structured prefilter.
    if cpp_template_reference_arguments(node, ctx.source).is_some()
        && ctx.visibility.is_template_specialization(&ctx.spec.target)
    {
        return false;
    }
    // One C++ type reached through a forward declaration in one header and its
    // definition in another is two CodeUnits with different signatures and one
    // qualified name. A file that sees either of them sees the target's type,
    // so only a candidate under a different qualified name decides the
    // reference against it. This is what separates the decoy in an unrelated
    // namespace from a redeclaration of the target itself.
    if ctx
        .visibility
        .visible_identifier_candidates(ctx.file, terminal)
        .any(|candidate| {
            candidate.kind() == ctx.spec.target.kind()
                && candidate.fq_name() == ctx.spec.target.fq_name()
        })
    {
        return false;
    }
    !ctx.visibility
        .structured_type_reference_may_resolve_to_target(
            &ctx.analyzer,
            ctx.file,
            std::slice::from_ref(terminal),
            false,
            &[],
            &ctx.spec.target,
        )
}

fn qualified_type_scope_contains_template(node: Node<'_>) -> bool {
    let Some(scope) = node.child_by_field_name("scope") else {
        return false;
    };
    let mut pending = vec![scope];
    while let Some(candidate) = pending.pop() {
        if candidate.kind() == "template_type" {
            return true;
        }
        if matches!(
            candidate.kind(),
            "qualified_identifier" | "scoped_identifier" | "scoped_type_identifier"
        ) {
            if let Some(scope) = candidate.child_by_field_name("scope") {
                pending.push(scope);
            }
            if let Some(name) = candidate.child_by_field_name("name") {
                pending.push(name);
            }
        }
    }
    false
}

fn physically_visible_type_target<'a>(ctx: &'a ScanCtx<'_>) -> Option<&'a CodeUnit> {
    ctx.target_group.iter().find(|target| {
        same_logical_symbol(target, &ctx.spec.target)
            && ctx.visibility.is_physically_visible(ctx.file, target)
    })
}

/// Preserve the terminal token of a resolver-proven alias construction.
/// Ordinary qualified types and template aliases retain their full type range.
/// Alias identity and the construction context are proven by the resolver.
fn push_resolved_type_hit(node: Node<'_>, candidates: &[CodeUnit], ctx: &mut ScanCtx<'_>) {
    if let Some(terminal) = resolved_alias_terminal_node(node, candidates, ctx) {
        push_type_hit_range(terminal, terminal.start_byte(), terminal.end_byte(), ctx);
    } else {
        push_type_hit(type_reference_hit_node(node), ctx);
    }
}

fn resolved_alias_terminal_node<'tree>(
    node: Node<'tree>,
    candidates: &[CodeUnit],
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    let [candidate] = candidates else {
        return None;
    };
    let alias_provider = ctx.analyzer.type_alias_provider()?;
    let candidate_is_alias = alias_provider.is_type_alias(candidate)
        && same_visible_symbol(&canonical_alias_target(candidate, ctx), &ctx.spec.target);
    let target_is_alias = alias_provider.is_type_alias(&ctx.spec.target)
        && same_visible_symbol(candidate, &ctx.spec.target);
    if !(candidate_is_alias || target_is_alias) {
        return None;
    }
    if crate::graph::resolver::cpp_template_reference_arguments(node, ctx.source).is_some() {
        return None;
    }
    let reference = crate::graph::resolver::qualified_alias_reference_preserves_target(
        node,
        &ctx.spec.target,
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        ctx.source,
    );
    if reference
        != Some(
            crate::graph::resolver::QualifiedAliasReferenceKind::ConstructorWithExpressionArgument,
        )
    {
        return None;
    }
    cpp_name_component_nodes(node)?.last().copied()
}

fn target_guided_missing_direct_temporary_type<'tree>(
    function: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    let target = physically_visible_type_target(ctx)?;
    let component_nodes = cpp_name_component_nodes(function)?;
    let terminal = component_nodes.last().copied()?;
    if node_text(terminal, ctx.source) != target.identifier() {
        return None;
    }
    let components = component_nodes
        .iter()
        .map(|component| node_text(*component, ctx.source).to_string())
        .collect::<Vec<_>>();
    let indexed_scope = indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, function)?;
    indexed_scope_matches_target_name(
        &indexed_scope,
        &components,
        is_globally_qualified_cpp_name(function),
        target,
    )
    .then_some(terminal)
}

fn maybe_record_direct_temporary_type_hit(call: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let Some(function) = call.child_by_field_name("function") else {
        return;
    };
    if !matches!(
        function.kind(),
        "identifier"
            | "type_identifier"
            | "template_function"
            | "template_type"
            | "qualified_identifier"
            | "scoped_identifier"
            | "scoped_type_identifier"
    ) {
        return;
    }
    if !type_reference_components_may_name_target(function, ctx) {
        return;
    }
    if let Some(scopes) = static_qualifier_type_scopes(function, ctx) {
        *ctx.raw_match_count += 1;
        for scope in scopes {
            push_type_hit(scope, ctx);
        }
        return;
    }
    let terminal = function_terminal_node(function);
    let name = node_text(terminal, ctx.source);
    if name.is_empty() || ctx.local_shadows.is_shadowed(name) {
        return;
    }
    if let Some(enclosing_owner) = structured_enclosing_owner(function, ctx) {
        match resolve_declaring_member_owner(
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            &enclosing_owner,
            name,
        ) {
            EnclosingMemberOwnerResolution::Owner(owner)
                if matches!(
                    ctx.visibility
                        .visible_member_for_owner_name(ctx.file, &owner, name,),
                    VisibleMemberResolution::Callable(_) | VisibleMemberResolution::AmbiguousKind
                ) =>
            {
                return;
            }
            EnclosingMemberOwnerResolution::Ambiguous => return,
            EnclosingMemberOwnerResolution::Owner(_) | EnclosingMemberOwnerResolution::Missing => {}
        }
    }

    // A type alias used as a direct temporary (`result_type(value)`) is parsed
    // as an ordinary identifier call. Callable lookup can be ambiguous when
    // parser recovery flattens a namespace or same-spelled aliases are
    // visible from sibling distributions. An exact enclosing class owner
    // proves the member alias without treating the call as an arbitrary name;
    // retain the shadow and declaration-visibility guards above and below.
    if ctx
        .analyzer
        .type_alias_provider()
        .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target))
        && name == ctx.spec.target.identifier()
        && physically_visible_type_target(ctx).is_some()
        && !local_type_name_shadows(function, ctx)
        && type_alias_owner_matches_structured_reference(function, ctx)
        && ctx.visibility.external_type_candidate_visible_in_context(
            &ctx.analyzer,
            ctx.file,
            &ctx.spec.target,
            function,
        )
    {
        *ctx.raw_match_count += 1;
        push_type_hit(terminal, ctx);
        return;
    }

    let call_resolution = resolve_qualified_call_target(
        call,
        function,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
    );
    match call_resolution {
        BareCallTargetResolution::Type(unit) => {
            if same_visible_symbol(&unit, &ctx.spec.target) {
                *ctx.raw_match_count += 1;
                push_type_hit(function, ctx);
                return;
            }
        }
        BareCallTargetResolution::FreeFunctions(units)
            if units.iter().all(|unit| {
                unit.fq_name() == ctx.spec.target.fq_name()
                    && ctx
                        .visibility
                        .callable_is_constructor_declaration(&ctx.analyzer, unit)
            }) => {}
        BareCallTargetResolution::Ambiguous => {
            push_unproven_hit(function, ctx);
            return;
        }
        BareCallTargetResolution::FreeFunctions(_)
        | BareCallTargetResolution::UnprovenFreeFunctions(_)
        | BareCallTargetResolution::CallableShadow => return,
        // Generated `.c` includes can leave ordinary callable resolution with
        // no active callable even when target-preserving type resolution can
        // prove the constructor's class. Let the structured type fallback
        // below make that decision.
        BareCallTargetResolution::Missing => {}
    }
    let target_resolution = resolve_type_node_lexically_for_target(
        function,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
        &ctx.spec.target,
        Some(&ctx.lexical_scope_cache),
        ctx.recovered_sentinel_scope(function).as_deref(),
    );
    match target_resolution {
        LexicalTypeResolution::Resolved {
            unit, candidates, ..
        } if same_visible_symbol(&unit, &ctx.spec.target)
            || candidates
                .iter()
                .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target)) =>
        {
            *ctx.raw_match_count += 1;
            push_type_hit(function, ctx);
        }
        LexicalTypeResolution::Missing => {
            if let Some(hit) = target_guided_nested_type_terminal_hit(terminal, ctx)
                .or_else(|| target_guided_missing_direct_temporary_type(function, ctx))
            {
                *ctx.raw_match_count += 1;
                push_type_hit(hit, ctx);
            }
        }
        LexicalTypeResolution::Resolved { .. } | LexicalTypeResolution::Ambiguous => {}
    }
}

pub enum BareCallTargetResolution {
    Type(CodeUnit),
    FreeFunctions(Vec<CodeUnit>),
    UnprovenFreeFunctions(Vec<CodeUnit>),
    CallableShadow,
    Ambiguous,
    Missing,
}

pub enum BlockUsingCallTargetResolution {
    Target(BareCallTargetResolution),
    Unindexed(Vec<String>),
    Ambiguous,
}

#[allow(clippy::too_many_arguments)]
fn resolve_qualified_call_target(
    call: Node<'_>,
    function: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
) -> BareCallTargetResolution {
    if matches!(function.kind(), "identifier" | "template_function") {
        return resolve_bare_call_target(
            call,
            function,
            analyzer,
            visibility,
            ordinary_type_imports,
            file,
            source,
        );
    }
    if !matches!(
        function.kind(),
        "qualified_identifier" | "scoped_identifier" | "scoped_type_identifier"
    ) {
        return BareCallTargetResolution::Missing;
    }
    let terminal = function_terminal_node(function);
    let name = node_text(terminal, source);
    let Some((mut components, _)) = qualified_callable_owner_components(function, source) else {
        return BareCallTargetResolution::Missing;
    };
    components.push(name.to_string());
    let qualified_name = components.join("::");
    let type_resolution = resolve_type_node_lexically(
        function,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
    );
    let same_name_resolves_to_type = matches!(
        &type_resolution,
        LexicalTypeResolution::Resolved {
            unit,
            candidates,
            ..
        } if cpp_name_for(unit) == qualified_name
            || candidates
                .iter()
                .any(|candidate| cpp_name_for(candidate) == qualified_name)
    );
    let has_explicit_template_arguments =
        cpp_template_reference_arguments(function, source).is_some();
    let candidates = visibility
        .visible_identifier_candidates(file, name)
        .filter(|candidate| {
            candidate.is_function()
                && type_owner_of(analyzer, candidate).is_none()
                && !(same_name_resolves_to_type
                    && (visibility.callable_is_constructor_declaration(analyzer, candidate)
                        || has_explicit_template_arguments
                            && visibility
                                .callable_is_deduction_guide_declaration(analyzer, candidate)))
                && cpp_name_for(candidate) == qualified_name
                && visibility.declaration_visible_at(analyzer, file, candidate, call.start_byte())
        })
        .cloned()
        .collect::<Vec<_>>();
    if !candidates.is_empty() {
        return resolve_callable_candidates(
            candidates,
            visibility.call_arity_evidence(file, call, source).exact(),
            call.start_byte(),
            analyzer,
            visibility,
            file,
        );
    }
    match type_resolution {
        LexicalTypeResolution::Resolved { unit, .. } => BareCallTargetResolution::Type(unit),
        LexicalTypeResolution::Ambiguous => BareCallTargetResolution::Ambiguous,
        LexicalTypeResolution::Missing => BareCallTargetResolution::Missing,
    }
}

fn ordinary_binding_lookup_targets(
    binding: &OrdinaryTypeImport,
    active_bindings: &[&OrdinaryTypeImport],
    name: &str,
) -> Vec<Vec<String>> {
    let Some(qualified) = binding.resolved_target_components.as_ref() else {
        return Vec::new();
    };
    let mut targets = Vec::new();
    match binding.target {
        EffectiveUsingTarget::Ordinary { .. } => targets.push(qualified.clone()),
        EffectiveUsingTarget::Namespace { .. } => {
            let mut stack = vec![qualified.clone()];
            let mut visited = HashSet::default();
            while let Some(namespace) = stack.pop() {
                if !visited.insert(namespace.clone()) {
                    continue;
                }
                let mut target = namespace.clone();
                target.push(name.to_string());
                targets.push(target);
                stack.extend(active_bindings.iter().filter_map(|candidate| {
                    (matches!(candidate.target, EffectiveUsingTarget::Namespace { .. })
                        && candidate.namespace_scope.as_deref() == Some(namespace.as_slice()))
                    .then(|| candidate.resolved_target_components.clone())
                    .flatten()
                }));
            }
        }
    }
    targets
}

fn binding_free_function_candidates(
    binding: &OrdinaryTypeImport,
    active_bindings: &[&OrdinaryTypeImport],
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    name: &str,
    reference_byte: usize,
) -> Vec<CodeUnit> {
    ordinary_binding_lookup_targets(binding, active_bindings, name)
        .into_iter()
        .flat_map(|target| {
            let qualified_name = target.join("::");
            visibility
                .visible_identifier_candidates(file, name)
                .filter(move |candidate| {
                    candidate.is_function()
                        && type_owner_of(analyzer, candidate).is_none()
                        && cpp_name_for(candidate) == qualified_name
                        && visibility.declaration_visible_at(
                            analyzer,
                            file,
                            candidate,
                            reference_byte,
                        )
                })
                .cloned()
        })
        .collect()
}

/// Collapse the candidates unqualified lookup found to one entry per logical
/// callable, keeping the first spelling of each.
///
/// A header declaration and its out-of-line body spell one parameter type
/// differently often enough that the persisted signature strings disagree, so
/// the string triple alone reports one C++ declaration as an overload set and
/// an unproven argument count then turns it into ambiguity.
/// `same_logical_callable` answers the string question first and resolves the
/// written parameter names only when the strings differ (#2010).
fn dedupe_callable_candidates(
    candidates: &mut Vec<CodeUnit>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
) {
    let mut deduped = Vec::with_capacity(candidates.len());
    for candidate in candidates.drain(..) {
        if !deduped
            .iter()
            .any(|existing| visibility.same_logical_callable(analyzer, existing, &candidate))
        {
            deduped.push(candidate);
        }
    }
    *candidates = deduped;
}

fn resolve_callable_candidates(
    candidates: Vec<CodeUnit>,
    call_arity: Option<usize>,
    reference_byte: usize,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
) -> BareCallTargetResolution {
    let mut candidates = candidates;
    dedupe_callable_candidates(&mut candidates, analyzer, visibility);
    if candidates.is_empty() {
        return BareCallTargetResolution::Missing;
    }
    let Some(call_arity) = call_arity else {
        // An unproven argument count cannot create ambiguity where lookup found
        // exactly one name binding: there is nothing to be ambiguous between.
        // C has no overloading at all, and a lone C++ candidate is the only
        // declaration unqualified lookup reached, so arity cannot pick another
        // one (#1811). Keeping it unproven discarded the proven candidate and
        // answered `ambiguous` with an empty definition list.
        if candidates.len() == 1 {
            return BareCallTargetResolution::FreeFunctions(candidates);
        }
        return BareCallTargetResolution::UnprovenFreeFunctions(candidates);
    };
    let applicable = candidates
        .into_iter()
        .filter(|candidate| {
            visibility
                .callable_arity_at_reference(analyzer, file, candidate, reference_byte)
                .is_some_and(|arity| arity.accepts(call_arity))
        })
        .collect::<Vec<_>>();
    if applicable.is_empty() {
        BareCallTargetResolution::CallableShadow
    } else {
        BareCallTargetResolution::FreeFunctions(applicable)
    }
}

fn deduplicate_type_import_candidates(
    candidates: Vec<(CodeUnit, Vec<String>)>,
) -> Vec<(CodeUnit, Vec<String>)> {
    let mut logical = Vec::<(CodeUnit, Vec<String>)>::new();
    for candidate in candidates {
        if !logical
            .iter()
            .any(|(existing, _)| same_logical_symbol(existing, &candidate.0))
        {
            logical.push(candidate);
        }
    }
    logical
}

fn resolve_direct_type_candidates(
    candidates: Vec<(CodeUnit, Vec<String>)>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
) -> BareCallTargetResolution {
    let logical = deduplicate_type_import_candidates(candidates);
    let [(target, components)] = logical.as_slice() else {
        return if logical.is_empty() {
            BareCallTargetResolution::Missing
        } else {
            BareCallTargetResolution::Ambiguous
        };
    };
    match visibility
        .resolve_imported_type_candidate(analyzer, file, target, components, None, false)
    {
        LexicalTypeResolution::Resolved { unit, .. } => BareCallTargetResolution::Type(unit),
        LexicalTypeResolution::Ambiguous => BareCallTargetResolution::Ambiguous,
        LexicalTypeResolution::Missing => BareCallTargetResolution::Missing,
    }
}

/// Resolve a direct using-declaration in the nearest concrete block before
/// class-member lookup. A block declaration such as `using std::swap;` adds
/// that name to the block scope and hides a same-named member. If the imported
/// target is not indexed, retain its structured path as boundary evidence.
#[allow(clippy::too_many_arguments)]
pub fn resolve_block_using_call_target(
    call: Node<'_>,
    function: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
) -> Option<BlockUsingCallTargetResolution> {
    if !matches!(function.kind(), "identifier" | "template_function") {
        return None;
    }
    let name = node_text(function_terminal_node(function), source);
    if name.is_empty() {
        return None;
    }
    let bindings = effective_using_bindings_for_name(
        visibility,
        ordinary_type_imports,
        file,
        function,
        source,
        name,
    );
    let block_bindings = bindings
        .iter()
        .filter(|binding| {
            binding.namespace_scope.is_none()
                && binding.block_scope
                && matches!(binding.target, EffectiveUsingTarget::Ordinary { .. })
        })
        .collect::<Vec<_>>();
    if block_bindings.is_empty() {
        return None;
    }
    let lexical_scope =
        match enclosing_lexical_scope_components(function, analyzer, visibility, file, source) {
            LexicalScopeResolution::Resolved(scope) => scope,
            LexicalScopeResolution::Ambiguous => {
                return Some(BlockUsingCallTargetResolution::Ambiguous);
            }
            LexicalScopeResolution::Missing => return None,
        };
    let reference_guards = preprocessor_guard_environment(function, source);
    let active = block_bindings
        .into_iter()
        .filter(|binding| {
            effective_using_binding_active(
                binding,
                function,
                &lexical_scope,
                reference_guards.as_ref(),
                visibility,
                file,
            )
        })
        .collect::<Vec<_>>();
    let depth = active.iter().map(|binding| binding.scope_depth).max()?;
    let at_tier = active
        .into_iter()
        .filter(|binding| binding.scope_depth == depth)
        .collect::<Vec<_>>();
    let callable_candidates = at_tier
        .iter()
        .flat_map(|binding| {
            binding_free_function_candidates(
                binding,
                &[],
                analyzer,
                visibility,
                file,
                name,
                call.start_byte(),
            )
        })
        .collect::<Vec<_>>();
    if !callable_candidates.is_empty() {
        return Some(BlockUsingCallTargetResolution::Target(
            resolve_callable_candidates(
                callable_candidates,
                visibility.call_arity_evidence(file, call, source).exact(),
                call.start_byte(),
                analyzer,
                visibility,
                file,
            ),
        ));
    }
    let type_candidates = at_tier
        .iter()
        .flat_map(|binding| {
            binding_type_candidates(
                binding,
                &[],
                analyzer,
                visibility,
                file,
                name,
                None,
                call.start_byte(),
            )
        })
        .collect::<Vec<_>>();
    if !type_candidates.is_empty() {
        return Some(BlockUsingCallTargetResolution::Target(
            resolve_direct_type_candidates(type_candidates, analyzer, visibility, file),
        ));
    }

    let mut unindexed = Vec::new();
    for binding in at_tier {
        let Some(components) = binding.resolved_target_components.as_ref() else {
            continue;
        };
        if !unindexed.contains(components) {
            unindexed.push(components.clone());
        }
    }
    match unindexed.as_slice() {
        [target] => Some(BlockUsingCallTargetResolution::Unindexed(target.clone())),
        [] => None,
        _ => Some(BlockUsingCallTargetResolution::Ambiguous),
    }
}

#[allow(clippy::too_many_arguments)]
pub fn resolve_bare_call_target(
    call: Node<'_>,
    function: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
) -> BareCallTargetResolution {
    if !matches!(function.kind(), "identifier" | "template_function") {
        return BareCallTargetResolution::Missing;
    }
    let terminal = function_terminal_node(function);
    let name = node_text(terminal, source);
    if name.is_empty() {
        return BareCallTargetResolution::Missing;
    }
    let call_arity = visibility.call_arity_evidence(file, call, source).exact();
    let lexical_scope =
        match enclosing_lexical_scope_components(function, analyzer, visibility, file, source) {
            LexicalScopeResolution::Resolved(scope) => scope,
            LexicalScopeResolution::Ambiguous => return BareCallTargetResolution::Ambiguous,
            LexicalScopeResolution::Missing => return BareCallTargetResolution::Missing,
        };
    let type_resolution = resolve_type_node_lexically(
        function,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
    );
    let type_components = match &type_resolution {
        LexicalTypeResolution::Resolved { components, .. } => Some(components.as_slice()),
        LexicalTypeResolution::Ambiguous | LexicalTypeResolution::Missing => None,
    };
    let direct_type_resolution = visibility.resolve_type_components_lexically(
        analyzer,
        file,
        &[name.to_string()],
        false,
        &lexical_scope,
    );
    let direct_type_components = match &direct_type_resolution {
        LexicalTypeResolution::Resolved { components, .. } => Some(components.as_slice()),
        LexicalTypeResolution::Ambiguous | LexicalTypeResolution::Missing => None,
    };
    let has_explicit_template_arguments =
        cpp_template_reference_arguments(function, source).is_some();
    let bindings = effective_using_bindings_for_name(
        visibility,
        ordinary_type_imports,
        file,
        function,
        source,
        name,
    );
    // Guard ancestry climbs the whole ancestor chain and each `Node::parent`
    // step re-descends from the root (#1927): with no bindings both filters
    // below select nothing, so the environment is never consulted.
    let function_guards = if bindings.is_empty() {
        None
    } else {
        preprocessor_guard_environment(function, source)
    };
    let active_bindings = bindings
        .iter()
        .filter(|binding| {
            effective_using_binding_active(
                binding,
                function,
                &lexical_scope,
                function_guards.as_ref(),
                visibility,
                file,
            )
        })
        .collect::<Vec<_>>();
    let transitive_bindings = bindings
        .iter()
        .filter(|binding| {
            effective_using_binding_guards_active(
                binding,
                function.start_byte(),
                function_guards.as_ref(),
                visibility,
                file,
            ) && (binding.namespace_scope.is_some()
                || (binding.scope_start <= function.start_byte()
                    && function.end_byte() <= binding.scope_end))
        })
        .collect::<Vec<_>>();
    let mut concrete_depths = active_bindings
        .iter()
        .filter(|binding| binding.namespace_scope.is_none())
        .map(|binding| binding.scope_depth)
        .collect::<Vec<_>>();
    concrete_depths.sort_unstable();
    concrete_depths.dedup();
    for depth in concrete_depths.into_iter().rev() {
        let at_tier = active_bindings
            .iter()
            .copied()
            .filter(|binding| binding.namespace_scope.is_none() && binding.scope_depth == depth);
        let direct = at_tier
            .clone()
            .filter(|binding| matches!(binding.target, EffectiveUsingTarget::Ordinary { .. }))
            .flat_map(|binding| {
                binding_free_function_candidates(
                    binding,
                    &transitive_bindings,
                    analyzer,
                    visibility,
                    file,
                    name,
                    call.start_byte(),
                )
            })
            .collect::<Vec<_>>();
        if !direct.is_empty() {
            return resolve_callable_candidates(
                direct,
                call_arity,
                call.start_byte(),
                analyzer,
                visibility,
                file,
            );
        }
        let direct_types = at_tier
            .clone()
            .filter(|binding| matches!(binding.target, EffectiveUsingTarget::Ordinary { .. }))
            .flat_map(|binding| {
                binding_type_candidates(
                    binding,
                    &transitive_bindings,
                    analyzer,
                    visibility,
                    file,
                    name,
                    None,
                    call.start_byte(),
                )
            })
            .collect::<Vec<_>>();
        if !direct_types.is_empty() {
            // `resolve_direct_type_candidates` never consults the argument
            // count: it answers the one type the name binds to, or reports the
            // competing types. An unknown count therefore cannot make this
            // ambiguous (#1812).
            return resolve_direct_type_candidates(direct_types, analyzer, visibility, file);
        }
        let directives = at_tier
            .filter(|binding| matches!(binding.target, EffectiveUsingTarget::Namespace { .. }))
            .flat_map(|binding| {
                binding_free_function_candidates(
                    binding,
                    &transitive_bindings,
                    analyzer,
                    visibility,
                    file,
                    name,
                    call.start_byte(),
                )
            })
            .collect::<Vec<_>>();
        if !directives.is_empty() {
            return resolve_callable_candidates(
                directives,
                call_arity,
                call.start_byte(),
                analyzer,
                visibility,
                file,
            );
        }
    }
    for prefix_len in (0..=lexical_scope.len()).rev() {
        let mut qualified = lexical_scope[..prefix_len].to_vec();
        qualified.push(name.to_string());
        let same_name_resolves_to_type = direct_type_components
            .is_some_and(|components| components == qualified.as_slice())
            || type_components.is_some_and(|components| components == qualified.as_slice());
        let mut direct = visibility
            .visible_identifier_candidates(file, name)
            .filter(|candidate| {
                candidate.is_function()
                    && type_owner_of(analyzer, candidate).is_none()
                    && !(same_name_resolves_to_type
                        && (visibility.callable_is_constructor_declaration(analyzer, candidate)
                            || has_explicit_template_arguments
                                && visibility
                                    .callable_is_deduction_guide_declaration(analyzer, candidate)))
                    && cpp_name_for(candidate) == qualified.join("::")
                    && if analyzer.reference_uses_c_semantics(file) {
                        visibility.declaration_visible_for_c_forward_call(
                            analyzer,
                            file,
                            candidate,
                            call.start_byte(),
                        )
                    } else {
                        visibility.declaration_visible_at(
                            analyzer,
                            file,
                            candidate,
                            call.start_byte(),
                        )
                    }
            })
            .cloned()
            .collect::<Vec<_>>();
        let at_tier = active_bindings.iter().copied().filter(|binding| {
            binding.namespace_scope.as_deref() == Some(&lexical_scope[..prefix_len])
        });
        direct.extend(
            at_tier
                .clone()
                .filter(|binding| matches!(binding.target, EffectiveUsingTarget::Ordinary { .. }))
                .flat_map(|binding| {
                    binding_free_function_candidates(
                        binding,
                        &transitive_bindings,
                        analyzer,
                        visibility,
                        file,
                        name,
                        call.start_byte(),
                    )
                }),
        );
        if !direct.is_empty() {
            return resolve_callable_candidates(
                direct,
                call_arity,
                call.start_byte(),
                analyzer,
                visibility,
                file,
            );
        }
        let mut direct_types = at_tier
            .clone()
            .filter(|binding| matches!(binding.target, EffectiveUsingTarget::Ordinary { .. }))
            .flat_map(|binding| {
                binding_type_candidates(
                    binding,
                    &transitive_bindings,
                    analyzer,
                    visibility,
                    file,
                    name,
                    None,
                    call.start_byte(),
                )
            })
            .collect::<Vec<_>>();
        if direct_type_components.is_some_and(|components| components == qualified.as_slice())
            && let LexicalTypeResolution::Resolved {
                unit, components, ..
            } = &direct_type_resolution
        {
            direct_types.push((unit.clone(), components.clone()));
        }
        if !direct_types.is_empty() {
            // `resolve_direct_type_candidates` never consults the argument
            // count: it answers the one type the name binds to, or reports the
            // competing types. An unknown count therefore cannot make this
            // ambiguous (#1812).
            return resolve_direct_type_candidates(direct_types, analyzer, visibility, file);
        }
        let directives = at_tier
            .filter(|binding| matches!(binding.target, EffectiveUsingTarget::Namespace { .. }))
            .flat_map(|binding| {
                binding_free_function_candidates(
                    binding,
                    &transitive_bindings,
                    analyzer,
                    visibility,
                    file,
                    name,
                    call.start_byte(),
                )
            })
            .collect::<Vec<_>>();
        if !directives.is_empty() {
            return resolve_callable_candidates(
                directives,
                call_arity,
                call.start_byte(),
                analyzer,
                visibility,
                file,
            );
        }
        if type_components.is_some_and(|components| components == qualified.as_slice()) {
            // The lexical type resolution below already answers with the single
            // type, or with its own ambiguity verdict; the argument count adds
            // nothing to that decision (#1812).
            return match type_resolution {
                LexicalTypeResolution::Resolved { unit, .. } => {
                    BareCallTargetResolution::Type(unit)
                }
                LexicalTypeResolution::Ambiguous => BareCallTargetResolution::Ambiguous,
                LexicalTypeResolution::Missing => BareCallTargetResolution::Missing,
            };
        }
    }
    // Every lookup tier is exhausted: no callable and no type candidate was
    // found. Reporting that as `Ambiguous` claimed an ambiguity between nothing
    // at all, and its early return in get_definition preempted the same-file
    // macro fallback - so a call to a macro defined in the referencing file
    // (libyang's `RBN_RIGHT`, glpk's `#define error dmx_error`) could never
    // resolve once an unresolvable include made the argument count unknown.
    // A no-candidate outcome is Missing, which is what makes the fallback
    // reachable (#1812).
    match type_resolution {
        LexicalTypeResolution::Resolved { unit, .. } => BareCallTargetResolution::Type(unit),
        LexicalTypeResolution::Ambiguous => BareCallTargetResolution::Ambiguous,
        LexicalTypeResolution::Missing => BareCallTargetResolution::Missing,
    }
}

fn static_qualifier_type_scopes<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Vec<Node<'tree>>> {
    if !matches!(
        node.kind(),
        "qualified_identifier" | "scoped_type_identifier"
    ) {
        return None;
    }
    // `maybe_record_type_hit` rejects nested type nodes before this helper, so
    // this root contains every structured component needed for prefix lookup.
    debug_assert!(!is_nested_type_node(node));
    let qualified = qualified_owner_components(node, ctx.source)?;
    static_qualifier_type_scopes_for_components(node, qualified, ctx)
}

fn static_qualifier_type_scopes_for_components<'tree>(
    node: Node<'tree>,
    qualified: QualifiedOwnerComponents<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Vec<Node<'tree>>> {
    if !qualified.global
        && let Some(name) = qualified.names.first()
        && let Some(alias_type) = local_receiver_alias_type_node(node, name, ctx)
    {
        return match resolve_receiver_type_node(alias_type, ctx) {
            Ok(Some(owner)) if same_visible_symbol(&owner, &ctx.spec.target) => {
                Some(vec![qualified.nodes[0]])
            }
            _ => None,
        };
    }
    let mut matches = Vec::new();
    let mut inherited_injected_name_is_shadowed = false;
    for component_count in 1..=qualified.names.len() {
        let resolution = resolve_type_components_lexically_at_for_target_with_scope_cache(
            node,
            &qualified.names[..component_count],
            qualified.global,
            &ctx.analyzer,
            ctx.visibility,
            &ctx.ordinary_type_imports,
            ctx.file,
            ctx.source,
            &ctx.spec.target,
            false,
            Some(&ctx.lexical_scope_cache),
        );
        match resolution {
            LexicalTypeResolution::Resolved {
                unit, candidates, ..
            } if (!ctx
                .analyzer
                .type_alias_provider()
                .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target))
                || ctx.visibility.external_type_candidate_visible_in_context(
                    &ctx.analyzer,
                    ctx.file,
                    &ctx.spec.target,
                    node,
                ))
                && (same_visible_symbol(&unit, &ctx.spec.target)
                    || candidates
                        .iter()
                        .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target)))
                && target_alias_candidates_visible(&candidates, node, ctx) =>
            {
                let matched =
                    qualified_type_component_hit_node(qualified.nodes[component_count - 1], node);
                if !template_type_component_preserves_target(matched, &candidates, ctx) {
                    continue;
                }
                if !matches.iter().any(|existing: &Node<'_>| {
                    existing.start_byte() == matched.start_byte()
                        && existing.end_byte() == matched.end_byte()
                }) {
                    matches.push(matched);
                }
            }
            // The ordinary lexical resolver can remain ambiguous when the
            // qualified terminal is an alias whose canonical target is not
            // indexed (for example, `Hash::Digest` aliases an external
            // `std::array`). The target-guided path below still requires one
            // physically visible logical class for every emitted prefix.
            LexicalTypeResolution::Ambiguous => {
                return (!inherited_injected_name_is_shadowed)
                    .then(|| inherited_injected_class_qualifier_scope(node, ctx))
                    .flatten()
                    .map(|scope| vec![scope])
                    .or_else(|| target_guided_qualifier_type_scopes(node, ctx));
            }
            LexicalTypeResolution::Resolved { .. } => {
                if let Some(matched) =
                    target_guided_nested_alias_type_scope(node, &qualified, component_count, ctx)
                {
                    matches.push(matched);
                }
                inherited_injected_name_is_shadowed |= component_count == 1;
            }
            LexicalTypeResolution::Missing => {
                if let Some(matched) =
                    target_guided_nested_alias_type_scope(node, &qualified, component_count, ctx)
                {
                    matches.push(matched);
                }
            }
        }
    }
    if matches.is_empty() {
        (!inherited_injected_name_is_shadowed)
            .then(|| inherited_injected_class_qualifier_scope(node, ctx))
            .flatten()
            .map(|scope| vec![scope])
            .or_else(|| target_guided_qualifier_type_scopes(node, ctx))
    } else {
        Some(matches)
    }
}

/// Recover a class owner in a qualified expression when guard-aware lookup
/// cannot prove the owner. Keep the hit on the owner component, not the member.
enum TargetGuidedQualifiedValueOwnerHit<'tree> {
    Proven(Node<'tree>),
    Unproven(Node<'tree>),
}

fn target_guided_qualified_value_owner_hit<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<TargetGuidedQualifiedValueOwnerHit<'tree>> {
    let target = physically_visible_type_target(ctx)?;
    if !target.is_class() {
        return None;
    }
    let qualified = qualified_owner_components(node, ctx.source)?;
    let lexical_scope = match enclosing_lexical_scope_components(
        node,
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        ctx.source,
    ) {
        LexicalScopeResolution::Resolved(scope) => scope,
        LexicalScopeResolution::Ambiguous | LexicalScopeResolution::Missing => {
            enclosing_namespace_components(node, ctx.source)
        }
    };
    let LexicalTypeResolution::Resolved {
        unit, candidates, ..
    } = ctx.visibility.resolve_type_components_lexically_for_target(
        &ctx.analyzer,
        ctx.file,
        &qualified.names,
        qualified.global,
        &lexical_scope,
        target,
    )
    else {
        return None;
    };
    let scope = qualified.nodes.last().copied()?;
    // Lexical component lookup does not consider source order, so it can
    // select a declaration that follows the reference. The forward selection
    // proves the owner only when that declaration is visible at the reference.
    let forward_uniquely_selects_target = match ctx
        .visibility
        .resolve_type_components_lexically_for_forward(
            &ctx.analyzer,
            ctx.file,
            &qualified.names,
            qualified.global,
            &lexical_scope,
        ) {
        LexicalTypeResolution::Resolved {
            unit, candidates, ..
        } if candidates.len() == 1 => {
            same_visible_symbol(&canonical_alias_target(&unit, ctx), target)
                && same_visible_symbol(&canonical_alias_target(&candidates[0], ctx), target)
                && ctx.visibility.external_type_candidate_visible_in_context(
                    &ctx.analyzer,
                    ctx.file,
                    &candidates[0],
                    scope,
                )
        }
        LexicalTypeResolution::Resolved { .. }
        | LexicalTypeResolution::Ambiguous
        | LexicalTypeResolution::Missing => false,
    };
    if forward_uniquely_selects_target
        || (same_visible_symbol(&unit, target)
            && !candidates.is_empty()
            && candidates
                .iter()
                .all(|candidate| same_visible_symbol(candidate, target)))
    {
        Some(TargetGuidedQualifiedValueOwnerHit::Proven(scope))
    } else if candidates
        .iter()
        .any(|candidate| same_visible_symbol(candidate, target))
    {
        Some(TargetGuidedQualifiedValueOwnerHit::Unproven(scope))
    } else {
        None
    }
}

/// Resolve a nested class-owned alias when the indexed alias path is not a
/// standalone type candidate. The C++ index stores `basic_json::type_error`
/// as a synthetic child of `basic_json`, while source can qualify it through
/// a class alias such as `json::type_error`. Resolve the owner prefix first,
/// then canonicalize the structured member alias against the requested type.
fn target_guided_nested_alias_type_scope<'tree>(
    node: Node<'tree>,
    qualified: &QualifiedOwnerComponents<'tree>,
    component_count: usize,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if component_count < 2 {
        return None;
    }
    let (owner_components, member_name) =
        qualified.names[..component_count].split_at(component_count - 1);
    let LexicalTypeResolution::Resolved { unit: owner, .. } = resolve_type_components_lexically_at(
        node,
        owner_components,
        qualified.global,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
    ) else {
        return None;
    };
    let member_name = member_name.first()?;
    let alias_provider = ctx.analyzer.type_alias_provider()?;
    ctx.visibility
        .visible_members_for_owner_name(ctx.file, &owner, member_name)
        .into_iter()
        .filter(|member| alias_provider.is_type_alias(member))
        .find(|member| {
            let member_visible = ctx.visibility.external_type_candidate_visible_in_context(
                &ctx.analyzer,
                ctx.file,
                member,
                node,
            ) || ctx
                .visibility
                .external_type_candidate_guard_compatible_in_context(
                    &ctx.analyzer,
                    ctx.file,
                    member,
                    node,
                );
            if !member_visible {
                return false;
            }
            same_visible_symbol(member, &ctx.spec.target)
                || same_visible_symbol(&canonical_alias_target(member, ctx), &ctx.spec.target)
        })
        .map(|_| qualified_type_component_hit_node(qualified.nodes[component_count - 1], node))
}

fn canonical_alias_target(candidate: &CodeUnit, ctx: &ScanCtx<'_>) -> CodeUnit {
    if ctx.visibility.structured_class_alias_resolves_to_target(
        &ctx.analyzer,
        ctx.file,
        candidate,
        &ctx.spec.target,
    ) {
        return ctx.spec.target.clone();
    }
    let structured = ctx
        .visibility
        .canonical_type_unit(&ctx.analyzer, ctx.file, candidate);
    structured.unwrap_or_else(|| candidate.clone())
}

/// Preserve the alias component of a qualified reference when the alias target
/// is a dependent nested type and forward lookup retains its primary template
/// as the bounded identity.
fn class_alias_guard_compatible(candidate: &CodeUnit, node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    ctx.visibility
        .external_type_candidate_guard_compatible_in_context(
            &ctx.analyzer,
            ctx.file,
            candidate,
            node,
        )
}

fn visible_class_alias_candidate(candidate: &CodeUnit, node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    ctx.visibility.is_physically_visible(ctx.file, candidate)
        && class_alias_guard_compatible(candidate, node, ctx)
}

fn class_alias_path_preserves_target(
    candidate: &CodeUnit,
    target: &CodeUnit,
    ctx: &ScanCtx<'_>,
) -> bool {
    ctx.visibility.structured_class_alias_path_preserves_target(
        &ctx.analyzer,
        ctx.file,
        candidate,
        target,
    )
}

fn target_guided_dependent_alias_qualifier_scope<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if !matches!(
        node.kind(),
        "qualified_identifier" | "scoped_type_identifier"
    ) {
        return None;
    }
    let target = physically_visible_type_target(ctx)?;
    let alias_provider = ctx.analyzer.type_alias_provider()?;
    if !target.is_class() || alias_provider.is_type_alias(target) {
        return None;
    }
    let nodes = cpp_name_component_nodes(node)?;
    let names = nodes
        .iter()
        .map(|component| node_text(*component, ctx.source).to_string())
        .collect::<Vec<_>>();
    let global = is_globally_qualified_cpp_name(node);
    let lexical_scope = match enclosing_lexical_scope_components(
        node,
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        ctx.source,
    ) {
        LexicalScopeResolution::Resolved(scope) => scope,
        LexicalScopeResolution::Ambiguous | LexicalScopeResolution::Missing => {
            enclosing_namespace_components(node, ctx.source)
        }
    };
    for component_count in 1..=names.len() {
        let components = &names[..component_count];
        let name = components.last()?;
        let candidates = ctx
            .visibility
            .visible_identifier_candidates(ctx.file, name)
            .filter(|candidate| alias_provider.is_type_alias(candidate))
            .filter(|candidate| visible_class_alias_candidate(candidate, node, ctx))
            .filter(|candidate| {
                let candidate_components = canonical_cpp_scope_components(candidate);
                lexical_component_tiers(components, global, &lexical_scope)
                    .any(|tier| tier == candidate_components)
                    || (component_count == 1
                        && member_alias_owner_matches_reference_for(
                            candidate,
                            nodes[component_count - 1],
                            ctx,
                        ))
            })
            .filter(|candidate| class_alias_path_preserves_target(candidate, target, ctx));
        let mut aliases: Vec<&CodeUnit> = Vec::new();
        for candidate in candidates {
            if !aliases
                .iter()
                .any(|existing| same_logical_symbol(existing, candidate))
            {
                aliases.push(candidate);
            }
        }
        if aliases.len() == 1 {
            return nodes.get(component_count - 1).copied();
        }
        if aliases.len() > 1 {
            return None;
        }
    }
    None
}

/// Preserve an unqualified class-owned alias when its dependent target path
/// retains the requested primary template as the bounded forward identity.
fn target_guided_dependent_class_alias_leaf<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if node.kind() != "type_identifier"
        || is_declaration_name(node)
        || local_type_name_shadows(node, ctx)
    {
        return None;
    }
    let target = physically_visible_type_target(ctx)?;
    let alias_provider = ctx.analyzer.type_alias_provider()?;
    if !target.is_class() || alias_provider.is_type_alias(target) {
        return None;
    }
    let name = node_text(node, ctx.source);
    let aliases = ctx
        .visibility
        .visible_identifier_candidates(ctx.file, name)
        .filter(|candidate| alias_provider.is_type_alias(candidate))
        .filter(|candidate| member_alias_owner_matches_reference_for(candidate, node, ctx))
        .filter(|candidate| visible_class_alias_candidate(candidate, node, ctx))
        .filter(|candidate| class_alias_path_preserves_target(candidate, target, ctx))
        .collect::<Vec<_>>();
    matches!(aliases.as_slice(), [_]).then_some(node)
}

/// Recover a namespace alias whose guard state blocks ordinary visibility.
/// Require one visible canonical target and an exact structured alias path.
fn target_guided_unproven_alias_type_reference<'tree>(
    node: Node<'tree>,
    candidates: &[CodeUnit],
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    let template_arguments = cpp_template_reference_arguments(node, ctx.source);
    let target = physically_visible_type_target(ctx)?;
    if !target.is_class() {
        return None;
    }
    let alias_provider = ctx.analyzer.type_alias_provider()?;
    let (components, _) = type_reference_components(node, ctx.source)?;
    let hit = template_arguments
        .as_ref()
        .and_then(|_| template_reference_name_node(node))
        .map(function_terminal_node)
        .unwrap_or_else(|| function_terminal_node(node));
    candidates
        .iter()
        .filter(|candidate| {
            alias_provider.is_type_alias(candidate)
                && ctx.visibility.is_physically_visible(ctx.file, candidate)
                && canonical_cpp_scope_components(candidate) == components
        })
        .find(|candidate| {
            template_arguments.as_ref().map_or_else(
                || {
                    same_visible_symbol(&canonical_alias_target(candidate, ctx), target)
                        || ctx.visibility.structured_alias_primary_preserves_target(
                            &ctx.analyzer,
                            ctx.file,
                            candidate,
                            target,
                        )
                },
                |arguments| {
                    ctx.visibility.template_alias_arguments_preserve_target(
                        &ctx.analyzer,
                        ctx.file,
                        candidate,
                        arguments,
                        target,
                    )
                },
            )
        })
        .map(|_| hit)
}

fn target_alias_candidates_visible(
    candidates: &[CodeUnit],
    reference: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> bool {
    let Some(alias_provider) = ctx.analyzer.type_alias_provider() else {
        return true;
    };
    if candidates.iter().any(|candidate| {
        !alias_provider.is_type_alias(candidate)
            && ctx.visibility.same_template_member_identity(
                &ctx.analyzer,
                candidate,
                &ctx.spec.target,
            )
    }) {
        return true;
    }
    let target_aliases = candidates
        .iter()
        .filter(|candidate| {
            alias_provider.is_type_alias(candidate)
                && same_visible_symbol(&canonical_alias_target(candidate, ctx), &ctx.spec.target)
        })
        .collect::<Vec<_>>();
    target_aliases.is_empty()
        || target_aliases
            .iter()
            .any(|candidate| type_candidate_visible_at_reference(candidate, reference, ctx))
}

fn type_candidate_visible_at_reference(
    candidate: &CodeUnit,
    reference: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> bool {
    let class_owned_alias = ctx
        .analyzer
        .type_alias_provider()
        .is_some_and(|provider| provider.is_type_alias(candidate))
        && ctx
            .analyzer
            .parent_of(candidate)
            .is_some_and(|owner| owner.is_class());
    if class_owned_alias {
        let conditional_family = ctx
            .visibility
            .is_exhaustive_same_fqn_type_declaration_family(&ctx.analyzer, ctx.file, candidate);
        let owner_match = qualified_reference_selects_type_candidate(candidate, reference, ctx)
            || unqualified_reference_selects_inherited_alias(candidate, reference, ctx)
            || member_alias_owner_matches_reference_for(candidate, reference, ctx);
        let guard_match = ctx
            .visibility
            .external_type_candidate_guard_compatible_in_context(
                &ctx.analyzer,
                ctx.file,
                candidate,
                reference,
            );
        let general_match = conditional_family
            && ctx.visibility.external_type_candidate_visible_in_context(
                &ctx.analyzer,
                ctx.file,
                candidate,
                reference,
            );
        return owner_match && (guard_match || general_match);
    }
    ctx.visibility.external_type_candidate_visible_in_context(
        &ctx.analyzer,
        ctx.file,
        candidate,
        reference,
    )
}

fn unqualified_reference_selects_inherited_alias(
    candidate: &CodeUnit,
    reference: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> bool {
    let Some((components, global)) = type_reference_components(reference, ctx.source) else {
        return false;
    };
    if global || components.len() != 1 {
        return false;
    }
    matches!(
        resolve_type_node_lexically_for_target(
            reference,
            &ctx.analyzer,
            ctx.visibility,
            &ctx.ordinary_type_imports,
            ctx.file,
            ctx.source,
            candidate,
            Some(&ctx.lexical_scope_cache),
            ctx.recovered_sentinel_scope(reference).as_deref(),
        ),
        LexicalTypeResolution::Resolved {
            ref unit,
            ref candidates,
            ..
        } if ctx
            .visibility
            .same_template_member_identity(&ctx.analyzer, unit, candidate)
            || candidates.iter().any(|resolved| {
                ctx.visibility.same_template_member_identity(
                    &ctx.analyzer,
                    resolved,
                    candidate,
                )
            })
    )
}

fn qualified_reference_selects_type_candidate(
    candidate: &CodeUnit,
    reference: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> bool {
    let Some((components, global)) = type_reference_components(reference, ctx.source) else {
        return false;
    };
    if components.len() < 2 {
        return false;
    }
    let candidate_components = canonical_cpp_scope_components(candidate);
    let lexical_scope = ctx.recovered_sentinel_scope(reference).unwrap_or_else(|| {
        match enclosing_lexical_scope_components(
            reference,
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            ctx.source,
        ) {
            LexicalScopeResolution::Resolved(scope) => scope,
            LexicalScopeResolution::Ambiguous | LexicalScopeResolution::Missing => {
                enclosing_namespace_components(reference, ctx.source)
            }
        }
    });
    lexical_component_tiers(&components, global, &lexical_scope)
        .any(|qualified| qualified == candidate_components)
}

fn qualified_type_component_hit_node<'tree>(
    component: Node<'tree>,
    qualified: Node<'tree>,
) -> Node<'tree> {
    let mut current = component;
    while let Some(parent) = current.parent() {
        let is_type_name = matches!(
            parent.kind(),
            "template_type"
                | "qualified_identifier"
                | "scoped_identifier"
                | "scoped_type_identifier"
        ) && parent
            .child_by_field_name("name")
            .is_some_and(|name| same_node(name, current));
        if !is_type_name {
            break;
        }
        current = parent;
        if same_node(parent, qualified) {
            break;
        }
    }
    current
}

fn template_type_component_preserves_target(
    node: Node<'_>,
    candidates: &[CodeUnit],
    ctx: &ScanCtx<'_>,
) -> bool {
    template_reference_candidates_select_target(
        node,
        candidates,
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        ctx.source,
        &ctx.spec.target,
    )
}

fn template_reference_candidates_select_target(
    node: Node<'_>,
    candidates: &[CodeUnit],
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    source: &str,
    target: &CodeUnit,
) -> bool {
    let Some(arguments) = cpp_template_reference_arguments(node, source) else {
        return !visibility.is_template_specialization(target);
    };
    let direct_template_name =
        template_reference_name_node(node).map(|name| node_text(name, source));
    let named_alias_selects_target = direct_template_name.is_some_and(|name| {
        analyzer.type_alias_provider().is_some_and(|provider| {
            visibility
                .visible_identifier_candidates(file, name)
                .filter(|candidate| provider.is_type_alias(candidate))
                .any(|candidate| {
                    visibility.template_alias_arguments_preserve_target(
                        analyzer, file, candidate, &arguments, target,
                    )
                })
        })
    });
    named_alias_selects_target
        || candidates.iter().any(|candidate| {
            (same_visible_symbol(candidate, target)
                && visibility.is_primary_template(target)
                && direct_template_name == Some(candidate.identifier()))
                || visibility.template_alias_arguments_preserve_target(
                    analyzer, file, candidate, &arguments, target,
                )
                || visibility
                    .resolve_template_arguments(file, candidate.clone(), &arguments)
                    .is_ok_and(|resolved| same_visible_symbol(&resolved, target))
        })
}

fn template_reference_name_node(node: Node<'_>) -> Option<Node<'_>> {
    let template = if node.kind() == "template_type" {
        node
    } else {
        node.child_by_field_name("name")
            .filter(|name| name.kind() == "template_type")?
    };
    template.child_by_field_name("name")
}

fn type_resolution_matches_target(
    node: Node<'_>,
    unit: &CodeUnit,
    candidates: &[CodeUnit],
    ctx: &ScanCtx<'_>,
) -> bool {
    type_resolution_matches_unit_target(node, unit, candidates, &ctx.spec.target, ctx)
}

fn type_resolution_matches_unit_target(
    node: Node<'_>,
    unit: &CodeUnit,
    candidates: &[CodeUnit],
    target: &CodeUnit,
    ctx: &ScanCtx<'_>,
) -> bool {
    target_alias_candidates_visible(candidates, node, ctx)
        && type_resolution_identifies_unit_target(node, unit, candidates, target, ctx)
}

/// The identity half of the type-resolution match, without the alias
/// visibility gate.
///
/// Use it only on the without-visibility fallback path, which reports an
/// unproven hit. An alias spelling does not contain the target identifier, so
/// the name-mention fallback can never recover a rejected alias reference: the
/// site would disappear instead of degrading to a reviewable hit.
fn type_resolution_identifies_unit_target(
    node: Node<'_>,
    unit: &CodeUnit,
    candidates: &[CodeUnit],
    target: &CodeUnit,
    ctx: &ScanCtx<'_>,
) -> bool {
    if !template_alias_owner_matches_reference(node, target, ctx) {
        return false;
    }
    if ctx.visibility.is_template_specialization(target)
        && cpp_template_reference_arguments(node, ctx.source).is_some()
    {
        let selected_unit =
            cpp_template_reference_arguments(node, ctx.source).and_then(|arguments| {
                ctx.visibility
                    .resolve_template_arguments(ctx.file, unit.clone(), &arguments)
                    .ok()
            });
        return selected_unit
            .as_ref()
            .is_some_and(|selected| same_visible_symbol(selected, target))
            || template_reference_candidates_select_target(
                node,
                candidates,
                &ctx.analyzer,
                ctx.visibility,
                ctx.file,
                ctx.source,
                target,
            );
    }
    unit == target
        || ctx
            .visibility
            .same_template_member_identity(&ctx.analyzer, unit, target)
        || ctx.visibility.c_tag_declaration_family_matches_target(
            &ctx.analyzer,
            ctx.file,
            &candidates.iter().collect::<Vec<_>>(),
            target,
        )
        || ctx.visibility.structured_class_alias_resolves_to_target(
            &ctx.analyzer,
            ctx.file,
            unit,
            target,
        )
        || candidates.iter().any(|candidate| {
            ctx.visibility
                .same_template_member_identity(&ctx.analyzer, candidate, target)
                || ctx.visibility.structured_class_alias_resolves_to_target(
                    &ctx.analyzer,
                    ctx.file,
                    candidate,
                    target,
                )
        })
}

/// Keep a member alias attached to the class specialization that declares it.
/// A target-guided lexical lookup can otherwise retain the primary alias when
/// the source reference is inside a partial specialization with the same
/// unqualified alias name. Compare the indexed template identities instead of
/// rendered text or suffixes.
fn template_alias_owner_matches_reference(
    node: Node<'_>,
    target: &CodeUnit,
    ctx: &ScanCtx<'_>,
) -> bool {
    if !ctx
        .analyzer
        .type_alias_provider()
        .is_some_and(|provider| provider.is_type_alias(target))
    {
        return true;
    }
    let Some(target_owner) = ctx.analyzer.parent_of(target) else {
        return true;
    };
    if !target_owner.is_class() {
        return true;
    }
    let Some(reference_owner) = structured_enclosing_owner(node, ctx) else {
        return true;
    };
    if !ctx.visibility.is_template_specialization(&target_owner)
        && !ctx.visibility.is_template_specialization(&reference_owner)
    {
        return true;
    }
    same_visible_symbol(&target_owner, &reference_owner)
}

fn inherited_injected_class_qualifier_scope<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    let qualified = qualified_owner_components(node, ctx.source)?;
    if qualified.global || qualified.names.is_empty() {
        return None;
    }
    let injected_name = &qualified.names[0];
    if !ctx.spec.target.is_class()
        || ctx.spec.target.identifier() != injected_name
        || physically_visible_type_target(ctx).is_none()
    {
        return None;
    }
    let enclosing_owner = structured_enclosing_owner(node, ctx)?;
    let owner = ctx.visibility.inherited_injected_class_owner(
        &ctx.analyzer,
        ctx.file,
        &enclosing_owner,
        injected_name,
    )?;
    same_visible_symbol(&owner, &ctx.spec.target)
        .then(|| qualified.nodes.first().copied())
        .flatten()
}

/// Resolve each qualified type component against the inverse target while
/// preserving C++ lexical-tier precedence and structured alias identity.
fn target_guided_qualifier_type_scopes<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Vec<Node<'tree>>> {
    if !matches!(
        node.kind(),
        "qualified_identifier" | "scoped_type_identifier"
    ) {
        return None;
    }
    let target = physically_visible_type_target(ctx)?;
    let qualified = qualified_owner_components(node, ctx.source)?;
    if !qualified.global
        && qualified
            .names
            .first()
            .is_some_and(|name| local_receiver_alias_type_node(node, name, ctx).is_some())
    {
        return static_qualifier_type_scopes_for_components(node, qualified, ctx);
    }
    // Prefer the C++ lexical tier that exactly matches a candidate's indexed
    // scope before falling back to suffix recovery.  A short unqualified
    // owner can have a same-spelled class in a nested namespace (for example
    // `ThreadDetails` and `Ui::ThreadDetails`).  Suffix-only matching treats
    // both as possible owners and then fails closed, even though the
    // translation unit's lexical scope selects the global class.  Keep the
    // suffix path for malformed namespace sentinels, where the parser does
    // not expose every indexed scope component.
    let lexical_scope = match enclosing_lexical_scope_components(
        node,
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        ctx.source,
    ) {
        LexicalScopeResolution::Resolved(scope) => scope,
        LexicalScopeResolution::Ambiguous | LexicalScopeResolution::Missing => {
            enclosing_namespace_components(node, ctx.source)
        }
    };
    let indexed_owner_scope =
        indexed_enclosing_owner_scope(&ctx.analyzer, ctx.visibility, ctx.file, node);
    let recovered_owner_scope = ctx.recovered_sentinel_scope(node);
    let mut matches = Vec::new();
    for component_count in 1..=qualified.names.len() {
        let components = &qualified.names[..component_count];
        let lexical_tiers = lexical_component_tiers(components, qualified.global, &lexical_scope)
            .collect::<Vec<_>>();
        let name = components.last()?;
        let mut candidates = Vec::new();
        let mut exact_candidates = Vec::new();
        for candidate in ctx
            .visibility
            .visible_identifier_candidates(ctx.file, name)
            .filter(|candidate| candidate.is_class())
            .filter(|candidate| type_candidate_visible_at_reference(candidate, node, ctx))
        {
            let candidate_components = brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
                brokk_bifrost_core::analyzer::Language::Cpp,
                &cpp_name_for(candidate),
            );
            if !candidate_components.ends_with(components)
                || candidates
                    .iter()
                    .any(|existing| same_logical_symbol(existing, candidate))
            {
                continue;
            }
            let exact_lexical_scope = lexical_tiers
                .iter()
                .any(|expected| expected == &candidate_components);
            let candidate_owner = &candidate_components[..candidate_components.len() - 1];
            let structured_owner_match = indexed_owner_scope
                .as_ref()
                .is_some_and(|owner| owner.starts_with(candidate_owner))
                || recovered_owner_scope
                    .as_ref()
                    .is_some_and(|owner| owner.starts_with(candidate_owner));
            let class_alias_owner_match = ctx
                .analyzer
                .type_alias_provider()
                .is_some_and(|provider| provider.is_type_alias(candidate))
                && member_alias_owner_matches_reference_for(candidate, node, ctx);
            let macro_namespace_owner_match = is_declaration_name(node)
                && macro_namespace_scope_matches(candidate_owner, node, ctx);
            if qualified.global && !exact_lexical_scope {
                continue;
            }
            if components.len() == 1
                && candidate_components != components
                && !exact_lexical_scope
                && !structured_owner_match
                && !class_alias_owner_match
                && !macro_namespace_owner_match
            {
                continue;
            }
            candidates.push(candidate.clone());
            if exact_lexical_scope {
                exact_candidates.push(candidate.clone());
            }
        }
        if !exact_candidates.is_empty() {
            candidates = exact_candidates;
        }
        // A typedef spelling can qualify nested C++ members while forward
        // lookup canonicalizes that spelling to its underlying class. Preserve
        // the exact alias prefix only when structured alias resolution proves
        // that it denotes this inverse target.
        let canonical_alias_target_matches = matches!(
            candidates.as_slice(),
            [candidate]
                if ctx
                    .analyzer
                    .type_alias_provider()
                    .is_some_and(|provider| provider.is_type_alias(candidate))
                    && type_candidate_visible_at_reference(candidate, node, ctx)
                    && same_visible_symbol(&canonical_alias_target(candidate, ctx), target)
                    && (brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
                        brokk_bifrost_core::analyzer::Language::Cpp,
                        &cpp_name_for(candidate),
                    ) == components
                        || member_alias_owner_matches_reference_for(candidate, node, ctx))
        );
        let direct_alias_target = ctx
            .analyzer
            .type_alias_provider()
            .is_some_and(|provider| provider.is_type_alias(target))
            && candidates
                .iter()
                .any(|candidate| same_symbol(candidate, target));
        let unique_target = matches!(
            candidates.as_slice(),
            [candidate] if same_visible_symbol(candidate, target)
        );
        if direct_alias_target || unique_target || canonical_alias_target_matches {
            let matched = if ctx
                .analyzer
                .type_alias_provider()
                .is_some_and(|provider| provider.is_type_alias(target))
                && ctx
                    .analyzer
                    .parent_of(target)
                    .is_some_and(|owner| owner.is_class())
                && ctx
                    .visibility
                    .is_exhaustive_same_fqn_type_declaration_family(&ctx.analyzer, ctx.file, target)
                && !class_owned_alias_has_distinct_visible_sibling(target, ctx)
            {
                // The alias declaration owns the terminal component. Keep
                // the inverse range narrow so `MathLib::bigint` records the
                // `bigint` token, not the complete qualified owner path.
                qualified.nodes[component_count - 1]
            } else {
                qualified_type_component_hit_node(qualified.nodes[component_count - 1], node)
            };
            if template_type_component_preserves_target(matched, &candidates, ctx) {
                matches.push(matched);
            }
        }
    }
    (!matches.is_empty()).then_some(matches)
}

fn class_owned_alias_has_distinct_visible_sibling(target: &CodeUnit, ctx: &ScanCtx<'_>) -> bool {
    let Some(alias_provider) = ctx.analyzer.type_alias_provider() else {
        return false;
    };
    ctx.visibility
        .visible_identifier_candidates(ctx.file, target.identifier())
        .any(|candidate| {
            alias_provider.is_type_alias(candidate)
                && candidate.identifier() == target.identifier()
                && !same_visible_symbol(candidate, target)
                && ctx
                    .analyzer
                    .parent_of(candidate)
                    .is_some_and(|owner| owner.is_class())
        })
}

/// Recover an out-of-line owner when the owner declaration and the reference
/// use different unknown preprocessor guards. Keep this result unproven.
fn target_guided_unproven_out_of_line_owner<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if !matches!(node.kind(), "qualified_identifier" | "scoped_identifier")
        || !is_declaration_name(node)
    {
        return None;
    }
    let target = physically_visible_type_target(ctx)?;
    if !target.is_class() {
        return None;
    }
    let qualified = qualified_owner_components(node, ctx.source)?;
    let target_components = canonical_cpp_scope_components(target);
    let target_namespace = &target_components[..target_components.len().saturating_sub(1)];
    let parser_scope = enclosing_namespace_components(node, ctx.source);
    let mut scope = ctx.recovered_sentinel_scope(node).or_else(|| {
        if !parser_scope.is_empty() || target_namespace.is_empty() {
            Some(parser_scope)
        } else {
            indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, node)
        }
    })?;
    if has_malformed_wrapper_function_definition_ancestor(node)
        && target_namespace.starts_with(&scope)
        && target_namespace.len() > scope.len()
    {
        scope = target_namespace.to_vec();
    }
    if !lexical_component_tiers(&qualified.names, qualified.global, &scope)
        .any(|components| components == target_components)
    {
        return None;
    }
    let owner_name = qualified.names.last()?;
    let candidates = ctx
        .visibility
        .visible_identifier_candidates(ctx.file, owner_name)
        .filter(|candidate| {
            candidate.is_class() && canonical_cpp_scope_components(candidate) == target_components
        })
        .collect::<Vec<_>>();
    if candidates.is_empty()
        || candidates
            .iter()
            .any(|candidate| !same_visible_symbol(candidate, target))
    {
        return None;
    }
    qualified.nodes.last().copied()
}

fn macro_namespace_scope_matches(
    candidate_owner: &[String],
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> bool {
    let namespace = enclosing_namespace_components(node, ctx.source);
    if namespace.is_empty() || candidate_owner.is_empty() {
        return false;
    }
    let mut expanded_owner = Vec::new();
    for component in candidate_owner {
        if let Some(replacement) =
            ctx.visibility
                .object_macro_replacement_at(ctx.file, component, node.start_byte())
        {
            let replacement_components =
                brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
                    brokk_bifrost_core::analyzer::Language::Cpp,
                    &replacement,
                );
            if replacement_components.is_empty() {
                return false;
            }
            expanded_owner.extend(replacement_components);
        } else {
            expanded_owner.push(component.clone());
        }
    }
    expanded_owner == namespace
}

fn target_guided_missing_type_leaf<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    physically_visible_type_target(ctx)?;
    target_guided_missing_dependent_nested_type_leaf(node, ctx)
        .or_else(|| target_guided_missing_declaration_type_leaf(node, ctx))
        .or_else(|| target_guided_missing_alias_rhs_type_leaf(node, ctx))
        .or_else(|| target_guided_missing_class_alias_target_type_leaf(node, ctx))
        .or_else(|| target_guided_missing_member_alias_type_leaf(node, ctx))
        .or_else(|| target_guided_missing_template_argument_type_leaf(node, ctx))
}

/// Recover a bare class-owned alias whose structured canonical target is the
/// requested type. The class owner must enclose the reference, and every alias
/// with that spelling in the owner chain must preserve the same target.
fn target_guided_missing_class_alias_target_type_leaf<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if node.kind() != "type_identifier"
        || is_declaration_name(node)
        || local_type_name_shadows(node, ctx)
    {
        return None;
    }
    let alias_provider = ctx.analyzer.type_alias_provider()?;
    let name = node_text(node, ctx.source);
    let aliases = ctx
        .visibility
        .visible_identifier_candidates(ctx.file, name)
        .filter(|candidate| alias_provider.is_type_alias(candidate))
        .filter(|candidate| {
            ctx.analyzer
                .parent_of(candidate)
                .is_some_and(|owner| owner.is_class())
        })
        .filter(|candidate| member_alias_owner_matches_reference_for(candidate, node, ctx))
        .filter(|candidate| class_alias_guard_compatible(candidate, node, ctx))
        .collect::<Vec<_>>();
    (!aliases.is_empty()
        && aliases.iter().all(|candidate| {
            same_visible_symbol(&canonical_alias_target(candidate, ctx), &ctx.spec.target)
        }))
    .then_some(node)
}

/// Recover an ambiguous unqualified alias used by a parameter or placement-new
/// type only when the indexed class owner proves the alias declaration. This
/// narrow path covers malformed class bodies without accepting unrelated aliases.
fn target_guided_ambiguous_owned_alias_type_leaf<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    let parameter = nearest_declaration_type_context(node).is_some_and(|declaration| {
        matches!(
            declaration.kind(),
            "parameter_declaration" | "optional_parameter_declaration"
        )
    });
    let placement_new_type = ctx.ancestry.parent(node).is_some_and(|parent| {
        parent.kind() == "new_expression" && parent.child_by_field_name("type") == Some(node)
    });
    if !parameter && !placement_new_type {
        return None;
    }
    if !ctx
        .analyzer
        .type_alias_provider()
        .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target))
        || !type_alias_owner_matches_structured_reference(node, ctx)
    {
        return None;
    }
    target_guided_missing_declaration_type_leaf(node, ctx)
}

/// Recover the terminal leaf of `Owner<T>::Nested` when a malformed namespace
/// sentinel prevents ordinary lexical resolution. The indexed target must have
/// an indexed class parent, the structured owner path must compose with one
/// proven lexical namespace source, and every visible candidate at that exact
/// owner path must be the indexed parent. This keeps the fallback owner-based;
/// a same-spelled nested type under another template remains unproven.
fn target_guided_missing_dependent_nested_type_leaf<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if !matches!(
        node.kind(),
        "qualified_identifier" | "scoped_type_identifier"
    ) || !qualified_type_scope_contains_template(node)
    {
        return None;
    }
    let name = node
        .child_by_field_name("name")
        .filter(|name| name.kind() == "type_identifier")?;
    if node_text(name, ctx.source) != ctx.spec.target.identifier() {
        return None;
    }
    let owner_target = ctx.analyzer.parent_of(&ctx.spec.target)?;
    if !owner_target.is_class() {
        return None;
    }
    let owner = node.child_by_field_name("scope")?;
    let owner_resolution = resolve_type_node_lexically_for_target(
        owner,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
        &owner_target,
        Some(&ctx.lexical_scope_cache),
        ctx.recovered_sentinel_scope(owner).as_deref(),
    );
    if matches!(
        owner_resolution,
        LexicalTypeResolution::Resolved {
            ref unit,
            ref candidates,
            ..
        } if type_resolution_matches_unit_target(
            owner,
            unit,
            candidates,
            &owner_target,
            ctx,
        )
    ) {
        return Some(name);
    }

    let qualified = qualified_owner_components(node, ctx.source)?;
    let namespace = ctx
        .lexical_scope_cache
        .orphaned
        .enclosing_namespace_components(node, ctx.source);
    let indexed_scope = ctx
        .recovered_sentinel_scope(node)
        .or_else(|| (!namespace.is_empty()).then_some(namespace))
        .or_else(|| indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, node))?;
    let owner_components = canonical_cpp_scope_components(&owner_target);
    if !lexical_component_tiers(&qualified.names, qualified.global, &indexed_scope)
        .any(|components| components == owner_components)
    {
        return None;
    }
    let scoped_candidates = visible_type_identifier_candidates(ctx, owner_target.identifier())
        .into_iter()
        .filter(|candidate| canonical_cpp_scope_components(candidate) == owner_components)
        .collect::<Vec<_>>();
    (!scoped_candidates.is_empty()
        && scoped_candidates
            .iter()
            .all(|candidate| same_visible_symbol(candidate, &owner_target)))
    .then_some(name)
}

/// Recover a nested type-alias reference when parser recovery leaves an
/// unqualified template argument under a member function.  The ordinary
/// lexical lookup can select a same-spelled namespace alias (or fail closed)
/// even though the indexed callable owner proves that the reference is inside
/// the class which declares the target alias.
fn target_guided_missing_member_alias_type_leaf<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if !is_cpp_template_argument_type_leaf(node)
        || is_declaration_name(node)
        || ctx
            .target_declaration_ranges
            .iter()
            .any(|range| range.start_byte <= node.start_byte() && node.end_byte() <= range.end_byte)
        || node_text(node, ctx.source) != ctx.spec.target.identifier()
        || local_type_name_shadows(node, ctx)
        || !ctx
            .analyzer
            .type_alias_provider()
            .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target))
    {
        return None;
    }
    let indexed_scope = indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, node);
    let owner_scope_matches = member_alias_owner_matches_reference(node, ctx);
    if !owner_scope_matches
        && !indexed_scope.is_some_and(|scope| {
            indexed_scope_matches_target_name(
                &scope,
                &[ctx.spec.target.identifier().to_string()],
                false,
                &ctx.spec.target,
            )
        })
    {
        return None;
    }
    // The indexed symbol table intentionally retains declarations from every
    // preprocessor branch and from later source positions.  The recovered
    // class-owner scope proves the spelling, but it does not prove that this
    // alias was active and introduced before the reference.  Apply the same
    // structured guard/source-order check used by the ordinary resolver before
    // turning the target-guided recovery into a proven hit.
    if !(ctx.visibility.external_type_candidate_visible_in_context(
        &ctx.analyzer,
        ctx.file,
        &ctx.spec.target,
        node,
    ) || owner_scope_matches && member_alias_complete_class_context(node, ctx))
    {
        return None;
    }
    let target_visible = ctx
        .visibility
        .visible_identifier_candidates(ctx.file, ctx.spec.target.identifier())
        .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target));
    target_visible.then_some(node)
}

/// Recover a class/enum template argument only when the parser's ordinary
/// lexical lookup failed but the indexed scope and visible declaration still
/// prove the exact target. This intentionally excludes aliases: an alias
/// argument needs its own template-argument selection path, while a direct
/// class/enum argument can be identified by its canonical scope and symbol.
fn target_guided_missing_template_argument_type_leaf<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    let target = &ctx.spec.target;
    let name = node_text(node, ctx.source);
    if !target.is_class()
        || !is_cpp_template_argument_type_leaf(node)
        || is_declaration_name(node)
        || name != target.identifier()
        || ctx.local_shadows.is_shadowed(name)
        || local_type_name_shadows(node, ctx)
        || !ctx.visibility.is_physically_visible(ctx.file, target)
        || ctx
            .analyzer
            .type_alias_provider()
            .is_some_and(|provider| provider.is_type_alias(target))
    {
        return None;
    }

    let indexed_scope = indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, node)?;
    let target_components = canonical_cpp_scope_components(target);
    if target_components.last().map(String::as_str) != Some(name)
        || !lexical_component_tiers(&[name.to_string()], false, &indexed_scope)
            .any(|components| components == target_components)
    {
        return None;
    }

    // The direct visible class candidate supplies the declaration identity;
    // the scope check above supplies its canonical owner path. Do not let an
    // alias or a same-scoped competing class enter this recovery path.
    let candidates = visible_type_identifier_candidates(ctx, name);
    if candidates.is_empty()
        || candidates.iter().any(|candidate| {
            !candidate.is_class()
                || ctx
                    .analyzer
                    .type_alias_provider()
                    .is_some_and(|provider| provider.is_type_alias(candidate))
                || (!same_visible_symbol(candidate, target)
                    && lexical_component_tiers(&[name.to_string()], false, &indexed_scope)
                        .any(|components| components == canonical_cpp_scope_components(candidate)))
        })
        || !candidates
            .iter()
            .any(|candidate| same_visible_symbol(candidate, target))
    {
        return None;
    }

    // Physical visibility covers the file/import projection; this second
    // guard preserves declaration ordering and preprocessor branch identity.
    ctx.visibility
        .external_type_candidate_visible_in_context(&ctx.analyzer, ctx.file, target, node)
        .then_some(node)
}

/// Recover the class owner of an out-of-line member whose trailing attribute
/// macro was parsed as a separate function definition around the real body.
fn split_macro_attribute_out_of_line_owner(node: Node<'_>, ctx: &ScanCtx<'_>) -> Option<CodeUnit> {
    let mut function = node;
    while function.kind() != "function_definition" {
        function = ctx.ancestry.parent(function)?;
    }
    let macro_name = function_definition_name_node(function)?;
    if !cpp_export_macro_token(&normalize_cpp_whitespace(node_text(macro_name, ctx.source))) {
        return None;
    }

    // An unknown trailing attribute macro can split one real definition into
    // a missing-semicolon declaration for `Owner::method()` and an adjacent
    // macro-named function definition that owns the body. Recover only that
    // exact CST sequence; a complete declaration or a non-macro function is
    // an ordinary independent construct.
    let declaration = function.prev_named_sibling()?;
    if declaration.kind() != "declaration"
        || !declaration.has_error()
        || function.start_position().row > declaration.end_position().row + 1
    {
        return None;
    }
    let mut missing_semicolon = false;
    let mut real_semicolon = false;
    for child in children_iter(declaration) {
        if child.kind() == ";" {
            missing_semicolon |= child.is_missing();
            real_semicolon |= !child.is_missing();
        }
    }
    if !missing_semicolon || real_semicolon {
        return None;
    }

    let initializer = declaration.child_by_field_name("declarator")?;
    if initializer.kind() != "init_declarator"
        || initializer
            .child_by_field_name("value")
            .is_none_or(|value| value.kind() != "argument_list")
    {
        return None;
    }
    let qualified_name = initializer
        .child_by_field_name("declarator")
        .and_then(declarator_name_node)?;
    let qualified = qualified_owner_components(qualified_name, ctx.source)?;
    let lexical_scope = enclosing_namespace_components(function, ctx.source);
    match ctx.visibility.resolve_type_components_lexically(
        &ctx.analyzer,
        ctx.file,
        &qualified.names,
        qualified.global,
        &lexical_scope,
    ) {
        LexicalTypeResolution::Resolved { unit, .. } if unit.is_class() => Some(unit),
        LexicalTypeResolution::Resolved { .. }
        | LexicalTypeResolution::Ambiguous
        | LexicalTypeResolution::Missing => None,
    }
}

/// A class member alias is visible throughout its complete class scope, even
/// when its declaration byte follows a recovered out-of-line member's
/// trailing return type. Match the indexed owner path structurally before
/// allowing the guard-only visibility check above to waive source ordering.
fn member_alias_owner_matches_reference(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    member_alias_owner_matches_reference_for(&ctx.spec.target, node, ctx)
}

fn member_alias_owner_matches_reference_for(
    target: &CodeUnit,
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> bool {
    let Some(owner) = ctx.analyzer.parent_of(target) else {
        return false;
    };
    if !owner.is_class() {
        return false;
    }
    let reference_owner = ctx
        .class_ranges
        .and_then(|class_ranges| class_ranges.enclosing_unit(node.start_byte()).cloned())
        .or_else(|| structured_enclosing_owner(node, ctx));
    if reference_owner.as_ref().is_some_and(|reference_owner| {
        ctx.visibility
            .same_template_owner_identity(&owner, reference_owner)
    }) {
        return true;
    }
    if split_macro_attribute_out_of_line_owner(node, ctx).is_some_and(|reference_owner| {
        ctx.visibility
            .same_template_owner_identity(&owner, &reference_owner)
    }) {
        return true;
    }
    if reference_owner.is_some_and(|reference_owner| {
        matches!(
            resolve_declaring_member_owner(
                &ctx.analyzer,
                ctx.visibility,
                ctx.file,
                &reference_owner,
                target.identifier(),
            ),
            EnclosingMemberOwnerResolution::Owner(declaring_owner)
                if ctx
                    .visibility
                    .same_template_owner_identity(&owner, &declaring_owner)
        )
    }) {
        return true;
    }
    let range = Range {
        start_byte: node.start_byte(),
        end_byte: node.end_byte(),
        start_line: node.start_position().row + 1,
        end_line: node.end_position().row + 1,
    };
    let mut indexed_enclosing = ctx.analyzer.enclosing_code_unit(ctx.file, &range);
    while let Some(candidate) = indexed_enclosing {
        if candidate.is_class()
            && ctx
                .visibility
                .same_template_owner_identity(&owner, &candidate)
        {
            return true;
        }
        indexed_enclosing = ctx.analyzer.parent_of(&candidate);
    }
    if let Some(reference_body) = malformed_recovered_class_body(node) {
        let mut root = node;
        while let Some(parent) = ctx.ancestry.parent(root) {
            root = parent;
        }
        if ctx.analyzer.ranges(target).iter().any(|range| {
            root.descendant_for_byte_range(range.start_byte, range.end_byte)
                .and_then(malformed_recovered_class_body)
                .is_some_and(|declaration_body| same_node(declaration_body, reference_body))
        }) {
            return true;
        }
    }
    if structured_enclosing_owner(node, ctx)
        .is_some_and(|reference_owner| same_logical_symbol(&owner, &reference_owner))
    {
        return true;
    }
    let owner_components = canonical_cpp_scope_components(&owner);
    if ctx
        .recovered_sentinel_scope(node)
        .is_some_and(|scope| scope == owner_components)
    {
        return true;
    }
    if matches!(
        cached_enclosing_lexical_scope_components_with_unresolved_owner(
            node,
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            ctx.source,
            false,
            false,
            Some(&ctx.lexical_scope_cache),
        ),
        LexicalScopeResolution::Resolved(reference_scope)
            if reference_scope == owner_components
    ) {
        return true;
    }
    let Some(reference_scope) = indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, node)
    else {
        return false;
    };
    !owner_components.is_empty() && reference_scope == owner_components
}

fn malformed_recovered_class_body(mut node: Node<'_>) -> Option<Node<'_>> {
    loop {
        if node.kind() == "compound_statement"
            && node
                .parent()
                .is_some_and(|parent| parent.kind() == "declaration_list")
            && node.prev_named_sibling().is_some_and(|header| {
                header.kind() == "ERROR"
                    && header.end_byte() <= node.start_byte()
                    && error_contains_class_header(header)
            })
        {
            return Some(node);
        }
        node = node.parent()?;
    }
}

/// Whether a shallow parser error contains a recognizable class header.
pub fn error_contains_class_header(node: Node<'_>) -> bool {
    let mut pending = vec![(node, 0usize)];
    while let Some((current, depth)) = pending.pop() {
        if matches!(current.kind(), "class" | "struct" | "union") {
            let mut sibling = current.next_sibling();
            let mut saw_name = false;
            while let Some(candidate) = sibling {
                match candidate.kind() {
                    "comment" => {}
                    "{" | "base_class_clause" | ":" => return saw_name,
                    "identifier" | "type_identifier" if !saw_name => saw_name = true,
                    _ if !candidate.is_named() => {}
                    _ => break,
                }
                sibling = candidate.next_sibling();
            }
        }
        if depth >= 1 {
            continue;
        }
        let mut cursor = current.walk();
        pending.extend(
            current
                .children(&mut cursor)
                .filter(|child| child.kind() != "compound_statement")
                .map(|child| (child, depth + 1)),
        );
    }
    false
}

fn member_alias_complete_class_context(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    has_ancestor_kind(node, "compound_statement")
        && ctx
            .visibility
            .external_type_candidate_guard_compatible_in_context(
                &ctx.analyzer,
                ctx.file,
                &ctx.spec.target,
                node,
            )
}

fn type_alias_owner_matches_structured_reference(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    ctx.analyzer
        .type_alias_provider()
        .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target))
        && member_alias_owner_matches_reference(node, ctx)
}

/// A nested class can use aliases declared by any enclosing class. Preserve
/// that structured owner chain for malformed macro-return nodes, whose phantom
/// field spelling otherwise makes ordinary lexical lookup ambiguous.
fn type_alias_owner_encloses_structured_reference(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    if !ctx
        .analyzer
        .type_alias_provider()
        .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target))
    {
        return false;
    }
    let Some(target_owner) = ctx.analyzer.parent_of(&ctx.spec.target) else {
        return false;
    };
    let mut reference_owner = structured_enclosing_owner(node, ctx);
    while let Some(owner) = reference_owner {
        if same_logical_symbol(&target_owner, &owner) {
            return true;
        }
        reference_owner = ctx.analyzer.parent_of(&owner);
    }
    false
}

/// An enclosing class alias is only usable when no nearer class declares the
/// same type name. The recovered macro-return path does not have a complete
/// lexical declaration node, so ordinary lookup cannot apply this shadowing
/// rule before the enclosing alias fast path runs.
fn nearer_type_name_shadows_structured_reference(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let Some(target_owner) = ctx.analyzer.parent_of(&ctx.spec.target) else {
        return false;
    };
    let Some(alias_provider) = ctx.analyzer.type_alias_provider() else {
        return false;
    };
    let Some(reference_owner) = structured_enclosing_owner(node, ctx) else {
        return false;
    };
    let candidates = ctx
        .visibility
        .visible_identifier_candidates(ctx.file, ctx.spec.target.identifier())
        .filter(|candidate| {
            candidate.is_class()
                && alias_provider.is_type_alias(candidate)
                && !same_visible_symbol(candidate, &ctx.spec.target)
        })
        .cloned()
        .collect::<Vec<_>>();

    let mut owner = Some(reference_owner);
    while let Some(owner_unit) = owner {
        if same_logical_symbol(&target_owner, &owner_unit) {
            return false;
        }
        if candidates.iter().any(|candidate| {
            ctx.analyzer
                .parent_of(candidate)
                .is_some_and(|candidate_owner| {
                    candidate_owner.is_class() && same_logical_symbol(&candidate_owner, &owner_unit)
                })
                && ctx
                    .visibility
                    .external_type_candidate_guard_compatible_in_context(
                        &ctx.analyzer,
                        ctx.file,
                        candidate,
                        node,
                    )
        }) {
            return true;
        }
        owner = ctx.analyzer.parent_of(&owner_unit);
    }
    false
}

fn local_type_name_shadows(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    if cpp_active_template_type_parameter(
        node,
        ctx.spec.target.identifier(),
        ctx.source,
        &ctx.ancestry,
    ) {
        return true;
    }
    let Some(callable) = nearest_callable_scope(node) else {
        return false;
    };
    let mut root_callable = callable;
    let mut ancestor = ctx.ancestry.parent(callable);
    while let Some(current) = ancestor {
        if matches!(current.kind(), "function_definition" | "lambda_expression") {
            root_callable = current;
        }
        ancestor = ctx.ancestry.parent(current);
    }

    let mut stack = vec![root_callable];
    while let Some(current) = stack.pop() {
        if current.start_byte() >= node.start_byte() {
            continue;
        }
        if let Some(name) = local_type_name_declaration_node(current)
            && node_text(name, ctx.source) == ctx.spec.target.identifier()
            && nearest_callable_scope(current).is_some_and(|owner| {
                !is_malformed_wrapper_function_definition(owner)
                    && owner.start_byte() <= callable.start_byte()
                    && callable.end_byte() <= owner.end_byte()
            })
            && local_alias_scope_contains_node(current, node)
        {
            return true;
        }
        let mut cursor = current.walk();
        stack.extend(current.named_children(&mut cursor));
    }
    false
}

fn local_type_name_declaration_node(node: Node<'_>) -> Option<Node<'_>> {
    local_type_alias_name_node(node).or_else(|| match node.kind() {
        "class_specifier" | "struct_specifier" | "union_specifier" | "enum_specifier" => node
            .child_by_field_name("name")
            .filter(|name| is_declaration_name(*name)),
        _ => None,
    })
}

fn nearest_callable_scope(mut node: Node<'_>) -> Option<Node<'_>> {
    loop {
        if matches!(node.kind(), "function_definition" | "lambda_expression") {
            return Some(node);
        }
        node = node.parent()?;
    }
}

fn local_type_alias_name_node(node: Node<'_>) -> Option<Node<'_>> {
    match node.kind() {
        "alias_declaration" => node.child_by_field_name("name"),
        "type_definition" => node
            .child_by_field_name("declarator")
            .and_then(declarator_name_node),
        _ => None,
    }
}

fn local_alias_scope_contains_node(alias: Node<'_>, node: Node<'_>) -> bool {
    let mut current = alias.parent();
    while let Some(parent) = current {
        if matches!(
            parent.kind(),
            "class_specifier" | "struct_specifier" | "union_specifier"
        ) {
            return false;
        }
        if parent.kind() == "compound_statement" {
            return parent.start_byte() <= node.start_byte()
                && node.end_byte() <= parent.end_byte();
        }
        if matches!(parent.kind(), "function_definition" | "lambda_expression") {
            let Some(body) = parent.child_by_field_name("body") else {
                return false;
            };
            return node_is_within(body, alias) && node_is_within(body, node);
        }
        current = parent.parent();
    }
    false
}

fn target_guided_missing_declaration_type_leaf<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if is_declaration_name(node) {
        return None;
    }
    let component_nodes = cpp_name_component_nodes(node)?;
    let name_node = component_nodes.last().copied()?;
    let name = node_text(name_node, ctx.source);
    if name != ctx.spec.target.identifier() {
        return None;
    }
    let inside_target_declaration = ctx
        .target_declaration_ranges
        .iter()
        .any(|range| range.start_byte <= node.start_byte() && node.end_byte() <= range.end_byte);
    if !inside_target_declaration
        && !ctx.visibility.external_type_candidate_visible_in_context(
            &ctx.analyzer,
            ctx.file,
            &ctx.spec.target,
            node,
        )
    {
        return None;
    }
    let components = component_nodes
        .iter()
        .map(|component| node_text(*component, ctx.source).to_string())
        .collect::<Vec<_>>();
    let local_alias_shadow = local_type_name_shadows(node, ctx);
    let structured_alias_owner = type_alias_owner_matches_structured_reference(node, ctx);
    let indexed_alias_owner = ctx
        .analyzer
        .type_alias_provider()
        .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target))
        && member_alias_owner_matches_reference(node, ctx);
    let target_alias_self_reference = inside_target_declaration
        && ctx
            .analyzer
            .type_alias_provider()
            .is_some_and(|provider| provider.is_type_alias(&ctx.spec.target));
    let member_alias_visible = ctx.visibility.external_type_candidate_visible_in_context(
        &ctx.analyzer,
        ctx.file,
        &ctx.spec.target,
        node,
    ) || member_alias_complete_class_context(node, ctx);
    if !target_alias_self_reference
        && !local_alias_shadow
        && member_alias_visible
        && (structured_alias_owner || indexed_alias_owner)
    {
        return Some(node);
    }
    let declaration = nearest_declaration_type_context(node)?;
    let candidates = visible_type_identifier_candidates(ctx, name);
    let unique_visible_target = !candidates.is_empty()
        && candidates
            .iter()
            .all(|candidate| same_visible_symbol(candidate, &ctx.spec.target));
    let indexed_scope = indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, node)?;
    let exact_scope_match = indexed_scope_matches_target_name(
        &indexed_scope,
        &components,
        is_globally_qualified_cpp_name(node),
        &ctx.spec.target,
    );
    if matches!(declaration.kind(), "field_declaration" | "declaration") {
        let parser_lost_declaration_scope =
            target_guided_scope_lost_namespace(&indexed_scope, &ctx.spec.target)
                && unique_visible_target;
        return (exact_scope_match || parser_lost_declaration_scope).then_some(node);
    }
    let lost_namespace_parameter_context =
        matches!(
            declaration.kind(),
            "parameter_declaration" | "optional_parameter_declaration"
        ) && target_guided_scope_lost_namespace(&indexed_scope, &ctx.spec.target);
    if exact_scope_match || (lost_namespace_parameter_context && unique_visible_target) {
        return Some(node);
    }
    None
}

fn target_guided_missing_alias_rhs_type_leaf<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    let mut stack = vec![node];
    while let Some(candidate) = stack.pop() {
        if candidate.kind() == "type_identifier"
            && !is_declaration_name(candidate)
            && matches!(
                ctx.ancestry.parent(candidate).map(|parent| parent.kind()),
                Some("template_type")
            )
        {
            let mut current = ctx.ancestry.parent(candidate);
            let mut saw_qualified = false;
            let mut saw_dependent = false;
            let mut saw_type_descriptor = false;
            let mut saw_alias_declaration = false;
            while let Some(ancestor) = current {
                match ancestor.kind() {
                    "qualified_identifier" | "scoped_type_identifier" => saw_qualified = true,
                    "dependent_type" => saw_dependent = true,
                    "type_descriptor" => saw_type_descriptor = true,
                    "alias_declaration" => {
                        saw_alias_declaration = true;
                        break;
                    }
                    "template_type"
                    | "template_argument_list"
                    | "typename"
                    | "template_declaration" => {}
                    _ => {}
                }
                current = ctx.ancestry.parent(ancestor);
            }
            let name = node_text(candidate, ctx.source);
            let visible_candidates = visible_type_identifier_candidates(ctx, name);
            let canonical_alias_target = visible_candidates
                .iter()
                .filter_map(|alias| ctx.visibility.alias_target(alias))
                .any(|target| same_visible_symbol(&target, &ctx.spec.target));
            let alias_resolves =
                ctx.visibility
                    .parser_alias_resolves_to_type(ctx.file, name, &ctx.spec.target)
                    || canonical_alias_target;
            if saw_qualified
                && saw_dependent
                && saw_type_descriptor
                && saw_alias_declaration
                && alias_resolves
                && ctx.visibility.external_type_candidate_visible_in_context(
                    &ctx.analyzer,
                    ctx.file,
                    &ctx.spec.target,
                    candidate,
                )
            {
                return Some(candidate);
            }
        }
        push_named_children_reversed(candidate, &mut stack);
    }
    None
}

fn nearest_declaration_type_context(node: Node<'_>) -> Option<Node<'_>> {
    let mut current = Some(node);
    while let Some(ancestor) = current {
        if matches!(
            ancestor.kind(),
            "field_declaration"
                | "parameter_declaration"
                | "optional_parameter_declaration"
                | "declaration"
                | "type_descriptor"
        ) {
            let contains_type = crate::declarations::cpp_type_field_contains_node(ancestor, node);
            if contains_type
                && !(ancestor.kind() == "type_descriptor"
                    && is_cpp_template_argument_type_leaf(node))
            {
                return Some(ancestor);
            }
            if ancestor.kind() == "type_descriptor"
                && ancestor.parent().is_some_and(|parent| {
                    matches!(
                        parent.kind(),
                        "cast_expression"
                            | "new_expression"
                            | "sizeof_expression"
                            | "alignof_expression"
                            | "typeid_expression"
                    )
                })
            {
                return Some(ancestor);
            }
        }
        if matches!(
            ancestor.kind(),
            "compound_statement"
                | "translation_unit"
                | "namespace_definition"
                | "alias_declaration"
                | "type_definition"
                | "base_class_clause"
        ) {
            return None;
        }
        current = ancestor.parent();
    }
    None
}

fn visible_type_identifier_candidates(ctx: &ScanCtx<'_>, name: &str) -> Vec<CodeUnit> {
    let mut candidates = Vec::new();
    for candidate in ctx
        .visibility
        .visible_identifier_candidates(ctx.file, name)
        .filter(|candidate| {
            candidate.is_class()
                || ctx
                    .analyzer
                    .type_alias_provider()
                    .is_some_and(|provider| provider.is_type_alias(candidate))
        })
    {
        if !candidates
            .iter()
            .any(|existing| same_logical_symbol(existing, candidate))
        {
            candidates.push(candidate.clone());
        }
    }
    candidates
}

/// Recover a direct type-alias argument of `static_cast` when parser recovery
/// misclassifies a namespace alias as a local declaration. The indexed scope
/// and exact alias identity are required so a same-spelled alias in another
/// namespace remains excluded.
fn target_guided_static_cast_alias_type_descriptor<'tree>(
    node: Node<'tree>,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    if node.kind() != "type_descriptor" {
        return None;
    }
    let argument_list = ctx.ancestry.parent(node).filter(|parent| {
        parent.kind() == "template_argument_list"
            && parent.named_child_count() == 1
            && parent.named_child(0) == Some(node)
    })?;
    let template = ctx.ancestry.parent(argument_list).filter(|parent| {
        parent.kind() == "template_function"
            && parent.child_by_field_name("arguments") == Some(argument_list)
    })?;
    let name = template.child_by_field_name("name")?;
    if name.kind() != "identifier" || node_text(name, ctx.source) != "static_cast" {
        return None;
    }
    let target = &ctx.spec.target;
    if node_text(node, ctx.source) != target.identifier()
        || !ctx
            .analyzer
            .type_alias_provider()
            .is_some_and(|provider| provider.is_type_alias(target))
        || !ctx.visibility.is_physically_visible(ctx.file, target)
        || !ctx.visibility.external_type_candidate_visible_in_context(
            &ctx.analyzer,
            ctx.file,
            target,
            node,
        )
    {
        return None;
    }

    let indexed_scope = indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, node)?;
    let target_scope = canonical_cpp_scope_components(target);
    let name_components = [target.identifier().to_string()];
    if !lexical_component_tiers(&name_components, false, &indexed_scope)
        .any(|components| components == target_scope)
    {
        return None;
    }

    let candidates = visible_type_identifier_candidates(ctx, target.identifier());
    if !candidates
        .iter()
        .any(|candidate| same_visible_symbol(candidate, target))
    {
        return None;
    }
    if candidates.iter().any(|candidate| {
        !same_visible_symbol(candidate, target)
            && lexical_component_tiers(&name_components, false, &indexed_scope)
                .any(|components| components == canonical_cpp_scope_components(candidate))
    }) {
        return None;
    }
    Some(node)
}

fn indexed_scope_matches_target_name(
    indexed_scope: &[String],
    components: &[String],
    global: bool,
    target: &CodeUnit,
) -> bool {
    let target_name = cpp_name_for(target);
    lexical_component_tiers(components, global, indexed_scope)
        .any(|qualified| qualified.join("::") == target_name)
}

fn target_guided_scope_lost_namespace(indexed_scope: &[String], target: &CodeUnit) -> bool {
    // A global scope or one surviving name alone cannot distinguish a lost
    // namespace from a real global/unrelated reference. Require an enclosing
    // declaration component as well as a namespace component matching the
    // target's qualified scope.
    if target.package_name().is_empty() || indexed_scope.len() <= 1 {
        return false;
    }
    let mut target_scope = brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
        brokk_bifrost_core::analyzer::Language::Cpp,
        &cpp_name_for(target),
    );
    target_scope.pop();
    (1..indexed_scope.len())
        .rev()
        .any(|prefix_len| target_scope.ends_with(&indexed_scope[..prefix_len]))
}

fn indexed_enclosing_lexical_scope(
    analyzer: &CppGraphSource<'_>,
    file: &ProjectFile,
    node: Node<'_>,
) -> Option<Vec<String>> {
    let range = Range {
        start_byte: node.start_byte(),
        end_byte: node.end_byte(),
        start_line: node.start_position().row,
        end_line: node.end_position().row,
    };
    let enclosing = analyzer.enclosing_code_unit(file, &range)?;
    let mut components = brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
        brokk_bifrost_core::analyzer::Language::Cpp,
        &cpp_name_for(&enclosing),
    );
    if !enclosing.is_class() && !enclosing.is_module() {
        components.pop();
    }
    Some(components)
}

fn static_qualifier_name_scope<'tree>(node: Node<'tree>, ctx: &ScanCtx<'_>) -> Option<Node<'tree>> {
    if node.kind() != "qualified_identifier" {
        return None;
    }
    let mut stack = vec![node];
    while let Some(current) = stack.pop() {
        if current.kind() != "qualified_identifier" {
            continue;
        }
        if let Some(scope) = current.child_by_field_name("scope") {
            let text = qualified_scope_text(scope, ctx.source);
            if name_mentions(&text, &ctx.spec.member_name) {
                return Some(scope);
            }
        }
        let mut cursor = current.walk();
        for child in current.named_children(&mut cursor) {
            if child.kind() == "qualified_identifier" {
                stack.push(child);
            }
        }
    }
    None
}

fn qualified_scope_text(scope: Node<'_>, source: &str) -> String {
    let mut parts = vec![node_text(scope, source).to_string()];
    let mut current = scope.parent();
    while let Some(qualified) = current {
        let Some(parent) = qualified.parent() else {
            break;
        };
        if parent.kind() != "qualified_identifier"
            || parent.child_by_field_name("name") != Some(qualified)
        {
            break;
        }
        if let Some(outer_scope) = parent.child_by_field_name("scope") {
            parts.push(node_text(outer_scope, source).to_string());
        }
        current = Some(parent);
    }
    parts.reverse();
    parts.join("::")
}

fn maybe_record_constructor_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if node.kind() == "using_declaration" {
        maybe_record_using_callable_hit(node, ctx);
        return;
    }
    if has_ancestor_kind(node, "using_declaration") {
        return;
    }
    if node.kind() == "function_definition" {
        return;
    }
    if !matches!(
        node.kind(),
        "call_expression"
            | "new_expression"
            | "compound_literal_expression"
            | "declaration"
            | "field_initializer"
    ) {
        return;
    }
    let Some(owner) = ctx.spec.owner.as_ref() else {
        return;
    };
    if node.kind() == "field_initializer" {
        if !field_initializer_constructs_target(node, ctx, owner)
            && !unqualified_base_initializer_constructs_target(node, ctx, owner)
        {
            return;
        }
        if let Some(expected) = ctx.spec.callable_arity_at(node.start_byte()) {
            match ctx
                .visibility
                .call_arity_evidence(ctx.file, node, ctx.source)
                .accepts(expected)
            {
                Some(true) => {}
                Some(false) => return,
                None => {
                    push_unproven_hit(node, ctx);
                    return;
                }
            }
        }
        match constructor_overload_selection(node, ctx) {
            ConstructorOverloadSelection::Target => push_hit(node, ctx),
            ConstructorOverloadSelection::Ambiguous => push_unproven_hit(node, ctx),
            ConstructorOverloadSelection::OtherOverload => {}
        }
        return;
    }
    if node.kind() == "declaration" {
        if declaration_is_object_construction_candidate(node, ctx)
            && declaration_mentions_type(node, ctx, owner)
            && ctx
                .spec
                .callable_arity_at(node.start_byte())
                .is_none_or(|expected| expected.accepts(declaration_constructor_arity(node, ctx)))
        {
            match constructor_overload_selection(node, ctx) {
                ConstructorOverloadSelection::Target => push_hit(node, ctx),
                ConstructorOverloadSelection::Ambiguous => push_unproven_hit(node, ctx),
                ConstructorOverloadSelection::OtherOverload => {}
            }
        }
        return;
    }
    let Some(type_node) = constructor_type_node(node) else {
        return;
    };
    let hit_node = function_terminal_node(type_node);
    let text = node_text(type_node, ctx.source);
    if !name_mentions(text, &ctx.spec.member_name) {
        return;
    }
    *ctx.raw_match_count += 1;
    if let Some(expected) = ctx.spec.callable_arity_at(node.start_byte()) {
        match ctx
            .visibility
            .call_arity_evidence(ctx.file, node, ctx.source)
            .accepts(expected)
        {
            Some(true) => {}
            Some(false) => return,
            None => {
                push_unproven_hit(hit_node, ctx);
                return;
            }
        }
    }
    match constructor_overload_selection(node, ctx) {
        ConstructorOverloadSelection::Target => {}
        ConstructorOverloadSelection::Ambiguous => {
            push_unproven_hit(hit_node, ctx);
            return;
        }
        ConstructorOverloadSelection::OtherOverload => return,
    }
    let structured_resolution = resolve_type_node_lexically_for_target(
        type_node,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
        owner,
        Some(&ctx.lexical_scope_cache),
        ctx.recovered_sentinel_scope(type_node).as_deref(),
    );
    let structurally_resolves = matches!(
        &structured_resolution,
        LexicalTypeResolution::Resolved {
            unit, candidates, ..
        } if same_visible_symbol(unit, owner)
            || candidates
                .iter()
                .any(|candidate| same_visible_symbol(candidate, owner))
    );
    if structurally_resolves
        || matches!(structured_resolution, LexicalTypeResolution::Missing)
            && ctx
                .visibility
                .resolves_to_type(&ctx.analyzer, ctx.file, text, owner)
    {
        push_hit(hit_node, ctx);
    } else {
        push_unproven_hit(hit_node, ctx);
    }
}

/// What the overload filter says about a construction site relative to the
/// constructor being scanned.
enum ConstructorOverloadSelection {
    /// The arguments leave the scan target as the only viable constructor, or
    /// the filter has no evidence to apply here. Either way nothing about the
    /// arguments argues against the site, so the rest of the scan decides it.
    Target,
    /// More than one of the owner's constructors stays viable, so the site
    /// cannot be proven to belong to the target.
    Ambiguous,
    /// The arguments select a sibling constructor and not the target.
    OtherOverload,
}

/// Which of the owner's constructors the arguments at a construction site
/// select, for every shape `maybe_record_constructor_hit` accepts: `T(args)`,
/// `T{args}`, `new T(args)`, the member initializer `: field(args)`, and the
/// `T var(args)` declaration.
///
/// This is the inverse reading of the forward direction's overload choice. The
/// candidate set is the owner's arity-compatible constructors, the arguments are
/// typed by the same `expression_arg_type` the method and free-function scan
/// paths use, and `cpp_filter_candidates_by_args_with_parameter_types` applies
/// the same exact-then-conversion ranking (#2894). Selecting a constructor by
/// arity alone made a scan of one overload claim every same-arity sibling's call
/// (#2908).
fn constructor_overload_selection(
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> ConstructorOverloadSelection {
    let Some(owner) = ctx.spec.owner.as_ref() else {
        return ConstructorOverloadSelection::Target;
    };
    if ctx.spec.param_types.is_none() {
        return ConstructorOverloadSelection::Target;
    }
    // A `T var(args)` declaration keeps its arguments under the declarator or the
    // init declarator's value; every other shape spells an argument list that the
    // shared call helpers find, and its argument count needs the macro-aware
    // arity evidence.
    let (arity, arg_types) = if node.kind() == "declaration" {
        match declaration_constructor_initializer(node) {
            DeclarationConstructorInitializer::Arguments(arguments) => (
                argument_children(arguments).count(),
                argument_list_types(arguments, ctx),
            ),
            DeclarationConstructorInitializer::Expression(value) => {
                (1, vec![expression_arg_type(value, ctx)])
            }
            DeclarationConstructorInitializer::Empty => (0, Vec::new()),
        }
    } else {
        let Some(arity) = ctx
            .visibility
            .call_arity_evidence(ctx.file, node, ctx.source)
            .exact()
        else {
            return ConstructorOverloadSelection::Target;
        };
        (arity, call_argument_types(node, ctx))
    };
    let mut candidates = ctx
        .visibility
        .visible_members_for_owner_name(ctx.file, owner, &ctx.spec.member_name)
        .into_iter()
        .filter(|unit| unit.is_function())
        .cloned()
        .collect::<Vec<_>>();
    candidates.retain(|unit| {
        cpp_callable_arity(&ctx.analyzer, unit).is_none_or(|known| known.accepts(arity))
    });
    if !candidates
        .iter()
        .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target))
    {
        return ConstructorOverloadSelection::Target;
    }
    let filtered = cpp_filter_candidates_by_args_with_parameter_types(
        candidates,
        &arg_types,
        &|candidate| cpp_callable_parameter_types(&ctx.analyzer, candidate),
        &|candidate| {
            ctx.visibility
                .callable_is_template_declaration(&ctx.analyzer, candidate)
        },
        &|name| ctx.visibility.resolve_type(ctx.file, name),
        &|left, right| same_visible_symbol(left, right),
    );
    if !filtered
        .iter()
        .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target))
    {
        return ConstructorOverloadSelection::OtherOverload;
    }
    // A header declaration and its out-of-line body are one constructor even
    // when their persisted signature strings spell a parameter differently, so
    // `same_logical_callable` decides what counts as a surviving sibling (#2010).
    if filtered.iter().all(|candidate| {
        ctx.visibility
            .same_logical_callable(&ctx.analyzer, candidate, &ctx.spec.target)
    }) {
        ConstructorOverloadSelection::Target
    } else {
        ConstructorOverloadSelection::Ambiguous
    }
}

fn unqualified_base_initializer_constructs_target(
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
    target_owner: &CodeUnit,
) -> bool {
    if first_named_child_of_kind(node, "qualified_identifier").is_some() {
        return false;
    }
    let Some(name) = node
        .child_by_field_name("name")
        .or_else(|| first_named_child_of_kind(node, "field_identifier"))
    else {
        return false;
    };
    if node_text(name, ctx.source) != ctx.spec.member_name {
        return false;
    }
    let Some(enclosing_owner) = structured_enclosing_owner(node, ctx) else {
        return false;
    };
    let inherited = ctx.visibility.inherited_injected_class_owner(
        &ctx.analyzer,
        ctx.file,
        &enclosing_owner,
        &ctx.spec.member_name,
    );
    inherited.is_some_and(|owner| {
        receiver_owner_matches_target(&owner, target_owner, node.start_byte(), ctx)
    })
}

fn maybe_record_free_function_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if node.kind() == "function_definition" {
        maybe_record_free_function_definition_hit(node, ctx);
        return;
    }
    if node.kind() == "function_declarator" {
        maybe_record_recovered_error_free_function_call(node, ctx);
        return;
    }
    if node.kind() == "identifier" {
        maybe_record_free_function_value_reference(node, ctx);
        return;
    }
    if node.kind() != "call_expression" {
        return;
    }
    let Some(function) = node
        .child_by_field_name("function")
        .or_else(|| node.named_child(0))
    else {
        return;
    };
    let text = node_text(function, ctx.source);
    if !name_matches_callable(text, &ctx.spec.member_name) {
        return;
    }
    *ctx.raw_match_count += 1;
    if let Some(expected) = ctx.spec.callable_arity_at(node.start_byte()) {
        match ctx
            .visibility
            .call_arity_evidence(ctx.file, node, ctx.source)
            .accepts(expected)
        {
            Some(true) => {}
            Some(false) => return,
            None => {
                // The argument count is unknown after macro expansion. It still
                // cannot select a *different* target when the bare name binds
                // to exactly one visible callable, so let the bare-call
                // resolution below prove that site; every other shape stays
                // unproven (#1811, the scan side of the same over-conservatism
                // that made the forward answer discard its lone candidate).
                if !bare_name_binds_only_target(node, function, text, ctx) {
                    push_unproven_hit(function_terminal_node(function), ctx);
                    return;
                }
            }
        }
    }
    if matches!(function.kind(), "identifier" | "template_function") {
        let terminal = function_terminal_node(function);
        let name = node_text(terminal, ctx.source);
        if ctx.local_shadows.is_shadowed(name) {
            return;
        }
        if let Some(enclosing_owner) = structured_enclosing_owner(function, ctx)
            && !matches!(
                resolve_declaring_member_owner(
                    &ctx.analyzer,
                    ctx.visibility,
                    ctx.file,
                    &enclosing_owner,
                    name,
                ),
                EnclosingMemberOwnerResolution::Missing
            )
        {
            return;
        }
        match resolve_bare_call_target(
            node,
            function,
            &ctx.analyzer,
            ctx.visibility,
            &ctx.ordinary_type_imports,
            ctx.file,
            ctx.source,
        ) {
            BareCallTargetResolution::FreeFunctions(units)
                if units
                    .iter()
                    .any(|unit| free_function_target_matches(unit, ctx)) =>
            {
                if free_function_call_may_target(node, text, ctx) {
                    let recursive = enclosing_context(terminal, ctx)
                        .enclosing
                        .as_ref()
                        .is_some_and(|enclosing| same_logical_symbol(enclosing, &ctx.spec.target));
                    if recursive {
                        push_recursive_reference_hit(terminal, ctx);
                    } else {
                        push_hit(terminal, ctx);
                    }
                }
            }
            BareCallTargetResolution::UnprovenFreeFunctions(units)
                if units
                    .iter()
                    .any(|unit| free_function_target_matches(unit, ctx)) =>
            {
                push_unproven_hit(terminal, ctx);
            }
            BareCallTargetResolution::FreeFunctions(_)
            | BareCallTargetResolution::UnprovenFreeFunctions(_)
            | BareCallTargetResolution::Type(_)
            | BareCallTargetResolution::CallableShadow => {}
            BareCallTargetResolution::Ambiguous | BareCallTargetResolution::Missing => {
                push_unproven_hit(terminal, ctx);
            }
        }
        return;
    }
    if !free_function_call_may_target(node, text, ctx) {
        return;
    }
    if ctx.visibility.contains_named_symbol(
        ctx.file,
        text,
        TargetKind::FreeFunction,
        &ctx.spec.target,
    ) {
        push_hit(function_terminal_node(function), ctx);
    } else if ctx.visibility.resolve_known_non_target(
        ctx.file,
        text,
        TargetKind::FreeFunction,
        &ctx.spec.target,
    ) {
        // An explicitly namespace-qualified call to a different namespace (e.g. `other::run()` when
        // the target is `ns::run`) is a proven non-match, not an unresolved reference.
    } else {
        push_unproven_hit(function_terminal_node(function), ctx);
    }
}

fn free_function_target_matches(unit: &CodeUnit, ctx: &ScanCtx<'_>) -> bool {
    same_visible_symbol(unit, &ctx.spec.target)
        || ctx
            .visibility
            .same_logical_callable(&ctx.analyzer, unit, &ctx.spec.target)
            && cpp_callable_definitions_share_identity_evidence_with_visibility(
                &ctx.analyzer,
                ctx.visibility,
                unit,
                &ctx.spec.target,
            )
}

/// Recover a bare call whose adjacent object-like macro arguments made
/// tree-sitter place a `function_declarator` directly under an `ERROR` node.
///
/// For example, `check(mount(A, PREFIX SUFFIX, 0))` loses the inner
/// `call_expression`, but retains `mount(...)` as a structured declarator. A
/// real block-scope function declaration remains under a `declaration`, so the
/// direct `ERROR` parent and compound-statement ancestry keep this recovery
/// out of declaration syntax. The malformed parameter list cannot establish
/// arity; publish a proven hit only when ordinary visibility leaves one
/// callable identity for the bare name.
fn maybe_record_recovered_error_free_function_call(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    // The macro-declaration grammar keeps the same call as a bogus
    // `function_definition` whose damaged declarator ends at the block
    // literal's `(`: its parameter list is the call's argument prefix, so
    // unlike the ERROR shape it carries countable arity evidence.
    let block_call_envelope = recovered_c_block_call_envelope(node).is_some();
    if !block_call_envelope
        && (ctx
            .ancestry
            .parent(node)
            .is_none_or(|parent| parent.kind() != "ERROR")
            || !has_ancestor_kind(node, "compound_statement"))
    {
        return;
    }
    let mut recovered_functions = Vec::new();
    if let Some(function) = node
        .child_by_field_name("declarator")
        .filter(|function| function.kind() == "identifier")
    {
        recovered_functions.push(function);
    }
    if let Some(parameters) = node.child_by_field_name("parameters") {
        let mut cursor = parameters.walk();
        for parameter in parameters
            .named_children(&mut cursor)
            .filter(|child| child.kind() == "parameter_declaration")
        {
            if parameter
                .child_by_field_name("declarator")
                .is_some_and(|declarator| declarator.kind() == "abstract_function_declarator")
                && let Some(function) = parameter
                    .child_by_field_name("type")
                    .filter(|function| function.kind() == "type_identifier")
            {
                recovered_functions.push(function);
            }
        }
    }

    for function in recovered_functions {
        let name = node_text(function, ctx.source);
        if !name_matches_callable(name, &ctx.spec.member_name)
            || ctx.local_shadows.is_shadowed(name)
        {
            continue;
        }
        *ctx.raw_match_count += 1;
        if block_call_envelope
            && let Some(expected) = ctx.spec.callable_arity_at(node.start_byte())
            && ctx
                .visibility
                .call_arity_evidence(ctx.file, node, ctx.source)
                .accepts(expected)
                == Some(false)
        {
            continue;
        }
        if bare_name_at_binds_only_target(function.start_byte(), name, ctx) {
            push_hit(function, ctx);
            continue;
        }
        let mut candidates =
            ctx.visibility
                .named_candidates(ctx.file, name, TargetKind::FreeFunction);
        candidates.retain(|candidate| {
            ctx.visibility.declaration_visible_at(
                &ctx.analyzer,
                ctx.file,
                candidate,
                function.start_byte(),
            )
        });
        dedupe_callable_candidates(&mut candidates, &ctx.analyzer, ctx.visibility);
        if candidates
            .iter()
            .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target))
        {
            push_unproven_hit(function, ctx);
        }
    }
}

/// Whether the bare name at `call` binds to exactly one visible callable, and
/// that callable is the scan target.
///
/// This is the scan-side reading of the #1811 rule: with one name binding there
/// is nothing an unknown argument count could select instead, so the site is a
/// proven reference rather than an unproven one. Only bare identifiers qualify;
/// a member or qualified call reaches its target through a receiver this cannot
/// judge.
fn bare_name_binds_only_target(
    call: Node<'_>,
    function: Node<'_>,
    text: &str,
    ctx: &ScanCtx<'_>,
) -> bool {
    if !matches!(function.kind(), "identifier" | "template_function") {
        return false;
    }
    bare_name_at_binds_only_target(call.start_byte(), text, ctx)
}

fn bare_name_at_binds_only_target(reference_byte: usize, text: &str, ctx: &ScanCtx<'_>) -> bool {
    let mut candidates = ctx
        .visibility
        .named_candidates(ctx.file, text, TargetKind::FreeFunction);
    candidates.retain(|candidate| {
        ctx.visibility
            .declaration_visible_at(&ctx.analyzer, ctx.file, candidate, reference_byte)
    });
    dedupe_callable_candidates(&mut candidates, &ctx.analyzer, ctx.visibility);
    matches!(candidates.as_slice(), [only] if same_visible_symbol(only, &ctx.spec.target))
}

fn free_function_call_may_target(call: Node<'_>, text: &str, ctx: &ScanCtx<'_>) -> bool {
    if ctx.spec.param_types.is_none() {
        return true;
    }
    let mut candidates = ctx
        .visibility
        .named_candidates(ctx.file, text, TargetKind::FreeFunction);
    candidates.retain(|candidate| {
        ctx.visibility
            .declaration_visible_at(&ctx.analyzer, ctx.file, candidate, call.start_byte())
    });
    callable_candidates_may_match_target(call, candidates, ctx)
}

fn callable_candidates_may_match_target(
    call: Node<'_>,
    mut candidates: Vec<CodeUnit>,
    ctx: &ScanCtx<'_>,
) -> bool {
    let Some(arity) = ctx
        .visibility
        .call_arity_evidence(ctx.file, call, ctx.source)
        .exact()
    else {
        return true;
    };
    candidates.retain(|unit| {
        cpp_callable_arity(&ctx.analyzer, unit).is_none_or(|known| known.accepts(arity))
    });
    if candidates.is_empty()
        || !candidates
            .iter()
            .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target))
    {
        return true;
    }
    let arg_types = call_argument_types(call, ctx);
    let filtered = cpp_filter_candidates_by_args_with_parameter_types(
        candidates,
        &arg_types,
        &|candidate| cpp_callable_parameter_types(&ctx.analyzer, candidate),
        &|candidate| {
            ctx.visibility
                .callable_is_template_declaration(&ctx.analyzer, candidate)
        },
        &|name| ctx.visibility.resolve_type(ctx.file, name),
        &|left, right| same_visible_symbol(left, right),
    );
    filtered
        .iter()
        .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target))
}

/// The types of the arguments an `argument_list` or `initializer_list` supplies,
/// in order.
///
/// A `None` entry is an argument the index cannot type; one of them makes
/// `cpp_filter_candidates_by_args` keep every candidate rather than guess.
fn argument_list_types(arguments: Node<'_>, ctx: &ScanCtx<'_>) -> Vec<Option<CppArgType>> {
    argument_children(arguments)
        .map(|arg| expression_arg_type(arg, ctx))
        .collect()
}

fn call_argument_types(call: Node<'_>, ctx: &ScanCtx<'_>) -> Vec<Option<CppArgType>> {
    call_arguments_node(call)
        .map(|arguments| argument_list_types(arguments, ctx))
        .unwrap_or_default()
}

fn expression_arg_type(node: Node<'_>, ctx: &ScanCtx<'_>) -> Option<CppArgType> {
    match node.kind() {
        "number_literal" | "true" | "false" | "char_literal" | "string_literal"
        | "unary_expression" => cpp_literal_arg_type(node, ctx.source).map(|mut literal| {
            literal.unit = ctx.visibility.resolve_type(ctx.file, &literal.name);
            literal
        }),
        "identifier" => identifier_arg_type(node, node_text(node, ctx.source), ctx),
        // `T v(x);` is the vexing parse: the grammar reads it as a function
        // declaration whose one parameter is `x` spelled as a type. A parameter
        // declaration that is nothing but a type identifier is that reading, and
        // the identifier it holds is the constructor argument.
        "parameter_declaration" => {
            let declared = node.child_by_field_name("type")?;
            (node.child_by_field_name("declarator").is_none()
                && declared.kind() == "type_identifier")
                .then(|| identifier_arg_type(declared, node_text(declared, ctx.source), ctx))
                .flatten()
        }
        // `this->m_params` names the same data member as the bare `m_params`.
        "field_expression" => {
            let receiver = node
                .child_by_field_name("argument")
                .or_else(|| node.named_child(0))?;
            let field = node.child_by_field_name("field")?;
            (receiver.kind() == "this")
                .then(|| enclosing_member_field_arg_type(node, node_text(field, ctx.source), ctx))
                .flatten()
        }
        "parenthesized_expression" => node
            .child_by_field_name("argument")
            .or_else(|| node.named_child(0))
            .and_then(|inner| expression_arg_type(inner, ctx)),
        // `std::move(t)` and `std::forward<T>(t)` have the type of what they
        // forward (#2552).
        "call_expression" => {
            let forwarded = cpp_forwarding_call_argument(node, ctx.source)?;
            expression_arg_type(forwarded, ctx)
        }
        "pointer_expression" => {
            let delta = match node.child_by_field_name("operator")?.kind() {
                "&" => 1,
                "*" => -1,
                _ => return None,
            };
            let inner = node
                .child_by_field_name("argument")
                .or_else(|| node.named_child(0))?;
            let mut arg_type = expression_arg_type(inner, ctx)?;
            arg_type.indirection += delta;
            Some(arg_type)
        }
        _ => None,
    }
}

/// The type of a bare value name used as a call argument: the local or
/// parameter binding when one is in scope, otherwise the enclosing class's data
/// member of that name.
///
/// Unqualified lookup reaches a local before a data member, so a local of the
/// same name ends the search rather than falling through to the field. This
/// mirrors `cpp_identifier_value_type` on the forward side, which is what keeps
/// the two directions agreeing about which overload a member-field argument
/// selects (#2894).
fn identifier_arg_type(node: Node<'_>, name: &str, ctx: &ScanCtx<'_>) -> Option<CppArgType> {
    match ctx.bindings.resolve_symbol(name) {
        SymbolResolution::Precise(bindings) => {
            bindings.iter().find_map(CppScanBinding::as_arg_type)
        }
        SymbolResolution::Ambiguous => None,
        SymbolResolution::Unknown => (!ctx.local_shadows.is_shadowed(name))
            .then(|| enclosing_member_field_arg_type(node, name, ctx))
            .flatten(),
    }
}

/// The declared type of `name` read as a data member of the class that lexically
/// owns `node`.
///
/// `None` when there is no enclosing class, when the name is not one data member
/// of it, or when the member's declared type does not resolve. An unknown
/// argument type makes the overload filter keep every candidate, which is the
/// honest answer for a field the index cannot type.
fn enclosing_member_field_arg_type(
    node: Node<'_>,
    name: &str,
    ctx: &ScanCtx<'_>,
) -> Option<CppArgType> {
    let owner = enclosing_context(node, ctx).owner?;
    let fields = ctx
        .visibility
        .visible_members_for_owner_name(ctx.file, &owner, name)
        .into_iter()
        .filter(|unit| unit.is_field())
        .collect::<Vec<_>>();
    let [field] = fields.as_slice() else {
        return None;
    };
    let (type_name, unit, indirection) =
        field_declared_type_binding(&ctx.analyzer, ctx.visibility, ctx.file, field)?;
    Some(CppArgType {
        name: type_name,
        unit,
        indirection,
        pointee_const: false,
    })
}

/// Record a *non-call* reference to a free function used as a value: `&foo`,
/// `fp = foo`, `foo` passed as an argument, etc. The callee identifier of a call
/// `foo()` is recorded by the call_expression arm, and the function's own
/// declaration/definition name is not a reference.
fn maybe_record_free_function_value_reference(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let text = node_text(node, ctx.source);
    if !name_matches_callable(text, &ctx.spec.member_name) {
        return;
    }
    if let Some(kind) = recovered_callable_declaration_kind(node, ctx) {
        *ctx.raw_match_count += 1;
        match kind {
            RecoveredCallableDeclarationKind::Declaration => push_declared_reference_hit(node, ctx),
            RecoveredCallableDeclarationKind::Definition => {
                push_recovered_definition_hit(node, ctx)
            }
        }
        return;
    }
    if is_declaration_name(node) {
        maybe_record_free_function_declaration_reference(node, ctx);
        return;
    }
    if is_call_callee_node(node) {
        return;
    }
    *ctx.raw_match_count += 1;
    if ctx.visibility.contains_named_symbol(
        ctx.file,
        text,
        TargetKind::FreeFunction,
        &ctx.spec.target,
    ) {
        push_hit(node, ctx);
    } else if ctx.visibility.resolve_known_non_target(
        ctx.file,
        text,
        TargetKind::FreeFunction,
        &ctx.spec.target,
    ) {
        // A qualified reference proven to a different namespace is not a match.
    } else {
        push_unproven_hit(node, ctx);
    }
}

#[derive(Clone, Copy)]
enum RecoveredCallableDeclarationKind {
    Declaration,
    Definition,
}

/// Recover the role of a callable name whose declaration was split by an
/// ERROR node. An indexed declaration range proves identity when available;
/// for a top-level C callable that recovery failed to range-index, same-file
/// name identity is sufficient because C has no function overloading. The CST
/// shape distinguishes a prototype from a definition. C++ parsing of
/// an unknown C return type can put the name under an ERROR child of the
/// function declarator, while call-shaped recovery puts that declarator under
/// an ERROR whose parent is a compound statement; only the former is admitted.
fn recovered_callable_declaration_kind(
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> Option<RecoveredCallableDeclarationKind> {
    if !matches!(node.kind(), "identifier" | "field_identifier") {
        return None;
    }
    let target_identity_proven =
        ctx.target_declaration_ranges.iter().any(|range| {
            range.start_byte <= node.start_byte() && node.end_byte() <= range.end_byte
        }) || (ctx.analyzer.reference_uses_c_semantics(ctx.file)
            && ctx.spec.target.is_function()
            && ctx.spec.target.source() == ctx.file);
    let mut current = ctx.ancestry.parent(node);
    while let Some(parent) = current {
        if parent.is_error() {
            // C files with an unknown return type can retain the real
            // callable name as `function_declarator > ERROR`, with the ERROR
            // as a named child rather than the declarator field itself.
            let error = parent;
            let Some(function) = ctx.ancestry.parent(error).filter(|function| {
                function.kind() == "function_declarator"
                    && function
                        .child_by_field_name("parameters")
                        .is_some_and(|parameters| error.end_byte() <= parameters.start_byte())
            }) else {
                current = ctx.ancestry.parent(parent);
                continue;
            };
            let container = ctx.ancestry.parent(function)?;
            let kind = match container.kind() {
                "declaration" => RecoveredCallableDeclarationKind::Declaration,
                "function_definition" => RecoveredCallableDeclarationKind::Definition,
                _ => return None,
            };
            return target_identity_proven.then_some(kind);
        }
        if parent.kind() == "function_declarator" {
            let error = ctx
                .ancestry
                .parent(parent)
                .filter(|parent| parent.is_error())?;
            let declarator = parent.child_by_field_name("declarator")?;
            if declarator.start_byte() > node.start_byte()
                || node.end_byte() > declarator.end_byte()
            {
                return None;
            }
            let container = ctx.ancestry.parent(error)?;
            let kind = match container.kind() {
                "declaration" => RecoveredCallableDeclarationKind::Declaration,
                "function_definition" => RecoveredCallableDeclarationKind::Definition,
                _ => return None,
            };
            return target_identity_proven.then_some(kind);
        }
        if parent.is_error() {
            current = ctx.ancestry.parent(parent);
            continue;
        }
        if matches!(
            parent.kind(),
            "translation_unit" | "function_definition" | "compound_statement"
        ) {
            return None;
        }
        current = ctx.ancestry.parent(parent);
    }
    None
}

fn maybe_record_free_function_declaration_reference(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if !ctx.spec.callable_has_definition_body {
        return;
    }
    let text = node_text(node, ctx.source);
    if !name_matches_callable(text, &ctx.spec.member_name) {
        return;
    }
    let mut declaration = ctx.ancestry.parent(node);
    while let Some(candidate) = declaration {
        if candidate.kind() == "function_definition" {
            return;
        }
        if candidate.kind() == "declaration" {
            break;
        }
        declaration = ctx.ancestry.parent(candidate);
    }
    if declaration.is_none() {
        return;
    }
    let linked_declaration = ctx
        .visibility
        .named_candidates(ctx.file, text, TargetKind::FreeFunction)
        .into_iter()
        .find(|candidate| {
            candidate.source() == ctx.file
                && candidate.is_function()
                && (!ctx.target_group.contains(candidate)
                    || candidate.source() == ctx.spec.target.source())
                && ctx.analyzer.ranges(candidate).iter().any(|range| {
                    range.start_byte <= node.start_byte() && node.end_byte() <= range.end_byte
                })
                && (candidate.source() == ctx.spec.target.source()
                    && candidate.fq_name() == ctx.spec.target.fq_name()
                    && candidate.signature() == ctx.spec.target.signature()
                    || cpp_callable_definitions_share_identity_evidence_with_visibility(
                        &ctx.analyzer,
                        ctx.visibility,
                        candidate,
                        &ctx.spec.target,
                    ))
                && callable_arity_matches_target(candidate, node, ctx)
        });
    if linked_declaration.is_none() {
        return;
    }
    *ctx.raw_match_count += 1;
    push_declaration_reference_hit(node, ctx);
}

fn maybe_record_free_function_definition_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let Some(function) = function_definition_name_node(node) else {
        return;
    };
    let text = node_text(function, ctx.source);
    if !name_matches_callable(text, &ctx.spec.member_name) {
        return;
    }
    *ctx.raw_match_count += 1;
    if !function_definition_signature_matches_target(node, ctx) {
        return;
    }
    match definition_name_target_resolution(function, TargetKind::FreeFunction, ctx) {
        DefinitionNameTargetResolution::Target => push_definition_hit(function, ctx),
        DefinitionNameTargetResolution::KnownNonTarget => {
            // A definition in another explicit namespace is a proven non-match.
        }
        DefinitionNameTargetResolution::Unresolved => push_unproven_definition_hit(function, ctx),
    }
}

fn maybe_record_method_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if node.kind() == "preproc_arg" {
        maybe_record_function_macro_replacement_method_hits(node, ctx);
        return;
    }
    if node.kind() == "using_declaration" {
        maybe_record_using_callable_hit(node, ctx);
        return;
    }
    if has_ancestor_kind(node, "using_declaration") {
        return;
    }
    if node.kind() == "function_definition" {
        maybe_record_method_definition_hit(node, ctx);
        return;
    }
    if is_declaration_name(node) {
        return;
    }
    if let Some(member) = recovered_direct_initializer_qualified_callable(node) {
        maybe_record_qualified_method_value_hit(node, member, ctx);
        return;
    }
    if let Some(value) = qualified_callable_value(node) {
        maybe_record_qualified_method_value_hit(value.qualified, value.member, ctx);
        return;
    }
    if let Some(call) = recovered_relational_template_member_call(node) {
        maybe_record_recovered_relational_template_method_hit(call, ctx);
        return;
    }
    if node.kind() != "call_expression" {
        return;
    }
    if let Some((receiver, operator)) = explicit_operator_call(node) {
        let text = node_text(operator, ctx.source);
        if !name_matches_callable(text, &ctx.spec.member_name) {
            return;
        }
        *ctx.raw_match_count += 1;
        if let Some(expected) = ctx.spec.callable_arity_at(node.start_byte()) {
            match ctx
                .visibility
                .call_arity_evidence(ctx.file, node, ctx.source)
                .accepts(expected)
            {
                Some(true) => {}
                Some(false) => return,
                None => {
                    push_unproven_hit(operator, ctx);
                    return;
                }
            }
        }
        let arity = ctx
            .visibility
            .call_arity_evidence(ctx.file, node, ctx.source)
            .exact();
        record_explicit_receiver_method_hit(receiver, operator, arity, ctx);
        return;
    }
    let Some(function) = node
        .child_by_field_name("function")
        .or_else(|| node.named_child(0))
    else {
        return;
    };
    if !callable_node_matches(function, &ctx.spec.member_name, ctx.source) {
        return;
    }
    if function.kind() == "identifier"
        && ctx
            .local_shadows
            .is_shadowed(node_text(function, ctx.source))
    {
        return;
    }
    *ctx.raw_match_count += 1;
    if let Some(expected) = ctx.spec.callable_arity_at(node.start_byte()) {
        match ctx
            .visibility
            .call_arity_evidence(ctx.file, node, ctx.source)
            .accepts(expected)
        {
            Some(true) => {}
            Some(false) => return,
            None => {
                push_unproven_hit(function_terminal_node(function), ctx);
                return;
            }
        }
    }
    if !method_call_may_target(node, ctx) {
        return;
    }
    if is_structurally_qualified(function) {
        match qualified_owner_resolution(function, ctx) {
            QualifiedOwnerResolution::Target => {
                push_hit(function_terminal_node(function), ctx);
            }
            QualifiedOwnerResolution::NonTarget => {}
            QualifiedOwnerResolution::Unresolved => {
                push_unproven_hit(function_terminal_node(function), ctx);
            }
        }
        return;
    }
    match call_function_target_resolution(function, ctx) {
        MethodReceiverTargetResolution::Target
            if call_function_has_direct_self_receiver(
                function,
                ctx.analyzer.reference_uses_c_semantics(ctx.file),
            ) =>
        {
            push_self_receiver_hit(function_terminal_node(function), ctx);
        }
        MethodReceiverTargetResolution::Target => {
            push_hit(function_terminal_node(function), ctx);
        }
        MethodReceiverTargetResolution::NonTarget | MethodReceiverTargetResolution::Ambiguous => {}
        // A bare `m()` whose name resolves through the enclosing class's base hierarchy to
        // the target member declared on a base is a genuine external usage of that inherited
        // base member (e.g. `Derived::run` calling inherited `Base::value`), so it is an
        // ordinary Reference hit -- not a same-type self call. Checked before the self-owner
        // arm because `same_owner_context` also accepts this inherited case.
        MethodReceiverTargetResolution::Missing
            if inherited_target_owner_context(function, ctx) =>
        {
            push_hit(function_terminal_node(function), ctx);
        }
        MethodReceiverTargetResolution::Missing
            if (matches!(function.kind(), "identifier" | "template_function")
                || call_function_has_direct_self_receiver(
                    function,
                    ctx.analyzer.reference_uses_c_semantics(ctx.file),
                ))
                && (same_owner_context(function, ctx)
                    || out_of_line_target_owner_context(function, ctx)) =>
        {
            push_self_receiver_hit(function_terminal_node(function), ctx);
        }
        MethodReceiverTargetResolution::Missing
            if function.kind() == "identifier"
                && resolves_to_lexical_free_function(function, ctx) =>
        {
            // A visible namespace/free function is a proven negative once the
            // enclosing structured owner and its hierarchy contain no such member.
        }
        MethodReceiverTargetResolution::Missing
            if !receiver_has_known_non_target(function, ctx)
                && !known_non_target_owner_context(function, ctx) =>
        {
            push_unproven_hit(function_terminal_node(function), ctx);
        }
        MethodReceiverTargetResolution::Missing => {}
    }
}

/// Report member calls written inside a function-like macro's replacement.
///
/// Tree-sitter keeps the whole replacement of `#define NAME(a) ...` as one
/// opaque `preproc_arg`, so the ordinary member-call path never sees the calls
/// it contains (#2549). The resolver's shared sentinel parse recovers them as
/// structure, and every hit is reported at the bytes the member spells inside
/// that token.
fn maybe_record_function_macro_replacement_method_hits(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let Some(definition) = ctx.ancestry.parent(node).filter(|parent| {
        parent.kind() == "preproc_function_def"
            && parent
                .child_by_field_name("value")
                .is_some_and(|value| same_node(value, node))
    }) else {
        return;
    };
    let Some(body) = ctx
        .visibility
        .function_macro_replacement_body(ctx.file, definition, ctx.source)
    else {
        return;
    };
    let Some(statements) = body.statements() else {
        return;
    };
    // Collect the candidate calls before typing anything: a replacement that
    // never names the queried member must not pay for its declarations.
    let mut candidates = Vec::new();
    let mut stack = vec![statements];
    while let Some(current) = stack.pop() {
        push_named_children_reversed(current, &mut stack);
        if current.kind() != "call_expression" {
            continue;
        }
        let Some(function) = current
            .child_by_field_name("function")
            .filter(|function| function.kind() == "field_expression")
        else {
            continue;
        };
        let Some(member) = function.child_by_field_name("field") else {
            continue;
        };
        if !name_matches_callable(node_text(member, &body.source), &ctx.spec.member_name) {
            continue;
        }
        let Some(receiver) = function
            .child_by_field_name("argument")
            .or_else(|| function.child_by_field_name("object"))
            .or_else(|| function.named_child(0))
        else {
            continue;
        };
        candidates.push((current, member, receiver));
    }
    if candidates.is_empty() {
        return;
    }
    let Some(replacement_start) =
        function_macro_replacement_span(definition, ctx.source).map(|span| span.start)
    else {
        return;
    };
    let locals = macro_replacement_local_receivers(statements, &body, ctx);
    for (current, member, receiver) in candidates {
        if *ctx.limit_exceeded {
            return;
        }
        let range = body.file_range(member, replacement_start);
        debug_assert_eq!(
            ctx.source.get(range.clone()),
            Some(node_text(member, &body.source)),
            "macro replacement member range must spell the member name"
        );
        *ctx.raw_match_count += 1;
        // The replacement's own macro environment is the one at the definition,
        // not at the sentinel offsets the recovered call carries.
        let arity_evidence = ctx.visibility.call_arity_evidence_at(
            ctx.file,
            current,
            &body.source,
            definition.start_byte(),
        );
        if let Some(expected) = ctx.spec.callable_arity_at(range.start) {
            match arity_evidence.accepts(expected) {
                Some(true) => {}
                Some(false) => continue,
                None => {
                    push_unproven_reference_hit_range(node, range.start, range.end, ctx);
                    continue;
                }
            }
        }
        let declaring_owner = match macro_replacement_receiver(receiver, &body, &locals, node, ctx)
        {
            MacroReplacementReceiver::Parameter => {
                if target_member_is_visible_candidate(ctx) {
                    push_unproven_reference_hit_range(node, range.start, range.end, ctx);
                }
                continue;
            }
            MacroReplacementReceiver::Unknown => continue,
            MacroReplacementReceiver::Units(units) => {
                declaring_owner_from_receiver_units(units, range.start, arity_evidence.exact(), ctx)
            }
        };
        match declaring_owner_target_resolution(declaring_owner, range.start, ctx) {
            MethodReceiverTargetResolution::Target => {
                push_reference_hit_range(node, range.start, range.end, ctx);
            }
            MethodReceiverTargetResolution::Missing => {
                push_unproven_reference_hit_range(node, range.start, range.end, ctx);
            }
            MethodReceiverTargetResolution::NonTarget
            | MethodReceiverTargetResolution::Ambiguous => {}
        }
    }
}

enum MacroReplacementReceiver {
    /// The receiver is one of the macro's parameters. Its type is supplied by
    /// each invocation, so a member call on it can never be proven here.
    Parameter,
    /// The receiver's declared type resolved to these units.
    Units(Vec<CodeUnit>),
    /// The receiver has a shape this path does not type.
    Unknown,
}

fn macro_replacement_receiver(
    receiver: Node<'_>,
    body: &ParsedReplacementBody,
    locals: &HashMap<String, Option<CodeUnit>>,
    anchor: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> MacroReplacementReceiver {
    let mut current = receiver;
    while matches!(
        current.kind(),
        "parenthesized_expression" | "pointer_expression"
    ) {
        let Some(inner) = current
            .child_by_field_name("argument")
            .or_else(|| current.named_child(0))
        else {
            return MacroReplacementReceiver::Unknown;
        };
        current = inner;
    }
    if !matches!(current.kind(), "identifier" | "field_identifier") {
        return MacroReplacementReceiver::Unknown;
    }
    let name = node_text(current, &body.source);
    if body.parameters.iter().any(|parameter| parameter == name) {
        return MacroReplacementReceiver::Parameter;
    }
    if let Some(local) = locals.get(name) {
        return match local {
            Some(unit) => MacroReplacementReceiver::Units(vec![unit.clone()]),
            None => MacroReplacementReceiver::Unknown,
        };
    }
    // Neither a parameter nor a replacement-local: an ordinary name the macro
    // definition site sees, resolved exactly as the ordinary receiver path
    // resolves a bare identifier.
    let global_fields = ctx
        .visibility
        .visible_identifier_candidates(ctx.file, name)
        .filter(|unit| has_persisted_global_field_identity(unit) && unit.identifier() == name)
        .collect::<Vec<_>>();
    if !global_fields.is_empty() {
        return MacroReplacementReceiver::Units(receiver_units_from_declared_fields(
            global_fields,
            anchor,
            ctx,
        ));
    }
    MacroReplacementReceiver::Units(
        ctx.visibility
            .resolve_type(ctx.file, name)
            .into_iter()
            .collect(),
    )
}

/// Type the locals a macro replacement declares, keyed by declared name.
///
/// `Catch::AssertionHandler h(expr); h.handleExpr(expr);` is the shape this
/// serves: the receiver's type is stated inside the replacement itself. A name
/// whose declared type does not resolve is kept with no unit, so a call on it
/// stays silent instead of falling through to file-scope name lookup.
fn macro_replacement_local_receivers(
    statements: Node<'_>,
    body: &ParsedReplacementBody,
    ctx: &ScanCtx<'_>,
) -> HashMap<String, Option<CodeUnit>> {
    let mut locals = HashMap::default();
    let mut stack = vec![statements];
    while let Some(current) = stack.pop() {
        push_named_children_reversed(current, &mut stack);
        if current.kind() != "declaration" {
            continue;
        }
        let Some(type_node) = current
            .child_by_field_name("type")
            .or_else(|| first_type_child(current))
        else {
            continue;
        };
        let unit = macro_replacement_declared_unit(type_node, body, ctx);
        let mut cursor = current.walk();
        for child in current.named_children(&mut cursor) {
            let declarator = if child.kind() == "init_declarator" {
                child.child_by_field_name("declarator")
            } else {
                is_declarator_node(child).then_some(child)
            };
            let Some(name) =
                declarator.and_then(|declarator| extract_variable_name(declarator, &body.source))
            else {
                continue;
            };
            locals.insert(name, unit.clone());
        }
    }
    locals
}

fn macro_replacement_declared_unit(
    type_node: Node<'_>,
    body: &ParsedReplacementBody,
    ctx: &ScanCtx<'_>,
) -> Option<CodeUnit> {
    let name = normalize_cpp_type_name(node_text(type_node, &body.source));
    let unit = match ctx
        .visibility
        .resolve_type_node_result(ctx.file, type_node, &body.source)
    {
        Ok(Some(unit)) => Some(unit),
        Ok(None) => ctx
            .visibility
            .canonical_type_for_reference(ctx.file, &name)
            .or_else(|| ctx.visibility.resolve_type(ctx.file, &name)),
        Err(_) => None,
    }?;
    canonical_receiver_unit(&unit, ctx)
}

/// Whether the queried member is a candidate this file can see.
///
/// A macro parameter receiver has no type at the definition, so a member call
/// on it is at most unproven. Requiring the target to be visible here keeps a
/// same-named member of an unrelated translation unit out of the result.
fn target_member_is_visible_candidate(ctx: &ScanCtx<'_>) -> bool {
    ctx.visibility
        .visible_identifier_candidates(ctx.file, &ctx.spec.member_name)
        .any(|candidate| same_visible_symbol(candidate, &ctx.spec.target))
}

fn maybe_record_recovered_relational_template_method_hit(
    call: RecoveredRelationalTemplateMemberCall<'_>,
    ctx: &mut ScanCtx<'_>,
) {
    if !callable_node_matches(call.member, &ctx.spec.member_name, ctx.source) {
        return;
    }
    *ctx.raw_match_count += 1;
    if !ctx
        .visibility
        .callable_is_template_declaration(&ctx.analyzer, &ctx.spec.target)
        || ctx
            .spec
            .callable_arity_at(call.member.start_byte())
            .is_some_and(|arity| !arity.accepts(call.arity))
    {
        return;
    }
    record_explicit_receiver_method_hit(call.receiver, call.member, Some(call.arity), ctx);
}

fn record_explicit_receiver_method_hit(
    receiver: Node<'_>,
    member: Node<'_>,
    arity: Option<usize>,
    ctx: &mut ScanCtx<'_>,
) {
    match explicit_receiver_target_resolution(receiver, arity, ctx) {
        MethodReceiverTargetResolution::Target
            if receiver_is_self_like(
                receiver,
                ctx.analyzer.reference_uses_c_semantics(ctx.file),
            ) =>
        {
            push_self_receiver_hit(member, ctx);
        }
        MethodReceiverTargetResolution::Target => push_hit(member, ctx),
        MethodReceiverTargetResolution::Missing => push_unproven_hit(member, ctx),
        MethodReceiverTargetResolution::NonTarget | MethodReceiverTargetResolution::Ambiguous => {}
    }
}

fn recovered_direct_initializer_qualified_callable(node: Node<'_>) -> Option<Node<'_>> {
    if node.kind() != "qualified_identifier" {
        return None;
    }
    let parameter = node
        .parent()
        .filter(|parent| parent.kind() == "parameter_declaration")?;
    let parameter_declarator = parameter.child_by_field_name("declarator")?;
    // Tree-sitter recovers `Value value(Owner::method(arg));` as a function
    // declaration whose sole pseudo-parameter has `Owner::method` as its type
    // and `(arg)` as an abstract function declarator. Ordinary qualified
    // parameter types have named/pointer/reference declarators instead.
    if parameter.child_by_field_name("type") != Some(node)
        || parameter_declarator.kind() != "abstract_function_declarator"
    {
        return None;
    }
    let parameter_list = parameter
        .parent()
        .filter(|parent| parent.kind() == "parameter_list")?;
    if parameter_list.named_child_count() != 1 {
        return None;
    }
    let function_declarator = parameter_list
        .parent()
        .filter(|parent| parent.kind() == "function_declarator")?;
    if function_declarator
        .child_by_field_name("declarator")
        .is_none_or(|declarator| declarator.kind() != "identifier")
        || function_declarator
            .parent()
            .is_none_or(|parent| parent.kind() != "declaration")
    {
        return None;
    }
    node.child_by_field_name("name")
}

fn maybe_record_using_callable_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let Some(imported) = ordinary_using_declaration_type_node(node) else {
        return;
    };
    if !callable_node_matches(imported, &ctx.spec.member_name, ctx.source) {
        return;
    }
    let Some(target_owner) = ctx.spec.owner.as_ref() else {
        return;
    };
    *ctx.raw_match_count += 1;
    let owner_resolution = qualified_owner_components(imported, ctx.source)
        .map(|qualified| {
            let lexical_scope = match enclosing_lexical_scope_components(
                imported,
                &ctx.analyzer,
                ctx.visibility,
                ctx.file,
                ctx.source,
            ) {
                LexicalScopeResolution::Resolved(scope) => scope,
                LexicalScopeResolution::Ambiguous => return LexicalTypeResolution::Ambiguous,
                LexicalScopeResolution::Missing => return LexicalTypeResolution::Missing,
            };
            ctx.visibility.resolve_type_components_lexically(
                &ctx.analyzer,
                ctx.file,
                &qualified.names,
                qualified.global,
                &lexical_scope,
            )
        })
        .unwrap_or(LexicalTypeResolution::Missing);
    let matches_target_owner = matches!(
        owner_resolution,
        LexicalTypeResolution::Resolved {
            ref unit,
            ref candidates,
            ..
        } if same_visible_symbol(unit, target_owner)
            || candidates
                .iter()
                .any(|candidate| same_visible_symbol(candidate, target_owner))
    );
    if !matches_target_owner {
        match owner_resolution {
            LexicalTypeResolution::Ambiguous | LexicalTypeResolution::Missing => {
                push_unproven_hit(imported, ctx);
            }
            LexicalTypeResolution::Resolved { .. } => {}
        }
        return;
    }
    match visible_target_callable_member_resolution(target_owner, ctx) {
        VisibleTargetCallableMemberResolution::Target => push_hit(imported, ctx),
        VisibleTargetCallableMemberResolution::NonCallable => {}
        VisibleTargetCallableMemberResolution::Unresolved => push_unproven_hit(imported, ctx),
    }
}

enum VisibleTargetCallableMemberResolution {
    Target,
    NonCallable,
    Unresolved,
}

fn visible_target_callable_member_resolution(
    owner: &CodeUnit,
    ctx: &ScanCtx<'_>,
) -> VisibleTargetCallableMemberResolution {
    match ctx
        .visibility
        .visible_member_for_owner_name(ctx.file, owner, &ctx.spec.member_name)
    {
        VisibleMemberResolution::Callable(candidates)
            if candidates.iter().all(|candidate| {
                ctx.target_group.contains(candidate)
                    || ctx
                        .target_group
                        .iter()
                        .any(|target| same_visible_symbol(candidate, target))
            }) =>
        {
            VisibleTargetCallableMemberResolution::Target
        }
        VisibleMemberResolution::NonCallable => VisibleTargetCallableMemberResolution::NonCallable,
        VisibleMemberResolution::Callable(_)
        | VisibleMemberResolution::AmbiguousKind
        | VisibleMemberResolution::Missing => VisibleTargetCallableMemberResolution::Unresolved,
    }
}

fn resolves_to_lexical_free_function(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let name = node_text(node, ctx.source);
    let namespace = enclosing_namespace_components(node, ctx.source).join(".");
    let key = (namespace.clone(), name.to_string());
    if let Some(resolved) = ctx.lexical_free_function_cache.borrow().get(&key).copied() {
        return resolved;
    }
    let resolved = ctx
        .visibility
        .visible_identifier_candidates(ctx.file, name)
        .any(|unit| {
            unit.is_function()
                && type_owner_of(&ctx.analyzer, unit).is_none()
                && unit.package_name() == namespace
        });
    ctx.lexical_free_function_cache
        .borrow_mut()
        .insert(key, resolved);
    resolved
}

fn maybe_record_qualified_method_value_hit(
    qualified: Node<'_>,
    member: Node<'_>,
    ctx: &mut ScanCtx<'_>,
) {
    if !name_matches_callable(node_text(member, ctx.source), &ctx.spec.member_name) {
        return;
    }
    *ctx.raw_match_count += 1;
    let resolution =
        qualified_callable_value_resolution(qualified, node_text(member, ctx.source), ctx);
    match resolution {
        LexicalCallableValueResolution::Type(resolved_owner) => {
            let Some(owner) = ctx.spec.owner.as_ref() else {
                push_unproven_hit(member, ctx);
                return;
            };
            if !receiver_owner_matches_target(&resolved_owner, owner, member.start_byte(), ctx) {
                if same_visible_symbol(&resolved_owner, owner) {
                    push_unproven_hit(member, ctx);
                }
                return;
            }
            // An explicitly qualified method value remains an external
            // reference even when its owner is the enclosing class.
            match visible_target_callable_member_resolution(owner, ctx) {
                VisibleTargetCallableMemberResolution::Target => push_hit(member, ctx),
                VisibleTargetCallableMemberResolution::NonCallable => {}
                VisibleTargetCallableMemberResolution::Unresolved => {
                    push_unproven_hit(member, ctx);
                }
            }
        }
        LexicalCallableValueResolution::FreeFunction(_) => {}
        LexicalCallableValueResolution::Ambiguous | LexicalCallableValueResolution::Missing => {
            push_unproven_hit(member, ctx);
        }
    }
}

fn qualified_callable_value_resolution(
    qualified: Node<'_>,
    member_name: &str,
    ctx: &ScanCtx<'_>,
) -> LexicalCallableValueResolution {
    let Some((owner_components, global)) =
        qualified_callable_owner_components(qualified, ctx.source)
    else {
        return LexicalCallableValueResolution::Missing;
    };
    let lexical_scope = if global {
        Vec::new()
    } else {
        match enclosing_lexical_scope_components(
            qualified,
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            ctx.source,
        ) {
            LexicalScopeResolution::Resolved(scope) => scope,
            LexicalScopeResolution::Ambiguous => {
                return LexicalCallableValueResolution::Ambiguous;
            }
            LexicalScopeResolution::Missing => return LexicalCallableValueResolution::Missing,
        }
    };
    if let Some(target_owner) = ctx.spec.owner.as_ref()
        && let LexicalTypeResolution::Resolved { unit, .. } =
            resolve_type_components_lexically_at_for_target_with_scope_cache(
                qualified,
                &owner_components,
                global,
                &ctx.analyzer,
                ctx.visibility,
                &ctx.ordinary_type_imports,
                ctx.file,
                ctx.source,
                target_owner,
                false,
                Some(&ctx.lexical_scope_cache),
            )
    {
        return LexicalCallableValueResolution::Type(unit);
    }
    ctx.visibility.resolve_callable_value_components_lexically(
        &ctx.analyzer,
        ctx.file,
        &owner_components,
        member_name,
        global,
        &lexical_scope,
    )
}

fn method_call_may_target(call: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let Some(owner) = ctx.spec.owner.as_ref() else {
        return true;
    };
    if ctx.spec.param_types.is_none() {
        return true;
    }
    let candidates = ctx
        .visibility
        .visible_members_for_owner_name(ctx.file, owner, &ctx.spec.member_name)
        .into_iter()
        .filter(|unit| unit.is_function())
        .cloned()
        .collect::<Vec<_>>();
    callable_candidates_may_match_target(call, candidates, ctx)
}

fn maybe_record_method_definition_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    let Some(function) = function_definition_name_node(node) else {
        return;
    };
    if !callable_node_matches(function, &ctx.spec.member_name, ctx.source) {
        return;
    }
    *ctx.raw_match_count += 1;
    if !function_definition_signature_matches_target(node, ctx) {
        return;
    }
    if node_inside_target_declaration(function, ctx) {
        return;
    }
    if is_structurally_qualified(function) {
        match qualified_owner_resolution(function, ctx) {
            QualifiedOwnerResolution::Target => push_definition_hit(function, ctx),
            QualifiedOwnerResolution::NonTarget => {}
            QualifiedOwnerResolution::Unresolved => push_unproven_definition_hit(function, ctx),
        }
        return;
    }
    match definition_name_target_resolution(function, TargetKind::Method, ctx) {
        DefinitionNameTargetResolution::Target => push_definition_hit(function, ctx),
        DefinitionNameTargetResolution::KnownNonTarget => {
            // A method definition for another visible owner is a proven non-match.
        }
        DefinitionNameTargetResolution::Unresolved
            if known_non_target_owner_context(function, ctx) => {}
        DefinitionNameTargetResolution::Unresolved => push_unproven_definition_hit(function, ctx),
    }
}

pub(super) fn node_inside_target_declaration(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let node_range = brokk_bifrost_core::analyzer::tree_walk::node_range(node);
    ctx.target_declaration_ranges
        .iter()
        .any(|range| range.contains(&node_range))
}

fn explicit_operator_call(node: Node<'_>) -> Option<(Node<'_>, Node<'_>)> {
    let mut receiver = None;
    let mut cursor = node.walk();
    for child in node.named_children(&mut cursor) {
        if child.kind() == "argument_list" {
            continue;
        }
        if let Some(operator) = first_descendant_of_kind(child, "operator_name") {
            return receiver.map(|receiver| (receiver, operator));
        }
        if receiver.is_none() {
            receiver = Some(child);
        }
    }
    None
}

/// Return the name node of a C++ function definition's declarator.
pub fn function_definition_name_node(node: Node<'_>) -> Option<Node<'_>> {
    if node.kind() != "function_definition" {
        return None;
    }
    node.child_by_field_name("declarator")
        .and_then(declarator_name_node)
}

fn function_definition_owner_lookup_node(node: Node<'_>) -> Option<Node<'_>> {
    function_definition_name_node(node)
}

fn function_definition_signature_matches_target(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let Some(expected) = ctx.spec.callable_arity_at(node.start_byte()) else {
        return true;
    };
    let Some(candidate) = canonical_callable_at_node(
        node,
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        ctx.source,
        ctx.spec.kind,
    ) else {
        return false;
    };
    let Some(actual_arity) = cpp_callable_arity(&ctx.analyzer, &candidate) else {
        return false;
    };
    if !callable_arity_matches(expected, actual_arity) {
        return false;
    }
    ctx.spec.param_types.as_ref().is_none_or(|expected| {
        cpp_callable_parameter_types(&ctx.analyzer, &candidate)
            .is_some_and(|actual| actual == *expected)
    })
}

fn callable_arity_matches_target(candidate: &CodeUnit, node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let Some(expected) = ctx.spec.callable_arity_at(node.start_byte()) else {
        return true;
    };
    cpp_callable_arity(&ctx.analyzer, candidate)
        .is_some_and(|actual| callable_arity_matches(expected, actual))
}

fn callable_arity_matches(
    expected: brokk_bifrost_core::analyzer::model::CallableArity,
    actual: brokk_bifrost_core::analyzer::model::CallableArity,
) -> bool {
    expected.accepts(actual.total())
}

fn canonical_callable_at_node(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    source: &str,
    kind: TargetKind,
) -> Option<CodeUnit> {
    let name = callable_name_node(node)?;
    let name_range = (name.start_byte(), name.end_byte());
    let name_text = node_text(name, source);
    for candidate in visibility.named_candidates(file, name_text, kind) {
        if candidate.source() != file || !candidate.is_function() {
            continue;
        }
        let Some(occurrences) = analyzer.declaration_source_occurrences(&candidate) else {
            continue;
        };
        for occurrence in occurrences {
            if occurrence
                .name_range
                .is_some_and(|range| (range.start_byte, range.end_byte) == name_range)
            {
                return Some(candidate);
            }
        }
    }
    None
}

fn callable_name_node(node: Node<'_>) -> Option<Node<'_>> {
    let name = if node.kind() == "function_definition" {
        function_definition_name_node(node)?
    } else {
        node.child_by_field_name("declarator")
            .and_then(declarator_name_node)?
    };
    Some(function_terminal_node(name))
}

fn callable_node_matches(node: Node<'_>, expected: &str, source: &str) -> bool {
    name_matches_callable(node_text(function_terminal_node(node), source), expected)
}

enum DefinitionNameTargetResolution {
    Target,
    KnownNonTarget,
    Unresolved,
}

fn definition_name_target_resolution(
    function: Node<'_>,
    target_kind: TargetKind,
    ctx: &ScanCtx<'_>,
) -> DefinitionNameTargetResolution {
    let candidates = definition_name_candidates(function, ctx);
    if candidates
        .iter()
        .filter(|name| target_kind != TargetKind::Method || name.contains("::"))
        .any(|name| {
            ctx.visibility
                .contains_named_symbol(ctx.file, name, target_kind, &ctx.spec.target)
        })
    {
        DefinitionNameTargetResolution::Target
    } else if candidates.iter().any(|name| {
        ctx.visibility
            .resolve_known_non_target(ctx.file, name, target_kind, &ctx.spec.target)
    }) {
        DefinitionNameTargetResolution::KnownNonTarget
    } else {
        DefinitionNameTargetResolution::Unresolved
    }
}

fn definition_name_candidates(function: Node<'_>, ctx: &ScanCtx<'_>) -> Vec<String> {
    let raw = normalize_cpp_reference_text(node_text(function, ctx.source));
    if raw.is_empty() {
        return Vec::new();
    }
    let Some(namespace) = enclosing_namespace_context(function, ctx.source) else {
        return vec![raw];
    };
    if !raw.contains("::") {
        return vec![format!("{namespace}::{raw}")];
    }
    // fqname-M4: peeks at the raw first `::`-split token, including the empty
    // token a leading-`::` absolute reference (`::Foo::Bar`) produces (same
    // shape as rust's `rust_reference_looks_external`); the shared structured
    // splitter filters empty segments, which would shift "which token is
    // first" for that one lead-`::` shape and is not proven equivalent here.
    if raw
        .split("::")
        .next()
        .is_some_and(|head| head != namespace && !namespace.ends_with(&format!("::{head}")))
    {
        vec![format!("{namespace}::{raw}"), raw]
    } else {
        vec![raw]
    }
}

fn first_descendant_of_kind<'tree>(node: Node<'tree>, kind: &str) -> Option<Node<'tree>> {
    brokk_bifrost_core::analyzer::tree_walk::first_named_descendant_of_kind_inclusive(node, kind)
}

/// Whether a name leaf the field scans reached sits in a value position.
///
/// Every kind those scans admit already names a value except `type_identifier`.
/// tree-sitter spells a non-type template argument with type syntax, so the
/// constant `N` in `std::array<W, N>` is a `type_identifier` exactly like the
/// type argument `W` beside it ([`is_type_shaped_template_argument_name`]).
/// Admit that leaf only where no visible type explains the spelling, which is
/// the order forward navigation applies before it reads the leaf in the value
/// namespace (#2556). Every other `type_identifier` is a type reference and
/// belongs to the type scan.
fn scan_leaf_is_value_position(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    node.kind() != "type_identifier"
        || (is_type_shaped_template_argument_name(node)
            && ctx
                .visibility
                .resolve_type(ctx.file, node_text(node, ctx.source))
                .is_none())
}

fn maybe_record_global_field_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if is_c_offsetof_member_node(node) {
        return;
    }
    if matches!(node.kind(), "identifier" | "field_identifier")
        && designated_initializer_owner(&ctx.analyzer, ctx.visibility, ctx.file, ctx.source, node)
            .is_some()
    {
        return;
    }
    if !matches!(
        node.kind(),
        "identifier" | "field_identifier" | "qualified_identifier" | "type_identifier"
    ) || !name_matches_terminal(node_text(node, ctx.source), &ctx.spec.member_name)
        || !scan_leaf_is_value_position(node, ctx)
        || is_declaration_name(node)
        || is_member_field_own_declarator(node, ctx)
        || is_selected_field_expression_member_descendant(node)
        || is_nested_in_qualified_identifier(node)
    {
        return;
    }
    *ctx.raw_match_count += 1;
    if global_field_resolves_to_target(node, ctx) {
        push_hit(node, ctx);
    } else if global_field_is_known_non_target(node, ctx) {
    } else {
        push_unproven_hit(node, ctx);
    }
}

/// Whether `node` belongs to the selected-member side of any enclosing field
/// expression. A reference may be nested arbitrarily inside the receiver side
/// (for example, an argument to a call-built fluent receiver), so direct child
/// equality is insufficient: classify each ancestor by structured subtree
/// containment instead.
fn is_selected_field_expression_member_descendant(mut node: Node<'_>) -> bool {
    let candidate = node;
    while let Some(parent) = node.parent() {
        if parent.kind() == "field_expression" {
            if let Some(field) = parent.child_by_field_name("field")
                && node_is_within(field, candidate)
            {
                // The `template` disambiguator in `receiver.template f<Arg>()`
                // wraps the selected member in a `dependent_name` whose single
                // named child is the `template_*` node the plain spelling puts
                // directly under `field`. Unwrap it so both spellings reach the
                // same name/arguments split (#2196).
                let selected = match field.kind() {
                    "dependent_name" => field.named_child(0).unwrap_or(field),
                    _ => field,
                };
                let selected_name = match selected.kind() {
                    "template_method" | "template_function" | "template_type" => {
                        selected.child_by_field_name("name").unwrap_or(selected)
                    }
                    _ => selected,
                };
                if node_is_within(selected_name, candidate) {
                    return true;
                }
                // A template argument is structurally inside the field subtree,
                // but it is an independent reference rather than the selected
                // member name.
                node = parent;
                continue;
            }
            let receiver = parent
                .child_by_field_name("argument")
                .or_else(|| parent.child_by_field_name("object"))
                .or_else(|| parent.named_child(0));
            if !receiver.is_some_and(|receiver| node_is_within(receiver, candidate)) {
                // Unknown grammar shape inside a field expression: fail closed
                // rather than treating it as a receiver reference.
                return true;
            }
        }
        node = parent;
    }
    false
}

fn global_field_resolves_to_target(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let text = node_text(node, ctx.source);
    if !text.contains("::") && ctx.local_shadows.is_shadowed(text) {
        return false;
    }
    if text.contains("::") {
        return ctx.visibility.contains_named_symbol(
            ctx.file,
            text,
            TargetKind::GlobalField,
            &ctx.spec.target,
        );
    }
    if let Some(namespace) = enclosing_namespace_context(node, ctx.source)
        && cpp_namespace_for(&ctx.spec.target).as_deref() == Some(namespace.as_str())
    {
        return ctx.visibility.contains_named_symbol(
            ctx.file,
            text,
            TargetKind::GlobalField,
            &ctx.spec.target,
        );
    }
    if let Some(indexed_scope) = indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, node)
        && cpp_namespace_for(&ctx.spec.target).is_some_and(|namespace| {
            brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
                brokk_bifrost_core::analyzer::Language::Cpp,
                &namespace,
            ) == indexed_scope
        })
    {
        return ctx.visibility.contains_named_symbol(
            ctx.file,
            text,
            TargetKind::GlobalField,
            &ctx.spec.target,
        );
    }
    bare_global_field_uniquely_resolves_to_target(text, ctx)
}

fn bare_global_field_uniquely_resolves_to_target(text: &str, ctx: &ScanCtx<'_>) -> bool {
    let mut matched_target = false;
    for unit in ctx.visibility.visible_identifier_candidates(ctx.file, text) {
        if !has_persisted_global_field_identity(unit)
            || !name_matches_terminal(unit.identifier(), &ctx.spec.member_name)
        {
            continue;
        }
        if !name_matches_terminal(cpp_name_for(unit).as_str(), text) {
            continue;
        }
        if same_visible_global_field_symbol(
            &ctx.analyzer,
            &mut ctx.global_field_internal_linkage_cache.borrow_mut(),
            unit,
            &ctx.spec.target,
        ) {
            matched_target = true;
        } else {
            return false;
        }
    }
    matched_target
}

pub(crate) fn has_persisted_global_field_identity(unit: &CodeUnit) -> bool {
    // C++ type members persist their owner in `short_name` (`Owner.member`), while namespace
    // identity lives in `package_name`; global and namespace-scoped fields therefore have a
    // terminal-only short name. Keep this hot lookup projection-only instead of asking the
    // analyzer for every same-named candidate's parent.
    unit.is_field() && !unit.short_name().contains('.')
}

fn global_field_is_known_non_target(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let text = node_text(node, ctx.source);
    if !text.contains("::") && ctx.local_shadows.is_shadowed(text) {
        return true;
    }
    if text.contains("::") {
        return ctx.visibility.resolve_known_non_target(
            ctx.file,
            text,
            TargetKind::GlobalField,
            &ctx.spec.target,
        );
    }
    let Some(namespace) = enclosing_namespace_context(node, ctx.source) else {
        return false;
    };
    cpp_namespace_for(&ctx.spec.target).as_deref() != Some(namespace.as_str())
        && ctx
            .visibility
            .visible_identifier_candidates(ctx.file, &ctx.spec.member_name)
            .any(|unit| {
                has_persisted_global_field_identity(unit)
                    && unit.identifier() == ctx.spec.member_name
                    && cpp_namespace_for(unit).as_deref() == Some(namespace.as_str())
                    && !same_visible_global_field_symbol(
                        &ctx.analyzer,
                        &mut ctx.global_field_internal_linkage_cache.borrow_mut(),
                        unit,
                        &ctx.spec.target,
                    )
            })
}

fn maybe_record_member_field_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if is_c_offsetof_member_node(node) {
        maybe_record_c_offsetof_field_hit(node, ctx);
        return;
    }
    if node.kind() == "field_expression" {
        let Some(field) = node.child_by_field_name("field") else {
            return;
        };
        if node_text(field, ctx.source) != ctx.spec.member_name {
            return;
        }
        *ctx.raw_match_count += 1;
        if !ctx.visibility.declaration_guards_compatible_at_reference(
            &ctx.analyzer,
            ctx.file,
            &ctx.spec.target,
            field,
        ) {
            return;
        }
        let receiver = node
            .child_by_field_name("argument")
            .or_else(|| node.child_by_field_name("object"));
        let receiver_resolution =
            receiver.map(|receiver| explicit_receiver_target_resolution(receiver, None, ctx));
        match receiver_resolution {
            Some(MethodReceiverTargetResolution::Target)
                if ctx.visibility.declaration_visible_at_reference(
                    &ctx.analyzer,
                    ctx.file,
                    &ctx.spec.target,
                    field,
                ) || (!ctx.analyzer.reference_uses_c_semantics(ctx.file)
                    && ctx.spec.target.source() == ctx.file
                    && ctx
                        .visibility
                        .external_type_candidate_guard_compatible_in_context(
                            &ctx.analyzer,
                            ctx.file,
                            &ctx.spec.target,
                            field,
                        )) =>
            {
                // The receiver proves the C++ member owner, including fields
                // recovered without callable activation facts. Its guard still
                // needs implication and stability, even in the same file.
                push_hit(field, ctx)
            }
            Some(
                MethodReceiverTargetResolution::Target | MethodReceiverTargetResolution::Missing,
            )
            | None => push_unproven_hit(field, ctx),
            Some(
                MethodReceiverTargetResolution::NonTarget
                | MethodReceiverTargetResolution::Ambiguous,
            ) => {}
        }
        return;
    }

    if matches!(node.kind(), "identifier" | "field_identifier")
        && name_matches_terminal(node_text(node, ctx.source), &ctx.spec.member_name)
        && let Some(designator_owner) =
            designated_initializer_owner(&ctx.analyzer, ctx.visibility, ctx.file, ctx.source, node)
    {
        *ctx.raw_match_count += 1;
        match designator_owner {
            DesignatedInitializerOwner::Resolved(owner)
                if ctx
                    .spec
                    .owner
                    .as_ref()
                    .is_some_and(|target_owner| same_visible_symbol(&owner, target_owner)) =>
            {
                push_hit(node, ctx);
            }
            DesignatedInitializerOwner::Unresolved => push_unproven_hit(node, ctx),
            DesignatedInitializerOwner::Resolved(_) => {}
        }
        return;
    }

    let qualified_member_name_matches =
        matches!(node.kind(), "qualified_identifier" | "scoped_identifier")
            && cpp_name_component_nodes(node)
                .and_then(|components| components.last().copied())
                .is_some_and(|terminal| node_text(terminal, ctx.source) == ctx.spec.member_name);
    if !matches!(
        node.kind(),
        "identifier"
            | "field_identifier"
            | "qualified_identifier"
            | "scoped_identifier"
            | "type_identifier"
    ) || (!name_matches_terminal(node_text(node, ctx.source), &ctx.spec.member_name)
        && !qualified_member_name_matches)
        || !scan_leaf_is_value_position(node, ctx)
        || is_declaration_name(node)
        || is_member_field_own_declarator(node, ctx)
        || is_selected_field_expression_member_descendant(node)
        || is_nested_in_qualified_identifier(node)
    {
        return;
    }
    *ctx.raw_match_count += 1;
    if is_structurally_qualified(node) {
        match qualified_owner_resolution(node, ctx) {
            QualifiedOwnerResolution::Target => push_hit(node, ctx),
            QualifiedOwnerResolution::NonTarget => {}
            QualifiedOwnerResolution::Unresolved => push_unproven_hit(node, ctx),
        }
        return;
    }
    let text = node_text(node, ctx.source);
    if ctx.local_shadows.is_shadowed(text) {
        return;
    }
    let unscoped_enum_match = ctx.spec.enum_owner_kind == EnumOwnerKind::Unscoped
        && ctx.visibility.is_visible(ctx.file, &ctx.spec.target);
    let owner_context = structured_owner_context_resolution(node, ctx);
    if matches!(
        owner_context,
        StructuredOwnerContextResolution::SelfTarget
            | StructuredOwnerContextResolution::InheritedTarget
    ) || unscoped_enum_match
    {
        push_hit(node, ctx);
    } else if let Some(target_owner) = (ctx.spec.enum_owner_kind == EnumOwnerKind::Scoped)
        .then_some(ctx.spec.owner.as_ref())
        .flatten()
    {
        let resolution =
            match resolve_active_using_enum_member(node, ctx) {
                ActiveUsingEnumMemberResolution::Block(resolution) => resolution,
                ActiveUsingEnumMemberResolution::Class(resolution) => {
                    if direct_class_member_shadows(node, ctx) {
                        return;
                    }
                    resolution
                }
                ActiveUsingEnumMemberResolution::Namespace(resolution) => {
                    if let Some(owner) = structured_enclosing_owner(node, ctx) {
                        if direct_class_member_shadows(node, ctx) {
                            return;
                        }
                        let complete_same_file_leaf =
                            owner.source() == ctx.file
                                && ctx.analyzer.type_hierarchy_provider().is_some_and(
                                    |hierarchy| hierarchy.get_direct_ancestors(&owner).is_empty(),
                                );
                        if !complete_same_file_leaf {
                            push_unproven_hit(node, ctx);
                            return;
                        }
                    }
                    match owner_context {
                        StructuredOwnerContextResolution::SelfTarget
                        | StructuredOwnerContextResolution::InheritedTarget
                        | StructuredOwnerContextResolution::NonTarget => return,
                        StructuredOwnerContextResolution::Ambiguous => {
                            push_unproven_hit(node, ctx);
                            return;
                        }
                        StructuredOwnerContextResolution::Missing => {}
                    }
                    if namespace_value_shadows(node, ctx) {
                        return;
                    }
                    resolution
                }
                ActiveUsingEnumMemberResolution::Missing => {
                    if direct_class_member_shadows(node, ctx)
                        || (structured_enclosing_owner(node, ctx).is_none()
                            && namespace_value_shadows(node, ctx))
                    {
                        return;
                    }
                    UsingEnumMemberResolution::Missing
                }
            };
        match resolution {
            UsingEnumMemberResolution::Resolved { owner, member }
                if same_visible_symbol(&owner, target_owner)
                    && same_visible_symbol(&member, &ctx.spec.target) =>
            {
                push_hit(node, ctx);
            }
            UsingEnumMemberResolution::Resolved { .. } => {}
            UsingEnumMemberResolution::Ambiguous | UsingEnumMemberResolution::Missing => {
                push_unproven_hit(node, ctx)
            }
        }
    } else if !matches!(owner_context, StructuredOwnerContextResolution::NonTarget) {
        push_unproven_hit(node, ctx);
    }
}

fn maybe_record_c_offsetof_field_hit(node: Node<'_>, ctx: &mut ScanCtx<'_>) {
    if node_text(node, ctx.source) != ctx.spec.member_name {
        return;
    }
    *ctx.raw_match_count += 1;
    let Some((type_reference, member)) = c_offsetof_member_parts(node) else {
        push_unproven_hit(node, ctx);
        return;
    };
    let owner = match resolve_type_node_lexically(
        type_reference,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
    ) {
        LexicalTypeResolution::Resolved { unit, .. } if unit.is_class() => unit,
        LexicalTypeResolution::Resolved { .. }
        | LexicalTypeResolution::Ambiguous
        | LexicalTypeResolution::Missing => {
            push_unproven_hit(member, ctx);
            return;
        }
    };
    let candidates = ctx
        .visibility
        .visible_members_for_owner_name(ctx.file, &owner, ctx.spec.member_name.as_str())
        .into_iter()
        .filter(|candidate| candidate.is_field())
        .collect::<Vec<_>>();
    if candidates.len() == 1 && ctx.target_group.contains(candidates[0]) {
        push_hit(member, ctx);
    } else if candidates.len() > 1 {
        push_unproven_hit(member, ctx);
    }
}

enum ActiveUsingEnumMemberResolution {
    Block(UsingEnumMemberResolution),
    Class(UsingEnumMemberResolution),
    Namespace(UsingEnumMemberResolution),
    Missing,
}

fn direct_class_member_shadows(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    structured_enclosing_owner(node, ctx).is_some_and(|owner| {
        ctx.visibility
            .visible_members_for_owner_name(ctx.file, &owner, &ctx.spec.member_name)
            .into_iter()
            .next()
            .is_some()
    })
}

fn resolve_active_using_enum_member(
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> ActiveUsingEnumMemberResolution {
    let block =
        ctx.using_enum_owners
            .resolve_member(ctx.visibility, ctx.file, &ctx.spec.member_name);
    if !matches!(block, UsingEnumMemberResolution::Missing) {
        return ActiveUsingEnumMemberResolution::Block(block);
    }
    let class = structured_enclosing_owner(node, ctx);
    let namespace = enclosing_namespace_components(node, ctx.source);
    match ctx.semantic_using_enum_owners.resolve_member(
        ctx.visibility,
        ctx.file,
        class.as_ref(),
        &namespace,
        node.start_byte(),
        &ctx.spec.member_name,
    ) {
        SemanticUsingEnumMemberResolution::Class(resolution) => {
            ActiveUsingEnumMemberResolution::Class(resolution)
        }
        SemanticUsingEnumMemberResolution::Namespace(resolution) => {
            ActiveUsingEnumMemberResolution::Namespace(resolution)
        }
        SemanticUsingEnumMemberResolution::Missing => ActiveUsingEnumMemberResolution::Missing,
    }
}

fn namespace_value_shadows(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let namespace = enclosing_namespace_components(node, ctx.source).join("::");
    !matches!(
        resolve_namespace_value(
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            &namespace,
            &ctx.spec.member_name,
            node.start_byte(),
        ),
        NamespaceValueResolution::Missing
    )
}

/// Whether `node` is a component of an enclosing qualified identifier's own
/// `scope`/`name` path, so the outer `qualified_identifier` is the single
/// reference surfaced for it.
///
/// A qualified identifier owns only that path. Everything else beneath it is an
/// independent reference that its own target scanner must resolve:
///
/// - `Owner::Template<argument>` holds each template argument outside the path.
/// - Error recovery can hang a complete member initializer off an `ERROR` child
///   of a synthetic qualified identifier, where no structured path exists.
/// - The grammar accepts a `pointer_type_declarator` as a qualified
///   identifier's `name`, so `EXPORT_MACRO Result *fn(unsigned int len = kMax);`
///   folds a whole parameter list under one `qualified_identifier`. Parameter
///   default values there are ordinary value expressions (#2548).
///
/// Follow the structured `scope`/`name` links rather than every ancestor, which
/// covers all three cases with one rule.
/// Whether `node` lies on the scope/name path of an enclosing
/// `qualified_identifier`, which owns the complete name. The grammar nests
/// `::A::b` and `n::A::b` as a qualified suffix `A::b`; resolving that suffix
/// on its own would drop the leading `::` or `n::` qualifier.
fn is_nested_in_qualified_identifier(node: Node<'_>) -> bool {
    let mut current = node;
    while let Some(parent) = current.parent() {
        let on_name_path = ["scope", "name"].into_iter().any(|field| {
            parent
                .child_by_field_name(field)
                .is_some_and(|component| same_node(component, current))
        });
        if !on_name_path {
            return false;
        }
        if parent.kind() == "qualified_identifier" {
            return true;
        }
        current = parent;
    }
    false
}

fn receiver_type_units(node: Node<'_>, source: &str, ctx: &ScanCtx<'_>) -> Vec<CodeUnit> {
    receiver_type_units_with_budget(node, source, ctx, MAX_RECEIVER_CALL_RESOLUTION_DEPTH)
}

/// What a receiver spelled as a qualified name denotes.
///
/// `ns::value.run()` reads the member off the declared type of the variable
/// `ns::value`; a type path spelled as a receiver reads it off the type itself.
/// Forward navigation and the inverse walk both ask this before typing such a
/// receiver, so the two directions accept the same receiver spellings (#2547).
pub enum QualifiedReceiverBase {
    /// Every visible declaration of the one variable the path names.
    Variable(Vec<CodeUnit>),
    /// The type the path names when it names no variable.
    Type(Option<CodeUnit>),
    /// The path names more than one variable; typing either would be a guess.
    Ambiguous,
}

pub fn qualified_receiver_base(
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    receiver: Node<'_>,
    source: &str,
) -> QualifiedReceiverBase {
    let reference = node_text(receiver, source);
    let fields = visibility
        .named_candidates(file, reference, TargetKind::GlobalField)
        .into_iter()
        .filter(has_persisted_global_field_identity)
        .collect::<Vec<_>>();
    let Some(first) = fields.first() else {
        return QualifiedReceiverBase::Type(visibility.resolve_type(file, reference));
    };
    if fields
        .iter()
        .skip(1)
        .any(|field| !same_visible_symbol(first, field))
    {
        return QualifiedReceiverBase::Ambiguous;
    }
    QualifiedReceiverBase::Variable(fields)
}

fn receiver_type_units_with_budget(
    node: Node<'_>,
    source: &str,
    ctx: &ScanCtx<'_>,
    remaining_call_depth: usize,
) -> Vec<CodeUnit> {
    let mut current = node;
    let mut member_chain = Vec::new();
    let mut base_units = loop {
        match current.kind() {
            "field_expression" => {
                let Some(member) = current.child_by_field_name("field") else {
                    return Vec::new();
                };
                let Some(receiver) = current
                    .child_by_field_name("argument")
                    .or_else(|| current.child_by_field_name("object"))
                    .or_else(|| current.named_child(0))
                else {
                    return Vec::new();
                };
                member_chain.push(node_text(member, source));
                current = receiver;
            }
            "pointer_expression" | "parenthesized_expression" | "subscript_expression" => {
                let Some(inner) = current
                    .child_by_field_name("argument")
                    .or_else(|| current.named_child(0))
                else {
                    return Vec::new();
                };
                current = inner;
            }
            // Tree-sitter uses `field_identifier` for an unqualified member
            // field when it appears as the base of another field expression
            // (`data_.as_chars()` / `prefix.edge`).  Resolve it through the
            // same structured binding and enclosing-owner paths as an
            // ordinary identifier; falling through to `resolve_type` would
            // treat the field name as a type and lose the receiver identity.
            "identifier" | "field_identifier" => {
                let name = node_text(current, source);
                // Function-like macro locals are visible in the replacement
                // range after substitution and shadow caller bindings. The
                // receiver scan has no root field, so recover the source tree
                // root before asking the visibility index for that binding.
                let mut root = current;
                while let Some(parent) = ctx.ancestry.parent(root) {
                    root = parent;
                }
                if let Some(binding) = ctx.visibility.macro_local_binding_at(
                    ctx.file,
                    root,
                    source,
                    current.start_byte(),
                    current.end_byte(),
                ) && binding.name == name
                {
                    let normalized = normalize_cpp_type_name(&binding.type_name);
                    let unit = binding
                        .proven_unit
                        .clone()
                        .or_else(|| {
                            binding.type_node.and_then(|type_node| {
                                resolve_receiver_type_node(type_node, ctx).ok().flatten()
                            })
                        })
                        .or_else(|| receiver_type_name_unit(current, &normalized, ctx));
                    // Keep the macro declaration's shadowing boundary even
                    // when its type is unavailable: an unresolved macro local
                    // cannot be reinterpreted as a static type or outer value.
                    break unit.into_iter().collect();
                }
                let local = ctx.bindings.resolve_symbol(name);
                if let Some(bindings) = local.as_precise() {
                    break receiver_units_from_bindings(current, bindings, ctx);
                }
                if ctx.bindings.is_shadowed(name) {
                    return Vec::new();
                }
                let owner = structured_enclosing_owner(current, ctx)
                    .filter(CodeUnit::is_class)
                    .or_else(|| {
                        enclosing_context(current, ctx)
                            .owner
                            .filter(CodeUnit::is_class)
                    });
                if let Some(owner) = owner {
                    // The enclosing class is only the search root: an implicit
                    // member-field receiver can be declared on any base, so the
                    // declaring owner comes from the same hierarchy walk the
                    // member chain below uses, not from an exact-parent match.
                    let declaring_owner = match resolve_declaring_member_owner(
                        &ctx.analyzer,
                        ctx.visibility,
                        ctx.file,
                        &owner,
                        name,
                    ) {
                        EnclosingMemberOwnerResolution::Owner(owner) => Some(owner),
                        EnclosingMemberOwnerResolution::Missing => None,
                        EnclosingMemberOwnerResolution::Ambiguous => return Vec::new(),
                    };
                    if let Some(declaring_owner) = declaring_owner {
                        let implicit_fields = ctx
                            .visibility
                            .visible_members_for_owner_name(ctx.file, &declaring_owner, name)
                            .into_iter()
                            .filter(|unit| unit.is_field())
                            .collect::<Vec<_>>();
                        if !implicit_fields.is_empty() {
                            break receiver_units_from_declared_fields(
                                implicit_fields,
                                current,
                                ctx,
                            );
                        }
                    }
                }
                let global_fields = ctx
                    .visibility
                    .visible_identifier_candidates(ctx.file, name)
                    .filter(|unit| {
                        has_persisted_global_field_identity(unit) && unit.identifier() == name
                    })
                    .collect::<Vec<_>>();
                if global_fields.is_empty() {
                    break ctx
                        .visibility
                        .resolve_type(ctx.file, name)
                        .into_iter()
                        .collect();
                }
                if let Some(first) = global_fields.first()
                    && global_fields.iter().skip(1).any(|field| {
                        !same_visible_global_field_symbol(
                            &ctx.analyzer,
                            &mut ctx.global_field_internal_linkage_cache.borrow_mut(),
                            first,
                            field,
                        )
                    })
                {
                    return Vec::new();
                }
                break receiver_units_from_declared_fields(global_fields, current, ctx);
            }
            "call_expression" | "new_expression" => {
                break infer_type_from_value_with_budget(current, ctx, remaining_call_depth)
                    .and_then(|binding| binding.unit)
                    .into_iter()
                    .collect();
            }
            // `((T*)p)->member` is typed by what the cast spells, not by the
            // operand it converts (#2981). Pointer depth does not change which
            // type declares the member, so only the descriptor's type matters.
            "cast_expression" => {
                let Some(descriptor) = current.child_by_field_name("type") else {
                    return Vec::new();
                };
                let Ok(unit) = resolve_receiver_type_node(descriptor, ctx) else {
                    return Vec::new();
                };
                break unit.into_iter().collect();
            }
            "this" if ctx.analyzer.reference_uses_c_semantics(ctx.file) => {
                let name = node_text(current, source);
                let local = ctx.bindings.resolve_symbol(name);
                if let Some(bindings) = local.as_precise() {
                    break receiver_units_from_bindings(current, bindings, ctx);
                }
                return Vec::new();
            }
            "this" => break enclosing_context(current, ctx).owner.into_iter().collect(),
            "qualified_identifier" | "scoped_identifier" => {
                match qualified_receiver_base(ctx.visibility, ctx.file, current, source) {
                    QualifiedReceiverBase::Variable(fields) => {
                        break receiver_units_from_declared_fields(
                            fields.iter().collect(),
                            current,
                            ctx,
                        );
                    }
                    QualifiedReceiverBase::Type(unit) => break unit.into_iter().collect(),
                    QualifiedReceiverBase::Ambiguous => return Vec::new(),
                }
            }
            _ => {
                break ctx
                    .visibility
                    .resolve_type(ctx.file, node_text(current, source))
                    .into_iter()
                    .collect();
            }
        }
    };

    base_units = canonical_receiver_units(base_units, ctx);
    if base_units.is_empty() {
        return Vec::new();
    }

    while let Some(member_name) = member_chain.pop() {
        let mut next_units = Vec::new();
        for owner in &base_units {
            let declaring_owner = match resolve_declaring_member_owner(
                &ctx.analyzer,
                ctx.visibility,
                ctx.file,
                owner,
                member_name,
            ) {
                EnclosingMemberOwnerResolution::Owner(owner) => owner,
                EnclosingMemberOwnerResolution::Missing => continue,
                EnclosingMemberOwnerResolution::Ambiguous => return Vec::new(),
            };
            let fields = ctx.visibility.visible_members_for_owner_name(
                ctx.file,
                &declaring_owner,
                member_name,
            );
            for field in fields.into_iter().filter(|unit| unit.is_field()) {
                let Some(unit) =
                    field_declared_binding(&ctx.analyzer, ctx.visibility, ctx.file, field)
                        .and_then(|binding| binding.unit)
                        .or_else(|| recovered_receiver_field_type(current, field, ctx))
                else {
                    continue;
                };
                if !next_units
                    .iter()
                    .any(|existing| same_visible_symbol(existing, &unit))
                {
                    next_units.push(unit);
                }
            }
        }
        if next_units.is_empty() {
            return Vec::new();
        }
        base_units = unanimous_receiver_units(next_units);
        if base_units.is_empty() {
            return Vec::new();
        }
    }
    base_units
}

fn receiver_units_from_bindings(
    node: Node<'_>,
    bindings: &HashSet<CppScanBinding>,
    ctx: &ScanCtx<'_>,
) -> Vec<CodeUnit> {
    let mut units = Vec::new();
    for binding in bindings {
        let raw_unit = if let Some(unit) = &binding.unit {
            unit.clone()
        } else {
            let Some(type_name) = binding.type_name.as_deref() else {
                return Vec::new();
            };
            let Some(unit) = receiver_type_name_unit(node, type_name, ctx) else {
                return Vec::new();
            };
            unit
        };
        if let Some(unit) = canonical_receiver_unit(&raw_unit, ctx) {
            // Type aliases are represented as class units. When an alias has
            // a dependent target, canonicalization deliberately preserves
            // that alias rather than inventing a concrete class. Give the
            // existing target-guided structured recovery a chance to prove
            // the queried owner before accepting that unresolved identity.
            if same_visible_symbol(&unit, &raw_unit)
                && let Some(recovered) = recovered_receiver_alias_target(node, &raw_unit, ctx)
            {
                units.push(recovered);
                continue;
            }
            units.push(unit);
            continue;
        }
        if let Some(unit) = recovered_receiver_alias_target(node, &raw_unit, ctx) {
            units.push(unit);
            continue;
        }
        return Vec::new();
    }
    unanimous_receiver_units(units)
}

/// Resolve a using-alias receiver from its declaration's structured RHS when
/// the alias target index cannot cross a malformed namespace-sentinel node.
/// The inverse target owner supplies only the exact class identity to prove;
/// lexical AST resolution still decides whether the alias denotes that class.
fn recovered_receiver_alias_target(
    reference: Node<'_>,
    alias: &CodeUnit,
    ctx: &ScanCtx<'_>,
) -> Option<CodeUnit> {
    if !ctx
        .analyzer
        .type_alias_provider()
        .is_some_and(|provider| provider.is_type_alias(alias))
    {
        return None;
    }
    let target = ctx.spec.owner.as_ref()?.clone();
    if !target.is_class() || alias.source() != ctx.file {
        return None;
    }
    let range = ctx
        .analyzer
        .ranges(alias)
        .into_iter()
        .find(|range| range.start_byte < range.end_byte)?;
    let mut node =
        root_node(reference).descendant_for_byte_range(range.start_byte, range.end_byte)?;
    while !matches!(node.kind(), "alias_declaration" | "type_definition") {
        node = ctx.ancestry.parent(node)?;
    }
    let type_descriptor = node.child_by_field_name("type")?;
    let type_node = receiver_type_node_base(type_descriptor);
    let resolution = resolve_type_node_lexically_for_target(
        type_node,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
        &target,
        Some(&ctx.lexical_scope_cache),
        ctx.recovered_sentinel_scope(type_node).as_deref(),
    );
    if let LexicalTypeResolution::Resolved {
        unit, candidates, ..
    } = resolution
        && (same_visible_symbol(&unit, &target)
            || candidates
                .iter()
                .any(|candidate| same_visible_symbol(candidate, &target)))
    {
        return Some(target);
    }
    let (components, global) = type_reference_components(type_node, ctx.source)?;
    if !global
        && components.len() == 2
        && cpp_active_template_type_parameter(type_node, &components[0], ctx.source, &ctx.ancestry)
        && dependent_nested_alias_concrete_target(
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            alias,
            &components[1],
            type_node,
        )
        .is_some_and(|unit| same_visible_symbol(&unit, &target))
    {
        return Some(target);
    }
    let scope = ctx
        .recovered_sentinel_scope(type_node)
        .or_else(|| indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, type_node))?;
    let path_matches = indexed_scope_matches_target_name(&scope, &components, global, &target);
    let visible = ctx.visibility.external_type_candidate_visible_in_context(
        &ctx.analyzer,
        ctx.file,
        &target,
        type_node,
    );
    (path_matches && visible).then_some(target)
}

/// The one concrete class that `alias`, spelled `Param::nested_name` through an
/// active template type parameter `Param`, can name: every other visible
/// class-owned alias named `nested_name` must reach the same indexed class
/// (#2250). `type_node` is the alias's target type node, whose guard context
/// each candidate must be compatible with. Competing concrete targets answer
/// `None`.
pub fn dependent_nested_alias_concrete_target(
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    alias: &CodeUnit,
    nested_name: &str,
    type_node: Node<'_>,
) -> Option<CodeUnit> {
    let alias_provider = analyzer.type_alias_provider()?;
    let concrete = visibility
        .visible_identifier_candidates(file, nested_name)
        .filter(|candidate| {
            alias_provider.is_type_alias(candidate)
                && !same_visible_symbol(candidate, alias)
                && type_owner_of(analyzer, candidate).is_some_and(|owner| owner.is_class())
                && visibility.is_physically_visible(file, candidate)
                && visibility.external_type_candidate_guard_compatible_in_context(
                    analyzer, file, candidate, type_node,
                )
        })
        .filter_map(|candidate| {
            let canonical =
                visibility.canonical_visible_full_type_unit(analyzer, file, candidate)?;
            // Another dependent alias can have the same nested name but
            // still canonicalize only to itself. It supplies no concrete
            // receiver identity and therefore cannot compete with an
            // alias that reaches an indexed class.
            (!same_visible_symbol(&canonical, candidate)).then_some(canonical)
        })
        .collect::<Vec<_>>();
    match unanimous_receiver_units(concrete).as_slice() {
        [unit] => Some(unit.clone()),
        _ => None,
    }
}

fn receiver_type_name_unit(node: Node<'_>, type_name: &str, ctx: &ScanCtx<'_>) -> Option<CodeUnit> {
    let normalized = normalize_cpp_type_name(type_name);
    if normalized.is_empty() {
        return None;
    }

    // A function-local alias is intentionally absent from the visibility
    // index. Recover its RHS from the structured alias declaration before
    // trying file-visible type lookup; this keeps the alias's lexical shadow
    // boundary intact.
    if let Some(alias_type) = local_receiver_alias_type_node(node, &normalized, ctx) {
        match resolve_receiver_type_node(alias_type, ctx) {
            Ok(Some(unit)) => return Some(unit),
            Err(_) => return None,
            Ok(None) => {}
        }
    }

    match resolve_receiver_type_name_lexically(node, &normalized, ctx) {
        LexicalTypeResolution::Resolved { unit, .. } => return Some(unit),
        LexicalTypeResolution::Ambiguous => return None,
        LexicalTypeResolution::Missing => {}
    }
    let candidates = ctx
        .visibility
        .type_name_candidates(ctx.file, &normalized)
        .into_iter()
        .filter_map(|candidate| canonical_receiver_unit(candidate, ctx))
        .collect();
    unanimous_receiver_units(candidates).into_iter().next()
}

/// The receiver type a type node names: the visible indexed type it resolves
/// to, else the type its components name in the enclosing lexical scope.
///
/// A `type_descriptor` (a cast's type, an alias declaration's right-hand side)
/// is unwrapped to its type specifier first, so every caller that has a spelled
/// type reads it the same way. `Err` reports a template whose arguments could
/// not be resolved; that is a structured failure, not an absent type.
fn resolve_receiver_type_node(
    type_node: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> std::result::Result<Option<CodeUnit>, CppTemplateResolutionError> {
    let type_node = receiver_type_node_base(type_node);
    if let Some(unit) = ctx
        .visibility
        .resolve_type_node_result(ctx.file, type_node, ctx.source)?
    {
        return Ok(Some(unit));
    }
    Ok(resolve_receiver_type_node_lexically(type_node, ctx))
}

fn resolve_receiver_type_node_lexically(
    type_node: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> Option<CodeUnit> {
    let type_node = receiver_type_node_base(type_node);
    let components = cpp_type_name_components(type_node, ctx.source)?;
    let lexical_scope = match enclosing_lexical_scope_components(
        type_node,
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        ctx.source,
    ) {
        LexicalScopeResolution::Resolved(scope) => scope,
        LexicalScopeResolution::Ambiguous | LexicalScopeResolution::Missing => return None,
    };
    match ctx.visibility.resolve_type_components_lexically(
        &ctx.analyzer,
        ctx.file,
        &components,
        is_globally_qualified_cpp_name(type_node),
        &lexical_scope,
    ) {
        LexicalTypeResolution::Resolved { unit, .. } => Some(unit),
        LexicalTypeResolution::Ambiguous | LexicalTypeResolution::Missing => None,
    }
}

fn receiver_type_node_base(mut node: Node<'_>) -> Node<'_> {
    while matches!(node.kind(), "type_descriptor" | "dependent_type") {
        let Some(inner) = node.child_by_field_name("type").or_else(|| {
            if node.kind() == "dependent_type" {
                node.named_child(0)
            } else {
                None
            }
        }) else {
            break;
        };
        node = inner;
    }
    node
}

fn resolve_receiver_type_name_lexically(
    node: Node<'_>,
    normalized: &str,
    ctx: &ScanCtx<'_>,
) -> LexicalTypeResolution {
    let components = brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
        brokk_bifrost_core::analyzer::Language::Cpp,
        normalized,
    );
    if components.is_empty() {
        return LexicalTypeResolution::Missing;
    }
    let lexical_scope = match enclosing_lexical_scope_components(
        node,
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        ctx.source,
    ) {
        LexicalScopeResolution::Resolved(scope) => scope,
        LexicalScopeResolution::Ambiguous => return LexicalTypeResolution::Ambiguous,
        LexicalScopeResolution::Missing => return LexicalTypeResolution::Missing,
    };
    ctx.visibility.resolve_type_components_lexically(
        &ctx.analyzer,
        ctx.file,
        &components,
        normalized.starts_with("::"),
        &lexical_scope,
    )
}

fn local_receiver_alias_type_node<'tree>(
    node: Node<'tree>,
    name: &str,
    ctx: &ScanCtx<'_>,
) -> Option<Node<'tree>> {
    let callable = nearest_callable_scope(node)?;
    let mut root_callable = callable;
    // See `target_guided_nested_type_terminal_hit`: the result carries the
    // caller's tree lifetime.
    let mut ancestor = callable.parent();
    while let Some(current) = ancestor {
        if matches!(current.kind(), "function_definition" | "lambda_expression") {
            root_callable = current;
        }
        ancestor = current.parent();
    }

    let mut stack = vec![root_callable];
    let mut best = None;
    while let Some(current) = stack.pop() {
        if current.start_byte() >= node.start_byte() {
            continue;
        }
        if local_type_alias_name_node(current)
            .is_some_and(|alias_name| node_text(alias_name, ctx.source) == name)
            && current
                .parent()
                .is_none_or(|parent| parent.kind() != "template_declaration")
            && has_function_scope_ancestor(current)
            && local_alias_scope_contains_node(current, node)
        {
            let replace = best
                .is_none_or(|existing: Node<'tree>| existing.start_byte() < current.start_byte());
            if replace {
                best = current.child_by_field_name("type");
            }
        }
        let mut cursor = current.walk();
        stack.extend(current.named_children(&mut cursor));
    }
    best
}

fn canonical_receiver_units(units: Vec<CodeUnit>, ctx: &ScanCtx<'_>) -> Vec<CodeUnit> {
    let mut canonical = Vec::with_capacity(units.len());
    for unit in units {
        let Some(unit) = canonical_receiver_unit(&unit, ctx) else {
            return Vec::new();
        };
        canonical.push(unit);
    }
    unanimous_receiver_units(canonical)
}

fn canonical_receiver_unit(unit: &CodeUnit, ctx: &ScanCtx<'_>) -> Option<CodeUnit> {
    if let Some(cached) = ctx.receiver_canonical_type_cache.borrow().get(unit) {
        return cached.clone();
    }
    let canonical = ctx
        .visibility
        .canonical_visible_full_type_unit(&ctx.analyzer, ctx.file, unit);
    ctx.receiver_canonical_type_cache
        .borrow_mut()
        .insert(unit.clone(), canonical.clone());
    canonical
}

fn receiver_units_from_declared_fields(
    fields: Vec<&CodeUnit>,
    reference: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> Vec<CodeUnit> {
    let Some(first) = fields.first() else {
        return Vec::new();
    };
    if fields
        .iter()
        .skip(1)
        .any(|field| !same_visible_symbol(first, field))
    {
        return Vec::new();
    }
    unanimous_receiver_units(
        fields
            .into_iter()
            .filter_map(|field| {
                field_declared_binding(&ctx.analyzer, ctx.visibility, ctx.file, field)
                    .and_then(|binding| binding.unit)
                    .or_else(|| recovered_receiver_field_type(reference, field, ctx))
            })
            .collect(),
    )
}

/// Resolve a field receiver's declared type from its structured declaration
/// when the persisted type fact was built under a malformed sentinel scope.
/// The queried member owner supplies the exact class identity to prove; the
/// declaration's type node and recovered lexical path provide the evidence.
fn recovered_receiver_field_type(
    reference: Node<'_>,
    field: &CodeUnit,
    ctx: &ScanCtx<'_>,
) -> Option<CodeUnit> {
    let target = ctx.spec.owner.as_ref()?.clone();
    if !target.is_class() || field.source() != ctx.file {
        return None;
    }
    let range = ctx
        .analyzer
        .ranges(field)
        .into_iter()
        .find(|range| range.start_byte < range.end_byte)?;
    let mut declaration =
        root_node(reference).descendant_for_byte_range(range.start_byte, range.end_byte)?;
    while !matches!(declaration.kind(), "declaration" | "field_declaration") {
        declaration = ctx.ancestry.parent(declaration)?;
    }
    let type_node = first_type_child(declaration)?;
    let resolution = resolve_type_node_lexically_for_target(
        type_node,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
        &target,
        Some(&ctx.lexical_scope_cache),
        ctx.recovered_sentinel_scope(type_node).as_deref(),
    );
    if let LexicalTypeResolution::Resolved {
        unit, candidates, ..
    } = resolution
        && (same_visible_symbol(&unit, &target)
            || candidates
                .iter()
                .any(|candidate| same_visible_symbol(candidate, &target)))
    {
        return Some(target);
    }
    let type_node = receiver_type_node_base(type_node);
    let (components, global) = type_reference_components(type_node, ctx.source)?;
    let scope = ctx
        .recovered_sentinel_scope(type_node)
        .or_else(|| indexed_enclosing_lexical_scope(&ctx.analyzer, ctx.file, type_node))?;
    (indexed_scope_matches_target_name(&scope, &components, global, &target)
        && ctx.visibility.external_type_candidate_visible_in_context(
            &ctx.analyzer,
            ctx.file,
            &target,
            type_node,
        ))
    .then_some(target)
}

fn unanimous_receiver_units(units: Vec<CodeUnit>) -> Vec<CodeUnit> {
    let mut unique = Vec::new();
    for unit in units {
        if !unique
            .iter()
            .any(|existing| same_visible_symbol(existing, &unit))
        {
            unique.push(unit);
            if unique.len() > 1 {
                return Vec::new();
            }
        }
    }
    unique
}

fn receiver_matches_target(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let Some(owner) = ctx.spec.owner.as_ref() else {
        return false;
    };
    match node.kind() {
        // `declaring_owner_for_explicit_receiver` already tried the complete field chain.
        // When that structured lookup fails, the base expression's owner is not the field's
        // type: treating `value_` as `Value` would misclassify
        // `value_.map_->clear()` as `Value::clear`. Direct `this->clear()` reaches this helper
        // with the `this` node itself, so failing closed for an unresolved field chain does not
        // discard genuine self calls.
        "field_expression" => false,
        "call_expression" => node
            .child_by_field_name("function")
            .is_some_and(|function| receiver_matches_target(function, ctx)),
        "pointer_expression" | "parenthesized_expression" | "subscript_expression" => node
            .child_by_field_name("argument")
            .or_else(|| node.named_child(0))
            .is_some_and(|child| receiver_matches_target(child, ctx)),
        "identifier" | "this" if ctx.analyzer.reference_uses_c_semantics(ctx.file) => ctx
            .bindings
            .resolve_symbol(node_text(node, ctx.source))
            .as_precise()
            .is_some_and(|targets| {
                targets
                    .iter()
                    .filter_map(|target| target.unit.as_ref())
                    .any(|target| {
                        receiver_owner_matches_target(target, owner, node.start_byte(), ctx)
                    })
            }),
        "this" => same_owner_context(node, ctx),
        _ => qualified_owner_matches(node, ctx),
    }
}

fn declaring_owner_for_explicit_receiver(
    receiver: Node<'_>,
    call_arity: Option<usize>,
    ctx: &ScanCtx<'_>,
) -> EnclosingMemberOwnerResolution {
    if receiver_is_self_like(receiver, ctx.analyzer.reference_uses_c_semantics(ctx.file)) {
        return EnclosingMemberOwnerResolution::Missing;
    }
    declaring_owner_from_receiver_units(
        receiver_type_units(receiver, ctx.source, ctx),
        receiver.start_byte(),
        call_arity,
        ctx,
    )
}

/// The owner that declares the queried member for a receiver already typed.
///
/// `reference_byte` is the reference's position in the scanned file, which
/// decides which declarations are visible there. A receiver recovered from a
/// macro replacement is typed against the sentinel parse but still reported at
/// its bytes in the defining file, so the two arrive separately.
fn declaring_owner_from_receiver_units(
    receiver_units: Vec<CodeUnit>,
    reference_byte: usize,
    call_arity: Option<usize>,
    ctx: &ScanCtx<'_>,
) -> EnclosingMemberOwnerResolution {
    let mut declaring_owner = None;
    for receiver_owner in receiver_units {
        if ctx.spec.owner.as_ref().is_some_and(|target_owner| {
            receiver_owner_matches_target(&receiver_owner, target_owner, reference_byte, ctx)
        }) {
            if declaring_owner
                .as_ref()
                .is_some_and(|existing| !same_visible_symbol(existing, &receiver_owner))
            {
                return EnclosingMemberOwnerResolution::Ambiguous;
            }
            declaring_owner = Some(receiver_owner);
            continue;
        }
        let ordinary = cached_declaring_member_owner(&receiver_owner, ctx);
        let owner_resolution = match call_arity {
            Some(arity) => resolve_declaring_callable_owner(
                &ctx.analyzer,
                ctx.visibility,
                ctx.file,
                ordinary,
                &ctx.spec.member_name,
                arity,
            ),
            None => ordinary,
        };
        match owner_resolution {
            EnclosingMemberOwnerResolution::Owner(owner) => {
                if declaring_owner
                    .as_ref()
                    .is_some_and(|existing| !same_visible_symbol(existing, &owner))
                {
                    return EnclosingMemberOwnerResolution::Ambiguous;
                }
                declaring_owner = Some(owner);
            }
            EnclosingMemberOwnerResolution::Ambiguous => {
                return EnclosingMemberOwnerResolution::Ambiguous;
            }
            EnclosingMemberOwnerResolution::Missing => {}
        }
    }
    declaring_owner
        .map(EnclosingMemberOwnerResolution::Owner)
        .unwrap_or(EnclosingMemberOwnerResolution::Missing)
}

fn declaring_owner_from_call_function(
    function: Node<'_>,
    call_arity: Option<usize>,
    ctx: &ScanCtx<'_>,
) -> Option<EnclosingMemberOwnerResolution> {
    match function.kind() {
        "field_expression" => function
            .child_by_field_name("argument")
            .or_else(|| function.child_by_field_name("object"))
            .map(|receiver| declaring_owner_for_explicit_receiver(receiver, call_arity, ctx))
            .or(Some(EnclosingMemberOwnerResolution::Missing)),
        "call_expression" => function
            .child_by_field_name("function")
            .and_then(|inner| declaring_owner_from_call_function(inner, call_arity, ctx)),
        _ => None,
    }
}

enum MethodReceiverTargetResolution {
    Target,
    NonTarget,
    Ambiguous,
    Missing,
}

fn method_receiver_target_resolution(
    node: Node<'_>,
    declaring_owner: EnclosingMemberOwnerResolution,
    ctx: &ScanCtx<'_>,
) -> MethodReceiverTargetResolution {
    match declaring_owner {
        EnclosingMemberOwnerResolution::Owner(_) | EnclosingMemberOwnerResolution::Ambiguous => {
            declaring_owner_target_resolution(declaring_owner, node.start_byte(), ctx)
        }
        EnclosingMemberOwnerResolution::Missing if ctx.spec.owner.is_none() => {
            MethodReceiverTargetResolution::Missing
        }
        EnclosingMemberOwnerResolution::Missing if receiver_matches_target(node, ctx) => {
            MethodReceiverTargetResolution::Target
        }
        EnclosingMemberOwnerResolution::Missing if receiver_has_known_non_target(node, ctx) => {
            MethodReceiverTargetResolution::NonTarget
        }
        EnclosingMemberOwnerResolution::Missing => MethodReceiverTargetResolution::Missing,
    }
}

/// Decide the queried member against a receiver's declaring owner alone.
///
/// This is the part of receiver typing that needs nothing but the owner and
/// the reference's position, so a member call recovered from a macro
/// replacement reaches the same verdict as ordinary code even though its
/// syntax lives in a separate sentinel parse.
fn declaring_owner_target_resolution(
    declaring_owner: EnclosingMemberOwnerResolution,
    reference_byte: usize,
    ctx: &ScanCtx<'_>,
) -> MethodReceiverTargetResolution {
    let Some(target_owner) = ctx.spec.owner.as_ref() else {
        return MethodReceiverTargetResolution::Missing;
    };
    match declaring_owner {
        EnclosingMemberOwnerResolution::Owner(owner)
            if receiver_owner_matches_target(&owner, target_owner, reference_byte, ctx) =>
        {
            MethodReceiverTargetResolution::Target
        }
        EnclosingMemberOwnerResolution::Owner(owner)
            if receiver_owner_is_known_non_target(&owner, target_owner, reference_byte, ctx) =>
        {
            MethodReceiverTargetResolution::NonTarget
        }
        EnclosingMemberOwnerResolution::Owner(_) | EnclosingMemberOwnerResolution::Missing => {
            MethodReceiverTargetResolution::Missing
        }
        EnclosingMemberOwnerResolution::Ambiguous => MethodReceiverTargetResolution::Ambiguous,
    }
}

fn explicit_receiver_target_resolution(
    receiver: Node<'_>,
    call_arity: Option<usize>,
    ctx: &ScanCtx<'_>,
) -> MethodReceiverTargetResolution {
    method_receiver_target_resolution(
        receiver,
        declaring_owner_for_explicit_receiver(receiver, call_arity, ctx),
        ctx,
    )
}

fn call_function_target_resolution(
    function: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> MethodReceiverTargetResolution {
    let call_arity = ctx.ancestry.parent(function).and_then(|call| {
        (call.kind() == "call_expression")
            .then(|| {
                ctx.visibility
                    .call_arity_evidence(ctx.file, call, ctx.source)
                    .exact()
            })
            .flatten()
    });
    let Some(declaring_owner) = declaring_owner_from_call_function(function, call_arity, ctx)
    else {
        // A bare function identifier has an implicit receiver. Do not reinterpret
        // that identifier as a same-named type or value before enclosing-owner
        // lookup gets a chance to establish the member call.
        return MethodReceiverTargetResolution::Missing;
    };
    method_receiver_target_resolution(function, declaring_owner, ctx)
}

fn receiver_owner_matches_target(
    receiver_owner: &CodeUnit,
    target_owner: &CodeUnit,
    reference_byte: usize,
    ctx: &ScanCtx<'_>,
) -> bool {
    same_symbol(receiver_owner, target_owner)
        || same_logical_symbol(receiver_owner, target_owner)
            && (ctx.visibility.is_physically_visible(ctx.file, target_owner)
                || (ctx.spec.owner_is_forward_declaration
                    && ctx
                        .visibility
                        .is_physically_visible(ctx.file, receiver_owner))
                || visible_target_peer_matches_owner(receiver_owner, reference_byte, ctx)
                || target_group_contains_owner_peer(receiver_owner, ctx)
                // An identical definition of the class in a header this file
                // includes is the target's owner too, the relation forward
                // definition lookup crosses from the body's side (#6902).
                || ctx.visibility.same_logical_class_definition(
                    &ctx.analyzer,
                    receiver_owner,
                    target_owner,
                ))
}

fn receiver_owner_is_known_non_target(
    receiver_owner: &CodeUnit,
    target_owner: &CodeUnit,
    reference_byte: usize,
    ctx: &ScanCtx<'_>,
) -> bool {
    if receiver_owner_matches_target(receiver_owner, target_owner, reference_byte, ctx) {
        return false;
    }
    if !same_logical_symbol(receiver_owner, target_owner) {
        return true;
    }
    !ctx.target_group.iter().any(|target| {
        same_logical_symbol(target, &ctx.spec.target) && target.source() == target_owner.source()
    })
}

fn target_group_contains_owner_peer(owner: &CodeUnit, ctx: &ScanCtx<'_>) -> bool {
    ctx.visibility
        .external_type_declaration_visible_at(ctx.file, owner, usize::MAX)
        && ctx.target_group.iter().any(|target| {
            type_owner_of(&ctx.analyzer, target)
                .as_ref()
                .is_some_and(|target_owner| owner_peer_matches(target_owner, owner))
        })
}

fn owner_peer_matches(candidate_owner: &CodeUnit, owner: &CodeUnit) -> bool {
    same_symbol(candidate_owner, owner)
        || (same_logical_symbol(candidate_owner, owner)
            && candidate_owner.source() == owner.source())
}

fn visible_target_peer_matches_owner(
    owner: &CodeUnit,
    reference_byte: usize,
    ctx: &ScanCtx<'_>,
) -> bool {
    ctx.visibility
        .external_type_declaration_visible_at(ctx.file, owner, reference_byte)
        && ctx
            .visibility
            .visible_identifier_candidates(ctx.file, &ctx.spec.member_name)
            .any(|candidate| {
                cpp_callable_definitions_share_identity_evidence(
                    &ctx.analyzer,
                    candidate,
                    &ctx.spec.target,
                ) && ctx.visibility.declaration_visible_at(
                    &ctx.analyzer,
                    ctx.file,
                    candidate,
                    reference_byte,
                ) && type_owner_of(&ctx.analyzer, candidate)
                    .as_ref()
                    .is_some_and(|candidate_owner| owner_peer_matches(candidate_owner, owner))
            })
}

fn call_function_has_direct_self_receiver(function: Node<'_>, reference_is_c: bool) -> bool {
    match function.kind() {
        "field_expression" => function
            .child_by_field_name("argument")
            .or_else(|| function.child_by_field_name("object"))
            .is_some_and(|receiver| receiver_is_self_like(receiver, reference_is_c)),
        _ => receiver_is_self_like(function, reference_is_c),
    }
}

fn receiver_has_known_non_target(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let Some(owner) = ctx.spec.owner.as_ref() else {
        return false;
    };
    match node.kind() {
        "field_expression" => node
            .child_by_field_name("argument")
            .or_else(|| node.child_by_field_name("object"))
            .is_some_and(|receiver| {
                // `this` names the enclosing class, not necessarily the class that
                // declares the invoked member. Let the hierarchy-aware enclosing-owner
                // lookup decide whether this is a same-owner call, an inherited base
                // member, a nearer override, or an ambiguous base. Rejecting a derived
                // `this` merely because its immediate type differs from the target owner
                // drops genuine inherited calls (#2541).
                if receiver_is_self_like(
                    receiver,
                    ctx.analyzer.reference_uses_c_semantics(ctx.file),
                ) {
                    return false;
                }
                if receiver_is_known_function_declarator(receiver, ctx) {
                    return true;
                }
                let units = receiver_type_units(receiver, ctx.source, ctx);
                !units.is_empty()
                    && units.iter().all(|target| {
                        receiver_owner_is_known_non_target(target, owner, node.start_byte(), ctx)
                    })
            }),
        "call_expression" => node
            .child_by_field_name("function")
            .is_some_and(|function| receiver_has_known_non_target(function, ctx)),
        "pointer_expression" | "parenthesized_expression" | "subscript_expression" => node
            .child_by_field_name("argument")
            .or_else(|| node.named_child(0))
            .is_some_and(|child| receiver_has_known_non_target(child, ctx)),
        "identifier" | "this" if ctx.analyzer.reference_uses_c_semantics(ctx.file) => ctx
            .bindings
            .resolve_symbol(node_text(node, ctx.source))
            .as_precise()
            .is_some_and(|targets| {
                let units = targets
                    .iter()
                    .filter_map(|target| target.unit.as_ref())
                    .collect::<Vec<_>>();
                !units.is_empty()
                    && units.iter().all(|target| {
                        receiver_owner_is_known_non_target(target, owner, node.start_byte(), ctx)
                    })
            }),
        "this" => known_non_target_owner_context(node, ctx),
        "qualified_identifier" | "scoped_identifier" | "field_identifier" => {
            qualified_owner_is_known_non_target(node, ctx)
        }
        _ => false,
    }
}

fn receiver_is_known_function_declarator(receiver: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    if receiver.kind() != "identifier" {
        return false;
    }
    let receiver_name = node_text(receiver, ctx.source);
    let mut current = receiver;
    while let Some(parent) = ctx.ancestry.parent(current) {
        if parent.kind() == "compound_statement" {
            let mut cursor = parent.walk();
            for statement in parent.named_children(&mut cursor) {
                if statement.start_byte() >= receiver.start_byte() {
                    break;
                }
                if statement.kind() != "declaration" || statement.end_byte() > receiver.start_byte()
                {
                    continue;
                }
                let type_text = statement
                    .child_by_field_name("type")
                    .or_else(|| first_type_child(statement))
                    .map(|type_node| node_text(type_node, ctx.source));
                let mut declaration_cursor = statement.walk();
                for child in statement.named_children(&mut declaration_cursor) {
                    let declarator = if child.kind() == "init_declarator" {
                        child.child_by_field_name("declarator")
                    } else if is_declarator_node(child) {
                        Some(child)
                    } else {
                        None
                    };
                    let Some(declarator) = declarator else {
                        continue;
                    };
                    if declarator.kind() == "function_declarator"
                        && extract_variable_name(declarator, ctx.source)
                            .is_some_and(|name| name == receiver_name)
                        && function_declarator_parameters_have_known_types(declarator, ctx)
                        && !constructor_style_local_declaration(
                            ctx.visibility,
                            ctx.file,
                            ctx.source,
                            declarator,
                            type_text,
                            &ctx.bindings,
                        )
                    {
                        return true;
                    }
                }
            }
            return false;
        }
        current = parent;
    }
    false
}

fn function_declarator_parameters_have_known_types(
    declarator: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> bool {
    let Some(parameters) = declarator.child_by_field_name("parameters") else {
        return false;
    };
    let mut cursor = parameters.walk();
    parameters.named_children(&mut cursor).all(|parameter| {
        if !matches!(
            parameter.kind(),
            "parameter_declaration" | "optional_parameter_declaration"
        ) {
            return false;
        }
        let Some(type_node) = parameter
            .child_by_field_name("type")
            .or_else(|| first_type_child(parameter))
        else {
            return false;
        };
        type_node.kind() == "primitive_type"
            || ctx
                .visibility
                .resolve_type_node_result(ctx.file, type_node, ctx.source)
                .ok()
                .flatten()
                .is_some()
    })
}

#[derive(Clone, Copy, PartialEq, Eq)]
enum QualifiedOwnerResolution {
    Target,
    NonTarget,
    Unresolved,
}

#[derive(Clone)]
pub enum LexicalScopeResolution {
    Resolved(Vec<String>),
    Ambiguous,
    Missing,
}

/// One scan's memo of lexical scope reconstructions for one file, keyed by
/// the reconstruction's anchor range and flags, with the file's recovered
/// namespace regions that the key and the reconstruction both read.
pub struct LexicalScopeCache {
    resolutions: RefCell<HashMap<(usize, usize, bool, bool), LexicalScopeResolution>>,
    orphaned: Arc<OrphanedNamespaceScopeIndex>,
}

impl LexicalScopeCache {
    fn new(visibility: &VisibilityIndex<'_>, file: &ProjectFile) -> Self {
        Self {
            resolutions: RefCell::new(HashMap::default()),
            orphaned: orphaned_namespace_scopes(visibility, file),
        }
    }
}

/// The namespaces parse recovery dropped from `file`, memoized on the
/// analyzer (issue #1537).
fn orphaned_namespace_scopes(
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
) -> Arc<OrphanedNamespaceScopeIndex> {
    visibility
        .cpp()
        .orphaned_namespace_scopes(visibility.token(), file)
}

fn qualified_owner_matches(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    qualified_owner_resolution(node, ctx) == QualifiedOwnerResolution::Target
}

fn qualified_owner_is_known_non_target(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    qualified_owner_resolution(node, ctx) == QualifiedOwnerResolution::NonTarget
}

fn is_structurally_qualified(node: Node<'_>) -> bool {
    matches!(node.kind(), "qualified_identifier" | "scoped_identifier")
        && qualified_name_has_concrete_scope_separators(node)
}

fn qualified_owner_resolution(node: Node<'_>, ctx: &ScanCtx<'_>) -> QualifiedOwnerResolution {
    let Some(target_owner) = ctx.spec.owner.as_ref() else {
        return QualifiedOwnerResolution::Unresolved;
    };
    let Some((components, global)) = qualified_callable_owner_components(node, ctx.source) else {
        return QualifiedOwnerResolution::Unresolved;
    };
    // A malformed wrapper can make the parser-derived enclosing owner look
    // like the lexical namespace (for example tinyxml2's macro-prefixed
    // XMLHandle declarations). Recover the target namespace only while this
    // function owns scope reconstruction. An explicit recovered scope is
    // authoritative and enters the scoped resolver directly.
    if !global
        && !matches!(
            enclosing_lexical_scope_components(
                node,
                &ctx.analyzer,
                ctx.visibility,
                ctx.file,
                ctx.source,
            ),
            LexicalScopeResolution::Resolved(_)
        )
    {
        return QualifiedOwnerResolution::Unresolved;
    }
    match resolve_type_components_lexically_at_for_target_with_scope_cache(
        node,
        &components,
        global,
        &ctx.analyzer,
        ctx.visibility,
        &ctx.ordinary_type_imports,
        ctx.file,
        ctx.source,
        target_owner,
        false,
        Some(&ctx.lexical_scope_cache),
    ) {
        LexicalTypeResolution::Resolved { unit: owner, .. } => {
            if receiver_owner_matches_target(&owner, target_owner, node.start_byte(), ctx) {
                return QualifiedOwnerResolution::Target;
            }
            match cached_declaring_member_owner(&owner, ctx) {
                EnclosingMemberOwnerResolution::Owner(declaring_owner)
                    if receiver_owner_matches_target(
                        &declaring_owner,
                        target_owner,
                        node.start_byte(),
                        ctx,
                    ) =>
                {
                    QualifiedOwnerResolution::Target
                }
                EnclosingMemberOwnerResolution::Owner(declaring_owner)
                    if receiver_owner_is_known_non_target(
                        &declaring_owner,
                        target_owner,
                        node.start_byte(),
                        ctx,
                    ) =>
                {
                    QualifiedOwnerResolution::NonTarget
                }
                EnclosingMemberOwnerResolution::Owner(_)
                | EnclosingMemberOwnerResolution::Ambiguous => QualifiedOwnerResolution::Unresolved,
                EnclosingMemberOwnerResolution::Missing
                    if same_visible_symbol(&owner, target_owner) =>
                {
                    QualifiedOwnerResolution::Unresolved
                }
                EnclosingMemberOwnerResolution::Missing => QualifiedOwnerResolution::NonTarget,
            }
        }
        LexicalTypeResolution::Ambiguous | LexicalTypeResolution::Missing => {
            QualifiedOwnerResolution::Unresolved
        }
    }
}

fn qualified_callable_owner_components(
    node: Node<'_>,
    source: &str,
) -> Option<(Vec<String>, bool)> {
    if !matches!(node.kind(), "qualified_identifier" | "scoped_identifier")
        || !qualified_name_has_concrete_scope_separators(node)
    {
        return None;
    }
    let owner = qualified_owner_components(node, source)?;
    Some((owner.names, owner.global))
}

fn type_reference_components(node: Node<'_>, source: &str) -> Option<(Vec<String>, bool)> {
    if !matches!(
        node.kind(),
        "identifier"
            | "type_identifier"
            | "namespace_identifier"
            | "qualified_identifier"
            | "scoped_identifier"
            | "scoped_type_identifier"
            | "template_type"
            | "template_function"
    ) {
        return None;
    }
    let components = cpp_type_name_components(node, source)?;
    (!components.is_empty()).then_some((components, is_globally_qualified_cpp_name(node)))
}

pub fn enclosing_namespace_components(node: Node<'_>, source: &str) -> Vec<String> {
    let mut namespaces = Vec::new();
    for parent in enclosing_cpp_namespace_nodes(node) {
        if let Some(name) = parent.child_by_field_name("name") {
            let mut components = Vec::new();
            if append_cpp_name_components(name, source, &mut components).is_some() {
                namespaces.push(components);
            }
        }
    }
    namespaces.into_iter().flatten().collect()
}

pub fn enclosing_lexical_scope_components(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    source: &str,
) -> LexicalScopeResolution {
    enclosing_lexical_scope_components_with_unresolved_owner(
        node,
        analyzer,
        visibility,
        file,
        source,
        false,
        false,
        &orphaned_namespace_scopes(visibility, file),
    )
}

#[allow(clippy::too_many_arguments)]
fn cached_enclosing_lexical_scope_components_with_unresolved_owner(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    source: &str,
    allow_structured_unresolved_owner: bool,
    ignore_function_owner: bool,
    cache: Option<&LexicalScopeCache>,
) -> LexicalScopeResolution {
    let Some(cache) = cache else {
        return enclosing_lexical_scope_components_with_unresolved_owner(
            node,
            analyzer,
            visibility,
            file,
            source,
            allow_structured_unresolved_owner,
            ignore_function_owner,
            &orphaned_namespace_scopes(visibility, file),
        );
    };
    let orphaned = &cache.orphaned;
    let (anchor_start, anchor_end) = lexical_scope_cache_anchor(node);
    // A namespace body or translation unit anchor spans every recovered
    // region among its children, whose scopes differ; the region bounds keep
    // the key exact there and leave an anchor inside one region unchanged.
    let (anchor_start, anchor_end) = match orphaned.region_at(node.start_byte()) {
        Some(region) => (anchor_start.max(region.start), anchor_end.min(region.end)),
        None => (anchor_start, anchor_end),
    };
    let key = (
        anchor_start,
        anchor_end,
        allow_structured_unresolved_owner,
        ignore_function_owner,
    );
    if let Some(cached) = cache.resolutions.borrow().get(&key).cloned() {
        return cached;
    }
    let resolved = enclosing_lexical_scope_components_with_unresolved_owner(
        node,
        analyzer,
        visibility,
        file,
        source,
        allow_structured_unresolved_owner,
        ignore_function_owner,
        orphaned,
    );
    cache.resolutions.borrow_mut().insert(key, resolved.clone());
    resolved
}

fn lexical_scope_cache_anchor(node: Node<'_>) -> (usize, usize) {
    let mut current = node;
    loop {
        if matches!(
            current.kind(),
            "function_definition"
                | "class_specifier"
                | "struct_specifier"
                | "union_specifier"
                | "namespace_definition"
                | "translation_unit"
        ) {
            return (current.start_byte(), current.end_byte());
        }
        let Some(parent) = current.parent() else {
            return (current.start_byte(), current.end_byte());
        };
        current = parent;
    }
}

#[allow(clippy::too_many_arguments)]
fn enclosing_lexical_scope_components_with_unresolved_owner(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    source: &str,
    allow_structured_unresolved_owner: bool,
    ignore_function_owner: bool,
    orphaned: &OrphanedNamespaceScopeIndex,
) -> LexicalScopeResolution {
    #[cfg(any(test, feature = "test-support"))]
    LEXICAL_SCOPE_RECONSTRUCTIONS_FOR_TEST.with(|count| count.set(count.get() + 1));
    // One ancestor climb collects the namespace chain, the class chain, the
    // nearest function definition and both displaced-class-shape facts.
    // `Node::parent` re-descends from the root on every call (tree-sitter
    // 0.24+), so the four separate climbs this replaces each cost another
    // near-full-AST scan per reconstruction on a large flat file (#1927).
    let mut namespaces = Vec::new();
    let mut classes = Vec::new();
    let mut function_definition = None;
    let mut displaced_class_scope = false;
    let mut current = node.parent();
    while let Some(parent) = current {
        match parent.kind() {
            "namespace_definition" => {
                if let Some(name) = parent.child_by_field_name("name") {
                    let mut components = Vec::new();
                    if append_cpp_name_components(name, source, &mut components).is_some() {
                        namespaces.push((
                            parent.start_byte(),
                            components,
                            namespace_definition_has_real_braces(parent),
                        ));
                    }
                }
            }
            "class_specifier" | "struct_specifier" | "union_specifier" => {
                if let Some(name) = parent.child_by_field_name("name") {
                    let mut components = Vec::new();
                    if append_cpp_name_components(name, source, &mut components).is_some() {
                        classes.push(components);
                    }
                }
            }
            "function_definition" => {
                if function_definition.is_none() {
                    function_definition = Some(parent);
                }
                displaced_class_scope = displaced_class_scope
                    || parent.child_by_field_name("type").is_some_and(|type_node| {
                        matches!(
                            type_node.kind(),
                            "class_specifier" | "struct_specifier" | "union_specifier"
                        )
                    })
                    || is_malformed_wrapper_function_definition(parent);
            }
            _ => {}
        }
        current = parent.parent();
    }
    namespaces.reverse();
    // The parsed chain can stop short of the namespaces tree-sitter's error
    // recovery closed early; the orphaned index restores them (#1537).
    let namespace = orphaned.restore_enclosing_namespaces(namespaces, node.start_byte());
    let mut scope = namespace.clone();
    // A malformed namespace-sentinel wrapper can parse `namespace a::b` as a
    // qualified function declarator. It is recovery scaffolding, not a real
    // callable owner, and must not overwrite the indexed class scope retained
    // by the wrapper body (#2249).
    let has_qualified_function_owner = function_definition
        .filter(|function| !is_malformed_wrapper_function_definition(*function))
        .and_then(function_definition_owner_lookup_node)
        .is_some_and(|owner| {
            is_structurally_qualified(owner) && !is_macro_decorated_function_owner(owner)
        });
    let indexed_scope = displaced_class_scope
        .then(|| {
            indexed_structural_class_scope(visibility, file, node, source)
                .or_else(|| indexed_enclosing_owner_scope(analyzer, visibility, file, node))
        })
        .flatten()
        .or_else(|| {
            // A qualified out-of-line definition can lose its class owner from
            // the parser tree when a namespace sentinel or export macro wraps
            // the declaration.  Recover the indexed owner scope up front so
            // all unqualified type references in the body see the same class
            // boundary as C++ lookup, including aliases in parameters and
            // local declarations (not only template-argument leaves).
            (has_qualified_function_owner && function_definition.is_some())
                .then(|| indexed_enclosing_owner_scope(analyzer, visibility, file, node))
                .flatten()
                .filter(|indexed| {
                    qualified_owner_scope_is_recoverable(
                        indexed,
                        &namespace,
                        &classes,
                        function_definition
                            .and_then(function_definition_owner_lookup_node)
                            .and_then(|owner| qualified_callable_owner_components(owner, source))
                            .map(|(components, _)| components),
                    )
                })
        })
        .or_else(|| {
            // A nested class declaration can likewise lose one of its outer
            // class ancestors from the CST.  Prefer the exact indexed
            // structural class scope. Its same-file declaration range and
            // exact template-id match already prove the owner, including a
            // specialization whose parser component retains only the primary
            // name. Keep the suffix guard for graph-only recovery, which lacks
            // that direct syntax-range proof.
            indexed_structural_class_scope(visibility, file, node, source).or_else(|| {
                indexed_enclosing_owner_scope(analyzer, visibility, file, node).filter(|indexed| {
                    qualified_owner_scope_is_recoverable(indexed, &namespace, &classes, None)
                })
            })
        })
        .or_else(|| {
            // Retain the existing indexed lexical-scope recovery for
            // unqualified function bodies.  It is intentionally last so a
            // canonical class owner wins whenever one is available.
            (classes.is_empty() && function_definition.is_some() && !has_qualified_function_owner)
                .then(|| indexed_enclosing_lexical_scope(analyzer, file, node))
                .flatten()
                .filter(|indexed| indexed.len() > namespace.len())
        });
    if let Some(indexed_scope) = indexed_scope.as_ref() {
        // A macro-displaced namespace can leave the parser with the real class
        // body but no namespace ancestor. Prefer the structural class match;
        // partial specializations whose structured name cannot round-trip use
        // the exact indexed enclosing-owner chain instead.
        scope = indexed_scope.clone();
        classes.clear();
    }

    if !ignore_function_owner
        && has_qualified_function_owner
        && let Some(function) = function_definition.and_then(function_definition_owner_lookup_node)
    {
        let Some((owner, global)) = qualified_callable_owner_components(function, source) else {
            return LexicalScopeResolution::Missing;
        };
        // Resolve the out-of-line owner from the parser namespace before the
        // provisional indexed parent can influence the answer. Per-file
        // extraction can assign the first same-depth using namespace to a
        // bare owner. The structured using resolver instead selects the
        // namespace whose visible class has the owner name (#1838).
        let imports = visibility.ordinary_type_import_cell(file);
        let owner_resolution = resolve_type_components_lexically_at_scoped(
            function,
            &owner,
            global,
            analyzer,
            visibility,
            &imports,
            file,
            source,
            None,
            false,
            false,
            false,
            namespace.clone(),
        );
        match owner_resolution {
            LexicalTypeResolution::Resolved {
                unit, components, ..
            } if is_indexed_class_owner(analyzer, &unit) => {
                scope = components;
                classes.clear();
            }
            LexicalTypeResolution::Ambiguous => return LexicalScopeResolution::Ambiguous,
            LexicalTypeResolution::Resolved { .. } | LexicalTypeResolution::Missing => {
                match visibility
                    .resolve_type_components_lexically(analyzer, file, &owner, global, &scope)
                {
                    LexicalTypeResolution::Resolved { components, .. } => scope = components,
                    LexicalTypeResolution::Ambiguous => return LexicalScopeResolution::Ambiguous,
                    LexicalTypeResolution::Missing if allow_structured_unresolved_owner => {
                        if let Some(indexed) = indexed_scope.as_ref().filter(|indexed| {
                            qualified_owner_scope_is_recoverable(
                                indexed,
                                &namespace,
                                &classes,
                                Some(owner.clone()),
                            )
                        }) {
                            scope = indexed.clone();
                        } else {
                            scope = if global || owner.starts_with(&namespace) {
                                owner
                            } else {
                                let mut relative = namespace;
                                relative.extend(owner);
                                relative
                            };
                        }
                    }
                    LexicalTypeResolution::Missing => {
                        // Structural lexical resolution cannot see an owner class that
                        // is reachable only through an in-scope `using namespace`
                        // directive, so it would otherwise hard-fail here. The indexed
                        // definition already carries the true fully-qualified owner
                        // (its package reflects the directive), so recover the real
                        // enclosing scope from the analyzer graph -- exactly the scope
                        // chain real C++ unqualified lookup traverses. Only the strict
                        // callers reach this arm; the best-effort callers above keep
                        // their existing structural guess (and its query profile).
                        match indexed_enclosing_owner_scope(analyzer, visibility, file, node)
                            .or_else(|| {
                                indexed_namespace_qualified_scope(
                                    analyzer, visibility, file, node, &owner,
                                )
                            }) {
                            Some(indexed) => scope = indexed,
                            None => return LexicalScopeResolution::Missing,
                        }
                    }
                }
            }
        }
    }

    classes.reverse();
    scope.extend(classes.into_iter().flatten());
    LexicalScopeResolution::Resolved(scope)
}

fn has_recovered_class_shape_ancestor(node: Node<'_>) -> bool {
    let mut current = node.parent();
    while let Some(parent) = current {
        if parent.kind() == "function_definition"
            && parent.child_by_field_name("type").is_some_and(|type_node| {
                matches!(
                    type_node.kind(),
                    "class_specifier" | "struct_specifier" | "union_specifier"
                )
            })
        {
            return true;
        }
        current = parent.parent();
    }
    false
}

fn has_malformed_wrapper_function_definition_ancestor(node: Node<'_>) -> bool {
    let mut current = node.parent();
    while let Some(parent) = current {
        if parent.kind() == "function_definition"
            && is_malformed_wrapper_function_definition(parent)
        {
            return true;
        }
        current = parent.parent();
    }
    false
}

/// Whether a function definition is a recovery wrapper with a non-function
/// declarator. The older grammar's evidence is parser damage; the
/// macro-declaration grammar keeps the same envelope clean, where a
/// `macro_modifier`/`macro_modifier_declarator`/`macro_type_specifier` head is
/// admitted only where the parse would otherwise contain an error.
pub fn is_malformed_wrapper_function_definition(node: Node<'_>) -> bool {
    let mut cursor = node.walk();
    let recovery_evidence = node.has_error()
        || node.named_children(&mut cursor).any(|child| {
            matches!(
                child.kind(),
                "macro_modifier" | "macro_modifier_declarator" | "macro_type_specifier"
            )
        });
    recovery_evidence
        && node
            .child_by_field_name("declarator")
            .is_some_and(|declarator| {
                declarator.kind() != "function_declarator"
                    && first_descendant_of_kind(declarator, "function_declarator").is_none()
            })
}

/// Tree-sitter can make an attribute/nullability macro look like the namespace
/// component of a qualified function owner when it appears between the return
/// type and the declarator (for example `CordRep* absl_nullable VerifyTree`).
/// The recovered owner is not a C++ lexical owner, so callers resolving the
/// ordinary return/parameter type must retain the surrounding namespace scope.
fn is_macro_decorated_function_owner(node: Node<'_>) -> bool {
    node.child_by_field_name("scope")
        .and_then(|scope| recovered_macro_decorated_type_node(scope))
        .is_some()
}

fn indexed_structural_class_scope(
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    node: Node<'_>,
    source: &str,
) -> Option<Vec<String>> {
    let mut current = node.parent();
    while let Some(parent) = current {
        if matches!(
            parent.kind(),
            "class_specifier" | "struct_specifier" | "union_specifier"
        ) {
            return visibility.indexed_structural_class_scope(file, parent, source);
        }
        current = parent.parent();
    }
    None
}

/// Check that an indexed owner scope is a structured completion of the parser
/// scope rather than an unrelated same-spelled declaration.
///
/// Error recovery around C++ namespace sentinels can preserve only a subset of
/// the namespace/class chain.  The indexed definition still carries the full
/// owner path, so require every surviving parser component to occur in order
/// and require any explicit qualified function owner to be the terminal
/// suffix.  An empty parser scope is accepted only with that qualified-owner
/// suffix evidence; a lone top-level short name is not evidence that a
/// namespace was lost.
fn qualified_owner_scope_is_recoverable(
    indexed: &[String],
    namespace: &[String],
    classes: &[Vec<String>],
    qualified_owner: Option<Vec<String>>,
) -> bool {
    if let Some(owner) = qualified_owner {
        if indexed.len() <= owner.len() || !indexed.ends_with(&owner) {
            return false;
        }
        // A malformed namespace sentinel can erase every parser namespace
        // ancestor.  The indexed enclosing callable still provides an
        // authoritative class owner, so the qualified owner suffix itself is
        // enough evidence in that case.  When namespace components survived,
        // retain the stricter subsequence check below.
        if namespace.is_empty() {
            return true;
        }
        if indexed.len() <= namespace.len() {
            return false;
        }
        return super::cpp_namespace_path_is_ordered_subsequence(namespace, indexed);
    }
    let class_components = classes.iter().flatten().cloned().collect::<Vec<_>>();
    if !class_components.is_empty() {
        return indexed.len() > class_components.len() && indexed.ends_with(&class_components);
    }
    if namespace.is_empty() || indexed.len() <= namespace.len() {
        return false;
    }
    super::cpp_namespace_path_is_ordered_subsequence(namespace, indexed)
}

/// Whether `unit` is a real (non-alias) class owner. A `using` alias never
/// counts as the true lexical owner recovered from the indexed graph.
fn is_indexed_class_owner(analyzer: &CppGraphSource<'_>, unit: &CodeUnit) -> bool {
    unit.is_class()
        && !analyzer
            .type_alias_provider()
            .is_some_and(|provider| provider.is_type_alias(unit))
}

/// Recover the enclosing member's true lexical scope from the *indexed*
/// definition when structural resolution cannot see the owner class.
///
/// An out-of-line member defined at file scope (`int HTMLLayout::method()
/// {...}`) whose owner class is reachable only through an in-scope `using
/// namespace X;` directive cannot be resolved by `resolve_type_components_
/// lexically`, which walks structural lexical tiers and never consults
/// using-directives. The definition itself, however, is indexed with its true
/// fully-qualified identity (its package already reflects the directive), so
/// the analyzer graph knows the real owner. Walk from the reference's indexed
/// enclosing code unit up to the innermost enclosing class and return that
/// class's fully-qualified scope components (e.g. `["log4cxx", "HTMLLayout"]`)
/// -- exactly the scope chain C++ unqualified lookup traverses.
fn indexed_enclosing_owner_scope(
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    node: Node<'_>,
) -> Option<Vec<String>> {
    visibility.indexed_enclosing_owner_scope(analyzer, file, node)
}

/// Recover the lexical scope of an out-of-line definition whose syntactic
/// qualifier names a *namespace* rather than a class (`void out::target(int)
/// {...}` written at file scope, issue #3096).
///
/// `indexed_enclosing_owner_scope` looks for an enclosing *class*, so it finds
/// nothing here and the strict caller would fail closed for every unqualified
/// reference in the body. C++ unqualified lookup inside such a definition
/// proceeds from the named namespace outward, exactly as inside a `namespace
/// out { ... }` block, and the indexed definition already carries that scope
/// (`["out"]` for `out::target`).
///
/// Take it only when a namespace of that name is visible from the file and the
/// indexed scope ends with the syntactic qualifier. A qualifier naming a class
/// the graph does not hold (`void MissingContainer::call()`) has no such
/// namespace, so it still fails closed -- and it is rejected by the in-memory
/// visibility index, before any indexed enclosing-unit query.
fn indexed_namespace_qualified_scope(
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    node: Node<'_>,
    owner: &[String],
) -> Option<Vec<String>> {
    let name = owner.last().expect("a qualified owner has one component");
    if !visibility
        .visible_identifier_candidates(file, name)
        .any(|unit| unit.is_module())
    {
        return None;
    }
    let indexed = indexed_enclosing_lexical_scope(analyzer, file, node)?;
    indexed.ends_with(owner).then_some(indexed)
}

fn cached_indexed_enclosing_class_owner(node: Node<'_>, ctx: &ScanCtx<'_>) -> Option<CodeUnit> {
    let start = enclosing_context(node, ctx).enclosing?;
    brokk_bifrost_core::analyzer::usages::common::enclosing_owner_chain(start, |unit| {
        ctx.analyzer.parent_of(unit)
    })
    .find(|unit| is_indexed_class_owner(&ctx.analyzer, unit))
}

pub fn resolve_type_node_lexically(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
) -> LexicalTypeResolution {
    let Some((components, global)) = type_reference_components(node, source) else {
        return LexicalTypeResolution::Missing;
    };
    let resolution = resolve_type_components_lexically_at(
        node,
        &components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
    );
    if !is_cpp_template_argument_type_leaf(node) {
        return resolution;
    }

    // Error recovery can detach a member function from its class while
    // leaving an unqualified type argument (for example `error_type` in
    // `expected<..., error_type>`). The normal structural scope then lacks
    // the class owner and resolves the wrong same-spelled alias, or fails
    // closed. The indexed enclosing unit still carries the authoritative
    // class scope; retry only this narrowly-shaped leaf with that scope.
    let Some(indexed_scope) = indexed_enclosing_lexical_scope(analyzer, file, node) else {
        return resolution;
    };
    let namespace_scope = enclosing_namespace_components(node, source);
    if indexed_scope.len() <= namespace_scope.len() {
        return resolution;
    }
    let indexed = resolve_type_components_in_authoritative_scope(
        node,
        &components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        None,
        false,
        false,
        false,
        indexed_scope,
    );
    match indexed {
        LexicalTypeResolution::Resolved { ref unit, .. }
            if !visibility
                .external_type_candidate_visible_in_context(analyzer, file, unit, node) =>
        {
            resolution
        }
        LexicalTypeResolution::Resolved { .. } => indexed,
        _ => resolution,
    }
}

/// Resolve a type lexically, using the target to guide incomplete evidence.
/// A lexical resolution visible in context wins over target guidance even when
/// its unit and candidates do not include the target.
#[allow(clippy::too_many_arguments)]
pub fn resolve_type_node_lexically_for_target(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    target: &CodeUnit,
    scope_cache: Option<&LexicalScopeCache>,
    recovered_scope: Option<&[String]>,
) -> LexicalTypeResolution {
    let Some((reference_components, global)) = type_reference_components(node, source) else {
        return LexicalTypeResolution::Missing;
    };
    let terminal = reference_components
        .last()
        .expect("type reference components are non-empty");
    if !visibility.coarse_unqualified_type_reference_may_resolve(file, terminal) {
        return LexicalTypeResolution::Missing;
    }
    let template_arguments = cpp_template_reference_arguments(node, source);
    let selects_concrete_specialization =
        template_arguments.is_some() && visibility.is_template_specialization(target);
    if !selects_concrete_specialization
        && !visibility.structured_type_reference_may_resolve_to_target(
            analyzer,
            file,
            std::slice::from_ref(terminal),
            false,
            &[],
            target,
        )
    {
        return LexicalTypeResolution::Missing;
    }
    if let Some(arguments) = template_arguments.as_ref() {
        let alias_resolution = if let Some(recovered_scope) = recovered_scope {
            resolve_type_components_lexically_at_preserving_alias_with_recovered_scope(
                node,
                &reference_components,
                global,
                analyzer,
                visibility,
                ordinary_type_imports,
                file,
                source,
                recovered_scope,
            )
        } else {
            resolve_type_components_lexically_at_preserving_alias_with_scope_cache(
                node,
                &reference_components,
                global,
                analyzer,
                visibility,
                ordinary_type_imports,
                file,
                source,
                scope_cache,
            )
        };
        return match alias_resolution {
            LexicalTypeResolution::Resolved {
                unit,
                components,
                candidates,
            } if visibility.template_alias_arguments_preserve_target(
                analyzer, file, &unit, arguments, target,
            ) =>
            {
                LexicalTypeResolution::Resolved {
                    unit: target.clone(),
                    components,
                    candidates,
                }
            }
            LexicalTypeResolution::Resolved {
                unit,
                components,
                candidates,
            } => match visibility.resolve_template_arguments(file, unit.clone(), arguments) {
                Ok(resolved_unit) => {
                    let target_guided = (!same_visible_symbol(&resolved_unit, target))
                        .then(|| {
                            target_guided_malformed_template_alias_resolution(
                                node,
                                analyzer,
                                visibility,
                                file,
                                arguments,
                                &reference_components,
                                target,
                            )
                        })
                        .flatten();
                    target_guided.unwrap_or(LexicalTypeResolution::Resolved {
                        unit: resolved_unit,
                        components,
                        candidates,
                    })
                }
                Err(_) => LexicalTypeResolution::Ambiguous,
            },
            LexicalTypeResolution::Missing => {
                let target_preserving = if let Some(recovered_scope) = recovered_scope {
                    resolve_type_components_lexically_at_for_target_with_recovered_scope(
                        node,
                        &reference_components,
                        global,
                        analyzer,
                        visibility,
                        ordinary_type_imports,
                        file,
                        source,
                        target,
                        true,
                        recovered_scope,
                    )
                } else {
                    resolve_type_components_lexically_at_for_target_with_scope_cache(
                        node,
                        &reference_components,
                        global,
                        analyzer,
                        visibility,
                        ordinary_type_imports,
                        file,
                        source,
                        target,
                        true,
                        scope_cache,
                    )
                };
                match target_preserving {
                    LexicalTypeResolution::Resolved {
                        unit: _,
                        components,
                        candidates,
                    } if template_reference_candidates_select_target(
                        node,
                        &candidates,
                        analyzer,
                        visibility,
                        file,
                        source,
                        target,
                    ) =>
                    {
                        LexicalTypeResolution::Resolved {
                            unit: target.clone(),
                            components,
                            candidates,
                        }
                    }
                    _ => target_guided_malformed_template_alias_resolution(
                        node,
                        analyzer,
                        visibility,
                        file,
                        arguments,
                        &reference_components,
                        target,
                    )
                    .unwrap_or(LexicalTypeResolution::Missing),
                }
            }
            LexicalTypeResolution::Ambiguous => LexicalTypeResolution::Ambiguous,
        };
    }
    let resolution = if let Some(recovered_scope) = recovered_scope {
        resolve_type_components_lexically_at_for_target_with_recovered_scope(
            node,
            &reference_components,
            global,
            analyzer,
            visibility,
            ordinary_type_imports,
            file,
            source,
            target,
            true,
            recovered_scope,
        )
    } else {
        resolve_type_components_lexically_at_for_target_with_scope_cache(
            node,
            &reference_components,
            global,
            analyzer,
            visibility,
            ordinary_type_imports,
            file,
            source,
            target,
            true,
            scope_cache,
        )
    };
    let resolution = if matches!(resolution, LexicalTypeResolution::Missing) {
        target_guided_qualified_namespace_function_type_resolution(
            node,
            &reference_components,
            global,
            analyzer,
            visibility,
            ordinary_type_imports,
            file,
            source,
            target,
        )
        .unwrap_or(resolution)
    } else {
        resolution
    };
    if !is_cpp_template_argument_type_leaf(node) {
        return resolution;
    }

    // Preprocessor recovery can lift a member declaration out of its class
    // field list.  The unqualified template argument is then resolved from
    // the namespace only, even though the indexed enclosing callable still
    // identifies the class owner.  Retry this exact leaf against that
    // structured owner scope; ordinary type nodes must continue to use the
    // parser-derived lexical scope so unrelated same-spelled aliases remain
    // excluded.
    let Some(indexed_scope) = indexed_enclosing_lexical_scope(analyzer, file, node) else {
        return resolution;
    };
    let namespace_scope = enclosing_namespace_components(node, source);
    if indexed_scope.len() <= namespace_scope.len() {
        return resolution;
    }
    let indexed = visibility.resolve_type_components_lexically_for_target(
        analyzer,
        file,
        &reference_components,
        global,
        &indexed_scope,
        target,
    );
    match indexed {
        LexicalTypeResolution::Resolved { ref unit, .. }
            if visibility
                .external_type_candidate_visible_in_context(analyzer, file, unit, node) =>
        {
            indexed
        }
        _ => resolution,
    }
}

/// Recover the lexical namespace of an out-of-line namespace function whose
/// relative qualifier is reachable through a `using namespace` directive.
///
/// Per-file declaration extraction can attach `void schema::consume(...)` to
/// the first visible namespace prefix when more than one using-directive is
/// active. A matching visible free-function declaration still proves the
/// complete namespace. Target-guided inverse lookup may use that namespace to
/// retry a parameter or body type, but only when the target lives in the same
/// namespace and the declaration's callable arity matches the definition.
#[allow(clippy::too_many_arguments)]
fn target_guided_qualified_namespace_function_type_resolution(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    target: &CodeUnit,
) -> Option<LexicalTypeResolution> {
    let function_definition = std::iter::successors(Some(node), |current| current.parent())
        .find(|current| current.kind() == "function_definition")?;
    let function = function_definition_name_node(function_definition)?;
    let (owner, owner_global) = qualified_callable_owner_components(function, source)?;
    let target_namespace = target.package_name();
    if target_namespace.is_empty() {
        return None;
    }
    let target_scope = brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
        brokk_bifrost_core::analyzer::Language::Cpp,
        target_namespace,
    );
    if (owner_global && target_scope != owner) || (!owner_global && !target_scope.ends_with(&owner))
    {
        return None;
    }

    let function_name = node_text(function_terminal_node(function), source);
    let definition_unit = canonical_callable_at_node(
        function_definition,
        analyzer,
        visibility,
        file,
        source,
        TargetKind::FreeFunction,
    )?;
    let definition_arity = cpp_callable_arity(analyzer, &definition_unit)?.total();
    let declaration_proves_namespace = visibility
        .visible_identifier_candidates(file, function_name)
        .filter(|candidate| {
            candidate.is_function()
                && type_owner_of(analyzer, candidate).is_none()
                && candidate.package_name() == target_namespace
        })
        .any(|candidate| {
            cpp_callable_arity(analyzer, candidate)
                .is_none_or(|known| known.accepts(definition_arity))
        });
    if !declaration_proves_namespace {
        return None;
    }

    let resolution = resolve_type_components_lexically_at_scoped(
        node,
        components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        Some(target),
        true,
        false,
        false,
        target_scope,
    );
    match &resolution {
        LexicalTypeResolution::Resolved {
            unit, candidates, ..
        } if (same_visible_symbol(unit, target)
            || candidates
                .iter()
                .any(|candidate| same_visible_symbol(candidate, target)))
            && visibility
                .external_type_candidate_visible_in_context(analyzer, file, unit, node) =>
        {
            Some(resolution)
        }
        LexicalTypeResolution::Resolved { .. }
        | LexicalTypeResolution::Ambiguous
        | LexicalTypeResolution::Missing => None,
    }
}

#[allow(clippy::too_many_arguments)]
fn target_guided_malformed_template_alias_resolution(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    arguments: &[brokk_bifrost_core::analyzer::model::CppTemplateExpression],
    components: &[String],
    target: &CodeUnit,
) -> Option<LexicalTypeResolution> {
    if components.len() != 1 || !has_malformed_wrapper_function_definition_ancestor(node) {
        return None;
    }

    let identifier = &components[0];
    let namespace =
        visibility.target_preserving_reference_namespace(analyzer, file, identifier, target)?;
    let namespace_name = namespace.join("::");
    let candidates = visibility
        .visible_identifier_candidates(file, identifier)
        .filter(|candidate| {
            cpp_namespace_for(candidate).unwrap_or_default() == namespace_name
                && visibility.type_candidate_may_be_visible_before_reference(
                    analyzer,
                    file,
                    candidate,
                    node.start_byte(),
                )
        })
        .cloned()
        .collect::<Vec<_>>();
    let first = candidates.first()?;
    if !candidates
        .iter()
        .all(|candidate| same_logical_symbol(first, candidate))
        || !candidates.iter().all(|candidate| {
            visibility.template_alias_arguments_preserve_target(
                analyzer, file, candidate, arguments, target,
            )
        })
    {
        return None;
    }

    let mut resolved_components = namespace;
    resolved_components.push(identifier.clone());
    Some(LexicalTypeResolution::Resolved {
        unit: target.clone(),
        components: resolved_components,
        candidates,
    })
}

fn resolve_type_node_lexically_for_target_without_visibility(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    source: &str,
    target: &CodeUnit,
) -> LexicalTypeResolution {
    let Some((components, global)) = type_reference_components(node, source) else {
        return LexicalTypeResolution::Missing;
    };
    let lexical_scope = match enclosing_lexical_scope_components_with_unresolved_owner(
        node,
        analyzer,
        visibility,
        file,
        source,
        true,
        recovered_macro_decorated_declarator_type(node)
            == Some(RecoveredDeclaratorTypeContext::FunctionDefinition),
        &orphaned_namespace_scopes(visibility, file),
    ) {
        LexicalScopeResolution::Resolved(scope) => scope,
        LexicalScopeResolution::Ambiguous => return LexicalTypeResolution::Ambiguous,
        LexicalScopeResolution::Missing => return LexicalTypeResolution::Missing,
    };
    visibility.resolve_type_components_lexically_for_target(
        analyzer,
        file,
        &components,
        global,
        &lexical_scope,
        target,
    )
}

fn type_node_has_exact_target_identity_without_visibility(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    source: &str,
    target: &CodeUnit,
) -> bool {
    let Some((components, global)) = type_reference_components(node, source) else {
        return false;
    };
    let LexicalScopeResolution::Resolved(lexical_scope) =
        enclosing_lexical_scope_components_with_unresolved_owner(
            node,
            analyzer,
            visibility,
            file,
            source,
            true,
            recovered_macro_decorated_declarator_type(node)
                == Some(RecoveredDeclaratorTypeContext::FunctionDefinition),
            &orphaned_namespace_scopes(visibility, file),
        )
    else {
        return false;
    };
    let target_name = cpp_name_for(target);
    lexical_component_tiers(&components, global, &lexical_scope)
        .any(|qualified| qualified.join("::") == target_name)
}

pub fn resolve_using_enum_declaration_owner(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
) -> LexicalTypeResolution {
    let Some(type_node) = using_enum_declaration_type_node(node) else {
        return LexicalTypeResolution::Missing;
    };
    let mut components = Vec::new();
    if append_cpp_name_components(type_node, source, &mut components).is_none()
        || components.is_empty()
    {
        return LexicalTypeResolution::Missing;
    }
    resolve_type_components_lexically_at(
        type_node,
        &components,
        is_globally_qualified_cpp_name(type_node),
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
    )
}

pub fn resolve_ordinary_using_declaration_owner(
    node: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    source: &str,
) -> LexicalTypeResolution {
    let Some(type_node) = ordinary_using_declaration_type_node(node) else {
        return LexicalTypeResolution::Missing;
    };
    let mut components = Vec::new();
    if append_cpp_name_components(type_node, source, &mut components).is_none()
        || components.len() < 2
    {
        return LexicalTypeResolution::Missing;
    }
    let lexical_scope =
        match enclosing_lexical_scope_components(type_node, analyzer, visibility, file, source) {
            LexicalScopeResolution::Resolved(scope) => scope,
            LexicalScopeResolution::Ambiguous => return LexicalTypeResolution::Ambiguous,
            LexicalScopeResolution::Missing => return LexicalTypeResolution::Missing,
        };
    visibility.resolve_type_components_lexically(
        analyzer,
        file,
        &components,
        is_globally_qualified_cpp_name(type_node),
        &lexical_scope,
    )
}

pub fn using_enum_declaration_type_node(node: Node<'_>) -> Option<Node<'_>> {
    (node.kind() == "using_declaration"
        && (0..node.child_count()).any(|index| {
            node.child(index)
                .is_some_and(|child| child.kind() == "enum")
        }))
    .then(|| node.named_child(0))
    .flatten()
}

pub fn ordinary_using_declaration_type_node(node: Node<'_>) -> Option<Node<'_>> {
    (node.kind() == "using_declaration"
        && using_enum_declaration_type_node(node).is_none()
        && using_namespace_directive_name_node(node).is_none())
    .then(|| node.named_child(0))
    .flatten()
}

/// Tree-sitter can recover `using ::absl::cord_internal::CordRep;` after an
/// undefined namespace-sentinel macro as a declaration whose type is the
/// all-caps sentinel and whose qualified declarator starts with a pseudo
/// `using` scope. The real imported name remains a structured qualified
/// identifier under that declarator. Recover only this exact CST envelope so
/// ordinary macro-decorated variables are not treated as imports.
fn recovered_macro_using_declaration_type_node<'tree>(
    node: Node<'tree>,
    source: &str,
) -> Option<(Node<'tree>, bool)> {
    if node.kind() != "declaration" {
        return None;
    }
    let macro_type = node.child_by_field_name("type")?;
    if macro_type.kind() != "type_identifier"
        || !cpp_export_macro_token(node_text(macro_type, source))
    {
        return None;
    }
    let declarator = node.child_by_field_name("declarator")?;
    if declarator.kind() != "qualified_identifier" {
        return None;
    }
    let scope = declarator.child_by_field_name("scope")?;
    if scope.kind() != "namespace_identifier" || node_text(scope, source) != "using" {
        return None;
    }
    let target = declarator.child_by_field_name("name")?;
    let mut components = Vec::new();
    append_cpp_name_components(target, source, &mut components)?;
    (components.len() >= 2).then_some((target, is_globally_qualified_cpp_name(target)))
}

fn using_namespace_directive_name_node(node: Node<'_>) -> Option<Node<'_>> {
    let is_directive = node.kind() == "using_directive"
        || (node.kind() == "using_declaration"
            && (0..node.child_count()).any(|index| {
                node.child(index)
                    .is_some_and(|child| child.kind() == "namespace")
            }));
    if !is_directive {
        return None;
    }
    node.child_by_field_name("name")
        .or_else(|| node.named_child(node.named_child_count().checked_sub(1)?))
}

fn using_named_scope(node: Node<'_>, source: &str) -> Option<Vec<String>> {
    let mut current = node.parent();
    while let Some(parent) = current {
        if matches!(
            parent.kind(),
            "compound_statement"
                | "function_definition"
                | "lambda_expression"
                | "for_statement"
                | "while_statement"
                | "if_statement"
                | "class_specifier"
                | "struct_specifier"
                | "union_specifier"
        ) {
            return None;
        }
        current = parent.parent();
    }
    Some(enclosing_namespace_components(node, source))
}

fn ordinary_using_scope(node: Node<'_>) -> Option<(usize, usize, usize, bool)> {
    let mut current = node.parent();
    while let Some(scope) = current {
        if matches!(
            scope.kind(),
            "compound_statement"
                | "declaration_list"
                | "field_declaration_list"
                | "translation_unit"
        ) {
            let mut depth = 0;
            let mut ancestor = scope.parent();
            while let Some(parent) = ancestor {
                depth += 1;
                ancestor = parent.parent();
            }
            return Some((
                scope.start_byte(),
                scope.end_byte(),
                depth,
                scope.kind() == "compound_statement",
            ));
        }
        current = scope.parent();
    }
    None
}

/// Build the per-file structured using index for `file`.
///
/// The result is a pure function of the file's parsed content, which is what
/// lets `CppSource::source_using_index` memoize it on the analyzer (#1927):
/// a `VisibilityIndex` is rebuilt per usage query, and rebuilding this index
/// per query re-walked a 9.5 MB amalgamation's AST for every candidate.
pub fn build_source_using_index(
    cpp: &dyn CppSource,
    token: QueryToken<'_>,
    file: &ProjectFile,
) -> SourceUsingIndex {
    let Some(prepared) = cpp.prepared_syntax(token, file) else {
        return SourceUsingIndex::default();
    };
    collect_source_using_index(cpp, file, prepared.tree().root_node(), prepared.source())
}

fn collect_source_using_index(
    cpp: &dyn CppSource,
    source_file: &ProjectFile,
    root: Node<'_>,
    source: &str,
) -> SourceUsingIndex {
    #[cfg(not(any(test, feature = "test-support")))]
    let _ = cpp;
    let mut index = SourceUsingIndex::default();
    let orphaned_namespaces = collect_orphaned_namespace_envelopes(root, source);
    let mut stack = vec![root];
    while let Some(node) = stack.pop() {
        let target = match node.kind() {
            "using_directive" | "using_declaration" => {
                if let Some(namespace_node) = using_namespace_directive_name_node(node) {
                    let mut namespace_components = Vec::new();
                    append_cpp_name_components(namespace_node, source, &mut namespace_components)
                        .map(|_| EffectiveUsingTarget::Namespace {
                            namespace_components,
                            global: is_globally_qualified_cpp_name(namespace_node),
                        })
                } else if let Some(type_node) = ordinary_using_declaration_type_node(node) {
                    let mut target_components = Vec::new();
                    (append_cpp_name_components(type_node, source, &mut target_components)
                        .is_some()
                        && target_components.len() >= 2)
                        .then(|| EffectiveUsingTarget::Ordinary {
                            name: target_components
                                .last()
                                .expect("ordinary using has a terminal component")
                                .clone(),
                            target_components,
                            global: is_globally_qualified_cpp_name(type_node),
                        })
                } else {
                    None
                }
            }
            "declaration" => recovered_macro_using_declaration_type_node(node, source).and_then(
                |(type_node, global)| {
                    let mut target_components = Vec::new();
                    (append_cpp_name_components(type_node, source, &mut target_components)
                        .is_some()
                        && target_components.len() >= 2)
                        .then(|| EffectiveUsingTarget::Ordinary {
                            name: target_components
                                .last()
                                .expect("recovered ordinary using has a terminal component")
                                .clone(),
                            target_components,
                            global,
                        })
                },
            ),
            _ => None,
        };
        if let Some(target) = target {
            // Guard ancestry is one of the most expensive tree-sitter operations: Node::parent
            // searches from the root. The project index visits every AST node, but only these
            // structured using declarations need a guard environment. Keep the cheap target
            // classification ahead of both ancestor walks so non-using nodes remain a one-pass
            // walk and the total cost is O(nodes + using declarations * ancestor depth).
            #[cfg(any(test, feature = "test-support"))]
            cpp.record_using_guard_context_inspection_for_test();
            let Some(required_guards) = binding_site_guards(node, source) else {
                let mut cursor = node.walk();
                stack.extend(node.children(&mut cursor));
                continue;
            };
            if let Some((scope_start, scope_end, scope_depth, block_scope)) =
                ordinary_using_scope(node)
            {
                let declaration_namespace = enclosing_namespace_components(node, source);
                let declaration_namespace = if declaration_namespace.is_empty() {
                    recovered_orphaned_namespace_components(node, source, &orphaned_namespaces)
                        .unwrap_or(declaration_namespace)
                } else {
                    declaration_namespace
                };
                let namespace_scope = using_named_scope(node, source);
                let lexical_depth = declaration_namespace.len();
                let binding = OrdinaryTypeImport {
                    target,
                    source: source_file.clone(),
                    declaration_byte: node.end_byte(),
                    scope_start,
                    scope_end,
                    scope_depth,
                    block_scope,
                    lexical_depth,
                    declaration_namespace,
                    namespace_scope,
                    resolved_target_components: None,
                    required_guards,
                };
                match &binding.target {
                    EffectiveUsingTarget::Ordinary { name, .. } => index
                        .ordinary_by_name
                        .entry(name.clone())
                        .or_default()
                        .push(binding),
                    EffectiveUsingTarget::Namespace { .. } => index.directives.push(binding),
                }
            }
        }
        let mut cursor = node.walk();
        stack.extend(node.children(&mut cursor));
    }
    index
}

struct OrphanedNamespaceEnvelope {
    body_end: usize,
    components: Vec<String>,
    class_names: HashSet<String>,
}

/// Tree-sitter can terminate a namespace body at an object-like namespace
/// macro (for example `ABSL_NAMESPACE_BEGIN`), then parse the following
/// out-of-line definitions at translation-unit scope. A block-scoped using
/// declaration in one of those definitions still belongs to the namespace
/// selected by the malformed namespace envelope. Keep the envelope scan
/// source-local and reuse its structural ownership evidence for each using.
fn collect_orphaned_namespace_envelopes(
    root: Node<'_>,
    source: &str,
) -> Vec<OrphanedNamespaceEnvelope> {
    let mut envelopes = Vec::new();
    let mut stack = vec![root];
    while let Some(current) = stack.pop() {
        if current.kind() == "namespace_definition"
            && let Some(body) = current.child_by_field_name("body")
            && current.end_byte() == body.end_byte()
            && let Some(name) = current.child_by_field_name("name")
        {
            let mut components = enclosing_namespace_components(current, source);
            if append_cpp_name_components(name, source, &mut components).is_some()
                && !components.is_empty()
            {
                let mut class_names = HashSet::default();
                let mut body_stack = vec![body];
                while let Some(node) = body_stack.pop() {
                    if let Some(name) = orphaned_class_definition_name(node, source) {
                        class_names.insert(name);
                    }
                    let mut cursor = node.walk();
                    if node.kind() == "ERROR" {
                        body_stack.extend(node.children(&mut cursor));
                    } else {
                        body_stack.extend(node.named_children(&mut cursor));
                    }
                }
                envelopes.push(OrphanedNamespaceEnvelope {
                    body_end: body.end_byte(),
                    components,
                    class_names,
                });
            }
        }
        let mut cursor = current.walk();
        stack.extend(current.named_children(&mut cursor));
    }
    envelopes
}

fn orphaned_class_definition_name(node: Node<'_>, source: &str) -> Option<String> {
    if matches!(
        node.kind(),
        "class_specifier" | "struct_specifier" | "union_specifier"
    ) {
        let body = node.child_by_field_name("body")?;
        let name = node.child_by_field_name("name")?;
        return (!name.is_missing() && !body.is_missing())
            .then(|| node_text(name, source).to_string());
    }
    if node.kind() != "ERROR" {
        return None;
    }

    // When an object-like namespace macro is parsed as a function definition,
    // tree-sitter can place the entire class declaration inside an ERROR node
    // and leave the `class`/`struct` keyword as an anonymous child. Keep the
    // fallback structural: accept only a named class-like keyword followed by
    // a real body, never an arbitrary identifier mentioned in the envelope.
    for index in 0..node.child_count() {
        let Some(keyword) = node.child(index) else {
            continue;
        };
        if !matches!(keyword.kind(), "class" | "struct" | "union") {
            continue;
        }
        let mut name = None;
        for next_index in (index + 1)..node.child_count() {
            let Some(next) = node.child(next_index) else {
                continue;
            };
            if next.kind() == ";" {
                break;
            }
            if next.kind() == "{" {
                return name
                    .filter(|name_node: &Node<'_>| !name_node.is_missing())
                    .map(|name_node| node_text(name_node, source).to_string());
            }
            if name.is_none() && matches!(next.kind(), "identifier" | "type_identifier") {
                name = Some(next);
            }
        }
    }
    None
}

fn recovered_orphaned_namespace_components(
    node: Node<'_>,
    source: &str,
    envelopes: &[OrphanedNamespaceEnvelope],
) -> Option<Vec<String>> {
    let owner_name = orphaned_using_owner_name(node, source)?;
    envelopes
        .iter()
        .filter(|envelope| {
            envelope.body_end <= node.start_byte() && envelope.class_names.contains(&owner_name)
        })
        .max_by_key(|envelope| envelope.body_end)
        .map(|envelope| envelope.components.clone())
}

fn orphaned_using_owner_name(node: Node<'_>, source: &str) -> Option<String> {
    let function = std::iter::successors(node.parent(), |current| current.parent())
        .find(|current| current.kind() == "function_definition")?;
    let owner = function_definition_owner_lookup_node(function)?;
    let scope = owner.child_by_field_name("scope")?;
    let mut components = Vec::new();
    append_cpp_name_components(scope, source, &mut components)?;
    // A qualified out-of-line member definition already carries its namespace
    // in the declarator scope (for example `foo::Widget::run`). The recovery
    // path is only for parser-orphaned top-level members whose owner scope
    // collapsed to the bare class name; requiring that shape prevents an
    // earlier, unrelated namespace/class from leaking into a global function's
    // using-directive lookup.
    if components.len() != 1 {
        return None;
    }
    components.pop()
}

fn build_project_using_index(visibility: &VisibilityIndex<'_>) -> ProjectUsingIndex {
    let started = Instant::now();
    let report_stats = std::env::var_os("BIFROST_CPP_VISIBILITY_STATS").is_some();
    let source_files = visibility.all_visible_source_files();
    if report_stats {
        eprintln!(
            "BIFROST_CPP_USING_INDEX_STATS status=started source_files={}",
            source_files.len()
        );
    }
    let mut project = ProjectUsingIndex::default();
    let mut ordinary_bindings = 0usize;
    for source_file in &source_files {
        // The per-file index is memoized on the analyzer, so assembling the
        // project index for a fresh `VisibilityIndex` copies bindings instead
        // of re-walking each file's AST (#1927).
        let source_index = visibility
            .cpp()
            .source_using_index(visibility.token(), source_file);
        for (name, bindings) in &source_index.ordinary_by_name {
            ordinary_bindings += bindings.len();
            project
                .ordinary_by_name
                .entry(name.clone())
                .or_default()
                .extend(bindings.iter().cloned());
        }
        project
            .directives
            .extend(source_index.directives.iter().cloned());
    }
    if report_stats {
        eprintln!(
            "BIFROST_CPP_USING_INDEX_STATS status=completed source_files={} ordinary_names={} ordinary_bindings={} directives={} elapsed_ms={}",
            source_files.len(),
            project.ordinary_by_name.len(),
            ordinary_bindings,
            project.directives.len(),
            started.elapsed().as_millis(),
        );
    }
    project
}

fn project_using_index<'a>(visibility: &'a VisibilityIndex<'_>) -> &'a ProjectUsingIndex {
    visibility.project_using_index(|| build_project_using_index(visibility))
}

/// Build the immutable project-wide using index before a parallel file scan.
///
/// Keeping the `OnceLock` publication here avoids making every scanner carry
/// an eager index, while callers that are about to fan out can prevent one
/// worker from doing the whole build as its peers wait on the lock.
pub fn prewarm_project_using_index(visibility: &VisibilityIndex<'_>) {
    let _ = project_using_index(visibility);
}

fn effective_using_target_tiers(binding: &OrdinaryTypeImport) -> Vec<Vec<String>> {
    let (components, global) = match &binding.target {
        EffectiveUsingTarget::Ordinary {
            target_components,
            global,
            ..
        } => (target_components, *global),
        EffectiveUsingTarget::Namespace {
            namespace_components,
            global,
        } => (namespace_components, *global),
    };
    lexical_component_tiers(components, global, &binding.declaration_namespace).collect()
}

fn using_binding_target_components_for_name(
    binding: &OrdinaryTypeImport,
    project: &ProjectUsingIndex,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    name: &str,
) -> Option<Vec<String>> {
    // Built once per call rather than per candidate: the filter runs over every
    // visible identifier of `name`, and the source is the same object each time.
    let cpp_source = CppGraphSource::from_source(visibility.cpp(), visibility.token());
    let visible_candidates = visibility
        .visible_identifier_candidates(file, name)
        .filter(|candidate| {
            candidate.is_class()
                || declared_type_alias(&cpp_source, candidate)
                || (candidate.is_function() && type_owner_of(&cpp_source, candidate).is_none())
        })
        .collect::<Vec<_>>();
    if visible_candidates.is_empty() {
        return None;
    }
    match &binding.target {
        EffectiveUsingTarget::Ordinary {
            name: imported_name,
            ..
        } if imported_name == name => {
            effective_using_target_tiers(binding)
                .into_iter()
                .find(|qualified| {
                    let qualified_name = qualified.join("::");
                    visible_candidates
                        .iter()
                        .any(|candidate| cpp_name_for(candidate) == qualified_name)
                })
        }
        EffectiveUsingTarget::Namespace { .. } => {
            visibility.note_using_namespace_lookup_for_test();
            let target_tiers = effective_using_target_tiers(binding);
            let resolved = target_tiers
                .iter()
                .find(|namespace_components| {
                    let namespace = namespace_components.join("::");
                    visible_candidates.iter().any(|candidate| {
                        visibility.note_using_name_candidate_inspection_for_test();
                        cpp_namespace_for(candidate).is_some_and(|candidate_namespace| {
                            candidate_namespace == namespace
                                || candidate_namespace.starts_with(&format!("{namespace}::"))
                        })
                    }) || project.directives.iter().any(|candidate| {
                        candidate.namespace_scope.as_deref()
                            == Some(namespace_components.as_slice())
                    }) || project
                        .ordinary_by_name
                        .values()
                        .flatten()
                        .any(|candidate| {
                            candidate.namespace_scope.as_deref()
                                == Some(namespace_components.as_slice())
                        })
                })
                .cloned();
            resolved.or_else(|| {
                // A sole lexical namespace tier is itself enough to retain the
                // directive. Candidate identity is resolved later, where
                // target guidance and macro-expanded owner names are available.
                // Dropping it here makes an unrelated same-terminal type hide
                // the actual namespace member before lookup can compare owners.
                (target_tiers.len() == 1)
                    .then(|| target_tiers.into_iter().next())
                    .flatten()
            })
        }
        EffectiveUsingTarget::Ordinary { .. } => None,
    }
}

fn include_node_for_activation(root: Node<'_>, activation: usize) -> Option<Node<'_>> {
    let start = activation.checked_sub(1)?;
    let mut node = root.descendant_for_byte_range(start, activation)?;
    while node.kind() != "preproc_include" {
        node = node.parent()?;
    }
    Some(node)
}

fn project_using_bindings(
    binding: OrdinaryTypeImport,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    root: Node<'_>,
    source: &str,
) -> Vec<OrdinaryTypeImport> {
    if binding.source == *file {
        return vec![binding];
    }
    if !visibility.source_is_visible(file, &binding.source) || binding.namespace_scope.is_none() {
        return Vec::new();
    }
    visibility.note_using_donor_activation_for_test();
    let Some(prepared) = visibility.cpp().prepared_syntax(visibility.token(), file) else {
        return Vec::new();
    };
    let projections = visibility
        .include_activation_for_source(visibility.cpp(), file, prepared.as_ref(), &binding.source)
        .map_or_else(
            || {
                visibility.conditional_include_projections_for_source(
                    file,
                    prepared.as_ref(),
                    &binding.source,
                )
            },
            |activation_byte| {
                Arc::from([ConditionalIncludeProjection {
                    activation_byte,
                    required_guards: HashSet::default(),
                    partial_guards: HashSet::default(),
                }])
            },
        );
    projections
        .iter()
        .cloned()
        .filter_map(|projection| {
            let required_guards =
                merge_preprocessor_guards(&binding.required_guards, &projection.required_guards)?;
            let mut projected = binding.clone();
            projected.required_guards = required_guards;
            project_using_binding_at_activation(projected, projection.activation_byte, root, source)
        })
        .collect()
}

fn project_using_binding_at_activation(
    mut binding: OrdinaryTypeImport,
    activation: usize,
    root: Node<'_>,
    source: &str,
) -> Option<OrdinaryTypeImport> {
    let include = include_node_for_activation(root, activation)?;
    let include_namespace = enclosing_namespace_components(include, source);
    let mut declaration_namespace = include_namespace.clone();
    declaration_namespace.extend(binding.declaration_namespace);
    binding.declaration_namespace = declaration_namespace;
    binding.declaration_byte = activation;
    if let Some(prefix) = using_named_scope(include, source) {
        let mut projected = prefix;
        projected.extend(binding.namespace_scope.take().unwrap_or_default());
        binding.scope_depth = projected.len();
        binding.block_scope = false;
        binding.lexical_depth = projected.len();
        binding.namespace_scope = Some(projected);
        binding.scope_start = 0;
        binding.scope_end = usize::MAX;
        Some(binding)
    } else if let Some((start, end, depth, block_scope)) = ordinary_using_scope(include) {
        binding.namespace_scope = None;
        binding.scope_start = start;
        binding.scope_end = end;
        binding.scope_depth = depth;
        binding.block_scope = block_scope;
        binding.lexical_depth = include_namespace.len();
        Some(binding)
    } else {
        None
    }
}

/// `node` may be any node of `file`'s tree; the projection reaches the tree
/// root itself when it needs one. `Node::parent` re-descends from the root on
/// every call (tree-sitter 0.24+), so climbing to the root eagerly at each
/// call site cost a near-full-AST scan per reference on a large flat file
/// (#1927); a name with no candidate bindings never pays for it.
pub fn effective_using_bindings_for_name(
    visibility: &VisibilityIndex<'_>,
    imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    node: Node<'_>,
    source: &str,
    name: &str,
) -> Arc<[OrdinaryTypeImport]> {
    imports
        .projection_cell(name)
        .get_or_init(|| {
            let project = project_using_index(visibility);
            let name_bindings = project.ordinary_by_name.get(name);
            if name_bindings.is_none() && project.directives.is_empty() {
                return Arc::from(Vec::new());
            }
            let root = root_node(node);
            let mut projected = Vec::new();
            for binding in name_bindings
                .into_iter()
                .flatten()
                .chain(project.directives.iter())
            {
                if !visibility.source_is_visible(file, &binding.source) {
                    continue;
                }
                let target_components = using_binding_target_components_for_name(
                    binding, project, visibility, file, name,
                )
                .or_else(|| match &binding.target {
                    EffectiveUsingTarget::Ordinary {
                        name: imported_name,
                        target_components,
                        ..
                    } if imported_name == name => Some(target_components.clone()),
                    EffectiveUsingTarget::Ordinary { .. }
                    | EffectiveUsingTarget::Namespace { .. } => None,
                });
                let Some(target_components) = target_components else {
                    continue;
                };
                let mut binding = binding.clone();
                binding.resolved_target_components = Some(target_components);
                projected.extend(project_using_bindings(
                    binding, visibility, file, root, source,
                ));
            }
            Arc::from(projected)
        })
        .clone()
}

pub fn initialized_ordinary_type_imports(
    root: Node<'_>,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    source: &str,
) -> OrdinaryTypeImportCell {
    let cell = visibility.ordinary_type_import_cell(file);
    let _ = (root, analyzer, source);
    cell
}

/// `reference_guards` is the reference node's guard environment, computed once
/// by the caller and shared across every binding: recomputing it per binding
/// repeated a full ancestor climb whose every `Node::parent` step re-descends
/// from the root (#1927).
fn effective_using_binding_active(
    binding: &OrdinaryTypeImport,
    node: Node<'_>,
    lexical_scope: &[String],
    reference_guards: Option<&HashSet<PreprocessorGuard>>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
) -> bool {
    effective_using_binding_guards_active(
        binding,
        node.start_byte(),
        reference_guards,
        visibility,
        file,
    ) && binding.namespace_scope.as_ref().map_or_else(
        || binding.scope_start <= node.start_byte() && node.end_byte() <= binding.scope_end,
        |namespace| lexical_scope.starts_with(namespace),
    )
}

fn effective_using_binding_guards_active(
    binding: &OrdinaryTypeImport,
    reference_byte: usize,
    reference_guards: Option<&HashSet<PreprocessorGuard>>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
) -> bool {
    binding.declaration_byte <= reference_byte
        && reference_guards.is_some_and(|active| binding.required_guards.is_subset(active))
        && effective_using_binding_guards_stable_between(binding, reference_byte, visibility, file)
}

fn effective_using_binding_guards_compatible(
    binding: &OrdinaryTypeImport,
    reference_byte: usize,
    reference_guards: Option<&HashSet<PreprocessorGuard>>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
) -> bool {
    binding.source != *file
        && !binding.required_guards.is_empty()
        && binding.declaration_byte <= reference_byte
        && reference_guards.is_some_and(|active| {
            !binding.required_guards.is_subset(active)
                && merge_preprocessor_guards(&binding.required_guards, active).is_some()
        })
        && effective_using_binding_guards_stable_between(binding, reference_byte, visibility, file)
}

fn effective_using_binding_guards_stable_between(
    binding: &OrdinaryTypeImport,
    reference_byte: usize,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
) -> bool {
    visibility.preprocessor_guards_stable_between(
        file,
        binding.declaration_byte,
        reference_byte,
        &binding.required_guards,
    )
}

#[allow(clippy::too_many_arguments)]
fn binding_type_candidates(
    binding: &OrdinaryTypeImport,
    active_bindings: &[&OrdinaryTypeImport],
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    name: &str,
    direct_target: Option<&CodeUnit>,
    reference_byte: usize,
) -> Vec<(CodeUnit, Vec<String>)> {
    ordinary_binding_lookup_targets(binding, active_bindings, name)
        .into_iter()
        .flat_map(|target| {
            let mut candidates = visibility
                .visible_identifier_candidates(file, name)
                .filter(|candidate| {
                    (candidate.is_class() || declared_type_alias(analyzer, candidate))
                        && type_candidate_matches_lookup_components(
                            analyzer,
                            visibility,
                            file,
                            candidate,
                            reference_byte,
                            &target,
                        )
                })
                .cloned()
                .collect::<Vec<_>>();
            if candidates.is_empty()
                && matches!(binding.target, EffectiveUsingTarget::Namespace { .. })
                && let Some(target_unit) = direct_target
            {
                let expanded_target_name = macro_expanded_cpp_name_components(
                    visibility,
                    file,
                    target_unit,
                    reference_byte,
                );
                if (target_unit.is_class() || declared_type_alias(analyzer, target_unit))
                    && expanded_target_name == target
                    && visibility.external_type_candidate_visible_at(
                        file,
                        target_unit,
                        reference_byte,
                    )
                {
                    candidates.push(target_unit.clone());
                }
            }
            if candidates.is_empty()
                && matches!(binding.target, EffectiveUsingTarget::Namespace { .. })
                && let Some(target_unit) = direct_target
            {
                let visible_types = visibility
                    .visible_identifier_candidates(file, name)
                    .filter(|candidate| {
                        candidate.is_class() || declared_type_alias(analyzer, candidate)
                    })
                    .collect::<Vec<_>>();
                let uniquely_names_target = !visible_types.is_empty()
                    && visible_types
                        .iter()
                        .all(|candidate| same_visible_symbol(candidate, target_unit));
                if uniquely_names_target {
                    candidates.extend(visible_types.into_iter().cloned());
                }
            }
            candidates
                .into_iter()
                .map(move |candidate| (candidate, target.clone()))
        })
        .collect()
}

fn macro_expanded_cpp_name_components(
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    unit: &CodeUnit,
    reference_byte: usize,
) -> Vec<String> {
    brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
        brokk_bifrost_core::analyzer::Language::Cpp,
        &cpp_name_for(unit),
    )
    .into_iter()
    .flat_map(|component| {
        macro_expanded_cpp_name_component(visibility, file, component, reference_byte)
    })
    .collect()
}

fn macro_expanded_cpp_name_component(
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    component: String,
    reference_byte: usize,
) -> Vec<String> {
    let Some(replacement) =
        visibility.object_macro_replacement_at(file, &component, reference_byte)
    else {
        return vec![component];
    };
    let expanded = brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
        brokk_bifrost_core::analyzer::Language::Cpp,
        &replacement,
    );
    if expanded.is_empty() {
        vec![component]
    } else {
        expanded
    }
}

/// Whether a visible type has the requested qualified spelling.
///
/// Members of an inline namespace are also members of its enclosing namespace,
/// so an ordinary using-declaration may legally omit the inline component. The
/// stored FQ name retains that component to keep declarations distinct. Recover
/// the omitted spellings from the candidate declaration's namespace ancestors,
/// using CST `inline` tokens rather than guessing from names.
fn type_candidate_matches_lookup_components(
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    candidate: &CodeUnit,
    reference_byte: usize,
    target: &[String],
) -> bool {
    let expanded = macro_expanded_cpp_name_components(visibility, file, candidate, reference_byte);
    if expanded == target {
        return true;
    }
    let Some(cpp) = analyzer.cpp else {
        return false;
    };
    let Some(prepared) = cpp.prepared_syntax(visibility.token(), candidate.source()) else {
        return false;
    };
    let root = prepared.tree().root_node();
    for range in analyzer.ranges(candidate) {
        let Some(mut current) = root.descendant_for_byte_range(range.start_byte, range.end_byte)
        else {
            continue;
        };
        let mut namespaces = Vec::<(Vec<String>, bool)>::new();
        loop {
            if current.kind() == "namespace_definition"
                && let Some(name) = current.child_by_field_name("name")
            {
                let mut components = Vec::new();
                if append_cpp_name_components(name, prepared.source(), &mut components).is_some()
                    && !components.is_empty()
                {
                    let inline = (0..current.child_count())
                        .filter_map(|index| current.child(index))
                        .any(|child| !child.is_named() && child.kind() == "inline");
                    namespaces.push((components, inline));
                }
            }
            let Some(parent) = current.parent() else {
                break;
            };
            current = parent;
        }
        namespaces.reverse();
        let mut namespace_components = Vec::new();
        let mut inline_indexes = HashSet::default();
        for (components, inline) in namespaces {
            for component in components {
                let expanded_component =
                    macro_expanded_cpp_name_component(visibility, file, component, reference_byte);
                if inline {
                    inline_indexes.extend(
                        namespace_components.len()
                            ..namespace_components.len() + expanded_component.len(),
                    );
                }
                namespace_components.extend(expanded_component);
            }
        }
        if inline_indexes.is_empty() || !expanded.starts_with(&namespace_components) {
            continue;
        }
        // Each inline namespace component can be present or elided. Compare
        // those alternatives as a small dynamic program instead of generating
        // every subset of a deeply nested inline-namespace chain.
        let mut reachable = vec![false; target.len() + 1];
        reachable[0] = true;
        for (index, component) in expanded.iter().enumerate() {
            let mut next = vec![false; target.len() + 1];
            for (target_index, reached) in reachable.iter().copied().enumerate() {
                if !reached {
                    continue;
                }
                if inline_indexes.contains(&index) {
                    next[target_index] = true;
                }
                if target
                    .get(target_index)
                    .is_some_and(|target_component| target_component == component)
                {
                    next[target_index + 1] = true;
                }
            }
            reachable = next;
        }
        if reachable[target.len()] {
            return true;
        }
    }
    false
}

#[allow(clippy::too_many_arguments)]
fn resolved_type_import(
    candidates: Vec<(CodeUnit, Vec<String>)>,
    lexical_depth: usize,
    is_direct: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    direct_target: Option<&CodeUnit>,
) -> OrdinaryTypeImportResolution {
    let logical = deduplicate_type_import_candidates(candidates);
    let selected = match logical.as_slice() {
        [] => return OrdinaryTypeImportResolution::Missing,
        [only] => only,
        // Several declarations of one FQN in one file are configuration
        // spellings of one entity, not competing types (#1845): the imported
        // name is unambiguous, only the branch that supplies it depends on the
        // build.
        several => {
            let units = several
                .iter()
                .map(|(unit, _)| unit)
                .collect::<Vec<&CodeUnit>>();
            let Some(spelling) = direct_target.and_then(|target| {
                visibility.same_fqn_type_spelling_for_target(analyzer, file, &units, target)
            }) else {
                return OrdinaryTypeImportResolution::Ambiguous { lexical_depth };
            };
            several
                .iter()
                .find(|(unit, _)| same_symbol(unit, spelling))
                .expect("the selected spelling is one of the imported candidates")
        }
    };
    OrdinaryTypeImportResolution::Resolved {
        target: selected.0.clone(),
        target_components: selected.1.clone(),
        lexical_depth,
        is_direct,
    }
}

#[allow(clippy::too_many_arguments)]
fn ordinary_type_import_resolution(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    lexical_scope: &[String],
    direct_target: Option<&CodeUnit>,
) -> OrdinaryTypeImportResolution {
    if global || components.len() != 1 {
        return OrdinaryTypeImportResolution::Missing;
    }
    let name = &components[0];
    let bindings = effective_using_bindings_for_name(visibility, imports, file, node, source, name);
    // Guard ancestry climbs the whole ancestor chain, and each `Node::parent`
    // step re-descends from the root (#1927). A name with no bindings needs
    // none of it, and one environment serves every binding of the reference.
    if bindings.is_empty() {
        return OrdinaryTypeImportResolution::Missing;
    }
    let reference_guards = preprocessor_guard_environment(node, source);
    let active = bindings
        .iter()
        .filter(|binding| {
            effective_using_binding_active(
                binding,
                node,
                lexical_scope,
                reference_guards.as_ref(),
                visibility,
                file,
            )
        })
        .collect::<Vec<_>>();
    let transitive = bindings
        .iter()
        .filter(|binding| {
            effective_using_binding_guards_active(
                binding,
                node.start_byte(),
                reference_guards.as_ref(),
                visibility,
                file,
            ) && (binding.namespace_scope.is_some()
                || (binding.scope_start <= node.start_byte()
                    && node.end_byte() <= binding.scope_end))
        })
        .collect::<Vec<_>>();
    ordinary_type_import_resolution_for_bindings(
        node,
        name,
        analyzer,
        visibility,
        file,
        lexical_scope,
        direct_target,
        &active,
        &transitive,
    )
}

#[allow(clippy::too_many_arguments)]
fn compatible_foreign_type_import_resolution(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    lexical_scope: &[String],
    direct_target: Option<&CodeUnit>,
) -> OrdinaryTypeImportResolution {
    if global || components.len() != 1 {
        return OrdinaryTypeImportResolution::Missing;
    }
    let name = &components[0];
    let bindings = effective_using_bindings_for_name(visibility, imports, file, node, source, name);
    if bindings.is_empty() {
        return OrdinaryTypeImportResolution::Missing;
    }
    let reference_guards = preprocessor_guard_environment(node, source);
    let compatible = bindings
        .iter()
        .filter(|binding| {
            effective_using_binding_guards_compatible(
                binding,
                node.start_byte(),
                reference_guards.as_ref(),
                visibility,
                file,
            ) && binding.namespace_scope.as_ref().map_or_else(
                || binding.scope_start <= node.start_byte() && node.end_byte() <= binding.scope_end,
                |namespace| lexical_scope.starts_with(namespace),
            )
        })
        .collect::<Vec<_>>();
    let transitive = bindings
        .iter()
        .filter(|binding| {
            effective_using_binding_guards_compatible(
                binding,
                node.start_byte(),
                reference_guards.as_ref(),
                visibility,
                file,
            ) && (binding.namespace_scope.is_some()
                || (binding.scope_start <= node.start_byte()
                    && node.end_byte() <= binding.scope_end))
        })
        .collect::<Vec<_>>();
    ordinary_type_import_resolution_for_bindings(
        node,
        name,
        analyzer,
        visibility,
        file,
        lexical_scope,
        direct_target,
        &compatible,
        &transitive,
    )
}

#[allow(clippy::too_many_arguments)]
fn ordinary_type_import_resolution_for_bindings(
    node: Node<'_>,
    name: &str,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    lexical_scope: &[String],
    direct_target: Option<&CodeUnit>,
    active: &[&OrdinaryTypeImport],
    transitive: &[&OrdinaryTypeImport],
) -> OrdinaryTypeImportResolution {
    let mut concrete_depths = active
        .iter()
        .filter(|binding| binding.namespace_scope.is_none())
        .map(|binding| binding.scope_depth)
        .collect::<Vec<_>>();
    concrete_depths.sort_unstable();
    concrete_depths.dedup();
    for depth in concrete_depths.into_iter().rev() {
        let at_tier = active
            .iter()
            .copied()
            .filter(|binding| binding.namespace_scope.is_none() && binding.scope_depth == depth);
        let direct = at_tier
            .clone()
            .filter(|binding| matches!(binding.target, EffectiveUsingTarget::Ordinary { .. }))
            .flat_map(|binding| {
                binding_type_candidates(
                    binding,
                    transitive,
                    analyzer,
                    visibility,
                    file,
                    name,
                    direct_target,
                    node.start_byte(),
                )
            })
            .collect::<Vec<_>>();
        if !direct.is_empty() {
            return resolved_type_import(
                direct,
                lexical_scope.len(),
                true,
                analyzer,
                visibility,
                file,
                direct_target,
            );
        }
        let directives = at_tier
            .filter(|binding| matches!(binding.target, EffectiveUsingTarget::Namespace { .. }))
            .flat_map(|binding| {
                binding_type_candidates(
                    binding,
                    transitive,
                    analyzer,
                    visibility,
                    file,
                    name,
                    direct_target,
                    node.start_byte(),
                )
            })
            .collect::<Vec<_>>();
        if !directives.is_empty() {
            return resolved_type_import(
                directives,
                lexical_scope.len(),
                false,
                analyzer,
                visibility,
                file,
                direct_target,
            );
        }
    }
    for prefix_len in (0..=lexical_scope.len()).rev() {
        let tier = &lexical_scope[..prefix_len];
        let at_tier = active
            .iter()
            .copied()
            .filter(|binding| binding.namespace_scope.as_deref() == Some(tier));
        let direct = at_tier
            .clone()
            .filter(|binding| matches!(binding.target, EffectiveUsingTarget::Ordinary { .. }))
            .flat_map(|binding| {
                binding_type_candidates(
                    binding,
                    transitive,
                    analyzer,
                    visibility,
                    file,
                    name,
                    direct_target,
                    node.start_byte(),
                )
            })
            .collect::<Vec<_>>();
        if !direct.is_empty() {
            return resolved_type_import(
                direct,
                prefix_len,
                true,
                analyzer,
                visibility,
                file,
                direct_target,
            );
        }
        let directives = at_tier
            .filter(|binding| matches!(binding.target, EffectiveUsingTarget::Namespace { .. }))
            .flat_map(|binding| {
                binding_type_candidates(
                    binding,
                    transitive,
                    analyzer,
                    visibility,
                    file,
                    name,
                    direct_target,
                    node.start_byte(),
                )
            })
            .collect::<Vec<_>>();
        if !directives.is_empty() {
            return resolved_type_import(
                directives,
                prefix_len,
                false,
                analyzer,
                visibility,
                file,
                direct_target,
            );
        }
    }
    OrdinaryTypeImportResolution::Missing
}

#[allow(clippy::too_many_arguments)]
pub fn resolve_type_components_lexically_at(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
) -> LexicalTypeResolution {
    resolve_type_components_lexically_at_inner(
        node,
        components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        None,
        false,
        false,
        false,
        None,
    )
}

/// Resolve a type at its lexical reference site while retaining the identity
/// of an alias that C++ lookup selects.
///
/// Forward navigation uses the selected spelling as its destination, whereas
/// graph attribution normally canonicalizes an alias to its target. Both
/// surfaces must still apply the same ordinary using-declarations, declaration
/// order, guard state, and lexical-depth precedence.
#[allow(clippy::too_many_arguments)]
pub fn resolve_type_components_lexically_at_preserving_alias(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    source: &str,
) -> LexicalTypeResolution {
    let ordinary_type_imports =
        initialized_ordinary_type_imports(root_node(node), analyzer, visibility, file, source);
    resolve_type_components_lexically_at_inner(
        node,
        components,
        global,
        analyzer,
        visibility,
        &ordinary_type_imports,
        file,
        source,
        None,
        false,
        true,
        true,
        None,
    )
}

#[allow(clippy::too_many_arguments)]
fn resolve_type_components_lexically_at_preserving_alias_with_scope_cache(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    scope_cache: Option<&LexicalScopeCache>,
) -> LexicalTypeResolution {
    resolve_type_components_lexically_at_inner(
        node,
        components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        None,
        false,
        true,
        false,
        scope_cache,
    )
}

#[allow(clippy::too_many_arguments)]
fn resolve_type_components_lexically_at_for_target_with_scope_cache(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    target: &CodeUnit,
    apply_structured_prefilter: bool,
    scope_cache: Option<&LexicalScopeCache>,
) -> LexicalTypeResolution {
    resolve_type_components_lexically_at_inner(
        node,
        components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        Some(target),
        apply_structured_prefilter,
        false,
        false,
        scope_cache,
    )
}

#[allow(clippy::too_many_arguments)]
fn resolve_type_components_lexically_at_preserving_alias_with_recovered_scope(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    recovered_scope: &[String],
) -> LexicalTypeResolution {
    resolve_type_components_in_authoritative_scope(
        node,
        components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        None,
        false,
        true,
        false,
        recovered_scope.to_vec(),
    )
}

#[allow(clippy::too_many_arguments)]
fn resolve_type_components_lexically_at_for_target_with_recovered_scope(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    target: &CodeUnit,
    apply_structured_prefilter: bool,
    recovered_scope: &[String],
) -> LexicalTypeResolution {
    resolve_type_components_in_authoritative_scope(
        node,
        components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        Some(target),
        apply_structured_prefilter,
        false,
        false,
        recovered_scope.to_vec(),
    )
}

#[allow(clippy::too_many_arguments)]
fn resolve_type_components_lexically_at_inner(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    direct_target: Option<&CodeUnit>,
    apply_structured_prefilter: bool,
    preserve_alias: bool,
    allow_compatible_foreign_import: bool,
    scope_cache: Option<&LexicalScopeCache>,
) -> LexicalTypeResolution {
    let report_stats = std::env::var_os("BIFROST_CPP_VISIBILITY_STATS").is_some();
    let lexical_scope_started = Instant::now();
    if report_stats {
        eprintln!("BIFROST_CPP_TYPE_LEXICAL_PHASE phase=lexical_scope status=started");
    }
    let lexical_scope = if global {
        Vec::new()
    } else {
        match cached_enclosing_lexical_scope_components_with_unresolved_owner(
            node,
            analyzer,
            visibility,
            file,
            source,
            true,
            recovered_macro_decorated_declarator_type(node)
                == Some(RecoveredDeclaratorTypeContext::FunctionDefinition),
            scope_cache,
        ) {
            LexicalScopeResolution::Resolved(scope) => scope,
            LexicalScopeResolution::Ambiguous => {
                if report_stats {
                    eprintln!(
                        "BIFROST_CPP_TYPE_LEXICAL_PHASE phase=lexical_scope status=completed outcome=ambiguous elapsed_ms={}",
                        lexical_scope_started.elapsed().as_millis(),
                    );
                }
                return LexicalTypeResolution::Ambiguous;
            }
            LexicalScopeResolution::Missing => {
                if report_stats {
                    eprintln!(
                        "BIFROST_CPP_TYPE_LEXICAL_PHASE phase=lexical_scope status=completed outcome=missing elapsed_ms={}",
                        lexical_scope_started.elapsed().as_millis(),
                    );
                }
                return LexicalTypeResolution::Missing;
            }
        }
    };
    if report_stats {
        eprintln!(
            "BIFROST_CPP_TYPE_LEXICAL_PHASE phase=lexical_scope status=completed components={} elapsed_ms={}",
            lexical_scope.len(),
            lexical_scope_started.elapsed().as_millis(),
        );
    }
    resolve_type_components_lexically_at_scoped(
        node,
        components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        direct_target,
        apply_structured_prefilter,
        preserve_alias,
        allow_compatible_foreign_import,
        lexical_scope,
    )
}

#[allow(clippy::too_many_arguments)]
fn resolve_type_components_lexically_at_scoped(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    direct_target: Option<&CodeUnit>,
    apply_structured_prefilter: bool,
    preserve_alias: bool,
    allow_compatible_foreign_import: bool,
    mut lexical_scope: Vec<String>,
) -> LexicalTypeResolution {
    if !global
        && components.len() == 1
        // The two constant-time conditions run before the ancestor climb: each
        // `Node::parent` step re-descends from the root (#1927).
        && let Some(target) = direct_target
        && lexical_scope
            .last()
            .is_none_or(|last| last != &components[0])
        // A recovered class may contain a real member function nested inside
        // the malformed outer wrapper (for example tinyxml2's macro-prefixed
        // XMLConstHandle). The nearest function_definition is then the member
        // itself, so inspect the complete ancestor chain.
        && has_malformed_wrapper_function_definition_ancestor(node)
        && let Some(indexed_namespace) =
            visibility.target_preserving_reference_namespace(analyzer, file, &components[0], target)
        && (lexical_scope.is_empty() || !lexical_scope.starts_with(&indexed_namespace))
    {
        lexical_scope = indexed_namespace;
    }
    resolve_type_components_in_authoritative_scope(
        node,
        components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        direct_target,
        apply_structured_prefilter,
        preserve_alias,
        allow_compatible_foreign_import,
        lexical_scope,
    )
}

/// Resolve within a scope already proven by recovered syntax.
///
/// Unlike parser-derived scope, this scope must not be replaced with the
/// queried target's namespace: doing so would let target guidance override a
/// nearer declaration represented by the recovered syntax.
///
/// A qualifier that names a namespace alias in effect at `node` is rebound
/// here, once, for forward and inverse lookup alike: the rebound name is
/// looked up from the scope of the alias that supplies it. An ordinary name
/// the written spelling reaches at a deeper lexical tier shadows the alias,
/// and an alias whose target cannot be established resolves to nothing.
#[allow(clippy::too_many_arguments)]
pub(super) fn resolve_type_components_in_authoritative_scope(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    direct_target: Option<&CodeUnit>,
    apply_structured_prefilter: bool,
    preserve_alias: bool,
    allow_compatible_foreign_import: bool,
    lexical_scope: Vec<String>,
) -> LexicalTypeResolution {
    let resolve = |components: &[String], global: bool, lexical_scope: Vec<String>| {
        resolve_unaliased_type_components_in_authoritative_scope(
            node,
            components,
            global,
            analyzer,
            visibility,
            ordinary_type_imports,
            file,
            source,
            direct_target,
            apply_structured_prefilter,
            preserve_alias,
            allow_compatible_foreign_import,
            lexical_scope,
        )
    };
    let binding =
        visibility.bind_namespace_qualifier(file, node, components, global, &lexical_scope);
    let Some(depth) = binding.depth() else {
        return resolve(components, global, lexical_scope);
    };
    if let LexicalTypeResolution::Resolved {
        components: resolved,
        ..
    } = visibility.resolve_type_components_lexically(
        analyzer,
        file,
        components,
        global,
        &lexical_scope,
    ) && resolved.len().saturating_sub(components.len()) > depth
    {
        return resolve(components, global, lexical_scope);
    }
    match binding {
        NamespaceQualifierBinding::Bound {
            components,
            global,
            lexical_scope,
            ..
        } => resolve(&components, global, lexical_scope),
        NamespaceQualifierBinding::Unresolved { .. } => LexicalTypeResolution::Ambiguous,
        NamespaceQualifierBinding::Unaliased => unreachable!("an unaliased binding has no depth"),
    }
}

#[allow(clippy::too_many_arguments)]
fn resolve_unaliased_type_components_in_authoritative_scope(
    node: Node<'_>,
    components: &[String],
    global: bool,
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    ordinary_type_imports: &OrdinaryTypeImportCell,
    file: &ProjectFile,
    source: &str,
    direct_target: Option<&CodeUnit>,
    apply_structured_prefilter: bool,
    preserve_alias: bool,
    allow_compatible_foreign_import: bool,
    lexical_scope: Vec<String>,
) -> LexicalTypeResolution {
    if apply_structured_prefilter
        && direct_target.is_some()
        && !preserve_alias
        && !global
        && components.len() == 1
        && !visibility.coarse_unqualified_type_reference_may_resolve(file, &components[0])
    {
        return LexicalTypeResolution::Missing;
    }
    // A recovered macro-prefixed return type can share its global spelling
    // with aliases from mutually exclusive included headers. C++ lookup uses
    // the declaration physically present earlier in this file; the visibility
    // index deliberately retains every configuration alternative. Restore
    // that precedence only for the exact macro-decorated head (recovered by
    // the older grammar, or its clean macro-declaration reading) and lexical
    // tier.
    if !global
        && components.len() == 1
        && (recovered_macro_decorated_type_node(node).is_some()
            || macro_modifier_decorated_type_node(node))
        && let Some(resolution) = recovered_same_file_type_alias_resolution(
            node,
            components,
            analyzer,
            visibility,
            file,
            direct_target,
            &lexical_scope,
        )
    {
        return resolution;
    }
    if apply_structured_prefilter
        && let Some(target) = direct_target
        && !preserve_alias
        && !visibility.structured_type_reference_may_resolve_to_target(
            analyzer,
            file,
            components,
            global,
            &lexical_scope,
            target,
        )
    {
        return LexicalTypeResolution::Missing;
    }
    let report_stats = std::env::var_os("BIFROST_CPP_VISIBILITY_STATS").is_some();
    let lexical_normal_started = Instant::now();
    if report_stats {
        eprintln!("BIFROST_CPP_TYPE_LEXICAL_PHASE phase=lexical_normal status=started");
    }
    let normal = if preserve_alias {
        visibility.resolve_type_components_lexically_for_forward(
            analyzer,
            file,
            components,
            global,
            &lexical_scope,
        )
    } else {
        direct_target.map_or_else(
            || {
                visibility.resolve_type_components_lexically(
                    analyzer,
                    file,
                    components,
                    global,
                    &lexical_scope,
                )
            },
            |target| {
                visibility.resolve_type_components_lexically_for_target(
                    analyzer,
                    file,
                    components,
                    global,
                    &lexical_scope,
                    target,
                )
            },
        )
    };
    if report_stats {
        eprintln!(
            "BIFROST_CPP_TYPE_LEXICAL_PHASE phase=lexical_normal status=completed elapsed_ms={}",
            lexical_normal_started.elapsed().as_millis(),
        );
    }
    let normal = match normal {
        LexicalTypeResolution::Resolved { ref unit, .. }
            if !visibility
                .external_type_candidate_visible_in_context(analyzer, file, unit, node)
                && !direct_target.is_some_and(|target| {
                    let candidate_refs = visibility
                        .visible_identifier_candidates(file, target.identifier())
                        .collect::<Vec<_>>();
                    visibility.c_tag_declaration_family_matches_target(
                        analyzer,
                        file,
                        &candidate_refs,
                        target,
                    )
                }) =>
        {
            LexicalTypeResolution::Missing
        }
        resolution => resolution,
    };
    let normal_depth = match &normal {
        LexicalTypeResolution::Resolved { components, .. } => {
            Some(components.len().saturating_sub(1))
        }
        LexicalTypeResolution::Ambiguous | LexicalTypeResolution::Missing => None,
    };
    // Ordinary using-declarations participate in unqualified lookup at their
    // lexical scope. They therefore replace the resolver's terminal/global
    // fallback at the same or a shallower depth. A declaration in a more deeply
    // nested named scope is the closer lexical result and remains authoritative.
    // Ambiguous imports fail closed unless such a closer declaration exists.
    let ordinary_import_started = Instant::now();
    if report_stats {
        eprintln!("BIFROST_CPP_TYPE_LEXICAL_PHASE phase=ordinary_import status=started");
    }
    let ordinary_import_resolution = ordinary_type_import_resolution(
        node,
        components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        &lexical_scope,
        direct_target,
    );
    if report_stats {
        eprintln!(
            "BIFROST_CPP_TYPE_LEXICAL_PHASE phase=ordinary_import status=completed elapsed_ms={}",
            ordinary_import_started.elapsed().as_millis(),
        );
    }
    let resolution = match ordinary_import_resolution {
        OrdinaryTypeImportResolution::Missing => normal,
        OrdinaryTypeImportResolution::Resolved {
            lexical_depth,
            is_direct,
            ..
        } if matches!(&normal, LexicalTypeResolution::Ambiguous)
            || normal_depth.is_some_and(|depth| {
                depth > lexical_depth || (!is_direct && depth == lexical_depth)
            }) =>
        {
            normal
        }
        OrdinaryTypeImportResolution::Resolved {
            target,
            target_components,
            ..
        } => visibility.resolve_imported_type_candidate(
            analyzer,
            file,
            &target,
            &target_components,
            direct_target,
            preserve_alias,
        ),
        OrdinaryTypeImportResolution::Ambiguous { lexical_depth }
            if normal_depth.is_some_and(|depth| depth > lexical_depth) =>
        {
            normal
        }
        OrdinaryTypeImportResolution::Ambiguous { .. } => LexicalTypeResolution::Ambiguous,
    };
    if !allow_compatible_foreign_import || !matches!(resolution, LexicalTypeResolution::Missing) {
        return resolution;
    }

    // A foreign header can contribute an exact using binding from a build
    // configuration that is compatible with, but not implied by, the current
    // reference. Forward navigation has no "unproven" result channel, so it
    // may still navigate through one unique structured import after ordinary
    // lookup misses. Inverse attribution keeps using its target-guided path
    // and records the same evidence as unproven (#940).
    match compatible_foreign_type_import_resolution(
        node,
        components,
        global,
        analyzer,
        visibility,
        ordinary_type_imports,
        file,
        source,
        &lexical_scope,
        None,
    ) {
        OrdinaryTypeImportResolution::Missing => resolution,
        OrdinaryTypeImportResolution::Resolved {
            target,
            target_components,
            ..
        } => visibility.resolve_imported_type_candidate(
            analyzer,
            file,
            &target,
            &target_components,
            None,
            true,
        ),
        OrdinaryTypeImportResolution::Ambiguous { .. } => LexicalTypeResolution::Ambiguous,
    }
}

fn recovered_same_file_type_alias_resolution(
    node: Node<'_>,
    components: &[String],
    analyzer: &CppGraphSource<'_>,
    visibility: &VisibilityIndex<'_>,
    file: &ProjectFile,
    direct_target: Option<&CodeUnit>,
    lexical_scope: &[String],
) -> Option<LexicalTypeResolution> {
    debug_assert_eq!(components.len(), 1);
    debug_assert!(
        recovered_macro_decorated_type_node(node).is_some()
            || macro_modifier_decorated_type_node(node)
    );
    let alias_provider = analyzer.type_alias_provider()?;
    for qualified in lexical_component_tiers(components, false, lexical_scope) {
        let candidates = visibility
            .visible_identifier_candidates(file, &components[0])
            .filter(|candidate| {
                candidate.source() == file
                    && canonical_cpp_scope_components(candidate) == qualified
                    && visibility
                        .external_type_candidate_visible_in_context(analyzer, file, candidate, node)
            })
            .collect::<Vec<_>>();
        if candidates.is_empty() {
            continue;
        }
        if candidates
            .iter()
            .any(|candidate| !alias_provider.is_type_alias(candidate))
        {
            return None;
        }
        let unit = if let Some(target) = direct_target {
            visibility.unique_type_candidate_preserving_target(
                analyzer,
                file,
                &candidates,
                target,
            )?
        } else {
            let first = candidates[0];
            if candidates
                .iter()
                .any(|candidate| !same_visible_symbol(candidate, first))
            {
                return None;
            }
            first.clone()
        };
        return Some(LexicalTypeResolution::Resolved {
            unit,
            components: qualified,
            candidates: candidates.into_iter().cloned().collect(),
        });
    }
    None
}

fn same_owner_context(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    matches!(
        structured_owner_context_resolution(node, ctx),
        StructuredOwnerContextResolution::SelfTarget
            | StructuredOwnerContextResolution::InheritedTarget
    )
}

/// A bare/`this->` member call whose name resolves, through the enclosing class's base
/// hierarchy or through a lexically enclosing class, to the target member declared on
/// another owner. This is a genuine external usage of that owner's member rather than a
/// same-type self call.
fn inherited_target_owner_context(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let Some(call) = ctx.ancestry.parent(node).filter(|parent| {
        parent.kind() == "call_expression" && parent.child_by_field_name("function") == Some(node)
    }) else {
        return matches!(
            structured_owner_context_resolution(node, ctx),
            StructuredOwnerContextResolution::InheritedTarget
        );
    };
    let Some(target_owner) = ctx.spec.owner.as_ref() else {
        return false;
    };
    let chain = structured_enclosing_owner_chain(node, ctx);
    let Some(innermost) = chain.first() else {
        return false;
    };
    if receiver_owner_matches_target(innermost, target_owner, node.start_byte(), ctx) {
        return false;
    }
    let Some(arity) = ctx
        .visibility
        .call_arity_evidence(ctx.file, call, ctx.source)
        .exact()
    else {
        return false;
    };
    for enclosing_owner in &chain {
        if receiver_owner_matches_target(enclosing_owner, target_owner, node.start_byte(), ctx) {
            return true;
        }
        match resolve_declaring_callable_owner(
            &ctx.analyzer,
            ctx.visibility,
            ctx.file,
            cached_declaring_member_owner(enclosing_owner, ctx),
            &ctx.spec.member_name,
            arity,
        ) {
            EnclosingMemberOwnerResolution::Owner(owner) => {
                return receiver_owner_matches_target(&owner, target_owner, node.start_byte(), ctx);
            }
            EnclosingMemberOwnerResolution::Ambiguous => return false,
            // The name is not declared in this class or its bases, so C++
            // unqualified lookup continues in the next enclosing class (#3095).
            EnclosingMemberOwnerResolution::Missing => {}
        }
    }
    false
}

fn known_non_target_owner_context(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    matches!(
        structured_owner_context_resolution(node, ctx),
        StructuredOwnerContextResolution::NonTarget
    )
}

fn out_of_line_target_owner_context(node: Node<'_>, ctx: &ScanCtx<'_>) -> bool {
    let Some(target_owner) = ctx.spec.owner.as_ref() else {
        return false;
    };
    let mut current = ctx.ancestry.parent(node);
    while let Some(parent) = current {
        if parent.kind() == "function_definition" {
            let Some(owner_lookup) = function_definition_owner_lookup_node(parent) else {
                return false;
            };
            if let Some(owners) = out_of_line_member_definition_owner(
                &ctx.analyzer,
                ctx.visibility,
                ctx.file,
                ctx.source,
                owner_lookup,
            ) && let Some((_, owner)) = owners.innermost()
            {
                return receiver_owner_matches_target(owner, target_owner, node.start_byte(), ctx);
            }
            if let Some(owner) = target_guided_out_of_line_owner(owner_lookup, ctx) {
                return receiver_owner_matches_target(&owner, target_owner, node.start_byte(), ctx);
            }
            return false;
        }
        current = ctx.ancestry.parent(parent);
    }
    false
}

#[derive(Clone, Copy)]
enum StructuredOwnerContextResolution {
    /// The enclosing class is itself the target owner: a bare/`this->` call here is a
    /// genuine same-type self call (the SelfReceiver policy from #1014-B applies).
    SelfTarget,
    /// The enclosing class does not declare the member; lookup reaches the target owner
    /// through a base of that class, or through a lexically enclosing class (a nested
    /// class calling the outer class's member). Either way the reference is a genuine
    /// external usage OF that owner's member (e.g. `Derived` calling inherited
    /// `Base::value`), not a self call, so it is attributed as an ordinary Reference.
    InheritedTarget,
    NonTarget,
    Ambiguous,
    Missing,
}

fn structured_owner_context_resolution(
    node: Node<'_>,
    ctx: &ScanCtx<'_>,
) -> StructuredOwnerContextResolution {
    let Some(target_owner) = ctx.spec.owner.as_ref() else {
        return StructuredOwnerContextResolution::Missing;
    };
    let chain = structured_enclosing_owner_chain(node, ctx);
    let Some(innermost) = chain.first() else {
        return StructuredOwnerContextResolution::Missing;
    };
    if receiver_owner_matches_target(innermost, target_owner, node.start_byte(), ctx) {
        return StructuredOwnerContextResolution::SelfTarget;
    }
    // Unqualified lookup searches the enclosing class and its bases, then each lexically
    // enclosing class outward, and stops at the first scope that declares the name (#3095).
    // Only the immediately enclosing class makes a reference a same-type self call; any
    // other owner it reaches is a genuine usage of that owner's member.
    for enclosing_owner in &chain {
        if receiver_owner_matches_target(enclosing_owner, target_owner, node.start_byte(), ctx) {
            return StructuredOwnerContextResolution::InheritedTarget;
        }
        match cached_declaring_member_owner(enclosing_owner, ctx) {
            EnclosingMemberOwnerResolution::Owner(owner)
                if receiver_owner_matches_target(&owner, target_owner, node.start_byte(), ctx) =>
            {
                return StructuredOwnerContextResolution::InheritedTarget;
            }
            EnclosingMemberOwnerResolution::Owner(_) => {
                return StructuredOwnerContextResolution::NonTarget;
            }
            EnclosingMemberOwnerResolution::Ambiguous => {
                return StructuredOwnerContextResolution::Ambiguous;
            }
            EnclosingMemberOwnerResolution::Missing => {}
        }
    }
    StructuredOwnerContextResolution::Missing
}

fn cached_declaring_member_owner(
    receiver_owner: &CodeUnit,
    ctx: &ScanCtx<'_>,
) -> EnclosingMemberOwnerResolution {
    if let Some(cached) = ctx.member_owner_cache.borrow().get(receiver_owner).cloned() {
        return cached;
    }
    let resolved = resolve_declaring_member_owner(
        &ctx.analyzer,
        ctx.visibility,
        ctx.file,
        receiver_owner,
        &ctx.spec.member_name,
    );
    let resolved = if matches!(resolved, EnclosingMemberOwnerResolution::Missing) {
        indexed_declaring_owner_for_recovered_member(receiver_owner, ctx)
    } else {
        resolved
    };
    ctx.member_owner_cache
        .borrow_mut()
        .insert(receiver_owner.clone(), resolved.clone());
    resolved
}

/// Recover a member's declaring owner when parser recovery omitted its
/// in-class declaration but retained an out-of-line definition. Ordinary
/// visible-member lookup runs first. The structured definition index then
/// supplies the missing member fact at each hierarchy level, so an indexed
/// derived override still hides the queried base member and distinct base
/// paths still fail closed.
fn indexed_declaring_owner_for_recovered_member(
    receiver_owner: &CodeUnit,
    ctx: &ScanCtx<'_>,
) -> EnclosingMemberOwnerResolution {
    let Some(spec_owner) = ctx.spec.owner.as_ref() else {
        return EnclosingMemberOwnerResolution::Missing;
    };
    if ctx.spec.kind != TargetKind::Method || ctx.spec.target.source() == spec_owner.source() {
        return EnclosingMemberOwnerResolution::Missing;
    }
    let Some(hierarchy) = ctx.analyzer.type_hierarchy_provider() else {
        return EnclosingMemberOwnerResolution::Missing;
    };
    let Some(receiver_owner) =
        ctx.visibility
            .canonical_visible_full_type_unit(&ctx.analyzer, ctx.file, receiver_owner)
    else {
        return EnclosingMemberOwnerResolution::Ambiguous;
    };
    let Some(target_owner) = ctx.spec.owner.as_ref().and_then(|owner| {
        ctx.visibility
            .canonical_visible_full_type_unit(&ctx.analyzer, ctx.file, owner)
    }) else {
        return EnclosingMemberOwnerResolution::Missing;
    };

    let owner_declares_member = |owner: &CodeUnit| {
        if same_visible_symbol(owner, &target_owner) {
            return true;
        }
        let mut member_fq = owner.fq().clone();
        member_fq.push(
            ctx.spec
                .target
                .fq()
                .last()
                .expect("a method target has a terminal member segment"),
        );
        ctx.analyzer
            .definitions(&member_fq.display(segment_interner()))
            .any(|child| child.is_function())
    };
    if owner_declares_member(&receiver_owner) {
        return EnclosingMemberOwnerResolution::Owner(receiver_owner);
    }

    let mut stack = hierarchy.get_direct_ancestors(&receiver_owner);
    let mut propagated_counts: HashMap<CodeUnit, u8> = HashMap::default();
    let mut declaring_owner = None;
    while let Some(raw_owner) = stack.pop() {
        let Some(owner) =
            ctx.visibility
                .canonical_visible_full_type_unit(&ctx.analyzer, ctx.file, &raw_owner)
        else {
            return EnclosingMemberOwnerResolution::Ambiguous;
        };
        let propagated = propagated_counts.entry(owner.clone()).or_default();
        if *propagated == 2 {
            continue;
        }
        *propagated += 1;
        if owner_declares_member(&owner) {
            if declaring_owner.is_some() {
                return EnclosingMemberOwnerResolution::Ambiguous;
            }
            declaring_owner = Some(owner);
            continue;
        }
        stack.extend(hierarchy.get_direct_ancestors(&owner));
    }
    declaring_owner
        .map(EnclosingMemberOwnerResolution::Owner)
        .unwrap_or(EnclosingMemberOwnerResolution::Missing)
}

/// The lexically enclosing classes at a reference, innermost first: C++ unqualified
/// lookup searches each in turn before it reaches the enclosing namespaces.
fn structured_enclosing_owner_chain(node: Node<'_>, ctx: &ScanCtx<'_>) -> Vec<CodeUnit> {
    let Some(innermost) = structured_enclosing_owner(node, ctx) else {
        return Vec::new();
    };
    // The innermost owner is whatever enclosing-owner resolution produced, so
    // it is kept as given; only the walk outward is filtered to classes.
    brokk_bifrost_core::analyzer::usages::common::enclosing_class_chain(innermost, |unit| {
        ctx.analyzer.parent_of(unit)
    })
    .collect()
}

fn structured_enclosing_owner(node: Node<'_>, ctx: &ScanCtx<'_>) -> Option<CodeUnit> {
    // Declaration recovery can index the true class/member ranges even when
    // the original error tree wraps that region in a bogus function. Prefer
    // the analyzer's exact enclosing-owner graph at the reference byte before
    // interpreting such a wrapper as a real callable owner.
    if (has_recovered_class_shape_ancestor(node)
        || has_malformed_wrapper_function_definition_ancestor(node))
        && let Some(owner) = cached_indexed_enclosing_class_owner(node, ctx)
    {
        return Some(owner);
    }
    let mut current = ctx.ancestry.parent(node);
    while let Some(parent) = current {
        if parent.kind() == "function_definition" {
            let owner_lookup = function_definition_owner_lookup_node(parent);
            if let Some(owner_lookup) = owner_lookup
                && let Some(owners) = out_of_line_member_definition_owner(
                    &ctx.analyzer,
                    ctx.visibility,
                    ctx.file,
                    ctx.source,
                    owner_lookup,
                )
                && let Some((_, owner)) = owners.innermost()
            {
                return Some(owner.clone());
            }
            if let Some(owner) = cached_indexed_enclosing_class_owner(parent, ctx) {
                return Some(owner);
            }
            if let Some(owner) = enclosing_context(parent, ctx)
                .owner
                .filter(|owner| owner.is_class())
            {
                return Some(owner);
            }
            if let Some(owner_lookup) = owner_lookup
                && let Some(owner) = target_guided_out_of_line_owner(owner_lookup, ctx)
            {
                return Some(owner);
            }
            break;
        }
        current = ctx.ancestry.parent(parent);
    }
    enclosing_context(node, ctx)
        .owner
        .filter(|owner| owner.is_class())
}

fn target_guided_out_of_line_owner(function: Node<'_>, ctx: &ScanCtx<'_>) -> Option<CodeUnit> {
    let target_owner = ctx.spec.owner.as_ref()?;
    let (owner_components, _) = qualified_callable_owner_components(function, ctx.source)?;
    let owner_name = owner_components.last()?;
    let mut candidates = Vec::new();
    for candidate in ctx
        .visibility
        .visible_identifier_candidates(ctx.file, owner_name)
        .filter(|candidate| candidate.is_class())
    {
        let components = brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path(
            brokk_bifrost_core::analyzer::Language::Cpp,
            &cpp_name_for(candidate),
        );
        if !components.ends_with(&owner_components)
            || candidates
                .iter()
                .any(|existing| same_logical_symbol(existing, candidate))
        {
            continue;
        }
        candidates.push(candidate.clone());
    }
    let [candidate] = candidates.as_slice() else {
        return None;
    };
    (same_logical_symbol(candidate, target_owner)
        && target_group_contains_owner_peer(candidate, ctx))
    .then(|| candidate.clone())
}