release-kit 0.9.14

//! `rk versions`: the pinned-tool registry, and its freshness check.
//!
//! Plain `rk versions` prints the registry exactly as authored, offline.
//! `--check` is the canon-side freshness answer and, beside `rk self-depend
//! sync`, one of the two verbs that fetch: it consults each pin's check
//! URL and reports per pin, where
//! an unreachable or unparsable source is a reported result at exit 0,
//! not an error — and it never edits `versions.toml`, because a pin
//! update is a reviewed change in this repository. The fetch goes through
//! `curl`, resolved like the forge CLIs with `RK_CURL_BIN` as the
//! override, so the check needs no HTTP stack of its own and a test can
//! substitute the network.

use serde::Serialize;

use crate::cli::versions::VersionsArgs;
use crate::error::RkError;
use crate::output::Output;
use crate::{embedded, registry};

/// One pin's check result.
#[derive(Debug, Serialize)]
struct PinResult {
    /// The tool's registry name.
    tool: String,
    /// The pinned version.
    pinned: String,
    /// `current`, `update-available`, `source-unreachable`,
    /// `source-unparsable`, or — for a pin whose freshness lives in its
    /// ref alone — `no-version-source`.
    result: &'static str,
    /// The version the source serves, where one was read.
    #[serde(skip_serializing_if = "Option::is_none")]
    available: Option<String>,
    /// The immutable execution commit, where the pin is an action.
    #[serde(skip_serializing_if = "Option::is_none")]
    commit: Option<String>,
    /// How the discovery ref moves, from the registry.
    #[serde(skip_serializing_if = "Option::is_none")]
    ref_class: Option<String>,
    /// `ref-unmoved`, `ref-moved`, `ref-unreachable`, or
    /// `ref-unparsable`, for a pin carrying an action and a commit.
    #[serde(skip_serializing_if = "Option::is_none")]
    ref_result: Option<&'static str>,
    /// The commit the discovery ref names today, where it was read.
    #[serde(skip_serializing_if = "Option::is_none")]
    ref_commit: Option<String>,
}

/// The machine form of a check report.
#[derive(Debug, Serialize)]
struct Report {
    /// The shape version of this document.
    schema: &'static str,
    /// One result per pin, in registry order.
    pins: Vec<PinResult>,
}

/// Print the registry, or check each pin upstream under `--check`.
///
/// # Errors
///
/// Returns [`RkError::Other`] only when the report cannot serialize; an
/// unreachable or unparsable source is a reported result, not a failure.
pub fn run(args: &VersionsArgs) -> Result<(), RkError> {
    if !args.check {
        Output::human().result_raw(embedded::VERSIONS);
        return Ok(());
    }
    let out = Output::new(args.json);
    let mut results = Vec::new();
    for pin in registry::pins() {
        let mut result = pin.check.as_deref().map_or_else(
            || PinResult {
                tool: pin.name.clone(),
                pinned: pin.version.clone(),
                // A pin can live without a version source only where its
                // freshness signal is the discovery ref itself.
                result: if pin.action.is_some() && pin.commit.is_some() {
                    "no-version-source"
                } else {
                    "source-unreachable"
                },
                available: None,
                commit: None,
                ref_class: None,
                ref_result: None,
                ref_commit: None,
            },
            |url| check_one(&pin.name, &pin.version, url),
        );
        if let (Some(action), Some(commit)) = (&pin.action, &pin.commit) {
            let (ref_result, ref_commit) = resolve_ref(action, commit);
            result.commit = Some(commit.clone());
            result.ref_class.clone_from(&pin.ref_class);
            result.ref_result = Some(ref_result);
            result.ref_commit = ref_commit;
        }
        out.result_line(match (&result.result, &result.available) {
            (&"update-available", Some(available)) => format!(
                "update-available {} {} pinned, {available} at the source",
                result.tool, result.pinned
            ),
            _ => format!("{} {} {}", result.result, result.tool, result.pinned),
        });
        if let Some(ref_result) = result.ref_result {
            let reference = pin
                .action
                .as_deref()
                .and_then(|action| action.split_once('@'))
                .map_or_else(String::new, |(_, reference)| reference.to_owned());
            out.result_line(match (ref_result, &result.ref_commit) {
                // Movement of a discovery ref is normal and by design: it
                // is an update signal the pinned commit already contains,
                // never something the tool can call an attack.
                ("ref-moved", Some(now)) => format!(
                    "ref-moved {}: {reference} now names {now}; an update to review, not an incident",
                    result.tool
                ),
                ("ref-unmoved", _) => format!(
                    "ref-unmoved {}: {reference} still names the pinned commit",
                    result.tool
                ),
                _ => format!("{ref_result} {}: {reference}", result.tool),
            });
        }
        results.push(result);
    }
    out.next(&[
        "a pin update is a reviewed change to versions.toml, with its checked date".to_owned(),
    ]);
    out.emit(&Report {
        schema: "rk.versions-check/2",
        pins: results,
    })
}

