phpantom_lsp 0.7.0

/// Right-hand-side expression resolution for variable assignments.
///
/// This module resolves the type of the right-hand side of an assignment
/// (`$var = <expr>`) to zero or more [`ResolvedType`] values.  It handles:
///
///   - Scalar literals: `1` → `int`, `'hello'` → `string`, etc.
///   - Array literals: `[new Foo()]` → `list<Foo>`,
///     `['a' => 1]` → `array{a: int}`
///   - `new ClassName(…)` → the instantiated class
///   - Array access: `$arr[0]` → generic element type,
///     `$arr['key']` → array shape value type,
///     `$arr['key'][0]` → chained bracket access
///   - Function calls: `someFunc()` → return type
///   - Method calls: `$this->method()`, `$obj->method()` → return type
///   - Static calls: `ClassName::method()` → return type
///   - Property access: `$this->prop`, `$obj->prop` → property type
///   - Match expressions: union of all arm types
///   - Ternary / null-coalescing: union of both branches
///   - Clone: `clone $expr` → preserves the cloned expression's type
///
/// The entry point is [`resolve_rhs_expression`], which dispatches to
/// specialised helpers based on the AST node kind.
/// The only caller is
/// [`check_expression_for_assignment`](super::resolution::check_expression_for_assignment)
/// in `variable_resolution.rs`.
use std::collections::HashMap;
use std::sync::Arc;

use mago_span::HasSpan;
use mago_syntax::ast::*;

use crate::Backend;
use crate::docblock;
use crate::parser::extract_hint_type;
use crate::php_type::PhpType;
use crate::types::{ClassInfo, ResolvedType};

use super::resolution::build_var_resolver_from_ctx;
use crate::completion::call_resolution::MethodReturnCtx;
use crate::completion::conditional_resolution::resolve_conditional_with_args;
use crate::completion::resolver::{Loaders, VarResolutionCtx};
use crate::util::strip_fqn_prefix;

/// Create a `ResolvedType` from a `PhpType`, looking up class info when the type names a class.
///
/// When the `PhpType` has a `base_name()` that resolves to a known class, returns
/// `ResolvedType::from_both(ty, class)`. Otherwise returns `ResolvedType::from_type_string(ty)`.
fn resolved_type_with_lookup(
    ty: PhpType,
    _current_class_name: &str,
    all_classes: &[Arc<ClassInfo>],
    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
) -> ResolvedType {
    if let Some(base) = ty.base_name() {
        let base = base.strip_prefix('\\').unwrap_or(base);
        // Don't try to look up scalars/pseudo-types
        if !crate::php_type::is_keyword_type(base) {
            // Try in-file classes first
            let cls = crate::util::find_class_by_name(all_classes, base)
                .map(|arc| arc.as_ref().clone())
                .or_else(|| class_loader(base).map(Arc::unwrap_or_clone));
            if let Some(class) = cls {
                return ResolvedType::from_both(ty, class);
            }
        }
    }
    ResolvedType::from_type_string(ty)
}

