mir-analyzer 0.85.0

mod args;
mod array_builtins;
mod callable;
mod function;
pub(crate) mod method;
mod opaque_callback;
mod static_call;

pub(crate) use args::substitute_static_in_return;
pub use args::{
    check_constructor_args, distinct_spans_for_expansion, expand_sole_spread_arg,
    spread_element_type, CheckArgsParams,
};
pub(crate) use callable::callable_string_token_span;
pub(crate) use function::extract_class_docblock;
pub(crate) use static_call::resolve_literal_class_scope;

pub struct CallAnalyzer;

/// Resolve a declared parameter's own textual argument position at a call
/// site — the index into `arg_types` (built in call-site TEXTUAL order),
/// not the parameter's own DECLARED index. The two differ when a named
/// argument reorders the call, so `resolve_conditional_returns`'s call sites
/// (`@return ($x is T ? A : B)`) must not index `arg_types` by declared
/// position. Mirrors `narrowing/assertions.rs`'s `arg_for_param_index`.
pub(crate) fn resolve_named_arg_type_index(
    params: &[mir_codebase::definitions::DeclaredParam],
    call_args: &[php_ast::owned::Arg],
    param_index: usize,
) -> Option<usize> {
    let param_name = params.get(param_index)?.name.as_ref();
    if let Some(idx) = call_args.iter().position(|a| {
        a.name
            .as_ref()
            .is_some_and(|n| crate::parser::name_to_string_owned(n) == param_name)
    }) {
        return Some(idx);
    }
    call_args
        .iter()
        .enumerate()
        .filter(|(_, a)| a.name.is_none())
        .nth(param_index)
        .map(|(i, _)| i)
}

/// `@return ($this is X ? A : B)` / `@return ($param is X ? A : B)` /
/// `@return (T is X ? A : B)` where
/// `X` is a CLASS name: `Type::resolve_conditional_returns` alone can never
/// resolve this, even once the discriminator's argument type is looked up
/// correctly — it's purely structural (`mir-types` has no `db`, so no
/// ancestor walk) and its closed predicate set (null/true/false/string/
/// list/array/int/float/bool) has no arm for an object atom at all, so an
/// object-typed subject always falls through to "unresolvable, widen to
/// the union of both branches" regardless of the looked-up argument.
/// Pre-resolves exactly that one shape (a single top-level `TConditional`
/// atom whose subject and looked-up argument are both object-like) via
/// `subtype::is_subtype`, then defers to the existing structural resolver
/// for every other shape (scalar discriminant, non-single-atomic type,
/// nested conditionals in the chosen branch) unchanged.
pub(crate) fn resolve_conditional_return<F>(
    ty: mir_types::Type,
    db: &dyn crate::db::MirDatabase,
    templates: Option<&rustc_hash::FxHashMap<mir_types::Name, mir_types::Type>>,
    lookup: F,
) -> mir_types::Type
where
    F: Fn(&str) -> Option<mir_types::Type>,
{
    let mut resolved = mir_types::Type::empty();
    for atomic in ty.types {
        let mir_types::Atomic::TConditional { data } = &atomic else {
            resolved.add_type(atomic);
            continue;
        };
        match resolve_class_subject_branch(data, db, templates, &lookup) {
            Some(branch) => resolved.merge_with(&branch),
            None => resolved
                .merge_with(&mir_types::Type::single(atomic).resolve_conditional_returns(&lookup)),
        }
    }
    resolved
}

/// The chosen branch of a conditional whose subject and discriminant are both
/// object types, resolved through `is_subtype`.
fn resolve_class_subject_branch<F>(
    data: &mir_types::atomic::ConditionalData,
    db: &dyn crate::db::MirDatabase,
    templates: Option<&rustc_hash::FxHashMap<mir_types::Name, mir_types::Type>>,
    lookup: &F,
) -> Option<mir_types::Type>
where
    F: Fn(&str) -> Option<mir_types::Type>,
{
    let is_object = |ty: &mir_types::Type, allow_case: bool| {
        !ty.types.is_empty()
            && ty.types.iter().all(|a| {
                a.named_object_fqcn()
                    .is_some_and(|f| allow_case || !f.contains("::"))
            })
    };
    // `Class::CASE` subjects are enum cases, which arg types do not track.
    if !is_object(&data.subject, false) {
        return None;
    }
    let param_name = data.param_name.as_ref()?;
    // `T is X`: `T` is a template, bound rather than a parameter.
    let arg_ty = lookup(param_name.as_ref())
        .or_else(|| templates.and_then(|t| t.get(param_name).cloned()))?;
    if !is_object(&arg_ty, true) {
        return None;
    }
    let branch = if crate::subtype::is_subtype(db, &arg_ty, &data.subject) {
        data.if_true.clone()
    } else {
        data.if_false.clone()
    };
    Some(branch.resolve_conditional_returns(lookup))
}

