php_lsp/types/

type_map.rs

/// Single-pass type inference: collects `$var = new ClassName()` assignments,
/// `@var` docblocks, `@param` hints, and PHPStorm meta factory calls to map
/// variable names to class names. Used to scope method completions after `->`.
use std::collections::HashMap;

use php_ast::{
    ClassMemberKind, EnumMemberKind, ExprKind, NamespaceBody, Stmt, StmtKind, TypeHint,
    TypeHintKind,
};
use tower_lsp::lsp_types::Position;

use crate::document::ast::{ParsedDoc, SourceView};
use crate::lang::docblock::{docblock_before, parse_docblock};
use crate::lang::phpstorm_meta::PhpStormMeta;
use crate::text::fqn_short_name;

/// Maps variable name (with `$`) → class name.
#[derive(Debug, Default, Clone)]
pub struct TypeMap(HashMap<String, String>);

impl TypeMap {
    #[cfg(test)]
    pub fn from_doc(doc: &ParsedDoc) -> Self {
        Self::from_doc_with_meta(doc, None)
    }

    /// Build from a parsed document, optionally enriched by PHPStorm metadata
    /// for factory-method return type inference.
    pub fn from_doc_with_meta(doc: &ParsedDoc, meta: Option<&PhpStormMeta>) -> Self {
        let mut map = HashMap::new();
        collect_types_stmts(
            doc.source(),
            &doc.program().stmts,
            &mut map,
            meta,
            None,
            doc,
        );
        let aliases = collect_file_type_aliases(doc.source(), &doc.program().stmts);
        expand_type_aliases(&mut map, &aliases);
        TypeMap(map)
    }

    /// Like [`from_doc_with_meta`] but scopes method-body variable collection
    /// to the method (or function) containing `position`. Variables local to
    /// other method bodies are excluded so they cannot pollute the map with
    /// wrong types at the cursor site. Sets `$this` when the position is inside
    /// an instance method.
    pub fn from_doc_at_position(
        doc: &ParsedDoc,
        meta: Option<&PhpStormMeta>,
        position: Position,
    ) -> Self {
        let cursor_byte = {
            let line_starts = doc.line_starts();
            let line = position.line as usize;
            if line < line_starts.len() {
                let line_start = line_starts[line] as usize;
                let col_byte = crate::text::utf16_offset_to_byte(
                    &doc.source()[line_start..],
                    position.character as usize,
                );
                Some((line_start + col_byte) as u32)
            } else {
                None
            }
        };
        let mut map = HashMap::new();
        collect_types_stmts(
            doc.source(),
            &doc.program().stmts,
            &mut map,
            meta,
            cursor_byte,
            doc,
        );
        let aliases = collect_file_type_aliases(doc.source(), &doc.program().stmts);
        expand_type_aliases(&mut map, &aliases);
        TypeMap(map)
    }

    /// Returns the class name for a variable, e.g. `get("$obj")` → `Some("Foo")`.
    pub fn get<'a>(&'a self, var: &str) -> Option<&'a str> {
        self.0.get(var).map(|s| s.as_str())
    }
}

/// Extract a class-name string from a type hint using mir's type resolver.
/// - `Named(Foo)` → `"Foo"`, `Named(\App\Foo)` → `"Foo"` (short name)
/// - `Nullable(Named(Foo))` → `"Foo"` (strips the nullable wrapper)
/// - `Union([Named(Foo), Named(Bar)])` → `"Foo|Bar"`
/// - `Intersection([Foo, Bar])` → `"Foo|Bar"` (flattened; `type_candidates()` splits on both `|` and `&`)
/// - `self` / `static` with `enclosing` → returns the enclosing short name
/// - Primitives and unrecognised kinds → `None`
fn type_hint_to_class_string(
    hint: &TypeHint<'_, '_>,
    enclosing_class: Option<&str>,
    doc: Option<&ParsedDoc>,
) -> Option<String> {
    use mir_types::Atomic;
    let union = mir_analyzer::parser::type_from_hint(hint, enclosing_class);
    let classes: Vec<String> = union
        .types
        .iter()
        .filter_map(|a| match a {
            Atomic::TNamedObject { fqcn, .. }
            | Atomic::TSelf { fqcn }
            | Atomic::TStaticObject { fqcn } => {
                let short = fqn_short_name(fqcn);
                Some(short.to_string())
            }
            Atomic::TParent { fqcn } => {
                if let (Some(doc), Some(enc_class)) = (doc, enclosing_class) {
                    if let Some(parent) = parent_class_name(doc, enc_class) {
                        let short = fqn_short_name(&parent);
                        Some(short.to_string())
                    } else {
                        let short = fqn_short_name(fqcn);
                        Some(short.to_string())
                    }
                } else {
                    let short = fqn_short_name(fqcn);
                    Some(short.to_string())
                }
            }
            Atomic::TIntersection { parts } => {
                let intersection_classes: Vec<String> = parts
                    .iter()
                    .flat_map(|part| {
                        part.types.iter().filter_map(|a| match a {
                            Atomic::TNamedObject { fqcn, .. }
                            | Atomic::TSelf { fqcn }
                            | Atomic::TStaticObject { fqcn } => {
                                let short = fqn_short_name(fqcn);
                                Some(short.to_string())
                            }
                            Atomic::TParent { fqcn } => {
                                if let (Some(doc), Some(enc_class)) = (doc, enclosing_class) {
                                    if let Some(parent) = parent_class_name(doc, enc_class) {
                                        let short = fqn_short_name(&parent);
                                        Some(short.to_string())
                                    } else {
                                        let short =
                                            fqcn.rsplit('\\').next().unwrap_or(fqcn.as_ref());
                                        Some(short.to_string())
                                    }
                                } else {
                                    let short = fqn_short_name(fqcn);
                                    Some(short.to_string())
                                }
                            }
                            _ => None,
                        })
                    })
                    .collect();
                if intersection_classes.is_empty() {
                    None
                } else {
                    Some(intersection_classes.join("|"))
                }
            }
            _ => None,
        })
        .collect();
    if classes.is_empty() {
        None
    } else {
        Some(classes.join("|"))
    }
}

/// Extract class names from a docblock type hint, in declaration order.
///
/// Splits a union (`Foo|Bar|null`), trims a leading `\` and nullable `?`, and
/// reduces each class part to its short name (`A\B\Foo` → `Foo`).
///
/// Generic parameters on *user-defined* class names are stripped so the result
/// is a bare FQCN suitable for member lookups (`Collection<User>` → `Collection`).
///
/// PHP built-in iterable types whose sole purpose is to carry an element type
/// (`list<T>`, `array<K,V>`, `iterable<K,V>`, `non-empty-list<T>`,
/// `non-empty-array<K,V>`) are unwrapped and their element-type class names are
/// returned instead — this enables the TypeMap fallback to propagate element
/// types through `foreach` loops when the mir-primary path is unavailable.
fn docblock_class_parts(type_hint: &str) -> Vec<String> {
    type_hint
        .split('|')
        .flat_map(|p| {
            let p = p.trim().trim_start_matches('\\').trim_start_matches('?');
            // PHP built-in iterable types: extract element class from the generic param.
            if let Some(elem) = php_iterable_element_type(p) {
                return docblock_class_parts(elem);
            }
            // User-defined class (starts uppercase): strip any generic params.
            if p.chars().next().map(|c| c.is_uppercase()).unwrap_or(false) {
                let base = p.split_once('<').map(|(b, _)| b).unwrap_or(p);
                if let Some(short) = base.rsplit('\\').next() {
                    return vec![short.to_string()];
                }
            }
            vec![]
        })
        .collect()
}

