mir_analyzer/

stubs.rs

/// PHP built-in stubs — registered into the salsa db before user-code analysis.
///
/// Stubs are embedded at compile time from the `stubs/{ext}/` workspace directory via
/// `build.rs`.  Each file gets a stable virtual path (e.g. `"stubs/standard/standard_9.php"`)
/// so symbols are source-attributed and go-to-definition works for them.
///
/// # `StubVfs`
///
/// [`StubVfs`] maps every embedded stub file path to its `&'static str` content.
/// Consumers use it to serve stub file content for go-to-definition on
/// built-in PHP symbols:
///
/// ```ignore
/// let file = db.symbol_defining_file("strlen"); // → "stubs/standard/standard_0.php"
/// let src  = stub_vfs.get(&file).unwrap();           // → &'static str PHP source
/// ```
use rustc_hash::{FxHashMap as HashMap, FxHashSet as HashSet};
use std::ops::ControlFlow;
use std::path::{Path, PathBuf};
use std::sync::{Arc, LazyLock};

use mir_codebase::definitions::StubSlice;
use php_ast::owned::visitor::{walk_owned_expr, walk_owned_program, OwnedVisitor};
use php_ast::owned::ExprKind;
use php_lexer::TokenKind;
use rayon::prelude::*;

use crate::db::MirDbStorage;
use crate::php_version::PhpVersion;

// Generated by build.rs: `static STUB_FILES: &[(&str, &str)]`
include!(concat!(env!("OUT_DIR"), "/stub_files.rs"));

// Generated by build.rs: `BUILTIN_FN_NAMES`, `STUB_FN_INDEX`,
// `STUB_CLASS_INDEX`, `STUB_CONST_INDEX`. See build.rs for details.
include!(concat!(env!("OUT_DIR"), "/phpstorm_builtin_fns.rs"));

/// Look up the embedded stub file content for a virtual path (e.g.
/// `"stubs/standard/standard_0.php"`). Returns `None` if the path isn't part
/// of the embedded set.
pub(crate) fn stub_content_for_path(path: &str) -> Option<&'static str> {
    STUB_FILES
        .iter()
        .find_map(|&(p, c)| if p == path { Some(c) } else { None })
}

/// Look up the stub virtual path that defines a built-in PHP function.
/// Lookup is case-insensitive (PHP function names are case-insensitive).
/// Returns `None` if the function isn't a known built-in.
pub(crate) fn stub_path_for_function(name: &str) -> Option<&'static str> {
    let lower = name.to_ascii_lowercase();
    STUB_FN_INDEX
        .binary_search_by(|(k, _)| (*k).cmp(lower.as_str()))
        .ok()
        .map(|i| STUB_FN_INDEX[i].1)
}

/// Look up the stub virtual path that defines a built-in PHP class / interface
/// / trait / enum. Lookup is case-insensitive. Strips a single leading
/// backslash if present. Returns `None` if not a known built-in type.
///
/// Public so the [`StubClassResolver`] in this crate (used by
/// `AnalysisSession` to make `find_class_like` aware of PHP built-ins)
/// can reach it, and so LSP consumers building their own chained
/// resolvers can compose it explicitly.
pub fn stub_path_for_class(fqcn: &str) -> Option<&'static str> {
    let trimmed = fqcn.strip_prefix('\\').unwrap_or(fqcn);
    let lower = trimmed.to_ascii_lowercase();
    STUB_CLASS_INDEX
        .binary_search_by(|(k, _)| (*k).cmp(lower.as_str()))
        .ok()
        .map(|i| STUB_CLASS_INDEX[i].1)
}

/// Look up the stub virtual path that defines a built-in PHP constant.
/// PHP constants are case-sensitive, so this lookup is exact.
pub(crate) fn stub_path_for_constant(name: &str) -> Option<&'static str> {
    let trimmed = name.strip_prefix('\\').unwrap_or(name);
    STUB_CONST_INDEX
        .binary_search_by(|(k, _)| (*k).cmp(trimmed))
        .ok()
        .map(|i| STUB_CONST_INDEX[i].1)
}

