arity 0.24.0

//! Harvest a single installed package into a [`PackageIndex`] by reading its
//! on-disk metadata — no R runtime.
//!
//! What is read:
//! - `DESCRIPTION` → version (and the building R version, when present).
//! - `NAMESPACE` → exported names (explicit `export()` plus `exportPattern()`
//!   expanded against the lazy-load object names).
//! - `data/Rdata.rdx` → lazy-data (`LazyData`) object names — what R exposes
//!   via `.getNamespaceInfo(ns, "lazydata")`, classified `Data`. (`datasets`
//!   is entirely lazy-data.)
//! - `R/{pkg}.rdb` → function formals and symbol-kind refinement.
//! - `Meta/Rd.rds` → per-symbol help titles + the help-page key for each alias.
//! - `help/{pkg}.rdb` → full Rd bodies (description/usage/arguments), rendered
//!   to markdown via [`rd`](crate::rindex::rd).

use std::collections::BTreeSet;
use std::path::{Path, PathBuf};

use rd_helpdb::{HelpTopicIndex, HelpTopicText, PackageHelpDb};
use smol_str::SmolStr;

use crate::namespace::{
    Argument as NamespaceArgument, Directive as NamespaceDirective, DirectiveKind,
};
use crate::rindex::deparse;
use crate::rindex::lazyload::{self, LazyLoadDb};
use crate::rindex::libpaths::LibrarySearch;
use crate::rindex::rd;
use crate::rindex::rds::{Rkind, Robj};
use crate::rindex::schema::{
    Formal, HelpDoc, PackageIndex, SCHEMA_VERSION, SymbolEntry, SymbolKind,
};

#[derive(Debug)]
pub enum HarvestError {
    NotAPackage(PathBuf),
    Io(String),
    BadDescription(String),
}

impl std::fmt::Display for HarvestError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            HarvestError::NotAPackage(p) => {
                write!(f, "{} is not an installed R package", p.display())
            }
            HarvestError::Io(s) => write!(f, "harvest I/O error: {s}"),
            HarvestError::BadDescription(s) => write!(f, "malformed DESCRIPTION: {s}"),
        }
    }
}

impl std::error::Error for HarvestError {}

type Result<T> = std::result::Result<T, HarvestError>;

#[derive(Debug, Clone, Copy)]
pub struct HarvestOptions {
    /// Harvest help metadata and bodies. When false, no help files are read.
    pub help: bool,
}

impl Default for HarvestOptions {
    fn default() -> Self {
        HarvestOptions { help: true }
    }
}

/// Harvest the package installed at `pkg_dir` (the directory named after the
/// package inside a library). `harvested_at` is supplied by the caller so this
/// stays a pure function of its inputs (callers stamp the wall clock).
///
/// Attach-set capture is disabled here: it needs a [`LibrarySearch`] to
/// validate members as installed, so this wrapper always records an empty
/// `attaches`. Use [`harvest_package_in`] when a search path is available.
pub fn harvest_package(
    pkg_dir: &Path,
    opts: HarvestOptions,
    harvested_at: u64,
) -> Result<PackageIndex> {
    harvest_package_in(
        pkg_dir,
        opts,
        harvested_at,
        &LibrarySearch::from_dirs(Vec::new()),
    )
}

/// [`harvest_package`], plus attach-set capture against `search`: when the
/// package looks like a meta-package (it has an `.onAttach` hook and a
/// well-known attach-set variable such as tidyverse's `core`), the validated
/// member list is recorded in [`PackageIndex::attaches`].
pub fn harvest_package_in(
    pkg_dir: &Path,
    opts: HarvestOptions,
    harvested_at: u64,
    search: &LibrarySearch,
) -> Result<PackageIndex> {
    let desc_path = pkg_dir.join("DESCRIPTION");
    if !desc_path.is_file() {
        return Err(HarvestError::NotAPackage(pkg_dir.to_path_buf()));
    }
    let desc = read_dcf(&desc_path)?;
    let package = desc
        .field("Package")
        .ok_or_else(|| HarvestError::BadDescription("no Package field".into()))?;
    let version = desc
        .field("Version")
        .ok_or_else(|| HarvestError::BadDescription("no Version field".into()))?;
    let r_version = desc
        .field("Built")
        .as_deref()
        .and_then(parse_built_r_version);
    // `folded_value` joins continuation lines with newlines; a `Title` is one
    // logical line, so flatten it back for display.
    let title = desc.field("Title").map(|t| SmolStr::new(flatten_ws(&t)));

    let object_names = read_object_names(pkg_dir, &package);
    let exports = resolve_package_exports(pkg_dir, &object_names);
    let lazydata = read_lazydata_names(pkg_dir);

    let help = HelpFiles::when_enabled(opts.help, || HelpFiles::open(pkg_dir, &package));

    // Missing code records leave explicit exports and metadata usable.
    let db = LazyLoadDb::open(&pkg_dir.join("R").join(format!("{package}.rdx")))
        .inspect_err(|error| {
            log::debug!("{}: code database unavailable: {error}", pkg_dir.display())
        })
        .ok();

    let export_set: BTreeSet<&str> = exports.iter().map(String::as_str).collect();
    let mut symbols: Vec<SymbolEntry> = exports
        .iter()
        .map(|name| {
            let help = build_help(&help, name);
            let (kind, formals) = refine_symbol(db.as_ref(), name);
            SymbolEntry {
                name: SmolStr::new(name),
                kind,
                exported: true,
                formals,
                help,
            }
        })
        .collect();

    // Lazy-data objects are available as `pkg::name` (and after attach) even
    // though NAMESPACE exports nothing, so treat them as exported. They are
    // `Data` by definition — no need to decode the (potentially large)
    // `data/Rdata.rdb` to re-derive a kind we already know. A name that is both
    // a code export and a dataset keeps its richer export classification.
    for name in &lazydata {
        if export_set.contains(name.as_str()) {
            continue;
        }
        let help = build_help(&help, name);
        symbols.push(SymbolEntry {
            name: SmolStr::new(name),
            kind: SymbolKind::Data,
            exported: true,
            formals: None,
            help,
        });
    }
    symbols.sort_by(|a, b| a.name.cmp(&b.name));

    Ok(PackageIndex {
        schema_version: SCHEMA_VERSION,
        package: SmolStr::new(&package),
        version: SmolStr::new(&version),
        lib_path: pkg_dir
            .parent()
            .map(|p| p.to_string_lossy().into_owned())
            .unwrap_or_default(),
        title,
        r_version,
        harvested_at,
        attaches: detect_attaches(db.as_ref(), &package, search),
        symbols,
    })
}