/// An assignment expression in argument position (`f($x = expr)`,
/// `->andReturn($mock = m::mock(...))`) has its value consumed by the call —
/// the write is used even if the variable is never read again.
pub(crate) fn consume_arg_assignment(
    expr: &php_ast::owned::Expr,
    ctx: &mut crate::flow_state::FlowState,
) {
    if let php_ast::owned::ExprKind::Assign(a) = &expr.kind {
        if let php_ast::owned::ExprKind::Variable(name) = &a.target.kind {
            let n = name.trim_start_matches('$');
            ctx.read_vars.insert(mir_types::Name::from(n));
            ctx.mark_consumed(n);
        }
    }
}

/// Pre-mark variables passed to by-reference parameters as defined.
///
/// Passing an as-yet-undefined variable to an out-parameter (e.g. `&$matches`
/// in `preg_match`, or a user method's `&$out`) defines it, so it must not be
/// reported as `UndefinedVariable`. Variadic by-ref params (`&...$rest`) cover
/// every argument from their position onward. Must run before the arguments are
/// analyzed so the read side never sees the variable as undefined.
///
/// Binds each arg to its param the same way `call/args/counts.rs::check_counts`
/// does — honoring named arguments that reorder which param a given arg feeds
/// — rather than assuming `args[i]` always feeds `params[i]`. That fuller
/// binder can't be reused directly here since it needs each arg's inferred
/// type, which isn't available yet (premarking must run before args are
/// analyzed).
pub(crate) fn premark_byref_arg_vars(
    params: &[mir_codebase::definitions::DeclaredParam],
    args: &[php_ast::owned::Arg],
    ctx: &mut crate::flow_state::FlowState,
) {
    use php_ast::owned::ExprKind;

    fn premark_one(
        param: &mir_codebase::definitions::DeclaredParam,
        arg: &php_ast::owned::Arg,
        ctx: &mut crate::flow_state::FlowState,
    ) {
        if !param.is_byref {
            return;
        }
        let Some(value) = &arg.value else { return };
        if let ExprKind::Variable(name) = &value.kind {
            let var_name = name.trim_start_matches('$');
            if !ctx.var_is_defined(var_name) {
                // Prefer @param-out type if declared; fall back to declared
                // in-type, then mixed.
                let ty = param
                    .out_ty
                    .as_ref()
                    .or(param.ty.as_ref())
                    .map(|t| (**t).clone())
                    .unwrap_or_else(mir_types::Type::mixed);
                ctx.set_var(var_name, ty);
            }
        }
    }

    let variadic_index = params.iter().position(|p| p.is_variadic);
    let max_positional = variadic_index.unwrap_or(params.len());
    let mut positional = 0usize;

    for arg in args {
        // A spread (`...$rest`) can't be statically bound to a single param.
        if arg.unpack {
            break;
        }
        if let Some(name) = &arg.name {
            let name = crate::parser::name_to_string_owned(name);
            if let Some(param) = params.iter().find(|p| p.name.as_ref() == name.as_str()) {
                premark_one(param, arg, ctx);
            } else if let Some(vi) = variadic_index {
                premark_one(&params[vi], arg, ctx);
            }
            continue;
        }
        let param = if positional < max_positional {
            params.get(positional)
        } else {
            variadic_index.map(|vi| &params[vi])
        };
        if let Some(param) = param {
            premark_one(param, arg, ctx);
        }
        positional += 1;
    }
}

// Reusable per-thread buffer for arg_types collection. The Option lets
// reentrant calls (foo(bar(baz()))) detect they can't borrow the same buffer
// and fall back to a fresh allocation.
thread_local! {
    pub(crate) static ARG_TYPES_BUF: std::cell::RefCell<Option<Vec<mir_types::Type>>> =
        const { std::cell::RefCell::new(Some(Vec::new())) };
}

/// Param types a callee passes to a closure bound to `param` (`callable(E)` /
/// `Closure(E)`), with `bindings` substituted.
pub(crate) fn callback_param_hints(
    ea: &crate::expr::ExpressionAnalyzer<'_>,
    param: &mir_codebase::definitions::DeclaredParam,
    bindings: &rustc_hash::FxHashMap<mir_types::Name, mir_types::Type>,
) -> Option<Vec<Option<mir_types::Type>>> {
    use mir_types::Atomic;
    let ty = param.ty.as_ref()?.substitute_templates(bindings);
    let mut callables = ty.types.iter().filter_map(|a| match a {
        Atomic::TCallable {
            params: Some(params),
            ..
        } => Some(params),
        Atomic::TClosure { data } => Some(&data.params),
        _ => None,
    });
    let fn_params = callables.next()?;
    if callables.next().is_some() {
        return None;
    }
    Some(
        fn_params
            .iter()
            .map(|p| {
                p.ty.as_ref()
                    .map(|t| callable::resolve_enum_case_refs(&t.to_union(), ea))
            })
            .collect(),
    )
}