arity 0.17.0

//! Symbol resolution against package namespaces.
//!
//! The default `StaticBaseR` provider knows the exports of R's seven default
//! packages (`base`, `utils`, `stats`, `methods`, `datasets`, `grDevices`,
//! `graphics`) — the same set R attaches on startup before any `.Rprofile` or
//! `library()` call. Symbol lists are baked in via `include_str!` from
//! `src/semantic/base_r/*.txt`, generated by `scripts/dump_base_symbols.R`.
//!
//! Non-default packages discovered via `library()` calls resolve against
//! [`BundledPackages`] — names-only export lists for the top-N CRAN packages by
//! download count, baked in via `include_str!` from
//! `src/semantic/cran/exports.txt` (generated by `scripts/dump_cran_symbols.R`,
//! ranked by `scripts/rank_cran_downloads.sh`). Packages outside that set still
//! resolve as [`PackageOrigin::Unknown`] unless locally harvested.

use std::collections::{HashMap, HashSet};
use std::path::Path;
use std::sync::LazyLock;

use rowan::TextRange;
use smol_str::SmolStr;

const PACKAGE_BASE: &str = "base";
const PACKAGE_UTILS: &str = "utils";
const PACKAGE_STATS: &str = "stats";
const PACKAGE_METHODS: &str = "methods";
const PACKAGE_DATASETS: &str = "datasets";
const PACKAGE_GRDEVICES: &str = "grDevices";
const PACKAGE_GRAPHICS: &str = "graphics";

const DEFAULT_PACKAGES: &[&str] = &[
    PACKAGE_BASE,
    PACKAGE_UTILS,
    PACKAGE_STATS,
    PACKAGE_METHODS,
    PACKAGE_DATASETS,
    PACKAGE_GRDEVICES,
    PACKAGE_GRAPHICS,
];

/// A `library()` / `require()` / `requireNamespace()` call discovered in the
/// file, in source order.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LoadedPackage {
    pub name: SmolStr,
    pub range: TextRange,
}

/// Core packages a *meta-package* attaches at load time via its `.onAttach`
/// hook. R's `library(tidyverse)` puts these on the search path too, but they
/// are not in the meta-package's own export list, so we model the attachment
/// explicitly — otherwise e.g. `tibble()` (exported by tibble, attached by
/// tidyverse) would resolve to nothing. Returns an empty slice for ordinary
/// packages. The members must themselves be resolvable (default / harvested /
/// remote / bundled) for their exports to actually resolve.
///
/// This static curated table is the *fallback*: when a meta-package is
/// installed and its attach set was captured at harvest time
/// ([`PackageIndex::attaches`](crate::rindex::schema::PackageIndex)), the
/// harvested, version-exact set wins (see
/// [`SymbolProvider::attached_packages`] and `rindex::provider`'s
/// `attach_members`). The table answers for uninstalled meta-packages and the
/// names-only remote/bundled tiers, which cannot carry an attach set.
pub fn meta_package_members(name: &str) -> &'static [&'static str] {
    // tidyverse 2.0 core set (attached by `library(tidyverse)`).
    const TIDYVERSE: &[&str] = &[
        "dplyr",
        "forcats",
        "ggplot2",
        "lubridate",
        "purrr",
        "readr",
        "stringr",
        "tibble",
        "tidyr",
    ];
    match name {
        "tidyverse" => TIDYVERSE,
        _ => &[],
    }
}

/// Packages attached *implicitly* for a file, by virtue of its location rather
/// than any `library()`/`require()` call in its text. Folded into the file's
/// loaded-package set so symbol resolution treats them as on the search path.
///
/// The one case today: testthat attaches itself before sourcing a package's
/// `tests/testthat/` files, so their `test_that`/`expect_*` calls resolve
/// without an explicit `library(testthat)` that the convention omits.
pub fn implicit_attached_packages(path: &Path) -> &'static [&'static str] {
    if is_testthat_file(path) {
        &["testthat"]
    } else {
        &[]
    }
}

/// Whether `path` is a testthat test file: a direct member of a `tests/testthat/`
/// directory (test, `helper*`, and `setup*` files all live flat there). Matched
/// structurally on the parent (`testthat`) and grandparent (`tests`) names.
fn is_testthat_file(path: &Path) -> bool {
    fn dir_name(dir: Option<&Path>) -> Option<&str> {
        dir.and_then(Path::file_name).and_then(|n| n.to_str())
    }
    let dir = path.parent();
    dir_name(dir) == Some("testthat") && dir_name(dir.and_then(Path::parent)) == Some("tests")
}