/// Resolve a right-hand-side expression to zero or more
/// [`ResolvedType`] values.
///
/// This is the single place where an arbitrary PHP expression is
/// resolved to a type.  It handles scalars, array literals,
/// instantiations, calls, property access, match/ternary/null-coalesce,
/// clone, closures, generators, pipe, and bare variables.
///
/// Entries may have `class_info: None` (e.g. scalar literals, array
/// shapes).  Callers that need only class-backed results should
/// filter with [`ResolvedType::into_classes`].
///
/// Used by `check_expression_for_assignment` (for `$var = <expr>`),
/// `check_expression_for_raw_type` (for hover/diagnostics type strings),
/// and recursively by multi-branch constructs (match, ternary, `??`).
pub(in crate::completion) fn resolve_rhs_expression<'b>(
    expr: &'b Expression<'b>,
    ctx: &VarResolutionCtx<'_>,
) -> Vec<ResolvedType> {
    match expr {
        // ── Scalar literals ─────────────────────────────────────────
        Expression::Literal(Literal::Integer(_)) => {
            vec![ResolvedType::from_type_string(PhpType::int())]
        }
        Expression::Literal(Literal::Float(_)) => {
            vec![ResolvedType::from_type_string(PhpType::float())]
        }
        Expression::Literal(Literal::String(_)) => {
            vec![ResolvedType::from_type_string(PhpType::string())]
        }
        Expression::Literal(Literal::True(_) | Literal::False(_)) => {
            vec![ResolvedType::from_type_string(PhpType::bool())]
        }
        Expression::Literal(Literal::Null(_)) => {
            vec![ResolvedType::from_type_string(PhpType::null())]
        }
        // ── Array literals ──────────────────────────────────────────
        Expression::Array(arr) => {
            let pt =
                super::raw_type_inference::infer_array_literal_raw_type(arr.elements.iter(), ctx)
                    .unwrap_or_else(PhpType::array);
            vec![ResolvedType::from_type_string(pt)]
        }
        Expression::LegacyArray(arr) => {
            let pt =
                super::raw_type_inference::infer_array_literal_raw_type(arr.elements.iter(), ctx)
                    .unwrap_or_else(PhpType::array);
            vec![ResolvedType::from_type_string(pt)]
        }
        Expression::Instantiation(inst) => resolve_rhs_instantiation(inst, ctx),
        // ── Anonymous class: `new class extends Foo { … }` ──────────
        // The parser stores these in `all_classes` with a synthetic
        // name `__anonymous@<offset>`.  Look it up by matching the
        // left-brace offset so the variable inherits the full
        // ClassInfo (parent class, traits, methods, etc.).
        Expression::AnonymousClass(anon) => {
            let start = anon.left_brace.start.offset;
            let name = format!("__anonymous@{}", start);
            if let Some(cls) = ctx.all_classes.iter().find(|c| c.name == name) {
                return ResolvedType::from_classes(vec![(**cls).clone()]);
            }
            vec![]
        }
        Expression::ArrayAccess(array_access) => resolve_rhs_array_access(array_access, expr, ctx),
        Expression::Call(call) => resolve_rhs_call(call, expr, ctx),
        Expression::Access(access) => resolve_rhs_property_access(access, ctx),
        Expression::Parenthesized(p) => resolve_rhs_expression(p.expression, ctx),
        Expression::Match(match_expr) => {
            let mut combined = Vec::new();
            for arm in match_expr.arms.iter() {
                let arm_results = resolve_rhs_expression(arm.expression(), ctx);
                ResolvedType::extend_unique(&mut combined, arm_results);
            }
            combined
        }
        Expression::Conditional(cond_expr) => {
            let mut combined = Vec::new();
            let then_expr = cond_expr.then.unwrap_or(cond_expr.condition);
            ResolvedType::extend_unique(&mut combined, resolve_rhs_expression(then_expr, ctx));
            ResolvedType::extend_unique(
                &mut combined,
                resolve_rhs_expression(cond_expr.r#else, ctx),
            );
            combined
        }
        Expression::Binary(binary) if binary.operator.is_null_coalesce() => {
            // When the LHS is syntactically non-nullable (e.g. `new Foo()`,
            // a literal, `clone $x`), the RHS is dead code — return only
            // the LHS results.  Otherwise resolve both sides; if the LHS
            // type string is nullable, strip `null` before unioning.
            let lhs_non_nullable = matches!(
                binary.lhs,
                Expression::Instantiation(_)
                    | Expression::Literal(_)
                    | Expression::Array(_)
                    | Expression::LegacyArray(_)
                    | Expression::Clone(_)
            );
            let lhs_results = resolve_rhs_expression(binary.lhs, ctx);
            if !lhs_results.is_empty() && lhs_non_nullable {
                lhs_results
            } else if !lhs_results.is_empty() {
                // Strip `null` entries and nullable wrappers from the
                // LHS type strings before unioning with the RHS.
                // Example: `?Foo ?? Bar` → `Foo|Bar`.
                let mut combined: Vec<ResolvedType> = lhs_results
                    .into_iter()
                    .filter_map(|mut rt| {
                        let parsed = rt.type_string.clone();
                        match parsed.non_null_type() {
                            // Nullable/union contained null — use the stripped version.
                            Some(non_null) => {
                                rt.type_string = non_null;
                                Some(rt)
                            }
                            // Not nullable/union: bare `null` is filtered out,
                            // everything else (including `mixed`) passes through.
                            None if rt.type_string == PhpType::null() => None,
                            None => Some(rt),
                        }
                    })
                    .collect();
                // Always union with the RHS.  Even when the LHS type
                // string looks non-nullable, the user wrote `??`
                // defensively and both branches are valid candidates.
                ResolvedType::extend_unique(&mut combined, resolve_rhs_expression(binary.rhs, ctx));
                combined
            } else {
                let mut combined = lhs_results;
                ResolvedType::extend_unique(&mut combined, resolve_rhs_expression(binary.rhs, ctx));
                combined
            }
        }
        Expression::Clone(clone_expr) => resolve_rhs_clone(clone_expr, ctx),
        // ── Pipe operator (PHP 8.5): `$expr |> callable(...)` ──
        // The result type is the return type of the callable.
        // The callable is typically a first-class callable reference
        // (PartialApplication) such as `trim(...)` or `createDate(...)`.
        Expression::Pipe(pipe) => resolve_rhs_pipe(pipe, ctx),
        Expression::PartialApplication(_)
        | Expression::Closure(_)
        | Expression::ArrowFunction(_) => {
            // First-class callable syntax (`strlen(...)`),
            // closure literals (`function() { … }`), and
            // arrow functions (`fn() => …`) all produce a
            // `Closure` instance at runtime.
            // Use the fully-qualified name so that resolution
            // succeeds even inside a namespace block (unqualified
            // class names are prefixed with the current namespace
            // and do NOT fall back to the global scope in PHP).
            let closure_ty = PhpType::closure();
            ResolvedType::from_classes_with_hint(
                crate::completion::type_resolution::type_hint_to_classes_typed(
                    &closure_ty,
                    &ctx.current_class.name,
                    ctx.all_classes,
                    ctx.class_loader,
                ),
                closure_ty,
            )
        }
        // ── Generator yield-assignment: `$var = yield $expr` ──
        // The value of a yield expression is the TSend type from
        // the enclosing function's `@return Generator<K, V, TSend, R>`.
        Expression::Yield(_) => {
            if let Some(ref ret_type) = ctx.enclosing_return_type
                && let Some(send_php_type) = ret_type.generator_send_type(true)
            {
                return ResolvedType::from_classes_with_hint(
                    crate::completion::type_resolution::type_hint_to_classes_typed(
                        send_php_type,
                        &ctx.current_class.name,
                        ctx.all_classes,
                        ctx.class_loader,
                    ),
                    send_php_type.clone(),
                );
            }
            vec![]
        }
        // ── Bare variable: `$a = $b` ────────────────────────────────
        // Resolve the RHS variable's type by walking assignments before
        // this point.  The caller (`check_expression_for_assignment`)
        // already set `ctx.cursor_offset` to the assignment's start
        // offset, so the recursive resolution only considers
        // assignments *before* the current one, preventing cycles.
        Expression::Variable(Variable::Direct(dv)) => {
            let rhs_var = dv.name.to_string();
            // Guard: never recurse into the same variable (self-assignment).
            if rhs_var == ctx.var_name {
                return vec![];
            }
            super::resolution::resolve_variable_types(
                &rhs_var,
                ctx.current_class,
                ctx.all_classes,
                ctx.content,
                ctx.cursor_offset,
                ctx.class_loader,
                Loaders::with_function(ctx.function_loader()),
            )
        }
        // ── Concatenation: `"prefix" . $var` → string ───────────────
        Expression::Binary(binary) if binary.operator.is_concatenation() => {
            vec![ResolvedType::from_type_string(PhpType::string())]
        }
        // ── Global constant access: `PHP_EOL`, `SORT_ASC`, etc. ────
        Expression::ConstantAccess(ca) => {
            let name = ca.name.value().to_string();
            let name_clean = strip_fqn_prefix(&name);
            // `true`, `false`, `null` are parsed as ConstantAccess by
            // some AST variants — handle them the same as literals.
            match name_clean.to_lowercase().as_str() {
                "true" | "false" => {
                    return vec![ResolvedType::from_type_string(PhpType::bool())];
                }
                "null" => {
                    return vec![ResolvedType::from_type_string(PhpType::null())];
                }
                _ => {}
            }
            if let Some(loader) = ctx.constant_loader()
                && let Some(maybe_value) = loader(name_clean)
                && let Some(ref value) = maybe_value
                && let Some(ts) = infer_type_from_constant_value(value)
            {
                return vec![ResolvedType::from_type_string(ts)];
            }
            vec![]
        }
        // ── Arithmetic: `$a + $b`, `$a * $b` etc. → numeric ────────
        // We can't distinguish int vs float without deeper analysis,
        // so we don't emit a type here and let callers fall back.
        //
        // ── Catch-all: unrecognised expression types ────────────────
        // Return an empty vec — callers that need a type string for
        // expressions not handled above should use the raw-type
        // inference pipeline.
        _ => vec![],
    }
}

/// Infer a scalar type from a constant's initializer value string.
///
/// Recognises integer literals (`42`, `-1`, `0xFF`), float literals
/// (`3.14`, `1e10`), string literals (`'hello'`, `"world"`), boolean
/// keywords (`true`, `false`), `null`, and array literals (`[...]`,
/// `array(...)`).  Returns `None` for expressions that cannot be
/// trivially classified (e.g. concatenation, function calls).
fn infer_type_from_constant_value(value: &str) -> Option<PhpType> {
    let v = value.trim();
    if v.is_empty() {
        return None;
    }

    // String literals: single or double quoted.
    if (v.starts_with('\'') && v.ends_with('\'')) || (v.starts_with('"') && v.ends_with('"')) {
        return Some(PhpType::string());
    }

    // Array literals.
    if v.starts_with('[') || v.starts_with("array(") || v.starts_with("array (") {
        return Some(PhpType::array());
    }

    let lower = v.to_lowercase();

    // Boolean / null keywords.
    if lower == "true" || lower == "false" {
        return Some(PhpType::bool());
    }
    if lower == "null" {
        return Some(PhpType::null());
    }

    // Numeric literals — try integer first, then float.
    // Strip optional leading sign for parsing.
    let numeric = v
        .strip_prefix('-')
        .or_else(|| v.strip_prefix('+'))
        .unwrap_or(v);
    if numeric.starts_with("0x") || numeric.starts_with("0X") {
        // Hex integer.
        if numeric[2..]
            .chars()
            .all(|c| c.is_ascii_hexdigit() || c == '_')
        {
            return Some(PhpType::int());
        }
    }
    if numeric.starts_with("0b") || numeric.starts_with("0B") {
        // Binary integer.
        if numeric[2..]
            .chars()
            .all(|c| c == '0' || c == '1' || c == '_')
        {
            return Some(PhpType::int());
        }
    }
    if numeric.starts_with("0o") || numeric.starts_with("0O") {
        // Octal integer (PHP 8.1+).
        if numeric[2..]
            .chars()
            .all(|c| ('0'..='7').contains(&c) || c == '_')
        {
            return Some(PhpType::int());
        }
    }
    // Decimal integer (may contain underscores: 1_000_000).
    if !numeric.is_empty()
        && numeric.chars().all(|c| c.is_ascii_digit() || c == '_')
        && numeric.chars().next().is_some_and(|c| c.is_ascii_digit())
    {
        return Some(PhpType::int());
    }
    // Float: contains `.` or `e`/`E` among digits.
    if !numeric.is_empty() {
        let has_dot = numeric.contains('.');
        let has_exp = numeric.contains('e') || numeric.contains('E');
        if (has_dot || has_exp)
            && numeric.chars().all(|c| {
                c.is_ascii_digit()
                    || c == '.'
                    || c == 'e'
                    || c == 'E'
                    || c == '+'
                    || c == '-'
                    || c == '_'
            })
        {
            return Some(PhpType::float());
        }
    }

    None
}

/// Resolve a pipe expression `$input |> callable(...)` to the callable's
/// return type.
///
/// The pipe operator passes `$input` as the first argument to `callable`
/// and returns its result.  Chains like `$a |> f(...) |> g(...)` are
/// nested: the outer pipe's input is the inner pipe expression.
///
/// Currently handles function-level callables (e.g. `createDate(...)`).
/// Method and static method callables are not yet supported.
fn resolve_rhs_pipe(pipe: &Pipe<'_>, ctx: &VarResolutionCtx<'_>) -> Vec<ResolvedType> {
    // The callable determines the result type.
    // For `PartialApplication::Function`, extract the function name
    // and look up its return type.
    match pipe.callable {
        Expression::PartialApplication(PartialApplication::Function(fpa)) => {
            let func_name = match fpa.function {
                Expression::Identifier(ident) => ident.value().to_string(),
                _ => return vec![],
            };
            if let Some(fl) = ctx.function_loader()
                && let Some(func_info) = fl(&func_name)
                && let Some(ref ret) = func_info.return_type
            {
                return ResolvedType::from_classes_with_hint(
                    crate::completion::type_resolution::type_hint_to_classes_typed(
                        ret,
                        &ctx.current_class.name,
                        ctx.all_classes,
                        ctx.class_loader,
                    ),
                    ret.clone(),
                );
            }
            vec![]
        }
        // Method callable: `$input |> $obj->method(...)`
        // Static callable: `$input |> Class::method(...)`
        // Not yet supported — fall back to empty.
        _ => vec![],
    }
}

/// Resolve `new ClassName(…)` to the instantiated class.
fn resolve_rhs_instantiation(
    inst: &Instantiation<'_>,
    ctx: &VarResolutionCtx<'_>,
) -> Vec<ResolvedType> {
    let class_name = match inst.class {
        Expression::Self_(_) => Some("self"),
        Expression::Static(_) => Some("static"),
        Expression::Identifier(ident) => Some(ident.value()),
        _ => None,
    };
    if let Some(name) = class_name {
        let parsed_name = PhpType::Named(name.to_string());
        let classes = crate::completion::type_resolution::type_hint_to_classes_typed(
            &parsed_name,
            &ctx.current_class.name,
            ctx.all_classes,
            ctx.class_loader,
        );

        // ── Constructor template inference ──────────────────────
        // When the class has `@template` params and the constructor
        // has `@param` bindings for them, infer concrete types from
        // the constructor arguments and apply the substitution to
        // the class so that methods returning `T` resolve correctly.
        if classes.len() == 1 && !classes[0].template_params.is_empty() {
            let cls = &classes[0];
            if let Some(ctor) = cls.methods.iter().find(|m| m.name == "__construct")
                && !ctor.template_bindings.is_empty()
                && let Some(ref arg_list) = inst.argument_list
            {
                let text_args =
                    super::raw_type_inference::extract_argument_text(arg_list, ctx.content);
                if !text_args.is_empty() {
                    let rctx = ctx.as_resolution_ctx();
                    let subs = build_constructor_template_subs(cls, ctor, &text_args, &rctx, ctx);
                    if !subs.is_empty() {
                        let type_args: Vec<PhpType> = cls
                            .template_params
                            .iter()
                            .map(|p| {
                                subs.get(p)
                                    .cloned()
                                    .unwrap_or_else(|| PhpType::Named(p.to_string()))
                            })
                            .collect();
                        let resolved =
                            crate::virtual_members::resolve_class_fully(cls, ctx.class_loader);
                        let mut substituted =
                            crate::inheritance::apply_generic_args(&resolved, &type_args);

                        // ── Template-param mixin resolution ────────────────
                        // When a class declares `@mixin TParam` where `TParam`
                        // is a template parameter, the mixin cannot be resolved
                        // during `resolve_class_fully` because the concrete type
                        // is not yet known.  Now that generic args are concrete,
                        // resolve those mixins and merge their members.
                        if cls.mixins.iter().any(|m| cls.template_params.contains(m)) {
                            let generic_subs =
                                crate::inheritance::build_generic_subs(cls, &type_args);
                            if !generic_subs.is_empty() {
                                let mixin_members =
                                    crate::virtual_members::phpdoc::resolve_template_param_mixins(
                                        cls,
                                        &generic_subs,
                                        ctx.class_loader,
                                    );
                                if !mixin_members.is_empty() {
                                    crate::virtual_members::merge_virtual_members(
                                        &mut substituted,
                                        mixin_members,
                                    );
                                }
                            }
                        }

                        let generic_type =
                            PhpType::Generic(substituted.name.clone(), type_args.clone());
                        return vec![ResolvedType::from_both(generic_type, substituted)];
                    }
                }
            }
        }

        return ResolvedType::from_classes_with_hint(classes, parsed_name);
    }

    // ── `new $var` where `$var` holds a class-string ────────────
    // When the class expression is a variable, resolve it to check
    // if it holds a class-string value (e.g. `$f = Foo::class;
    // new $f`).  Extract the class name from the class-string and
    // use it to resolve the instantiated type.
    if let Expression::Variable(Variable::Direct(dv)) = inst.class {
        let var_name = dv.name.to_string();
        let resolved =
            crate::completion::variable::class_string_resolution::resolve_class_string_targets(
                &var_name,
                ctx.current_class,
                ctx.all_classes,
                ctx.content,
                ctx.cursor_offset,
                ctx.class_loader,
            );
        if !resolved.is_empty() {
            return ResolvedType::from_classes(resolved);
        }
    }

    vec![]
}

/// Build a template substitution map from constructor arguments.
///
/// Uses the constructor's `template_bindings` (from `@param T $name`
/// annotations) to match template parameters to their concrete types
/// inferred from the call-site arguments.  Handles:
///   - Direct type: `@param T $bar` + `new Foo(new Baz())` → `T = Baz`
///   - Array type: `@param T[] $items` + `new Foo([new X()])` → `T = X`
///   - Generic wrapper: `@param Wrapper<T> $w` + `new Foo(new Wrapper(new X()))` → `T = X`
///     (by resolving the wrapper's constructor template params recursively)
fn build_constructor_template_subs(
    _class: &ClassInfo,
    ctor: &crate::types::MethodInfo,
    text_args: &str,
    rctx: &crate::completion::resolver::ResolutionCtx<'_>,
    ctx: &VarResolutionCtx<'_>,
) -> HashMap<String, PhpType> {
    let args = crate::completion::conditional_resolution::split_text_args(text_args);
    let mut subs = HashMap::new();

    for (tpl_name, param_name) in &ctor.template_bindings {
        // Find the parameter index for this binding.
        let param_idx = match ctor.parameters.iter().position(|p| p.name == *param_name) {
            Some(idx) => idx,
            None => continue,
        };

        // Get the corresponding argument text.
        let arg_text = match args.get(param_idx) {
            Some(text) => text.trim(),
            None => continue,
        };

        // Determine the binding mode by inspecting the parameter's
        // docblock type hint.  The type hint tells us how the template
        // param is embedded in the `@param` annotation.
        let param_hint = ctor
            .parameters
            .get(param_idx)
            .and_then(|p| p.type_hint.as_ref());
        let binding_mode = classify_template_binding(tpl_name, param_hint);

        match binding_mode {
            TemplateBindingMode::Direct => {
                // `@param T $bar` — the argument resolves directly to T.
                if let Some(resolved_type) = Backend::resolve_arg_text_to_type(arg_text, rctx) {
                    subs.insert(tpl_name.clone(), resolved_type);
                }
            }
            TemplateBindingMode::CallableReturnType => {
                // `@param callable(...): T $cb` — extract the closure's
                // return type annotation from the argument text.
                if let Some(ret_type) =
                    crate::completion::source::helpers::extract_closure_return_type_from_text(
                        arg_text,
                    )
                {
                    subs.insert(tpl_name.clone(), ret_type);
                }
            }
            TemplateBindingMode::CallableParamType(position) => {
                // `@param Closure(T): void $cb` — extract the closure's
                // parameter type annotation at the given position.
                if let Some(param_type) =
                    crate::completion::source::helpers::extract_closure_param_type_from_text(
                        arg_text, position,
                    )
                {
                    subs.insert(tpl_name.clone(), param_type);
                }
            }
            TemplateBindingMode::ArrayElement => {
                // `@param T[] $items` — resolve individual array elements.
                if arg_text.starts_with('[') && arg_text.ends_with(']') {
                    let inner = arg_text[1..arg_text.len() - 1].trim();
                    if !inner.is_empty() {
                        let first_elem =
                            crate::completion::conditional_resolution::split_text_args(inner);
                        if let Some(elem) = first_elem.first()
                            && let Some(resolved_type) =
                                Backend::resolve_arg_text_to_type(elem.trim(), rctx)
                        {
                            subs.insert(tpl_name.clone(), resolved_type);
                        }
                    }
                } else if let Some(resolved_type) =
                    Backend::resolve_arg_text_to_type(arg_text, rctx)
                {
                    // Fallback: treat as direct if not an array literal.
                    subs.insert(tpl_name.clone(), resolved_type);
                }
            }
            TemplateBindingMode::GenericWrapper(wrapper_name, tpl_position) => {
                // `@param Wrapper<T> $a` — resolve the wrapper's constructor
                // template params to find the concrete type for T.
                if let Some(concrete) = resolve_generic_wrapper_template(
                    &wrapper_name,
                    tpl_position,
                    arg_text,
                    rctx,
                    ctx,
                ) {
                    subs.insert(tpl_name.clone(), concrete);
                }
            }
        }
    }

    subs
}

/// How a template parameter is referenced in a `@param` type annotation.
#[derive(Debug)]
pub(crate) enum TemplateBindingMode {
    /// `@param T $bar` — the whole type is the template param.
    Direct,
    /// `@param T[] $items` — the template param is the array element type.
    ArrayElement,
    /// `@param Wrapper<..., T, ...> $a` — the template param is a generic
    /// argument of the wrapper class at the given position.
    GenericWrapper(String, usize),
    /// `@param callable(...): T $cb` — the template param appears in the
    /// callable's return type.  The binding is resolved by extracting the
    /// return type annotation from the closure/arrow-function argument.
    CallableReturnType,
    /// `@param Closure(T): void $cb` — the template param appears in the
    /// callable's parameter list at the given position (0-based).  The
    /// binding is resolved by extracting the closure's parameter type
    /// annotation at that index from the argument text.
    CallableParamType(usize),
}

/// Classify how a template parameter name appears in a `@param` type hint.
///
/// Handles union types like `Arrayable<TKey, TValue>|iterable<TKey, TValue>|null`
/// by recursively inspecting the [`PhpType`] structure.
pub(crate) fn classify_template_binding(
    tpl_name: &str,
    param_hint: Option<&PhpType>,
) -> TemplateBindingMode {
    let hint = match param_hint {
        Some(h) => h,
        None => return TemplateBindingMode::Direct,
    };

    classify_from_php_type(tpl_name, hint)
}

/// Recursively classify how a template parameter name appears in a parsed
/// [`PhpType`].
fn classify_from_php_type(tpl_name: &str, ty: &PhpType) -> TemplateBindingMode {
    match ty {
        PhpType::Nullable(inner) => classify_from_php_type(tpl_name, inner),
        PhpType::Union(members) => {
            for member in members {
                if member.is_null() {
                    continue;
                }
                let result = classify_from_php_type(tpl_name, member);
                if !matches!(result, TemplateBindingMode::Direct) {
                    return result;
                }
                // If it matched Direct because it IS the template name, return it.
                if member.is_named(tpl_name) {
                    return TemplateBindingMode::Direct;
                }
            }
            TemplateBindingMode::Direct
        }
        PhpType::Array(inner) => {
            if inner.as_ref().is_named(tpl_name) {
                return TemplateBindingMode::ArrayElement;
            }
            TemplateBindingMode::Direct
        }
        PhpType::Named(n) if n == tpl_name => TemplateBindingMode::Direct,
        PhpType::Generic(wrapper_name, args) => {
            for (i, arg) in args.iter().enumerate() {
                if arg.is_named(tpl_name) {
                    return TemplateBindingMode::GenericWrapper(wrapper_name.clone(), i);
                }
            }
            TemplateBindingMode::Direct
        }
        PhpType::Callable {
            params,
            return_type,
            ..
        } => {
            if let Some(rt) = return_type
                && type_contains_name(rt, tpl_name)
            {
                return TemplateBindingMode::CallableReturnType;
            }
            for (i, p) in params.iter().enumerate() {
                if type_contains_name(&p.type_hint, tpl_name) {
                    return TemplateBindingMode::CallableParamType(i);
                }
            }
            TemplateBindingMode::Direct
        }
        _ => TemplateBindingMode::Direct,
    }
}

/// Check whether a [`PhpType`] tree contains a [`PhpType::Named`] with the
/// given name anywhere in its structure.
fn type_contains_name(ty: &PhpType, name: &str) -> bool {
    match ty {
        PhpType::Named(n) => n == name,
        PhpType::Nullable(inner) | PhpType::Array(inner) => type_contains_name(inner, name),
        PhpType::Union(members) | PhpType::Intersection(members) => {
            members.iter().any(|m| type_contains_name(m, name))
        }
        PhpType::Generic(_, args) => args.iter().any(|a| type_contains_name(a, name)),
        PhpType::Callable {
            params,
            return_type,
            ..
        } => {
            params
                .iter()
                .any(|p| type_contains_name(&p.type_hint, name))
                || return_type
                    .as_ref()
                    .is_some_and(|rt| type_contains_name(rt, name))
        }
        PhpType::ClassString(Some(inner))
        | PhpType::InterfaceString(Some(inner))
        | PhpType::KeyOf(inner)
        | PhpType::ValueOf(inner) => type_contains_name(inner, name),
        _ => false,
    }
}

/// Resolve a template param that appears inside a generic wrapper type.
///
/// For `@param Wrapper<T> $a` with argument `new Wrapper(new X())`,
/// recursively resolve the wrapper's constructor template params to
/// find the concrete type for the template param at `tpl_position`.
fn resolve_generic_wrapper_template(
    wrapper_name: &str,
    tpl_position: usize,
    arg_text: &str,
    rctx: &crate::completion::resolver::ResolutionCtx<'_>,
    ctx: &VarResolutionCtx<'_>,
) -> Option<PhpType> {
    // Load the wrapper class.
    let wrapper_cls = (ctx.class_loader)(wrapper_name)
        .map(Arc::unwrap_or_clone)
        .or_else(|| {
            ctx.all_classes
                .iter()
                .find(|c| crate::util::short_name(&c.name) == crate::util::short_name(wrapper_name))
                .map(|c| ClassInfo::clone(c))
        })?;

    // Find the wrapper's constructor and its template bindings.
    let wrapper_ctor = wrapper_cls
        .methods
        .iter()
        .find(|m| m.name == "__construct")?;
    if wrapper_ctor.template_bindings.is_empty() {
        return None;
    }

    // Extract the constructor arguments from the argument text.
    // e.g. from `new Foobar(new X())` extract `new X()`.
    let paren_start = arg_text.find('(')?;
    let paren_end = arg_text.rfind(')')?;
    let inner_args = arg_text[paren_start + 1..paren_end].trim();

    let wrapper_subs =
        build_constructor_template_subs(&wrapper_cls, wrapper_ctor, inner_args, rctx, ctx);

    // Find the wrapper's template param at the given position and
    // look it up in the substitution map.
    let wrapper_tpl = wrapper_cls.template_params.get(tpl_position)?;
    wrapper_subs.get(wrapper_tpl).cloned()
}

/// Resolve `$arr[0]` / `$arr[$key]` by extracting the generic element
/// type from the base array's annotation or assignment.
fn resolve_rhs_array_access<'b>(
    array_access: &ArrayAccess<'b>,
    expr: &'b Expression<'b>,
    ctx: &VarResolutionCtx<'_>,
) -> Vec<ResolvedType> {
    // Collect bracket segments and find the innermost base variable by
    // walking through nested ArrayAccess nodes.  This handles both
    // single access (`$result['data']`) and chained access
    // (`$result['items'][0]`).
    let mut segments: Vec<ArrayBracketSegment> = Vec::new();
    let mut current_expr: &Expression<'_> = array_access.array;

    // Classify the outermost (current) index first.
    segments.push(classify_array_index(array_access.index));

    // Walk inward through nested ArrayAccess nodes.
    while let Expression::ArrayAccess(inner) = current_expr {
        segments.push(classify_array_index(inner.index));
        current_expr = inner.array;
    }

    // Segments were collected innermost-last; reverse to left-to-right order.
    segments.reverse();

    let access_offset = expr.span().start.offset as usize;

    // Resolve the base expression's raw type string.
    // For bare variables (`$var['key']`), use docblock or assignment scanning.
    // For property chains (`$obj->prop['key']`), resolve the property type.
    let raw_type: Option<PhpType> =
        if let Expression::Variable(Variable::Direct(base_dv)) = current_expr {
            let base_var = base_dv.name.to_string();
            docblock::find_iterable_raw_type_in_source(ctx.content, access_offset, &base_var)
                .or_else(|| {
                    let resolved = super::resolution::resolve_variable_types(
                        &base_var,
                        ctx.current_class,
                        ctx.all_classes,
                        ctx.content,
                        access_offset as u32,
                        ctx.class_loader,
                        Loaders::with_function(ctx.function_loader()),
                    );
                    if resolved.is_empty() {
                        None
                    } else {
                        Some(ResolvedType::types_joined(&resolved))
                    }
                })
        } else {
            // Non-variable base (e.g. property access `$obj->prop['key']`,
            // method call `$obj->getItems()['key']`, etc.).
            // Resolve the base expression to get its type.
            let base_resolved = resolve_rhs_expression(current_expr, ctx);
            if base_resolved.is_empty() {
                None
            } else {
                Some(ResolvedType::types_joined(&base_resolved))
            }
        };

    let Some(mut current) = raw_type else {
        return vec![];
    };

    // Expand type aliases so that shape/generic extraction can see the
    // underlying type (e.g. a `@phpstan-type` alias).
    if let Some(expanded) = crate::completion::type_resolution::resolve_type_alias_typed(
        &current,
        &ctx.current_class.name,
        ctx.all_classes,
        ctx.class_loader,
    ) {
        current = expanded;
    }

    // Walk each bracket segment, narrowing the type at each step.
    for seg in &segments {
        // Try pure-type extraction first (array shapes, generics).
        let extracted = match seg {
            ArrayBracketSegment::StringKey(key) => current
                .shape_value_type(key)
                .cloned()
                .or_else(|| current.extract_value_type(true).cloned()),
            ArrayBracketSegment::ElementAccess => current.extract_value_type(true).cloned(),
        };

        if let Some(element) = extracted {
            current = element;
        } else {
            // Fallback: when the current type is a plain class name (e.g.
            // `OpeningHours`), resolve the class and check its iterable
            // generics (`@extends`, `@implements`) for the element type.
            // This handles `$obj->prop['key']` where `prop` is a collection
            // class like `OpeningHours extends DataCollection<string, Day>`.
            let class_element = crate::completion::type_resolution::type_hint_to_classes_typed(
                &current,
                &ctx.current_class.name,
                ctx.all_classes,
                ctx.class_loader,
            )
            .into_iter()
            .find_map(|cls| {
                let merged = crate::virtual_members::resolve_class_fully(&cls, ctx.class_loader);
                super::foreach_resolution::extract_iterable_element_type_from_class(
                    &merged,
                    ctx.class_loader,
                )
            });

            if let Some(element) = class_element {
                current = element;
            } else {
                return vec![];
            }
        }

        // After each segment, the resulting type might itself be an
        // alias (e.g. a shape value defined as another alias).
        if let Some(expanded) = crate::completion::type_resolution::resolve_type_alias_typed(
            &current,
            &ctx.current_class.name,
            ctx.all_classes,
            ctx.class_loader,
        ) {
            current = expanded;
        }
    }

    ResolvedType::from_classes_with_hint(
        crate::completion::type_resolution::type_hint_to_classes_typed(
            &current,
            &ctx.current_class.name,
            ctx.all_classes,
            ctx.class_loader,
        ),
        current,
    )
}