/// If `ty` is one of the PHP built-in iterable types with a generic element
/// (`list<T>`, `array<K,V>`, `iterable<K,V>`, `non-empty-list<T>`,
/// `non-empty-array<K,V>`), returns the element-type substring; otherwise `None`.
fn php_iterable_element_type(ty: &str) -> Option<&str> {
    let base = ty.split_once('<').map(|(b, _)| b).unwrap_or(ty);
    if !matches!(
        base,
        "list" | "array" | "iterable" | "non-empty-list" | "non-empty-array"
    ) {
        return None;
    }
    let inner = ty.split_once('<')?.1.strip_suffix('>')?;
    // array<K,V> / iterable<K,V>: element type is the last generic argument.
    Some(if let Some((_, last)) = inner.rsplit_once(',') {
        last.trim()
    } else {
        inner.trim()
    })
}

/// Collect `@psalm-type` / `@phpstan-type` aliases from all statement-level
/// docblocks in `stmts`.  Aliases declared in a class docblock (the docblock
/// immediately before the `class` keyword) are the most common case.
fn collect_file_type_aliases(source: &str, stmts: &[Stmt<'_, '_>]) -> HashMap<String, String> {
    let mut aliases = HashMap::new();
    collect_aliases_in_stmts(source, stmts, &mut aliases);
    aliases
}

fn collect_aliases_in_stmts(
    source: &str,
    stmts: &[Stmt<'_, '_>],
    aliases: &mut HashMap<String, String>,
) {
    for stmt in stmts {
        if let Some(raw) = docblock_before(source, stmt.span.start) {
            let db = parse_docblock(&raw);
            for ta in &db.type_aliases {
                aliases.insert(ta.name.clone(), ta.type_expr.clone());
            }
        }
        if let StmtKind::Namespace(ns) = &stmt.kind
            && let NamespaceBody::Braced(inner) = &ns.body
        {
            collect_aliases_in_stmts(source, &inner.stmts, aliases);
        }
    }
}

/// Post-process `map` by expanding any value that is a known alias name.
///
/// `@psalm-type Result = Success|Failure` → variables mapped to `"Result"` are
/// updated to `"Success|Failure"` so member lookups find the actual classes.
/// Only one level of expansion is performed (no recursive alias resolution).
fn expand_type_aliases(map: &mut HashMap<String, String>, aliases: &HashMap<String, String>) {
    if aliases.is_empty() {
        return;
    }
    for value in map.values_mut() {
        if let Some(expanded_expr) = aliases.get(value.as_str()) {
            let expanded_classes = docblock_class_parts(expanded_expr);
            if !expanded_classes.is_empty() {
                *value = expanded_classes.join("|");
            }
        }
    }
}

/// Apply `@param` class-type hints from the docblock preceding `span_start` to
/// `map`, keyed by `$name`. Uses `or_insert` so real signature type hints
/// (collected separately) take precedence.
fn collect_param_docblock_types(source: &str, span_start: u32, map: &mut HashMap<String, String>) {
    let Some(raw) = docblock_before(source, span_start) else {
        return;
    };
    let db = parse_docblock(&raw);
    for param in &db.params {
        let classes = docblock_class_parts(&param.type_hint);
        if classes.is_empty() {
            continue;
        }
        let key = if param.name.starts_with('$') {
            param.name.clone()
        } else {
            format!("${}", param.name)
        };
        map.entry(key).or_insert_with(|| classes.join("|"));
    }
}