/// Scan PHP `source` for identifiers that match known built-in functions /
/// classes / constants, and return the deduplicated list of stub virtual
/// paths needed to cover them.
///
/// This is the core of the lazy-stub auto-discovery used by
/// [`crate::AnalysisSession::ensure_stubs_for_source`]. Uses the PHP lexer
/// to safely extract identifier tokens, avoiding manual byte-level scanning.
/// False positives (e.g., `imagecreate` appearing inside a string literal)
/// cost only one extra stub ingest — cheap and idempotent.
pub(crate) fn collect_referenced_builtin_paths(source: &str) -> Vec<&'static str> {
    use php_lexer::lex_all;

    let mut tokens: HashSet<&str> = HashSet::default();
    let (lexed, _errors) = lex_all(source);

    let mut i = 0;
    while i < lexed.len() {
        let token = &lexed[i];
        if token.kind == TokenKind::Identifier {
            let start = token.span.start as usize;
            let end = token.span.end as usize;
            if let Some(mut text) = source.get(start..end) {
                // Handle namespaced identifiers: Foo\Bar\Baz
                let mut j = i + 1;
                while j + 1 < lexed.len()
                    && lexed[j].kind == TokenKind::Backslash
                    && lexed[j + 1].kind == TokenKind::Identifier
                {
                    j += 2;
                    if let Some(part) = source.get(start..(lexed[j - 1].span.end as usize)) {
                        text = part;
                    }
                }
                tokens.insert(text);
                i = j;
            } else {
                i += 1;
            }
        } else {
            i += 1;
        }
    }

    let mut paths: HashSet<&'static str> = HashSet::default();
    for token in tokens {
        if let Some(p) = stub_path_for_function(token) {
            paths.insert(p);
        }
        if let Some(p) = stub_path_for_class(token) {
            paths.insert(p);
        }
        if let Some(p) = stub_path_for_constant(token) {
            paths.insert(p);
        }
    }
    paths.into_iter().collect()
}

/// Walk the parsed AST to find identifiers that match known built-in functions /
/// classes / constants, and return the deduplicated list of stub virtual paths.
///
/// Unlike [`collect_referenced_builtin_paths`], this walks the real AST instead
/// of doing a byte-level heuristic scan. This eliminates false positives from
/// function names appearing inside string literals or comments. Used by
/// [`crate::AnalysisSession::ensure_stubs_for_ast`] for single-file analysis
/// where the AST is already available.
pub(crate) fn collect_referenced_builtin_paths_from_ast(
    program: &php_ast::owned::Program,
) -> Vec<&'static str> {
    let mut visitor = BuiltinRefVisitor {
        paths: HashSet::default(),
    };
    let _ = walk_owned_program(&mut visitor, program);
    visitor.paths.into_iter().collect()
}

/// Visitor for extracting function/class/constant references from the AST.
struct BuiltinRefVisitor {
    paths: HashSet<&'static str>,
}

impl OwnedVisitor for BuiltinRefVisitor {
    fn visit_expr(&mut self, expr: &php_ast::owned::Expr) -> ControlFlow<()> {
        match &expr.kind {
            ExprKind::FunctionCall(call) => {
                if let ExprKind::Identifier(name) = &call.name.kind {
                    if let Some(p) = stub_path_for_function(name.as_ref()) {
                        self.paths.insert(p);
                    }
                }
            }
            ExprKind::New(new_expr) => {
                if let ExprKind::Identifier(name) = &new_expr.class.kind {
                    if let Some(p) = stub_path_for_class(name.as_ref()) {
                        self.paths.insert(p);
                    }
                }
            }
            ExprKind::StaticMethodCall(call) => {
                if let ExprKind::Identifier(name) = &call.class.kind {
                    if let Some(p) = stub_path_for_class(name.as_ref()) {
                        self.paths.insert(p);
                    }
                }
            }
            ExprKind::ClassConstAccess(access) => {
                if let ExprKind::Identifier(name) = &access.class.kind {
                    if let Some(p) = stub_path_for_class(name.as_ref()) {
                        self.paths.insert(p);
                    }
                }
            }
            ExprKind::Identifier(name) => {
                if let Some(p) = stub_path_for_constant(name.as_ref()) {
                    self.paths.insert(p);
                }
            }
            _ => {}
        }
        walk_owned_expr(self, expr)
    }
}

// ---------------------------------------------------------------------------
// Public accessors for embedded stub data
// ---------------------------------------------------------------------------

/// Every PHP stub file from `stubs/{ext}/` embedded at compile time as `(path, content)`.
///
/// Path is workspace-relative (e.g. `"stubs/standard/standard_9.php"`).
pub fn stub_files() -> &'static [(&'static str, &'static str)] {
    STUB_FILES
}

// ---------------------------------------------------------------------------
// Public entry point
// ---------------------------------------------------------------------------

/// Default-version entry point retained for callers (CLI, benches, tests) that
/// don't track a target PHP version. Equivalent to
/// [`load_stubs_for_version`] with `PhpVersion::LATEST`.
#[allow(dead_code)]
pub(crate) fn load_stubs(db: &mut MirDbStorage) {
    load_stubs_for_version(db, PhpVersion::LATEST);
}