/// Well-known namespace variables that hold a meta-package's attach set — the
/// convention tidyverse established (`core`) and tidymodels follows. Grown as
/// evidence for other conventions appears.
const ATTACH_SET_VARS: &[&str] = &["core"];

/// Capture what `package` attaches at `library()` time, without running R.
///
/// `.onAttach` bodies are byte-compiled, so the hook itself cannot be read;
/// instead the well-known attach-set variables ([`ATTACH_SET_VARS`]) are
/// fetched from the namespace lazy-load DB and validated. Empty means "found
/// nothing"; resolution then falls back to the static curated table.
fn detect_attaches(db: Option<&LazyLoadDb>, package: &str, search: &LibrarySearch) -> Vec<SmolStr> {
    let Some(db) = db else {
        return Vec::new();
    };
    // A package without an `.onAttach` hook cannot attach anything, whatever
    // its internal variables happen to be named.
    if !db.contains(".onAttach") {
        return Vec::new();
    }
    let installed = |member: &str| search.find_package(member).is_some();
    for var in ATTACH_SET_VARS {
        if let Ok(obj) = db.fetch_shared(var)
            && let Some(members) = validate_attach_set(&obj, package, &installed)
        {
            return members;
        }
    }
    Vec::new()
}

/// Validate a candidate attach-set object, all-or-nothing: `Some` only when
/// `obj` is a plain character vector of syntactically valid, *installed*
/// package names (self and duplicates dropped). Any NA rejects the whole set
/// (see [`validate_attach_names`] for the rest of the rules).
fn validate_attach_set(
    obj: &rd_rds::RObject,
    package: &str,
    installed: &dyn Fn(&str) -> bool,
) -> Option<Vec<SmolStr>> {
    let rd_rds::RValue::Character(strings) = obj.value() else {
        return None;
    };
    let names = strings
        .iter()
        .map(|s| s.as_str()?.ok())
        .collect::<Option<Vec<_>>>()?;
    let borrowed: Vec<_> = names.iter().map(|s| s.as_ref()).collect();
    validate_attach_names(&borrowed, package, installed)
}

/// Validate candidate attach-set member `names`, all-or-nothing: `Some` only
/// when every name is a syntactically valid, *installed* package name (self
/// and duplicates dropped). One malformed or uninstalled member rejects the
/// whole set — a partial set would override the static fallback table while
/// being wrong, and an unverifiable member would permanently trip the
/// conservative undefined-symbol gates. Shared with the opt-in
/// [`attach_probe`](crate::rindex::attach_probe).
pub(crate) fn validate_attach_names(
    names: &[&str],
    package: &str,
    installed: &dyn Fn(&str) -> bool,
) -> Option<Vec<SmolStr>> {
    let mut members: Vec<SmolStr> = Vec::new();
    for &name in names {
        if name == package {
            continue;
        }
        if !is_valid_package_name(name) {
            return None;
        }
        if !members.iter().any(|m| m == name) {
            members.push(SmolStr::new(name));
        }
    }
    if members.is_empty() || !members.iter().all(|m| installed(m)) {
        return None;
    }
    Some(members)
}

/// R's package-name rules: at least two characters of ASCII letters, digits,
/// and dots, starting with a letter and not ending with a dot.
pub(crate) fn is_valid_package_name(name: &str) -> bool {
    name.len() >= 2
        && name.chars().next().is_some_and(|c| c.is_ascii_alphabetic())
        && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '.')
        && !name.ends_with('.')
}

/// The exported names of the package at `pkg_dir`. A package with a `NAMESPACE`
/// file exports exactly what it declares (explicit exports plus `exportPattern`
/// matches). A package *without* a `NAMESPACE` — most notably `base`, whose
/// namespace is the implicit base environment — exports its whole object set,
/// matching R's pre-namespace "export everything" rule. Over-exporting is
/// harmless: name resolution still gates which names reach a `base` lookup.
fn resolve_package_exports(pkg_dir: &Path, object_names: &[String]) -> Vec<String> {
    let ns_path = pkg_dir.join("NAMESPACE");
    if ns_path.is_file() {
        let namespace = std::fs::read_to_string(&ns_path).unwrap_or_default();
        let borrowed: Vec<&str> = object_names.iter().map(String::as_str).collect();
        resolve_exports(&namespace, &borrowed)
    } else {
        object_names.to_vec()
    }
}

