provenant/models/

purl.rs

// SPDX-FileCopyrightText: Provenant contributors
// SPDX-License-Identifier: Apache-2.0

//! Central, per-type Package-URL (PURL) normalization.
//!
//! The `packageurl` crate percent-encodes components and lowercases a few
//! hard-coded names, but does not apply the full per-type case/canonicalization
//! rules from the [purl-spec](https://github.com/package-url/purl-spec), and
//! never touches the namespace. Without a central layer each parser would have
//! to reimplement these rules, so the same package could get different PURLs
//! from different datasources (e.g. `typing_extensions` vs `typing-extensions`),
//! breaking dedup and registry/vuln-database lookups.
//!
//! Every emitted PURL passes through [`normalize_purl`]: in-memory before a
//! [`crate::models::Package`] derives its `package_uid` (the dedup key), and at
//! the `src/output_schema` boundary for package, package-data, dependency, and
//! resolved-package PURLs.
//!
//! This layer covers the case/name-canonicalization rules. Structural per-type
//! fixes that need parser knowledge (type remapping, moving a value between
//! namespace/qualifier/subpath, synthesizing a required qualifier) stay with the
//! owning parser. Unlisted types are returned unchanged, preserving the
//! case-sensitive types (npm, maven, cargo, gem, …).

use std::borrow::Cow;
use std::str::FromStr;

use packageurl::PackageUrl;

/// Normalize a PURL string according to its type's spec rules.
///
/// Per-type case/canonicalization rules are applied to the namespace and name;
/// version, qualifiers, and subpath are preserved. Unparsable input and types
/// with no rule are returned unchanged, so already-canonical PURLs never churn.
pub fn normalize_purl(purl: &str) -> String {
    let Ok(parsed) = PackageUrl::from_str(purl) else {
        return purl.to_string();
    };

    let (new_namespace, new_name): (Option<String>, String) = match parsed.ty() {
        // PEP 503: lowercase, then collapse runs of `-_.` to a single `-` (the
        // crate only handles `_`). Namespace is prohibited for pypi.
        "pypi" => (None, normalize_pypi_name(parsed.name())),

        // Lowercase namespace + name. The crate lowercases some of these names
        // but never the namespace.
        "composer" | "hex" | "github" | "gitlab" | "bitbucket" => (
            parsed.namespace().map(str::to_ascii_lowercase),
            parsed.name().to_ascii_lowercase(),
        ),

        // golang's spec is self-contradictory and acknowledged-broken; the
        // decided direction (purl-spec#308) is to lowercase only the host
        // segment and preserve path-part case (e.g. keep `github.com/Azure/…`).
        // The crate force-lowercases the whole golang namespace at parse time,
        // so `parsed` has already lost the case — edit the raw string instead.
        "golang" => return lowercase_first_path_segment(purl, "pkg:golang/"),

        _ => return purl.to_string(),
    };

    rebuild(purl, &parsed, new_namespace, new_name)
}

/// Re-emit `parsed` with a replaced namespace/name, preserving the rest.
///
/// Falls back to the original string if the rebuilt PURL cannot be constructed.
fn rebuild(
    original: &str,
    parsed: &PackageUrl<'_>,
    namespace: Option<String>,
    name: String,
) -> String {
    let Ok(mut rebuilt) = PackageUrl::new(parsed.ty().to_string(), name) else {
        return original.to_string();
    };

    if let Some(namespace) = namespace.filter(|value| !value.is_empty())
        && rebuilt.with_namespace(namespace).is_err()
    {
        return original.to_string();
    }

    if let Some(version) = parsed.version()
        && rebuilt.with_version(version.to_string()).is_err()
    {
        return original.to_string();
    }

    for (key, value) in parsed.qualifiers() {
        if rebuilt
            .add_qualifier(key.to_string(), value.to_string())
            .is_err()
        {
            return original.to_string();
        }
    }

    if let Some(subpath) = parsed.subpath()
        && rebuilt.with_subpath(subpath.to_string()).is_err()
    {
        return original.to_string();
    }

    rebuilt.to_string()
}