/// Load stubs filtered for `php_version`. Symbols whose `@since` post-dates
/// the target, or whose `@removed` is at or before the target, are skipped —
/// so multiple declarations of the same name (e.g. `each` on PHP 7 vs.
/// PHP 8) gated by `@since`/`@removed` collapse to the one matching variant.
pub(crate) fn load_stubs_for_version(db: &mut MirDbStorage, php_version: PhpVersion) {
    // Wire the target version before registering any SourceFile inputs so
    // collect_file_definitions reads the right version for @since/@removed filtering.
    db.set_php_version(Arc::from(php_version.to_string().as_str()));
    // Register each stub file's text as a salsa `SourceFile` input.
    // `find_class_like` / `find_function` resolve built-in PHP symbols by
    // routing through the `StubClassResolver` we install below.
    for (filename, content) in STUB_FILES {
        let arc_path: Arc<str> = Arc::from(*filename);
        let arc_content: Arc<str> = Arc::from(*content);
        db.upsert_source_file(arc_path, arc_content);
    }
    let resolver: Arc<dyn crate::ClassResolver> = Arc::new(crate::StubClassResolver);
    db.set_resolver(Some(resolver));
}

pub(crate) fn builtin_stub_slices_for_version(php_version: PhpVersion) -> Vec<StubSlice> {
    STUB_FILES
        .par_iter()
        .map(|(filename, content)| stub_slice_from_source(filename, content, Some(php_version)))
        .collect()
}

pub(crate) fn stub_slice_from_source(
    filename: &str,
    content: &str,
    php_version: Option<PhpVersion>,
) -> StubSlice {
    let result = php_rs_parser::parse(content);
    let file: Arc<str> = Arc::from(filename);
    let collector =
        crate::collector::DefinitionCollector::new_for_slice(file, content, &result.source_map);
    let collector = match php_version {
        Some(version) => collector.with_php_version(version),
        None => collector,
    };
    let (mut slice, _) = collector.collect_slice(&result.program);
    mir_codebase::definitions::deduplicate_params_in_slice(&mut slice);
    slice
}

pub(crate) fn collect_stub_dir_paths(dir: &Path, paths: &mut Vec<PathBuf>) {
    let entries = match std::fs::read_dir(dir) {
        Ok(e) => e,
        Err(e) => {
            eprintln!("mir: cannot read stub directory {}: {}", dir.display(), e);
            return;
        }
    };
    let mut dir_entries: Vec<PathBuf> = entries.filter_map(|e| e.ok().map(|e| e.path())).collect();
    dir_entries.sort_unstable();
    for path in dir_entries {
        if path.is_dir() {
            collect_stub_dir_paths(&path, paths);
        } else if path.extension().is_some_and(|e| e == "php") {
            paths.push(path);
        }
    }
}

/// Fingerprint the user-configured stub set (paths + contents) for the result
/// cache epoch. User stubs are resolvable just like bundled ones, so editing,
/// adding, or removing them changes analysis output for files that reference
/// those symbols — and the per-file content hash can't see it. Returns 0 when
/// no user stubs are configured (the common case), so the epoch is unaffected.
pub(crate) fn user_stub_fingerprint(files: &[PathBuf], dirs: &[PathBuf]) -> u64 {
    if files.is_empty() && dirs.is_empty() {
        return 0;
    }
    let mut all_paths: Vec<PathBuf> = files.to_vec();
    for dir in dirs {
        collect_stub_dir_paths(dir, &mut all_paths);
    }
    // Sort for a path-order-independent fingerprint.
    all_paths.sort_unstable();
    let mut hasher = blake3::Hasher::new();
    for path in &all_paths {
        hasher.update(path.to_string_lossy().as_bytes());
        hasher.update(&[0]);
        // Content too, so an in-place edit of a stub flips the fingerprint.
        // A read failure still contributes the path, so add/remove is caught.
        if let Ok(src) = std::fs::read(path) {
            hasher.update(&src);
        }
        hasher.update(&[0]);
    }
    let bytes = hasher.finalize();
    u64::from_le_bytes(bytes.as_bytes()[..8].try_into().unwrap())
}

// ---------------------------------------------------------------------------
// StubVfs — virtual file system for stub content
// ---------------------------------------------------------------------------

/// A read-only map from stub file path to its embedded PHP source content.
///
/// Consumers use this to serve stub source for go-to-definition on built-in
/// PHP symbols.
///
/// # Example
///
/// ```ignore
/// let vfs = StubVfs::new();
/// // After analysis:
/// if let Some(path) = session.symbol_defining_file("strlen") {
///     if let Some(src) = vfs.get(path.as_ref()) {
///         // serve `src` as a read-only virtual document
///     }
/// }
/// ```
pub struct StubVfs {
    files: HashMap<&'static str, &'static str>,
}