/// Classification of an array access index expression.
enum ArrayBracketSegment {
    /// A string-key access, e.g. `['items']`.
    StringKey(String),
    /// A numeric or variable index access, e.g. `[0]` or `[$i]`.
    ElementAccess,
}

/// Classify an array index expression as either a string key or generic
/// element access.
fn classify_array_index(index: &Expression<'_>) -> ArrayBracketSegment {
    if let Expression::Literal(Literal::String(s)) = index {
        let key = s.value.map(|v| v.to_string()).unwrap_or_else(|| {
            crate::util::unquote_php_string(s.raw)
                .unwrap_or(s.raw)
                .to_string()
        });
        ArrayBracketSegment::StringKey(key)
    } else {
        ArrayBracketSegment::ElementAccess
    }
}

/// Build a template substitution map for a function-level `@template` call.
///
/// Uses the function's `template_bindings` to match template parameters to
/// their concrete types inferred from the call-site arguments.  Handles:
///   - Direct type: `@param T $bar` + `func(new Baz())` → `T = Baz`
///   - Array type: `@param T[] $items` + `func([new X()])` → `T = X`
///   - Generic wrapper: `@param array<TKey, TValue> $v` + `func($users)` →
///     positional resolution through the wrapper's generic arguments.
pub(crate) fn build_function_template_subs(
    func_info: &crate::types::FunctionInfo,
    text_args: &str,
    rctx: &crate::completion::resolver::ResolutionCtx<'_>,
) -> HashMap<String, PhpType> {
    let args = crate::completion::conditional_resolution::split_text_args(text_args);
    let mut subs = HashMap::new();

    for (tpl_name, param_name) in &func_info.template_bindings {
        let param_idx = match func_info
            .parameters
            .iter()
            .position(|p| p.name == *param_name)
        {
            Some(idx) => idx,
            None => continue,
        };

        let arg_text = match args.get(param_idx) {
            Some(text) => text.trim(),
            None => continue,
        };

        // Determine the binding mode by inspecting the parameter's
        // docblock type hint.  The type hint tells us how the template
        // param is embedded in the `@param` annotation.
        let param_hint = func_info
            .parameters
            .get(param_idx)
            .and_then(|p| p.type_hint.as_ref());
        let binding_mode = classify_template_binding(tpl_name, param_hint);

        match binding_mode {
            TemplateBindingMode::Direct => {
                if let Some(resolved_type) = Backend::resolve_arg_text_to_type(arg_text, rctx) {
                    subs.insert(tpl_name.clone(), resolved_type);
                }
            }
            TemplateBindingMode::CallableReturnType => {
                // `@param callable(...): T $cb` — extract the closure's
                // return type annotation from the argument text.
                if let Some(ret_type) =
                    crate::completion::source::helpers::extract_closure_return_type_from_text(
                        arg_text,
                    )
                {
                    subs.insert(tpl_name.clone(), ret_type);
                }
            }
            TemplateBindingMode::CallableParamType(position) => {
                // `@param Closure(T): void $cb` — extract the closure's
                // parameter type annotation at the given position.
                if let Some(param_type) =
                    crate::completion::source::helpers::extract_closure_param_type_from_text(
                        arg_text, position,
                    )
                {
                    subs.insert(tpl_name.clone(), param_type);
                }
            }
            TemplateBindingMode::ArrayElement => {
                // `@param T[] $items` — resolve individual array elements.
                if arg_text.starts_with('[') && arg_text.ends_with(']') {
                    let inner = arg_text[1..arg_text.len() - 1].trim();
                    if !inner.is_empty() {
                        let first_elem =
                            crate::completion::conditional_resolution::split_text_args(inner);
                        if let Some(elem) = first_elem.first()
                            && let Some(resolved_type) =
                                Backend::resolve_arg_text_to_type(elem.trim(), rctx)
                        {
                            subs.insert(tpl_name.clone(), resolved_type);
                        }
                    }
                } else if let Some(resolved_type) =
                    Backend::resolve_arg_text_to_type(arg_text, rctx)
                {
                    // Fallback: treat as direct if not an array literal.
                    subs.insert(tpl_name.clone(), resolved_type);
                }
            }
            TemplateBindingMode::GenericWrapper(ref wrapper_name, tpl_position) => {
                // For `@param array<TKey, TValue> $value` with a variable
                // argument like `$users`, resolve the variable's raw type
                // string (e.g. `User[]`, `array<int, User>`) and extract
                // the positional generic argument.
                if is_array_like_wrapper(wrapper_name)
                    && arg_text.starts_with('$')
                    && let Some(resolved) = resolve_arg_variable_raw_type(arg_text, rctx)
                    && let Some(concrete) = extract_array_type_at_position(&resolved, tpl_position)
                {
                    subs.insert(tpl_name.clone(), concrete);
                    continue;
                }
                // Fall back to direct resolution for non-array wrappers
                // or when raw type extraction fails.
                if let Some(resolved_type) = Backend::resolve_arg_text_to_type(arg_text, rctx) {
                    subs.insert(tpl_name.clone(), resolved_type);
                }
            }
        }
    }

    subs
}