/// Resolve an action's discovery ref to the commit it names today and
/// compare it against the pinned execution commit.
fn resolve_ref(action: &str, pinned_commit: &str) -> (&'static str, Option<String>) {
    let Some((path, reference)) = action.split_once('@') else {
        return ("ref-unparsable", None);
    };
    // An action may live below its repository's root — `owner/repo/init` is
    // one entry point of `owner/repo` — and a ref belongs to the repository,
    // so only the first two segments address it.
    let mut segments = path.split('/');
    let (Some(owner), Some(repo)) = (segments.next(), segments.next()) else {
        return ("ref-unparsable", None);
    };
    // The ref is one path segment, so a `/` inside it is encoded rather than
    // passed through. This endpoint happens to accept the raw form too, but
    // the documented contract is the encoded one and a maintained-branch ref
    // like `release/v1` is exactly the case that relies on it.
    let encoded: String = reference
        .bytes()
        .map(|byte| {
            if byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-' | b'_' | b'~') {
                char::from(byte).to_string()
            } else {
                format!("%{byte:02X}")
            }
        })
        .collect();
    let url = format!("https://api.github.com/repos/{owner}/{repo}/commits/{encoded}");
    let curl = std::env::var_os("RK_CURL_BIN").unwrap_or_else(|| "curl".into());
    let fetched = std::process::Command::new(curl)
        .args(["-fsSL", "--max-time", "10", &url])
        .output();
    let body = match fetched {
        Ok(output) if output.status.success() => output.stdout,
        _ => return ("ref-unreachable", None),
    };
    let Some(sha) = serde_json::from_slice::<serde_json::Value>(&body)
        .ok()
        .and_then(|value| {
            value
                .get("sha")
                .and_then(serde_json::Value::as_str)
                .map(str::to_owned)
        })
    else {
        return ("ref-unparsable", None);
    };
    if sha == pinned_commit {
        ("ref-unmoved", Some(sha))
    } else {
        ("ref-moved", Some(sha))
    }
}

/// The page bound for a paged answer: at 100 entries a page, ten pages is
/// a thousand tags, past any forge project this registry pins, and Docker
/// Hub refuses an anonymous read past its tenth page. A source deeper than
/// that reads as unreachable rather than as a version this check silently
/// guessed.
const MAX_PAGES: u32 = 10;

/// One GET, or `None` where the fetch failed.
fn fetch(url: &str) -> Option<Vec<u8>> {
    let curl = std::env::var_os("RK_CURL_BIN").unwrap_or_else(|| "curl".into());
    let fetched = std::process::Command::new(curl)
        .args(["-fsSL", "--max-time", "10", url])
        .output();
    match fetched {
        Ok(output) if output.status.success() => Some(output.stdout),
        _ => None,
    }
}

/// The same URL at a later page, in the query form every paged source here
/// takes.
fn paged(url: &str, page: u32) -> String {
    let joiner = if url.contains('?') { '&' } else { '?' };
    format!("{url}{joiner}page={page}")
}

/// Fetch one check URL and classify the answer.
///
/// An object answer — a crates.io crate, a forge's latest release — is one
/// GET. An array answer is a page of a list, and the endpoint documents no
/// ordering, so reading one page would compute the greatest of an arbitrary
/// subset and could report a stale pin as current. Every page is therefore
/// read, to the bound above, and the greatest version across all of them
/// wins.
///
/// Reaching the bound with a page still full is not an answer: the list
/// continues past what was read, so the greatest version is unknown. That
/// reads as `source-unreachable`, the same as a failed fetch, rather than
/// as the greatest of the pages that happened to fit. A Docker Hub tag
/// list is an object that links its next page, and it is read the same
/// way: every page to the same bound, the greatest numbered tag across
/// them, and a failed page or a bound reached with a next page still
/// named reads as `source-unreachable`.
fn check_one(tool: &str, pinned: &str, url: &str) -> PinResult {
    check_with(tool, pinned, url, fetch)
}

