provenant/parsers/

cran.rs

// SPDX-FileCopyrightText: nexB Inc. and others
// ScanCode is a trademark of nexB Inc.
// SPDX-FileCopyrightText: Provenant contributors
// SPDX-License-Identifier: Apache-2.0
// Derived from ScanCode Toolkit (Apache-2.0); modified. See NOTICE.

//! Parser for CRAN R package DESCRIPTION files.
//!
//! Extracts package metadata and dependencies from R package DESCRIPTION files
//! which use Debian Control File (DCF) format similar to RFC822.
//!
//! # Supported Formats
//! - DESCRIPTION (CRAN R package manifest)
//!
//! # Key Features
//! - Multi-type dependency extraction (Depends, Imports, Suggests, Enhances, LinkingTo)
//! - Version constraint parsing with operators (>=, <=, >, <, ==)
//! - Filters out R version requirements (not actual packages)
//! - Author/Maintainer party extraction with email parsing
//! - Package URL (purl) generation
//!
//! # Implementation Notes
//! - Uses DCF/RFC822-like format with continuation lines
//! - Field names are case-sensitive (Package, Version, Description, etc.)
//! - Dependencies are comma-separated with optional version constraints
//! - R version requirements (e.g., "R (>= 4.1.0)") are filtered out
//! - Authors@R field is NOT parsed (requires R interpreter)

use std::collections::HashMap;
use std::path::Path;
use std::sync::LazyLock;

use crate::parser_warn as warn;
use packageurl::PackageUrl;
use regex::Regex;

use crate::models::{
    DatasourceId, Dependency, LicenseDetection, PackageData, PackageType, Party, PartyType,
};
use crate::parsers::license_normalization::{
    DeclaredLicenseMatchMetadata, NormalizedDeclaredLicense, build_declared_license_data,
    combine_normalized_licenses, normalize_declared_license_key, normalize_spdx_expression,
};
use crate::parsers::utils::{CappedIterExt, read_file_to_string, truncate_field};

use super::PackageParser;

/// CRAN R package DESCRIPTION file parser.
///
/// Extracts package metadata, dependencies, and party information from
/// standard DESCRIPTION files used by R packages in the CRAN ecosystem.
pub struct CranParser;

impl PackageParser for CranParser {
    const PACKAGE_TYPE: PackageType = PackageType::Cran;

    fn is_match(path: &Path) -> bool {
        path.file_name().is_some_and(|name| name == "DESCRIPTION")
    }