/// Whether a call to `name` evaluates (some of) its arguments under R's
/// data-masking / tidy-evaluation rules, where a bare identifier resolves to a
/// data-frame column rather than an in-scope binding or package export.
///
/// Identifiers inside such a call's arguments cannot be judged "undefined"
/// statically — the column set is data-dependent — so `undefined-symbol`
/// suppresses them (see the builder's `mask_depth`). The match is name-only
/// (the last `::` segment), independent of which package is actually attached:
/// over-matching only ever *suppresses* a finding, the conservative direction
/// for a rule whose sole risk is false positives.
pub fn is_data_masking_callee(name: &str) -> bool {
    matches!(
        name,
        // base R
        "with" | "within" | "subset" | "transform"
        // dplyr data-masking verbs
        | "mutate" | "transmute" | "summarise" | "summarize" | "filter" | "arrange"
        | "group_by" | "reframe" | "slice" | "slice_head" | "slice_tail" | "slice_min"
        | "slice_max" | "slice_sample" | "count" | "add_count" | "tally" | "add_tally"
        | "distinct" | "rename" | "rename_with" | "select" | "relocate" | "pull"
        | "group_split"
        // tidyr data-masking / tidyselect
        | "pivot_longer" | "pivot_wider" | "nest" | "unnest" | "separate"
        | "separate_wider_delim" | "separate_wider_position" | "separate_wider_regex"
        | "unite" | "drop_na" | "fill" | "replace_na" | "extract" | "gather" | "spread"
        | "complete" | "expand" | "crossing" | "nesting" | "chop" | "unchop" | "pack"
        | "unpack" | "hoist"
        // ggplot2
        | "aes"
    )
}

/// Whether `name` is a model-fitting function that builds a *model frame* from
/// its `data` argument. Such a call evaluates the arguments named by
/// [`is_model_frame_arg`] inside that frame, where a bare name is a column of
/// the data frame rather than an in-scope binding.
///
/// Name-only and package-agnostic, matching [`is_data_masking_callee`];
/// hand-curated (stats + MASS core). Over-matching only ever suppresses a
/// finding, the conservative direction.
pub fn is_model_frame_callee(name: &str) -> bool {
    model_frame_formals(name).is_some()
}

/// The formals of each [`is_model_frame_callee`] function, in declaration
/// order with `"..."` where it appears, for simulating R's argument matching
/// via [`match_args_to_formals`]: `data` may be supplied positionally (`lm`'s
/// second formal, `glm`'s third) or by unique prefix (`dat = d`), and the
/// model-frame arguments themselves partial-match too (`weight = w`).
/// Generics (`model.frame`, `rlm`, `lda`, …) use the formals of the method a
/// formula call dispatches to.
pub fn model_frame_formals(name: &str) -> Option<&'static [&'static str]> {
    Some(match name {
        // stats
        "lm" => &[
            "formula",
            "data",
            "subset",
            "weights",
            "na.action",
            "method",
            "model",
            "x",
            "y",
            "qr",
            "singular.ok",
            "contrasts",
            "offset",
            "...",
        ],
        "glm" => &[
            "formula",
            "family",
            "data",
            "weights",
            "subset",
            "na.action",
            "start",
            "etastart",
            "mustart",
            "offset",
            "control",
            "model",
            "method",
            "x",
            "y",
            "singular.ok",
            "contrasts",
            "...",
        ],
        // `manova(...)` forwards everything to `aov`, so it shares aov's table.
        "aov" | "manova" => &["formula", "data", "projections", "qr", "contrasts", "..."],
        "loess" => &[
            "formula",
            "data",
            "weights",
            "subset",
            "na.action",
            "model",
            "span",
            "enp.target",
            "degree",
            "parametric",
            "drop.square",
            "normalize",
            "family",
            "method",
            "control",
            "...",
        ],
        "nls" => &[
            "formula",
            "data",
            "start",
            "control",
            "algorithm",
            "trace",
            "subset",
            "weights",
            "na.action",
            "model",
            "lower",
            "upper",
            "...",
        ],
        "xtabs" => &[
            "formula",
            "data",
            "subset",
            "sparse",
            "na.action",
            "addNA",
            "exclude",
            "drop.unused.levels",
        ],
        "model.frame" => &[
            "formula",
            "data",
            "subset",
            "na.action",
            "drop.unused.levels",
            "xlev",
            "...",
        ],
        "model.matrix" => &["object", "data", "contrasts.arg", "xlev", "..."],
        // MASS / nnet
        "polr" => &[
            "formula",
            "data",
            "weights",
            "start",
            "...",
            "subset",
            "na.action",
            "contrasts",
            "Hess",
            "model",
            "method",
        ],
        "rlm" => &[
            "formula",
            "data",
            "weights",
            "...",
            "subset",
            "na.action",
            "method",
            "wt.method",
            "model",
            "x.ret",
            "y.ret",
            "contrasts",
        ],
        "lda" | "qda" => &["formula", "data", "...", "subset", "na.action"],
        "glm.nb" => &[
            "formula",
            "data",
            "weights",
            "subset",
            "na.action",
            "start",
            "etastart",
            "mustart",
            "control",
            "method",
            "model",
            "x",
            "y",
            "contrasts",
            "...",
            "init.theta",
            "link",
        ],
        "multinom" => &[
            "formula",
            "data",
            "weights",
            "subset",
            "na.action",
            "contrasts",
            "Hess",
            "summ",
            "censored",
            "model",
            "...",
        ],
        _ => return None,
    })
}

