mir_codebase/

definitions.rs

use std::sync::Arc;

/// Insertion-ordered member map keyed by lowercased member name.
/// FxHash instead of SipHash: member lookup is one of the hottest analyzer
/// operations and the keys are short trusted identifiers.
pub type MemberMap<V> = indexmap::IndexMap<std::sync::Arc<str>, V, rustc_hash::FxBuildHasher>;
use mir_types::{Location, Name, Type};
use rustc_hash::FxHashMap;
use serde::{Deserialize, Serialize};

// ---------------------------------------------------------------------------
// Interned common types for deduplication
// ---------------------------------------------------------------------------

/// Interned Type types for common parameter/property types.
/// Deduplicates allocations when thousands of parameters share types like `string`, `int`, etc.
mod interned_types {
    use super::*;
    use std::sync::OnceLock;

    fn intern_string() -> Arc<Type> {
        Arc::new(Type::string())
    }

    fn intern_int() -> Arc<Type> {
        Arc::new(Type::int())
    }

    fn intern_float() -> Arc<Type> {
        Arc::new(Type::float())
    }

    fn intern_bool() -> Arc<Type> {
        Arc::new(Type::bool())
    }

    fn intern_mixed() -> Arc<Type> {
        Arc::new(Type::mixed())
    }

    fn intern_null() -> Arc<Type> {
        Arc::new(Type::null())
    }

    fn intern_void() -> Arc<Type> {
        Arc::new(Type::void())
    }

    static STRING: OnceLock<Arc<Type>> = OnceLock::new();
    static INT: OnceLock<Arc<Type>> = OnceLock::new();
    static FLOAT: OnceLock<Arc<Type>> = OnceLock::new();
    static BOOL: OnceLock<Arc<Type>> = OnceLock::new();
    static MIXED: OnceLock<Arc<Type>> = OnceLock::new();
    static NULL: OnceLock<Arc<Type>> = OnceLock::new();
    static VOID: OnceLock<Arc<Type>> = OnceLock::new();

    pub fn string() -> Arc<Type> {
        STRING.get_or_init(intern_string).clone()
    }

    pub fn int() -> Arc<Type> {
        INT.get_or_init(intern_int).clone()
    }

    pub fn float() -> Arc<Type> {
        FLOAT.get_or_init(intern_float).clone()
    }

    pub fn bool() -> Arc<Type> {
        BOOL.get_or_init(intern_bool).clone()
    }

    pub fn mixed() -> Arc<Type> {
        MIXED.get_or_init(intern_mixed).clone()
    }

    pub fn null() -> Arc<Type> {
        NULL.get_or_init(intern_null).clone()
    }

    pub fn void() -> Arc<Type> {
        VOID.get_or_init(intern_void).clone()
    }

    /// Global content-keyed `Arc<Type>` interner. Any structurally-identical
    /// Type is shared as a single Arc across the session.
    ///
    /// Why: PHP codebases re-declare a small set of type shapes thousands of
    /// times — `string|null` return types, `int` params, `array<string, mixed>`
    /// property types. Without interning, each declaration allocates its own
    /// `Arc<Type>` plus the inline `SmallVec<[Atomic; 2]>` and any boxed
    /// `Atomic` payloads. With interning, only the first occurrence allocates.
    ///
    /// Trade-off: every `intern_or_wrap` call hashes + does one DashMap lookup.
    /// Hashing a `Type` is cheap (SmallVec, small atomics) — measured cost is
    /// well below the alloc-savings benefit on real workloads.
    type InternTable = dashmap::DashMap<Type, Arc<Type>, rustc_hash::FxBuildHasher>;

    static GLOBAL_UNION_INTERN: std::sync::OnceLock<InternTable> = std::sync::OnceLock::new();

    fn global_intern_table() -> &'static InternTable {
        GLOBAL_UNION_INTERN.get_or_init(|| dashmap::DashMap::with_hasher(Default::default()))
    }

    /// The shared `Arc` of a single-atomic scalar `union` without flags.
    fn scalar_singleton(union: &Type) -> Option<Arc<Type>> {
        // Excludes `falsy_stripped`/`possibly_absent_offset` types (e.g.
        // `preg_replace_callback`'s narrowed `string`, or a generic
        // array-offset read's value type) — the canonical singleton never
        // carries either flag, so returning it here would silently drop it.
        if union.types.len() != 1
            || union.possibly_undefined
            || union.from_docblock
            || union.falsy_stripped
            || union.possibly_absent_offset
        {
            return None;
        }
        match &union.types[0] {
            mir_types::Atomic::TString => Some(string()),
            mir_types::Atomic::TInt => Some(int()),
            mir_types::Atomic::TFloat => Some(float()),
            mir_types::Atomic::TBool => Some(bool()),
            mir_types::Atomic::TMixed => Some(mixed()),
            mir_types::Atomic::TNull => Some(null()),
            mir_types::Atomic::TVoid => Some(void()),
            _ => None,
        }
    }

    /// Try to intern a Type if it matches a common type, otherwise wrap in Arc.
    pub fn intern_or_wrap(union: Type) -> Arc<Type> {
        if let Some(scalar) = scalar_singleton(&union) {
            return scalar;
        }
        // Empty Type — also a common case (e.g. unresolved return type).
        // Don't pollute the intern table with these.
        if union.types.is_empty() {
            return Arc::new(union);
        }
        let hash = {
            use std::hash::BuildHasher;
            rustc_hash::FxBuildHasher.hash_one(&union)
        };
        let slot = (hash as usize) & (LOCAL_SLOTS - 1);
        let hit = LOCAL_CACHE.with(|cache| {
            cache.borrow()[slot]
                .as_ref()
                .filter(|(h, arc)| *h == hash && **arc == union)
                .map(|(_, arc)| Arc::clone(arc))
        });
        if let Some(hit) = hit {
            return hit;
        }
        let interned = intern_global(union);
        LOCAL_CACHE.with(|cache| cache.borrow_mut()[slot] = Some((hash, Arc::clone(&interned))));
        interned
    }

    const LOCAL_SLOTS: usize = 1024;

    type LocalSlots = std::cell::RefCell<Box<[Option<(u64, Arc<Type>)>]>>;

    thread_local! {
        /// Direct-mapped front for the global table. It holds only Arcs taken
        /// from that table: equal types that differ in key order (equality
        /// ignores it) must keep resolving to the table's one representative.
        static LOCAL_CACHE: LocalSlots =
            std::cell::RefCell::new(vec![None; LOCAL_SLOTS].into_boxed_slice());
    }

    fn intern_global(union: Type) -> Arc<Type> {
        let table = global_intern_table();
        if let Some(existing) = table.get(&union) {
            return Arc::clone(existing.value());
        }
        let arc = Arc::new(union.clone());
        // `insert` semantics: if a parallel thread beat us, its Arc wins.
        // The lookup-before-insert race is benign — both Arcs are content-
        // equal — but we still want to share the canonical one going forward.
        match table.entry(union) {
            dashmap::mapref::entry::Entry::Occupied(o) => Arc::clone(o.get()),
            dashmap::mapref::entry::Entry::Vacant(v) => {
                v.insert(Arc::clone(&arc));
                arc
            }
        }
    }
}