/// Read the lazy-load object names from `R/{pkg}.rdx`, if present.
fn read_object_names(pkg_dir: &Path, package: &str) -> Vec<String> {
    let rdx = pkg_dir.join("R").join(format!("{package}.rdx"));
    lazyload::read_index_names(&rdx)
        .inspect_err(|error| {
            log::debug!("{}: names unavailable: {error}", rdx.display());
        })
        .unwrap_or_default()
}

/// Read lazy-data (`LazyData`) object names from `data/Rdata.rdx`, if present.
/// These are the names R exposes via `.getNamespaceInfo(ns, "lazydata")`;
/// `datasets` is entirely lazy-data. The `.rdx` index alone is read (cheap — no
/// `.rdb` decode). The file uses the fixed `Rdata` stem, not `{pkg}`.
fn read_lazydata_names(pkg_dir: &Path) -> Vec<String> {
    let rdx = pkg_dir.join("data").join("Rdata.rdx");
    lazyload::read_index_names(&rdx)
        .inspect_err(|error| {
            log::debug!("{}: names unavailable: {error}", rdx.display());
        })
        .unwrap_or_default()
}

/// Classify an exported object and, for closures, read its formals. Falls back
/// to the cheap-tier default (`Function`, no formals) when there is no DB to
/// fetch from, or the object isn't in it, or it decodes to a type we don't
/// model — a single object that won't decode never aborts the package.
fn refine_symbol(db: Option<&LazyLoadDb>, name: &str) -> (SymbolKind, Option<Vec<Formal>>) {
    let Some(db) = db else {
        return (SymbolKind::Function, None);
    };
    let obj = match db.fetch(name) {
        Ok(obj) => obj,
        Err(error) => {
            log::debug!("code binding {name:?} unavailable: {error}");
            return (SymbolKind::Function, None);
        }
    };
    match &obj.kind {
        Rkind::Closure { formals, .. } => (SymbolKind::Function, Some(extract_formals(formals))),
        // A primitive aliased into the package (e.g. `add <- `+``): callable,
        // but no R-level formals.
        Rkind::Builtin => (SymbolKind::Function, None),
        Rkind::Logical(_) | Rkind::Int(_) | Rkind::Real(_) | Rkind::Str(_) | Rkind::List(_) => {
            (SymbolKind::Data, None)
        }
        // Environments, S4 objects, external pointers, symbols, …
        _ => (SymbolKind::Other, None),
    }
}

/// Map a closure's formals pairlist (tag = parameter name, value = default
/// expression or the empty-arg sentinel) to [`Formal`]s. A zero-parameter
/// function yields an empty list (distinct from `None` = "not read").
fn extract_formals(formals: &Robj) -> Vec<Formal> {
    match &formals.kind {
        Rkind::Pairlist(items) => items
            .iter()
            .map(|it| Formal {
                name: it.tag.clone().unwrap_or_default(),
                default: deparse::deparse(&it.value),
            })
            .collect(),
        _ => Vec::new(),
    }
}

// ---------------------------------------------------------------------------
// DESCRIPTION (DCF)
// ---------------------------------------------------------------------------

/// A parsed DESCRIPTION, reduced to the field lookup this module needs.
struct Dcf {
    document: crate::dcf::Document,
}

impl Dcf {
    /// The first field named `name`, folded to its logical value.
    fn field(&self, name: &str) -> Option<String> {
        self.document.field(name).map(|field| field.folded_value())
    }
}

fn read_dcf(path: &Path) -> Result<Dcf> {
    let text = std::fs::read_to_string(path).map_err(|e| HarvestError::Io(e.to_string()))?;
    // The parser's diagnostics are dropped on purpose. This DESCRIPTION comes
    // from whatever the user happens to have installed, and a malformed one is
    // input, not a bug report: it must degrade to "no symbols for this package"
    // rather than fail the harvest.
    Ok(Dcf {
        document: crate::dcf::parse(&text).document(),
    })
}

/// Collapse every run of whitespace (including the newlines `folded_value`
/// leaves between continuation lines) to a single space.
fn flatten_ws(s: &str) -> String {
    s.split_whitespace().collect::<Vec<_>>().join(" ")
}

/// `Built:` looks like `R 4.5.3; ; 2025-...; unix` — pull the R version.
fn parse_built_r_version(built: &str) -> Option<SmolStr> {
    let first = built.split(';').next()?.trim();
    let ver = first.strip_prefix("R ").unwrap_or(first).trim();
    if ver.is_empty() {
        None
    } else {
        Some(SmolStr::new(ver))
    }
}

// ---------------------------------------------------------------------------
// NAMESPACE
// ---------------------------------------------------------------------------