/// Resolve a variable argument to its raw type string.
///
/// For `$pens` with `/** @var Pen[] $pens */`, returns `Some("Pen[]")`.
/// For `$users` with `/** @var array<int, User> $users */`, returns
/// `Some("array<int, User>")`.
///
/// Tries docblock annotations first, then falls back to AST-based
/// raw type inference.
fn resolve_arg_variable_raw_type(
    arg_text: &str,
    rctx: &crate::completion::resolver::ResolutionCtx<'_>,
) -> Option<PhpType> {
    let var_name = arg_text.trim();
    if !var_name.starts_with('$') {
        return None;
    }

    // ── Property chain: `$this->items`, `$obj->prop` ────────────
    // When the argument is a property access chain, resolve the base
    // object's type and look up the property's type hint.  This is
    // needed for template substitution in calls like
    // `array_any($this->items, fn($item) => …)` where `$this->items`
    // is `array<int, PurchaseFileProduct>` after generic substitution.
    if let Some(arrow_pos) = var_name.find("->") {
        let base = &var_name[..arrow_pos];
        let prop = &var_name[arrow_pos + 2..];
        // Only handle simple single-level property access for now.
        if !prop.is_empty() && !prop.contains("->") && !prop.contains('(') {
            let base_classes = ResolvedType::into_arced_classes(
                crate::completion::resolver::resolve_target_classes(
                    base,
                    crate::types::AccessKind::Arrow,
                    rctx,
                ),
            );
            for cls in &base_classes {
                if let Some(hint) =
                    crate::inheritance::resolve_property_type_hint(cls, prop, rctx.class_loader)
                {
                    return Some(hint);
                }
            }
        }
    }

    // 1. Try docblock annotation (@var).
    if let Some(raw) = crate::docblock::find_iterable_raw_type_in_source(
        rctx.content,
        rctx.cursor_offset as usize,
        var_name,
    ) {
        return Some(raw);
    }

    // 2. Fall back to unified variable resolution pipeline.
    let default_class = crate::types::ClassInfo::default();
    let current_class = rctx.current_class.unwrap_or(&default_class);
    let resolved = super::resolution::resolve_variable_types(
        var_name,
        current_class,
        rctx.all_classes,
        rctx.content,
        rctx.cursor_offset,
        rctx.class_loader,
        Loaders::with_function(rctx.function_loader),
    );
    if resolved.is_empty() {
        None
    } else {
        Some(ResolvedType::types_joined(&resolved))
    }
}