// ---------------------------------------------------------------------------
// Shared primitives
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
pub enum Visibility {
    Public,
    Protected,
    Private,
}

impl Visibility {
    pub fn is_at_least(&self, required: Visibility) -> bool {
        *self <= required
    }
}

impl std::fmt::Display for Visibility {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Visibility::Public => write!(f, "public"),
            Visibility::Protected => write!(f, "protected"),
            Visibility::Private => write!(f, "private"),
        }
    }
}

fn serialize_template_bound<S>(value: &Option<Arc<Type>>, serializer: S) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    value.as_deref().serialize(serializer)
}

fn deserialize_template_bound<'de, D>(deserializer: D) -> Result<Option<Arc<Type>>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Option::<Type>::deserialize(deserializer).map(|opt| opt.map(interned_types::intern_or_wrap))
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TemplateParam {
    pub name: Name,
    /// Declared upper bound, e.g. `@template T of Traversable`.
    /// Stored as `Option<Arc<Type>>` so common bounds (e.g. `object`, `mixed`)
    /// are deduplicated across all template params via the global intern table.
    #[serde(
        serialize_with = "serialize_template_bound",
        deserialize_with = "deserialize_template_bound"
    )]
    pub bound: Option<Arc<Type>>,
    /// Default type used when nothing binds this template param, e.g.
    /// `@template T = string`. Falls back to `mixed` when absent, same as
    /// before this field existed.
    #[serde(
        default,
        serialize_with = "serialize_template_bound",
        deserialize_with = "deserialize_template_bound"
    )]
    pub default: Option<Arc<Type>>,
    /// The entity (class or function FQN) that declared this template param.
    pub defining_entity: Name,
    pub variance: mir_types::Variance,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeclaredParam {
    pub name: Name,
    /// Parameter type. Stored as `Option<Arc<Type>>` to enable deduplication of
    /// common types across parameters. Many parameters share types like `string`,
    /// `int`, `bool`, etc., so interning via Arc saves allocations.
    #[serde(
        deserialize_with = "deserialize_param_type",
        serialize_with = "serialize_param_type"
    )]
    pub ty: Option<Arc<Type>>,
    /// Out-type declared via `@param-out` / `@psalm-param-out`. When set, this
    /// type is written back to the caller's argument variable after the call
    /// instead of (or in addition to) the declared in-type.
    #[serde(
        default,
        deserialize_with = "deserialize_param_type",
        serialize_with = "serialize_param_type"
    )]
    pub out_ty: Option<Arc<Type>>,
    /// `@param-closure-this Type`: the `$this` type of a closure literal passed for this parameter.
    #[serde(
        default,
        deserialize_with = "deserialize_param_type",
        serialize_with = "serialize_param_type"
    )]
    pub closure_this: Option<Arc<Type>>,
    /// Raw `@param` type spelling when `ty` came from a docblock rather than a
    /// native hint. Preserved so later analysis can resolve ambiguous
    /// pseudo-type aliases (e.g. `integer`) against same-named classes once the
    /// full symbol table is available.
    #[serde(default)]
    pub doc_type_raw: Option<Arc<str>>,
    /// Declaring file for `doc_type_raw`. Needed because inherited signatures
    /// may be consumed from a different file/namespace than the original
    /// docblock declaration.
    #[serde(default)]
    pub doc_type_file: Option<Arc<str>>,
    /// Whether this parameter has a default value. Analysis uses it only to mark
    /// parameters optional; the value itself is kept as text in `default_text`.
    pub has_default: bool,
    /// Source text of the default value expression (`10`, `null`, `self::X`).
    /// `None` when there is no default or its source text is unavailable.
    #[serde(default)]
    pub default_text: Option<Arc<str>>,
    pub is_variadic: bool,
    pub is_byref: bool,
    pub is_optional: bool,
}

impl std::hash::Hash for DeclaredParam {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.name.hash(state);
        self.has_default.hash(state);
        self.default_text.hash(state);
        self.is_variadic.hash(state);
        self.is_byref.hash(state);
        self.is_optional.hash(state);
        self.doc_type_raw.hash(state);
        self.doc_type_file.hash(state);
        // Hash the type value (not the Arc pointer) so that two FnParams with
        // equal types (PartialEq) always produce the same hash, even when they
        // are backed by different Arc allocations.
        self.ty.as_deref().hash(state);
        self.out_ty.as_deref().hash(state);
        self.closure_this.as_deref().hash(state);
    }
}

// Serde helpers to transparently convert between Option<Type> and Option<Arc<Type>>
fn deserialize_param_type<'de, D>(deserializer: D) -> Result<Option<Arc<Type>>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Option::<Type>::deserialize(deserializer).map(|opt| opt.map(interned_types::intern_or_wrap))
}