/// Everything a NAMESPACE file declares that name resolution cares about.
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct NamespaceInfo {
    /// Names made public via `export()` / `exportMethods()` / `exportClasses()`,
    /// plus `exportPattern()` matches against the package's object names.
    pub exports: BTreeSet<String>,
    /// Names imported individually via `importFrom(pkg, name, ...)`.
    pub imported_names: BTreeSet<String>,
    /// Packages imported wholesale via `import(pkg)`. Every export of such a
    /// package is in scope, so without that package's index any unresolved name
    /// could come from it.
    pub imported_packages: BTreeSet<String>,
    /// Packages named by `importFrom(pkg, ...)`. A *reference* to `pkg` just as
    /// `import(pkg)` is — and the fact stage 3's `unused-dependency` asks for —
    /// but kept apart because the names it brings in are already enumerated in
    /// [`imported_names`](Self::imported_names), so it never leaves resolution
    /// incomplete.
    pub imported_from_packages: BTreeSet<String>,
    /// The subset of [`exports`](Self::exports) registered via `S3method()`
    /// rather than `export()`. Still exports (they are in the namespace, so name
    /// resolution must see them), but reached by *dispatch*, never by a direct
    /// call — so "nothing calls this name" says nothing about a method being
    /// dead. Tracked apart so `unused-function` can exclude them.
    pub s3_methods: BTreeSet<String>,
    /// Names `useDynLib()` binds *by enumeration*: every positional argument
    /// after the DLL name, plus the alias of each `alias = routine` form. These
    /// are native symbol objects, not R bindings, so nothing in the package's R
    /// sources defines them.
    pub dynlib_routines: BTreeSet<String>,
    /// `Some(fixes)` when a `useDynLib()` declares `.registration = TRUE`. The
    /// routine names then live in the package's C sources rather than here, so
    /// this only carries the affixes R wraps each harvested name in — see
    /// [`crate::project::native`].
    pub dynlib_registration: Option<DynLibFixes>,
}

/// The `.fixes` of a `useDynLib(..., .registration = TRUE)`: the prefix and
/// suffix R puts around every registered routine name when it binds it. Both
/// empty when `.fixes` is absent.
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct DynLibFixes {
    pub prefix: String,
    pub suffix: String,
}

impl DynLibFixes {
    /// `routine` as R binds it in the package namespace.
    pub fn apply(&self, routine: &str) -> String {
        format!("{}{routine}{}", self.prefix, self.suffix)
    }
}

/// Parse a NAMESPACE file into the exports and imports it declares, expanding
/// `exportPattern` directives against `object_names` (the package's top-level
/// object names).
pub fn parse_namespace(namespace: &str, object_names: &[&str]) -> NamespaceInfo {
    let mut info = NamespaceInfo::default();
    let mut patterns: Vec<regex::Regex> = Vec::new();

    for directive in crate::namespace::parse(namespace).document().directives() {
        match directive.kind() {
            DirectiveKind::Export
            | DirectiveKind::ExportClass
            | DirectiveKind::ExportClasses
            | DirectiveKind::ExportMethods => {
                info.exports.extend(directive_values(&directive));
            }
            DirectiveKind::S3Method => {
                // `S3method(generic, class)` registers the method `generic.class`;
                // the three-arg form `S3method(generic, class, method)` binds the
                // explicitly named `method` instead.
                let args: Vec<String> = directive_values(&directive).collect();
                let method = match args.as_slice() {
                    [_, _, method] => Some(method.clone()),
                    [generic, class] => Some(format!("{generic}.{class}")),
                    _ => None,
                };
                if let Some(method) = method {
                    info.exports.insert(method.clone());
                    info.s3_methods.insert(method);
                }
            }
            DirectiveKind::ExportPattern | DirectiveKind::ExportClassPattern => {
                for arg in directive_values(&directive) {
                    if let Some(re) = compile_r_pattern(&arg) {
                        patterns.push(re);
                    }
                }
            }
            DirectiveKind::ImportFrom
            | DirectiveKind::ImportClassFrom
            | DirectiveKind::ImportClassesFrom
            | DirectiveKind::ImportMethodsFrom => {
                // `importFrom(pkg, a, b, ...)`: the first arg is the package, the
                // rest are the imported names. The S4 forms have the same shape
                // and reference `pkg` just as surely; their names go into the
                // same set, which can only ever *suppress* an
                // `undefined-symbol` — the conservative direction.
                let mut args = directive_values(&directive);
                if let Some(package) = args.next() {
                    info.imported_from_packages.insert(package);
                    info.imported_names.extend(args);
                }
            }
            DirectiveKind::Import => {
                // R drops `except` and treats every remaining argument as a
                // package, so only the *positional* arguments name packages. A
                // kept `except = c(a, b)` would enter the set as a package no
                // index can enumerate.
                info.imported_packages
                    .extend(directive_positional_values(&directive));
            }
            DirectiveKind::UseDynLib => parse_use_dyn_lib(&directive, &mut info),
            DirectiveKind::Unsupported => {}
        }
    }

    if !patterns.is_empty() {
        for name in object_names {
            if patterns.iter().any(|re| re.is_match(name)) {
                info.exports.insert((*name).to_string());
            }
        }
    }

    info
}

/// Fold one `useDynLib(name, ...)` directive into `info`.
///
/// The first *positional* argument is the DLL, not a routine. Every later one
/// names a routine bound under its own name, and `alias = routine` binds the
/// alias. `.registration` and `.fixes` are options, so they are the two keywords
/// that do not name a binding.
fn parse_use_dyn_lib(directive: &NamespaceDirective, info: &mut NamespaceInfo) {
    let mut fixes: Option<DynLibFixes> = None;
    let mut registration = false;
    let mut seen_dll = false;
    for arg in directive.arguments() {
        let Some(value) = namespace_argument_value(&arg) else {
            continue;
        };
        match arg.name().as_deref() {
            Some(".registration") => registration |= is_r_true(&value),
            Some(".fixes") => fixes = Some(parse_fixes(&value)),
            Some(alias) => {
                info.dynlib_routines.insert(alias.to_string());
            }
            None if !seen_dll => seen_dll = true,
            None => {
                info.dynlib_routines.insert(value);
            }
        }
    }
    if registration {
        info.dynlib_registration = Some(fixes.unwrap_or_default());
    }
}