/// Simulate R's argument matching. `names` holds each supplied argument's name
/// in call order (`None` for a positional argument); `formals` is the callee's
/// table from [`model_frame_formals`]. Returns, per argument, the formal it
/// binds (`None` when it lands in `...` or matches nothing). Matching follows
/// R's three passes: exact names first (the only way to reach formals declared
/// after `...`), then unique-prefix partial matches against the formals before
/// `...`, then positional fill of what remains before `...`.
pub fn match_args_to_formals(
    names: &[Option<SmolStr>],
    formals: &'static [&'static str],
) -> Vec<Option<&'static str>> {
    let dots = formals
        .iter()
        .position(|f| *f == "...")
        .unwrap_or(formals.len());
    let mut consumed = vec![false; formals.len()];
    let mut matched: Vec<Option<&'static str>> = vec![None; names.len()];
    for (arg, slot) in names.iter().zip(matched.iter_mut()) {
        let Some(name) = arg else { continue };
        if let Some(j) =
            (0..formals.len()).find(|&j| !consumed[j] && j != dots && formals[j] == name.as_str())
        {
            consumed[j] = true;
            *slot = Some(formals[j]);
        }
    }
    for (arg, slot) in names.iter().zip(matched.iter_mut()) {
        let Some(name) = arg else { continue };
        if slot.is_some() {
            continue;
        }
        let mut candidates =
            (0..dots).filter(|&j| !consumed[j] && formals[j].starts_with(name.as_str()));
        if let (Some(j), None) = (candidates.next(), candidates.next()) {
            consumed[j] = true;
            *slot = Some(formals[j]);
        }
    }
    let mut next = 0;
    for (arg, slot) in names.iter().zip(matched.iter_mut()) {
        if arg.is_some() {
            continue;
        }
        while next < dots && consumed[next] {
            next += 1;
        }
        if next == dots {
            break;
        }
        consumed[next] = true;
        *slot = Some(formals[next]);
    }
    matched
}

/// Whether the argument bound to formal `name` of a model-fitting call is
/// evaluated in the model frame. `data` itself is *not* one of these: it names
/// the data frame and must resolve to a real binding.
pub fn is_model_frame_arg(name: &str) -> bool {
    matches!(name, "subset" | "weights" | "offset")
}

/// Whether `name` is a (prefix of a) model-frame argument name — the masking
/// test for a named argument that fell into `...`. Dots-forwarded arguments
/// are re-matched at the inner fitting call, partial matching included, so
/// `aov(y ~ x, data = d, weights = w)` forwards `weights` to `lm`'s model
/// frame even though `aov` has no such formal itself.
pub fn is_model_frame_arg_prefix(name: &str) -> bool {
    !name.is_empty()
        && ["subset", "weights", "offset"]
            .iter()
            .any(|f| f.starts_with(name))
}

/// Where a bare function/identifier name resolves to within the attached
/// packages. Mirrors jarl's enum of the same name.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PackageOrigin {
    /// Exactly one attached package exports this name.
    Resolved(SmolStr),
    /// Multiple attached packages export this name. The vec is in load order
    /// (first attached first); the *last* element is the package that masks
    /// the others under R's standard lookup rules.
    Ambiguous(Vec<SmolStr>),
    /// No attached package is known to export this name.
    Unknown,
}

pub trait SymbolProvider: Send + Sync {
    /// Resolve a bare name against a load-ordered list of attached packages.
    ///
    /// The provider should consider both R's seven default packages (always
    /// attached) and any packages listed in `loaded`, treating the default
    /// packages as attached *before* anything in `loaded`.
    fn origin(&self, name: &str, loaded: &[LoadedPackage]) -> PackageOrigin;

    /// True when `name` is exported by one of R's default packages.
    fn is_base(&self, name: &str) -> bool;