fn serialize_param_type<S>(value: &Option<Arc<Type>>, serializer: S) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    let opt = value.as_ref().map(|arc| (**arc).clone());
    opt.serialize(serializer)
}

fn deserialize_return_type<'de, D>(deserializer: D) -> Result<Option<Arc<Type>>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Option::<Type>::deserialize(deserializer).map(|opt| opt.map(interned_types::intern_or_wrap))
}

fn serialize_return_type<S>(value: &Option<Arc<Type>>, serializer: S) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    let opt = value.as_ref().map(|arc| (**arc).clone());
    opt.serialize(serializer)
}

fn deserialize_params<'de, D>(deserializer: D) -> Result<Arc<[DeclaredParam]>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Vec::<DeclaredParam>::deserialize(deserializer).map(|v| Arc::from(v.into_boxed_slice()))
}

fn default_imports() -> Arc<FxHashMap<Name, Name>> {
    Arc::new(FxHashMap::default())
}

/// Deserialize imports map. Supports both new (Name-keyed) and legacy
/// (String-keyed) on-disk formats — older `cache.bin` files have plain
/// `HashMap<String, String>`. Either way, we intern at load time so the
/// in-memory representation is always `Arc<FxHashMap<Name, Name>>`.
fn deserialize_imports<'de, D>(deserializer: D) -> Result<Arc<FxHashMap<Name, Name>>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let raw = FxHashMap::<String, String>::deserialize(deserializer)?;
    let mut out: FxHashMap<Name, Name> =
        FxHashMap::with_capacity_and_hasher(raw.len(), Default::default());
    for (k, v) in raw {
        out.insert(Name::new(&k), Name::new(&v));
    }
    Ok(Arc::new(out))
}

/// Serialize imports as the legacy `HashMap<String, String>` shape so disk
/// caches written by this version remain compatible with readers that haven't
/// been recompiled yet (and vice-versa).
fn serialize_imports<S>(
    value: &Arc<FxHashMap<Name, Name>>,
    serializer: S,
) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    use serde::ser::SerializeMap;
    let mut map = serializer.serialize_map(Some(value.len()))?;
    for (k, v) in value.iter() {
        map.serialize_entry(k.as_str(), v.as_str())?;
    }
    map.end()
}

fn serialize_params<S>(value: &Arc<[DeclaredParam]>, serializer: S) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    value.as_ref().serialize(serializer)
}

/// Helper to wrap `Option<Type>` in interned `Arc<Type>`.
pub fn wrap_param_type(ty: Option<Type>) -> Option<Arc<Type>> {
    ty.map(interned_types::intern_or_wrap)
}

/// Helper to wrap return type `Option<Type>` in interned `Arc<Type>`.
pub fn wrap_return_type(ty: Option<Type>) -> Option<Arc<Type>> {
    ty.map(interned_types::intern_or_wrap)
}

/// Helper to wrap a `PropertyDef` type field (`ty`/`inferred_ty`/`default`) in
/// an interned `Arc<Type>`, deduplicating common property types via the global
/// pool. See [`PropertyDef`].
pub fn wrap_property_type(ty: Option<Type>) -> Option<Arc<Type>> {
    ty.map(interned_types::intern_or_wrap)
}

/// Helper to wrap a `TemplateParam.bound` in an interned `Arc<Type>`.
pub fn wrap_template_bound(ty: Option<Type>) -> Option<Arc<Type>> {
    ty.map(interned_types::intern_or_wrap)
}

/// Wrap a variable type in an interned `Arc<Type>`. Use instead of
/// `Arc::new(ty)` at `FlowState::set_var` and parameter-init sites so that
/// common scalars (string, int, bool, null, mixed) share a static Arc rather
/// than allocating a fresh one per assignment.
pub fn wrap_var_type(ty: Type) -> Arc<Type> {
    interned_types::intern_or_wrap(ty)
}

// ---------------------------------------------------------------------------
// Assertion — `@psalm-assert`, `@psalm-assert-if-true`, etc.
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum AssertionKind {
    Assert,
    AssertIfTrue,
    AssertIfFalse,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Assertion {
    pub kind: AssertionKind,
    pub param: Arc<str>,
    pub ty: Type,
    /// True for the `!Type` negated form (`@psalm-assert !null $x`): the
    /// parameter is asserted to NOT be `ty`, rather than to BE it.
    #[serde(default)]
    pub negated: bool,
    /// Set for an assertion targeting a specific (possibly nested) array key
    /// path of `param` rather than the whole parameter (`@psalm-assert-if-true
    /// string $arr['a']['b']` — `param` is `"arr"`, `param_key` is
    /// `[String("a"), String("b")]`). Empty means "targets the whole parameter".
    #[serde(default)]
    pub param_key: Vec<mir_types::atomic::ArrayKey>,
}

// ---------------------------------------------------------------------------
// MethodDef
// ---------------------------------------------------------------------------

/// Prose following the type and name of `@param`, `@return` and `@throws`
/// tags. Tags without prose are omitted.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct TagDescriptions {
    /// `(parameter name without $, description)`.
    pub params: Vec<(Arc<str>, Arc<str>)>,
    pub returns: Option<Arc<str>>,
    /// `(resolved exception FQCN, description)`.
    pub throws: Vec<(Arc<str>, Arc<str>)>,
}