#[allow(clippy::too_many_arguments)]
fn collect_types_stmts(
    source: &str,
    stmts: &[Stmt<'_, '_>],
    map: &mut HashMap<String, String>,
    meta: Option<&PhpStormMeta>,
    cursor_byte: Option<u32>,
    doc: &ParsedDoc,
) {
    for stmt in stmts {
        if let Some(raw) = docblock_before(source, stmt.span.start) {
            let db = parse_docblock(&raw);
            if let Some(type_str) = db.var_type {
                let class_name = docblock_class_parts(&type_str).into_iter().next();
                if let Some(class_name) = class_name {
                    if let Some(vname) = db.var_name {
                        map.insert(format!("${}", vname.as_str()), class_name);
                    } else if let StmtKind::Expression(e) = &stmt.kind
                        && let ExprKind::Assign(a) = &e.kind
                        && let ExprKind::Variable(vn) = &a.target.kind
                    {
                        map.insert(format!("${}", vn.as_str()), class_name);
                    }
                }
            }
        }

        match &stmt.kind {
            StmtKind::Expression(e) => collect_types_expr(source, e, map, meta, cursor_byte, doc),
            StmtKind::Function(f) => {
                let in_scope =
                    cursor_byte.is_none_or(|c| stmt.span.start <= c && c <= stmt.span.end);
                if !in_scope {
                    continue;
                }
                collect_param_docblock_types(source, stmt.span.start, map);
                for p in f.params.iter() {
                    if let Some(hint) = &p.type_hint
                        && let Some(class_str) = type_hint_to_class_string(hint, None, Some(doc))
                    {
                        map.insert(format!("${}", p.name), class_str);
                    }
                }
                collect_types_stmts(source, &f.body.stmts, map, meta, cursor_byte, doc);
            }
            StmtKind::Class(c) => {
                let class_name = c.name.map(|n| n.to_string());
                for member in c.body.members.iter() {
                    if let ClassMemberKind::Method(m) = &member.kind {
                        let in_scope = cursor_byte
                            .is_none_or(|cb| member.span.start <= cb && cb <= member.span.end);
                        if !in_scope {
                            continue;
                        }
                        collect_param_docblock_types(source, member.span.start, map);
                        for p in m.params.iter() {
                            if let Some(hint) = &p.type_hint
                                && let Some(class_str) = type_hint_to_class_string(
                                    hint,
                                    class_name.as_deref(),
                                    Some(doc),
                                )
                            {
                                map.insert(format!("${}", p.name), class_str);
                            }
                        }
                        if !m.is_static
                            && let Some(ref cname) = class_name
                        {
                            map.insert("$this".to_string(), cname.clone());
                        }
                        if let Some(body) = &m.body {
                            collect_types_stmts(source, &body.stmts, map, meta, cursor_byte, doc);
                        }
                    }
                }
            }
            StmtKind::Trait(t) => {
                for member in t.body.members.iter() {
                    if let ClassMemberKind::Method(m) = &member.kind {
                        let in_scope = cursor_byte
                            .is_none_or(|cb| member.span.start <= cb && cb <= member.span.end);
                        if !in_scope {
                            continue;
                        }
                        for p in m.params.iter() {
                            if let Some(hint) = &p.type_hint
                                && let Some(class_str) =
                                    type_hint_to_class_string(hint, None, Some(doc))
                            {
                                map.insert(format!("${}", p.name), class_str);
                            }
                        }
                        if let Some(body) = &m.body {
                            collect_types_stmts(source, &body.stmts, map, meta, cursor_byte, doc);
                        }
                    }
                }
            }
            StmtKind::Enum(e) => {
                for member in e.body.members.iter() {
                    if let EnumMemberKind::Method(m) = &member.kind {
                        let in_scope = cursor_byte
                            .is_none_or(|cb| member.span.start <= cb && cb <= member.span.end);
                        if !in_scope {
                            continue;
                        }
                        for p in m.params.iter() {
                            if let Some(hint) = &p.type_hint
                                && let Some(class_str) =
                                    type_hint_to_class_string(hint, None, Some(doc))
                            {
                                map.insert(format!("${}", p.name), class_str);
                            }
                        }
                        if let Some(body) = &m.body {
                            collect_types_stmts(source, &body.stmts, map, meta, cursor_byte, doc);
                        }
                    }
                }
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body {
                    collect_types_stmts(source, &inner.stmts, map, meta, cursor_byte, doc);
                }
            }
            // `instanceof` narrowing is handled by mir's flow-sensitive analysis; we only recurse into the branches.
            StmtKind::If(if_stmt) => {
                collect_types_stmts(
                    source,
                    std::slice::from_ref(if_stmt.then_branch),
                    map,
                    meta,
                    cursor_byte,
                    doc,
                );
                for elseif in if_stmt.elseif_branches.iter() {
                    collect_types_stmts(
                        source,
                        std::slice::from_ref(&elseif.body),
                        map,
                        meta,
                        cursor_byte,
                        doc,
                    );
                }
                if let Some(else_branch) = if_stmt.else_branch {
                    collect_types_stmts(
                        source,
                        std::slice::from_ref(else_branch),
                        map,
                        meta,
                        cursor_byte,
                        doc,
                    );
                }
            }

            StmtKind::Foreach(f) => {
                // Propagate element type: if the iterable is a variable with a
                // known TypeMap type (e.g. from `@var list<Widget> $items`), map
                // the foreach value variable to that same type so completions
                // work inside the loop body in the TypeMap fallback path.
                if let ExprKind::Variable(arr_name) = &f.expr.kind
                    && let ExprKind::Variable(val_name) = &f.value.kind
                {
                    let arr_key = format!("${}", arr_name.as_str());
                    if let Some(elem_type) = map.get(&arr_key).cloned() {
                        map.entry(format!("${}", val_name.as_str()))
                            .or_insert(elem_type);
                    }
                }
                collect_types_stmts(
                    source,
                    std::slice::from_ref(f.body),
                    map,
                    meta,
                    cursor_byte,
                    doc,
                );
            }
            StmtKind::TryCatch(t) => {
                collect_types_stmts(source, &t.body.stmts, map, meta, cursor_byte, doc);
                for catch in t.catches.iter() {
                    collect_types_stmts(source, &catch.body.stmts, map, meta, cursor_byte, doc);
                }
                if let Some(finally) = &t.finally {
                    collect_types_stmts(source, &finally.stmts, map, meta, cursor_byte, doc);
                }
            }

            StmtKind::StaticVar(vars) => {
                for var in vars.iter() {
                    let var_key = format!("${}", &var.name.to_string());
                    if let Some(default) = &var.default {
                        if let ExprKind::New(new_expr) = &default.kind
                            && let Some(class_name) = extract_class_name(new_expr.class)
                        {
                            map.insert(var_key.clone(), class_name);
                        }
                        if let ExprKind::Array(_) = &default.kind {
                            map.insert(var_key, "array".to_string());
                        }
                    }
                }
            }

            _ => {}
        }
    }
}

fn collect_types_expr(
    source: &str,
    expr: &php_ast::Expr<'_, '_>,
    map: &mut HashMap<String, String>,
    meta: Option<&PhpStormMeta>,
    cursor_byte: Option<u32>,
    doc: &ParsedDoc,
) {
    match &expr.kind {
        ExprKind::Assign(assign) => {
            if let ExprKind::Variable(var_name) = &assign.target.kind {
                if let ExprKind::New(new_expr) = &assign.value.kind
                    && let Some(class_name) = extract_class_name(new_expr.class)
                {
                    map.insert(format!("${}", var_name.as_str()), class_name);
                }
                // `clone($obj, [...])` (PHP 8.5 clone-with) preserves the object's
                // type; mir resolves this directly, so no TypeMap branch is needed.
                // PHPStorm meta: `$var = $obj->make(SomeClass::class)`
                if let Some(meta) = meta
                    && let Some(inferred) = infer_from_meta_method_call(assign.value, map, meta)
                {
                    map.insert(format!("${}", var_name.as_str()), inferred);
                }
                // First-class callable syntax (`strlen(...)`, `$obj->method(...)`)
                // produces a `Closure` instance (PHP 8.1+).  Register the variable
                // as Closure so hover and member-completion recognise it.
                if let ExprKind::CallableCreate(_) = &assign.value.kind {
                    map.entry(format!("${}", var_name.as_str()))
                        .or_insert_with(|| "Closure".to_string());
                }
            }
            collect_types_expr(source, assign.value, map, meta, cursor_byte, doc);
        }

        ExprKind::Closure(c) => {
            for p in c.params.iter() {
                if let Some(hint) = &p.type_hint
                    && let TypeHintKind::Named(name) = &hint.kind
                {
                    map.insert(format!("${}", p.name), name.to_string_repr().to_string());
                }
            }
            // Snapshot captured `use` variable types from the outer scope so they
            // remain resolvable inside the closure body even if the body walk
            // encounters assignments that would shadow them.
            let use_var_snapshot: Vec<(String, String)> = c
                .use_vars
                .iter()
                .filter_map(|uv| {
                    let key = format!("${}", &uv.name.to_string());
                    map.get(&key).map(|ty| (key, ty.clone()))
                })
                .collect();
            collect_types_stmts(source, &c.body.stmts, map, meta, cursor_byte, doc);
            // Restore captured variable types: inner assignments inside the closure
            // body should not affect the outer scope's type for completions.
            for (key, ty) in use_var_snapshot {
                map.insert(key, ty);
            }
        }

        ExprKind::ArrowFunction(af) => {
            for p in af.params.iter() {
                if let Some(hint) = &p.type_hint
                    && let TypeHintKind::Named(name) = &hint.kind
                {
                    map.insert(format!("${}", p.name), name.to_string_repr().to_string());
                }
            }
            collect_types_expr(source, af.body, map, meta, cursor_byte, doc);
        }

        _ => {}
    }
}

fn extract_class_name(expr: &php_ast::Expr<'_, '_>) -> Option<String> {
    match &expr.kind {
        ExprKind::Identifier(name) => Some(name.as_str().to_string()),
        _ => None,
    }
}