/// Extract the concrete type at `position` from an array type string.
///
/// For array types with two generic parameters (key + value):
/// - `array<int, User>` at position 0 → `"int"`, position 1 → `"User"`
/// - `User[]` at position 0 → `"int"` (implicit key), position 1 → `"User"`
/// - `list<User>` at position 0 → `"int"`, position 1 → `"User"`
///
/// For single-param forms:
/// - `array<User>` at position 0 → `"User"`
fn extract_array_type_at_position(ty: &PhpType, position: usize) -> Option<PhpType> {
    match position {
        0 => ty.extract_key_type(false).cloned(),
        1 => ty.extract_value_type(false).cloned(),
        _ => None,
    }
}

/// Whether a wrapper type name should be treated as array-like for
/// positional generic argument extraction.
///
/// When `@param Wrapper<TKey, TValue> $value` binds a template param
/// via `GenericWrapper`, and the wrapper is an array-like type, we can
/// resolve the argument variable's raw type (e.g. `User[]`) and extract
/// the positional generic component (key at 0, value at 1).
///
/// This covers `array`, `iterable`, `list`, and common Laravel/PHPStan
/// collection interfaces whose generic args follow `<TKey, TValue>`.
fn is_array_like_wrapper(name: &str) -> bool {
    matches!(
        name.to_ascii_lowercase().as_str(),
        "array" | "list" | "non-empty-array" | "non-empty-list" | "iterable"
    ) || crate::util::short_name(name).eq_ignore_ascii_case("arrayable")
}

/// Resolve function, method, and static method calls to their return
/// types.
fn resolve_rhs_call<'b>(
    call: &'b Call<'b>,
    expr: &'b Expression<'b>,
    ctx: &VarResolutionCtx<'_>,
) -> Vec<ResolvedType> {
    match call {
        Call::Function(func_call) => resolve_rhs_function_call(func_call, expr, ctx),
        Call::Method(method_call) => resolve_rhs_method_call_inner(
            method_call.object,
            &method_call.method,
            &method_call.argument_list,
            ctx,
        ),
        Call::NullSafeMethod(method_call) => resolve_rhs_method_call_inner(
            method_call.object,
            &method_call.method,
            &method_call.argument_list,
            ctx,
        ),
        Call::StaticMethod(static_call) => resolve_rhs_static_call(static_call, ctx),
    }
}