/// `@taint-source`, `@taint-escape`, `@taint-unescape` and `@psalm-flow` on a function or method.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct TaintAnnotations {
    /// Kinds of an `@taint-source`; none means every kind.
    pub source: Vec<Arc<str>>,
    /// Sink kinds the return value no longer carries.
    pub escape: Vec<Arc<str>>,
    /// Sink kinds the return value regains from tainted arguments.
    pub unescape: Vec<Arc<str>>,
    /// Parameters whose taint flows into the return value.
    pub flow_params: Vec<Arc<str>>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MethodDef {
    pub name: Arc<str>,
    pub fqcn: Arc<str>,
    #[serde(
        deserialize_with = "deserialize_params",
        serialize_with = "serialize_params"
    )]
    pub params: Arc<[DeclaredParam]>,
    /// Type from annotation (`@return` / native type hint). `None` means unannotated.
    /// Stored as `Option<Arc<Type>>` to enable deduplication of common return types
    /// (e.g., `void`, `string`, `mixed`, `bool`) across thousands of methods.
    #[serde(
        deserialize_with = "deserialize_return_type",
        serialize_with = "serialize_return_type"
    )]
    pub return_type: Option<Arc<Type>>,
    /// Type inferred from body analysis. Stored as `Option<Arc<Type>>` (8 B) rather
    /// than inline `Option<Type>` (176 B, no niche) — inference is now demand-driven
    /// via salsa (`inferred_*_return_type_demand`), so this field is a rarely/never
    /// populated fallback; shrinking it saves ~168 B on every MethodDef.
    #[serde(
        deserialize_with = "deserialize_return_type",
        serialize_with = "serialize_return_type"
    )]
    pub inferred_return_type: Option<Arc<Type>>,
    /// Native return hint kept beside a `@return` that names a template, to bound it when unbound.
    #[serde(default)]
    pub native_return: Option<Box<Type>>,
    pub visibility: Visibility,
    pub is_static: bool,
    pub is_abstract: bool,
    pub is_final: bool,
    pub is_constructor: bool,
    pub template_params: Vec<TemplateParam>,
    pub assertions: Vec<Assertion>,
    pub throws: Vec<Arc<str>>,
    pub deprecated: Option<Arc<str>>,
    pub is_internal: bool,
    pub is_pure: bool,
    /// An explicit `@impure`/`@psalm-impure`/`@phpstan-impure` declaration.
    #[serde(default)]
    pub is_impure: bool,
    /// `@no-named-arguments` — callers must not use named argument syntax.
    #[serde(default)]
    pub no_named_arguments: bool,
    /// True when the method has the `#[Override]` PHP attribute.
    #[serde(default)]
    pub is_override: bool,
    pub location: Option<Location>,
    /// Plain-text description from the docblock (text before `@tag` lines).
    /// Used for hover info.
    #[serde(default)]
    pub docstring: Option<Arc<str>>,
    /// Prose attached to `@param`, `@return` and `@throws` tags. `None` when
    /// no tag carries a description.
    #[serde(default)]
    pub tag_descriptions: Option<Arc<TagDescriptions>>,
    /// True for methods added via `@method` docblock annotations. Virtual
    /// methods must not be required as concrete interface implementations.
    #[serde(default)]
    pub is_virtual: bool,
    /// Parameters declared as taint sinks via `@taint-sink <kind> $param`.
    /// Each entry is `(param_name_without_dollar, sink_kind_string)`.
    #[serde(default)]
    pub taint_sink_params: Vec<(Arc<str>, Arc<str>)>,
    /// `@taint-source` — this method's return value is treated as tainted
    /// (attacker-controlled) at every call site, mirroring `@taint-sink`'s
    /// mechanism but marking the source side instead.
    #[serde(default)]
    pub is_taint_source: bool,
    #[serde(default)]
    pub taint: Option<Arc<TaintAnnotations>>,
    /// `@if-this-is Type` — the resolved constraint a receiver's type must
    /// satisfy for this method to be callable. `None` when absent.
    #[serde(default)]
    pub if_this_is: Option<Arc<Type>>,
    /// `@psalm-self-out Type` / `@phpstan-self-out Type` — the receiver's type
    /// after this call returns (e.g. a fluent builder that narrows `$this` as
    /// it's configured). `None` when absent.
    #[serde(default)]
    pub self_out: Option<Arc<Type>>,
    /// True when the method has `@inheritDoc` / `{@inheritDoc}` in its docblock.
    /// The analyzer inherits the parent's return type, param types, throws, and
    /// template params when this method has none of its own.
    #[serde(default)]
    pub is_inherit_doc: bool,
    /// `@psalm-mutation-free` / `@phpstan-mutation-free` — this method must not
    /// assign to `$this` properties (same constraint as `@psalm-immutable` on the
    /// class, but scoped to this single method).
    #[serde(default)]
    pub is_mutation_free: bool,
    /// `@psalm-external-mutation-free` — this method must not mutate any objects
    /// passed as arguments, but is allowed to modify `$this`.
    #[serde(default)]
    pub is_external_mutation_free: bool,
    /// The body provably never writes a property, so a call leaves the
    /// receiver's property narrowing intact. Derived from the body, unlike
    /// `is_mutation_free`, which comes from the annotation.
    #[serde(default)]
    pub inferred_mutation_free: bool,
    /// Method names referenced via `@dataProvider name` / `#[DataProvider('name')]`
    /// (PHPUnit) — treated as used by dead-code analysis, since PHPUnit invokes
    /// them by name through reflection rather than a direct call site.
    #[serde(default)]
    pub data_provider_targets: Vec<Arc<str>>,
}

impl MethodDef {
    pub fn effective_return_type(&self) -> Option<&Type> {
        self.return_type
            .as_deref()
            .or(self.inferred_return_type.as_deref())
    }
}