/// Try to infer the return type of `$obj->method(SomeClass::class)` using the
/// PHPStorm meta map.  `map` is consulted to resolve `$obj`'s class.
fn infer_from_meta_method_call(
    expr: &php_ast::Expr<'_, '_>,
    var_map: &HashMap<String, String>,
    meta: &PhpStormMeta,
) -> Option<String> {
    let ExprKind::MethodCall(m) = &expr.kind else {
        return None;
    };
    // Resolve the receiver's type.
    let receiver_class = match &m.object.kind {
        ExprKind::Variable(v) => {
            let key = format!("${}", v.as_str());
            var_map.get(&key)?.clone()
        }
        _ => return None,
    };
    // Get the method name.
    let method_name = match &m.method.kind {
        ExprKind::Identifier(n) => n.to_string(),
        _ => return None,
    };
    // Get the first argument as a class name string.
    let arg = m.args.first()?;
    let arg_str = match &arg.value.kind {
        ExprKind::String(s) => s.trim_start_matches('\\').to_string(),
        ExprKind::ClassConstAccess(c) if c.member.name_str() == Some("class") => {
            match &c.class.kind {
                ExprKind::Identifier(n) => n
                    .trim_start_matches('\\')
                    .rsplit('\\')
                    .next()
                    .unwrap_or(n)
                    .to_string(),
                _ => return None,
            }
        }
        _ => return None,
    };
    meta.resolve_return_type(&receiver_class, &method_name, &arg_str)
        .map(|s| s.to_string())
}

/// Return the direct parent class name of `class_name` in `doc`, if any.
pub fn parent_class_name(doc: &ParsedDoc, class_name: &str) -> Option<String> {
    parent_in_stmts(&doc.program().stmts, class_name)
}

fn parent_in_stmts(stmts: &[Stmt<'_, '_>], class_name: &str) -> Option<String> {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Class(c)
                if c.name.as_ref().map(|n| n.to_string()) == Some(class_name.to_string()) =>
            {
                return c.extends.as_ref().map(|n| n.to_string_repr().to_string());
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body
                    && let found @ Some(_) = parent_in_stmts(&inner.stmts, class_name)
                {
                    return found;
                }
            }
            _ => {}
        }
    }
    None
}

/// All members of a named class split by kind and static-ness.
#[derive(Debug, Default)]
pub struct ClassMembers {
    /// (name, is_static, has_params)
    pub methods: Vec<(String, bool, bool)>,
    /// (name, is_static)
    pub properties: Vec<(String, bool)>,
    /// Names of readonly properties (PHP 8.1+).
    pub readonly_properties: Vec<String>,
    pub constants: Vec<String>,
    /// Direct parent class name, if any.
    pub parent: Option<String>,
    /// Trait names used by this class (`use Foo, Bar;`).
    pub trait_uses: Vec<String>,
    /// True when a class/enum/trait with this name was found in the doc.
    /// Lets workspace-wide loops short-circuit once the defining doc is hit
    /// instead of continuing to scan every file.
    pub found: bool,
}

/// Return all members (methods, properties, constants) of `class_name`.
/// Also returns the direct parent class name via `ClassMembers::parent`.
pub fn members_of_class(doc: &ParsedDoc, class_name: &str) -> ClassMembers {
    let mut out = ClassMembers::default();
    out.parent = collect_members_stmts(doc.source(), &doc.program().stmts, class_name, &mut out);
    out
}

fn collect_members_stmts(
    source: &str,
    stmts: &[Stmt<'_, '_>],
    class_name: &str,
    out: &mut ClassMembers,
) -> Option<String> {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Class(c)
                if c.name.as_ref().map(|n| n.to_string()) == Some(class_name.to_string()) =>
            {
                out.found = true;
                // Check docblock for @property and @method tags
                if let Some(raw) = docblock_before(source, stmt.span.start) {
                    let db = parse_docblock(&raw);
                    for prop in &db.properties {
                        out.properties.push((prop.name.clone(), false));
                    }
                    for method in &db.methods {
                        out.methods.push((
                            method.name.clone(),
                            method.is_static,
                            !method.params.is_empty(),
                        ));
                    }
                }
                for member in c.body.members.iter() {
                    match &member.kind {
                        ClassMemberKind::Method(m) => {
                            out.methods.push((
                                m.name.to_string(),
                                m.is_static,
                                !m.params.is_empty(),
                            ));
                            if m.name == "__construct" {
                                for p in m.params.iter() {
                                    if p.visibility.is_some() {
                                        out.properties.push((p.name.to_string(), false));
                                        // AST does not expose the `readonly` flag on Param; scan the raw span text.
                                        let param_src =
                                            &source[p.span.start as usize..p.span.end as usize];
                                        if param_src.contains("readonly") {
                                            out.readonly_properties.push(p.name.to_string());
                                        }
                                    }
                                }
                            }
                        }
                        ClassMemberKind::Property(p) => {
                            out.properties.push((p.name.to_string(), p.is_static));
                            if p.is_readonly {
                                out.readonly_properties.push(p.name.to_string());
                            }
                        }
                        ClassMemberKind::ClassConst(c) => {
                            out.constants.push(c.name.to_string());
                        }
                        ClassMemberKind::TraitUse(t) => {
                            for name in t.traits.iter() {
                                out.trait_uses.push(name.to_string_repr().to_string());
                            }
                        }
                    }
                }
                return c.extends.as_ref().map(|n| n.to_string_repr().to_string());
            }
            StmtKind::Enum(e) if e.name == class_name => {
                out.found = true;
                let is_backed = e.scalar_type.is_some();
                out.properties.push(("name".to_string(), false));
                if is_backed {
                    out.properties.push(("value".to_string(), false));
                }
                out.methods.push(("cases".to_string(), true, false));
                if is_backed {
                    out.methods.push(("from".to_string(), true, true));
                    out.methods.push(("tryFrom".to_string(), true, true));
                }
                for member in e.body.members.iter() {
                    match &member.kind {
                        EnumMemberKind::Case(c) => {
                            out.constants.push(c.name.to_string());
                        }
                        EnumMemberKind::Method(m) => {
                            out.methods.push((
                                m.name.to_string(),
                                m.is_static,
                                !m.params.is_empty(),
                            ));
                        }
                        EnumMemberKind::ClassConst(c) => {
                            out.constants.push(c.name.to_string());
                        }
                        _ => {}
                    }
                }
                return None; // enums have no parent class
            }
            StmtKind::Trait(t) if t.name == class_name => {
                out.found = true;
                for member in t.body.members.iter() {
                    match &member.kind {
                        ClassMemberKind::Method(m) => {
                            out.methods.push((
                                m.name.to_string(),
                                m.is_static,
                                !m.params.is_empty(),
                            ));
                        }
                        ClassMemberKind::Property(p) => {
                            out.properties.push((p.name.to_string(), p.is_static));
                        }
                        ClassMemberKind::ClassConst(c) => {
                            out.constants.push(c.name.to_string());
                        }
                        ClassMemberKind::TraitUse(t) => {
                            for name in t.traits.iter() {
                                out.trait_uses.push(name.to_string_repr().to_string());
                            }
                        }
                    }
                }
                return None; // traits have no parent
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body {
                    let result = collect_members_stmts(source, &inner.stmts, class_name, out);
                    if result.is_some() {
                        return result;
                    }
                }
            }
            _ => {}
        }
    }
    None
}