impl StubVfs {
    /// Build the VFS from the embedded stub set.
    pub fn new() -> Self {
        let files = STUB_FILES.iter().map(|&(p, c)| (p, c)).collect();
        Self { files }
    }

    /// Return the PHP source for `path`, or `None` if it is not a stub file.
    pub fn get(&self, path: &str) -> Option<&'static str> {
        self.files.get(path).copied()
    }

    /// Return `true` if `path` is a known stub file path.
    pub fn is_stub_file(&self, path: &str) -> bool {
        self.files.contains_key(path)
    }
}

impl Default for StubVfs {
    fn default() -> Self {
        Self::new()
    }
}

// ---------------------------------------------------------------------------
// StubClassResolver — ClassResolver for bundled PHP built-in stubs
// ---------------------------------------------------------------------------

/// [`crate::ClassResolver`] that maps PHP built-in class FQCNs
/// (`ArrayObject`, `Exception`, `ReflectionClass`, …) to the stub virtual
/// path that defines them. Used by [`crate::ChainedClassResolver`] to
/// make `find_class_like` aware of PHP built-ins in addition to the
/// user's PSR-4 / classmap.
///
/// The returned paths are the same virtual paths used by [`StubVfs`] and
/// matched against `MirDbStorage`'s registered `SourceFile`s when stubs are
/// loaded (see `load_stubs_for_version`, which calls `upsert_source_file`
/// for each stub).
pub struct StubClassResolver;

impl crate::ClassResolver for StubClassResolver {
    fn resolve(&self, fqcn: &str) -> Option<std::path::PathBuf> {
        // Try classes first; then functions / constants — built-in FQNs
        // share a single resolver since they all map to the bundled stub
        // VFS paths registered as SourceFile inputs.
        stub_path_for_class(fqcn)
            .or_else(|| stub_path_for_function(fqcn))
            .or_else(|| stub_path_for_constant(fqcn))
            .map(std::path::PathBuf::from)
    }
}

/// [`crate::ClassResolver`] composing a primary resolver (user's PSR-4 /
/// classmap) with a fallback (typically [`StubClassResolver`]). The
/// primary is consulted first; if it misses, the fallback is tried.
///
/// `AnalysisSession::with_psr4` and `with_class_resolver` automatically
/// wrap the user-supplied resolver in this chain so PHP built-ins are
/// resolvable through `resolve_fqcn_to_path` (and therefore
/// `find_class_like`) without per-consumer setup.
pub struct ChainedClassResolver {
    primary: Arc<dyn crate::ClassResolver>,
    fallback: Arc<dyn crate::ClassResolver>,
}

impl ChainedClassResolver {
    pub fn new(
        primary: Arc<dyn crate::ClassResolver>,
        fallback: Arc<dyn crate::ClassResolver>,
    ) -> Self {
        Self { primary, fallback }
    }
}

impl crate::ClassResolver for ChainedClassResolver {
    fn resolve(&self, fqcn: &str) -> Option<std::path::PathBuf> {
        self.primary
            .resolve(fqcn)
            .or_else(|| self.fallback.resolve(fqcn))
    }
}

// ---------------------------------------------------------------------------
// Builtin-function query
// ---------------------------------------------------------------------------

/// Returns `true` if `name` is a known PHP built-in function.
///
/// Fast path: binary search on `BUILTIN_FN_NAMES`, a sorted compile-time slice
/// generated from `PhpStormStubsMap.php` by `build.rs`.
///
/// Fallback (when `BUILTIN_FN_NAMES` is empty): reads the embedded stub slices and checks
/// the embedded stubs and checks membership there.
///
/// # Example
/// ```
/// assert!(mir_analyzer::stubs::is_builtin_function("strlen"));
/// assert!(!mir_analyzer::stubs::is_builtin_function("my_custom_function"));
/// ```
pub fn is_builtin_function(name: &str) -> bool {
    if !BUILTIN_FN_NAMES.is_empty() {
        return BUILTIN_FN_NAMES.binary_search(&name).is_ok();
    }
    static FALLBACK: LazyLock<HashSet<Arc<str>>> = LazyLock::new(|| {
        builtin_stub_slices_for_version(PhpVersion::LATEST)
            .into_iter()
            .flat_map(|slice| slice.functions.into_iter().map(|func| func.fqn.clone()))
            .collect()
    });
    FALLBACK.contains(name)
}

// ---------------------------------------------------------------------------
// Builtin-constant query
// ---------------------------------------------------------------------------

