php_lsp/

references.rs

use std::collections::HashSet;
use std::sync::Arc;

use php_ast::{ClassMemberKind, EnumMemberKind, NamespaceBody, Span, Stmt, StmtKind};
use rayon::prelude::*;
use tower_lsp::lsp_types::{Location, Position, Range, Url};

use crate::ast::{ParsedDoc, str_offset_in_range};
use crate::util::utf16_code_units;
use crate::walk::{
    class_refs_in_stmts, fqn_new_class_refs_in_stmts, function_refs_in_stmts, method_refs_in_stmts,
    new_refs_in_stmts, property_refs_in_stmts, refs_in_stmts, refs_in_stmts_with_use,
};

/// Callback signature for the mir-codebase reference-lookup fast path:
/// `(key) -> Vec<(file_uri, start_byte, end_byte)>`.
pub type RefLookup<'a> = dyn Fn(&str) -> Vec<(Arc<str>, u32, u16, u16)> + 'a;

/// What kind of symbol the cursor is on.  Used to dispatch to the
/// appropriate semantic walker so that, e.g., searching for `get` as a
/// *method* doesn't return free-function calls named `get`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SymbolKind {
    /// A free (top-level) function.
    Function,
    /// An instance or static method (`->name`, `?->name`, `::name`).
    Method,
    /// A class, interface, trait, or enum name used as a type.
    Class,
    /// A class / trait property (`->name`, `?->name`, promoted or declared).
    Property,
}

fn class_has_ancestor(
    codebase: &mir_analyzer::db::MirDb,
    class_fqcn: &str,
    target_fqcn: &str,
) -> bool {
    mir_analyzer::db::extends_or_implements_via_db(codebase, class_fqcn, target_fqcn)
}

/// Find all locations where `word` is referenced across the given documents.
/// If `include_declaration` is true, also includes the declaration site.
/// Pass `kind` to restrict results to a particular symbol category; `None`
/// falls back to the original word-based walker (better some results than none).
pub fn find_references(
    word: &str,
    all_docs: &[(Url, Arc<ParsedDoc>)],
    include_declaration: bool,
    kind: Option<SymbolKind>,
) -> Vec<Location> {
    find_references_inner(word, all_docs, include_declaration, false, kind, None)
}

/// Like [`find_references`] but narrows scanning to docs whose namespace +
/// `use` imports would resolve `word` to `target_fqn`. Used by
/// `textDocument/references` for the AST fallback so it doesn't match
/// same-short-name symbols in unrelated namespaces.
pub fn find_references_with_target(
    word: &str,
    all_docs: &[(Url, Arc<ParsedDoc>)],
    include_declaration: bool,
    kind: Option<SymbolKind>,
    target_fqn: &str,
) -> Vec<Location> {
    // Default: include `use` statement spans so callers that pass
    // `kind=None` (notably the rename handler) get their use-import edits.
    // For typed kinds we want the kind-specific walker (so a Method search
    // doesn't pick up free functions sharing the name); the general walker
    // would falsely widen those results.
    let include_use = kind.is_none();
    find_references_inner(
        word,
        all_docs,
        include_declaration,
        include_use,
        kind,
        Some(target_fqn),
    )
}

/// Like `find_references` but also includes `use` statement spans.
/// Used by rename so that `use Foo;` statements are also updated.
/// Always uses the general walker (rename must update all occurrence kinds).
pub fn find_references_with_use(
    word: &str,
    all_docs: &[(Url, Arc<ParsedDoc>)],
    include_declaration: bool,
) -> Vec<Location> {
    find_references_inner(word, all_docs, include_declaration, true, None, None)
}

/// Find only `new ClassName(...)` instantiation sites across all docs.
///
/// Used by the `__construct` references handler — `SymbolKind::Class` (the normal
/// class-kind path) is too broad because mir's `ClassReference` key covers type
/// hints, `instanceof`, `extends`, and `implements` in addition to `new` calls.
/// This function walks the AST using `new_refs_in_stmts` which only emits spans
/// for `ExprKind::New` nodes, giving the caller exactly the call sites.
///
/// `class_fqn` is the fully-qualified name (e.g. `"Alpha\\Widget"`) used to
/// filter files where the short name resolves to a different class. Pass `None`
/// for global-namespace classes.
pub fn find_constructor_references(
    short_name: &str,
    all_docs: &[(Url, Arc<ParsedDoc>)],
    class_fqn: Option<&str>,
) -> Vec<Location> {
    all_docs
        .par_iter()
        .flat_map_iter(|(uri, doc)| {
            // Skip files that can't reference the target unless they may use the FQN
            // directly (without a `use` statement). FQN-qualified identifiers in the
            // AST are disambiguated inside `new_refs_in_stmts` via `class_fqn`.
            if let Some(fqn) = class_fqn
                && !doc_can_reference_target(doc, short_name, fqn)
                && !doc.view().source().contains(fqn.trim_start_matches('\\'))
            {
                return Vec::new();
            }
            let mut spans = Vec::new();
            new_refs_in_stmts(&doc.program().stmts, short_name, class_fqn, &mut spans);
            let sv = doc.view();
            spans
                .into_iter()
                .map(|span| {
                    let start = sv.position_of(span.start);
                    let end = sv.position_of(span.end);
                    Location {
                        uri: uri.clone(),
                        range: Range { start, end },
                    }
                })
                .collect::<Vec<_>>()
        })
        .collect()
}

/// Fast path: look up pre-computed reference locations from the mir codebase index.
///
/// Handles `Function`, `Class`, and (partially) `Method` kinds.  For `Function` and
/// `Class` the mir analyzer records every call-site / instantiation via
/// `mark_*_referenced_at` and the index is authoritative.
///
/// For `Method`, the index is used as a pre-filter: only files that contain a tracked
/// call site for the method are scanned with the AST walker.  This fast path is
/// activated for two cases where the tracked set is reliably complete or narrows the
/// search scope without missing real references:
///   • `private` methods — PHP semantics guarantee that private methods are only
///     callable from within the class body, so mir always resolves the receiver type.
///   • methods on `final` classes — no subclassing means call sites on the concrete
///     type are unambiguous; the codebase set covers all statically-typed callers.
///
/// Returns `None` for public/protected methods on non-final classes and for `None`
/// kind (caller should use the general AST walker instead).  Also returns `None` when
/// no matching symbol is found in the codebase.
pub fn find_references_codebase(
    word: &str,
    all_docs: &[(Url, Arc<ParsedDoc>)],
    include_declaration: bool,
    kind: Option<SymbolKind>,
    codebase: &mir_analyzer::db::MirDb,
    lookup_refs: &RefLookup<'_>,
) -> Option<Vec<Location>> {
    find_references_codebase_with_target(
        word,
        all_docs,
        include_declaration,
        kind,
        None,
        codebase,
        lookup_refs,
    )
}