/// Return the `@mixin` class names declared in `class_name`'s docblock.
pub fn mixin_classes_of(doc: &ParsedDoc, class_name: &str) -> Vec<String> {
    let source = doc.source();
    mixin_classes_in_stmts(source, &doc.program().stmts, class_name)
}

fn mixin_classes_in_stmts(source: &str, stmts: &[Stmt<'_, '_>], class_name: &str) -> Vec<String> {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Class(c)
                if c.name.as_ref().map(|n| n.to_string()) == Some(class_name.to_string()) =>
            {
                if let Some(raw) = docblock_before(source, stmt.span.start) {
                    return parse_docblock(&raw).mixins;
                }
                return vec![];
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body {
                    let found = mixin_classes_in_stmts(source, &inner.stmts, class_name);
                    if !found.is_empty() {
                        return found;
                    }
                }
            }
            _ => {}
        }
    }
    vec![]
}

/// Return the name of the class whose body contains `position`, or `None`.
pub fn enclosing_class_at(_source: &str, doc: &ParsedDoc, position: Position) -> Option<String> {
    let sv = doc.view();
    enclosing_class_in_stmts(sv, &doc.program().stmts, position)
}

/// Like [`enclosing_class_at`] but returns the fully-qualified name
/// (`"Ns\\ClassName"`) when the class lives inside a namespace.
/// Used by the `__construct` call-site path so that `construct_references`
/// can apply namespace-level filtering and avoid matching a same-short-named
/// class in a different namespace.
pub fn enclosing_class_fqn_at(
    _source: &str,
    doc: &ParsedDoc,
    position: Position,
) -> Option<String> {
    let sv = doc.view();
    enclosing_class_fqn_in_stmts(sv, &doc.program().stmts, position, "")
}

fn enclosing_class_fqn_in_stmts(
    sv: SourceView<'_>,
    stmts: &[Stmt<'_, '_>],
    pos: Position,
    ns_prefix: &str,
) -> Option<String> {
    let make_fqn = |ns: &str, short: &str| -> String {
        if ns.is_empty() {
            short.to_owned()
        } else {
            format!("{}\\{}", ns, short)
        }
    };
    let mut current_ns = ns_prefix.to_owned();
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Class(c) => {
                let start = sv.position_of(stmt.span.start).line;
                let end = sv.position_of(stmt.span.end).line;
                if pos.line >= start && pos.line <= end {
                    return c.name.map(|n| make_fqn(&current_ns, &n.to_string()));
                }
            }
            StmtKind::Interface(i) => {
                let start = sv.position_of(stmt.span.start).line;
                let end = sv.position_of(stmt.span.end).line;
                if pos.line >= start && pos.line <= end {
                    return Some(make_fqn(&current_ns, &i.name.to_string()));
                }
            }
            StmtKind::Trait(t) => {
                let start = sv.position_of(stmt.span.start).line;
                let end = sv.position_of(stmt.span.end).line;
                if pos.line >= start && pos.line <= end {
                    return Some(make_fqn(&current_ns, &t.name.to_string()));
                }
            }
            StmtKind::Enum(e) => {
                let start = sv.position_of(stmt.span.start).line;
                let end = sv.position_of(stmt.span.end).line;
                if pos.line >= start && pos.line <= end {
                    return Some(make_fqn(&current_ns, &e.name.to_string()));
                }
            }
            StmtKind::Namespace(ns) => {
                let ns_name = ns
                    .name
                    .as_ref()
                    .map(|n| n.to_string_repr().to_string())
                    .unwrap_or_default();
                match &ns.body {
                    NamespaceBody::Braced(inner) => {
                        if let Some(found) =
                            enclosing_class_fqn_in_stmts(sv, &inner.stmts, pos, &ns_name)
                        {
                            return Some(found);
                        }
                    }
                    NamespaceBody::Simple => {
                        current_ns = ns_name;
                    }
                }
            }
            _ => {}
        }
    }
    None
}

/// Return the LSP range of the class/interface/trait/enum declaration
/// whose body contains `position`, or `None` if the cursor is outside any.
/// Used by linked-editing to scope same-name member rewrites to the
/// enclosing class instead of every class in the file.
pub fn enclosing_class_range_at(
    doc: &ParsedDoc,
    position: Position,
) -> Option<tower_lsp::lsp_types::Range> {
    let sv = doc.view();
    enclosing_class_range_in_stmts(sv, &doc.program().stmts, position)
}

/// Return the LSP range of every class/interface/trait/enum declaration in
/// the file (recursing into braced-namespace bodies). Used by linked-editing
/// to drop highlights that fall inside an *other* class than the cursor's.
pub fn collect_all_class_ranges(doc: &ParsedDoc) -> Vec<tower_lsp::lsp_types::Range> {
    let sv = doc.view();
    let mut out = Vec::new();
    collect_class_ranges_in_stmts(sv, &doc.program().stmts, &mut out);
    out
}

fn collect_class_ranges_in_stmts(
    sv: SourceView<'_>,
    stmts: &[Stmt<'_, '_>],
    out: &mut Vec<tower_lsp::lsp_types::Range>,
) {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Class(_)
            | StmtKind::Interface(_)
            | StmtKind::Trait(_)
            | StmtKind::Enum(_) => {
                out.push(sv.range_of(stmt.span));
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body {
                    collect_class_ranges_in_stmts(sv, &inner.stmts, out);
                }
            }
            _ => {}
        }
    }
}

fn enclosing_class_range_in_stmts(
    sv: SourceView<'_>,
    stmts: &[Stmt<'_, '_>],
    pos: Position,
) -> Option<tower_lsp::lsp_types::Range> {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Class(_)
            | StmtKind::Interface(_)
            | StmtKind::Trait(_)
            | StmtKind::Enum(_) => {
                let r = sv.range_of(stmt.span);
                if pos.line >= r.start.line && pos.line <= r.end.line {
                    return Some(r);
                }
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body
                    && let Some(r) = enclosing_class_range_in_stmts(sv, &inner.stmts, pos)
                {
                    return Some(r);
                }
            }
            _ => {}
        }
    }
    None
}

fn enclosing_class_in_stmts(
    sv: SourceView<'_>,
    stmts: &[Stmt<'_, '_>],
    pos: Position,
) -> Option<String> {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Class(c) => {
                let start = sv.position_of(stmt.span.start).line;
                let end = sv.position_of(stmt.span.end).line;
                if pos.line >= start && pos.line <= end {
                    return c.name.map(|n| n.to_string());
                }
            }
            StmtKind::Interface(i) => {
                let start = sv.position_of(stmt.span.start).line;
                let end = sv.position_of(stmt.span.end).line;
                if pos.line >= start && pos.line <= end {
                    return Some(i.name.to_string());
                }
            }
            StmtKind::Trait(t) => {
                let start = sv.position_of(stmt.span.start).line;
                let end = sv.position_of(stmt.span.end).line;
                if pos.line >= start && pos.line <= end {
                    return Some(t.name.to_string());
                }
            }
            StmtKind::Enum(e) => {
                let start = sv.position_of(stmt.span.start).line;
                let end = sv.position_of(stmt.span.end).line;
                if pos.line >= start && pos.line <= end {
                    return Some(e.name.to_string());
                }
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body
                    && let Some(found) = enclosing_class_in_stmts(sv, &inner.stmts, pos)
                {
                    return Some(found);
                }
            }
            _ => {}
        }
    }
    None
}