// ---------------------------------------------------------------------------
// PropertyDef
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PropertyDef {
    pub name: Arc<str>,
    /// Declared/inferred/default types. Stored as `Option<Arc<Type>>` (8 B)
    /// rather than inline `Option<Type>` (176 B, no niche) and interned via the
    /// global pool on construction/deserialization — common property types
    /// (`string`, `int`, a shared class type) dedup to one allocation. Mirrors
    /// `DeclaredParam::ty`. On-disk format is unchanged (the serde helpers (de)serialize
    /// the inner `Type` transparently).
    #[serde(
        deserialize_with = "deserialize_param_type",
        serialize_with = "serialize_param_type"
    )]
    pub ty: Option<Arc<Type>>,
    #[serde(
        deserialize_with = "deserialize_param_type",
        serialize_with = "serialize_param_type"
    )]
    pub inferred_ty: Option<Arc<Type>>,
    pub visibility: Visibility,
    /// Asymmetric write visibility (`private(set)`); `None` follows `visibility`.
    pub set_visibility: Option<Visibility>,
    pub is_static: bool,
    pub is_readonly: bool,
    #[serde(
        deserialize_with = "deserialize_param_type",
        serialize_with = "serialize_param_type"
    )]
    pub default: Option<Arc<Type>>,
    pub location: Option<Location>,
    /// `@deprecated` docblock annotation, if present.
    #[serde(default)]
    pub deprecated: Option<Arc<str>>,
    /// True when the property declares a PHP native type hint (`public int $x`).
    /// A property typed only via a `@var` docblock (or untyped entirely) is
    /// `false`: PHP gives such a property an implicit `null` default, so it is
    /// never "uninitialized" (no MissingConstructor) and accepts `null` on
    /// assignment regardless of the advisory docblock type.
    #[serde(default)]
    pub has_native_type: bool,
    /// True when this entry was synthesised from a `@property` / `@property-read` /
    /// `@property-write` docblock tag rather than a real PHP property declaration.
    /// Such entries describe magic properties accessible via `__get`/`__set` and
    /// do **not** participate in PHP's inheritance visibility rules.
    #[serde(default)]
    pub from_docblock: bool,
    /// True when the property declares a `get` hook with no accompanying `set`
    /// hook. Such a property is virtual: it has no backing storage, computes
    /// its value on every access, and can never be assigned to at all — so it
    /// is never "left uninitialized" by the constructor. A property that also
    /// declares (or only declares) a `set` hook is backed and can still be
    /// left uninitialized, so it does not count here.
    #[serde(default)]
    pub get_only_hook: bool,
    /// Hooks declared without a body (interface or `abstract` property): bit 0 `get`, bit 1 `set`.
    #[serde(default)]
    pub abstract_hooks: u8,
    /// For a virtual property (hooks, none touching `$this->name`), its declared hooks as in
    /// `abstract_hooks`; 0 for a backed one.
    #[serde(default)]
    pub virtual_hooks: u8,
    /// True when `readonly` comes from a native PHP keyword (`readonly` modifier or
    /// `readonly class`). False when only a `@readonly` docblock annotation is present.
    /// Distinguishes PHP-enforced read-only from advisory documentation.
    #[serde(default)]
    pub has_native_readonly: bool,
    /// Declared with `#[Override]` (PHP 8.5 checks properties too).
    #[serde(default)]
    pub is_override: bool,
    /// The PHP native type hint alone, with any `@var` docblock refinement stripped —
    /// `None` when `has_native_type` is false. `ty` mixes in the docblock type when
    /// present, which makes it unsuitable for checking PHP's redeclared-property
    /// type invariance rule: that rule is enforced by the runtime purely on the
    /// native hint, never on the (unenforced) docblock annotation.
    #[serde(default)]
    #[serde(
        deserialize_with = "deserialize_param_type",
        serialize_with = "serialize_param_type"
    )]
    pub native_ty: Option<Arc<Type>>,
}

// ---------------------------------------------------------------------------
// ConstantDef
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ConstantDef {
    pub name: Arc<str>,
    pub ty: Type,
    /// Literal initializer when a `@var` makes `ty` wider than the value.
    #[serde(default)]
    pub literal_value: Option<Type>,
    pub visibility: Option<Visibility>,
    #[serde(default)]
    pub is_final: bool,
    pub location: Option<Location>,
    /// `@deprecated` docblock annotation, if present.
    #[serde(default)]
    pub deprecated: Option<Arc<str>>,
}

// ---------------------------------------------------------------------------
// ClassDef
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClassDef {
    pub fqcn: Arc<str>,
    pub short_name: Arc<str>,
    /// Marked `@api` / `@psalm-api`: used from outside the analyzed code.
    #[serde(default)]
    pub is_api: bool,
    pub parent: Option<Arc<str>>,
    pub interfaces: Vec<Arc<str>>,
    pub traits: Vec<Arc<str>>,
    pub own_methods: MemberMap<Arc<MethodDef>>,
    pub own_properties: MemberMap<PropertyDef>,
    pub own_constants: MemberMap<ConstantDef>,
    #[serde(default)]
    pub mixins: Vec<Arc<str>>,
    /// Source of each `mixins` tag, same order; empty when unknown.
    #[serde(default)]
    pub mixin_locations: Vec<Location>,
    pub template_params: Vec<TemplateParam>,
    /// Type arguments from `@extends ParentClass<T1, T2>` — maps parent's template params to concrete types.
    pub extends_type_args: Vec<Type>,
    /// Type arguments from `@implements Interface<T1, T2>`.
    #[serde(default)]
    pub implements_type_args: Vec<(Arc<str>, Vec<Type>)>,
    /// Type arguments from `@use TraitName<T1, T2>`, keyed by the used
    /// trait's FQCN — a class's `use` clause (unlike `@extends`) may name
    /// several traits at once.
    #[serde(default)]
    pub trait_use_type_args: Vec<(Arc<str>, Vec<Type>)>,
    pub is_abstract: bool,
    pub is_final: bool,
    pub is_readonly: bool,
    pub deprecated: Option<Arc<str>>,
    pub is_internal: bool,
    /// Set when the class carries `@psalm-immutable` — non-constructor methods must not
    /// assign to `$this` properties.
    #[serde(default)]
    pub is_immutable: bool,
    /// Attribute target flags if this class has `#[Attribute]` annotation.
    /// `None` = not an attribute class. The value is a bitmask of PHP's
    /// `Attribute::TARGET_*` constants (e.g. `Attribute::TARGET_CLASS = 1`).
    #[serde(default)]
    pub attribute_flags: Option<i64>,
    /// Declared with `#[AllowDynamicProperties]`; subclasses inherit it.
    #[serde(default)]
    pub allows_dynamic_properties: bool,
    pub location: Option<Location>,
    /// Per-`use` statement locations for each used trait: `(fqcn, location)` in
    /// declaration order, parallel to `traits`.  Absent from older serialized
    /// slices; defaults to empty.
    #[serde(default)]
    pub trait_use_locations: Vec<(Arc<str>, Location)>,
    /// Type aliases declared on this class via `@psalm-type` / `@phpstan-type`.
    #[serde(default)]
    pub type_aliases: FxHashMap<Arc<str>, Type>,
    /// Raw import-type declarations (`(local_name, original_name, from_class)`) — resolved during finalization.
    #[serde(default)]
    pub pending_import_types: Vec<(Arc<str>, Arc<str>, Arc<str>)>,
    /// Trait precedence exclusions from `insteadof` declarations in this class's `use` blocks.
    /// Maps method_name_lowercase → list of trait FQCNs whose version of the method is excluded.
    /// E.g. `use A, B { B::hello insteadof A; }` stores `"hello" → ["A"]`.
    #[serde(default)]
    pub trait_insteadof: MemberMap<Vec<Arc<str>>>,
    /// Trait method aliases from `as` declarations in this class's `use` blocks.
    /// Maps new_name_lowercase → (optional_trait_fqcn, original_method_name_lowercase, visibility_override, alias_cased).
    /// `alias_cased` is the alias name preserving the original PHP casing (for error messages / case checks).
    /// Visibility is `None` when the `as` clause only renames without changing visibility.
    /// E.g. `use Base { __construct as __constructBase; }` stores
    ///   `"__constructbase" → (None, "__construct", None, "__constructBase")`.
    /// E.g. `use T { foo as private traitFoo; }` stores
    ///   `"traitfoo" → (None, "foo", Some(Private), "traitFoo")`.
    #[serde(default)]
    #[allow(clippy::type_complexity)]
    pub trait_aliases:
        FxHashMap<Arc<str>, (Option<Arc<str>>, Arc<str>, Option<Visibility>, Arc<str>)>,
    /// Source span of each `trait_aliases` adaptation, keyed the same way.
    #[serde(default)]
    pub trait_alias_locations: FxHashMap<Arc<str>, Location>,
}