/// Resolve a plain function call: `someFunc()`, array functions, variable
/// invocations (`$fn()`), and conditional return types.
fn resolve_rhs_function_call<'b>(
    func_call: &'b FunctionCall<'b>,
    expr: &'b Expression<'b>,
    ctx: &VarResolutionCtx<'_>,
) -> Vec<ResolvedType> {
    let current_class_name: &str = &ctx.current_class.name;
    let all_classes = ctx.all_classes;
    let content = ctx.content;
    let class_loader = ctx.class_loader;
    let function_loader = ctx.function_loader();

    let func_name = match func_call.function {
        Expression::Identifier(ident) => Some(ident.value().to_string()),
        _ => None,
    };

    // ── Known array functions ────────────────────────
    // For element-extracting functions (array_pop, etc.)
    // resolve to the element ClassInfo directly.
    if let Some(ref name) = func_name
        && let Some(element_type) = super::raw_type_inference::resolve_array_func_element_type(
            name,
            &func_call.argument_list,
            ctx,
        )
    {
        let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
            &element_type,
            current_class_name,
            all_classes,
            class_loader,
        );
        if !resolved.is_empty() {
            return ResolvedType::from_classes_with_hint(resolved, element_type);
        }
    }

    // For type-preserving functions (array_filter, array_values, etc.)
    // the output has the same iterable type as the input array.
    // Return the full type string (e.g. `list<User>`) so that
    // downstream consumers (foreach, array access, hover) see the
    // element type without needing the raw-type pipeline's fallback.
    if let Some(ref name) = func_name
        && let Some(raw_type) = super::raw_type_inference::resolve_array_func_raw_type(
            name,
            &func_call.argument_list,
            ctx,
        )
    {
        let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
            &raw_type,
            current_class_name,
            all_classes,
            class_loader,
        );
        if !resolved.is_empty() {
            return ResolvedType::from_classes_with_hint(resolved, raw_type);
        }
        // The type string is informative (e.g. `list<User>`) but
        // doesn't resolve to a class — return as type-string-only.
        return vec![resolved_type_with_lookup(
            raw_type,
            current_class_name,
            all_classes,
            class_loader,
        )];
    }

    if let Some(ref name) = func_name
        && let Some(fl) = function_loader
        && let Some(func_info) = fl(name)
    {
        // Try conditional return type first
        if let Some(ref cond) = func_info.conditional_return {
            let var_resolver = build_var_resolver_from_ctx(ctx);
            let resolved_type = resolve_conditional_with_args(
                cond,
                &func_info.parameters,
                &func_call.argument_list,
                Some(&var_resolver),
                Some(current_class_name),
            );
            if let Some(ref ty) = resolved_type {
                let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
                    ty,
                    current_class_name,
                    all_classes,
                    class_loader,
                );
                if !resolved.is_empty() {
                    return ResolvedType::from_classes_with_hint(resolved, ty.clone());
                }
            }
        }

        // ── Function-level @template substitution ────────────
        // When the function has template params and bindings,
        // infer concrete types from the arguments and apply
        // substitution to the return type before resolving.
        if !func_info.template_params.is_empty()
            && !func_info.template_bindings.is_empty()
            && func_info.return_type.is_some()
        {
            let text_args =
                super::raw_type_inference::extract_argument_text(&func_call.argument_list, content);
            if !text_args.is_empty() {
                let rctx = ctx.as_resolution_ctx();
                let subs = build_function_template_subs(&func_info, &text_args, &rctx);
                if !subs.is_empty()
                    && let Some(ref ret) = func_info.return_type
                {
                    let substituted = ret.substitute(&subs);
                    let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
                        &substituted,
                        current_class_name,
                        all_classes,
                        class_loader,
                    );
                    if !resolved.is_empty() {
                        return ResolvedType::from_classes_with_hint(resolved, substituted);
                    }
                }
            }
        }

        if let Some(ref ret) = func_info.return_type {
            let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
                ret,
                current_class_name,
                all_classes,
                class_loader,
            );
            if !resolved.is_empty() {
                return ResolvedType::from_classes_with_hint(resolved, ret.clone());
            }
            // The function has a return type string but
            // `type_hint_to_classes_typed` found no matching class (e.g.
            // `list<Widget>`, `int`, `array{name: string}`).  Return a
            // type-string-only entry so that consumers reading
            // `.type_string` still get the information.
            //
            // When the return type is `void`, PHP yields `null` at
            // runtime — mirror that so the variable type is correct.
            if *ret == PhpType::void() {
                return vec![ResolvedType::from_type_string(PhpType::null())];
            }
            return vec![resolved_type_with_lookup(
                ret.clone(),
                current_class_name,
                all_classes,
                class_loader,
            )];
        }
    }

    // ── Source-scanning fallback for named function calls ────
    // When no function_loader is available (e.g. raw-type pipeline,
    // test backends without PSR-4), scan the source text for the
    // function's docblock @return annotation.  This covers standalone
    // function calls when no function_loader is available.
    if let Some(ref name) = func_name
        && function_loader.is_none()
        && let Some(ret) =
            crate::completion::source::helpers::extract_function_return_from_source(name, content)
    {
        let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
            &ret,
            current_class_name,
            all_classes,
            class_loader,
        );
        if !resolved.is_empty() {
            return ResolvedType::from_classes_with_hint(resolved, ret);
        }
        if ret == PhpType::void() {
            return vec![ResolvedType::from_type_string(PhpType::null())];
        }
        return vec![resolved_type_with_lookup(
            ret,
            current_class_name,
            all_classes,
            class_loader,
        )];
    }

    // ── Variable invocation: $fn() ──────────────────
    // When the callee is a variable (not a named function),
    // resolve the variable's type annotation for a
    // callable/Closure return type, or look for a
    // closure/arrow-function literal in the assignment.
    if let Expression::Variable(Variable::Direct(dv)) = func_call.function {
        let var_name = dv.name.to_string();
        let offset = expr.span().start.offset as usize;

        // 1. Try docblock annotation:
        //    `@var Closure(): User $fn` or
        //    `@param callable(int): Response $fn`
        if let Some(raw_type) =
            crate::docblock::find_iterable_raw_type_in_source(content, offset, &var_name)
            && let Some(ret_type) = raw_type.callable_return_type()
        {
            let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
                ret_type,
                current_class_name,
                all_classes,
                class_loader,
            );
            if !resolved.is_empty() {
                return ResolvedType::from_classes_with_hint(resolved, ret_type.clone());
            }
        }

        // 2. Scan for closure literal assignment and
        //    extract native return type hint.
        if let Some(ret) =
            crate::completion::source::helpers::extract_closure_return_type_from_assignment(
                &var_name,
                content,
                ctx.cursor_offset,
            )
        {
            let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
                &ret,
                current_class_name,
                all_classes,
                class_loader,
            );
            if !resolved.is_empty() {
                return ResolvedType::from_classes_with_hint(resolved, ret);
            }
        }

        // 3. Scan backward for first-class callable assignment:
        //    `$fn = strlen(...)`, `$fn = $obj->method(...)`, or
        //    `$fn = ClassName::staticMethod(...)`.
        //    Resolve the underlying function/method's return type.
        let rctx = ctx.as_resolution_ctx();
        if let Some(ret) =
            crate::completion::source::helpers::extract_first_class_callable_return_type(
                &var_name, &rctx,
            )
        {
            let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
                &ret,
                current_class_name,
                all_classes,
                class_loader,
            );
            if !resolved.is_empty() {
                return ResolvedType::from_classes_with_hint(resolved, ret);
            }
        }

        // 4. Resolve the variable's type and check for __invoke().
        //    When $f holds an object with an __invoke() method,
        //    $f() should return __invoke()'s return type.
        let rctx = ctx.as_resolution_ctx();
        let var_classes =
            ResolvedType::into_arced_classes(crate::completion::resolver::resolve_target_classes(
                &var_name,
                crate::types::AccessKind::Arrow,
                &rctx,
            ));
        for owner in &var_classes {
            if let Some(invoke) = owner.methods.iter().find(|m| m.name == "__invoke")
                && let Some(ref ret) = invoke.return_type
            {
                let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
                    ret,
                    current_class_name,
                    all_classes,
                    class_loader,
                );
                if !resolved.is_empty() {
                    return ResolvedType::from_classes_with_hint(resolved, ret.clone());
                }
                // When type_hint_to_classes_typed can't resolve the return
                // type (e.g. `Item[]` where the `[]` suffix prevents
                // class lookup), emit a type-string-only entry so that
                // callers like foreach resolution can still extract the
                // element type via `PhpType::extract_value_type`.
                if !ret.is_empty() {
                    return vec![resolved_type_with_lookup(
                        ret.clone(),
                        current_class_name,
                        all_classes,
                        class_loader,
                    )];
                }
            }
        }
    }

    // ── General expression invocation: ($expr)() ────
    // When the callee is an arbitrary expression (e.g.
    // `($this->foo)()`, `(getFactory())()`, etc.), resolve
    // the expression to classes and check for __invoke().
    let callee_expr = match func_call.function {
        Expression::Parenthesized(p) => p.expression,
        other => other,
    };
    // Skip if we already handled it as a variable above.
    if !matches!(callee_expr, Expression::Variable(Variable::Direct(_))) {
        // ── Directly invoked closure / arrow function ────
        // `(fn (): Foo => …)()` or `(function (): Foo { … })()`
        // Extract the return type from the literal instead of going
        // through `__invoke()` on the generic `Closure` stub.
        if let Some(parsed_ret_type) = extract_closure_or_arrow_return_type(callee_expr) {
            let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
                &parsed_ret_type,
                current_class_name,
                all_classes,
                class_loader,
            );
            if !resolved.is_empty() {
                return ResolvedType::from_classes_with_hint(resolved, parsed_ret_type);
            }
        }

        let callee_results = resolve_rhs_expression(callee_expr, ctx);
        for rt in &callee_results {
            if let Some(ref owner_cls) = rt.class_info
                && let Some(invoke) = owner_cls.methods.iter().find(|m| m.name == "__invoke")
                && let Some(ref ret) = invoke.return_type
            {
                let resolved = crate::completion::type_resolution::type_hint_to_classes_typed(
                    ret,
                    current_class_name,
                    all_classes,
                    class_loader,
                );
                if !resolved.is_empty() {
                    return ResolvedType::from_classes_with_hint(resolved, ret.clone());
                }
                if !ret.is_empty() {
                    return vec![resolved_type_with_lookup(
                        ret.clone(),
                        current_class_name,
                        all_classes,
                        class_loader,
                    )];
                }
            }
        }
    }

    vec![]
}

/// Resolve an instance method call: `$this->method()`, `$var->method()`,
/// chained calls, and other object expressions via AST-based resolution.
/// Resolve a method call (regular or null-safe) from its constituent parts.
///
/// Both `$obj->method()` and `$obj?->method()` share the same resolution
/// logic — the null-safe operator only affects whether `null` propagates
/// at runtime, not which class the method belongs to.
fn resolve_rhs_method_call_inner<'b>(
    object: &'b Expression<'b>,
    method: &'b ClassLikeMemberSelector<'b>,
    argument_list: &'b ArgumentList<'b>,
    ctx: &VarResolutionCtx<'_>,
) -> Vec<ResolvedType> {
    let method_name = match method {
        ClassLikeMemberSelector::Identifier(ident) => ident.value.to_string(),
        // Variable method name (`$obj->$method()`) — can't resolve statically.
        _ => return vec![],
    };
    // Resolve the object expression to candidate owner classes.
    // Keep the full `ResolvedType` for non-$this variables and chain
    // expressions so that the receiver's generic type string (e.g.
    // `Builder<Article>`) is available when the method returns
    // `static`/`self`/`$this`.
    let (owner_classes, receiver_resolved): (Vec<ClassInfo>, Vec<ResolvedType>) =
        if let Expression::Variable(Variable::Direct(dv)) = object
            && dv.name == "$this"
        {
            let classes: Vec<ClassInfo> = ctx
                .all_classes
                .iter()
                .find(|c| c.name == ctx.current_class.name)
                .map(|c| ClassInfo::clone(c))
                .into_iter()
                .collect();
            (classes, vec![])
        } else if let Expression::Variable(Variable::Direct(dv)) = object {
            let var = dv.name.to_string();
            let resolved = crate::completion::variable::resolution::resolve_variable_types(
                &var,
                ctx.current_class,
                ctx.all_classes,
                ctx.content,
                // Use the object's end offset so preceding assignments
                // are visible but the current assignment is not.
                object.span().end.offset,
                ctx.class_loader,
                crate::completion::resolver::Loaders::with_function(ctx.function_loader()),
            );
            if !resolved.is_empty() {
                let classes = ResolvedType::into_classes(resolved.clone());
                (classes, resolved)
            } else {
                // Fall back to resolve_target_classes when the
                // variable resolution pipeline returns nothing (e.g.
                // for parameters that are resolved through the
                // completion pipeline's subject resolution).
                let classes: Vec<ClassInfo> = ResolvedType::into_classes(
                    crate::completion::resolver::resolve_target_classes(
                        &var,
                        crate::types::AccessKind::Arrow,
                        &ctx.as_resolution_ctx(),
                    ),
                );
                (classes, vec![])
            }
        } else {
            // Handle non-variable object expressions like
            // `(new Factory())->create()`, `getService()->method()`,
            // or chained calls by recursively resolving the expression.
            let resolved = resolve_rhs_expression(object, ctx);
            let classes = ResolvedType::into_classes(resolved.clone());
            (classes, resolved)
        };

    let text_args = super::raw_type_inference::extract_argument_text(argument_list, ctx.content);
    let rctx = ctx.as_resolution_ctx();
    let var_resolver = build_var_resolver_from_ctx(ctx);

    for owner in &owner_classes {
        let template_subs =
            Backend::build_method_template_subs(owner, &method_name, &text_args, &rctx);
        let mr_ctx = MethodReturnCtx {
            all_classes: ctx.all_classes,
            class_loader: ctx.class_loader,
            template_subs: &template_subs,
            var_resolver: Some(&var_resolver),
            cache: ctx.resolved_class_cache,
            calling_class_name: Some(&ctx.current_class.name),
            is_static: false,
        };
        // Recover the effective return type string from the method.
        // Look up the method on the (possibly merged) owner and apply
        // the same template substitution that
        // `resolve_method_return_types_with_args` used internally,
        // then replace `static`/`self`/`$this` with the owner class
        // name (or the receiver's full generic type when available)
        // so that e.g. `static[]` becomes `Country[]` and a bare
        // `static` on `Builder<Article>` becomes `Builder<Article>`.
        let merged = crate::virtual_members::resolve_class_fully(owner, ctx.class_loader);
        let ret_type_string = merged
            .methods
            .iter()
            .find(|m| m.name == method_name)
            .and_then(|m| m.return_type.as_ref())
            .map(|ret| {
                let substituted = if !template_subs.is_empty() {
                    ret.substitute(&template_subs)
                } else {
                    ret.clone()
                };
                // When the return type contains `static`/`self`/`$this`
                // and the receiver was resolved with generic parameters,
                // use the receiver's full type (e.g. `Builder<Article>`)
                // for substitution so the generics are preserved.
                let receiver_type = if substituted.contains_self_ref() {
                    receiver_type_for_owner(&receiver_resolved, &owner.name)
                } else {
                    None
                };
                match receiver_type {
                    Some(rt) => substituted.replace_self_with_type(&rt),
                    None => substituted.replace_self(&owner.name),
                }
            });

        let results = Backend::resolve_method_return_types_with_args(
            owner,
            &method_name,
            &text_args,
            &mr_ctx,
        );
        if !results.is_empty() {
            let classes: Vec<ClassInfo> = results.into_iter().map(Arc::unwrap_or_clone).collect();
            // When the method has a conditional return type, the
            // resolved classes came from evaluating the conditional
            // (e.g. `$type is class-string<T> ? T : mixed` resolved
            // to the concrete class).  In that case, using the
            // method's declared return type (typically `mixed`) as
            // the type hint would be misleading.  Skip it so that
            // `from_classes` uses the resolved class names instead.
            let has_conditional = merged
                .methods
                .iter()
                .any(|m| m.name == method_name && m.conditional_return.is_some());
            let effective_hint = if has_conditional {
                None
            } else {
                ret_type_string
            };
            return match effective_hint {
                Some(hint) => ResolvedType::from_classes_with_hint(classes, hint),
                None => ResolvedType::from_classes(classes),
            };
        }

        // The method has a return type string but `type_hint_to_classes_typed`
        // found no matching class (e.g. `list<Widget>`, `int`,
        // `array{name: string}`).  Return a type-string-only entry so
        // that consumers reading `.type_string` (hover, foreach
        // resolution, null-coalesce stripping) still get the information.
        //
        // Return the type string even for non-informative types like
        // `array` or `mixed` — a correct-but-vague type is better
        // than keeping the previous (wrong) type after reassignment.
        // Skip only `void` (void methods don't produce a value).
        // Also expand type aliases before returning so that
        // `@phpstan-type UserList array<int, User>` with
        // `@return UserList` is expanded to its concrete type.
        if let Some(ref hint) = ret_type_string {
            let expanded = crate::completion::type_resolution::resolve_type_alias_typed(
                hint,
                &owner.name,
                ctx.all_classes,
                ctx.class_loader,
            );
            let parsed_effective = match expanded {
                Some(e) => e,
                None => hint.clone(),
            };
            if parsed_effective == PhpType::void() {
                return vec![ResolvedType::from_type_string(PhpType::null())];
            }
            return vec![resolved_type_with_lookup(
                parsed_effective,
                &ctx.current_class.name,
                ctx.all_classes,
                ctx.class_loader,
            )];
        }
    }
    vec![]
}