    /// True if this provider has *full* export knowledge for `pkg` — i.e. an
    /// unresolved name attributed to `pkg` is genuinely undefined, not merely
    /// un-indexed. Default packages always qualify; installed packages qualify
    /// once harvested into the index. Default: `false`.
    fn package_indexed(&self, pkg: &str) -> bool {
        let _ = pkg;
        false
    }

    /// Packages `pkg` attaches beyond itself when `library()`d — a
    /// meta-package's core set. Empty for ordinary packages. Default: the
    /// static curated table ([`meta_package_members`]); providers with a
    /// harvested index override this to prefer the version-exact attach set
    /// captured at harvest time.
    fn attached_packages(&self, pkg: &str) -> Vec<SmolStr> {
        meta_package_members(pkg).iter().map(SmolStr::new).collect()
    }
}

/// Static symbol provider backed by the baked-in default-package export lists.
#[derive(Debug)]
pub struct StaticBaseR {
    /// Maps a symbol → the list of default packages that export it. Most
    /// symbols are exported by exactly one package; a handful (e.g. `body`
    /// from base and methods) are exported by more.
    name_to_packages: HashMap<SmolStr, Vec<SmolStr>>,
    /// Set of all names exported by any default package, for fast `is_base`.
    base_names: HashSet<SmolStr>,
}

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

impl StaticBaseR {
    pub fn new() -> Self {
        let mut name_to_packages: HashMap<SmolStr, Vec<SmolStr>> = HashMap::new();
        let mut base_names = HashSet::new();
        for &(pkg, list) in PACKAGE_LISTS {
            let pkg_str = SmolStr::new(pkg);
            for name in list.lines() {
                let name = name.trim();
                if name.is_empty() {
                    continue;
                }
                let name_str = SmolStr::new(name);
                name_to_packages
                    .entry(name_str.clone())
                    .or_default()
                    .push(pkg_str.clone());
                base_names.insert(name_str);
            }
        }
        Self {
            name_to_packages,
            base_names,
        }
    }
}

impl StaticBaseR {
    /// Iterate every name exported by a default package (for completion).
    pub fn base_names(&self) -> impl Iterator<Item = &SmolStr> {
        self.base_names.iter()
    }

    /// The default package that exports `name` (the first listed, when several
    /// default packages export it), if any.
    pub fn package_of(&self, name: &str) -> Option<&SmolStr> {
        self.name_to_packages
            .get(name)
            .and_then(|pkgs| pkgs.first())
    }
}

impl SymbolProvider for StaticBaseR {
    fn origin(&self, name: &str, loaded: &[LoadedPackage]) -> PackageOrigin {
        let mut candidates: Vec<SmolStr> = Vec::new();
        if let Some(pkgs) = self.name_to_packages.get(name) {
            candidates.extend(pkgs.iter().cloned());
        }
        // Non-default `library()` calls add nothing this pass — no manifest yet.
        let _ = loaded;
        match candidates.len() {
            0 => PackageOrigin::Unknown,
            1 => PackageOrigin::Resolved(candidates.into_iter().next().unwrap()),
            _ => PackageOrigin::Ambiguous(candidates),
        }
    }

    fn is_base(&self, name: &str) -> bool {
        self.base_names.contains(name)
    }

    fn package_indexed(&self, pkg: &str) -> bool {
        // The seven default packages are fully known via the baked-in lists.
        DEFAULT_PACKAGES.contains(&pkg)
    }
}

pub fn default_packages() -> &'static [&'static str] {
    DEFAULT_PACKAGES
}

/// Names-only export lists for the top-N CRAN packages by download count,
/// baked in from `cran/exports.txt` and parsed once.
///
/// This is the lowest-precision tier in the resolution stack: locally harvested
/// packages (version-exact) and the default base packages both take precedence.
/// It exists so `undefined-symbol` can resolve `library()`-attached packages
/// that aren't installed, without the conservative whole-file suppression.
#[derive(Debug)]
pub struct BundledPackages {
    /// package → set of exported names.
    exports: &'static HashMap<SmolStr, HashSet<SmolStr>>,
}

static BUNDLED_EXPORTS: LazyLock<HashMap<SmolStr, HashSet<SmolStr>>> =
    LazyLock::new(|| parse_bundled(include_str!("cran/exports.txt")));