impl ClassDef {
    pub fn get_method(&self, name: &str) -> Option<&MethodDef> {
        // PHP method names are case-insensitive; caller should pass lowercase name.
        // Only searches own_methods — inherited method resolution is done by
        // `db::lookup_method_in_chain`.
        self.own_methods.get(name).map(Arc::as_ref).or_else(|| {
            self.own_methods
                .iter()
                .find(|(k, _)| k.as_ref().eq_ignore_ascii_case(name))
                .map(|(_, v)| v.as_ref())
        })
    }

    pub fn get_property(&self, name: &str) -> Option<&PropertyDef> {
        self.own_properties.get(name)
    }
}

// ---------------------------------------------------------------------------
// InterfaceDef
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InterfaceDef {
    pub fqcn: Arc<str>,
    pub short_name: Arc<str>,
    /// Marked `@api` / `@psalm-api`: used from outside the analyzed code.
    #[serde(default)]
    pub is_api: bool,
    pub extends: Vec<Arc<str>>,
    pub own_methods: MemberMap<Arc<MethodDef>>,
    pub own_constants: MemberMap<ConstantDef>,
    pub template_params: Vec<TemplateParam>,
    pub location: Option<Location>,
    /// `@deprecated` docblock annotation, if present.
    #[serde(default)]
    pub deprecated: Option<Arc<str>>,
    /// Properties declared via `@property*` docblock annotations on the interface.
    #[serde(default)]
    pub own_properties: MemberMap<PropertyDef>,
    /// `@seal-properties` / `@psalm-seal-properties` — disallows undeclared property access.
    #[serde(default)]
    pub seal_properties: bool,
    /// Type arguments from `@extends BaseIface<T1, T2>` docblock lines, keyed by the
    /// extended interface's FQCN — an interface's native `extends` list (unlike a
    /// class's single parent) may name several base interfaces at once.
    #[serde(default)]
    pub extends_type_args: Vec<(Arc<str>, Vec<Type>)>,
    /// Type aliases declared on this interface via `@psalm-type` / `@phpstan-type`.
    #[serde(default)]
    pub type_aliases: FxHashMap<Arc<str>, Type>,
}

// ---------------------------------------------------------------------------
// TraitDef
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TraitDef {
    pub fqcn: Arc<str>,
    pub short_name: Arc<str>,
    /// Marked `@api` / `@psalm-api`: used from outside the analyzed code.
    #[serde(default)]
    pub is_api: bool,
    pub own_methods: MemberMap<Arc<MethodDef>>,
    pub own_properties: MemberMap<PropertyDef>,
    pub own_constants: MemberMap<ConstantDef>,
    pub template_params: Vec<TemplateParam>,
    /// Traits used by this trait (`use OtherTrait;` inside a trait body).
    pub traits: Vec<Arc<str>>,
    pub location: Option<Location>,
    /// Per-`use` statement locations for each used trait: `(fqcn, location)` in
    /// declaration order, parallel to `traits`. Mirrors `ClassDef`/`EnumDef`'s
    /// field of the same name. Absent from older serialized slices; defaults
    /// to empty.
    #[serde(default)]
    pub trait_use_locations: Vec<(Arc<str>, Location)>,
    /// Type arguments from `@use OtherTrait<T1, T2>` (a trait may itself
    /// `use` a generic trait).
    #[serde(default)]
    pub trait_use_type_args: Vec<(Arc<str>, Vec<Type>)>,
    /// Set when the trait carries `@psalm-immutable`.
    #[serde(default)]
    pub is_immutable: bool,
    /// `@psalm-require-extends` / `@phpstan-require-extends` — FQCNs that using classes must extend.
    #[serde(default)]
    pub require_extends: Vec<Arc<str>>,
    /// `@psalm-require-implements` / `@phpstan-require-implements` — FQCNs that using classes must implement.
    #[serde(default)]
    pub require_implements: Vec<Arc<str>>,
    /// `@deprecated` docblock annotation, if present.
    #[serde(default)]
    pub deprecated: Option<Arc<str>>,
    /// Type aliases declared on this trait via `@psalm-type` / `@phpstan-type`.
    #[serde(default)]
    pub type_aliases: FxHashMap<Arc<str>, Type>,
}