/// [`check_one`] over any fetch, so a test can answer each URL itself.
fn check_with(
    tool: &str,
    pinned: &str,
    url: &str,
    fetch: impl Fn(&str) -> Option<Vec<u8>>,
) -> PinResult {
    let result = |result, available| PinResult {
        tool: tool.to_owned(),
        pinned: pinned.to_owned(),
        result,
        available,
        commit: None,
        ref_class: None,
        ref_result: None,
        ref_commit: None,
    };
    let Some(body) = fetch(url) else {
        return result("source-unreachable", None);
    };
    let mut best = latest_version(&body);
    if is_page(&body) && !is_empty_page(&body) {
        let mut ended = false;
        for page in 2..=MAX_PAGES {
            let Some(body) = fetch(&paged(url, page)) else {
                return result("source-unreachable", None);
            };
            // Every page of a list is a list. A later page that answers
            // some other shape is a source this reader does not
            // understand, and feeding it to the object parser would mint
            // a version out of an answer that names no tag.
            if !is_page(&body) {
                return result("source-unparsable", None);
            }
            if is_empty_page(&body) {
                ended = true;
                break;
            }
            best = greater(best, latest_version(&body));
        }
        if !ended {
            return result("source-unreachable", None);
        }
    } else {
        // A Docker Hub tag list names its next page in `next`, and its
        // order does not establish the greatest version, so every page is
        // read, to the bound.
        let mut next = next_page(&body);
        let mut pages = 1;
        while let Some(link) = next {
            if pages == MAX_PAGES {
                return result("source-unreachable", None);
            }
            let Some(body) = fetch(&link) else {
                return result("source-unreachable", None);
            };
            if !is_tag_list(&body) {
                return result("source-unparsable", None);
            }
            best = greater(best, latest_version(&body));
            next = next_page(&body);
            pages += 1;
        }
    }
    let Some(available) = best else {
        return result("source-unparsable", None);
    };
    if is_current(pinned, &available) {
        result("current", Some(available))
    } else {
        result("update-available", Some(available))
    }
}

/// Whether the answer is one page of a list rather than a single object.
fn is_page(body: &[u8]) -> bool {
    serde_json::from_slice::<serde_json::Value>(body).is_ok_and(|value| value.is_array())
}

/// Whether the answer is a page of a Docker Hub tag list.
fn is_tag_list(body: &[u8]) -> bool {
    serde_json::from_slice::<serde_json::Value>(body).is_ok_and(|value| {
        value
            .get("results")
            .is_some_and(serde_json::Value::is_array)
    })
}

/// The link a Docker Hub tag list page gives to the page after it, or
/// `None` on its last page and on every other answer.
fn next_page(body: &[u8]) -> Option<String> {
    let value: serde_json::Value = serde_json::from_slice(body).ok()?;
    value.get("results")?.as_array()?;
    value
        .get("next")?
        .as_str()
        .filter(|link| !link.is_empty())
        .map(str::to_owned)
}

/// Whether the answer is a page past the end of the list.
fn is_empty_page(body: &[u8]) -> bool {
    serde_json::from_slice::<serde_json::Value>(body)
        .is_ok_and(|value| value.as_array().is_some_and(Vec::is_empty))
}

/// The greater of two versions, comparing numerically component by
/// component, with an absent version losing to any present one.
fn greater(left: Option<String>, right: Option<String>) -> Option<String> {
    match (left, right) {
        (Some(left), Some(right)) => {
            if numeric_parts(&right) > numeric_parts(&left) {
                Some(right)
            } else {
                Some(left)
            }
        }
        (some, None) | (None, some) => some,
    }
}