/// Like [`find_references_codebase`] but accepts an exact FQN (for Function/Class)
/// or owning FQCN (for Method) to avoid short-name collisions across namespaces
/// and unrelated classes. When `target_fqn` is `None`, behaves identically to
/// `find_references_codebase`.
pub fn find_references_codebase_with_target(
    _word: &str,
    _all_docs: &[(Url, Arc<ParsedDoc>)],
    _include_declaration: bool,
    kind: Option<SymbolKind>,
    _target_fqn: Option<&str>,
    _codebase: &mir_analyzer::db::MirDb,
    _lookup_refs: &RefLookup<'_>,
) -> Option<Vec<Location>> {
    match kind {
        Some(SymbolKind::Function) => {
            // For now, fall back to the AST walker for functions.
            // In the future, we could query the MirDb for function info.
            None
        }

        // The mir index records ClassReference only for `new Foo()` expressions, not
        // for type hints, `extends`, `implements`, or `instanceof`. Using the index
        // would silently drop those sites when any `new` call exists. Always fall
        // through to the AST walker (class_refs_in_stmts) which covers all sites.
        Some(SymbolKind::Class) => None,

        Some(SymbolKind::Method) => {
            // For now, fall back to the AST walker for methods.
            // In the future, we could use the MirDb to optimize this.
            None
        }

        // General walker already handles None kind; codebase index adds no value.
        None => None,

        // Properties aren't tracked in the mir codebase index; fall through to
        // the general AST walker by returning None.
        Some(SymbolKind::Property) => None,
    }
}

fn find_references_inner(
    word: &str,
    all_docs: &[(Url, Arc<ParsedDoc>)],
    include_declaration: bool,
    include_use: bool,
    kind: Option<SymbolKind>,
    target_fqn: Option<&str>,
) -> Vec<Location> {
    // Each document is scanned independently: substring pre-filter, AST walk,
    // then span → position translation. Rayon parallelizes across docs; the
    // per-doc work is CPU-bound and 100% independent, so this scales linearly
    // with cores on large workspaces (Laravel: ~1,600 files).
    // Per-file namespace pre-filter only applies to Function and Class kinds,
    // where the target FQN refers to the symbol itself. For methods the
    // target is the *owning* FQCN, which can't be compared against the
    // method name via namespace resolution.
    let namespace_filter_active =
        matches!(kind, Some(SymbolKind::Function) | Some(SymbolKind::Class));
    all_docs
        .par_iter()
        .flat_map_iter(|(uri, doc)| {
            if namespace_filter_active
                && let Some(target) = target_fqn
                && !doc_can_reference_target(doc, word, target)
            {
                return Vec::new();
            }
            scan_doc(word, uri, doc, include_declaration, include_use, kind)
        })
        .collect()
}

/// Return true when this doc's namespace + `use` imports could plausibly
/// refer to `target_fqn` under the short name `word`.  Used as a pre-filter
/// so the AST walker doesn't emit refs in files whose namespace would resolve
/// `word` to a different FQN.
fn doc_can_reference_target(doc: &ParsedDoc, word: &str, target_fqn: &str) -> bool {
    let target = target_fqn.trim_start_matches('\\');
    let imports = collect_file_imports(doc);
    let resolved = crate::moniker::resolve_fqn(doc, word, &imports);
    // PHP falls back to the global namespace for unqualified *function* calls
    // when the namespaced version doesn't exist.  We don't know at this point
    // which symbol category the target is, so accept either an exact match
    // or a global-namespace fallback match.
    resolved == target
        || (resolved == word && !target.contains('\\'))
        || (resolved == word && target == format!("\\{word}"))
}

/// Build a local-name → FQN map from a doc's `use` statements.  Mirrors
/// `Backend::file_imports` but self-contained so the reference walker can
/// run without a persistent codebase.
pub(crate) fn collect_file_imports(doc: &ParsedDoc) -> std::collections::HashMap<String, String> {
    let mut out = std::collections::HashMap::new();
    fn walk(stmts: &[Stmt<'_, '_>], out: &mut std::collections::HashMap<String, String>) {
        for stmt in stmts {
            match &stmt.kind {
                StmtKind::Use(u) => {
                    for item in u.uses.iter() {
                        let fqn = item.name.to_string_repr().into_owned();
                        let short = item
                            .alias
                            .map(|a| a.to_string())
                            .unwrap_or_else(|| fqn.rsplit('\\').next().unwrap_or(&fqn).to_string());
                        out.insert(short, fqn);
                    }
                }
                StmtKind::Namespace(ns) => {
                    if let NamespaceBody::Braced(inner) = &ns.body {
                        walk(inner, out);
                    }
                }
                _ => {}
            }
        }
    }
    walk(&doc.program().stmts, &mut out);
    out
}

/// Collect every FQN class name (e.g. `\App\Model\Entity`) referenced in a
/// `new` expression that has no corresponding `use` import (i.e. written with
/// a leading `\`).  Returns de-duplicated strings with the leading `\` stripped,
/// ready for `session.lazy_load_class`.
pub(crate) fn collect_fqn_new_class_refs(doc: &ParsedDoc) -> Vec<String> {
    fqn_new_class_refs_in_stmts(&doc.program().stmts)
}