// ---------------------------------------------------------------------------
// EnumDef
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EnumCaseDef {
    pub name: Arc<str>,
    pub value: Option<Type>,
    pub location: Option<Location>,
    /// `@deprecated` docblock annotation, if present.
    #[serde(default)]
    pub deprecated: Option<Arc<str>>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EnumDef {
    pub fqcn: Arc<str>,
    pub short_name: Arc<str>,
    /// Marked `@api` / `@psalm-api`: used from outside the analyzed code.
    #[serde(default)]
    pub is_api: bool,
    pub scalar_type: Option<Type>,
    pub interfaces: Vec<Arc<str>>,
    /// Type arguments from `@implements Interface<T1, T2>`.
    #[serde(default)]
    pub implements_type_args: Vec<(Arc<str>, Vec<Type>)>,
    pub cases: MemberMap<EnumCaseDef>,
    pub own_methods: MemberMap<Arc<MethodDef>>,
    pub own_constants: MemberMap<ConstantDef>,
    /// `use SomeTrait;` declarations. PHP enums may use traits (for methods),
    /// just never carry instance properties from them.
    #[serde(default)]
    pub traits: Vec<Arc<str>>,
    #[serde(default)]
    pub trait_use_locations: Vec<(Arc<str>, Location)>,
    /// Type arguments from `@use SomeTrait<T1, T2>`.
    #[serde(default)]
    pub trait_use_type_args: Vec<(Arc<str>, Vec<Type>)>,
    pub location: Option<Location>,
    /// `@deprecated` docblock annotation (or `#[Deprecated]` attribute), if present.
    #[serde(default)]
    pub deprecated: Option<Arc<str>>,
    /// Type aliases declared on this enum via `@psalm-type` / `@phpstan-type`.
    #[serde(default)]
    pub type_aliases: FxHashMap<Arc<str>, Type>,
    /// Properties declared via `@property*` docblock annotations on the enum.
    #[serde(default)]
    pub own_properties: MemberMap<PropertyDef>,
}

// ---------------------------------------------------------------------------
// FunctionDef
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FunctionDef {
    pub fqn: Arc<str>,
    pub short_name: Arc<str>,
    #[serde(
        deserialize_with = "deserialize_params",
        serialize_with = "serialize_params"
    )]
    pub params: Arc<[DeclaredParam]>,
    /// Type from annotation (`@return` / native type hint). `None` means unannotated.
    /// Stored as `Option<Arc<Type>>` to enable deduplication of common return types.
    #[serde(
        deserialize_with = "deserialize_return_type",
        serialize_with = "serialize_return_type"
    )]
    pub return_type: Option<Arc<Type>>,
    /// See `MethodDef::inferred_return_type` — `Option<Arc<Type>>` (8 B) for the
    /// same demand-driven-inference reason.
    #[serde(
        deserialize_with = "deserialize_return_type",
        serialize_with = "serialize_return_type"
    )]
    pub inferred_return_type: Option<Arc<Type>>,
    pub template_params: Vec<TemplateParam>,
    pub assertions: Vec<Assertion>,
    pub throws: Vec<Arc<str>>,
    pub deprecated: Option<Arc<str>>,
    pub is_pure: bool,
    /// `@psalm-mutation-free` / `@phpstan-mutation-free` on a free function.
    /// A free function has no `$this`, so this is behaviorally equivalent to
    /// `is_external_mutation_free` here (both forbid mutating a parameter);
    /// see `MethodDef::is_mutation_free` for the method-level (has-`$this`)
    /// distinction this mirrors.
    #[serde(default)]
    pub is_mutation_free: bool,
    /// `@psalm-external-mutation-free` on a free function — must not mutate
    /// any object passed as an argument.
    #[serde(default)]
    pub is_external_mutation_free: bool,
    /// `@no-named-arguments` — callers must not use named argument syntax.
    #[serde(default)]
    pub no_named_arguments: bool,
    pub location: Option<Location>,
    /// Plain-text description from the docblock (text before `@tag` lines).
    /// Used for hover info.
    #[serde(default)]
    pub docstring: Option<Arc<str>>,
    /// Prose attached to `@param`, `@return` and `@throws` tags. `None` when
    /// no tag carries a description.
    #[serde(default)]
    pub tag_descriptions: Option<Arc<TagDescriptions>>,
    /// Parameters declared as taint sinks via `@taint-sink <kind> $param`.
    /// Each entry is `(param_name_without_dollar, sink_kind_string)`.
    #[serde(default)]
    pub taint_sink_params: Vec<(Arc<str>, Arc<str>)>,
    /// `@taint-source` — this function's return value is treated as tainted
    /// (attacker-controlled) at every call site, mirroring `@taint-sink`'s
    /// mechanism but marking the source side instead.
    #[serde(default)]
    pub is_taint_source: bool,
    #[serde(default)]
    pub taint: Option<Arc<TaintAnnotations>>,
    /// Type aliases declared on this function via `@psalm-type` / `@phpstan-type`.
    #[serde(default)]
    pub type_aliases: FxHashMap<Arc<str>, Type>,
}

impl FunctionDef {
    pub fn effective_return_type(&self) -> Option<&Type> {
        self.return_type
            .as_deref()
            .or(self.inferred_return_type.as_deref())
    }
}

// ---------------------------------------------------------------------------
// StubSlice — serializable bundle of definitions from one extension's stubs
// ---------------------------------------------------------------------------