    fn extract_packages(path: &Path) -> Vec<PackageData> {
        let content = match read_file_to_string(path, None) {
            Ok(c) => c,
            Err(e) => {
                warn!("Failed to read DESCRIPTION at {:?}: {}", path, e);
                return vec![default_package_data()];
            }
        };
        let fields = parse_dcf(&content);

        let name = fields
            .get("Package")
            .map(|s| truncate_field(s.trim().to_string()));
        let version = fields
            .get("Version")
            .map(|s| truncate_field(s.trim().to_string()));

        // Generate PURL
        let purl = create_package_url(&name, &version);

        // Generate repository URLs
        let repository_homepage_url = name
            .as_ref()
            .map(|n| truncate_field(format!("https://cran.r-project.org/package={}", n)));

        // Build description from Title and Description fields
        let description = build_description(&fields);

        // Extract license statement
        let extracted_license_statement = fields
            .get("License")
            .map(|s| truncate_field(s.trim().to_string()));

        // Recover the SPDX core from R-specific `License:` idioms (e.g.
        // `MIT + file LICENSE`, `GPL-2 | file LICENSE`, `BSD_3_clause`) that the
        // shared declared-license normalization cannot parse. Cases this leaves
        // unset fall through to the shared post-extraction populate step.
        let (declared_license_expression, declared_license_expression_spdx, license_detections) =
            normalize_r_declared_license(extracted_license_statement.as_deref());

        // Extract URL field
        let homepage_url = fields
            .get("URL")
            .map(|s| truncate_field(s.split(',').next().unwrap_or("").trim().to_string()))
            .filter(|s| !s.is_empty());

        // Extract parties (Author and Maintainer)
        let mut parties = Vec::new();

        // Parse Maintainer field
        if let Some(maintainer_str) = fields.get("Maintainer")
            && let Some(party) = parse_party(maintainer_str, "maintainer")
        {
            parties.push(party);
        }

        // Parse Author field
        if let Some(author_str) = fields.get("Author") {
            for author_part in split_author_entries(author_str) {
                if let Some(party) = parse_party(author_part, "author") {
                    parties.push(party);
                }
            }
        }

        // Extract dependencies from all dependency fields
        let mut dependencies = Vec::new();

        // Process each dependency type
        for (field_name, scope) in [
            ("Depends", None),
            ("Imports", Some("imports")),
            ("Suggests", Some("suggests")),
            ("Enhances", Some("enhances")),
            ("LinkingTo", Some("linkingto")),
        ] {
            if let Some(deps_str) = fields.get(field_name) {
                dependencies.extend(parse_dependencies(deps_str, scope));
            }
        }

        vec![PackageData {
            package_type: Some(Self::PACKAGE_TYPE),
            namespace: None,
            name,
            version,
            qualifiers: None,
            subpath: None,
            primary_language: Some("R".to_string()),
            description,
            release_date: None,
            parties,
            keywords: Vec::new(),
            homepage_url,
            download_url: None,
            size: None,
            sha1: None,
            md5: None,
            sha256: None,
            sha512: None,
            bug_tracking_url: None,
            code_view_url: None,
            vcs_url: None,
            copyright: None,
            holder: None,
            declared_license_expression,
            declared_license_expression_spdx,
            license_detections,
            other_license_expression: None,
            other_license_expression_spdx: None,
            other_license_detections: Vec::new(),
            extracted_license_statement,
            notice_text: None,
            source_packages: Vec::new(),
            file_references: Vec::new(),
            is_private: false,
            is_virtual: false,
            extra_data: None,
            dependencies,
            repository_homepage_url,
            repository_download_url: None,
            api_data_url: None,
            datasource_id: Some(DatasourceId::CranDescription),
            purl,
        }]
    }

    fn metadata() -> Vec<super::metadata::ParserMetadata> {
        vec![super::metadata::ParserMetadata {
            description: "CRAN R package DESCRIPTION file",
            file_patterns: &["**/DESCRIPTION"],
            package_type: "cran",
            primary_language: "R",
            documentation_url: Some(
                "https://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file",
            ),
        }]
    }
}

fn parse_dcf(content: &str) -> HashMap<String, String> {
    let mut fields: HashMap<String, String> = HashMap::new();
    let mut current_field: Option<String> = None;
    let mut current_value = String::new();

    for line in content.lines().capped("DESCRIPTION DCF lines") {
        // Check if line is a continuation (starts with whitespace)
        if line.starts_with(' ') || line.starts_with('\t') {
            if current_field.is_some() {
                // Append to current value, replacing continuation line indent with space
                if !current_value.is_empty() {
                    current_value.push(' ');
                }
                current_value.push_str(line.trim_start());
            }
        } else if let Some((field_name, field_value)) = line.split_once(':') {
            // New field: save previous field if any
            if let Some(field) = current_field.take() {
                fields.insert(field, truncate_field(current_value.clone()));
                current_value.clear();
            }

            // Start new field
            current_field = Some(field_name.trim().to_string());
            current_value = field_value.trim_start().to_string();
        }
        // Else: empty line or invalid line - ignore
    }

    // Save the last field
    if let Some(field) = current_field {
        fields.insert(field, truncate_field(current_value));
    }

    fields
}