fn scan_doc(
    word: &str,
    uri: &Url,
    doc: &Arc<ParsedDoc>,
    include_declaration: bool,
    include_use: bool,
    kind: Option<SymbolKind>,
) -> Vec<Location> {
    let source = doc.source();
    // Substring pre-filter: every walker below pushes a span only when an
    // identifier's bytes equal `word`, so if `word` does not appear in the
    // source it cannot produce any reference. `str::contains` is memchr-fast
    // and skips the full AST traversal for the vast majority of files.
    if !source.contains(word) {
        return Vec::new();
    }
    let stmts = &doc.program().stmts;
    let mut spans = Vec::new();

    if include_use {
        // Rename path: general walker covers call sites, `use` imports, and declarations.
        refs_in_stmts_with_use(source, stmts, word, &mut spans);
        if !include_declaration {
            let mut decl_spans = Vec::new();
            collect_declaration_spans(source, stmts, word, None, &mut decl_spans);
            let decl_set: HashSet<(u32, u32)> =
                decl_spans.iter().map(|s| (s.start, s.end)).collect();
            spans.retain(|span| !decl_set.contains(&(span.start, span.end)));
        }
    } else {
        match kind {
            Some(SymbolKind::Function) => function_refs_in_stmts(stmts, word, &mut spans),
            Some(SymbolKind::Method) => method_refs_in_stmts(stmts, word, &mut spans),
            Some(SymbolKind::Class) => class_refs_in_stmts(stmts, word, &mut spans),
            // Property walker emits both access sites *and* declaration spans
            // (used by rename). Strip decls here when the caller doesn't want them.
            Some(SymbolKind::Property) => {
                property_refs_in_stmts(source, stmts, word, &mut spans);
                if !include_declaration {
                    let mut decl_spans = Vec::new();
                    collect_declaration_spans(
                        source,
                        stmts,
                        word,
                        Some(SymbolKind::Property),
                        &mut decl_spans,
                    );
                    let decl_set: HashSet<(u32, u32)> =
                        decl_spans.iter().map(|s| (s.start, s.end)).collect();
                    spans.retain(|span| !decl_set.contains(&(span.start, span.end)));
                }
            }
            // General walker already includes declarations; filter them out if unwanted.
            None => {
                refs_in_stmts(source, stmts, word, &mut spans);
                if !include_declaration {
                    let mut decl_spans = Vec::new();
                    collect_declaration_spans(source, stmts, word, None, &mut decl_spans);
                    let decl_set: HashSet<(u32, u32)> =
                        decl_spans.iter().map(|s| (s.start, s.end)).collect();
                    spans.retain(|span| !decl_set.contains(&(span.start, span.end)));
                }
            }
        }
        // Typed walkers (except Property, which already includes decls) don't emit
        // declaration spans, so add them separately when wanted. Pass `kind` so only
        // declarations of the matching category are appended — a Method search must
        // not return a free-function declaration with the same name.
        if include_declaration
            && matches!(
                kind,
                Some(SymbolKind::Function) | Some(SymbolKind::Method) | Some(SymbolKind::Class)
            )
        {
            collect_declaration_spans(source, stmts, word, kind, &mut spans);
        }
    }

    let sv = doc.view();
    let word_utf16_len: u32 = utf16_code_units(word);
    spans
        .into_iter()
        .map(|span| {
            let start = sv.position_of(span.start);
            let end = Position {
                line: start.line,
                character: start.character + word_utf16_len,
            };
            Location {
                uri: uri.clone(),
                range: Range { start, end },
            }
        })
        .collect()
}

/// Build a span covering exactly the declared name (not the keyword before it).
/// Uses the stmt_span to search within the statement's context, avoiding false
/// matches from earlier occurrences of the same name in the file.
fn declaration_name_span(source: &str, name: &str, stmt_span: Span) -> Span {
    let start = str_offset_in_range(source, stmt_span, name).unwrap_or(stmt_span.start);
    Span {
        start,
        end: start + name.len() as u32,
    }
}

/// Collect method-name declaration spans for a method named `method_word`
/// inside the class/interface/trait/enum whose short name is `class_short`.
/// Used by the Method fast path to emit precise declaration spans that are
/// scoped to the target owning type, so unrelated same-named methods in the
/// same file don't pollute the results.
fn collect_method_decls_in_class(
    source: &str,
    stmts: &[Stmt<'_, '_>],
    class_short: &str,
    method_word: &str,
    out: &mut Vec<Span>,
) {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Class(c)
                if c.name.as_ref().map(|n| n.to_string()) == Some(class_short.to_string()) =>
            {
                for member in c.members.iter() {
                    if let ClassMemberKind::Method(m) = &member.kind
                        && m.name == method_word
                    {
                        out.push(declaration_name_span(
                            source,
                            &m.name.to_string(),
                            stmt.span,
                        ));
                    }
                }
            }
            StmtKind::Interface(i) if i.name == class_short => {
                for member in i.members.iter() {
                    if let ClassMemberKind::Method(m) = &member.kind
                        && m.name == method_word
                    {
                        out.push(declaration_name_span(
                            source,
                            &m.name.to_string(),
                            stmt.span,
                        ));
                    }
                }
            }
            StmtKind::Trait(t) if t.name == class_short => {
                for member in t.members.iter() {
                    if let ClassMemberKind::Method(m) = &member.kind
                        && m.name == method_word
                    {
                        out.push(declaration_name_span(
                            source,
                            &m.name.to_string(),
                            stmt.span,
                        ));
                    }
                }
            }
            StmtKind::Enum(e) if e.name == class_short => {
                for member in e.members.iter() {
                    if let EnumMemberKind::Method(m) = &member.kind
                        && m.name == method_word
                    {
                        out.push(declaration_name_span(
                            source,
                            &m.name.to_string(),
                            stmt.span,
                        ));
                    }
                }
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body {
                    collect_method_decls_in_class(source, inner, class_short, method_word, out);
                }
            }
            _ => {}
        }
    }
}