/// Apply the PEP 503 normalized distribution name rule: lowercase, then collapse
/// every run of `-`, `_`, or `.` into a single `-`.
fn normalize_pypi_name(name: &str) -> String {
    let lower = name.to_ascii_lowercase();
    let mut normalized = String::with_capacity(lower.len());
    let mut last_was_separator = false;

    for ch in lower.chars() {
        if matches!(ch, '-' | '_' | '.') {
            if !last_was_separator {
                normalized.push('-');
                last_was_separator = true;
            }
        } else {
            normalized.push(ch);
            last_was_separator = false;
        }
    }

    normalized
}

/// Lowercase the first path segment that follows `prefix` in a PURL string,
/// stopping at the next path separator or component delimiter (`/ @ ? #`).
///
/// Used for golang's host-only lowercasing: it edits the raw string so the
/// remaining path parts, version, qualifiers, and subpath survive untouched.
/// Returns the input unchanged if it does not start with `prefix`.
fn lowercase_first_path_segment(purl: &str, prefix: &str) -> String {
    let Some(rest) = purl.strip_prefix(prefix) else {
        return purl.to_string();
    };
    let end = rest.find(['/', '@', '?', '#']).unwrap_or(rest.len());
    format!(
        "{prefix}{}{}",
        rest[..end].to_ascii_lowercase(),
        &rest[end..]
    )
}

/// Add the `uuid` qualifier that turns a PURL into a UID, keeping it a
/// qualifier.
///
/// A PURL orders its parts `…?qualifiers#subpath`, so appending to the end of the
/// string lands the uuid *inside the subpath* whenever one is present: a
/// cocoapods subspec UID came out as `pkg:cocoapods/SwiftFormat@0.44.17#CLI?uuid=…`,
/// where `?uuid=…` is no longer a qualifier and re-parsing yields the subpath
/// `CLI?uuid=…`. Insert ahead of the subpath instead, and use `&` only when the
/// PURL already carries a qualifier.
///
/// Non-PURL bases (the `generated-package:` fallback identity) carry neither
/// qualifiers nor a subpath, so they simply take the `?uuid=` form.
pub(crate) fn append_uuid_qualifier(base: &str, uuid: &str) -> String {
    let (head, subpath) = split_subpath(base);
    let separator = if head.contains('?') { '&' } else { '?' };
    match subpath {
        Some(subpath) => format!("{head}{separator}uuid={uuid}#{subpath}"),
        None => format!("{head}{separator}uuid={uuid}"),
    }
}

/// The UID with its `uuid` qualifier removed, restoring the underlying PURL.
///
/// Borrows whenever the UID has no subpath, which is the common case; only a
/// subpath-carrying UID needs the two remaining parts rejoined.
pub(crate) fn strip_uuid_qualifier(uid: &str) -> Cow<'_, str> {
    let (head, subpath) = split_subpath(uid);
    let Some((prefix, _)) = head
        .split_once("?uuid=")
        .or_else(|| head.split_once("&uuid="))
    else {
        return Cow::Borrowed(uid);
    };

    match subpath {
        Some(subpath) => Cow::Owned(format!("{prefix}#{subpath}")),
        None => Cow::Borrowed(prefix),
    }
}

/// The value of a UID's `uuid` qualifier, or `None` when it carries none.
pub(crate) fn uuid_qualifier_value(uid: &str) -> Option<&str> {
    let (head, _) = split_subpath(uid);
    head.split_once("?uuid=")
        .or_else(|| head.split_once("&uuid="))
        .map(|(_, uuid)| uuid)
}