/// Parse a comma-separated dependency list with optional version constraints.
///
/// Format: "package1 (>= 1.0), package2, package3 (== 2.0)"
/// Filters out R version requirements like "R (>= 4.1.0)"
fn parse_dependencies(deps_str: &str, scope: Option<&str>) -> Vec<Dependency> {
    let mut dependencies = Vec::new();

    for dep in deps_str.split(',').capped("CRAN dependency list") {
        let dep = dep.trim();
        if dep.is_empty() {
            continue;
        }

        let (name, extracted_requirement, is_pinned) = parse_version_constraint(dep);

        // Skip R version requirements (not actual package dependencies)
        if name == "R" {
            continue;
        }

        // Create PURL for dependency
        let purl = if is_pinned {
            // For pinned versions, extract version from requirement
            if let Some(ref req) = extracted_requirement {
                if let Some(version) = extract_version_from_requirement(req) {
                    match PackageUrl::new("cran", &name) {
                        Ok(mut p) => {
                            if p.with_version(&version).is_ok() {
                                Some(p.to_string())
                            } else {
                                // Failed to set version, create without it
                                PackageUrl::new("cran", &name).ok().map(|p| p.to_string())
                            }
                        }
                        Err(e) => {
                            warn!(
                                "Failed to create PURL for CRAN dependency '{}': {}",
                                name, e
                            );
                            None
                        }
                    }
                } else {
                    // No version found in requirement
                    PackageUrl::new("cran", &name).ok().map(|p| p.to_string())
                }
            } else {
                // No requirement
                PackageUrl::new("cran", &name).ok().map(|p| p.to_string())
            }
        } else {
            // Not pinned, create PURL without version
            PackageUrl::new("cran", &name).ok().map(|p| p.to_string())
        };

        dependencies.push(Dependency {
            purl,
            extracted_requirement: extracted_requirement.map(truncate_field),
            scope: scope.map(|s| truncate_field(s.to_string())),
            is_runtime: Some(scope.is_none() || scope == Some("imports")),
            is_optional: Some(scope == Some("suggests") || scope == Some("enhances")),
            is_pinned: Some(is_pinned),
            is_direct: Some(true),
            resolved_package: None,
            extra_data: None,
        });
    }

    dependencies
}

static VERSION_CONSTRAINT_RE: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(r"^([a-zA-Z0-9.]+)\s*\(([><=]+)\s*([^)]+)\)\s*$").expect("valid regex")
});

/// Examples:
/// - "cli (>= 3.6.2)" -> ("cli", Some(">= 3.6.2"), true)
/// - "generics" -> ("generics", None, false)
/// - "glue (== 1.3.2)" -> ("glue", Some("== 1.3.2"), true)
fn parse_version_constraint(dep: &str) -> (String, Option<String>, bool) {
    if let Some(captures) = VERSION_CONSTRAINT_RE.captures(dep) {
        let name = match captures.get(1) {
            Some(m) => truncate_field(m.as_str().to_string()),
            None => return (truncate_field(dep.trim().to_string()), None, false),
        };
        let operator = match captures.get(2) {
            Some(m) => m.as_str(),
            None => return (name, None, false),
        };
        let version = match captures.get(3) {
            Some(m) => m.as_str(),
            None => return (name, None, false),
        };
        let requirement = truncate_field(format!("{} {}", operator, version));
        let is_pinned = operator == "==";

        (name, Some(requirement), is_pinned)
    } else {
        (truncate_field(dep.trim().to_string()), None, false)
    }
}

/// Extract version number from a requirement string like ">= 3.6.2" or "== 1.0.0".
fn extract_version_from_requirement(requirement: &str) -> Option<String> {
    requirement
        .split_whitespace()
        .nth(1)
        .map(|s| truncate_field(s.to_string()))
}

/// Build description from Title and Description fields.
fn build_description(fields: &HashMap<String, String>) -> Option<String> {
    let title = fields.get("Title").map(|s| s.trim());
    let desc = fields.get("Description").map(|s| s.trim());

    match (title, desc) {
        (Some(t), Some(d)) if !t.is_empty() && !d.is_empty() => {
            Some(truncate_field(format!("{}\n{}", t, d)))
        }
        (Some(t), _) if !t.is_empty() => Some(truncate_field(t.to_string())),
        (_, Some(d)) if !d.is_empty() => Some(truncate_field(d.to_string())),
        _ => None,
    }
}

fn split_author_entries(author_str: &str) -> Vec<&str> {
    let mut entries = Vec::new();
    let mut start = 0;
    let mut bracket_depth: usize = 0;
    let mut paren_depth: usize = 0;

    for (idx, ch) in author_str.char_indices().capped("CRAN author string") {
        match ch {
            '[' => bracket_depth += 1,
            ']' => bracket_depth = bracket_depth.saturating_sub(1),
            '(' => paren_depth += 1,
            ')' => paren_depth = paren_depth.saturating_sub(1),
            ',' if bracket_depth == 0 && paren_depth == 0 => {
                let entry = author_str[start..idx].trim();
                if !entry.is_empty() {
                    entries.push(entry);
                }
                start = idx + 1;
            }
            _ => {}
        }
    }

    let final_entry = author_str[start..].trim();
    if !final_entry.is_empty() {
        entries.push(final_entry);
    }

    entries
}