/// Return the parameter names of the function or method named `func_name`.
pub fn params_of_function(doc: &ParsedDoc, func_name: &str) -> Vec<String> {
    let mut out = Vec::new();
    collect_params_stmts(&doc.program().stmts, func_name, &mut out);
    out
}

/// Return the parameter names of `method_name` on class `class_name`.
/// Primarily used to offer named-argument completions for attribute constructors.
pub fn params_of_method(doc: &ParsedDoc, class_name: &str, method_name: &str) -> Vec<String> {
    let mut out = Vec::new();
    collect_method_params_stmts(&doc.program().stmts, class_name, method_name, &mut out);
    out
}

fn collect_method_params_stmts(
    stmts: &[php_ast::Stmt<'_, '_>],
    class_name: &str,
    method_name: &str,
    out: &mut Vec<String>,
) {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Class(c)
                if c.name.as_ref().map(|n| n.to_string()) == Some(class_name.to_string()) =>
            {
                for member in c.body.members.iter() {
                    if let ClassMemberKind::Method(m) = &member.kind
                        && m.name == method_name
                    {
                        for p in m.params.iter() {
                            out.push(p.name.to_string());
                        }
                        return;
                    }
                }
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body {
                    collect_method_params_stmts(&inner.stmts, class_name, method_name, out);
                }
            }
            _ => {}
        }
    }
}

/// Returns `true` if `class_name` is declared as an `enum` in `doc`.
pub fn is_enum(doc: &ParsedDoc, class_name: &str) -> bool {
    is_enum_in_stmts(&doc.program().stmts, class_name)
}

fn is_enum_in_stmts(stmts: &[Stmt<'_, '_>], name: &str) -> bool {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Enum(e) if e.name == name => return true,
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body
                    && is_enum_in_stmts(&inner.stmts, name)
                {
                    return true;
                }
            }
            _ => {}
        }
    }
    false
}

/// Returns `true` if `class_name` is a *backed* enum (`enum Foo: string` /
/// `enum Foo: int`) in `doc`.  Backed enums have a `->value` property.
pub fn is_backed_enum(doc: &ParsedDoc, class_name: &str) -> bool {
    enum_backing_type(doc, class_name).is_some()
}

/// Returns the declared backing type (`"string"` / `"int"`) of `class_name`
/// if it is a backed enum in `doc`, or `None` if it is not an enum, or is an
/// unbacked (pure) enum.
pub fn enum_backing_type(doc: &ParsedDoc, class_name: &str) -> Option<String> {
    enum_backing_type_in_stmts(&doc.program().stmts, class_name)
}

fn enum_backing_type_in_stmts(stmts: &[Stmt<'_, '_>], name: &str) -> Option<String> {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Enum(e) if e.name == name => {
                return e
                    .scalar_type
                    .as_ref()
                    .map(|t| t.to_string_repr().to_string());
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body
                    && let Some(ty) = enum_backing_type_in_stmts(&inner.stmts, name)
                {
                    return Some(ty);
                }
            }
            _ => {}
        }
    }
    None
}