fn split_subpath(purl: &str) -> (&str, Option<&str>) {
    match purl.split_once('#') {
        Some((head, subpath)) => (head, Some(subpath)),
        None => (purl, None),
    }
}

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

    #[test]
    fn uuid_qualifier_stays_a_qualifier_when_the_purl_has_a_subpath() {
        let uid = append_uuid_qualifier("pkg:cocoapods/SwiftFormat@0.44.17#CLI", "abc");
        assert_eq!(uid, "pkg:cocoapods/SwiftFormat@0.44.17?uuid=abc#CLI");
        assert_eq!(
            strip_uuid_qualifier(&uid),
            "pkg:cocoapods/SwiftFormat@0.44.17#CLI"
        );

        // The parsed UID must still expose the original subpath rather than one
        // with the uuid swallowed into it.
        let parsed = PackageUrl::from_str(&uid).expect("uid should parse as a purl");
        assert_eq!(parsed.subpath(), Some("CLI"));
        assert_eq!(
            parsed.qualifiers().get("uuid").map(Cow::as_ref),
            Some("abc")
        );
    }

    #[test]
    fn uuid_qualifier_joins_existing_qualifiers_with_an_ampersand() {
        let uid = append_uuid_qualifier("pkg:generic/x?arch=amd64", "abc");
        assert_eq!(uid, "pkg:generic/x?arch=amd64&uuid=abc");
        assert_eq!(strip_uuid_qualifier(&uid), "pkg:generic/x?arch=amd64");
    }

    #[test]
    fn uuid_qualifier_round_trips_plain_purls_and_opaque_bases() {
        for base in [
            "pkg:pypi/requests@2.0",
            "pkg:npm/%40scope/name@1.0.0",
            "generated-package:cargo/unknown@unknown",
        ] {
            let uid = append_uuid_qualifier(base, "abc");
            assert_eq!(uid, format!("{base}?uuid=abc"));
            assert_eq!(strip_uuid_qualifier(&uid), base);
        }
    }

    #[test]
    fn strip_uuid_qualifier_leaves_a_uid_without_one_untouched() {
        assert_eq!(
            strip_uuid_qualifier("pkg:pypi/requests@2.0"),
            "pkg:pypi/requests@2.0"
        );
        assert_eq!(strip_uuid_qualifier(""), "");
    }

    /// Spec-rule matrix: representative PURL per type asserted against the
    /// canonical form. Guards every parser against drift.
    #[test]
    fn normalize_purl_matrix() {
        let cases = [
            // pypi: full PEP 503 (lowercase + collapse `-_.` runs).
            (
                "pkg:pypi/typing_extensions@4.0.0",
                "pkg:pypi/typing-extensions@4.0.0",
            ),
            ("pkg:pypi/Django@4.2", "pkg:pypi/django@4.2"),
            ("pkg:pypi/zope.interface@5.0", "pkg:pypi/zope-interface@5.0"),
            ("pkg:pypi/foo__bar@1.0", "pkg:pypi/foo-bar@1.0"),
            // composer: lowercase vendor namespace + name.
            (
                "pkg:composer/Monolog/Monolog@2.0",
                "pkg:composer/monolog/monolog@2.0",
            ),
            // hex: lowercase namespace + name.
            ("pkg:hex/Phoenix@1.7.0", "pkg:hex/phoenix@1.7.0"),
            // github / gitlab / bitbucket: lowercase namespace + name.
            (
                "pkg:github/Package-Url/purl-Spec@1.0",
                "pkg:github/package-url/purl-spec@1.0",
            ),
            ("pkg:gitlab/FooBar/Baz@2.0", "pkg:gitlab/foobar/baz@2.0"),
            (
                "pkg:bitbucket/Birkenfeld/Pygments@2.0",
                "pkg:bitbucket/birkenfeld/pygments@2.0",
            ),
            // golang: lowercase host only, preserve path-part case.
            (
                "pkg:golang/github.com/Azure/azure-sdk-for-go@1.0",
                "pkg:golang/github.com/Azure/azure-sdk-for-go@1.0",
            ),
            (
                "pkg:golang/GitHub.com/Azure/azure-sdk-for-go@1.0",
                "pkg:golang/github.com/Azure/azure-sdk-for-go@1.0",
            ),
        ];

        for (input, expected) in cases {
            assert_eq!(normalize_purl(input), expected, "input: {input}");
        }
    }

    /// Case-sensitive and custom types must be returned byte-for-byte unchanged.
    #[test]
    fn normalize_purl_preserves_case_sensitive_types() {
        let untouched = [
            // npm grandfathers mixed-case names.
            "pkg:npm/%40angular/Core@13.0.0",
            "pkg:maven/com.Example/MyLib@1.0",
            "pkg:cargo/Serde@1.0",
            "pkg:gem/RSpec@3.0",
            // Unknown / custom type with no registered spec.
            "pkg:bower/SomeLib@1.0",
        ];

        for purl in untouched {
            assert_eq!(normalize_purl(purl), purl, "input: {purl}");
        }
    }

    #[test]
    fn normalize_purl_is_idempotent() {
        let inputs = [
            "pkg:pypi/typing_extensions@4.0.0",
            "pkg:composer/Monolog/Monolog@2.0",
            "pkg:golang/GitHub.com/Azure/azure-sdk-for-go@1.0",
            "pkg:github/Foo/Bar",
        ];

        for input in inputs {
            let once = normalize_purl(input);
            let twice = normalize_purl(&once);
            assert_eq!(once, twice, "not idempotent for {input}");
        }
    }

    #[test]
    fn normalize_purl_preserves_qualifiers_and_subpath() {
        // pypi name changes, but qualifiers and subpath survive the round-trip.
        assert_eq!(
            normalize_purl("pkg:pypi/typing_extensions@4.0?arch=any#sub/path"),
            "pkg:pypi/typing-extensions@4.0?arch=any#sub/path",
        );
    }

    #[test]
    fn normalize_purl_returns_unparsable_input_unchanged() {
        assert_eq!(normalize_purl("not-a-purl"), "not-a-purl");
        assert_eq!(normalize_purl(""), "");
    }

    #[test]
    fn normalize_purl_handles_pypi_without_version() {
        assert_eq!(
            normalize_purl("pkg:pypi/typing_extensions"),
            "pkg:pypi/typing-extensions",
        );
    }

    /// A golang PURL with no namespace (single-segment module path): the whole
    /// `rest` slice is lowercased, which is the correct host-only rule when the
    /// module name itself is the host (e.g. the standard library placeholder).
    #[test]
    fn normalize_purl_golang_no_namespace() {
        assert_eq!(
            normalize_purl("pkg:golang/Std@go1.21"),
            "pkg:golang/std@go1.21",
        );
        // Already lowercase — unchanged.
        assert_eq!(
            normalize_purl("pkg:golang/std@go1.21"),
            "pkg:golang/std@go1.21",
        );
    }

    /// Qualifiers and subpath on a golang PURL must survive the raw-string edit.
    #[test]
    fn normalize_purl_golang_preserves_qualifiers_and_subpath() {
        assert_eq!(
            normalize_purl(
                "pkg:golang/GITHUB.COM/Azure/pkg@1.0?vcs_url=https://github.com/Azure/pkg#sub/path"
            ),
            "pkg:golang/github.com/Azure/pkg@1.0?vcs_url=https://github.com/Azure/pkg#sub/path",
        );
    }

    /// A golang PURL whose type prefix is not all-lowercase is returned unchanged
    /// because `lowercase_first_path_segment` relies on the crate serializer
    /// always emitting a lowercase type; all PURL-generating paths in this code
    /// base go through that serializer so this edge is never triggered in practice.
    #[test]
    fn normalize_purl_golang_mixed_case_type_unchanged() {
        // The crate's serializer always lowercases the type, so "pkg:Golang/"
        // never appears in practice. The function documents this no-op contract.
        assert_eq!(
            normalize_purl("pkg:Golang/GITHUB.COM/Azure/pkg@1.0"),
            "pkg:Golang/GITHUB.COM/Azure/pkg@1.0",
        );
    }
}