/// Parse party information from Author or Maintainer field.
///
/// Formats supported:
/// - "Name <email@domain.com>"
/// - "Name"
/// - "email@domain.com"
fn parse_party(info: &str, role: &str) -> Option<Party> {
    let info = info.trim();
    if info.is_empty() {
        return None;
    }

    // Check for "Name <email>" format
    if info.contains('<') && info.contains('>') {
        let parts: Vec<&str> = info.split('<').collect();
        if parts.len() == 2 {
            let name = parts[0].trim().to_string();
            let email = parts[1].trim_end_matches('>').trim().to_string();

            if !email.contains('@') {
                return Some(Party {
                    r#type: Some(PartyType::Person),
                    role: Some(truncate_field(role.to_string())),
                    name: Some(truncate_field(info.to_string())),
                    email: None,
                    url: None,
                    organization: None,
                    organization_url: None,
                    timezone: None,
                });
            }

            return Some(Party {
                r#type: Some(PartyType::Person),
                role: Some(truncate_field(role.to_string())),
                name: if name.is_empty() {
                    None
                } else {
                    Some(truncate_field(name))
                },
                email: if email.is_empty() {
                    None
                } else {
                    Some(truncate_field(email))
                },
                url: None,
                organization: None,
                organization_url: None,
                timezone: None,
            });
        }
    }

    // Just a name or email
    Some(Party {
        r#type: Some(PartyType::Person),
        role: Some(truncate_field(role.to_string())),
        name: Some(truncate_field(info.to_string())),
        email: None,
        url: None,
        organization: None,
        organization_url: None,
        timezone: None,
    })
}

/// Create a package URL for a CRAN package.
fn create_package_url(name: &Option<String>, version: &Option<String>) -> Option<String> {
    name.as_ref().and_then(|name| {
        let mut package_url = match PackageUrl::new("cran", name) {
            Ok(p) => p,
            Err(e) => {
                warn!(
                    "Failed to create PackageUrl for CRAN package '{}': {}",
                    name, e
                );
                return None;
            }
        };

        if let Some(v) = version
            && let Err(e) = package_url.with_version(v)
        {
            warn!(
                "Failed to set version '{}' for CRAN package '{}': {}",
                v, name, e
            );
            return None;
        }

        Some(package_url.to_string())
    })
}

/// Normalizes an R `License:` field into declared-license data, recovering the
/// SPDX core from R-specific idioms.
///
/// R's `DESCRIPTION` `License:` grammar is not SPDX: `|` separates alternatives
/// (OR), `+ file <NAME>` / `| file <NAME>` attach a supplementary file holding
/// the year/holder (the license itself is the non-file part), and BSD licenses
/// use underscore spellings (`BSD_3_clause`, `BSD_2_clause`).
///
/// This handles only the idioms the shared declared-license normalization cannot
/// parse. When the statement carries no R-specific idiom (e.g. a bare `GPL` or a
/// version-range `GPL (>= 3)`), this returns empty data so the statement falls
/// through to the shared post-extraction populate step, which already resolves
/// those forms. It is deliberately conservative: a pure `+ file <NAME>` pointer
/// is skipped, but if any real license alternative cannot be resolved (e.g. a
/// version-range form like `GPL (>= 3)` mixed with `|`), the whole statement is
/// left unset rather than emitting a partial that silently drops an operand.
fn normalize_r_declared_license(
    statement: Option<&str>,
) -> (Option<String>, Option<String>, Vec<LicenseDetection>) {
    let Some(statement) = statement.map(str::trim).filter(|value| !value.is_empty()) else {
        return empty_license_data();
    };

    if !has_r_license_idiom(statement) {
        return empty_license_data();
    }

    // `|` separates OR alternatives. Each alternative may carry a `+ file <NAME>`
    // (or be a bare `file <NAME>`) clause that is dropped; a pure `file <NAME>`
    // alternative yields no license core and is skipped.
    //
    // Every remaining license core must normalize. If any real alternative does
    // not (e.g. a version-range form this idiom layer does not expand, as in
    // `GPL-2 | GPL (>= 3)`), bail to an honest null via the shared path rather
    // than silently dropping that alternative and emitting a misleading partial.
    let mut normalized: Vec<NormalizedDeclaredLicense> = Vec::new();
    for core in statement
        .split('|')
        .capped("R License alternatives")
        .filter_map(strip_supplementary_file_clause)
    {
        let Some(license) = normalize_r_license_core(core) else {
            return empty_license_data();
        };
        normalized.push(license);
    }

    if normalized.is_empty() {
        return empty_license_data();
    }

    let Some(combined) = combine_normalized_licenses(normalized, " OR ") else {
        return empty_license_data();
    };

    build_declared_license_data(
        combined,
        DeclaredLicenseMatchMetadata::single_line(statement),
    )
}