/// The latest version a source's JSON names, across the four answer
/// shapes: `max_stable_version` from a crates.io answer, `tag_name` from a
/// forge's releases answer, the greatest `name` from a forge's tags
/// answer, which is an array, and the greatest numbered `name` in the
/// `results` of a Docker Hub tag list.
///
/// The tags shape exists for a project that publishes tags and cuts no
/// releases, so no releases answer names its latest version. The greatest
/// is taken rather than the first, because the endpoint promises no
/// ordering. A Docker Hub tag counts only where it opens with its version,
/// read up to the variant suffix, so `13.7-slim` reads as `13.7` and a
/// dated suite tag never passes for a version.
fn latest_version(body: &[u8]) -> Option<String> {
    let value: serde_json::Value = serde_json::from_slice(body).ok()?;
    if let Some(tags) = value.as_array() {
        return tags
            .iter()
            .filter_map(|tag| tag.get("name").and_then(serde_json::Value::as_str))
            .filter_map(number_from)
            .max_by(|left, right| numeric_parts(left).cmp(&numeric_parts(right)));
    }
    if let Some(results) = value.get("results").and_then(serde_json::Value::as_array) {
        return results
            .iter()
            .filter_map(|tag| tag.get("name").and_then(serde_json::Value::as_str))
            .filter(|name| name.starts_with(|c: char| c.is_ascii_digit()))
            .map(|name| {
                name.split(|c: char| !(c.is_ascii_digit() || c == '.'))
                    .next()
                    .unwrap_or_default()
                    .trim_end_matches('.')
                    .to_owned()
            })
            .max_by(|left, right| numeric_parts(left).cmp(&numeric_parts(right)));
    }
    let raw = value
        .get("crate")
        .and_then(|krate| krate.get("max_stable_version"))
        .or_else(|| value.get("tag_name"))
        .and_then(serde_json::Value::as_str)?;
    number_from(raw)
}

/// A ref name from its first digit on: a tag may prefix the number —
/// `v2.13.1`, or a name before it.
fn number_from(raw: &str) -> Option<String> {
    let start = raw.find(|c: char| c.is_ascii_digit())?;
    Some(raw[start..].to_owned())
}

/// A version's numeric components, so that 2.10 orders above 2.9 rather
/// than below it; the first component that is not a number ends the list,
/// which keeps a suffixed variant below its plain sibling.
fn numeric_parts(version: &str) -> Vec<u64> {
    version
        .split('.')
        .map_while(|part| part.parse::<u64>().ok())
        .collect()
}

/// Whether the pin already matches the source: exactly, or — for a pin
/// naming only a major, as the action pins do — by major version.
fn is_current(pinned: &str, available: &str) -> bool {
    if pinned == available {
        return true;
    }
    !pinned.contains('.') && available.split('.').next() == Some(pinned)
}

#[cfg(test)]
mod tests {
    use super::{PinResult, Report, check_with, is_current, latest_version};

    /// One page of a Docker Hub tag list naming `tags`, with `next` as its
    /// link to the page after it.
    fn tag_page(next: Option<&str>, tags: &[&str]) -> Vec<u8> {
        serde_json::json!({
            "next": next,
            "results": tags.iter().map(|name| serde_json::json!({"name": name})).collect::<Vec<_>>(),
        })
        .to_string()
        .into_bytes()
    }

    const HUB: &str =
        "https://hub.docker.com/v2/namespaces/library/repositories/debian/tags?page_size=100";

    /// A newer numbered tag on a later page of a Docker Hub tag list wins,
    /// because the list's order does not establish the greatest version.
    #[test]
    fn a_docker_hub_tag_list_reads_a_newer_tag_on_a_later_page() {
        let checked = check_with("debian-image", "13.7", HUB, |url| match url {
            HUB => Some(tag_page(
                Some("https://hub.example/p2"),
                &["13.7-slim", "13-slim"],
            )),
            "https://hub.example/p2" => Some(tag_page(None, &["13.8-slim", "12.15-slim"])),
            _ => None,
        });
        assert_eq!(checked.result, "update-available");
        assert_eq!(checked.available.as_deref(), Some("13.8"));
    }

    /// A later page that fails leaves the greatest version unknown, so the
    /// pin reads as not observed, never as current.
    #[test]
    fn a_docker_hub_tag_list_with_a_failed_page_is_not_observed() {
        let checked = check_with("debian-image", "13.7", HUB, |url| {
            (url == HUB).then(|| tag_page(Some("https://hub.example/p2"), &["13.7-slim"]))
        });
        assert_eq!(checked.result, "source-unreachable");
        assert_eq!(checked.available, None);
    }

    /// A list that still names a next page at the bound is read only in
    /// part, so the pin reads as not observed, never as current.
    #[test]
    fn a_docker_hub_tag_list_past_the_bound_is_not_observed() {
        let checked = check_with("debian-image", "13.7", HUB, |url| {
            let page: u32 = url
                .strip_prefix("https://hub.example/p")
                .map_or(1, |page| page.parse().expect("a page number"));
            Some(tag_page(
                Some(&format!("https://hub.example/p{}", page + 1)),
                &["13.7-slim"],
            ))
        });
        assert_eq!(checked.result, "source-unreachable");
        assert_eq!(checked.available, None);
    }