/// Whether an R literal spells truth. `parse_args` has already unquoted, so
/// only the two bare spellings can appear.
fn is_r_true(value: &str) -> bool {
    matches!(value.trim(), "TRUE" | "T")
}

/// Parse a `.fixes` value: a length-1 or length-2 character vector giving the
/// prefix and suffix. `parse_args` leaves an unquoted `c(...)` call intact, so
/// the vector form is unwrapped here.
fn parse_fixes(value: &str) -> DynLibFixes {
    let trimmed = value.trim();
    let parts: Vec<String> = match trimmed
        .strip_prefix("c(")
        .and_then(|rest| rest.strip_suffix(')'))
    {
        Some(inner) => split_top_level_commas(inner)
            .into_iter()
            .map(|part| unquote(part).unwrap_or_default())
            .collect(),
        None => vec![trimmed.to_string()],
    };
    DynLibFixes {
        prefix: parts.first().cloned().unwrap_or_default(),
        suffix: parts.get(1).cloned().unwrap_or_default(),
    }
}

/// Resolve the set of exported names from a NAMESPACE file, expanding
/// `exportPattern` directives against the package's object names.
pub fn resolve_exports(namespace: &str, object_names: &[&str]) -> Vec<String> {
    parse_namespace(namespace, object_names)
        .exports
        .into_iter()
        .collect()
}

/// Translate an R regular expression (as found in `exportPattern`) into a Rust
/// `regex`. R uses POSIX ERE here; for the patterns that appear in NAMESPACE
/// files these are directly compatible. Returns `None` (caller skips the
/// pattern) if it fails to compile.
fn compile_r_pattern(pattern: &str) -> Option<regex::Regex> {
    regex::Regex::new(pattern).ok()
}

/// Every argument's interpreted value, named or not. Interpretation stays in
/// the root crate: the parser owns only the argument's syntax and range.
fn directive_values(directive: &NamespaceDirective) -> impl Iterator<Item = String> + '_ {
    directive
        .arguments()
        .filter_map(|argument| namespace_argument_value(&argument))
}

/// Only positional argument values. `import(pkg, except = ...)` names packages
/// positionally and options by keyword.
fn directive_positional_values(
    directive: &NamespaceDirective,
) -> impl Iterator<Item = String> + '_ {
    directive
        .arguments()
        .filter(|argument| argument.name().is_none())
        .filter_map(|argument| namespace_argument_value(&argument))
}

fn namespace_argument_value(argument: &NamespaceArgument) -> Option<String> {
    let value = argument.value()?;
    unquote(value.to_string().trim())
}

fn split_top_level_commas(inner: &str) -> Vec<&str> {
    let bytes = inner.as_bytes();
    let mut parts = Vec::new();
    let mut start = 0;
    let mut depth = 0i32;
    let mut in_str: Option<u8> = None;
    let mut i = 0;
    while i < bytes.len() {
        let c = bytes[i];
        if let Some(q) = in_str {
            if c == b'\\' {
                i += 2;
                continue;
            }
            if c == q {
                in_str = None;
            }
        } else {
            match c {
                b'"' | b'\'' | b'`' => in_str = Some(c),
                b'(' | b'[' | b'{' => depth += 1,
                b')' | b']' | b'}' => depth -= 1,
                b',' if depth == 0 => {
                    parts.push(&inner[start..i]);
                    start = i + 1;
                }
                _ => {}
            }
        }
        i += 1;
    }
    parts.push(&inner[start..]);
    parts
}

/// Unquote an R string literal, applying `\\` → `\` and `\"`/`\'` unescaping.
/// A bare (unquoted) identifier is returned as-is.
fn unquote(value: &str) -> Option<String> {
    let value = value.trim();
    let bytes = value.as_bytes();
    if bytes.len() >= 2
        && (bytes[0] == b'"' || bytes[0] == b'\'' || bytes[0] == b'`')
        && bytes[bytes.len() - 1] == bytes[0]
    {
        let inner = &value[1..value.len() - 1];
        let mut out = String::with_capacity(inner.len());
        let mut chars = inner.chars();
        while let Some(c) = chars.next() {
            if c == '\\' {
                match chars.next() {
                    Some('n') => out.push('\n'),
                    Some('t') => out.push('\t'),
                    Some(other) => out.push(other),
                    None => {}
                }
            } else {
                out.push(c);
            }
        }
        Some(out)
    } else if value.is_empty() {
        None
    } else {
        Some(value.to_string())
    }
}

// ---------------------------------------------------------------------------
// Help index (Meta/Rd.rds) — alias → (title, help-page key)
// ---------------------------------------------------------------------------

fn read_help_index(pkg_dir: &Path) -> Option<HelpTopicIndex> {
    match HelpTopicIndex::read_installed(pkg_dir) {
        Ok(index) => {
            if let Some(index) = &index {
                for (row, entry) in index.entries().enumerate() {
                    for (field, value) in [("title", &entry.title), ("file", &entry.file)] {
                        if let HelpTopicText::Invalid(reason) = value {
                            log::debug!(
                                "{}: help metadata row {row} {field}: {reason}",
                                pkg_dir.display()
                            );
                        }
                    }
                }
            }
            index
        }
        Err(error) => {
            log::debug!("{}: help metadata unavailable: {error}", pkg_dir.display());
            None
        }
    }
}