/// Find the receiver's type string that matches the given owner class name.
///
/// Scans `receiver_resolved` for a `ResolvedType` whose `class_info`
/// name matches `owner_name` and whose `type_string` is a `Generic`
/// (i.e. carries generic parameters like `Builder<Article>`).  Returns
/// the matching `PhpType` so that `replace_self_with_type` can preserve
/// those generic parameters when the method returns `static`/`self`/`$this`.
fn receiver_type_for_owner(
    receiver_resolved: &[ResolvedType],
    owner_name: &str,
) -> Option<PhpType> {
    for rt in receiver_resolved {
        let matches = rt
            .class_info
            .as_ref()
            .is_some_and(|ci| ci.name == owner_name)
            && matches!(rt.type_string, PhpType::Generic(_, _));
        if matches {
            return Some(rt.type_string.clone());
        }
    }
    None
}

/// Resolve a static method call: `ClassName::method()`, `self::method()`,
/// `static::method()`.
fn resolve_rhs_static_call(
    static_call: &StaticMethodCall<'_>,
    ctx: &VarResolutionCtx<'_>,
) -> Vec<ResolvedType> {
    let current_class_name: &str = &ctx.current_class.name;

    let class_name = match static_call.class {
        Expression::Self_(_) => Some(current_class_name.to_string()),
        Expression::Static(_) => Some(current_class_name.to_string()),
        Expression::Parent(_) => ctx.current_class.parent_class.clone(),
        Expression::Identifier(ident) => Some(ident.value().to_string()),
        // ── `$var::method()` where `$var` holds a class-string ──
        Expression::Variable(Variable::Direct(dv)) => {
            let var_name = dv.name.to_string();
            let targets =
                crate::completion::variable::class_string_resolution::resolve_class_string_targets(
                    &var_name,
                    ctx.current_class,
                    ctx.all_classes,
                    ctx.content,
                    ctx.cursor_offset,
                    ctx.class_loader,
                );
            if let Some(first) = targets.first() {
                Some(first.name.clone())
            } else {
                // Fallback: resolve the variable's type and extract the
                // inner type from `class-string<T>`.  This handles
                // parameters typed as `@param class-string<Foo> $var`
                // where there is no `$var = Foo::class` assignment.
                let resolved = super::resolution::resolve_variable_types(
                    &var_name,
                    ctx.current_class,
                    ctx.all_classes,
                    ctx.content,
                    ctx.cursor_offset,
                    ctx.class_loader,
                    Loaders::with_function(ctx.function_loader()),
                );
                resolved.iter().find_map(|rt| match &rt.type_string {
                    PhpType::ClassString(Some(inner)) => inner.base_name().map(|s| s.to_string()),
                    PhpType::Nullable(inner) => match inner.as_ref() {
                        PhpType::ClassString(Some(cs_inner)) => {
                            cs_inner.base_name().map(|s| s.to_string())
                        }
                        _ => None,
                    },
                    PhpType::Union(members) => members.iter().find_map(|m| match m {
                        PhpType::ClassString(Some(inner)) => {
                            inner.base_name().map(|s| s.to_string())
                        }
                        PhpType::Nullable(inner) => match inner.as_ref() {
                            PhpType::ClassString(Some(cs_inner)) => {
                                cs_inner.base_name().map(|s| s.to_string())
                            }
                            _ => None,
                        },
                        _ => None,
                    }),
                    _ => None,
                })
            }
        }
        _ => None,
    };
    if let Some(cls_name) = class_name
        && let ClassLikeMemberSelector::Identifier(ident) = &static_call.method
    {
        let method_name = ident.value.to_string();
        let owner = ctx
            .all_classes
            .iter()
            .find(|c| c.name == cls_name)
            .map(|c| ClassInfo::clone(c))
            .or_else(|| (ctx.class_loader)(&cls_name).map(Arc::unwrap_or_clone));
        if let Some(ref owner) = owner {
            let text_args = super::raw_type_inference::extract_argument_text(
                &static_call.argument_list,
                ctx.content,
            );
            let rctx = ctx.as_resolution_ctx();
            let template_subs =
                Backend::build_method_template_subs(owner, &method_name, &text_args, &rctx);
            let var_resolver = build_var_resolver_from_ctx(ctx);
            let mr_ctx = MethodReturnCtx {
                all_classes: ctx.all_classes,
                class_loader: ctx.class_loader,
                template_subs: &template_subs,
                var_resolver: Some(&var_resolver),
                cache: ctx.resolved_class_cache,
                calling_class_name: Some(&ctx.current_class.name),
                is_static: true,
            };
            // Recover the effective return type string from the method.
            // Look up the method on the (possibly merged) owner and apply
            // the same template substitution that
            // `resolve_method_return_types_with_args` used internally,
            // then replace `static`/`self`/`$this` with the owner class
            // name so that e.g. `static[]` becomes `Country[]`.
            let merged = crate::virtual_members::resolve_class_fully(owner, ctx.class_loader);
            let ret_type_string = merged
                .methods
                .iter()
                .find(|m| m.name == method_name)
                .and_then(|m| m.return_type.as_ref())
                .map(|ret| {
                    let substituted = if !template_subs.is_empty() {
                        ret.substitute(&template_subs)
                    } else {
                        ret.clone()
                    };
                    substituted.replace_self(&owner.name)
                });

            let results = Backend::resolve_method_return_types_with_args(
                owner,
                &method_name,
                &text_args,
                &mr_ctx,
            );
            if !results.is_empty() {
                let classes: Vec<ClassInfo> =
                    results.into_iter().map(Arc::unwrap_or_clone).collect();
                // When the method has a conditional return type, the
                // resolved classes came from evaluating the conditional.
                // Using the method's declared return type (typically
                // `mixed`) as the type hint would be misleading.
                let has_conditional = merged
                    .methods
                    .iter()
                    .any(|m| m.name == method_name && m.conditional_return.is_some());
                let effective_hint = if has_conditional {
                    None
                } else {
                    ret_type_string
                };
                return match effective_hint {
                    Some(hint) => ResolvedType::from_classes_with_hint(classes, hint),
                    None => ResolvedType::from_classes(classes),
                };
            }

            // The method has a return type string but `type_hint_to_classes_typed`
            // found no matching class (e.g. `list<Widget>`, `int`,
            // `array{name: string}`).  Return a type-string-only entry so
            // that consumers reading `.type_string` (hover, raw-type
            // pipeline, null-coalesce stripping) still get the information.
            if let Some(ref hint) = ret_type_string {
                if *hint == PhpType::void() {
                    return vec![ResolvedType::from_type_string(PhpType::null())];
                }
                return vec![resolved_type_with_lookup(
                    hint.clone(),
                    current_class_name,
                    ctx.all_classes,
                    ctx.class_loader,
                )];
            }
        }
    }
    vec![]
}