/// Parse the sectioned `cran/exports.txt` format: a `[pkg]` line opens a
/// section, subsequent non-empty, non-`#` lines are that package's exports.
fn parse_bundled(text: &str) -> HashMap<SmolStr, HashSet<SmolStr>> {
    let mut map: HashMap<SmolStr, HashSet<SmolStr>> = HashMap::new();
    let mut current: Option<SmolStr> = None;
    for line in text.lines() {
        let line = line.trim();
        if line.is_empty() || line.starts_with('#') {
            continue;
        }
        if let Some(pkg) = line.strip_prefix('[').and_then(|s| s.strip_suffix(']')) {
            current = Some(SmolStr::new(pkg));
            map.entry(current.clone().unwrap()).or_default();
        } else if let Some(pkg) = &current {
            map.get_mut(pkg).unwrap().insert(SmolStr::new(line));
        }
    }
    map
}

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

impl BundledPackages {
    pub fn new() -> Self {
        Self {
            exports: &BUNDLED_EXPORTS,
        }
    }

    /// True if `package` is in the bundled set.
    pub fn has_package(&self, package: &str) -> bool {
        self.exports.contains_key(package)
    }

    /// True if the bundled list for `package` includes `name`.
    pub fn exports(&self, package: &str, name: &str) -> bool {
        self.exports
            .get(package)
            .is_some_and(|set| set.contains(name))
    }

    /// Iterate a bundled package's export names, if it is in the set (for
    /// completion's member fallback when the package isn't locally harvested).
    pub fn package_exports(&self, package: &str) -> Option<impl Iterator<Item = &SmolStr>> {
        self.exports.get(package).map(|set| set.iter())
    }
}

const PACKAGE_LISTS: &[(&str, &str)] = &[
    (PACKAGE_BASE, include_str!("base_r/base.txt")),
    (PACKAGE_UTILS, include_str!("base_r/utils.txt")),
    (PACKAGE_STATS, include_str!("base_r/stats.txt")),
    (PACKAGE_METHODS, include_str!("base_r/methods.txt")),
    (PACKAGE_DATASETS, include_str!("base_r/datasets.txt")),
    (PACKAGE_GRDEVICES, include_str!("base_r/grDevices.txt")),
    (PACKAGE_GRAPHICS, include_str!("base_r/graphics.txt")),
];

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

    #[test]
    fn knows_common_base_names() {
        let p = StaticBaseR::new();
        assert!(p.is_base("c"));
        assert!(p.is_base("length"));
        assert!(p.is_base("print"));
    }

    #[test]
    fn resolves_base_function() {
        let p = StaticBaseR::new();
        match p.origin("length", &[]) {
            PackageOrigin::Resolved(pkg) => assert_eq!(pkg.as_str(), "base"),
            other => panic!("expected Resolved(base), got {other:?}"),
        }
    }

    #[test]
    fn returns_unknown_for_unknown_name() {
        let p = StaticBaseR::new();
        assert_eq!(
            p.origin("not_a_real_symbol_xyz", &[]),
            PackageOrigin::Unknown
        );
    }

    #[test]
    fn knows_stats_function() {
        let p = StaticBaseR::new();
        assert!(p.is_base("lm"));
    }

    #[test]
    fn knows_datasets_lazydata() {
        let p = StaticBaseR::new();
        // `iris` lives in datasets via lazy-loaded data.
        assert!(p.is_base("iris"));
    }

    #[test]
    fn bundled_knows_curated_package() {
        let b = BundledPackages::new();
        assert!(b.has_package("data.table"));
        assert!(b.exports("data.table", "fread"));
        assert!(!b.exports("data.table", "definitely_not_a_real_export"));
    }

    #[test]
    fn base_names_enumerable_and_mapped() {
        let p = StaticBaseR::new();
        let names: HashSet<&SmolStr> = p.base_names().collect();
        assert!(names.iter().any(|n| n.as_str() == "mean"));
        assert_eq!(p.package_of("length").map(|s| s.as_str()), Some("base"));
        assert!(p.package_of("not_a_real_symbol_xyz").is_none());
    }

    #[test]
    fn bundled_package_exports_enumerable() {
        let b = BundledPackages::new();
        let names: Vec<String> = b
            .package_exports("data.table")
            .expect("data.table bundled")
            .map(|s| s.to_string())
            .collect();
        assert!(names.iter().any(|n| n == "fread"));
        assert!(b.package_exports("not_a_real_package_xyz").is_none());
    }

    #[test]
    fn bundled_unknown_package_is_absent() {
        let b = BundledPackages::new();
        assert!(!b.has_package("not_a_real_package_xyz"));
        assert!(!b.exports("not_a_real_package_xyz", "anything"));
    }

    #[test]
    fn bundled_names_are_not_base() {
        // A bundled-only export must not be reported as base R.
        let base = StaticBaseR::new();
        let bundled = BundledPackages::new();
        assert!(bundled.exports("rlang", "abort"));
        assert!(!base.is_base("abort"));
    }
}