/// Assemble a symbol's [`HelpDoc`]: the title from `Meta/Rd.rds`, the body
/// (description/usage/arguments) from the help lazy-load DB page, if any. A page
/// that fails to decode degrades to title-only; a symbol no Rd documents yields
/// `None`.
fn build_help(help: &HelpFiles, name: &str) -> Option<HelpDoc> {
    let entry = help.index.as_ref()?.find_alias(name)?;
    let sections = entry
        .topic_key()
        .zip(help.database.as_ref())
        .and_then(|(key, database)| match database.document(key) {
            Ok(document) => {
                let rendered = rd::render_document(&document);
                for issue in rendered.issues {
                    log::debug!(
                        "{}: topic {key:?}, omitted {} at {:?}",
                        help.package_dir.display(),
                        issue.field,
                        issue.path
                    );
                }
                Some(rendered.sections)
            }
            Err(error) => {
                log::debug!(
                    "{}: topic {key:?} unavailable: {error}",
                    help.package_dir.display()
                );
                None
            }
        })
        .unwrap_or_default();
    let doc = rd::into_help_doc(entry.title.as_str().map(str::to_owned), sections);
    (doc != HelpDoc::default()).then_some(doc)
}

#[derive(Default)]
struct HelpFiles {
    index: Option<HelpTopicIndex>,
    database: Option<HelpDatabase>,
    package_dir: PathBuf,
}

impl HelpFiles {
    fn when_enabled(enabled: bool, load: impl FnOnce() -> Self) -> Self {
        if enabled { load() } else { Self::default() }
    }

    fn open(package_dir: &Path, package: &str) -> Self {
        let index = read_help_index(package_dir);
        let database = HelpDatabase::open(package_dir, package)
            .map_err(|error| {
                log::debug!(
                    "{}: compiled help unavailable: {error}",
                    package_dir.display()
                );
            })
            .ok();
        Self {
            index,
            database,
            package_dir: package_dir.to_owned(),
        }
    }
}

enum HelpDatabase {
    Package(PackageHelpDb),
    // The public harvester also accepts renamed directories. The package view
    // assumes basename == Package, so those paths need explicit shared access.
    Explicit(rd_rds::lazyload::LazyLoadDb),
}

impl HelpDatabase {
    fn open(package_dir: &Path, package: &str) -> std::result::Result<Self, String> {
        if package_dir.file_name().and_then(|s| s.to_str()) == Some(package) {
            PackageHelpDb::open(package_dir)
                .map(Self::Package)
                .map_err(|e| e.to_string())
        } else {
            let help = package_dir.join("help");
            rd_rds::lazyload::LazyLoadDb::open(
                help.join(format!("{package}.rdx")),
                help.join(format!("{package}.rdb")),
            )
            .map(Self::Explicit)
            .map_err(|e| e.to_string())
        }
    }