fn collect_params_stmts(stmts: &[Stmt<'_, '_>], func_name: &str, out: &mut Vec<String>) {
    for stmt in stmts {
        match &stmt.kind {
            StmtKind::Function(f) if f.name == func_name => {
                for p in f.params.iter() {
                    out.push(p.name.to_string());
                }
                return;
            }
            StmtKind::Class(c) => {
                for member in c.body.members.iter() {
                    if let ClassMemberKind::Method(m) = &member.kind
                        && m.name == func_name
                    {
                        for p in m.params.iter() {
                            out.push(p.name.to_string());
                        }
                        return;
                    }
                }
            }
            StmtKind::Namespace(ns) => {
                if let NamespaceBody::Braced(inner) = &ns.body {
                    collect_params_stmts(&inner.stmts, func_name, out);
                }
            }
            _ => {}
        }
    }
}

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

    #[test]
    fn infers_type_from_new_expression() {
        let src = "<?php\n$obj = new Foo();";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(tm.get("$obj"), Some("Foo"));
    }

    #[test]
    fn unknown_variable_returns_none() {
        let src = "<?php\n$obj = new Foo();";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert!(tm.get("$other").is_none());
    }

    #[test]
    fn multiple_assignments() {
        let src = "<?php\n$a = new Foo();\n$b = new Bar();";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(tm.get("$a"), Some("Foo"));
        assert_eq!(tm.get("$b"), Some("Bar"));
    }

    #[test]
    fn later_assignment_overwrites() {
        let src = "<?php\n$a = new Foo();\n$a = new Bar();";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(tm.get("$a"), Some("Bar"));
    }

    #[test]
    fn infers_type_from_typed_param() {
        let src = "<?php\nfunction process(Mailer $mailer): void { $mailer-> }";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(tm.get("$mailer"), Some("Mailer"));
    }

    #[test]
    fn parent_class_name_finds_parent() {
        let src = "<?php\nclass Base {}\nclass Child extends Base {}";
        let doc = ParsedDoc::parse(src.to_string());
        assert_eq!(parent_class_name(&doc, "Child"), Some("Base".to_string()));
    }

    #[test]
    fn parent_class_name_returns_none_for_top_level() {
        let src = "<?php\nclass Base {}";
        let doc = ParsedDoc::parse(src.to_string());
        assert!(parent_class_name(&doc, "Base").is_none());
    }

    #[test]
    fn members_of_class_includes_parent_field() {
        let src = "<?php\nclass Base {}\nclass Child extends Base {}";
        let doc = ParsedDoc::parse(src.to_string());
        let m = members_of_class(&doc, "Child");
        assert_eq!(m.parent.as_deref(), Some("Base"));
    }

    #[test]
    fn members_of_class_finds_methods() {
        let src = "<?php\nclass Calc { public function add() {} public function sub() {} }";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "Calc");
        let names: Vec<&str> = members.methods.iter().map(|(n, _, _)| n.as_str()).collect();
        assert!(names.contains(&"add"), "missing 'add'");
        assert!(names.contains(&"sub"), "missing 'sub'");
    }

    /// `has_params` distinguishes a zero-arg method from one that takes
    /// arguments, so completion can decide whether the inserted snippet
    /// needs a `$1` tab stop inside the parens or should insert `()` plain.
    #[test]
    fn members_of_class_tracks_has_params_per_method() {
        let src = "<?php\nclass Calc { public function reset() {} public function add(int $x) {} }";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "Calc");
        let has_params = |name: &str| {
            members
                .methods
                .iter()
                .find(|(n, _, _)| n == name)
                .map(|(_, _, p)| *p)
        };
        assert_eq!(has_params("reset"), Some(false));
        assert_eq!(has_params("add"), Some(true));
    }

    #[test]
    fn members_of_unknown_class_is_empty() {
        let src = "<?php\nclass Calc { public function add() {} }";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "Unknown");
        assert!(members.methods.is_empty());
    }

    #[test]
    fn constructor_promoted_params_appear_as_properties() {
        let src = "<?php\nclass Point {\n    public function __construct(\n        public float $x,\n        public float $y,\n    ) {}\n}";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "Point");
        let prop_names: Vec<&str> = members.properties.iter().map(|(n, _)| n.as_str()).collect();
        assert!(
            prop_names.contains(&"x"),
            "promoted param x should be a property"
        );
        assert!(
            prop_names.contains(&"y"),
            "promoted param y should be a property"
        );
    }

    #[test]
    fn promoted_readonly_params_appear_in_readonly_properties() {
        let src = "<?php\nclass User {\n    public function __construct(\n        public readonly string $name,\n        public int $age,\n    ) {}\n}";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "User");
        let prop_names: Vec<&str> = members.properties.iter().map(|(n, _)| n.as_str()).collect();
        assert!(
            prop_names.contains(&"name"),
            "promoted param name should be a property"
        );
        assert!(
            prop_names.contains(&"age"),
            "promoted param age should be a property"
        );
        assert!(
            members.readonly_properties.contains(&"name".to_string()),
            "readonly promoted param name should be in readonly_properties"
        );
        assert!(
            !members.readonly_properties.contains(&"age".to_string()),
            "non-readonly promoted param age should not be in readonly_properties"
        );
    }

    #[test]
    fn enum_instance_members_include_name() {
        let src = "<?php\nenum Status { case Active; case Inactive; }";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "Status");
        let prop_names: Vec<&str> = members.properties.iter().map(|(n, _)| n.as_str()).collect();
        assert!(
            prop_names.contains(&"name"),
            "pure enum should expose ->name"
        );
        assert!(
            !prop_names.contains(&"value"),
            "pure enum should not expose ->value"
        );
    }

    #[test]
    fn backed_enum_exposes_value_and_factory_methods() {
        let src = "<?php\nenum Color: string { case Red = 'red'; }";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "Color");
        let prop_names: Vec<&str> = members.properties.iter().map(|(n, _)| n.as_str()).collect();
        let method_names: Vec<&str> = members.methods.iter().map(|(n, _, _)| n.as_str()).collect();
        assert!(
            prop_names.contains(&"value"),
            "backed enum should expose ->value"
        );
        assert!(
            method_names.contains(&"from"),
            "backed enum should have ::from()"
        );
        assert!(
            method_names.contains(&"tryFrom"),
            "backed enum should have ::tryFrom()"
        );
        assert!(
            method_names.contains(&"cases"),
            "enum should have ::cases()"
        );
    }

    #[test]
    fn enum_cases_appear_as_constants() {
        let src = "<?php\nenum Status { case Active; case Inactive; }";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "Status");
        assert!(members.constants.contains(&"Active".to_string()));
        assert!(members.constants.contains(&"Inactive".to_string()));
    }

    #[test]
    fn trait_members_are_collected() {
        let src = "<?php\ntrait Logging { public function log() {} public string $logFile; }";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "Logging");
        let method_names: Vec<&str> = members.methods.iter().map(|(n, _, _)| n.as_str()).collect();
        let prop_names: Vec<&str> = members.properties.iter().map(|(n, _)| n.as_str()).collect();
        assert!(
            method_names.contains(&"log"),
            "trait method log should be collected"
        );
        assert!(
            prop_names.contains(&"logFile"),
            "trait property logFile should be collected"
        );
    }

    #[test]
    fn class_with_trait_use_lists_trait() {
        let src = "<?php\ntrait Logging { public function log() {} }\nclass App { use Logging; }";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "App");
        assert!(
            members.trait_uses.contains(&"Logging".to_string()),
            "should list used trait"
        );
    }

    #[test]
    fn var_docblock_with_explicit_varname_infers_type() {
        let src = "<?php\n/** @var Mailer $mailer */\n$mailer = $container->get('mailer');";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$mailer"),
            Some("Mailer"),
            "@var with explicit name should map the variable"
        );
    }

    #[test]
    fn var_docblock_without_varname_infers_from_assignment() {
        let src = "<?php\n/** @var Repository */\n$repo = $this->getRepository();";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$repo"),
            Some("Repository"),
            "@var without name should use assignment LHS"
        );
    }

    #[test]
    fn var_docblock_does_not_map_primitive_types() {
        let src = "<?php\n/** @var string */\n$name = 'hello';";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        // Primitives (lowercase) should not be mapped as class names.
        assert!(
            tm.get("$name").is_none(),
            "primitive @var should not produce a class mapping"
        );
    }

    #[test]
    fn var_nullable_docblock_maps_to_class() {
        // `@var ?Foo $x` is now normalised to `Foo|null` by the mir parser.
        // The type_map must still infer the class name `Foo`, not `Foo|null`.
        let src = "<?php\n/** @var ?Mailer $mailer */\n$mailer = null;";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$mailer"),
            Some("Mailer"),
            "@var ?Foo should map to 'Foo', not 'Foo|null'"
        );
    }

    #[test]
    fn var_union_docblock_maps_first_class() {
        // `@var Foo|null $x` — first class-type component should be used.
        let src = "<?php\n/** @var Repository|null $repo */\n$repo = null;";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$repo"),
            Some("Repository"),
            "@var Foo|null should map to 'Foo', not 'Foo|null'"
        );
    }

    #[test]
    fn is_enum_pure() {
        let src = "<?php\nenum Suit { case Hearts; case Clubs; }";
        let doc = ParsedDoc::parse(src.to_string());
        assert!(is_enum(&doc, "Suit"));
        assert!(!is_backed_enum(&doc, "Suit"));
    }

    #[test]
    fn is_backed_enum_string() {
        let src = "<?php\nenum Status: string { case Active = 'active'; }";
        let doc = ParsedDoc::parse(src.to_string());
        assert!(is_enum(&doc, "Status"));
        assert!(is_backed_enum(&doc, "Status"));
    }

    #[test]
    fn is_enum_false_for_class() {
        let src = "<?php\nclass Foo {}";
        let doc = ParsedDoc::parse(src.to_string());
        assert!(!is_enum(&doc, "Foo"));
        assert!(!is_backed_enum(&doc, "Foo"));
    }

    #[test]
    fn closure_use_var_type_is_available_inside_body() {
        let src = "<?php\n$svc = new PaymentService();\n$fn = function() use ($svc) { $svc->process(); };";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$svc"),
            Some("PaymentService"),
            "captured use variable should retain its outer type inside closure body"
        );
    }

    #[test]
    fn closure_use_var_inner_assignment_does_not_override_outer_type() {
        // If inside a closure we assign $svc = new Other(), the outer $svc type
        // should be restored after walking the closure body (or_insert semantics).
        let src = "<?php\n$svc = new PaymentService();\n$fn = function() use ($svc) { $svc = new OtherService(); };";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        // The snapshot restore ensures $svc retains PaymentService for the outer scope.
        assert_eq!(
            tm.get("$svc"),
            Some("PaymentService"),
            "outer type should not be overwritten by inner assignment in closure"
        );
    }

    #[test]
    fn param_docblock_type_inferred() {
        let src = "<?php\n/**\n * @param Mailer $mailer\n */\nfunction send($mailer) { $mailer-> }";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(tm.get("$mailer"), Some("Mailer"));
    }

    #[test]
    fn param_docblock_does_not_override_ast_hint() {
        let src = "<?php\n/**\n * @param OtherClass $x\n */\nfunction foo(Foo $x) {}";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        // AST type hint takes precedence over docblock (AST processed after, overwrites)
        assert_eq!(tm.get("$x"), Some("Foo"));
    }

    #[test]
    fn not_null_check_preserves_existing_type() {
        let src = "<?php\n$x = new Foo();\nif ($x !== null) { $x-> }";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(tm.get("$x"), Some("Foo"));
    }

    #[test]
    fn docblock_property_appears_in_members() {
        let src =
            "<?php\n/**\n * @property string $email\n * @property-read int $id\n */\nclass User {}";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "User");
        let props: Vec<&str> = members.properties.iter().map(|(n, _)| n.as_str()).collect();
        assert!(props.contains(&"email"));
        assert!(props.contains(&"id"));
    }

    #[test]
    fn docblock_method_appears_in_members() {
        let src = "<?php\n/**\n * @method User find(int $id)\n * @method static Builder where(string $col, mixed $val)\n */\nclass Model {}";
        let doc = ParsedDoc::parse(src.to_string());
        let members = members_of_class(&doc, "Model");
        let method_names: Vec<&str> = members.methods.iter().map(|(n, _, _)| n.as_str()).collect();
        assert!(method_names.contains(&"find"));
        assert!(method_names.contains(&"where"));
        let where_static = members
            .methods
            .iter()
            .find(|(n, _, _)| n == "where")
            .map(|(_, s, _)| *s);
        assert_eq!(where_static, Some(true));
        let find_has_params = members
            .methods
            .iter()
            .find(|(n, _, _)| n == "find")
            .map(|(_, _, p)| *p);
        assert_eq!(find_has_params, Some(true));
    }

    #[test]
    fn union_type_param_maps_both_classes() {
        // function f(Foo|Bar $x) — both Foo and Bar should be in the union type string
        let src = "<?php\nfunction f(Foo|Bar $x) {}";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        let val = tm.get("$x").expect("$x should be in the type map");
        assert!(
            val.contains("Foo"),
            "union type should contain 'Foo', got: {}",
            val
        );
        assert!(
            val.contains("Bar"),
            "union type should contain 'Bar', got: {}",
            val
        );
    }

    #[test]
    fn nullable_param_resolves_to_class() {
        // function f(?Foo $x) — $x should map to Foo (nullable stripped)
        let src = "<?php\nfunction f(?Foo $x) {}";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$x"),
            Some("Foo"),
            "nullable type hint ?Foo should map $x to Foo"
        );
    }

    #[test]
    fn null_assignment_does_not_overwrite_class() {
        // $x = new Foo(); $x = null; — $x type should stay Foo because
        // assigning null does not overwrite a known class type in the single-pass map.
        let src = "<?php\n$x = new Foo();\n$x = null;\n";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        // The single-pass type map does not treat null as a class, so the last
        // successful class assignment (Foo) persists.
        assert_eq!(
            tm.get("$x"),
            Some("Foo"),
            "$x should retain its Foo type after being assigned null"
        );
    }

    #[test]
    fn infers_type_from_assignment_inside_trait_method() {
        let src = "<?php\ntrait Builder { public function make(): void { $obj = new Widget(); } }";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$obj"),
            Some("Widget"),
            "type map should walk into trait method bodies"
        );
    }

    #[test]
    fn infers_type_from_assignment_inside_enum_method() {
        let src = "<?php\nenum Color { case Red; public function make(): void { $obj = new Palette(); } }";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$obj"),
            Some("Palette"),
            "type map should walk into enum method bodies"
        );
    }

    // ── Gap 1: generic params stripped from class types ───────────────────────

    #[test]
    fn generic_type_annotation_stripped_to_base_class() {
        // `@var Collection<User> $coll` — the TypeMap fallback should store
        // "Collection", not "Collection<User>", so member lookups succeed.
        let src = "<?php\n/** @var Collection<User> $coll */\n$coll = get();";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$coll"),
            Some("Collection"),
            "generic param should be stripped; expected Collection, not Collection<User>"
        );
    }

    // ── Gap 4: list<T> element type propagated through foreach ────────────────

    #[test]
    fn list_var_annotation_maps_to_element_type() {
        // `@var list<Widget> $items` — TypeMap should store "Widget" for $items
        // so the foreach propagation step has a type to forward.
        let src = "<?php\n/** @var list<Widget> $items */\n$items = get();";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$items"),
            Some("Widget"),
            "element type Widget should be extracted from list<Widget>"
        );
    }

    #[test]
    fn array_element_annotation_maps_to_element_type() {
        // `@var array<Widget> $map` (single-param form) — TypeMap should store "Widget".
        // Note: `array<int, Widget>` with a space inside the generics is not handled
        // by the whitespace-split @var body extractor in docblock.rs; use the
        // single-param form or list<T> for this fallback path.
        let src = "<?php\n/** @var array<Widget> $map */\n$map = get();";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$map"),
            Some("Widget"),
            "element type Widget should be extracted from array<Widget>"
        );
    }

    #[test]
    fn foreach_value_var_inherits_element_type() {
        // `@var list<Widget> $items` followed by `foreach ($items as $w)` —
        // TypeMap should map `$w` to "Widget" in the fallback path.
        let src = "<?php\n/** @var list<Widget> $items */\n$items = get();\nforeach ($items as $w) { $w; }";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$w"),
            Some("Widget"),
            "$w should inherit Widget element type inside foreach"
        );
    }

    // ── Gap 2: @psalm-type alias expansion ────────────────────────────────────

    #[test]
    fn psalm_type_alias_expanded_for_param() {
        // Class docblock declares `@psalm-type Result = Success|Failure`.
        // The method `@param Result $r` should expand to both classes.
        let src = r#"<?php
/** @psalm-type Result = Success|Failure */
class Processor {
    /** @param Result $r */
    public function handle($r): void {}
}"#;
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        let val = tm.get("$r").expect("$r should be in the type map");
        assert!(
            val.contains("Success"),
            "alias should expand to include Success; got: {val}"
        );
        assert!(
            val.contains("Failure"),
            "alias should expand to include Failure; got: {val}"
        );
    }

    // ── Gap 6: first-class callable mapped to Closure ────────────────────────

    #[test]
    fn first_class_callable_maps_to_closure() {
        let src = "<?php\n$fn = strlen(...);";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$fn"),
            Some("Closure"),
            "first-class callable should be mapped to Closure"
        );
    }

    #[test]
    fn first_class_method_callable_maps_to_closure() {
        let src = "<?php\n$obj = new Foo();\n$m = $obj->bar(...);";
        let doc = ParsedDoc::parse(src.to_string());
        let tm = TypeMap::from_doc(&doc);
        assert_eq!(
            tm.get("$m"),
            Some("Closure"),
            "method first-class callable should be mapped to Closure"
        );
    }
}