/// Collect every span where `word` is *declared* within `stmts`.
///
/// When `kind` is `Some`, only declarations of the matching category are collected:
/// - `Function` → free (`StmtKind::Function`) declarations only
/// - `Method`   → method declarations inside classes / traits / enums only
/// - `Class`    → class / interface / trait / enum type declarations only
///
/// `None` collects every declaration kind (used by `is_declaration_span`).
fn collect_declaration_spans(
    source: &str,
    stmts: &[Stmt<'_, '_>],
    word: &str,
    kind: Option<SymbolKind>,
    out: &mut Vec<Span>,
) {
    let want_free = matches!(kind, None | Some(SymbolKind::Function));
    let want_method = matches!(kind, None | Some(SymbolKind::Method));
    let want_type = matches!(kind, None | Some(SymbolKind::Class));
    let want_property = matches!(kind, None | Some(SymbolKind::Property));

    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Function(f) if want_free && f.name == word => {
                out.push(declaration_name_span(
                    source,
                    &f.name.to_string(),
                    stmt.span,
                ));
            }
            StmtKind::Class(c) => {
                if want_type
                    && let Some(name) = c.name
                    && name == word
                {
                    out.push(declaration_name_span(source, &name.to_string(), stmt.span));
                }
                if want_method || want_property {
                    for member in c.members.iter() {
                        match &member.kind {
                            ClassMemberKind::Method(m) if want_method && m.name == word => {
                                // Scope the name search to the member span,
                                // not the whole class — otherwise a class
                                // named the same as one of its members
                                // (`class get { function get() {} }`) resolves
                                // both decls to the class name's position.
                                out.push(declaration_name_span(
                                    source,
                                    &m.name.to_string(),
                                    member.span,
                                ));
                            }
                            ClassMemberKind::Method(m)
                                if want_property && m.name == "__construct" =>
                            {
                                // Promoted constructor params act as property declarations.
                                for p in m.params.iter() {
                                    if p.visibility.is_some() && p.name == word {
                                        out.push(declaration_name_span(
                                            source,
                                            &p.name.to_string(),
                                            p.span,
                                        ));
                                    }
                                }
                            }
                            ClassMemberKind::Property(p) if want_property && p.name == word => {
                                out.push(declaration_name_span(
                                    source,
                                    &p.name.to_string(),
                                    member.span,
                                ));
                            }
                            _ => {}
                        }
                    }
                }
            }
            StmtKind::Interface(i) => {
                if want_type && i.name == word {
                    out.push(declaration_name_span(
                        source,
                        &i.name.to_string(),
                        stmt.span,
                    ));
                }
                if want_method {
                    for member in i.members.iter() {
                        if let ClassMemberKind::Method(m) = &member.kind
                            && m.name == word
                        {
                            out.push(declaration_name_span(
                                source,
                                &m.name.to_string(),
                                member.span,
                            ));
                        }
                    }
                }
            }
            StmtKind::Trait(t) => {
                if want_type && t.name == word {
                    out.push(declaration_name_span(
                        source,
                        &t.name.to_string(),
                        stmt.span,
                    ));
                }
                if want_method || want_property {
                    for member in t.members.iter() {
                        match &member.kind {
                            ClassMemberKind::Method(m) if want_method && m.name == word => {
                                out.push(declaration_name_span(
                                    source,
                                    &m.name.to_string(),
                                    stmt.span,
                                ));
                            }
                            ClassMemberKind::Property(p) if want_property && p.name == word => {
                                out.push(declaration_name_span(
                                    source,
                                    &p.name.to_string(),
                                    stmt.span,
                                ));
                            }
                            _ => {}
                        }
                    }
                }
            }
            StmtKind::Enum(e) => {
                if want_type && e.name == word {
                    out.push(declaration_name_span(
                        source,
                        &e.name.to_string(),
                        stmt.span,
                    ));
                }
                for member in e.members.iter() {
                    match &member.kind {
                        EnumMemberKind::Method(m) if want_method && m.name == word => {
                            out.push(declaration_name_span(
                                source,
                                &m.name.to_string(),
                                stmt.span,
                            ));
                        }
                        EnumMemberKind::Case(c) if want_type && c.name == word => {
                            out.push(declaration_name_span(
                                source,
                                &c.name.to_string(),
                                stmt.span,
                            ));
                        }
                        _ => {}
                    }
                }
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body {
                    collect_declaration_spans(source, inner, word, kind, out);
                }
            }
            _ => {}
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn uri(path: &str) -> Url {
        Url::parse(&format!("file://{path}")).unwrap()
    }

    fn doc(path: &str, source: &str) -> (Url, Arc<ParsedDoc>) {
        (uri(path), Arc::new(ParsedDoc::parse(source.to_string())))
    }

    #[test]
    fn finds_function_call_reference() {
        let src = "<?php\nfunction greet() {}\ngreet();\ngreet();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("greet", &docs, false, None);
        assert_eq!(refs.len(), 2, "expected 2 call-site refs, got {:?}", refs);
    }

    #[test]
    fn include_declaration_adds_def_site() {
        let src = "<?php\nfunction greet() {}\ngreet();";
        let docs = vec![doc("/a.php", src)];
        let with_decl = find_references("greet", &docs, true, None);
        let without_decl = find_references("greet", &docs, false, None);
        // Without declaration: only the call site (line 2)
        assert_eq!(
            without_decl.len(),
            1,
            "expected 1 call-site ref without declaration"
        );
        assert_eq!(
            without_decl[0].range.start.line, 2,
            "call site should be on line 2"
        );
        // With declaration: 2 refs total (decl on line 1, call on line 2)
        assert_eq!(
            with_decl.len(),
            2,
            "expected 2 refs with declaration included"
        );
    }

    #[test]
    fn finds_new_expression_reference() {
        let src = "<?php\nclass Foo {}\n$x = new Foo();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("Foo", &docs, false, None);
        assert_eq!(
            refs.len(),
            1,
            "expected exactly 1 reference to Foo in new expr"
        );
        assert_eq!(
            refs[0].range.start.line, 2,
            "new Foo() reference should be on line 2"
        );
    }

    #[test]
    fn finds_reference_in_nested_function_call() {
        let src = "<?php\nfunction greet() {}\necho(greet());";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("greet", &docs, false, None);
        assert_eq!(
            refs.len(),
            1,
            "expected exactly 1 nested function call reference"
        );
        assert_eq!(
            refs[0].range.start.line, 2,
            "nested greet() call should be on line 2"
        );
    }

    #[test]
    fn finds_references_across_multiple_docs() {
        let a = doc("/a.php", "<?php\nfunction helper() {}");
        let b = doc("/b.php", "<?php\nhelper();\nhelper();");
        let refs = find_references("helper", &[a, b], false, None);
        assert_eq!(refs.len(), 2, "expected 2 cross-file references");
        assert!(refs.iter().all(|r| r.uri.path().ends_with("/b.php")));
    }

    #[test]
    fn finds_method_call_reference() {
        let src = "<?php\nclass Calc { public function add() {} }\n$c = new Calc();\n$c->add();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("add", &docs, false, None);
        assert_eq!(
            refs.len(),
            1,
            "expected exactly 1 method call reference to 'add'"
        );
        assert_eq!(
            refs[0].range.start.line, 3,
            "add() call should be on line 3"
        );
    }

    #[test]
    fn finds_reference_inside_if_body() {
        let src = "<?php\nfunction check() {}\nif (true) { check(); }";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("check", &docs, false, None);
        assert_eq!(refs.len(), 1, "expected exactly 1 reference inside if body");
        assert_eq!(
            refs[0].range.start.line, 2,
            "check() inside if should be on line 2"
        );
    }

    #[test]
    fn finds_use_statement_reference() {
        // Renaming MyClass — the `use MyClass;` statement should be in the results
        // when using find_references_with_use.
        let src = "<?php\nuse MyClass;\n$x = new MyClass();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references_with_use("MyClass", &docs, false);
        // Exactly 2 references: the `use MyClass;` on line 1 and `new MyClass()` on line 2.
        assert_eq!(
            refs.len(),
            2,
            "expected exactly 2 references, got: {:?}",
            refs
        );
        let mut lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        lines.sort_unstable();
        assert_eq!(
            lines,
            vec![1, 2],
            "references should be on lines 1 (use) and 2 (new)"
        );
    }

    #[test]
    fn find_references_returns_correct_lines() {
        // `helper` is called on lines 1 and 2 (0-based); check exact line numbers.
        let src = "<?php\nhelper();\nhelper();\nfunction helper() {}";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("helper", &docs, false, None);
        assert_eq!(refs.len(), 2, "expected exactly 2 call-site references");
        let mut lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        lines.sort_unstable();
        assert_eq!(lines, vec![1, 2], "references should be on lines 1 and 2");
    }

    #[test]
    fn declaration_excluded_when_flag_false() {
        // When include_declaration=false the declaration line must not appear.
        let src = "<?php\nfunction doWork() {}\ndoWork();\ndoWork();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("doWork", &docs, false, None);
        // Declaration is on line 1; call sites are on lines 2 and 3.
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            !lines.contains(&1),
            "declaration line (1) must not appear when include_declaration=false, got: {:?}",
            lines
        );
        assert_eq!(refs.len(), 2, "expected 2 call-site references only");
    }

    #[test]
    fn partial_match_not_included() {
        // Searching for references to `greet` should NOT include occurrences of `greeting`.
        let src = "<?php\nfunction greet() {}\nfunction greeting() {}\ngreet();\ngreeting();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("greet", &docs, false, None);
        // Only `greet()` call site should be included, not `greeting()`.
        for r in &refs {
            // Each reference range should span exactly the length of "greet" (5 chars),
            // not longer (which would indicate "greeting" was matched).
            let span_len = r.range.end.character - r.range.start.character;
            assert_eq!(
                span_len, 5,
                "reference span length should equal len('greet')=5, got {} at {:?}",
                span_len, r
            );
        }
        // There should be exactly 1 call-site reference (the greet() call, not greeting()).
        assert_eq!(
            refs.len(),
            1,
            "expected exactly 1 reference to 'greet' (not 'greeting'), got: {:?}",
            refs
        );
    }

    #[test]
    fn finds_reference_in_class_property_default() {
        // A class constant used as a property default value should be found by find_references.
        let src = "<?php\nclass Foo {\n    public string $status = Status::ACTIVE;\n}";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("Status", &docs, false, None);
        assert_eq!(
            refs.len(),
            1,
            "expected exactly 1 reference to Status in property default, got: {:?}",
            refs
        );
        assert_eq!(refs[0].range.start.line, 2, "reference should be on line 2");
    }

    #[test]
    fn class_const_access_span_covers_only_member_name() {
        // Searching for the constant name `ACTIVE` in `Status::ACTIVE` must highlight
        // only `ACTIVE`, not the whole `Status::ACTIVE` expression.
        // Line 0: <?php
        // Line 1: $x = Status::ACTIVE;
        //                       ^ character 13
        let src = "<?php\n$x = Status::ACTIVE;";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("ACTIVE", &docs, false, None);
        assert_eq!(refs.len(), 1, "expected 1 reference, got: {:?}", refs);
        let r = &refs[0].range;
        assert_eq!(r.start.line, 1, "reference must be on line 1");
        // "$x = Status::" is 13 chars; "ACTIVE" starts at character 13.
        // Before the fix this was 5 (the start of "Status"), not 13.
        assert_eq!(
            r.start.character, 13,
            "range must start at 'ACTIVE' (char 13), not at 'Status' (char 5); got {:?}",
            r
        );
    }

    #[test]
    fn class_const_access_no_duplicate_when_name_equals_class() {
        // Edge case: enum case named the same as the enum itself — `Status::Status`.
        // The general walker finds two distinct references:
        //   - the class-side `Status` at character 5  ($x = [S]tatus::Status)
        //   - the member-side `Status` at character 13 ($x = Status::[S]tatus)
        // Before the fix, both pushed a span starting at character 5, producing a duplicate.
        // Line 0: <?php
        // Line 1: $x = Status::Status;
        //              ^    char 5 (class)
        //                       ^ char 13 (member)
        let src = "<?php\n$x = Status::Status;";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("Status", &docs, false, None);
        assert_eq!(
            refs.len(),
            2,
            "expected exactly 2 refs (class side + member side), got: {:?}",
            refs
        );
        let mut chars: Vec<u32> = refs.iter().map(|r| r.range.start.character).collect();
        chars.sort_unstable();
        assert_eq!(
            chars,
            vec![5, 13],
            "class-side ref must be at char 5 and member-side at char 13, got: {:?}",
            refs
        );
    }

    #[test]
    fn finds_reference_inside_enum_method_body() {
        // A function call inside an enum method body should be found by find_references.
        let src = "<?php\nfunction helper() {}\nenum Status {\n    public function label(): string { return helper(); }\n}";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("helper", &docs, false, None);
        assert_eq!(
            refs.len(),
            1,
            "expected exactly 1 reference to helper() inside enum method, got: {:?}",
            refs
        );
        assert_eq!(refs[0].range.start.line, 3, "reference should be on line 3");
    }

    #[test]
    fn finds_reference_in_for_init_and_update() {
        // Function calls in `for` init and update expressions should be found.
        let src = "<?php\nfunction tick() {}\nfor (tick(); $i < 10; tick()) {}";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("tick", &docs, false, None);
        assert_eq!(
            refs.len(),
            2,
            "expected exactly 2 references to tick() (init + update), got: {:?}",
            refs
        );
        // Both are on line 2.
        assert!(refs.iter().all(|r| r.range.start.line == 2));
    }

    // ── Semantic (kind-aware) tests ───────────────────────────────────────────

    #[test]
    fn function_kind_skips_method_call_with_same_name() {
        // When looking for the free function `get`, method calls `$obj->get()` must be excluded.
        let src = "<?php\nfunction get() {}\nget();\n$obj->get();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("get", &docs, false, Some(SymbolKind::Function));
        // Only the free call `get()` on line 2 should appear; not the method call on line 3.
        assert_eq!(
            refs.len(),
            1,
            "expected 1 free-function ref, got: {:?}",
            refs
        );
        assert_eq!(refs[0].range.start.line, 2);
    }

    #[test]
    fn method_kind_skips_free_function_call_with_same_name() {
        // When looking for the method `add`, the free function call `add()` must be excluded.
        let src = "<?php\nfunction add() {}\nadd();\n$calc->add();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("add", &docs, false, Some(SymbolKind::Method));
        // Only the method call on line 3 should appear.
        assert_eq!(refs.len(), 1, "expected 1 method ref, got: {:?}", refs);
        assert_eq!(refs[0].range.start.line, 3);
    }

    #[test]
    fn class_kind_finds_new_expression() {
        // SymbolKind::Class should find `new Foo()` but not a free function call `Foo()`.
        let src = "<?php\nclass Foo {}\n$x = new Foo();\nFoo();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("Foo", &docs, false, Some(SymbolKind::Class));
        // `new Foo()` on line 2 yes; `Foo()` on line 3 should NOT appear as a class ref.
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&2),
            "expected new Foo() on line 2, got: {:?}",
            refs
        );
        assert!(
            !lines.contains(&3),
            "free call Foo() should not appear as class ref, got: {:?}",
            refs
        );
    }

    #[test]
    fn class_kind_finds_extends_and_implements() {
        let src = "<?php\nclass Base {}\ninterface Iface {}\nclass Child extends Base implements Iface {}";
        let docs = vec![doc("/a.php", src)];

        let base_refs = find_references("Base", &docs, false, Some(SymbolKind::Class));
        let lines_base: Vec<u32> = base_refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines_base.contains(&3),
            "expected extends Base on line 3, got: {:?}",
            base_refs
        );

        let iface_refs = find_references("Iface", &docs, false, Some(SymbolKind::Class));
        let lines_iface: Vec<u32> = iface_refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines_iface.contains(&3),
            "expected implements Iface on line 3, got: {:?}",
            iface_refs
        );
    }

    #[test]
    fn class_kind_finds_type_hint() {
        // SymbolKind::Class should find `Foo` as a parameter type hint.
        let src = "<?php\nclass Foo {}\nfunction take(Foo $x): void {}";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("Foo", &docs, false, Some(SymbolKind::Class));
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&2),
            "expected type hint Foo on line 2, got: {:?}",
            refs
        );
    }

    // ── Declaration span precision tests ────────────────────────────────────────

    #[test]
    fn function_declaration_span_points_to_name_not_keyword() {
        // `include_declaration: true` — the declaration ref must start at `greet`,
        // not at the `function` keyword.
        let src = "<?php\nfunction greet() {}";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("greet", &docs, true, None);
        assert_eq!(refs.len(), 1, "expected exactly 1 ref (the declaration)");
        // "function " is 9 bytes; "greet" starts at byte 15 (after "<?php\n").
        // As a position, line 1, character 9.
        assert_eq!(
            refs[0].range.start.line, 1,
            "declaration should be on line 1"
        );
        assert_eq!(
            refs[0].range.start.character, 9,
            "declaration should start at the function name, not the 'function' keyword"
        );
        assert_eq!(
            refs[0].range.end.character,
            refs[0].range.start.character + utf16_code_units("greet"),
            "range should span exactly the function name"
        );
    }

    #[test]
    fn class_declaration_span_points_to_name_not_keyword() {
        let src = "<?php\nclass MyClass {}";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("MyClass", &docs, true, None);
        assert_eq!(refs.len(), 1);
        // "class " is 6 bytes; "MyClass" starts at character 6.
        assert_eq!(refs[0].range.start.line, 1);
        assert_eq!(
            refs[0].range.start.character, 6,
            "declaration should start at 'MyClass', not 'class'"
        );
    }

    #[test]
    fn method_declaration_span_points_to_name_not_keyword() {
        let src = "<?php\nclass C {\n    public function doThing() {}\n}\n(new C())->doThing();";
        let docs = vec![doc("/a.php", src)];
        // include_declaration=true so we get the method declaration too.
        let refs = find_references("doThing", &docs, true, None);
        // Declaration on line 2, call on line 4.
        let decl_ref = refs
            .iter()
            .find(|r| r.range.start.line == 2)
            .expect("no declaration ref on line 2");
        // "    public function " is 20 chars; "doThing" starts at character 20.
        assert_eq!(
            decl_ref.range.start.character, 20,
            "method declaration should start at the method name, not 'public function'"
        );
    }

    #[test]
    fn method_kind_with_include_declaration_does_not_return_free_function() {
        // Regression: kind precision must be preserved even when include_declaration=true.
        // A free function `get` and a method `get` coexist; searching with
        // SymbolKind::Method must NOT return either the free function call or its declaration.
        //
        // Line 0: <?php
        // Line 1: function get() {}          ← free function declaration
        // Line 2: get();                     ← free function call
        // Line 3: class C { public function get() {} }  ← method declaration
        // Line 4: $c->get();                 ← method call
        let src =
            "<?php\nfunction get() {}\nget();\nclass C { public function get() {} }\n$c->get();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("get", &docs, true, Some(SymbolKind::Method));
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&3),
            "method declaration (line 3) must be present, got: {:?}",
            lines
        );
        assert!(
            lines.contains(&4),
            "method call (line 4) must be present, got: {:?}",
            lines
        );
        assert!(
            !lines.contains(&1),
            "free function declaration (line 1) must not appear when kind=Method, got: {:?}",
            lines
        );
        assert!(
            !lines.contains(&2),
            "free function call (line 2) must not appear when kind=Method, got: {:?}",
            lines
        );
    }

    #[test]
    fn function_kind_with_include_declaration_does_not_return_method_call() {
        // Symmetric: SymbolKind::Function + include_declaration=true must not return method
        // calls or method declarations with the same name.
        //
        // Line 0: <?php
        // Line 1: function add() {}          ← free function declaration
        // Line 2: add();                     ← free function call
        // Line 3: class C { public function add() {} }  ← method declaration
        // Line 4: $c->add();                 ← method call
        let src =
            "<?php\nfunction add() {}\nadd();\nclass C { public function add() {} }\n$c->add();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("add", &docs, true, Some(SymbolKind::Function));
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&1),
            "function declaration (line 1) must be present, got: {:?}",
            lines
        );
        assert!(
            lines.contains(&2),
            "function call (line 2) must be present, got: {:?}",
            lines
        );
        assert!(
            !lines.contains(&3),
            "method declaration (line 3) must not appear when kind=Function, got: {:?}",
            lines
        );
        assert!(
            !lines.contains(&4),
            "method call (line 4) must not appear when kind=Function, got: {:?}",
            lines
        );
    }

    #[test]
    fn interface_method_declaration_included_when_flag_true() {
        // Regression: collect_declaration_spans must cover interface members, not only
        // classes/traits/enums. When include_declaration=true and kind=Method the
        // abstract method stub inside the interface must appear.
        //
        // Line 0: <?php
        // Line 1: interface I {
        // Line 2:     public function add(): void;   ← interface method declaration
        // Line 3: }
        // Line 4: $obj->add();                        ← call site
        let src = "<?php\ninterface I {\n    public function add(): void;\n}\n$obj->add();";
        let docs = vec![doc("/a.php", src)];

        let refs = find_references("add", &docs, true, Some(SymbolKind::Method));
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&2),
            "interface method declaration (line 2) must appear with include_declaration=true, got: {:?}",
            lines
        );
        assert!(
            lines.contains(&4),
            "call site (line 4) must appear, got: {:?}",
            lines
        );

        // With include_declaration=false only the call site should remain.
        let refs_no_decl = find_references("add", &docs, false, Some(SymbolKind::Method));
        let lines_no_decl: Vec<u32> = refs_no_decl.iter().map(|r| r.range.start.line).collect();
        assert!(
            !lines_no_decl.contains(&2),
            "interface method declaration must be excluded when include_declaration=false, got: {:?}",
            lines_no_decl
        );
    }

    #[test]
    fn declaration_filter_finds_method_inside_same_named_class() {
        // Edge case: a class named `get` contains a method also named `get`.
        // collect_declaration_spans(kind=None) must find BOTH the class declaration
        // and the method declaration so is_declaration_span correctly filters both
        // when include_declaration=false.
        //
        // Line 0: <?php
        // Line 1: class get { public function get() {} }
        // Line 2: $obj->get();
        let src = "<?php\nclass get { public function get() {} }\n$obj->get();";
        let docs = vec![doc("/a.php", src)];

        // With include_declaration=false, neither the class name nor the method
        // declaration should appear — only the call site on line 2.
        let refs = find_references("get", &docs, false, None);
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            !lines.contains(&1),
            "declaration line (1) must not appear when include_declaration=false, got: {:?}",
            lines
        );
        assert!(
            lines.contains(&2),
            "call site (line 2) must be present, got: {:?}",
            lines
        );

        // With include_declaration=true, the class declaration AND method declaration
        // are both on line 1; the call site is on line 2.
        let refs_with = find_references("get", &docs, true, None);
        assert_eq!(
            refs_with.len(),
            3,
            "expected 3 refs (class decl + method decl + call), got: {:?}",
            refs_with
        );
    }

    #[test]
    fn interface_method_declaration_included_with_kind_none() {
        // Regression: the general walker must emit interface method name spans so that
        // kind=None + include_declaration=true returns the declaration, matching the
        // behaviour already present for class and trait methods.
        //
        // Line 0: <?php
        // Line 1: interface I {
        // Line 2:     public function add(): void;   ← declaration
        // Line 3: }
        // Line 4: $obj->add();                        ← call site
        let src = "<?php\ninterface I {\n    public function add(): void;\n}\n$obj->add();";
        let docs = vec![doc("/a.php", src)];

        let refs = find_references("add", &docs, true, None);
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&2),
            "interface method declaration (line 2) must appear with kind=None + include_declaration=true, got: {:?}",
            lines
        );
    }

    #[test]
    fn interface_method_declaration_excluded_with_kind_none_flag_false() {
        // Counterpart to interface_method_declaration_included_with_kind_none.
        // is_declaration_span calls collect_declaration_spans(kind=None), which after
        // the fix now emits interface method name spans. Verify that
        // include_declaration=false correctly suppresses the declaration.
        //
        // Line 0: <?php
        // Line 1: interface I {
        // Line 2:     public function add(): void;   ← declaration — must be absent
        // Line 3: }
        // Line 4: $obj->add();                        ← call site — must be present
        let src = "<?php\ninterface I {\n    public function add(): void;\n}\n$obj->add();";
        let docs = vec![doc("/a.php", src)];

        let refs = find_references("add", &docs, false, None);
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            !lines.contains(&2),
            "interface method declaration (line 2) must be excluded with kind=None + include_declaration=false, got: {:?}",
            lines
        );
        assert!(
            lines.contains(&4),
            "call site (line 4) must be present, got: {:?}",
            lines
        );
    }

    #[test]
    fn function_kind_does_not_include_interface_method_declaration() {
        // kind=Function must not return interface method declarations. The existing
        // function_kind_with_include_declaration_does_not_return_method_call test
        // covers class methods; this covers the interface case specifically.
        //
        // Line 0: <?php
        // Line 1: function add() {}              ← free function declaration
        // Line 2: add();                         ← free function call
        // Line 3: interface I {
        // Line 4:     public function add(): void;  ← interface method — must be absent
        // Line 5: }
        let src =
            "<?php\nfunction add() {}\nadd();\ninterface I {\n    public function add(): void;\n}";
        let docs = vec![doc("/a.php", src)];

        let refs = find_references("add", &docs, true, Some(SymbolKind::Function));
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&1),
            "free function declaration (line 1) must be present, got: {:?}",
            lines
        );
        assert!(
            lines.contains(&2),
            "free function call (line 2) must be present, got: {:?}",
            lines
        );
        assert!(
            !lines.contains(&4),
            "interface method declaration (line 4) must not appear with kind=Function, got: {:?}",
            lines
        );
    }

    // ── switch / throw / unset / property-default coverage ──────────────────

    #[test]
    fn finds_function_call_inside_switch_case() {
        // Line 1: function tick() {}
        // Line 2: switch ($x) { case 1: tick(); break; }
        let src = "<?php\nfunction tick() {}\nswitch ($x) {\n    case 1: tick(); break;\n}";
        let docs = vec![doc("/a.php", src)];
        let lines: Vec<u32> = find_references("tick", &docs, false, Some(SymbolKind::Function))
            .iter()
            .map(|r| r.range.start.line)
            .collect();
        assert!(
            lines.contains(&3),
            "tick() call inside switch case (line 3) must be present, got: {:?}",
            lines
        );
    }

    #[test]
    fn finds_method_call_inside_switch_case() {
        // Line 1: switch ($x) { case 1: $obj->process(); break; }
        let src = "<?php\nswitch ($x) {\n    case 1: $obj->process(); break;\n}";
        let docs = vec![doc("/a.php", src)];
        let lines: Vec<u32> = find_references("process", &docs, false, Some(SymbolKind::Method))
            .iter()
            .map(|r| r.range.start.line)
            .collect();
        assert!(
            lines.contains(&2),
            "process() call inside switch case (line 2) must be present, got: {:?}",
            lines
        );
    }

    #[test]
    fn finds_function_call_inside_switch_condition() {
        // Line 1: function classify() {}
        // Line 2: switch (classify()) { default: break; }
        let src = "<?php\nfunction classify() {}\nswitch (classify()) { default: break; }";
        let docs = vec![doc("/a.php", src)];
        let lines: Vec<u32> = find_references("classify", &docs, false, Some(SymbolKind::Function))
            .iter()
            .map(|r| r.range.start.line)
            .collect();
        assert!(
            lines.contains(&2),
            "classify() in switch subject (line 2) must be present, got: {:?}",
            lines
        );
    }

    #[test]
    fn finds_function_call_inside_throw() {
        // Line 1: function makeException() {}
        // Line 2: throw makeException();
        let src = "<?php\nfunction makeException() {}\nthrow makeException();";
        let docs = vec![doc("/a.php", src)];
        let lines: Vec<u32> =
            find_references("makeException", &docs, false, Some(SymbolKind::Function))
                .iter()
                .map(|r| r.range.start.line)
                .collect();
        assert!(
            lines.contains(&2),
            "makeException() inside throw (line 2) must be present, got: {:?}",
            lines
        );
    }

    #[test]
    fn finds_method_call_inside_throw() {
        // Line 1: throw $factory->create();
        let src = "<?php\nthrow $factory->create();";
        let docs = vec![doc("/a.php", src)];
        let lines: Vec<u32> = find_references("create", &docs, false, Some(SymbolKind::Method))
            .iter()
            .map(|r| r.range.start.line)
            .collect();
        assert!(
            lines.contains(&1),
            "create() inside throw (line 1) must be present, got: {:?}",
            lines
        );
    }

    #[test]
    fn finds_method_call_inside_unset() {
        // Line 1: unset($obj->getProp());
        let src = "<?php\nunset($obj->getProp());";
        let docs = vec![doc("/a.php", src)];
        let lines: Vec<u32> = find_references("getProp", &docs, false, Some(SymbolKind::Method))
            .iter()
            .map(|r| r.range.start.line)
            .collect();
        assert!(
            lines.contains(&1),
            "getProp() inside unset (line 1) must be present, got: {:?}",
            lines
        );
    }

    #[test]
    fn finds_static_method_call_in_class_property_default() {
        // Line 1: class Config {
        // Line 2:     public array $data = self::defaults();
        // Line 3:     public static function defaults(): array { return []; }
        // Line 4: }
        let src = "<?php\nclass Config {\n    public array $data = self::defaults();\n    public static function defaults(): array { return []; }\n}";
        let docs = vec![doc("/a.php", src)];
        let lines: Vec<u32> = find_references("defaults", &docs, false, Some(SymbolKind::Method))
            .iter()
            .map(|r| r.range.start.line)
            .collect();
        assert!(
            lines.contains(&2),
            "defaults() in class property default (line 2) must be present, got: {:?}",
            lines
        );
    }

    #[test]
    fn finds_static_method_call_in_trait_property_default() {
        // Line 1: trait T {
        // Line 2:     public int $x = self::init();
        // Line 3:     public static function init(): int { return 0; }
        // Line 4: }
        let src = "<?php\ntrait T {\n    public int $x = self::init();\n    public static function init(): int { return 0; }\n}";
        let docs = vec![doc("/a.php", src)];
        let lines: Vec<u32> = find_references("init", &docs, false, Some(SymbolKind::Method))
            .iter()
            .map(|r| r.range.start.line)
            .collect();
        assert!(
            lines.contains(&2),
            "init() in trait property default (line 2) must be present, got: {:?}",
            lines
        );
    }

    // ── SymbolKind::Property ─────────────────────────────────────────────────

    #[test]
    fn property_kind_finds_instance_property_access() {
        // $obj->status should be found; free function `status()` must not appear.
        let src = "<?php\nclass Order {\n    public string $status = '';\n}\nfunction status() {}\n$o->status;\nstatus();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("status", &docs, false, Some(SymbolKind::Property));
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&5),
            "$o->status access (line 5) must be present, got: {:?}",
            lines
        );
        assert!(
            !lines.contains(&6),
            "free function call status() (line 6) must not appear with kind=Property, got: {:?}",
            lines
        );
    }

    #[test]
    fn property_kind_with_include_declaration_finds_decl() {
        // include_declaration=true must return the property declaration on the class body.
        let src = "<?php\nclass Foo {\n    public int $count = 0;\n}\n$f->count;\n$f->count;";
        let docs = vec![doc("/a.php", src)];
        let refs_with = find_references("count", &docs, true, Some(SymbolKind::Property));
        let lines_with: Vec<u32> = refs_with.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines_with.contains(&2),
            "property declaration (line 2) must be included with include_declaration=true, got: {:?}",
            lines_with
        );
        assert!(
            lines_with.contains(&4),
            "first access (line 4) must be included, got: {:?}",
            lines_with
        );
        assert!(
            lines_with.contains(&5),
            "second access (line 5) must be included, got: {:?}",
            lines_with
        );
    }

    #[test]
    fn property_kind_excludes_declaration_when_flag_false() {
        // include_declaration=false must suppress the property declaration but keep accesses.
        let src = "<?php\nclass Foo {\n    public int $count = 0;\n}\n$f->count;";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("count", &docs, false, Some(SymbolKind::Property));
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            !lines.contains(&2),
            "property declaration (line 2) must be excluded when include_declaration=false, got: {:?}",
            lines
        );
        assert!(
            lines.contains(&4),
            "access (line 4) must be included, got: {:?}",
            lines
        );
    }

    #[test]
    fn property_kind_does_not_match_method_with_same_name() {
        // $obj->run is a property access; $obj->run() is a method call.
        // kind=Property must not return the method call.
        let src = "<?php\nclass Task {\n    public bool $run = false;\n    public function run(): void {}\n}\n$t->run;\n$t->run();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("run", &docs, false, Some(SymbolKind::Property));
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&5),
            "property access $t->run (line 5) must be present, got: {:?}",
            lines
        );
        // The method call $t->run() on line 6 is an ExprKind::MethodCall, not PropertyAccess,
        // so the property walker must not emit it.
        assert!(
            !lines.contains(&6),
            "method call $t->run() (line 6) must not appear with kind=Property, got: {:?}",
            lines
        );
    }

    // ── Static method call ────────────────────────────────────────────────────

    #[test]
    fn method_kind_finds_static_method_call() {
        // ClassName::method() is a StaticMethodCall; the method walker must capture it.
        let src = "<?php\nclass Builder {\n    public static function create(): self { return new self(); }\n}\nBuilder::create();\n$b->create();";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references("create", &docs, false, Some(SymbolKind::Method));
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&4),
            "Builder::create() static call (line 4) must be present, got: {:?}",
            lines
        );
        assert!(
            lines.contains(&5),
            "$b->create() instance call (line 5) must be present, got: {:?}",
            lines
        );
    }

    // ── find_references_with_target namespace filtering ───────────────────────

    #[test]
    fn find_references_with_target_includes_file_whose_namespace_resolves_to_target() {
        // file_a.php is in namespace Alpha — calling `Widget` resolves to `Alpha\Widget`.
        // find_references_with_target with target `Alpha\Widget` must include it.
        let src_a = "<?php\nnamespace Alpha;\nfunction make(): void { $w = new Widget(); }";
        let docs = vec![doc("/a.php", src_a)];
        let refs = find_references_with_target(
            "Widget",
            &docs,
            false,
            Some(SymbolKind::Class),
            "Alpha\\Widget",
        );
        let lines: Vec<u32> = refs.iter().map(|r| r.range.start.line).collect();
        assert!(
            lines.contains(&2),
            "new Widget() in Alpha namespace (line 2) must be included, got: {:?}",
            lines
        );
    }

    #[test]
    fn find_references_with_target_excludes_file_with_different_namespace() {
        // file_b.php is in namespace Beta — `Widget` there resolves to `Beta\Widget`,
        // so it must be excluded when the target is `Alpha\Widget`.
        let src_a = "<?php\nnamespace Alpha;\n$w = new Widget();";
        let src_b = "<?php\nnamespace Beta;\n$w = new Widget();";
        let docs = vec![doc("/a.php", src_a), doc("/b.php", src_b)];
        let refs = find_references_with_target(
            "Widget",
            &docs,
            false,
            Some(SymbolKind::Class),
            "Alpha\\Widget",
        );
        let uris: Vec<&str> = refs.iter().map(|r| r.uri.as_str()).collect();
        assert!(
            uris.iter().any(|u| u.ends_with("/a.php")),
            "Alpha\\Widget in a.php must be included, got: {:?}",
            refs
        );
        assert!(
            !uris.iter().any(|u| u.ends_with("/b.php")),
            "Beta\\Widget in b.php must be excluded, got: {:?}",
            refs
        );
    }

    #[test]
    fn find_references_with_target_global_function_fallback() {
        // A file with no namespace calls `strlen` — PHP falls back to the global
        // namespace, so the target `strlen` (no backslash) must match.
        let src = "<?php\n$n = strlen('hello');";
        let docs = vec![doc("/a.php", src)];
        let refs = find_references_with_target(
            "strlen",
            &docs,
            false,
            Some(SymbolKind::Function),
            "strlen",
        );
        assert!(
            !refs.is_empty(),
            "strlen() in global-namespace file must be included, got: {:?}",
            refs
        );
    }
}