    #[test]
    fn a_source_version_is_read_from_both_answer_shapes() {
        assert_eq!(
            latest_version(br#"{"crate":{"max_stable_version":"0.3.170"}}"#),
            Some("0.3.170".to_owned())
        );
        assert_eq!(
            latest_version(br#"{"tag_name":"v2.13.1"}"#),
            Some("2.13.1".to_owned())
        );
        assert_eq!(
            latest_version(br#"{"tag_name":"release-plz-v0.3.160"}"#),
            Some("0.3.160".to_owned())
        );
        assert_eq!(latest_version(b"not json"), None);
        assert_eq!(latest_version(br#"{"unrelated":true}"#), None);
    }

    /// The tags shape, for a project that publishes tags and cuts no
    /// releases. The greatest wins, not the first, because the endpoint
    /// promises no ordering; and 2.10 is above 2.9, not below it.
    #[test]
    fn a_tags_answer_reads_the_greatest_name() {
        assert_eq!(
            latest_version(br#"[{"name":"2.35.0"},{"name":"2.35.2"},{"name":"2.34.8"}]"#),
            Some("2.35.2".to_owned())
        );
        assert_eq!(
            latest_version(br#"[{"name":"2.9.0"},{"name":"2.10.0"}]"#),
            Some("2.10.0".to_owned())
        );
        assert_eq!(
            latest_version(br#"[{"name":"v1.2.3"}]"#),
            Some("1.2.3".to_owned())
        );
        assert_eq!(latest_version(b"[]"), None);
        assert_eq!(latest_version(br#"[{"sha":"abc"}]"#), None);
    }

    /// Docker Hub's tag list, for an image that cuts no forge release. Only
    /// a tag that opens with its version counts, read up to the variant
    /// suffix, so a dated or suite-named tag never passes for a version.
    #[test]
    fn a_docker_hub_tag_list_reads_the_greatest_numbered_tag() {
        assert_eq!(
            latest_version(
                br#"{"count":5,"next":null,"results":[{"name":"trixie-20261104-slim"},{"name":"13.7-slim"},{"name":"13-slim"},{"name":"12.15-slim"},{"name":"stable-slim"}]}"#
            ),
            Some("13.7".to_owned())
        );
        assert_eq!(
            latest_version(br#"{"results":[{"name":"13.10-slim"},{"name":"13.9-slim"}]}"#),
            Some("13.10".to_owned())
        );
        assert_eq!(
            latest_version(br#"{"results":[{"name":"stable-slim"}]}"#),
            None
        );
    }

    #[test]
    fn a_major_only_pin_is_current_within_its_major() {
        assert!(is_current("0.3.160", "0.3.160"));
        assert!(!is_current("0.3.160", "0.3.170"));
        assert!(is_current("4", "4.3.1"));
        assert!(!is_current("4", "5.0.0"));
    }

    /// The complete `rk.versions-check/2` shape, held by snapshot.
    #[test]
    fn the_versions_check_schema_snapshot_holds() {
        let report = Report {
            schema: "rk.versions-check/2",
            pins: vec![PinResult {
                tool: "release-plz".into(),
                pinned: "0.3.160".into(),
                result: "update-available",
                available: Some("0.3.170".into()),
                commit: Some("2eb1d8bcb770b4c48ccfaad919734b38b51958c9".into()),
                ref_class: Some("moving-minor-tag".into()),
                ref_result: Some("ref-unmoved"),
                ref_commit: Some("2eb1d8bcb770b4c48ccfaad919734b38b51958c9".into()),
            }],
        };
        assert_eq!(
            serde_json::to_string(&report).expect("a report serializes"),
            r#"{"schema":"rk.versions-check/2","pins":[{"tool":"release-plz","pinned":"0.3.160","result":"update-available","available":"0.3.170","commit":"2eb1d8bcb770b4c48ccfaad919734b38b51958c9","ref_class":"moving-minor-tag","ref_result":"ref-unmoved","ref_commit":"2eb1d8bcb770b4c48ccfaad919734b38b51958c9"}]}"#
        );
    }
}