/// Returns `true` if `name` is a known PHP built-in constant (`PHP_EOL`,
/// `PHP_VERSION`, ...).
///
/// PHP constants are case-sensitive, so — unlike [`stub_path_for_class`]'s
/// case-insensitive class-name lookup — this match is exact. A leading `\`
/// (the global-namespace escape) is stripped first, same as
/// [`stub_path_for_class`] does for class names.
///
/// # Example
/// ```
/// assert!(mir_analyzer::stubs::is_builtin_constant("PHP_EOL"));
/// assert!(!mir_analyzer::stubs::is_builtin_constant("MY_CUSTOM_CONST"));
/// ```
pub fn is_builtin_constant(name: &str) -> bool {
    stub_path_for_constant(name).is_some()
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use crate::db::{class_exists, constant_exists, function_exists, MirDatabase, MirDbStorage};

    fn stubs_codebase() -> MirDbStorage {
        let mut db = MirDbStorage::default();
        load_stubs(&mut db);
        db
    }

    fn stubs_codebase_for(version: PhpVersion) -> MirDbStorage {
        let mut db = MirDbStorage::default();
        load_stubs_for_version(&mut db, version);
        db
    }

    fn stub_function_for(
        version: PhpVersion,
        name: &str,
    ) -> Option<std::sync::Arc<mir_codebase::FunctionDef>> {
        builtin_stub_slices_for_version(version)
            .into_iter()
            .flat_map(|slice| slice.functions.into_iter())
            .find(|func| func.fqn.as_ref() == name)
    }

    fn stub_class_for(
        version: PhpVersion,
        name: &str,
    ) -> Option<std::sync::Arc<mir_codebase::ClassDef>> {
        builtin_stub_slices_for_version(version)
            .into_iter()
            .flat_map(|slice| slice.classes.into_iter())
            .find(|cls| cls.fqcn.as_ref() == name)
    }

    #[test]
    fn since_filter_applies_to_methods() {
        // Direct stub-slice probe — independent of which path is consulted
        // for symbol lookup.
        let cls = stub_class_for(PhpVersion::new(7, 4), "DateTimeImmutable")
            .expect("DateTimeImmutable must exist");
        assert!(
            !cls.own_methods.contains_key("createfrominterface"),
            "createFromInterface should be absent on PHP 7.4"
        );

        let cls_new = stub_class_for(PhpVersion::new(8, 0), "DateTimeImmutable")
            .expect("DateTimeImmutable must exist");
        assert!(
            cls_new.own_methods.contains_key("createfrominterface"),
            "createFromInterface should be present on PHP 8.0"
        );
    }

    #[test]
    fn since_tag_excludes_function_below_target() {
        let cb = stubs_codebase_for(PhpVersion::new(7, 4));
        assert!(
            !function_exists(&cb, "str_contains"),
            "str_contains (@since 8.0) must be absent on PHP 7.4"
        );
        assert!(
            !function_exists(&cb, "str_starts_with"),
            "str_starts_with (@since 8.0) must be absent on PHP 7.4"
        );
        assert!(
            !function_exists(&cb, "array_is_list"),
            "array_is_list (@since 8.1) must be absent on PHP 7.4"
        );

        let cb80 = stubs_codebase_for(PhpVersion::new(8, 0));
        assert!(
            function_exists(&cb80, "str_contains"),
            "str_contains must be present on PHP 8.0"
        );
        assert!(
            !function_exists(&cb80, "array_is_list"),
            "array_is_list (@since 8.1) must be absent on PHP 8.0"
        );

        let cb81 = stubs_codebase_for(PhpVersion::new(8, 1));
        assert!(
            function_exists(&cb81, "array_is_list"),
            "array_is_list must be present on PHP 8.1"
        );
    }

    #[test]
    fn removed_tag_excludes_function_at_or_after_target() {
        // hebrevc() was removed in PHP 8.0 (@removed 8.0).
        let cb74 = stubs_codebase_for(PhpVersion::new(7, 4));
        assert!(
            function_exists(&cb74, "hebrevc"),
            "hebrevc must be present on PHP 7.4"
        );

        let cb80 = stubs_codebase_for(PhpVersion::new(8, 0));
        assert!(
            !function_exists(&cb80, "hebrevc"),
            "hebrevc (@removed 8.0) must be absent on PHP 8.0"
        );
    }

    fn assert_fn(cb: &MirDbStorage, name: &str) {
        assert!(
            function_exists(cb, name),
            "expected stub for `{name}` to be registered"
        );
    }

    #[test]
    fn sscanf_vars_param_is_byref_and_variadic() {
        let func = stub_function_for(PhpVersion::LATEST, "sscanf").expect("sscanf must be defined");
        let vars = func.params.get(2).expect("sscanf must have a 3rd param");
        assert!(vars.is_byref, "sscanf vars param must be by-ref");
        assert!(vars.is_variadic, "sscanf vars param must be variadic");
    }

    #[test]
    fn sscanf_output_vars_not_undefined() {
        use crate::batch::BatchOptions;
        use crate::session::AnalysisSession;
        use crate::PhpVersion;
        use mir_issues::IssueKind;

        let src = "<?php\nfunction test($str) {\n    sscanf($str, \"%d %d\", $row, $col);\n    return $row + $col;\n}\n";
        let tmp = std::env::temp_dir().join("mir_test_sscanf_undefined.php");
        std::fs::write(&tmp, src).unwrap();
        let session = AnalysisSession::new(PhpVersion::LATEST);
        let result = session.analyze_paths(
            std::slice::from_ref(&tmp),
            &BatchOptions::new().without_symbols(),
        );
        std::fs::remove_file(tmp).ok();
        let undef: Vec<_> = result.issues.iter()
            .filter(|i| matches!(&i.kind, IssueKind::UndefinedVariable { name } if name == "row" || name == "col"))
            .collect();
        assert!(
            undef.is_empty(),
            "sscanf output vars must not be reported as UndefinedVariable; got: {undef:?}"
        );
    }

    #[test]
    fn stream_functions_are_defined() {
        let cb = stubs_codebase();
        assert_fn(&cb, "stream_isatty");
        assert_fn(&cb, "stream_select");
        assert_fn(&cb, "stream_get_meta_data");
        assert_fn(&cb, "stream_set_blocking");
        assert_fn(&cb, "stream_copy_to_stream");
    }

    #[test]
    fn preg_grep_is_defined() {
        let cb = stubs_codebase();
        assert_fn(&cb, "preg_grep");
    }

    #[test]
    fn standard_missing_functions_are_defined() {
        let cb = stubs_codebase();
        assert_fn(&cb, "get_resource_type");
        assert_fn(&cb, "ftruncate");
        assert_fn(&cb, "umask");
        assert_fn(&cb, "date_default_timezone_set");
        assert_fn(&cb, "date_default_timezone_get");
    }

    #[test]
    fn mb_missing_functions_are_defined() {
        let cb = stubs_codebase();
        assert_fn(&cb, "mb_strwidth");
        assert_fn(&cb, "mb_convert_variables");
    }

    #[test]
    fn pcntl_functions_are_defined() {
        let cb = stubs_codebase();
        assert_fn(&cb, "pcntl_signal");
        assert_fn(&cb, "pcntl_async_signals");
        assert_fn(&cb, "pcntl_signal_get_handler");
        assert_fn(&cb, "pcntl_alarm");
    }

    #[test]
    fn posix_functions_are_defined() {
        let cb = stubs_codebase();
        assert_fn(&cb, "posix_kill");
        assert_fn(&cb, "posix_getpid");
    }

    #[test]
    fn sapi_windows_functions_are_defined() {
        let cb = stubs_codebase();
        assert_fn(&cb, "sapi_windows_vt100_support");
        assert_fn(&cb, "sapi_windows_cp_set");
        assert_fn(&cb, "sapi_windows_cp_get");
        assert_fn(&cb, "sapi_windows_cp_conv");
    }

    #[test]
    fn cli_functions_are_defined() {
        let cb = stubs_codebase();
        assert_fn(&cb, "cli_set_process_title");
        assert_fn(&cb, "cli_get_process_title");
    }

    #[test]
    fn builtin_fn_names_has_sufficient_entries() {
        // Guards against PhpStormStubsMap.php parsing regressions in build.rs.
        // When the submodule is absent the slice is empty — skip the check in that case.
        if BUILTIN_FN_NAMES.is_empty() {
            return;
        }
        assert!(
            BUILTIN_FN_NAMES.len() >= 500,
            "BUILTIN_FN_NAMES has only {} entries — \
             build.rs may have failed to parse PhpStormStubsMap.php correctly",
            BUILTIN_FN_NAMES.len()
        );
    }

    #[test]
    fn preg_match_matches_param_is_byref_with_type() {
        let func = stub_function_for(PhpVersion::LATEST, "preg_match")
            .expect("preg_match should exist in stubs");
        let matches_param = func
            .params
            .iter()
            .find(|p| p.name.as_ref() == "matches")
            .expect("preg_match should have a $matches param");
        assert!(matches_param.is_byref, "$matches should be byref");
        assert!(
            matches_param.ty.is_some(),
            "$matches should have a type annotation (string[] from PHPDoc)"
        );
    }

    #[test]
    fn is_builtin_function_returns_true_for_known_builtins() {
        assert!(is_builtin_function("strlen"), "strlen should be a builtin");
        assert!(
            is_builtin_function("array_map"),
            "array_map should be a builtin"
        );
        assert!(
            is_builtin_function("json_encode"),
            "json_encode should be a builtin"
        );
        assert!(
            is_builtin_function("preg_match"),
            "preg_match should be a builtin"
        );
    }

    #[test]
    fn is_builtin_function_covers_stdlib_functions() {
        assert!(is_builtin_function("bcadd"), "bcadd should be a builtin");
        assert!(
            is_builtin_function("sodium_crypto_secretbox"),
            "sodium_crypto_secretbox should be a builtin"
        );
    }

    #[test]
    fn is_builtin_function_returns_false_for_unknown_names() {
        assert!(
            !is_builtin_function("my_custom_function"),
            "my_custom_function should not be a builtin"
        );
        assert!(
            !is_builtin_function(""),
            "empty string should not be a builtin"
        );
        assert!(
            !is_builtin_function("gearman_bugreport"),
            "extension function with no vendored stub dir should not be a builtin"
        );
    }

    #[test]
    fn is_builtin_constant_returns_true_for_known_constants() {
        assert!(
            is_builtin_constant("PHP_EOL"),
            "PHP_EOL should be a builtin"
        );
        assert!(
            is_builtin_constant("PHP_VERSION"),
            "PHP_VERSION should be a builtin"
        );
    }

    #[test]
    fn is_builtin_constant_is_case_sensitive() {
        assert!(
            !is_builtin_constant("php_eol"),
            "PHP constant lookup is exact-case, unlike class names"
        );
    }

    #[test]
    fn is_builtin_constant_strips_leading_backslash() {
        assert!(
            is_builtin_constant("\\PHP_EOL"),
            "a global-namespace-escaped constant should still resolve"
        );
    }

    #[test]
    fn is_builtin_constant_returns_false_for_unknown_names() {
        assert!(
            !is_builtin_constant("MY_CUSTOM_CONST"),
            "MY_CUSTOM_CONST should not be a builtin"
        );
        assert!(
            !is_builtin_constant(""),
            "empty string should not be a builtin"
        );
    }

    // --- stub coverage tests ---

    fn assert_cls(cb: &MirDbStorage, name: &str) {
        assert!(
            class_exists(cb, name),
            "expected stub class `{name}` to be registered"
        );
    }

    fn assert_iface(cb: &MirDbStorage, name: &str) {
        assert!(
            class_exists(cb, name),
            "expected stub interface `{name}` to be registered"
        );
    }

    fn assert_const(cb: &MirDbStorage, name: &str) {
        assert!(
            constant_exists(cb, name),
            "expected stub constant `{name}` to be registered"
        );
    }

    #[test]
    fn stubs_coverage_counts() {
        let mut fn_count = 0usize;
        let mut type_count = 0usize;
        let mut const_count = 0usize;
        for slice in builtin_stub_slices_for_version(PhpVersion::LATEST) {
            fn_count += slice.functions.len();
            type_count += slice.classes.len()
                + slice.interfaces.len()
                + slice.traits.len()
                + slice.enums.len();
            const_count += slice.constants.len();
        }
        assert!(fn_count > 500, "expected >500 functions, got {fn_count}");
        assert!(type_count > 120, "expected >120 types, got {type_count}");
        assert!(
            const_count > 200,
            "expected >200 constants, got {const_count}"
        );
    }

    #[test]
    fn curl_multi_exec_still_running_is_byref() {
        let func = stub_function_for(PhpVersion::LATEST, "curl_multi_exec")
            .expect("curl_multi_exec must be defined");
        let still_running = func
            .params
            .iter()
            .find(|p| p.name.as_ref() == "still_running")
            .expect("curl_multi_exec must have a still_running param");
        assert!(
            still_running.is_byref,
            "curl_multi_exec $still_running must be by-ref (generated from PHP stub)"
        );
    }

    // --- Stub loading regression tests ---

    #[test]
    fn stub_files_are_non_empty() {
        // Regression: STUB_FILES was silently empty when build.rs used
        // the crate manifest dir instead of the workspace root to locate stubs/.
        assert!(
            !STUB_FILES.is_empty(),
            "STUB_FILES must not be empty — check build.rs find_workspace_root()"
        );
    }

    #[test]
    fn stub_vfs_resolves_all_paths() {
        let vfs = StubVfs::new();
        for &(path, expected_content) in STUB_FILES {
            let got = vfs
                .get(path)
                .unwrap_or_else(|| panic!("StubVfs::get({path:?}) returned None"));
            assert_eq!(got, expected_content, "StubVfs content mismatch for {path}");
            assert!(
                vfs.is_stub_file(path),
                "StubVfs::is_stub_file({path:?}) returned false"
            );
        }
    }

    #[test]
    fn stub_vfs_rejects_user_file_paths() {
        let vfs = StubVfs::new();
        assert!(!vfs.is_stub_file("/tmp/user_code.php"));
        assert!(!vfs.is_stub_file("src/MyClass.php"));
        assert!(!vfs.is_stub_file(""));
    }

    #[test]
    fn symbol_to_file_paths_are_resolvable_via_stub_vfs() {
        let mut db = MirDbStorage::default();
        db.init_workspace_revision();
        load_stubs(&mut db);
        let vfs = StubVfs::new();

        let functions = crate::db::workspace_functions(&db);
        for symbol in functions.iter() {
            let Some(path) = db.symbol_defining_file(symbol.as_str()) else {
                continue;
            };
            assert!(
                vfs.get(path.as_ref()).is_some(),
                "symbol '{}' points to '{}' which StubVfs cannot resolve — \
                 go-to-definition would silently break for this symbol",
                symbol.as_str(),
                path
            );
        }
    }

    #[test]
    fn function_lookup_is_case_insensitive() {
        // PHP function names are case-insensitive: `STRLEN($x)` must resolve
        // to the same node as `strlen($x)`. Regression for users seeing
        // `UndefinedFunction: Function Restore_Error_Handler() is not defined`
        // on mixed-case calls of built-ins.
        let cb = stubs_codebase();
        assert!(function_exists(&cb, "strlen"));
        assert!(function_exists(&cb, "STRLEN"));
        assert!(function_exists(&cb, "StrLen"));
        assert!(function_exists(&cb, "Restore_Error_Handler"));
        assert!(function_exists(&cb, "RESTORE_ERROR_HANDLER"));
    }

    #[test]
    fn class_lookup_is_case_insensitive() {
        // PHP class names are case-insensitive: `new arrayobject()` must
        // resolve to `ArrayObject`. Regression for `UndefinedClass` on
        // lower- or upper-cased built-in class references.
        let cb = stubs_codebase();
        assert!(class_exists(&cb, "ArrayObject"));
        assert!(class_exists(&cb, "arrayobject"));
        assert!(class_exists(&cb, "ARRAYOBJECT"));
        assert!(class_exists(&cb, "ArrayOBJECT"));
    }

    #[test]
    fn constant_lookup_stays_case_sensitive() {
        // PHP global constants ARE case-sensitive (except true/false/null).
        // Make sure the case-insensitivity fix for functions/classes did not
        // leak into constants.
        let cb = stubs_codebase();
        assert!(constant_exists(&cb, "PHP_INT_MAX"));
        assert!(!constant_exists(&cb, "php_int_max"));
        assert!(!constant_exists(&cb, "Php_Int_Max"));
    }

    #[test]
    fn stdlib_symbols_are_loaded() {
        let cb = stubs_codebase();

        assert_fn(&cb, "bcadd");
        assert_fn(&cb, "bcsub");
        assert_fn(&cb, "bcmul");
        assert_fn(&cb, "bcdiv");
        assert_fn(&cb, "sodium_crypto_secretbox");
        assert_fn(&cb, "sodium_randombytes_buf");

        assert_cls(&cb, "SplObjectStorage");
        assert_cls(&cb, "SplHeap");
        assert_cls(&cb, "IteratorIterator");
        assert_cls(&cb, "FilterIterator");
        assert_cls(&cb, "LimitIterator");
        assert_cls(&cb, "CallbackFilterIterator");
        assert_cls(&cb, "RegexIterator");
        assert_cls(&cb, "AppendIterator");
        assert_cls(&cb, "GlobIterator");
        assert_cls(&cb, "ReflectionObject");
        assert_cls(&cb, "Attribute");

        assert_iface(&cb, "SeekableIterator");
        assert_iface(&cb, "SplObserver");
        assert_iface(&cb, "SplSubject");

        assert_const(&cb, "PHP_INT_MAX");
        assert_const(&cb, "PHP_INT_MIN");
        assert_const(&cb, "PHP_EOL");
        assert_const(&cb, "SORT_REGULAR");
        assert_const(&cb, "JSON_THROW_ON_ERROR");
        assert_const(&cb, "FILTER_VALIDATE_EMAIL");
        assert_const(&cb, "PREG_OFFSET_CAPTURE");
        assert_const(&cb, "M_PI");
        assert_const(&cb, "PASSWORD_DEFAULT");
    }
}