/// A `namespace` declaration's byte range with the names it resolves against.
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct NamespaceBlock {
    pub start: u32,
    pub end: u32,
    pub namespace: Option<Arc<str>>,
    #[serde(
        deserialize_with = "deserialize_imports",
        serialize_with = "serialize_imports"
    )]
    pub class_imports: Arc<FxHashMap<Name, Name>>,
    #[serde(
        deserialize_with = "deserialize_imports",
        serialize_with = "serialize_imports"
    )]
    pub function_imports: Arc<FxHashMap<Name, Name>>,
    #[serde(
        deserialize_with = "deserialize_imports",
        serialize_with = "serialize_imports"
    )]
    pub const_imports: Arc<FxHashMap<Name, Name>>,
}

/// A snapshot of all PHP definitions contributed by a single stub file set.
///
/// Produced by `mir-stubs-gen` at code-generation time and deserialized at
/// runtime to ingest definitions into the salsa db via
/// `MirDatabase::ingest_stub_slice`.
#[derive(Debug, Clone, Default, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct StubSlice {
    pub classes: Vec<Arc<ClassDef>>,
    pub interfaces: Vec<Arc<InterfaceDef>>,
    pub traits: Vec<Arc<TraitDef>>,
    pub enums: Vec<Arc<EnumDef>>,
    pub functions: Vec<Arc<FunctionDef>>,
    #[serde(default)]
    pub constants: Vec<(Arc<str>, Type)>,
    /// Source file this slice was collected from. `None` for bundled stub slices
    /// that were pre-computed and are not tied to a specific on-disk file.
    #[serde(default)]
    pub file: Option<Arc<str>>,
    /// Types of `@var`-annotated global variables collected from this file.
    /// Populated by `DefinitionCollector`; ingested into the salsa db's
    /// `global_vars` table by `ingest_stub_slice` when `file` is `Some`.
    #[serde(default)]
    pub global_vars: Vec<(Arc<str>, Type)>,
    /// The first namespace declared in this file (e.g. `"App\\Service"`).
    /// Populated by `DefinitionCollector`; ingested into the salsa db's
    /// `file_namespaces` table by `ingest_stub_slice` when `file` is `Some`.
    #[serde(default)]
    pub namespace: Option<Arc<str>>,
    /// `use` class-like aliases: alias → FQCN. Each `use` kind has its own map, as in PHP.
    #[serde(
        deserialize_with = "deserialize_imports",
        serialize_with = "serialize_imports"
    )]
    #[serde(default = "default_imports")]
    pub class_imports: Arc<FxHashMap<Name, Name>>,
    /// `use function` aliases: alias → function FQN.
    #[serde(
        deserialize_with = "deserialize_imports",
        serialize_with = "serialize_imports"
    )]
    #[serde(default = "default_imports")]
    pub function_imports: Arc<FxHashMap<Name, Name>>,
    /// `use const` aliases: alias → constant FQN.
    #[serde(
        deserialize_with = "deserialize_imports",
        serialize_with = "serialize_imports"
    )]
    #[serde(default = "default_imports")]
    pub const_imports: Arc<FxHashMap<Name, Name>>,
    /// Per-block namespace and imports; populated only when the file declares
    /// two or more `namespace` blocks, otherwise empty.
    #[serde(default)]
    pub namespace_blocks: Arc<[NamespaceBlock]>,
    /// Set to `true` after `deduplicate_params_in_slice` has run on this slice.
    /// `ingest_stub_slice` skips the clone+re-dedup when this flag is set.
    #[serde(skip)]
    pub is_deduped: bool,
}

// ---------------------------------------------------------------------------
// Param list deduplication
// ---------------------------------------------------------------------------

/// Sharded so slices collected in parallel don't serialize on one lock.
type ParamCache =
    dashmap::DashMap<Vec<DeclaredParam>, Arc<[DeclaredParam]>, rustc_hash::FxBuildHasher>;

/// Global cache of canonical Arc<[DeclaredParam]> instances for deduplication.
/// Shared across all StubSlices to deduplicate vendor code with millions of
/// methods that often have identical parameter lists.
static PARAM_DEDUP_CACHE: std::sync::OnceLock<ParamCache> = std::sync::OnceLock::new();

/// Deduplicate parameter lists across all methods and functions in a StubSlice.
/// Many PHP framework methods share identical parameter lists (e.g., thousands
/// of `(string $arg, array $opts)` signatures). This function groups identical
/// param lists globally (across all slices processed so far) and replaces them
/// with Arc<[DeclaredParam]> pointers to shared allocations.
///
/// Expected memory savings: 100–150 MiB on cold start (vendor collection).
pub fn deduplicate_params_in_slice(slice: &mut StubSlice) {
    let cache: &ParamCache =
        PARAM_DEDUP_CACHE.get_or_init(|| dashmap::DashMap::with_hasher(Default::default()));

    let deduplicate = |params: &mut Arc<[DeclaredParam]>| {
        if let Some(existing) = cache.get(params.as_ref()) {
            *params = existing.clone();
            return;
        }
        let canonical = cache
            .entry(params.as_ref().to_vec())
            .or_insert_with(|| params.clone())
            .clone();
        *params = canonical;
    };

    // Deduplicate method params in all classes
    for cls in &mut slice.classes {
        for method in Arc::make_mut(cls).own_methods.values_mut() {
            deduplicate(&mut Arc::make_mut(method).params);
        }
    }

    // Deduplicate method params in all interfaces
    for iface in &mut slice.interfaces {
        for method in Arc::make_mut(iface).own_methods.values_mut() {
            deduplicate(&mut Arc::make_mut(method).params);
        }
    }

    // Deduplicate method params in all traits
    for tr in &mut slice.traits {
        for method in Arc::make_mut(tr).own_methods.values_mut() {
            deduplicate(&mut Arc::make_mut(method).params);
        }
    }

    // Deduplicate method params in all enums
    for en in &mut slice.enums {
        for method in Arc::make_mut(en).own_methods.values_mut() {
            deduplicate(&mut Arc::make_mut(method).params);
        }
    }

    // Deduplicate function params
    for func in &mut slice.functions {
        deduplicate(&mut Arc::make_mut(func).params);
    }
    slice.is_deduped = true;
}