/// Resolve property access: `$this->prop`, `$obj->prop`, `$obj?->prop`.
fn resolve_rhs_property_access(
    access: &Access<'_>,
    ctx: &VarResolutionCtx<'_>,
) -> Vec<ResolvedType> {
    let current_class_name: &str = &ctx.current_class.name;
    let all_classes = ctx.all_classes;
    let class_loader = ctx.class_loader;

    /// Resolve a property's type to `Vec<ResolvedType>`, preserving the
    /// property's type hint string in each result.
    ///
    /// When the property type is a scalar (e.g. `string`, `int`) and
    /// `type_hint_to_classes_typed` returns no `ClassInfo`, a type-string-only
    /// `ResolvedType` is produced so that the type information is not lost.
    fn resolve_property_with_hint(
        prop_name: &str,
        owner: &ClassInfo,
        current_class_name: &str,
        all_classes: &[Arc<ClassInfo>],
        class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
    ) -> Vec<ResolvedType> {
        // Get the type hint before resolving to ClassInfo.
        let type_hint =
            crate::inheritance::resolve_property_type_hint(owner, prop_name, class_loader);
        let resolved = crate::completion::type_resolution::resolve_property_types(
            prop_name,
            owner,
            all_classes,
            class_loader,
        );
        if resolved.is_empty() {
            // The property has a type hint but `type_hint_to_classes_typed`
            // found no matching class (e.g. `list<Widget>`, `int`,
            // `array{name: string}`).  Return a type-string-only
            // entry when the type is informative (carries generics,
            // shapes, or names a non-scalar class).
            return match type_hint {
                Some(hint) => {
                    vec![resolved_type_with_lookup(
                        hint,
                        current_class_name,
                        all_classes,
                        class_loader,
                    )]
                }
                _ => vec![],
            };
        }
        match type_hint {
            Some(hint) => ResolvedType::from_classes_with_hint(resolved, hint),
            None => ResolvedType::from_classes(resolved),
        }
    }

    // ── Class constant / enum case access: `Foo::BAR` ──
    // When the RHS is a class constant access, resolve the class and
    // check whether the constant is an enum case (→ type is the enum
    // itself) or a typed constant (→ use its type_hint).
    if let Access::ClassConstant(cca) = access {
        let class_name = match cca.class {
            Expression::Identifier(ident) => Some(ident.value().to_string()),
            Expression::Self_(_) => Some(current_class_name.to_string()),
            Expression::Static(_) => Some(current_class_name.to_string()),
            _ => None,
        };
        if let Some(class_name) = class_name {
            let resolved_name = class_name.strip_prefix('\\').unwrap_or(&class_name);
            let resolved_typed = PhpType::Named(resolved_name.to_string());
            let target_classes = crate::completion::type_resolution::type_hint_to_classes_typed(
                &resolved_typed,
                current_class_name,
                all_classes,
                class_loader,
            );

            let const_name = match &cca.constant {
                ClassLikeConstantSelector::Identifier(ident) => Some(ident.value.to_string()),
                _ => None,
            };

            if let Some(const_name) = const_name {
                for cls in &target_classes {
                    // Check if the constant is an enum case — the
                    // result type is the enum class itself.
                    if let Some(c) = cls.constants.iter().find(|c| c.name == const_name) {
                        if c.is_enum_case {
                            return ResolvedType::from_classes(target_classes);
                        }
                        // Typed class constant — resolve via type_hint.
                        if let Some(ref th) = c.type_hint {
                            let resolved =
                                crate::completion::type_resolution::type_hint_to_classes_typed(
                                    th,
                                    current_class_name,
                                    all_classes,
                                    class_loader,
                                );
                            if !resolved.is_empty() {
                                return ResolvedType::from_classes_with_hint(resolved, th.clone());
                            }
                        }
                        // No type_hint — infer from the initializer value.
                        if let Some(ref val) = c.value
                            && let Some(ts) = infer_type_from_constant_value(val)
                        {
                            let resolved =
                                crate::completion::type_resolution::type_hint_to_classes_typed(
                                    &ts,
                                    current_class_name,
                                    all_classes,
                                    class_loader,
                                );
                            if !resolved.is_empty() {
                                return ResolvedType::from_classes_with_hint(resolved, ts);
                            }
                            return vec![ResolvedType::from_type_string(ts)];
                        }
                    }
                }
            }
        }
        return vec![];
    }

    let (object_expr, prop_selector) = match access {
        Access::Property(pa) => (Some(pa.object), Some(&pa.property)),
        Access::NullSafeProperty(pa) => (Some(pa.object), Some(&pa.property)),
        _ => (None, None),
    };
    if let Some(obj) = object_expr
        && let Some(sel) = prop_selector
    {
        let prop_name = match sel {
            ClassLikeMemberSelector::Identifier(ident) => Some(ident.value.to_string()),
            _ => None,
        };
        if let Some(prop_name) = prop_name {
            let owner_classes: Vec<ClassInfo> = if let Expression::Variable(Variable::Direct(dv)) =
                obj
                && dv.name == "$this"
            {
                all_classes
                    .iter()
                    .find(|c| c.name == current_class_name)
                    .map(|c| ClassInfo::clone(c))
                    .into_iter()
                    .collect()
            } else if let Expression::Variable(Variable::Direct(dv)) = obj {
                let var = dv.name.to_string();
                ResolvedType::into_classes(crate::completion::resolver::resolve_target_classes(
                    &var,
                    crate::types::AccessKind::Arrow,
                    &ctx.as_resolution_ctx(),
                ))
            } else {
                // Handle non-variable object expressions like
                // `(new Canvas())->easel`, `getService()->prop`,
                // or `SomeClass::make()->prop` by recursively
                // resolving the expression type.
                ResolvedType::into_classes(resolve_rhs_expression(obj, ctx))
            };

            for owner in &owner_classes {
                let resolved = resolve_property_with_hint(
                    &prop_name,
                    owner,
                    current_class_name,
                    all_classes,
                    class_loader,
                );
                if !resolved.is_empty() {
                    return resolved;
                }
            }
        }
    }
    vec![]
}

/// Resolve `clone $expr` — preserves the cloned expression's type.
///
/// First tries resolving the inner expression structurally (handles
/// `clone new Foo()`, `clone $this->getConfig()`, ternary, etc.).
/// If that yields nothing, falls back to text-based resolution by
/// extracting the source text of the cloned expression and resolving
/// it as a subject string via `resolve_target_classes`.
fn resolve_rhs_clone(clone_expr: &Clone<'_>, ctx: &VarResolutionCtx<'_>) -> Vec<ResolvedType> {
    let structural = resolve_rhs_expression(clone_expr.object, ctx);
    if !structural.is_empty() {
        return structural;
    }
    // Fallback: extract source text of the cloned expression
    // and resolve it as a subject.  This handles cases like
    // `clone $original` where `$original`'s type was set by a
    // prior assignment or parameter type hint.
    let obj_span = clone_expr.object.span();
    let start = obj_span.start.offset as usize;
    let end = obj_span.end.offset as usize;
    if end <= ctx.content.len() {
        let obj_text = ctx.content[start..end].trim();
        if !obj_text.is_empty() {
            let rctx = ctx.as_resolution_ctx();
            return crate::completion::resolver::resolve_target_classes(
                obj_text,
                crate::types::AccessKind::Arrow,
                &rctx,
            );
        }
    }
    vec![]
}

/// Extract the return type hint from a closure or arrow function expression.
///
/// Returns the type-hint string when the expression is a `Closure` or
/// `ArrowFunction` with an explicit return type annotation, e.g.
/// `fn (): Foo => …` yields `"Foo"`.  Returns `None` otherwise.
fn extract_closure_or_arrow_return_type(expr: &Expression<'_>) -> Option<PhpType> {
    match expr {
        Expression::ArrowFunction(arrow) => arrow
            .return_type_hint
            .as_ref()
            .map(|rth| extract_hint_type(&rth.hint)),
        Expression::Closure(closure) => closure
            .return_type_hint
            .as_ref()
            .map(|rth| extract_hint_type(&rth.hint)),
        _ => None,
    }
}

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

    #[test]
    fn classify_direct_param() {
        let ty = PhpType::parse("T");
        let mode = classify_template_binding("T", Some(&ty));
        assert!(matches!(mode, TemplateBindingMode::Direct));
    }

    #[test]
    fn classify_array_element() {
        let ty = PhpType::parse("T[]");
        let mode = classify_template_binding("T", Some(&ty));
        assert!(matches!(mode, TemplateBindingMode::ArrayElement));
    }

    #[test]
    fn classify_generic_wrapper() {
        let ty = PhpType::parse("Collection<T>");
        let mode = classify_template_binding("T", Some(&ty));
        assert!(matches!(mode, TemplateBindingMode::GenericWrapper(_, 0)));
    }

    #[test]
    fn classify_callable_return_type() {
        let ty =
            PhpType::parse("callable(TReduceInitial|TReduceReturnType, TValue): TReduceReturnType");
        let mode = classify_template_binding("TReduceReturnType", Some(&ty));
        assert!(matches!(mode, TemplateBindingMode::CallableReturnType));
    }

    #[test]
    fn classify_closure_return_type() {
        let ty = PhpType::parse("Closure(int, string): T");
        let mode = classify_template_binding("T", Some(&ty));
        assert!(matches!(mode, TemplateBindingMode::CallableReturnType));
    }

    #[test]
    fn classify_callable_param_type() {
        // Template appears only in params, not in return type — should be CallableParamType.
        let ty = PhpType::parse("callable(T): void");
        let mode = classify_template_binding("T", Some(&ty));
        assert!(matches!(mode, TemplateBindingMode::CallableParamType(0)));
    }

    #[test]
    fn classify_callable_param_type_second_position() {
        let ty = PhpType::parse("Closure(int, T): void");
        let mode = classify_template_binding("T", Some(&ty));
        assert!(matches!(mode, TemplateBindingMode::CallableParamType(1)));
    }

    #[test]
    fn classify_callable_return_type_preferred_over_param() {
        // When T appears in both params and return type, return type wins.
        let ty = PhpType::parse("callable(T): T");
        let mode = classify_template_binding("T", Some(&ty));
        assert!(matches!(mode, TemplateBindingMode::CallableReturnType));
    }

    #[test]
    fn classify_nullable_union_callable() {
        // Template in callable return type within a union.
        let ty = PhpType::parse("callable(int): T|null");
        let mode = classify_template_binding("T", Some(&ty));
        assert!(matches!(mode, TemplateBindingMode::CallableReturnType));
    }

    #[test]
    fn classify_none_hint() {
        let mode = classify_template_binding("T", None);
        assert!(matches!(mode, TemplateBindingMode::Direct));
    }

    #[test]
    fn type_contains_name_simple() {
        let ty = PhpType::Named("Foo".to_owned());
        assert!(type_contains_name(&ty, "Foo"));
        assert!(!type_contains_name(&ty, "Bar"));
    }

    #[test]
    fn type_contains_name_nested_callable() {
        let ty = PhpType::parse("callable(int): Decimal");
        assert!(type_contains_name(&ty, "Decimal"));
        assert!(type_contains_name(&ty, "int"));
        assert!(!type_contains_name(&ty, "string"));
    }

    #[test]
    fn type_contains_name_union() {
        let ty = PhpType::parse("Foo|Bar|null");
        assert!(type_contains_name(&ty, "Foo"));
        assert!(type_contains_name(&ty, "Bar"));
        assert!(type_contains_name(&ty, "null"));
        assert!(!type_contains_name(&ty, "Baz"));
    }
}