/// Returns true when the statement uses an R-specific `License:` idiom that the
/// shared SPDX/declared normalization cannot parse on its own: an alternative
/// separator (`|`), a supplementary `file` clause, or an underscore BSD
/// spelling.
fn has_r_license_idiom(statement: &str) -> bool {
    if statement.contains('|') {
        return true;
    }
    let lower = statement.to_ascii_lowercase();
    lower.contains("file ") || lower.contains("bsd_3_clause") || lower.contains("bsd_2_clause")
}

/// Drops a trailing `+ file <NAME>` supplementary-file clause from one
/// alternative and returns the remaining license core. A bare `file <NAME>`
/// alternative (no license core) yields `None` so it is skipped.
fn strip_supplementary_file_clause(alternative: &str) -> Option<String> {
    let core = alternative
        .split('+')
        .capped("R License components")
        .map(str::trim)
        .filter(|component| {
            !component.is_empty() && !component.to_ascii_lowercase().starts_with("file ")
        })
        .collect::<Vec<_>>()
        .join(" + ");

    let core = core.trim();
    (!core.is_empty()).then(|| core.to_string())
}

/// Matches R's bare GNU-family version spelling (`GPL-2`, `LGPL-2.1`, `AGPL-3`)
/// so the major-only form can be expanded to the SPDX point release.
static R_GNU_FAMILY_RE: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"(?i)^(A?GPL|LGPL)-(\d+)(\.\d+)?$").expect("valid regex"));

/// Resolves a single cleaned R license core into a normalized declared license,
/// mapping R's non-SPDX spellings to SPDX before normalization.
///
/// R writes BSD licenses with underscores (`BSD_3_clause`) and GNU licenses with
/// a bare major version (`GPL-2`, `LGPL-3`); the latter is not valid SPDX, which
/// requires the point release (`GPL-2.0`). A major-only GNU version is expanded
/// to its canonical point release (`GPL-2` -> `GPL-2.0`), matching R's "version N
/// exactly" meaning (the `-only` SPDX form). Version-or-later forms such as
/// `GPL (>= 2)` are not handled here; they carry no R-specific idiom and are left
/// to the shared post-extraction populate step.
fn normalize_r_license_core(core: String) -> Option<NormalizedDeclaredLicense> {
    let mapped = match core.to_ascii_lowercase().as_str() {
        "bsd_3_clause" => "BSD-3-Clause".to_string(),
        "bsd_2_clause" => "BSD-2-Clause".to_string(),
        _ => expand_r_gnu_family_version(&core),
    };

    normalize_spdx_expression(&mapped).or_else(|| normalize_declared_license_key(&mapped))
}

/// Expands R's bare GNU-family version (`GPL-2`) to the SPDX point release
/// (`GPL-2.0`), leaving an explicit minor version (`LGPL-2.1`) and any
/// non-GNU value untouched.
fn expand_r_gnu_family_version(core: &str) -> String {
    match R_GNU_FAMILY_RE.captures(core) {
        Some(captures) if captures.get(3).is_none() => {
            format!("{}-{}.0", &captures[1], &captures[2])
        }
        _ => core.to_string(),
    }
}

fn empty_license_data() -> (Option<String>, Option<String>, Vec<LicenseDetection>) {
    (None, None, Vec::new())
}

fn default_package_data() -> PackageData {
    PackageData {
        package_type: Some(CranParser::PACKAGE_TYPE),
        primary_language: Some("R".to_string()),
        datasource_id: Some(DatasourceId::CranDescription),
        ..Default::default()
    }
}