    fn document(&self, key: &str) -> std::result::Result<rd_ast::RdDocument, String> {
        let object = match self {
            Self::Package(db) => db.raw_topic(key).map_err(|e| e.to_string())?,
            Self::Explicit(db) => {
                let record = db.read(key).map_err(|e| e.to_string())?;
                rd_rds::parse(record.decompressed_bytes()).map_err(|e| e.to_string())?
            }
        };
        rd_ast::lower_r_object(&object).map_err(|e| e.to_string())
    }
}

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

    #[test]
    fn disabled_help_does_not_open_metadata_or_records() {
        let help = HelpFiles::when_enabled(false, || panic!("help files must not be read"));
        assert!(help.index.is_none());
        assert!(help.database.is_none());
    }

    fn str_vec(names: &[Option<&str>]) -> rd_rds::RObject {
        let values = names
            .iter()
            .map(|name| match name {
                Some(name) => rd_rds::RStr::new(
                    name.as_bytes(),
                    rd_rds::REncoding::Utf8,
                    rd_rds::NativeEncodingSource::Unknown,
                ),
                None => rd_rds::RStr::Na,
            })
            .collect();
        rd_rds::RObject::from_parts(
            rd_rds::RValue::Character(values),
            rd_rds::Attributes::default(),
        )
    }

    #[test]
    fn attach_set_accepts_installed_package_names() {
        let obj = str_vec(&[Some("dplyr"), Some("ggplot2")]);
        let members = validate_attach_set(&obj, "tidyverse", &|_| true).unwrap();
        assert_eq!(members, [SmolStr::new("dplyr"), SmolStr::new("ggplot2")]);
    }

    #[test]
    fn attach_set_rejects_non_character_objects() {
        let obj = rd_rds::RObject::from_parts(rd_rds::RValue::Null, rd_rds::Attributes::default());
        assert!(validate_attach_set(&obj, "tidyverse", &|_| true).is_none());
    }

    #[test]
    fn attach_set_rejects_na_and_invalid_names() {
        // An NA element poisons the whole set.
        let obj = str_vec(&[Some("dplyr"), None]);
        assert!(validate_attach_set(&obj, "tidyverse", &|_| true).is_none());
        // Not a syntactically valid package name (a path, a sentence, …).
        for bad in ["with space", "path/pkg", "x", "1pkg", "pkg.", ""] {
            let obj = str_vec(&[Some(bad)]);
            assert!(
                validate_attach_set(&obj, "tidyverse", &|_| true).is_none(),
                "{bad:?} should be rejected"
            );
        }
    }

    #[test]
    fn attach_set_rejects_any_uninstalled_member() {
        // All-or-nothing: one unverifiable member kills the whole set — a
        // partial set would beat the static fallback while being wrong.
        let obj = str_vec(&[Some("dplyr"), Some("notinstalled")]);
        let installed = |m: &str| m == "dplyr";
        assert!(validate_attach_set(&obj, "tidyverse", &installed).is_none());
    }

    #[test]
    fn attach_set_strips_self_and_duplicates() {
        let obj = str_vec(&[Some("tidyverse"), Some("dplyr"), Some("dplyr")]);
        let members = validate_attach_set(&obj, "tidyverse", &|_| true).unwrap();
        assert_eq!(members, [SmolStr::new("dplyr")]);
    }

    #[test]
    fn attach_set_rejects_empty_and_self_only_sets() {
        let obj = str_vec(&[]);
        assert!(validate_attach_set(&obj, "tidyverse", &|_| true).is_none());
        let obj = str_vec(&[Some("tidyverse")]);
        assert!(validate_attach_set(&obj, "tidyverse", &|_| true).is_none());
    }

    /// Harvest reads its metadata through folded field values, so it keeps
    /// pinning the folding itself. The tree-level guarantees live in
    /// `arity_parser::dcf`.
    #[test]
    fn dcf_folds_continuation_lines() {
        let text = "Package: testpkg\nCollate:\n    a.R\n    b.R\nVersion: 1.0\n";
        let desc = Dcf {
            document: crate::dcf::parse(text).document(),
        };
        assert_eq!(desc.field("Package").as_deref(), Some("testpkg"));
        assert_eq!(desc.field("Collate").as_deref(), Some("a.R\nb.R"));
        assert_eq!(desc.field("Version").as_deref(), Some("1.0"));
    }

    #[test]
    fn resolves_explicit_exports() {
        let ns = r#"
            export(foo)
            export("bar")
            S3method(print, baz)
            exportMethods(show)
        "#;
        let exports = resolve_exports(ns, &[]);
        assert!(exports.contains(&"foo".to_string()));
        assert!(exports.contains(&"bar".to_string()));
        assert!(exports.contains(&"show".to_string()));
        // `S3method(generic, class)` registers the method `generic.class`, not
        // the generic or class names on their own.
        assert!(exports.contains(&"print.baz".to_string()));
        assert!(!exports.contains(&"print".to_string()));
        assert!(!exports.contains(&"baz".to_string()));
    }

    #[test]
    fn s3method_registers_dotted_method_name() {
        let ns = r#"
            S3method(coef, SLOPE)
            S3method(predict, "GaussianSLOPE")
        "#;
        let exports = resolve_exports(ns, &[]);
        assert!(exports.contains(&"coef.SLOPE".to_string()));
        assert!(exports.contains(&"predict.GaussianSLOPE".to_string()));
    }

    #[test]
    fn s3method_three_arg_form_uses_explicit_method() {
        // `S3method(generic, class, method)` binds `method`, not `generic.class`.
        let ns = "S3method(print, foo, print_foo_impl)\n";
        let exports = resolve_exports(ns, &[]);
        assert!(exports.contains(&"print_foo_impl".to_string()));
        assert!(!exports.contains(&"print.foo".to_string()));
    }

    #[test]
    fn expands_export_pattern_excluding_dotted() {
        let ns = r#"exportPattern("^[^\\.]")"#;
        let objs = ["alpha", "beta", ".hidden", ".__NAMESPACE__."];
        let exports = resolve_exports(ns, &objs);
        assert_eq!(exports, vec!["alpha".to_string(), "beta".to_string()]);
    }

    #[test]
    fn unquotes_operator_exports() {
        let ns = r#"export("%>%")
                    export("n'est pas")"#;
        let exports = resolve_exports(ns, &[]);
        assert!(exports.contains(&"%>%".to_string()));
        assert!(exports.contains(&"n'est pas".to_string()));
    }

    #[test]
    fn ignores_export_inside_export_pattern_keyword() {
        // `find_call` must not treat the `export` in `exportPattern` as an
        // `export(...)` directive.
        let ns = r#"exportPattern("^x")"#;
        let exports = resolve_exports(ns, &["xa", "yb"]);
        assert_eq!(exports, vec!["xa".to_string()]);
    }

    #[test]
    fn ignores_directive_spellings_outside_namespace_positions() {
        let ns = r#"
            # export(in_comment)
            custom("export(in_string)", c(export(in_argument)))
            if (requireNamespace("pkg") && export(in_condition)) export(real)
            pkg::export(in_qualified_call)
        "#;
        let info = parse_namespace(ns, &[]);
        assert_eq!(info.exports, ["real".to_string()].into());
    }

    #[test]
    fn reads_directives_from_both_conditional_branches() {
        let ns = r#"
            if (getRversion() >= "4.0.0") {
                export(new_api)
            } else {
                export(old_api)
            }
        "#;
        let info = parse_namespace(ns, &[]);
        assert_eq!(
            info.exports,
            ["new_api".to_string(), "old_api".to_string()].into()
        );
    }

    #[test]
    fn parses_import_directives() {
        let ns = "import(rlang)\nimportFrom(dplyr, filter, select)\nexport(foo)\n";
        let info = parse_namespace(ns, &[]);
        assert!(info.exports.contains("foo"));
        assert!(info.imported_names.contains("filter"));
        assert!(info.imported_names.contains("select"));
        // The package name is not itself an imported name.
        assert!(!info.imported_names.contains("dplyr"));
        assert!(info.imported_packages.contains("rlang"));
    }

    #[test]
    fn import_keeps_only_the_packages_it_names() {
        // R's `import()` drops its `except` argument and treats every remaining
        // argument as a package. Keeping `except`'s value would invent a
        // package named `c(filter, lag)` — and since no index can enumerate
        // that, a consumer gating on "are these exports knowable" would
        // suppress the file permanently.
        let info = parse_namespace("import(dplyr, except = c(filter, lag))\n", &[]);
        assert_eq!(info.imported_packages, ["dplyr".to_string()].into());

        // Several packages in one directive is legal and must all be kept.
        let info = parse_namespace("import(stats, utils)\n", &[]);
        assert_eq!(
            info.imported_packages,
            ["stats".to_string(), "utils".to_string()].into()
        );
    }

    #[test]
    fn import_from_records_the_package_it_names() {
        // `importFrom(pkg, x)` references `pkg` as surely as `import(pkg)` does.
        // It is tracked apart because its names are already enumerated, so it
        // never makes resolution incomplete.
        let info = parse_namespace("importFrom(dplyr, filter, select)\n", &[]);
        assert_eq!(info.imported_from_packages, ["dplyr".to_string()].into());
        assert!(info.imported_packages.is_empty());
        assert_eq!(
            info.imported_names,
            ["filter".to_string(), "select".to_string()].into()
        );
    }

    #[test]
    fn use_dyn_lib_enumerates_explicit_routines() {
        // The first positional argument is the DLL, every later one a routine.
        let info = parse_namespace("useDynLib(backports, dotsElt, dotsLength)\n", &[]);
        assert_eq!(
            info.dynlib_routines,
            ["dotsElt".to_string(), "dotsLength".to_string()].into()
        );
        assert!(info.dynlib_registration.is_none());
    }

    #[test]
    fn use_dyn_lib_binds_the_alias_not_the_routine() {
        let info = parse_namespace("useDynLib(pkg, my_alias = c_routine)\n", &[]);
        assert_eq!(info.dynlib_routines, ["my_alias".to_string()].into());
    }

    #[test]
    fn use_dyn_lib_registration_records_its_fixes() {
        // `.registration`/`.fixes` are options, so neither names a binding, and
        // the routines themselves live in the package's C sources.
        let info = parse_namespace(
            "useDynLib(bit, .registration = TRUE, .fixes = \"C_\")\n",
            &[],
        );
        assert!(info.dynlib_routines.is_empty());
        let fixes = info.dynlib_registration.expect("registration declared");
        assert_eq!(fixes.apply("foo"), "C_foo");

        // Length-2 `.fixes` gives a suffix too, and an unspaced `=` is legal.
        let info = parse_namespace(
            "useDynLib(pkg,.registration=TRUE,.fixes=c(\"C_\",\"_\"))",
            &[],
        );
        let fixes = info.dynlib_registration.expect("registration declared");
        assert_eq!(fixes.apply("foo"), "C_foo_");

        // Without `.fixes` the registered name is bound verbatim.
        let info = parse_namespace("useDynLib(rlang, .registration = TRUE)\n", &[]);
        assert_eq!(
            info.dynlib_registration.expect("registration").apply("ffi"),
            "ffi"
        );
    }

    #[test]
    fn use_dyn_lib_without_registration_declares_none() {
        // A plain `useDynLib(pkg)` loads the library without binding any name,
        // and an explicit `FALSE` is not a declaration either.
        assert!(
            parse_namespace("useDynLib(caret)\n", &[])
                .dynlib_registration
                .is_none()
        );
        let info = parse_namespace("useDynLib(pkg, .registration = FALSE)\n", &[]);
        assert!(info.dynlib_registration.is_none());
        assert!(info.dynlib_routines.is_empty());
    }

    /// The S4 forms reference their package exactly as `importFrom` does. An S4
    /// package whose only reference to a dependency is one of these would
    /// otherwise look unused.
    #[test]
    fn s4_import_forms_record_the_package_they_name() {
        let info = parse_namespace(
            "importClassesFrom(Matrix, dgCMatrix)\nimportMethodsFrom(Matrix, crossprod)\n",
            &[],
        );
        assert_eq!(info.imported_from_packages, ["Matrix".to_string()].into());
        assert_eq!(
            info.imported_names,
            ["dgCMatrix".to_string(), "crossprod".to_string()].into()
        );
    }

    #[test]
    fn singular_s4_aliases_match_their_plural_forms() {
        let info = parse_namespace(
            "exportClass(OldClass)\nimportClassFrom(methods, oldClass)\n",
            &[],
        );
        assert_eq!(info.exports, ["OldClass".to_string()].into());
        assert_eq!(info.imported_from_packages, ["methods".to_string()].into());
        assert_eq!(info.imported_names, ["oldClass".to_string()].into());
    }

    #[test]
    fn no_namespace_exports_every_object() {
        // `base` ships no NAMESPACE; its whole object set is exported.
        let tmp = tempfile::tempdir().unwrap();
        let objs = vec!["as.matrix".to_string(), "cbind".to_string()];
        let exports = resolve_package_exports(tmp.path(), &objs);
        assert_eq!(exports, objs);
    }

    #[test]
    fn namespace_present_restricts_to_declared_exports() {
        let tmp = tempfile::tempdir().unwrap();
        std::fs::write(tmp.path().join("NAMESPACE"), "export(foo)\n").unwrap();
        let exports = resolve_package_exports(tmp.path(), &["foo".to_string(), "bar".to_string()]);
        assert_eq!(exports, vec!["foo".to_string()]);
    }

    #[test]
    fn parses_built_r_version() {
        assert_eq!(
            parse_built_r_version("R 4.5.3; ; 2025-01-01 00:00:00 UTC; unix").as_deref(),
            Some("4.5.3")
        );
    }
}