ktstr 0.5.2

//! Kernel source acquisition: tarball download, git clone, local tree.
//!
//! Three entry points — [`download_tarball`], [`git_clone`], and
//! [`local_source`] — each return an [`AcquiredSource`] carrying the
//! source directory, cache key, and metadata the caller needs to
//! proceed to configuration and build.

use std::io::Read;
use std::num::NonZeroU32;
use std::path::{Path, PathBuf};
use std::sync::OnceLock;
use std::time::{Duration, Instant};

use anyhow::{Context, Result, anyhow};
use reqwest::blocking::Client;
use sha2::{Digest, Sha256};

/// Process-wide [`reqwest::blocking::Client`] lazily initialized on
/// first access via [`shared_client`]. Keeping a single `Client`
/// instance across the fetch-family reuses its TCP connection pool
/// and TLS session cache across repeated calls to the same host
/// within a CLI run. Cross-host fetches in the same run still
/// re-handshake because reqwest's connection pool keys on host.
static SHARED_CLIENT: OnceLock<Client> = OnceLock::new();

/// Connect-phase timeout for [`shared_client`]: bounds the time spent
/// in the TCP + TLS handshake before reqwest gives up on a peer.
/// Bounds the dead-route case — a CDN edge that accepts the SYN but
/// stalls the handshake, or a route that blackholes outright —
/// without putting any ceiling on the response body's streaming
/// duration once the connection is up.
///
/// No total request `.timeout()` is set: the same client serves both
/// short requests (directory listings, releases.json) and large
/// tarball streams ([`download_stable_tarball`],
/// [`download_rc_tarball`]), where a 130–180 MB compressed payload
/// over a slow uplink can take minutes of wall-clock to deliver.
/// Capping that with a per-request timeout would abort legitimate
/// downloads; bounding only the connect phase preserves the
/// dead-route guarantee while letting
/// the body stream as long as the upstream is making forward
/// progress.
const SHARED_CLIENT_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);

/// Return the process-wide shared [`reqwest::blocking::Client`]. First
/// call constructs it via `Client::builder()` with
/// [`SHARED_CLIENT_CONNECT_TIMEOUT`] applied; every subsequent call
/// returns a reference to the same instance. This helper is for
/// top-level CLI entries that want the default client.
///
/// Tests that need to verify a network round-trip (rather than a
/// cache hit) must NOT pass `shared_client()` to a cache-routed
/// helper (`cached_releases`, `cached_releases_with`,
/// [`fetch_latest_stable_version`], [`fetch_version_for_prefix`]) —
/// [`RELEASES_CACHE`] may already be populated by a peer test, in
/// which case the helper returns cached data and the network is
/// never touched. Construct a local `Client` and pass it to the
/// cache-routed helper to skip the cache; the pointer-equality gate
/// in [`cached_releases_with`] routes a non-singleton client to a
/// direct [`fetch_releases`] call against [`RELEASES_URL`] (the
/// production URL — the bypass skips the cache, NOT the URL). For
/// full URL injection (e.g. localhost mock server testing), call
/// either [`fetch_releases`] directly with the mock URL — see
/// `fetch_releases_against_localhost_mock_returns_parsed` — or use
/// the cache-aware seam [`cached_releases_with_url`], which routes
/// the non-singleton bypass branch through the supplied URL while
/// preserving the singleton/cache routing identical to
/// [`cached_releases_with`].
///
/// # Panics
///
/// Panics on the first call if `Client::builder().build()` fails to
/// construct a client. The documented failure modes are TLS backend
/// initialization (e.g. rustls/native-tls subsystem unreachable) and
/// are treated as setup bugs rather than runtime errors. The
/// `expect` here, rather than propagating the error, mirrors the
/// inherited behavior of `reqwest::blocking::Client::new()` (which
/// is itself an infallible wrapper around `builder().build().expect`).
pub fn shared_client() -> &'static Client {
    SHARED_CLIENT.get_or_init(|| {
        Client::builder()
            .connect_timeout(SHARED_CLIENT_CONNECT_TIMEOUT)
            .build()
            .expect("build shared reqwest client")
    })
}

/// Process-wide cache of the parsed `releases.json` payload.
/// Populated by [`cached_releases_with`] on its first successful
/// singleton-path fetch; every subsequent singleton call returns a
/// clone of the cached vector without re-issuing the HTTP request.
/// Lifetime matches the process — `releases.json` does not change
/// underneath a single CLI invocation, so a per-process cache
/// cannot serve stale data in any way the user would notice.
///
/// Failures are NOT cached: a transient kernel.org outage that
/// errors the first call must allow a later caller to retry, since
/// the underlying network condition may have cleared. Storing
/// `Vec<Release>` rather than `Result<Vec<Release>>` enforces this
/// at the type level — there's no way to populate the cache with
/// a failure.
///
/// Companion to [`SHARED_CLIENT`]: both amortize per-invocation
/// network cost across the resolve pipeline. Without this cache,
/// `cargo ktstr test --kernel 6.10..6.12 --kernel 6.14..6.16`
/// fetches `releases.json` twice — once per Range spec — under
/// the rayon par_iter that drives `resolve_kernel_set`. With
/// the cache the first Range to reach `expand_kernel_range`
/// populates the slot; the second observes the populated slot
/// and skips the network entirely.
static RELEASES_CACHE: OnceLock<Vec<Release>> = OnceLock::new();

/// Fetch `releases.json` via the process-wide [`shared_client`],
/// routing through [`RELEASES_CACHE`].
///
/// Thin wrapper for callers that don't already thread a `&Client`
/// — top-level CLI entries like [`crate::cli::expand_kernel_range`]
/// (under the rayon-driven `cargo ktstr` resolve pipeline) and
/// [`crate::cli::fetch_active_prefixes`] (the EOL-annotation pass).
/// Caching, race semantics, and fault-injection routing are all
/// documented on [`cached_releases_with`].
pub(crate) fn cached_releases() -> Result<Vec<Release>> {
    cached_releases_with(shared_client())
}

/// Pointer-equality against the [`OnceLock`]-backed
/// [`shared_client`] singleton is the correct predicate because
/// `shared_client()` returns a stable `&'static Client` address.
/// The [`cached_releases_with`] gate uses this predicate to
/// decide whether to consult [`RELEASES_CACHE`]: the singleton
/// hits the cache, every other (test-constructed) `Client`
/// bypasses it and exercises the underlying [`fetch_releases`]
/// path.
///
/// Caveat: `shared_client().clone()` produces a distinct
/// `Client` at a different address even though it shares the
/// singleton's connection pool via the inner `Arc`, so the
/// clone bypasses the cache. Always pass `shared_client()`
/// directly — never a clone — when cache routing is desired.
///
/// Side-effect-free when [`SHARED_CLIENT`] is uninitialized:
/// no client can equal a not-yet-allocated singleton, so we
/// return `false` without triggering `get_or_init` — tests
/// that pass a local `Client` before any production code path
/// has touched the singleton skip the construction entirely.
fn is_shared_client(client: &Client) -> bool {
    match SHARED_CLIENT.get() {
        Some(singleton) => std::ptr::eq(client, singleton),
        None => false,
    }
}

/// Unified cache-aware entry point for `releases.json`. Routes
/// the process-wide [`shared_client`] singleton through
/// [`RELEASES_CACHE`]; any other (test-constructed) `Client`
/// bypasses [`RELEASES_CACHE`] and calls [`fetch_releases`] with
/// [`RELEASES_URL`] directly — the cache is skipped but the
/// production URL is used.
///
/// Used by every in-file caller that already threads a `&Client`
/// — [`fetch_latest_stable_version`], [`fetch_version_for_prefix`],
/// [`latest_in_series`] — so production callers reuse
/// [`RELEASES_CACHE`] and tests still get cache-bypass via the
/// pointer-equality gate. [`cached_releases`] is the no-`Client`
/// wrapper for top-level CLI entries.
///
/// Tests that need URL injection on the bypass branch (e.g.
/// localhost mock server testing) call
/// [`cached_releases_with_url`] directly with their mock URL —
/// the URL-injectable form preserves identical routing
/// semantics. This wrapper is the production entry point and
/// pins the URL to [`RELEASES_URL`]; production code MUST go
/// through this wrapper. A singleton call with a non-RELEASES_URL
/// would otherwise populate [`RELEASES_CACHE`] with
/// non-production data and corrupt every later production
/// call — the singleton-path branch in
/// [`cached_releases_with_url`] guards against this in both
/// dev (`debug_assert!`) and release builds (fall back to
/// bypass), but routing every production call through this
/// wrapper makes the misuse impossible by construction.
/// Caching, race semantics, and the bypass-vs-cache routing
/// are fully documented on [`cached_releases_with_url`].
fn cached_releases_with(client: &Client) -> Result<Vec<Release>> {
    cached_releases_with_url(client, RELEASES_URL)
}

/// URL-injectable form of [`cached_releases_with`]. Production
/// always reaches this through the [`cached_releases_with`]
/// wrapper, which pins `url` to [`RELEASES_URL`]; the explicit
/// `url` parameter exists so the bypass-branch test can route
/// the non-singleton path through a localhost
/// [`std::net::TcpListener`]-backed mock instead of hitting real
/// kernel.org. Without this seam, the bypass test would either
/// (a) require a real network round-trip on every run, or
/// (b) accept a 5s timeout penalty on offline hosts to surface
/// `Err` as a bypass-confirmation signal — both costs the seam
/// eliminates.
///
/// Cache contract is identical to [`cached_releases_with`]:
/// non-singleton clients bypass [`RELEASES_CACHE`] and call
/// [`fetch_releases`] with `url`; the singleton routes through
/// the cache only when `url == RELEASES_URL` (consulting via
/// `OnceLock::get`, populating via `OnceLock::set` on miss). A
/// singleton call with a non-RELEASES_URL trips the
/// `debug_assert!` in dev builds and falls back to the bypass
/// behavior in release builds — fetches directly via `url`,
/// returns the result, never touches [`RELEASES_CACHE`]. The
/// cache only ever stores data fetched from the singleton +
/// RELEASES_URL combination, so a test that injects a mock URL
/// on either branch cannot pollute the production cache.
///
/// Failures are propagated without populating [`RELEASES_CACHE`],
/// so a transient kernel.org outage on the first call lets the
/// next caller retry. Storing `Vec<Release>` (not
/// `Result<Vec<Release>>`) enforces this at the type level.
///
/// Concurrent population on the singleton path is safe via the
/// `OnceLock::set` race: the loser's `set` returns `Err(clone)`
/// (the cloned vector that was passed in is moved back), the
/// returned `Err` is discarded via `let _ = …`, and the loser
/// returns its own original `fresh` vector. Both winner and
/// loser return content-equivalent data since both fetched the
/// same `releases.json`. Worst case under concurrent first
/// calls: both callers issue the network round-trip, only one
/// populates [`RELEASES_CACHE`]; every later call — from any
/// thread — observes the populated slot via the `get` fast-path
/// and skips the network.
fn cached_releases_with_url(client: &Client, url: &str) -> Result<Vec<Release>> {
    // Non-singleton clients bypass the cache (test fault injection).
    if !is_shared_client(client) {
        return fetch_releases(client, url);
    }
    // Cache-poison guard: the singleton path populates
    // RELEASES_CACHE on miss. A test author that mistakenly
    // passes a non-production URL with shared_client() would
    // fill the cache with non-production data and corrupt every
    // later production call (which reaches the cache via
    // get-fast-path). Catch the misuse at debug-build time —
    // production callers always thread RELEASES_URL through the
    // `cached_releases_with` wrapper, so the assertion is a
    // no-op for them; only a future test author wiring this
    // function up with shared_client() and a mock URL would trip
    // it.
    debug_assert!(
        url == RELEASES_URL,
        "cached_releases_with_url: shared_client() must use RELEASES_URL \
         to avoid RELEASES_CACHE pollution — got url={url:?}, expected \
         RELEASES_URL ({RELEASES_URL:?}). Tests that need URL injection \
         must pass a non-singleton Client (which takes the bypass branch \
         above and never touches the cache).",
    );
    // Release-build guard: `debug_assert!` is stripped in
    // optimized builds, so a non-RELEASES_URL on the singleton
    // path would otherwise reach the populate-on-miss path below
    // and persistently poison RELEASES_CACHE for every later
    // production caller. Mirror the bypass-branch behavior
    // (fetch directly, do not touch the cache) so the misuse
    // degrades to a slow per-call fetch instead of a permanently
    // wrong cache. The debug_assert above still fires loudly in
    // dev builds; this branch only catches the misuse that
    // slipped through to release.
    if url != RELEASES_URL {
        return fetch_releases(client, url);
    }
    if let Some(cached) = RELEASES_CACHE.get() {
        return Ok(cached.clone());
    }
    let fresh = fetch_releases(client, url)?;
    // Race-loss: `set` returns `Err(clone)` carrying back the
    // clone we passed in; we discard it and return the original
    // `fresh` below. See the rustdoc above for full semantics.
    let _ = RELEASES_CACHE.set(fresh.clone());
    Ok(fresh)
}

/// Downloaded/cloned kernel source ready for building.
#[non_exhaustive]
pub struct AcquiredSource {
    /// Path to the kernel source directory.
    pub source_dir: PathBuf,
    /// Cache key for this source (e.g. "6.14.2-tarball-x86_64-kc{kconfig_hash}").
    pub cache_key: String,
    /// Version string if known (e.g. "6.14.2", "6.15-rc3").
    pub version: Option<String>,
    /// How the source was acquired, with per-variant payload
    /// (git hash/ref for `Git`, source tree path and git hash for
    /// `Local`).
    pub kernel_source: crate::cache::KernelSource,
    /// Whether the source is a temporary directory that should be
    /// cleaned up after building.
    pub is_temp: bool,
    /// For local sources: whether the working tree is dirty.
    /// Dirty trees must not be cached.
    pub is_dirty: bool,
    /// For local sources: whether the source is an actual git
    /// repository. `true` when `gix::discover` succeeded and the
    /// crate could compute index + worktree dirty state; `false`
    /// for non-git source trees (tarball-extracted, rsync'd,
    /// hand-assembled) where dirty detection is impossible and
    /// the source is always cache-skipped pessimistically. Lets
    /// the cache-skip hint branch on whether `commit` / `stash`
    /// are actionable remediations (they aren't for non-git
    /// sources).
    ///
    /// For non-local sources (tarball, git clone) the field is
    /// set to `true` by convention — these paths are always
    /// `is_dirty = false`, so the cache-skip branch that reads
    /// `is_git` is never reached and the value is inert. Pinning
    /// to `true` (rather than leaving the field meaningless)
    /// keeps the invariant "is_git is meaningful only when
    /// is_dirty is true, but always set" so a future code path
    /// that reaches `is_git` outside the cache-skip context does
    /// not trip on an `is_git = false` under a known-good source.
    pub is_git: bool,
}

/// Target architecture string and boot image name.
pub fn arch_info() -> (&'static str, &'static str) {
    #[cfg(target_arch = "x86_64")]
    {
        ("x86_64", "bzImage")
    }
    #[cfg(target_arch = "aarch64")]
    {
        ("aarch64", "Image")
    }
}

/// Parse a version string into its major version for URL construction.
///
/// "6.14.2" -> 6, "6.15-rc3" -> 6.
fn major_version(version: &str) -> Result<u32> {
    let major_str = version
        .split('.')
        .next()
        .ok_or_else(|| anyhow!("invalid version: {version}"))?;
    major_str
        .parse::<u32>()
        .with_context(|| format!("invalid major version in {version}"))
}

/// Determine if a version string represents an RC release.
///
/// RC releases use a different URL pattern and gzip compression
/// (vs xz for stable).
fn is_rc(version: &str) -> bool {
    version.contains("-rc")
}

/// One (`moniker`, `version`) row from kernel.org's `releases.json`.
///
/// A named struct instead of a bare `(String, String)` tuple so every
/// call site reads its field by name (`r.moniker`, `r.version`) rather
/// than positional destructuring — the two strings are trivially
/// swappable at a tuple-destructure call site, and a silent swap
/// would mis-drive `is_skippable_release_moniker` while the
/// now-misnamed "moniker" string flows into `version_prefix`
/// downstream. Naming the fields removes that class of bug at the
/// type-checker level and shows up in IDE hints on every iteration
/// site.
///
/// Both fields are owned `String` (not `&str`) because the values are
/// parsed out of a `reqwest::Response` body whose lifetime ends when
/// `fetch_releases` returns; downstream callers iterate the vector
/// long after that borrow would dangle.
#[derive(Clone, Debug)]
pub(crate) struct Release {
    /// releases.json `moniker` field — stable / longterm / mainline /
    /// linux-next / etc. Consumed by
    /// [`is_skippable_release_moniker`] and by
    /// [`fetch_latest_stable_version`]'s stable/longterm filter.
    pub moniker: String,
    /// releases.json `version` field — e.g. `"6.14.2"`, `"6.15-rc3"`,
    /// `"6.16-rc2-next-20260420"`. Consumed by
    /// [`version_tuple`], [`patch_level`], and
    /// `cli::version_prefix`.
    pub version: String,
}

/// Is this releases.json moniker one that the version-resolution
/// pipeline should skip?
///
/// `linux-next` is a rolling integration branch whose version strings
/// carry a date suffix rather than a stable tag, so it does not fit
/// the major.minor.patch resolution model used by `latest_in_series`,
/// `fetch_version_for_prefix`, and `cli::fetch_active_prefixes`. The
/// release iteration in all three sites filters it out; this helper
/// is the single point of truth for that decision so a future moniker
/// that also warrants skipping can be added in one place.
pub(crate) fn is_skippable_release_moniker(moniker: &str) -> bool {
    moniker == "linux-next"
}

/// Find the latest version in the same major.minor series from releases.json.
///
/// Returns `Some("6.14.10")` for prefix `"6.14"` if that series exists in
/// releases.json. Returns `None` if the series is not found (EOL or invalid).
fn latest_in_series(client: &Client, version: &str) -> Option<String> {
    let prefix = {
        let parts: Vec<&str> = version.split('.').collect();
        if parts.len() >= 2 {
            format!("{}.{}", parts[0], parts[1])
        } else {
            return None;
        }
    };

    // Routes through [`RELEASES_CACHE`] for the singleton; see
    // [`cached_releases_with`] for the bypass gate.
    let releases = cached_releases_with(client).ok()?;
    let mut best: Option<(String, (u32, u32, u32))> = None;
    for r in &releases {
        if is_skippable_release_moniker(&r.moniker) {
            continue;
        }
        if !r.version.starts_with(&prefix) {
            continue;
        }
        if r.version.len() != prefix.len() && r.version.as_bytes()[prefix.len()] != b'.' {
            continue;
        }
        if let Some(tuple) = version_tuple(&r.version)
            && (best.is_none() || tuple > best.as_ref().unwrap().1)
        {
            best = Some((r.version.clone(), tuple));
        }
    }
    best.map(|(v, _)| v)
}

/// Build a user-facing error message for a version that was not found.
///
/// Suggests the latest version in the same major.minor series when
/// releases.json contains one.
fn version_not_found_msg(client: &Client, version: &str) -> String {
    let parts: Vec<&str> = version.split('.').collect();
    let prefix = if parts.len() >= 2 {
        format!("{}.{}", parts[0], parts[1])
    } else {
        version.to_string()
    };
    match latest_in_series(client, version) {
        Some(latest) if latest != version => {
            format!("version {version} not found. latest {prefix}.x: {latest}")
        }
        _ => format!("version {version} not found"),
    }
}

/// Reject responses where the server returned HTML instead of a binary
/// archive. Some CDN error pages return 200 with text/html.
fn reject_html_response(response: &reqwest::blocking::Response, url: &str) -> Result<()> {
    if let Some(ct) = response.headers().get(reqwest::header::CONTENT_TYPE)
        && let Ok(ct_str) = ct.to_str()
        && ct_str.contains("text/html")
    {
        anyhow::bail!(
            "download {url}: server returned HTML instead of tarball (URL may be invalid)"
        );
    }
    Ok(())
}

/// Print download size from Content-Length header if available.
///
/// `cli_label` prefixes the diagnostic line so the message matches the
/// binary the user invoked (`"ktstr"` vs `"cargo ktstr"`).
fn print_download_size(response: &reqwest::blocking::Response, url: &str, cli_label: &str) {
    if let Some(len) = response.content_length() {
        let mb = len as f64 / (1024.0 * 1024.0);
        eprintln!("{cli_label}: downloading {url} ({mb:.1} MB)");
    } else {
        eprintln!("{cli_label}: downloading {url}");
    }
}

/// Maximum tolerated stretch of "no body bytes received" before a
/// streaming download is declared stalled. Catches a TCP connection
/// that completed handshake (so connect_timeout doesn't fire) but
/// then silently stops delivering body data — a common CDN failure
/// mode where keepalive holds the socket open while the upstream
/// origin is unreachable. The 60s value is generous enough that a
/// real slow uplink delivering chunks every few seconds never
/// triggers it, but tight enough that a wedged connection surfaces
/// before the run's overall test timeout.
const DOWNLOAD_NO_PROGRESS_TIMEOUT: Duration = Duration::from_secs(60);

/// Streaming `Read` adapter for kernel tarball downloads.
///
/// Wraps the [`reqwest::blocking::Response`] body to do two things
/// the bare response cannot:
///
/// 1. **Body-progress watchdog.** Tracks `last_progress` (the
///    instant of the last successful read with `n > 0`) and errors
///    when more than [`DOWNLOAD_NO_PROGRESS_TIMEOUT`] elapses
///    between byte-producing reads. Without this, a CDN edge that
///    keepalives the socket but stops delivering body bytes would
///    leave the download blocked indefinitely (reqwest's per-read
///    timeout reset on every empty wakeup, and the connect-phase
///    timeout already passed during handshake). The check fires
///    BEFORE the inner `read()` so a stalled inner reader cannot
///    out-block the watchdog.
///
/// 2. **Streaming SHA-256.** Updates a [`Sha256`] hasher with every
///    byte that flows past, so the caller can verify the finalized
///    digest against an expected value (parsed out of
///    `sha256sums.asc`) without a second pass over the data. The
///    hasher only sees bytes that were actually consumed by the
///    decoder + tar extractor, which is the same set of bytes that
///    landed on disk — so a partial download that errored midway
///    produces a hash over only what we successfully streamed,
///    preventing false-positive verifications on truncated input.
///
/// Sits between [`reqwest::blocking::Response`] and the
/// decompression layer (`XzDecoder` / `GzDecoder`); both
/// decompressors expose `into_inner()` so the wrapper can be
/// recovered after extraction completes (see
/// [`Self::finalize`]).
struct DownloadStream<R: Read> {
    /// Underlying reqwest response body. Owned because `XzDecoder`
    /// and `GzDecoder` take ownership of their inner reader, so
    /// the wrapper must hold the response by value rather than by
    /// reference.
    inner: R,
    /// Running SHA-256 hasher updated on every byte-producing read.
    /// Consumed by [`DownloadStream::finalize`] (which takes `self`
    /// by value); the call site recovers the wrapper from inside
    /// the decoder + tar archive chain via `into_inner` before
    /// finalizing.
    hasher: Sha256,
    /// Total body bytes read so far. Surfaced in the watchdog
    /// error message so an operator triaging "no progress" can see
    /// how many bytes did arrive before the stall — distinguishing
    /// "connection dropped after a few bytes" from "connection
    /// dropped after most of the payload".
    bytes_total: u64,
    /// `Instant` of the last successful read with `n > 0`. Set at
    /// construction (not on first read) so a connection that wins
    /// the handshake but never delivers any body bytes still
    /// trips the watchdog after [`DOWNLOAD_NO_PROGRESS_TIMEOUT`]
    /// rather than waiting for an indeterminate pre-data window.
    last_progress: Instant,
    /// Tolerated stretch of zero-progress time. Pinned at
    /// construction from [`DOWNLOAD_NO_PROGRESS_TIMEOUT`]; held in
    /// the struct rather than read from the constant on every
    /// `read()` so a future per-call override (e.g. shorter
    /// timeouts in tests) lands without touching the watchdog
    /// logic.
    no_progress_timeout: Duration,
}

impl<R: Read> DownloadStream<R> {
    /// Construct a fresh streaming wrapper around `inner` with the
    /// production no-progress budget. `last_progress` is set to
    /// "now" so the watchdog clock starts at construction; the
    /// downstream decoder may take an indeterminate amount of time
    /// between construction and the first `read()`, but ANY actual
    /// progress resets the clock.
    fn new(inner: R) -> Self {
        Self {
            inner,
            hasher: Sha256::new(),
            bytes_total: 0,
            last_progress: Instant::now(),
            no_progress_timeout: DOWNLOAD_NO_PROGRESS_TIMEOUT,
        }
    }

    /// Consume the wrapper and return `(hex_digest, bytes_total)`.
    /// Lowercase hex matches the format kernel.org publishes in
    /// `sha256sums.asc`, so the caller can do a direct
    /// `eq_ignore_ascii_case` comparison without re-encoding.
    fn finalize(self) -> (String, u64) {
        (hex::encode(self.hasher.finalize()), self.bytes_total)
    }
}

impl<R: Read> Read for DownloadStream<R> {
    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
        // Watchdog gate: trip BEFORE delegating to the inner reader
        // so a stalled inner read does not get a fresh chance to
        // run after the no-progress window has already expired. The
        // wrapper cannot interrupt a `read()` that is currently
        // blocked in a syscall — that protection comes from the
        // per-request timeout configured via
        // `RequestBuilder::timeout` — but it can refuse to issue
        // the next call once the cumulative no-progress window
        // crosses the bound.
        let elapsed = self.last_progress.elapsed();
        if elapsed > self.no_progress_timeout {
            return Err(std::io::Error::new(
                std::io::ErrorKind::TimedOut,
                format!(
                    "download stalled: no body bytes for {}s after {} bytes received",
                    elapsed.as_secs(),
                    self.bytes_total,
                ),
            ));
        }
        match self.inner.read(buf) {
            Ok(0) => {
                // EOF: do NOT update last_progress — a 0-byte read
                // is not progress, and updating here would let a
                // decoder that polls past EOF reset the watchdog
                // indefinitely.
                Ok(0)
            }
            Ok(n) => {
                self.hasher.update(&buf[..n]);
                self.bytes_total += n as u64;
                self.last_progress = Instant::now();
                Ok(n)
            }
            Err(e) => Err(e),
        }
    }
}

/// Per-request body-stream timeout passed to
/// [`reqwest::blocking::RequestBuilder::timeout`] for tarball
/// downloads. The blocking client treats this as a per-`read()`
/// deadline (reset on every successful read), so it complements the
/// [`DownloadStream`] watchdog: reqwest's deadline kills a single
/// stalled syscall, and the watchdog observes the cumulative
/// no-progress window across multiple reads. Set generously
/// (5 minutes) because a slow but progressing connection can
/// legitimately take that long for a single read on a large CDN
/// chunk; the watchdog provides the tighter 60s no-progress bound.
const DOWNLOAD_REQUEST_READ_TIMEOUT: Duration = Duration::from_secs(300);

/// Total request timeout for [`fetch_stable_sha256sums`]: bounds
/// the wall-clock window for the single small-body GET that
/// retrieves the cleartext-signed checksum manifest. The body is
/// the `sha256sums.asc` cleartext block — typically a few KiB of
/// `<hash>  <filename>` lines plus a PGP signature trailer — so a
/// tight 30 s ceiling fits the realistic case (sub-second on a
/// healthy CDN edge) while still bounding the failure mode this
/// guards against: a stalled CDN that accepts the connection but
/// never delivers bytes. Without a per-request timeout the
/// shared client only carries [`SHARED_CLIENT_CONNECT_TIMEOUT`]
/// (handshake-only), so a stalled body read would hang the build
/// indefinitely. The caller treats any error from this function
/// as "no expected hash available" and downgrades verification
/// to a warning, so a 30 s timeout that fires on a hung CDN
/// surfaces as an unverified-but-progressing download rather
/// than a wedged build.
const SHA256SUMS_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);

/// Fetch the cleartext SHA-256 manifest published alongside stable
/// kernel tarballs at
/// `https://cdn.kernel.org/pub/linux/kernel/v{major}.x/sha256sums.asc`.
///
/// Returns the file body as a `String` on success. Any error
/// (transport failure, non-2xx status, non-UTF-8 body) is
/// propagated; the caller treats failure as "no expected hash
/// available" and downgrades verification to a warning.
fn fetch_stable_sha256sums(client: &Client, major: u32) -> Result<String> {
    let url = format!("https://cdn.kernel.org/pub/linux/kernel/v{major}.x/sha256sums.asc");
    tracing::info!(%url, "fetching kernel tarball sha256sums (requires network)");
    let response = client
        .get(&url)
        .timeout(SHA256SUMS_REQUEST_TIMEOUT)
        .send()
        .with_context(|| format!("fetch {url}"))?;
    if !response.status().is_success() {
        anyhow::bail!("fetch {url}: HTTP {}", response.status());
    }
    response
        .text()
        .with_context(|| format!("read body of {url}"))
}

/// Extract the SHA-256 hex digest for `target_filename` from the
/// cleartext-signed `sha256sums.asc` body.
///
/// kernel.org publishes `sha256sums.asc` as a PGP-cleartext-signed
/// document: a `-----BEGIN PGP SIGNED MESSAGE-----` header, an
/// optional `Hash:` line, a blank line, the cleartext body
/// (`<64-hex-chars>  <filename>` per line), then a
/// `-----BEGIN PGP SIGNATURE-----` block. We only need the
/// cleartext body — signature verification is a separate concern
/// (the user-facing instruction is "If no expected hash available,
/// log warning", not "require signature").
///
/// Returns `Some(lowercase_hex)` on first match. Returns `None` if
/// the target filename does not appear in the manifest (e.g. the
/// upstream rotated or removed the entry).
fn parse_sha256_for_file(manifest: &str, target_filename: &str) -> Option<String> {
    // Strip the PGP signature trailer if present. Everything after
    // the signature marker is binary noise that never contains
    // checksum lines.
    let body = manifest
        .split_once("-----BEGIN PGP SIGNATURE-----")
        .map(|(before, _)| before)
        .unwrap_or(manifest);
    for line in body.lines() {
        let line = line.trim();
        // sha256sum format: `<64-hex-chars><whitespace><filename>`.
        // Split on whitespace; require exactly two tokens and a
        // 64-char hex first token.
        let mut parts = line.split_whitespace();
        let Some(hash) = parts.next() else { continue };
        let Some(name) = parts.next() else { continue };
        if name != target_filename {
            continue;
        }
        if hash.len() != 64 || !hash.chars().all(|c| c.is_ascii_hexdigit()) {
            continue;
        }
        return Some(hash.to_ascii_lowercase());
    }
    None
}

/// Verify `actual_hex` against `expected_hex` (case-insensitive).
/// Returns `Ok(())` on match, `Err` with a diagnostic message on
/// mismatch. Pulled out of the call site so the comparison logic
/// has one home and the diagnostic carries both digests in lowercase
/// hex for direct copy-paste reuse.
fn verify_sha256(actual_hex: &str, expected_hex: &str, url: &str) -> Result<()> {
    if actual_hex.eq_ignore_ascii_case(expected_hex) {
        Ok(())
    } else {
        anyhow::bail!(
            "sha256 mismatch for {url}: expected {}, got {}. \
             If cdn.kernel.org updated this tarball in-place, \
             retry with --skip-sha256 to bypass verification.",
            expected_hex.to_ascii_lowercase(),
            actual_hex.to_ascii_lowercase(),
        );
    }
}

/// Resolve the expected SHA-256 digest for a stable tarball from
/// cdn.kernel.org's `sha256sums.asc` manifest.
///
/// Three outcomes:
/// - `Some(hex)` — manifest fetched and the entry for `tarball_name`
///   was parsed cleanly.
/// - `None` with no warning (only when `skip_sha256 = true`) —
///   operator explicitly opted out of verification; emits a single
///   security-sensitive bypass warning instead.
/// - `None` with a per-cause warning (manifest fetch failed, or
///   manifest fetched but entry missing) — best-effort fallback so
///   a transient cdn.kernel.org outage / schema drift does not
///   gate the whole download.
///
/// The fallback path is deliberately permissive: we trade strict
/// authentication for build availability. A network-path attacker
/// who can deny `sha256sums.asc` while serving a poisoned
/// `linux-{version}.tar.xz` could exploit this; operators who
/// require strict verification should pin the source via `--source`
/// or `--git` rather than the download path. The bypass warnings
/// surface on the operator's diagnostic stream so the lost
/// guarantee is visible to ops triage.
///
/// Extracted from [`download_stable_tarball`] so the gate is
/// directly unit-testable without mocking network calls — the
/// caller-supplied `client` reaches a `Client::get` only when
/// `skip_sha256 == false`, so a `skip_sha256 = true` test does not
/// need a configured `Client`.
fn resolve_expected_sha256(
    client: &Client,
    major: u32,
    tarball_name: &str,
    skip_sha256: bool,
) -> Option<String> {
    if skip_sha256 {
        tracing::warn!(
            tarball = %tarball_name,
            "--skip-sha256: bypassing checksum verification — the \
             downloaded tarball will not be authenticated against \
             cdn.kernel.org's sha256sums.asc manifest. Use only when \
             upstream has updated a tarball in-place and the manifest \
             is mismatched.",
        );
        return None;
    }
    // Best-effort expected-hash lookup: any failure (network,
    // status, parse, missing entry) downgrades to a warning so the
    // download still proceeds. The warning surfaces the cause so an
    // operator triaging "kernel build went weird" can spot that
    // verification was skipped.
    match fetch_stable_sha256sums(client, major) {
        Ok(manifest) => match parse_sha256_for_file(&manifest, tarball_name) {
            Some(hex) => Some(hex),
            None => {
                tracing::warn!(
                    tarball = %tarball_name,
                    "sha256sums.asc fetched but no entry for {tarball_name}; \
                     download will proceed without checksum verification. \
                     Pass --skip-sha256 to bypass the manifest fetch when \
                     the entry is known to be absent.",
                );
                None
            }
        },
        Err(err) => {
            tracing::warn!(
                error = %format!("{err:#}"),
                "failed to fetch sha256sums.asc; download will proceed \
                 without checksum verification. Pass --skip-sha256 to \
                 bypass the manifest fetch when the manifest is known \
                 to be unavailable.",
            );
            None
        }
    }
}

/// Download a stable kernel tarball (.tar.xz) from cdn.kernel.org.
///
/// Streams the body through a [`DownloadStream`] watchdog so a
/// stalled connection (no body bytes for
/// [`DOWNLOAD_NO_PROGRESS_TIMEOUT`]) surfaces as an error rather
/// than blocking indefinitely. Computes SHA-256 over the streamed
/// bytes and verifies against the digest in
/// `sha256sums.asc` for the matching `linux-{version}.tar.xz`
/// entry; if the manifest fetch / parse fails (transient outage,
/// schema drift, missing entry), logs a warning and continues
/// without verification rather than failing the whole download.
///
/// `skip_sha256 = true` bypasses the manifest fetch entirely and
/// emits a single bypass warning. Intended for the case where
/// cdn.kernel.org has updated a tarball in-place (a new point
/// release reusing the same URL) and the manifest is stale or
/// mismatched. Unverified downloads are a security-sensitive
/// fallback — the bypass warning surfaces the lost guarantee on
/// the operator's diagnostic stream.
fn download_stable_tarball(
    client: &Client,
    version: &str,
    dest_dir: &Path,
    cli_label: &str,
    skip_sha256: bool,
) -> Result<PathBuf> {
    let major = major_version(version)?;
    let tarball_name = format!("linux-{version}.tar.xz");
    let url = format!("https://cdn.kernel.org/pub/linux/kernel/v{major}.x/{tarball_name}");

    let expected_sha256 = resolve_expected_sha256(client, major, &tarball_name, skip_sha256);

    tracing::info!(%url, "downloading stable kernel tarball (requires network)");
    let response = client
        .get(&url)
        .timeout(DOWNLOAD_REQUEST_READ_TIMEOUT)
        .send()
        .with_context(|| format!("download {url}"))?;
    if !response.status().is_success() {
        if response.status() == reqwest::StatusCode::NOT_FOUND {
            anyhow::bail!("{}", version_not_found_msg(client, version));
        }
        anyhow::bail!("download {url}: HTTP {}", response.status());
    }
    reject_html_response(&response, &url)?;
    print_download_size(&response, &url, cli_label);

    eprintln!("{cli_label}: extracting tarball (xz)");
    // Stage extraction inside `dest_dir` (same filesystem) so the
    // final `fs::rename` into place is atomic and a verification
    // failure leaves `dest_dir` untouched. A bad mirror that serves
    // a wrong-version archive — or sneaks stray top-level entries
    // alongside `linux-{version}/` — gets caught after extraction
    // but before anything lands in `dest_dir`. The TempDir's Drop
    // sweeps every entry the malicious archive deposited.
    let staging =
        tempfile::TempDir::new_in(dest_dir).with_context(|| "create extraction staging dir")?;
    let stream = DownloadStream::new(response);
    let decoder = xz2::read::XzDecoder::new(stream);
    let mut archive = tar::Archive::new(decoder);
    archive
        .unpack(staging.path())
        .with_context(|| "extract tarball")?;

    // Recover the watchdog wrapper from inside the decoder/archive
    // chain to read the streaming digest. `into_inner` on tar +
    // xz2 each peel one layer of the chain. Done after a successful
    // unpack so we don't compute over a partial stream.
    let stream = archive.into_inner().into_inner();
    let (actual_hex, bytes_total) = stream.finalize();
    if let Some(expected) = expected_sha256.as_deref() {
        verify_sha256(&actual_hex, expected, &url)?;
        eprintln!("{cli_label}: sha256 verified ({bytes_total} bytes, hash {actual_hex})");
    } else if !skip_sha256 {
        // Skip path already emitted its bespoke bypass warning
        // before the download; firing again here under "no
        // expected sha256 available" would mislead — that wording
        // implies a fallback, not an explicit operator opt-out.
        tracing::warn!(
            url = %url,
            bytes = bytes_total,
            sha256 = %actual_hex,
            "no expected sha256 available for {url}; computed digest \
             {actual_hex} over {bytes_total} bytes is unverified",
        );
    }

    let source_dir = promote_staged_kernel_tree(&staging, dest_dir, version)?;
    Ok(source_dir)
}

/// Verify a kernel tarball's staged extraction contains exactly one
/// top-level entry named `linux-{version}/` and atomically rename it
/// into `dest_dir/linux-{version}`. Bails — leaving `dest_dir`
/// untouched — when the staging dir holds a stray entry, when the
/// expected inner directory is missing, or when the rename fails.
/// The caller's `TempDir` outlives this helper, so its Drop sweeps
/// any residual staging contents whether this returns Ok or Err.
fn promote_staged_kernel_tree(
    staging: &tempfile::TempDir,
    dest_dir: &Path,
    version: &str,
) -> Result<PathBuf> {
    let expected_name = format!("linux-{version}");
    let mut found_inner = false;
    for entry in std::fs::read_dir(staging.path()).with_context(|| "read staging dir entries")? {
        let entry = entry.with_context(|| "iterate staging dir entry")?;
        let name = entry.file_name();
        if name == std::ffi::OsStr::new(&expected_name) {
            found_inner = true;
        } else {
            anyhow::bail!(
                "tarball contains unexpected top-level entry {name:?}; \
                 expected only {expected_name}/"
            );
        }
    }
    if !found_inner {
        anyhow::bail!("expected directory {expected_name} after extraction");
    }
    let inner = staging.path().join(&expected_name);
    let source_dir = dest_dir.join(&expected_name);
    std::fs::rename(&inner, &source_dir)
        .with_context(|| format!("rename {} -> {}", inner.display(), source_dir.display()))?;
    Ok(source_dir)
}

/// Download an RC kernel tarball (.tar.gz) from git.kernel.org.
///
/// Streams the body through a [`DownloadStream`] watchdog so a
/// stalled connection surfaces as an error rather than blocking
/// indefinitely. RC tarballs are dynamically generated by gitweb
/// at request time and have no published `sha256sums` manifest, so
/// this path always logs a warning that the digest is unverified —
/// it is computed and surfaced for diagnostic value (operators can
/// pin it manually) but never compared to an authoritative source.
fn download_rc_tarball(
    client: &Client,
    version: &str,
    dest_dir: &Path,
    cli_label: &str,
) -> Result<PathBuf> {
    let url = format!("https://git.kernel.org/torvalds/t/linux-{version}.tar.gz");
    tracing::info!(%url, "downloading RC kernel tarball (requires network)");

    let response = client
        .get(&url)
        .timeout(DOWNLOAD_REQUEST_READ_TIMEOUT)
        .send()
        .with_context(|| format!("download {url}"))?;
    if response.status() == reqwest::StatusCode::NOT_FOUND {
        anyhow::bail!(
            "RC tarball not found: {url}\n  \
             RC releases are removed from git.kernel.org after the stable version ships."
        );
    }
    if !response.status().is_success() {
        anyhow::bail!("download {url}: HTTP {}", response.status());
    }
    reject_html_response(&response, &url)?;
    print_download_size(&response, &url, cli_label);

    eprintln!("{cli_label}: extracting tarball (gzip)");
    // Stage extraction inside `dest_dir` (same filesystem) so the
    // final atomic rename keeps `dest_dir` clean when a bad mirror
    // serves a wrong-version archive or sneaks stray top-level
    // entries past the archive boundary. RC tarballs have no
    // upstream sha256 manifest, so structural verification is the
    // only defence against a hostile gitweb response.
    let staging =
        tempfile::TempDir::new_in(dest_dir).with_context(|| "create extraction staging dir")?;
    let stream = DownloadStream::new(response);
    let decoder = flate2::read::GzDecoder::new(stream);
    let mut archive = tar::Archive::new(decoder);
    archive
        .unpack(staging.path())
        .with_context(|| "extract tarball")?;

    // Surface the streamed digest as a warning. RC tarballs have
    // no upstream manifest, so verification is impossible — but
    // emitting the hash gives an operator a value they can
    // capture for offline pinning if they want to detect drift on
    // re-fetch.
    let stream = archive.into_inner().into_inner();
    let (actual_hex, bytes_total) = stream.finalize();
    tracing::warn!(
        url = %url,
        bytes = bytes_total,
        sha256 = %actual_hex,
        "no expected sha256 available for {url} (RC tarballs are \
         dynamically generated by git.kernel.org and have no \
         published manifest); computed digest {actual_hex} over \
         {bytes_total} bytes is unverified",
    );

    let source_dir = promote_staged_kernel_tree(&staging, dest_dir, version)?;
    Ok(source_dir)
}

/// Download a kernel tarball (stable or RC) and extract it.
///
/// `cli_label` prefixes diagnostic status output (e.g. `"ktstr"` or
/// `"cargo ktstr"`).
///
/// `skip_sha256` propagates to [`download_stable_tarball`] only —
/// stable tarballs publish a `sha256sums.asc` manifest the flag
/// bypasses. RC tarballs (`download_rc_tarball`) have no published
/// manifest so verification is impossible regardless of the flag;
/// the RC path always runs unverified and emits its own warning,
/// so `skip_sha256` is a no-op on the RC arm. `--source` and
/// `--git` callers do not reach this function at all.
pub fn download_tarball(
    client: &Client,
    version: &str,
    dest_dir: &Path,
    cli_label: &str,
    skip_sha256: bool,
) -> Result<AcquiredSource> {
    let (arch, _) = arch_info();
    let source_dir = if is_rc(version) {
        download_rc_tarball(client, version, dest_dir, cli_label)?
    } else {
        download_stable_tarball(client, version, dest_dir, cli_label, skip_sha256)?
    };

    Ok(AcquiredSource {
        source_dir,
        cache_key: format!("{version}-tarball-{arch}-kc{}", crate::cache_key_suffix()),
        version: Some(version.to_string()),
        kernel_source: crate::cache::KernelSource::Tarball,
        is_temp: true,
        is_dirty: false,
        is_git: true,
    })
}

/// Parse the patch level from a kernel version string.
/// "6.12.8" → Some(8), "7.0" → Some(0), "abc" → None.
fn patch_level(version: &str) -> Option<u32> {
    let parts: Vec<&str> = version.split('.').collect();
    match parts.len() {
        2 => Some(0), // "7.0" has patch level 0
        3 => parts[2].parse().ok(),
        _ => None,
    }
}

/// Production URL for `releases.json`. Tests call [`fetch_releases`] directly with a localhost mock URL.
pub(crate) const RELEASES_URL: &str = "https://www.kernel.org/releases.json";

/// Fetch `releases.json` from `url` and return a vector of
/// [`Release`] records. Issues an HTTP GET unconditionally — no
/// cache consultation.
///
/// Production callers reach this function via
/// [`cached_releases_with`] (or [`cached_releases`]) which pass
/// [`RELEASES_URL`]; the cache helper only invokes
/// `fetch_releases` on a cache miss for the singleton path or on
/// the bypass branch for non-singleton clients. Tests that need
/// to exercise the underlying GET directly — without the cache
/// layer — call this function with a locally-constructed `Client`
/// and a localhost URL pointed at a TcpListener-backed mock that
/// returns canned `releases.json` content.
pub(crate) fn fetch_releases(client: &Client, url: &str) -> Result<Vec<Release>> {
    tracing::info!(%url, "fetching kernel.org releases index (requires network)");
    let response = client
        .get(url)
        .send()
        .with_context(|| format!("fetch {url}"))?;
    if !response.status().is_success() {
        anyhow::bail!("fetch {url}: HTTP {}", response.status());
    }
    let body = response.text().with_context(|| "read response body")?;
    parse_releases_body(&body)
}

fn parse_releases_body(body: &str) -> Result<Vec<Release>> {
    let json: serde_json::Value =
        serde_json::from_str(body).with_context(|| "parse releases.json")?;
    let releases = json
        .get("releases")
        .and_then(|r| r.as_array())
        .ok_or_else(|| anyhow!("releases.json: missing releases array"))?;
    let input_rows = releases.len();
    let parsed: Vec<Release> = releases
        .iter()
        .filter_map(|r| {
            let moniker = r.get("moniker")?.as_str()?;
            let version = r.get("version")?.as_str()?;
            Some(Release {
                moniker: moniker.to_string(),
                version: version.to_string(),
            })
        })
        .collect();
    // Per-row tolerance: a corrupt row is silently dropped via the
    // filter_map `?` chain so a single bad entry does not abort the
    // whole fetch (see `fetch_releases_row_missing_moniker_drops_row`
    // and siblings). The drop is also a hazard: the truncated vector
    // gets cached in [`RELEASES_CACHE`] for the rest of the process
    // lifetime via the singleton path, so a transient malformed row
    // at fetch time persists as a partial snapshot for every later
    // cache-hit caller. Surface the drop count so an operator
    // tailing logs sees that releases.json arrived partial — without
    // this, the symptom (a missing version on resolve) is invisible
    // until it propagates as "version not found" elsewhere.
    let dropped = input_rows - parsed.len();
    if dropped > 0 {
        tracing::warn!(
            input_rows,
            parsed_rows = parsed.len(),
            dropped,
            "releases.json: dropped {dropped} of {input_rows} row(s) \
             missing moniker/version (or non-string values); cached \
             snapshot will reflect this for the process lifetime"
        );
    }
    Ok(parsed)
}

/// Fetch the latest stable kernel version from kernel.org.
///
/// Selects from the `releases` array (moniker "stable" or "longterm"),
/// requiring patch version >= 8 to avoid brand-new major versions
/// that may have build issues on CI runners.
///
/// When `client` is the process-wide [`shared_client`] singleton,
/// routes through [`RELEASES_CACHE`]; other clients bypass the
/// cache via pointer-equality and exercise [`fetch_releases`]
/// directly — see [`cached_releases_with`] for details.
///
/// `cli_label` prefixes diagnostic status output (e.g. `"ktstr"` or
/// `"cargo ktstr"`).
pub fn fetch_latest_stable_version(client: &Client, cli_label: &str) -> Result<String> {
    eprintln!("{cli_label}: fetching latest kernel version");
    let releases = cached_releases_with(client)?;

    let mut best: Option<&str> = None;
    for r in &releases {
        if r.moniker != "stable" && r.moniker != "longterm" {
            continue;
        }
        if patch_level(&r.version).unwrap_or(0) < 8 {
            continue;
        }
        // Pick the first matching release — releases.json is ordered
        // newest first, so the first stable with patch >= 8 is the best.
        best = Some(r.version.as_str());
        break;
    }

    let version =
        best.ok_or_else(|| anyhow!("no stable kernel with patch >= 8 found in releases.json"))?;
    eprintln!("{cli_label}: latest stable kernel: {version}");
    Ok(version.to_string())
}

/// Parse a version string into numeric components for comparison.
/// "6.14.2" → Some((6, 14, 2)), "6.14" → Some((6, 14, 0)),
/// "7.0" → Some((7, 0, 0)). Returns None for unparseable versions.
fn version_tuple(version: &str) -> Option<(u32, u32, u32)> {
    let parts: Vec<&str> = version.split('.').collect();
    match parts.len() {
        2 => {
            let major = parts[0].parse().ok()?;
            let minor = parts[1].parse().ok()?;
            Some((major, minor, 0))
        }
        3 => {
            let major = parts[0].parse().ok()?;
            let minor = parts[1].parse().ok()?;
            let patch = parts[2].parse().ok()?;
            Some((major, minor, patch))
        }
        _ => None,
    }
}

/// Return true when `s` is a kernel major.minor prefix like
/// `"6.14"` (as opposed to a full patch version `"6.14.2"` or an rc
/// tag `"6.15-rc3"`). Callers use this to decide whether the input
/// needs prefix resolution via [`fetch_version_for_prefix`].
///
/// Accepts any string with fewer than 2 dots and no `-rc` substring,
/// so `"7"` (single-segment) and `""` both return true. This matches
/// the historical inline check used by kernel-build dispatchers.
pub fn is_major_minor_prefix(s: &str) -> bool {
    s.matches('.').count() < 2 && !s.contains("-rc")
}

/// Resolve the highest version matching a prefix.
///
/// E.g., "6.12" → "6.12.81", "6" → "6.19.12" (highest 6.x.y).
///
/// Scans all monikers in releases.json except linux-next. If no
/// match is found (EOL series), fetches the cdn.kernel.org directory
/// listing to find the highest patch version with a tarball.
///
/// When `client` is the process-wide [`shared_client`] singleton,
/// routes through [`RELEASES_CACHE`]; other clients bypass the
/// cache via pointer-equality and exercise [`fetch_releases`]
/// directly — see [`cached_releases_with`] for details. Cache
/// scope is releases.json only; the EOL-series directory-listing
/// fallback in [`probe_latest_patch`] always hits the network.
///
/// `cli_label` prefixes diagnostic status output (e.g. `"ktstr"` or
/// `"cargo ktstr"`).
pub fn fetch_version_for_prefix(client: &Client, prefix: &str, cli_label: &str) -> Result<String> {
    eprintln!("{cli_label}: fetching latest {prefix}.x kernel version");
    let releases = cached_releases_with(client)?;

    let mut best: Option<(&str, (u32, u32, u32))> = None;
    for r in &releases {
        if is_skippable_release_moniker(&r.moniker) {
            continue;
        }
        if !r.version.starts_with(prefix) {
            continue;
        }
        if r.version.len() != prefix.len() && r.version.as_bytes()[prefix.len()] != b'.' {
            continue;
        }
        let Some(tuple) = version_tuple(&r.version) else {
            continue;
        };
        if best.is_none() || tuple > best.unwrap().1 {
            best = Some((r.version.as_str(), tuple));
        }
    }

    if let Some((version, _)) = best {
        eprintln!("{cli_label}: latest {prefix}.x kernel: {version}");
        return Ok(version.to_string());
    }

    eprintln!("{cli_label}: {prefix}.x not in releases.json (EOL series), probing cdn.kernel.org");
    probe_latest_patch(client, prefix, cli_label)
}

/// Find the latest patch version for an EOL series by fetching the
/// CDN directory listing.
///
/// GETs the `v{major}.x/` directory index from cdn.kernel.org and
/// extracts `linux-{prefix}.{patch}.tar.xz` filenames to find the
/// highest patch. One GET replaces the former parallel-HEAD probe
/// which failed in CI environments that block or mishandle HEAD
/// requests to the CDN.
fn probe_latest_patch(client: &Client, prefix: &str, cli_label: &str) -> Result<String> {
    let major = major_version(prefix)?;
    let url = format!("https://cdn.kernel.org/pub/linux/kernel/v{major}.x/");
    eprintln!("{cli_label}: fetching directory listing from {url}");
    let body = client
        .get(&url)
        .send()
        .with_context(|| format!("GET {url}"))?
        .error_for_status()
        .with_context(|| format!("GET {url}"))?
        .text()
        .with_context(|| format!("reading body from {url}"))?;

    let needle = format!("linux-{prefix}.");
    let mut best_patch: Option<u32> = None;
    for line in body.lines() {
        let Some(pos) = line.find(&needle) else {
            continue;
        };
        let after = &line[pos + needle.len()..];
        let Some(dot) = after.find(".tar.xz") else {
            continue;
        };
        let patch_str = &after[..dot];
        if let Ok(patch) = patch_str.parse::<u32>()
            && best_patch.is_none_or(|b| patch > b)
        {
            best_patch = Some(patch);
        }
    }

    match best_patch {
        Some(patch) => {
            let version = format!("{prefix}.{patch}");
            eprintln!("{cli_label}: latest {prefix}.x kernel (from cdn listing): {version}");
            Ok(version)
        }
        None => {
            anyhow::bail!(
                "no tarball matching {prefix}.x found in cdn.kernel.org \
                 directory listing at {url}"
            );
        }
    }
}

/// Clone a git repository with shallow depth.
///
/// `cli_label` prefixes diagnostic status output (e.g. `"ktstr"` or
/// `"cargo ktstr"`).
pub fn git_clone(
    url: &str,
    git_ref: &str,
    dest_dir: &Path,
    cli_label: &str,
) -> Result<AcquiredSource> {
    let (arch, _) = arch_info();
    eprintln!("{cli_label}: cloning {url} (ref: {git_ref}, depth: 1)");

    let clone_dir = dest_dir.join("linux");

    let mut prep = gix::prepare_clone(url, &clone_dir)
        .with_context(|| "prepare clone")?
        .with_shallow(gix::remote::fetch::Shallow::DepthAtRemote(
            NonZeroU32::new(1).expect("1 is nonzero"),
        ))
        .with_ref_name(Some(git_ref))
        .with_context(|| "set ref name")?;

    let (mut checkout, _outcome) = prep
        .fetch_then_checkout(
            gix::progress::Discard,
            &std::sync::atomic::AtomicBool::new(false),
        )
        .with_context(|| "clone fetch")?;

    let (_repo, _outcome) = checkout
        .main_worktree(
            gix::progress::Discard,
            &std::sync::atomic::AtomicBool::new(false),
        )
        .with_context(|| "checkout")?;

    let repo = gix::open(&clone_dir).with_context(|| "open cloned repo")?;
    let head = repo.head_id().with_context(|| "read HEAD")?;
    let short_hash = format!("{}", head).chars().take(7).collect::<String>();

    let cache_key = format!(
        "{git_ref}-git-{short_hash}-{arch}-kc{}",
        crate::cache_key_suffix()
    );

    Ok(AcquiredSource {
        source_dir: clone_dir,
        cache_key,
        version: None,
        kernel_source: crate::cache::KernelSource::Git {
            git_hash: Some(short_hash),
            git_ref: Some(git_ref.to_string()),
        },
        is_temp: true,
        is_dirty: false,
        is_git: true,
    })
}

/// Use a local kernel source tree.
///
/// Dirty detection uses gix `tree_index_status` (HEAD-vs-index) and
/// `status().into_index_worktree_iter()` (index-vs-worktree) to check
/// for modifications to tracked files. Submodule checks are skipped
/// entirely. Untracked files do not affect the dirty flag.
///
/// When the tree is dirty, the HEAD commit does not describe the
/// source actually being built, so `git_hash` is dropped — no
/// commit identifies a dirty worktree. `is_dirty=true` carries that
/// fact forward; callers (see [`crate::cli`]) use it to bypass the
/// kernel cache entirely.
///
/// No diagnostic output: all operator-visible messaging for a
/// local source is routed through `kernel_build_pipeline`'s
/// cache-skip hint (`DIRTY_TREE_CACHE_SKIP_HINT` /
/// `NON_GIT_TREE_CACHE_SKIP_HINT`), which has the full context
/// to emit a single informational line rather than two redundant
/// warnings. Sibling entries (`download_tarball`, `git_clone`)
/// still take a `cli_label` because they genuinely print
/// progress lines — `local_source` does not.
pub fn local_source(source_path: &Path) -> Result<AcquiredSource> {
    let (arch, _) = arch_info();

    if !source_path.is_dir() {
        anyhow::bail!("{}: not a directory", source_path.display());
    }

    let canonical = source_path
        .canonicalize()
        .with_context(|| format!("canonicalize {}", source_path.display()))?;

    let LocalSourceState {
        short_hash,
        is_dirty,
        is_git,
    } = inspect_local_source_state(&canonical)?;

    // User .config is folded into the cache key so two builds of the
    // same HEAD with different `.config` files do NOT collide on the
    // same key — see [`config_hash_for_key`] for the encoding.
    // Read at `local_source` time (rather than at the post-build
    // store site) so cache LOOKUP and cache STORE see the same key.
    let user_config_hash = config_hash_for_key(&canonical);

    let cache_key =
        compose_local_cache_key(arch, &short_hash, &canonical, user_config_hash.as_deref());

    Ok(AcquiredSource {
        source_dir: canonical.clone(),
        cache_key,
        version: None,
        kernel_source: crate::cache::KernelSource::Local {
            source_tree_path: Some(canonical),
            git_hash: short_hash,
        },
        is_temp: false,
        is_dirty,
        is_git,
    })
}

/// Result of [`inspect_local_source_state`] — git hash and dirty/git
/// classification of a canonical source-tree path. Pulled out of
/// [`local_source`] so the post-build dirty re-check (a second call
/// from [`crate::cli::kernel_build_pipeline`]) reuses the exact same
/// gix path.
#[derive(Debug, Clone)]
pub struct LocalSourceState {
    /// HEAD short hash (7 chars). `None` when the tree is dirty
    /// (HEAD doesn't describe the actual source) or non-git (no
    /// HEAD at all). Mirrors the `git_hash` field on
    /// [`AcquiredSource::kernel_source`] for [`crate::cache::KernelSource::Local`].
    pub short_hash: Option<String>,
    /// Tracked-file dirt: HEAD-vs-index disagreement OR
    /// index-vs-worktree disagreement. Always `true` for non-git
    /// trees (dirty detection is impossible without git, so the
    /// pessimistic stance is dirty).
    pub is_dirty: bool,
    /// `true` when `gix::discover` succeeded (the tree is a git
    /// repo); `false` otherwise. Lets the cache-skip hint branch
    /// on whether `commit` / `stash` is actionable.
    pub is_git: bool,
}

/// Inspect a canonical source-tree path for git hash + dirty state.
///
/// Submodule checks are skipped (false positives on kernel trees
/// with uninitialized submodules). The non-git arm returns
/// `(None, true, false)` so the caller's cache-skip hint can
/// distinguish "dirty git repo" from "not a git repo at all".
///
/// Called twice per build by [`crate::cli::kernel_build_pipeline`]:
/// once at acquire time (via [`local_source`]) and again after
/// `make` returns to detect mid-build worktree edits, branch flips,
/// or commits that would otherwise let a racing-write build land in
/// the cache under a stale identity. Both calls share the same gix
/// path so the post-build comparison is apples-to-apples.
///
/// Non-atomic against concurrent git operations: the probe runs
/// six sequential gix calls (`discover` → `head_id` → `head_tree`
/// → `index_or_empty` → `tree_index_status` → `status`), each a
/// separate filesystem read with no transactional bracket. A
/// concurrent `git commit`, `git add`, or worktree write between
/// any two calls can produce internally-inconsistent results —
/// e.g. `head_id` reads commit C0, a peer commit lands C1, then
/// `head_tree` reads C1's root tree and the diff against the
/// post-add index reports unexpected dirt. Git itself serializes
/// its own writes via per-resource lockfiles under `.git/`
/// (`index.lock` for staging operations, `HEAD.lock` and
/// `refs/heads/<branch>.lock` for ref updates), so peer `git`
/// processes wait on whichever lockfile their operation touches;
/// the genuinely-unsynchronized class is worktree-only writes
/// (autoformatter, IDE-on-save) which the index-worktree status
/// step catches regardless of timing.
///
/// The disposition is intentionally pessimistic so inconsistency is
/// safe: any `Err` propagates to the caller, which treats it as a
/// rebuild signal (`MidWaitState::ProbeFailed` in the mid-wait
/// caller); any spurious dirty signal falls into DirtyEdit /
/// HashAdvanced, both forcing a rebuild. The cost of a false-
/// positive rebuild is one extra `make`; the cost of a false-
/// negative would be a cache slot keyed on a HEAD that no longer
/// describes the source — the asymmetry is the reason for the
/// pessimistic disposition. Callers should treat the returned
/// state as a best-effort approximation of probe-time, not an
/// instantaneous snapshot.
pub fn inspect_local_source_state(canonical: &Path) -> Result<LocalSourceState> {
    let (short_hash, is_dirty, is_git) = match gix::discover(canonical) {
        Ok(repo) => {
            let head = repo.head_id().with_context(|| "read HEAD")?;
            let short_hash = format!("{}", head).chars().take(7).collect::<String>();

            // tree_index_status compares a TREE id against the index;
            // the HEAD commit id is not itself a tree, so peel HEAD
            // to its root tree before diffing or the diff silently
            // returns an error and index dirt goes undetected.
            let head_tree = repo.head_tree().with_context(|| "read HEAD tree")?;
            let head_tree_id = head_tree.id;

            // Check HEAD-vs-index for tracked file changes.
            let mut index_dirty = false;
            let index = repo.index_or_empty().with_context(|| "open index")?;
            let _ = repo.tree_index_status(
                &head_tree_id,
                &index,
                None,
                gix::status::tree_index::TrackRenames::Disabled,
                |_, _, _| {
                    index_dirty = true;
                    Ok::<_, std::convert::Infallible>(std::ops::ControlFlow::Break(()))
                },
            );

            // Check index-vs-worktree for modified tracked files,
            // skipping submodules entirely (Ignore::All).
            let worktree_dirty = if !index_dirty {
                repo.status(gix::progress::Discard)
                    .with_context(|| "status")?
                    .index_worktree_rewrites(None)
                    .index_worktree_submodules(gix::status::Submodule::Given {
                        ignore: gix::submodule::config::Ignore::All,
                        check_dirty: false,
                    })
                    .index_worktree_options_mut(|opts| {
                        opts.dirwalk_options = None;
                    })
                    .into_index_worktree_iter(Vec::new())
                    .map(|mut iter| iter.next().is_some())
                    .unwrap_or(false)
            } else {
                false
            };

            let is_dirty = index_dirty || worktree_dirty;
            // Drop the HEAD hash when dirty — the commit does not
            // describe the actual source being built, so publishing
            // it via git_hash / cache_key would misidentify the
            // build input.
            let hash = if is_dirty { None } else { Some(short_hash) };
            (hash, is_dirty, true)
        }
        Err(_) => {
            // The downstream kernel_build_pipeline (cli::kernel_build_pipeline)
            // emits `NON_GIT_TREE_CACHE_SKIP_HINT` — a single
            // informational line that names both the cause and the
            // remediation paths — once the is_dirty=true branch
            // decides to skip the cache. Emitting a second
            // "not a git repository" warning here duplicated that
            // content for every non-git `--source` run. The
            // `(None, true, false)` tuple silently communicates
            // the non-git state to the cache-skip decision site;
            // no separate stderr line is needed on this path.
            (None, true, false)
        }
    };
    Ok(LocalSourceState {
        short_hash,
        is_dirty,
        is_git,
    })
}

/// Compose the cache key for a local source given its arch, optional
/// HEAD short hash, canonical source path, and optional user
/// `.config` hash.
///
/// Three shapes:
/// - `local-{hash7}-{arch}-kc{suffix}` — clean git tree, no user
///   `.config` (plain `make defconfig` path or no config file yet)
/// - `local-{hash7}-{arch}-cfg{user_config}-kc{suffix}` — clean git
///   tree with a user `.config` whose hash differs from `defconfig`
/// - `local-unknown-{path_hash}-{arch}-kc{suffix}` — dirty / non-git
///   tree (HEAD does not describe the source; the path-derived
///   crc32 salt keeps two distinct dirty trees from colliding on the
///   same `local-unknown-...` slot)
///
/// `path_hash` is the full 8-char (32-bit) lowercase-hex CRC32 of
/// the canonical source-path bytes. CRC32 keeps the per-path
/// disambiguator stable across runs without pulling in a
/// crypto-grade hash for what is fundamentally a slot disambiguator.
///
/// `user_config_hash` is `None` whenever the source tree has no
/// `.config` file yet (the build will run `make defconfig` and
/// produce one). This collapses the user-config branch back into the
/// hash-only key so a fresh checkout's first build still hits a
/// later cache lookup keyed without the cfg segment.
pub fn compose_local_cache_key(
    arch: &str,
    short_hash: &Option<String>,
    canonical: &Path,
    user_config_hash: Option<&str>,
) -> String {
    let suffix = crate::cache_key_suffix();
    match short_hash {
        Some(hash) => match user_config_hash {
            Some(cfg) => format!("local-{hash}-{arch}-cfg{cfg}-kc{suffix}"),
            None => format!("local-{hash}-{arch}-kc{suffix}"),
        },
        None => {
            let path_hash = canonical_path_hash(canonical);
            format!("local-unknown-{path_hash}-{arch}-kc{suffix}")
        }
    }
}

/// CRC32 of the canonical source-path bytes, lowercase hex
/// (full 8-char width — the entire 32-bit value). Disambiguates
/// `local-unknown-...` cache keys and per-source-tree lockfile
/// names across distinct dirty / non-git source trees so two
/// parallel `cargo ktstr test --kernel ./linux-a` and
/// `--kernel ./linux-b` runs can't write each other's vmlinux into
/// the same cache slot or share a single source-tree flock.
///
/// Full 32 bits (8 hex chars) of CRC32 keep collision risk
/// negligible against the practical population (handful of source
/// trees per host) while staying human-readable. The earlier
/// 6-char (24-bit) form left ~6× the collision surface for the
/// same key shape; truncation served no purpose other than visual
/// brevity. Path bytes are taken via `OsStr::as_encoded_bytes` so
/// a non-UTF-8 component (rare on Linux but possible) doesn't lose
/// entropy through a UTF-8 lossy conversion.
pub(crate) fn canonical_path_hash(canonical: &Path) -> String {
    let bytes = canonical.as_os_str().as_encoded_bytes();
    format!("{:08x}", crc32fast::hash(bytes))
}

/// Read `<canonical>/.config` and return its CRC32 as a lowercase
/// hex string suitable for embedding in the cache key. Returns
/// `None` when no `.config` exists (a fresh tree before the build
/// runs `make defconfig`).
///
/// Distinct from the `config_hash` written into [`crate::cache::KernelMetadata`]
/// at store time — that records the FINAL `.config` after
/// configuration runs, for diagnostic display in `kernel list`.
/// This helper records the PRE-BUILD `.config` so the cache key
/// reflects what the operator's tree currently has on disk; the
/// same `.config` content always maps to the same key, even if the
/// downstream `make olddefconfig` step elaborates additional
/// defaults.
fn config_hash_for_key(canonical: &Path) -> Option<String> {
    let config_path = canonical.join(".config");
    let data = std::fs::read(&config_path).ok()?;
    Some(format!("{:08x}", crc32fast::hash(&data)))
}

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

    // -- arch_info --

    #[test]
    fn fetch_arch_info_returns_known_arch() {
        let (arch, image) = arch_info();
        assert!(
            (arch == "x86_64" && image == "bzImage") || (arch == "aarch64" && image == "Image"),
            "unexpected arch/image: {arch}/{image}"
        );
    }

    // -- is_major_minor_prefix --

    #[test]
    fn is_major_minor_prefix_accepts_two_segment() {
        assert!(is_major_minor_prefix("6.14"));
        assert!(is_major_minor_prefix("7.0"));
    }

    #[test]
    fn is_major_minor_prefix_rejects_patch_version() {
        assert!(!is_major_minor_prefix("6.14.2"));
        assert!(!is_major_minor_prefix("5.4.0"));
    }

    #[test]
    fn is_major_minor_prefix_rejects_rc_tag() {
        assert!(!is_major_minor_prefix("6.15-rc3"));
        assert!(!is_major_minor_prefix("6.14-rc1"));
    }

    #[test]
    fn is_major_minor_prefix_historical_edge_cases() {
        // Historical behavior: accepts single-segment and empty inputs.
        // Callers are expected to gate upstream.
        assert!(is_major_minor_prefix("7"));
        assert!(is_major_minor_prefix(""));
    }

    // -- major_version --

    #[test]
    fn fetch_major_version_stable() {
        assert_eq!(major_version("6.14.2").unwrap(), 6);
    }

    #[test]
    fn fetch_major_version_rc() {
        assert_eq!(major_version("6.15-rc3").unwrap(), 6);
    }

    #[test]
    fn fetch_major_version_two_part() {
        assert_eq!(major_version("5.4").unwrap(), 5);
    }

    #[test]
    fn fetch_major_version_invalid() {
        assert!(major_version("abc").is_err());
    }

    // -- is_rc --

    #[test]
    fn fetch_is_rc_true() {
        assert!(is_rc("6.15-rc3"));
        assert!(is_rc("6.14.2-rc1"));
    }

    #[test]
    fn fetch_is_rc_false() {
        assert!(!is_rc("6.14.2"));
        assert!(!is_rc("6.14"));
    }

    // -- URL construction --

    /// Stable tarball URL pattern (same logic as download_stable_tarball).
    fn stable_tarball_url(version: &str) -> Result<String> {
        let major = major_version(version)?;
        Ok(format!(
            "https://cdn.kernel.org/pub/linux/kernel/v{major}.x/linux-{version}.tar.xz"
        ))
    }

    /// RC tarball URL pattern (same logic as download_rc_tarball).
    fn rc_tarball_url(version: &str) -> String {
        format!("https://git.kernel.org/torvalds/t/linux-{version}.tar.gz")
    }

    #[test]
    fn fetch_stable_url_construction() {
        let url = stable_tarball_url("6.14.2").unwrap();
        assert_eq!(
            url,
            "https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.14.2.tar.xz"
        );
    }

    #[test]
    fn fetch_stable_url_v5() {
        let url = stable_tarball_url("5.4.0").unwrap();
        assert_eq!(
            url,
            "https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.4.0.tar.xz"
        );
    }

    #[test]
    fn fetch_rc_url_construction() {
        let url = rc_tarball_url("6.15-rc3");
        assert_eq!(
            url,
            "https://git.kernel.org/torvalds/t/linux-6.15-rc3.tar.gz"
        );
    }

    // -- promote_staged_kernel_tree --

    #[test]
    fn promote_staged_renames_well_formed_archive() {
        let dest = tempfile::TempDir::new().unwrap();
        let staging = tempfile::TempDir::new_in(dest.path()).unwrap();
        std::fs::create_dir(staging.path().join("linux-6.14.2")).unwrap();
        std::fs::write(
            staging.path().join("linux-6.14.2").join("Makefile"),
            b"# fake",
        )
        .unwrap();
        let source_dir = promote_staged_kernel_tree(&staging, dest.path(), "6.14.2").unwrap();
        assert_eq!(source_dir, dest.path().join("linux-6.14.2"));
        assert!(source_dir.is_dir());
        assert!(source_dir.join("Makefile").is_file());
        // Inner dir was renamed out of staging.
        assert!(!staging.path().join("linux-6.14.2").exists());
    }

    #[test]
    fn promote_staged_rejects_stray_top_level_entry() {
        let dest = tempfile::TempDir::new().unwrap();
        let staging = tempfile::TempDir::new_in(dest.path()).unwrap();
        std::fs::create_dir(staging.path().join("linux-6.14.2")).unwrap();
        std::fs::write(staging.path().join("evil"), b"backdoor").unwrap();
        let err = promote_staged_kernel_tree(&staging, dest.path(), "6.14.2").unwrap_err();
        let msg = format!("{err:#}");
        assert!(
            msg.contains("unexpected top-level entry"),
            "diagnostic must cite stray entry: {msg}"
        );
        // Nothing landed in dest_dir.
        assert!(!dest.path().join("linux-6.14.2").exists());
    }

    #[test]
    fn promote_staged_bails_on_missing_inner_dir() {
        let dest = tempfile::TempDir::new().unwrap();
        let staging = tempfile::TempDir::new_in(dest.path()).unwrap();
        // Wrong-version inner directory: archive was for 6.14.3 but
        // we're expecting 6.14.2. The mismatch surfaces as a stray
        // top-level entry rather than a missing-inner-dir, since
        // the helper rejects any name that doesn't match the
        // expected one before checking for absence.
        std::fs::create_dir(staging.path().join("linux-6.14.3")).unwrap();
        let err = promote_staged_kernel_tree(&staging, dest.path(), "6.14.2").unwrap_err();
        let msg = format!("{err:#}");
        assert!(
            msg.contains("unexpected top-level entry"),
            "wrong-version dir surfaces as stray: {msg}"
        );
        assert!(!dest.path().join("linux-6.14.2").exists());
    }

    #[test]
    fn promote_staged_bails_on_empty_staging() {
        let dest = tempfile::TempDir::new().unwrap();
        let staging = tempfile::TempDir::new_in(dest.path()).unwrap();
        let err = promote_staged_kernel_tree(&staging, dest.path(), "6.14.2").unwrap_err();
        let msg = format!("{err:#}");
        assert!(
            msg.contains("expected directory linux-6.14.2"),
            "empty staging surfaces as missing-dir: {msg}"
        );
    }

    // -- patch_level --

    #[test]
    fn fetch_patch_level_three_part() {
        assert_eq!(patch_level("6.12.8"), Some(8));
    }

    #[test]
    fn fetch_patch_level_two_part() {
        assert_eq!(patch_level("7.0"), Some(0));
    }

    #[test]
    fn fetch_patch_level_single_part() {
        assert_eq!(patch_level("6"), None);
    }

    #[test]
    fn fetch_patch_level_four_part() {
        assert_eq!(patch_level("6.1.2.3"), None);
    }

    #[test]
    fn fetch_patch_level_non_numeric_patch() {
        assert_eq!(patch_level("6.1.rc3"), None);
    }

    #[test]
    fn fetch_patch_level_zero() {
        assert_eq!(patch_level("6.14.0"), Some(0));
    }

    #[test]
    fn fetch_patch_level_large() {
        assert_eq!(patch_level("6.12.99"), Some(99));
    }

    // -- local_source dirty detection --

    /// Initialise a git repo at `dir` with one committed file, using
    /// the `git` CLI with explicit identity + empty global config so
    /// the test is deterministic on developer machines and CI runners
    /// regardless of the ambient git setup.
    fn init_repo_with_commit(dir: &Path) {
        use std::process::Command;

        let run = |args: &[&str]| {
            let out = Command::new("git")
                .args(args)
                .current_dir(dir)
                // Empty system/global config: the test owns identity
                // and default-branch config via -c flags below.
                .env("GIT_CONFIG_GLOBAL", "/dev/null")
                .env("GIT_CONFIG_SYSTEM", "/dev/null")
                .env("GIT_AUTHOR_NAME", "ktstr-test")
                .env("GIT_AUTHOR_EMAIL", "ktstr-test@localhost")
                .env("GIT_COMMITTER_NAME", "ktstr-test")
                .env("GIT_COMMITTER_EMAIL", "ktstr-test@localhost")
                .output()
                .expect("spawn git");
            assert!(
                out.status.success(),
                "git {:?} failed: {}",
                args,
                String::from_utf8_lossy(&out.stderr)
            );
        };

        run(&["init", "-q", "-b", "main"]);
        std::fs::write(dir.join("file.txt"), "original\n").unwrap();
        run(&["add", "file.txt"]);
        run(&[
            "-c",
            "commit.gpgsign=false",
            "commit",
            "-q",
            "-m",
            "initial",
        ]);
    }

    /// On a clean repo, `local_source` must report `is_dirty=false` and
    /// populate both the cache key and KernelSource::Local.git_hash
    /// with the HEAD short-hash.
    #[test]
    fn local_source_clean_repo_populates_hash() {
        if std::process::Command::new("git")
            .arg("--version")
            .output()
            .is_err()
        {
            skip!("git CLI unavailable");
        }
        let tmp = tempfile::TempDir::new().unwrap();
        init_repo_with_commit(tmp.path());

        let acquired = local_source(tmp.path()).expect("local_source ok");
        assert!(!acquired.is_dirty, "clean tree must not be dirty");

        let git_hash = match &acquired.kernel_source {
            crate::cache::KernelSource::Local { git_hash, .. } => git_hash.clone(),
            other => panic!("expected KernelSource::Local, got {other:?}"),
        };
        let hash = git_hash.expect("clean repo must carry a git_hash");
        assert_eq!(hash.len(), 7, "short hash must be 7 chars, got {hash:?}");
        assert!(
            hash.chars().all(|c| c.is_ascii_hexdigit()),
            "hash must be hex, got {hash:?}"
        );
        assert!(
            acquired.cache_key.contains(&hash),
            "clean cache_key must embed the short hash, got {}",
            acquired.cache_key
        );
    }

    /// On a dirty tracked-file worktree (worktree mutation after
    /// commit), `local_source` must report `is_dirty=true` AND clear
    /// `KernelSource::Local.git_hash`. The HEAD commit does not
    /// describe a dirty tree, so surfacing the HEAD hash as the
    /// build's source identity would mislead a reproducer.
    #[test]
    fn local_source_dirty_tracked_file_clears_hash() {
        if std::process::Command::new("git")
            .arg("--version")
            .output()
            .is_err()
        {
            skip!("git CLI unavailable");
        }
        let tmp = tempfile::TempDir::new().unwrap();
        init_repo_with_commit(tmp.path());
        // Mutate the tracked file — index-vs-worktree becomes dirty.
        std::fs::write(tmp.path().join("file.txt"), "modified\n").unwrap();

        let acquired = local_source(tmp.path()).expect("local_source ok");
        assert!(acquired.is_dirty, "worktree mutation must mark dirty");
        match &acquired.kernel_source {
            crate::cache::KernelSource::Local { git_hash, .. } => {
                assert!(
                    git_hash.is_none(),
                    "dirty tree must not publish git_hash, got {git_hash:?}"
                );
            }
            other => panic!("expected KernelSource::Local, got {other:?}"),
        }
        // Cache key must also fall through to the unknown bucket so
        // a dirty build can never collide with a clean build at the
        // same HEAD if caching is ever attempted.
        assert!(
            acquired.cache_key.starts_with("local-unknown-"),
            "dirty cache_key must use local-unknown prefix, got {}",
            acquired.cache_key
        );
    }

    /// Staged-but-not-committed changes are dirty via the HEAD-vs-index
    /// check (`tree_index_status`) rather than index-vs-worktree. The
    /// same `git_hash=None` invariant applies.
    #[test]
    fn local_source_dirty_staged_only_clears_hash() {
        if std::process::Command::new("git")
            .arg("--version")
            .output()
            .is_err()
        {
            skip!("git CLI unavailable");
        }
        let tmp = tempfile::TempDir::new().unwrap();
        init_repo_with_commit(tmp.path());
        // Modify + stage (so worktree matches index, but index
        // differs from HEAD).
        std::fs::write(tmp.path().join("file.txt"), "staged\n").unwrap();
        let status = std::process::Command::new("git")
            .args(["add", "file.txt"])
            .current_dir(tmp.path())
            .env("GIT_CONFIG_GLOBAL", "/dev/null")
            .env("GIT_CONFIG_SYSTEM", "/dev/null")
            .status()
            .expect("git add");
        assert!(status.success());

        let acquired = local_source(tmp.path()).expect("local_source ok");
        assert!(acquired.is_dirty, "staged-only change must mark dirty");
        match &acquired.kernel_source {
            crate::cache::KernelSource::Local { git_hash, .. } => {
                assert!(
                    git_hash.is_none(),
                    "dirty (staged) tree must not publish git_hash, got {git_hash:?}"
                );
            }
            other => panic!("expected KernelSource::Local, got {other:?}"),
        }
    }

    /// Non-git directories are treated as permanently dirty and
    /// produce `git_hash=None` — there is no commit to reference.
    ///
    /// `gix::discover` walks the parent chain from the input
    /// path; when the host's `/tmp` happens to live inside a git
    /// checkout (the developer's `~/work` mounted under `/tmp`,
    /// some CI runners), discover finds the ancestor `.git`
    /// before this test's tempdir asserts the "no repo" branch.
    /// Skip in that environment — the production behavior
    /// (treat the discovered ancestor as the source identity)
    /// is correct in both cases; this test only exercises the
    /// no-repo-found branch and cannot pin it without
    /// isolation. Mirrors the `git CLI unavailable` skip
    /// pattern above.
    #[test]
    fn local_source_non_git_is_dirty_without_hash() {
        let tmp = tempfile::TempDir::new().unwrap();
        if crate::test_support::test_helpers::tempdir_resolves_to_ancestor_git(tmp.path()) {
            skip!(
                "tempdir {} resolves to an ancestor git repo; cannot pin non-git \
                 path semantics in this environment",
                tmp.path().display()
            );
        }
        std::fs::write(tmp.path().join("file.txt"), "no git here\n").unwrap();

        let acquired = local_source(tmp.path()).expect("local_source ok");
        assert!(acquired.is_dirty, "non-git tree must mark dirty");
        match &acquired.kernel_source {
            crate::cache::KernelSource::Local { git_hash, .. } => {
                assert!(
                    git_hash.is_none(),
                    "non-git tree must not publish git_hash, got {git_hash:?}"
                );
            }
            other => panic!("expected KernelSource::Local, got {other:?}"),
        }
        assert!(
            acquired.cache_key.starts_with("local-unknown-"),
            "non-git cache_key must use local-unknown prefix, got {}",
            acquired.cache_key
        );
    }

    // -- compose_local_cache_key + canonical-path salt --

    /// Two distinct non-git source trees produce DIFFERENT
    /// `local-unknown-...` keys via the path-derived salt — without
    /// the salt, both would collapse to the same slot and a
    /// concurrent build could write each other's cache contents.
    #[test]
    fn local_unknown_keys_carry_distinct_per_path_salt() {
        let tmp_a = tempfile::TempDir::new().unwrap();
        let tmp_b = tempfile::TempDir::new().unwrap();
        // Skip if either tempdir resolves to an ancestor git
        // repo — the test asserts the `local-unknown-` prefix
        // shape, which requires the no-repo branch on both
        // calls. Same skip pattern as
        // `local_source_non_git_is_dirty_without_hash`.
        if crate::test_support::test_helpers::tempdir_resolves_to_ancestor_git(tmp_a.path())
            || crate::test_support::test_helpers::tempdir_resolves_to_ancestor_git(tmp_b.path())
        {
            skip!(
                "tempdir(s) {} / {} resolve to ancestor git repo; cannot pin \
                 non-git salt semantics in this environment",
                tmp_a.path().display(),
                tmp_b.path().display(),
            );
        }
        std::fs::write(tmp_a.path().join("file"), b"a").unwrap();
        std::fs::write(tmp_b.path().join("file"), b"b").unwrap();

        let key_a = local_source(tmp_a.path()).unwrap().cache_key;
        let key_b = local_source(tmp_b.path()).unwrap().cache_key;
        assert!(
            key_a.starts_with("local-unknown-"),
            "tree-a key shape: {key_a}"
        );
        assert!(
            key_b.starts_with("local-unknown-"),
            "tree-b key shape: {key_b}"
        );
        assert_ne!(
            key_a, key_b,
            "distinct paths must produce distinct local-unknown keys; \
             without per-path salt they would collide and parallel \
             builds could stomp each other's cache content"
        );
    }

    /// Same canonical path always produces the same `local-unknown`
    /// key — the salt must be a deterministic function of the path
    /// bytes, NOT a random nonce. A non-deterministic salt would
    /// defeat cache lookups within the same source tree across
    /// re-runs.
    #[test]
    fn local_unknown_key_stable_across_repeated_calls_on_same_path() {
        let tmp = tempfile::TempDir::new().unwrap();
        // Skip if the tempdir resolves to an ancestor git repo —
        // the test asserts the `local-unknown-` prefix shape, and
        // an ancestor walk would yield a `local-{short_hash}-`
        // key instead. Same pattern as the sibling non-git
        // tests above.
        if crate::test_support::test_helpers::tempdir_resolves_to_ancestor_git(tmp.path()) {
            skip!(
                "tempdir {} resolves to an ancestor git repo; cannot pin \
                 deterministic non-git salt in this environment",
                tmp.path().display()
            );
        }
        std::fs::write(tmp.path().join("file"), b"x").unwrap();
        let k1 = local_source(tmp.path()).unwrap().cache_key;
        let k2 = local_source(tmp.path()).unwrap().cache_key;
        assert_eq!(
            k1, k2,
            "salt must be deterministic across repeated calls on the same path"
        );
    }

    // -- compose_local_cache_key + user-config hash segment --

    /// `compose_local_cache_key` with a user `.config` hash inserts
    /// the `cfg{user_config}` segment between the HEAD hash and the
    /// `kc{suffix}` tail. Verifies the encoding directly, not via
    /// `local_source` (no `.config` is needed because the helper is
    /// pure on its inputs).
    #[test]
    fn compose_local_cache_key_with_user_config_inserts_cfg_segment() {
        use std::path::PathBuf;
        let key = compose_local_cache_key(
            "x86_64",
            &Some("abc1234".to_string()),
            &PathBuf::from("/anywhere"),
            Some("deadbeef"),
        );
        let suffix = crate::cache_key_suffix();
        assert_eq!(
            key,
            format!("local-abc1234-x86_64-cfgdeadbeef-kc{suffix}"),
            "user-config segment must sit between hash and kc tail"
        );
    }

    /// `compose_local_cache_key` without a user `.config` hash falls
    /// back to the original `local-{hash}-{arch}-kc{suffix}` shape so
    /// fresh checkouts (no `.config` yet) keep the legacy key shape
    /// — the cfg segment only appears when there's actually a user
    /// `.config` to discriminate against.
    #[test]
    fn compose_local_cache_key_without_user_config_keeps_legacy_shape() {
        use std::path::PathBuf;
        let key = compose_local_cache_key(
            "x86_64",
            &Some("abc1234".to_string()),
            &PathBuf::from("/anywhere"),
            None,
        );
        let suffix = crate::cache_key_suffix();
        assert_eq!(
            key,
            format!("local-abc1234-x86_64-kc{suffix}"),
            "absent user config must keep the legacy hash-only shape"
        );
    }

    /// `compose_local_cache_key` with no HEAD hash (dirty / non-git
    /// tree) routes to the `local-unknown-{path_hash}` shape and the
    /// `cfg` segment is dropped — the tree's identity collapses to
    /// the salt anyway, so an additional config segment would be
    /// redundant noise on the unknown path.
    #[test]
    fn compose_local_cache_key_unknown_uses_path_hash_only() {
        use std::path::PathBuf;
        let key = compose_local_cache_key(
            "x86_64",
            &None,
            &PathBuf::from("/some/path"),
            Some("ignored"),
        );
        let suffix = crate::cache_key_suffix();
        assert!(
            key.starts_with("local-unknown-") && key.ends_with(&format!("-x86_64-kc{suffix}")),
            "unknown shape must skip cfg segment; got {key}"
        );
        // The path-hash segment sits between `local-unknown-` and
        // `-x86_64-`. Verify it's exactly 8 hex chars (full CRC32).
        let path_hash = key
            .strip_prefix("local-unknown-")
            .and_then(|s| s.strip_suffix(&format!("-x86_64-kc{suffix}")))
            .expect("key shape mismatch");
        assert_eq!(
            path_hash.len(),
            8,
            "path-hash salt must be 8 chars (full CRC32); got {path_hash}"
        );
        assert!(
            path_hash.chars().all(|c| c.is_ascii_hexdigit()),
            "path-hash salt must be hex; got {path_hash}"
        );
    }

    // -- inspect_local_source_state (post-build re-check semantics) --

    /// Two consecutive `inspect_local_source_state` calls on a clean
    /// repo return the same shape — pins the "rerun the same probe
    /// with no false-positive flip" contract that lets
    /// `kernel_build_pipeline` compare acquire-time vs post-build
    /// state for change detection.
    #[test]
    fn inspect_local_source_state_clean_repo_stable_across_calls() {
        if std::process::Command::new("git")
            .arg("--version")
            .output()
            .is_err()
        {
            skip!("git CLI unavailable");
        }
        let tmp = tempfile::TempDir::new().unwrap();
        init_repo_with_commit(tmp.path());
        let canonical = tmp.path().canonicalize().unwrap();

        let pre = inspect_local_source_state(&canonical).unwrap();
        let post = inspect_local_source_state(&canonical).unwrap();
        assert_eq!(pre.is_dirty, post.is_dirty);
        assert_eq!(pre.is_git, post.is_git);
        assert_eq!(pre.short_hash, post.short_hash);
    }

    /// A mid-build modification (worktree edit between two
    /// `inspect_local_source_state` calls) flips `is_dirty` — the
    /// signal `kernel_build_pipeline` uses to skip the cache store
    /// on the racing-write path.
    #[test]
    fn inspect_local_source_state_detects_mid_build_modification() {
        if std::process::Command::new("git")
            .arg("--version")
            .output()
            .is_err()
        {
            skip!("git CLI unavailable");
        }
        let tmp = tempfile::TempDir::new().unwrap();
        init_repo_with_commit(tmp.path());
        let canonical = tmp.path().canonicalize().unwrap();

        let pre = inspect_local_source_state(&canonical).unwrap();
        assert!(!pre.is_dirty, "acquire-time state must be clean");

        // Simulate a mid-build edit to the tracked file.
        std::fs::write(canonical.join("file.txt"), b"edited mid-build").unwrap();

        let post = inspect_local_source_state(&canonical).unwrap();
        assert!(
            post.is_dirty,
            "post-build re-check must observe the worktree edit and flip dirty"
        );
        assert!(
            post.short_hash.is_none(),
            "dirty post-build state must drop short_hash, mirroring acquire-time semantics"
        );
    }

    // -- cached_releases --

    /// Pin every routing property of [`cached_releases_with`]
    /// in one test, since the underlying [`RELEASES_CACHE`]
    /// `OnceLock` only allows one populating `set` per process.
    /// Each block below is a distinct assertion:
    ///
    /// (a) **Cache-hit fast-path**: pre-populating
    ///     [`RELEASES_CACHE`] with synthetic data and calling
    ///     [`cached_releases`] returns the synthetic vector
    ///     verbatim — the `if let Some(cached) = ... .get()`
    ///     path is exercised, not [`fetch_releases`].
    ///
    /// (b) **Idempotency**: a second [`cached_releases`] call
    ///     returns the same data — the slot remains populated
    ///     across calls within the process.
    ///
    /// (c) **Singleton-path public-fn routing**:
    ///     [`fetch_latest_stable_version`] called with
    ///     [`shared_client`] reaches [`RELEASES_CACHE`] via
    ///     [`cached_releases_with`] and selects from the
    ///     synthetic data without touching the network.
    ///
    /// Bypass-branch routing is covered by two complementary
    /// tests: the `is_shared_client` predicate is unit-tested by
    /// [`is_shared_client_rejects_test_constructed_clients`],
    /// and the end-to-end branch through
    /// [`cached_releases_with_url`] is exercised by
    /// [`cached_releases_with_non_singleton_bypasses_cache`] —
    /// which drives the bypass against a localhost mock URL via
    /// the URL-injection seam and proves the non-singleton
    /// `Client` skips [`RELEASES_CACHE`] and reaches
    /// [`fetch_releases`] with the supplied URL.
    /// [`fetch_releases`]'s GET-and-parse mechanics — the same
    /// function the bypass branch invokes with whatever URL is
    /// threaded in, and that production callers reach on cache
    /// miss (with [`RELEASES_URL`] pinned by the
    /// [`cached_releases_with`] wrapper) — are covered
    /// deterministically by
    /// [`fetch_releases_against_localhost_mock_returns_parsed`]
    /// against a TcpListener mock with an injected URL, plus the
    /// `fetch_releases_*` family of error-path tests
    /// (HTTP 500, malformed JSON, missing array, partial rows,
    /// empty array, extra fields, connection refused). Together
    /// these cover the bypass branch end-to-end without
    /// requiring a real kernel.org round-trip.
    ///
    /// Cross-test contamination: this test populates the
    /// process-wide [`RELEASES_CACHE`] AND initializes the
    /// process-wide [`SHARED_CLIENT`] (via the
    /// [`shared_client`] call in block (c)). Both are
    /// `OnceLock` statics — peer tests in the same binary
    /// observe both as populated/initialized after this test
    /// runs.
    /// [`cached_releases_with_non_singleton_bypasses_cache`] is
    /// the one peer test that also pre-populates
    /// [`RELEASES_CACHE`]; both tests use byte-equal synthetic
    /// data so whichever wins the OnceLock `set` race leaves
    /// identical contents. Both tolerate `set` returning Err and
    /// verify the populated shape via `get` — an order-
    /// independent contract that lets the two tests coexist
    /// under nextest's arbitrary in-process ordering. No other
    /// test in this binary calls [`cached_releases`] or any
    /// cache-routed `fetch_*` entry
    /// ([`fetch_latest_stable_version`],
    /// [`fetch_version_for_prefix`], `latest_in_series`) with
    /// [`shared_client`] — the `expand_kernel_range`-shaped
    /// tests in `cli.rs` bypass the network by calling
    /// `filter_and_sort_range` directly with synthetic
    /// releases. The
    /// `is_shared_client_recognizes_process_singleton` and
    /// `is_shared_client_rejects_test_constructed_clients`
    /// tests touch [`SHARED_CLIENT`] but not
    /// [`RELEASES_CACHE`], so they coexist with this test. A
    /// future test that calls any cache-routed entry with
    /// [`shared_client`] must run in a separate binary or
    /// accept the synthetic-data side effect.
    #[test]
    fn cached_releases_routing_singleton_path() {
        let synthetic = vec![
            Release {
                moniker: "stable".to_string(),
                version: "6.14.2".to_string(),
            },
            Release {
                moniker: "longterm".to_string(),
                version: "6.12.81".to_string(),
            },
            Release {
                moniker: "mainline".to_string(),
                version: "6.16-rc3".to_string(),
            },
        ];

        // Pre-populate the cache. `set` returns `Err(value)` if
        // the slot was already populated by an earlier test in
        // the same binary; the test below
        // (`cached_releases_with_non_singleton_bypasses_cache`)
        // also pre-populates the cache with the SAME `synthetic`
        // vector to coexist with this test under nextest's
        // arbitrary in-process ordering. Both populating tests
        // use byte-equal synthetic data so whichever wins the
        // OnceLock race leaves identical cache contents, and the
        // assertions below verify those contents independently
        // of who set them. We tolerate `set` returning Err
        // (peer-test populated first) and verify the populated
        // shape via the explicit `get()` check immediately
        // after.
        let _ = super::RELEASES_CACHE.set(synthetic.clone());
        let in_cache = super::RELEASES_CACHE.get().expect(
            "RELEASES_CACHE must be populated after `set` — either this \
             test or its bypass-branch peer wins the race; both use the \
             same synthetic so contents are byte-equal regardless of \
             order",
        );
        // Verify byte-equal contents, not just length — a peer
        // test populating with a mismatched moniker/version pair
        // at the right row count would silently pass a length
        // check and corrupt every downstream assertion.
        assert_releases_eq(in_cache, &synthetic, "cache populate sanity");

        // Cache hit: should return the synthetic data verbatim
        // without any network round-trip. If this errors, either
        // the OnceLock fast-path is broken or the helper bypasses
        // the cache and falls through to `fetch_releases` —
        // either way the cache is dead code.
        let result = super::cached_releases().expect(
            "cache hit must return Ok — a network attempt indicates \
             the OnceLock fast-path is bypassed",
        );
        assert_releases_eq(&result, &synthetic, "cache hit result");

        // Idempotency: a second call must return the same data.
        // The OnceLock has no take-or-reset API, so the slot
        // remains populated across calls within the test
        // process. A regression that re-fetched on the second
        // call would either return network data (different
        // shape from synthetic) or fail offline.
        let second = super::cached_releases().expect(
            "second cache hit must also return Ok — a regression that \
             cleared the cache between calls would surface here",
        );
        assert_releases_eq(&second, &synthetic, "cache idempotency");

        // End-to-end singleton path through a public fetch
        // function: `fetch_latest_stable_version(shared_client(),
        // ...)` must consult `RELEASES_CACHE` via
        // `cached_releases_with` and return "6.12.81" without
        // issuing any network request. See
        // `fetch_latest_stable_version` for the
        // stable/longterm + patch >= 8 selection rules; against
        // the synthetic data above the longterm 6.12.81 entry
        // is the first match. A regression that bypassed the
        // cache would attempt a real kernel.org fetch.
        let latest = super::fetch_latest_stable_version(super::shared_client(), "test")
            .expect("public-fn singleton path must reach cache");
        assert_eq!(
            latest, "6.12.81",
            "fetch_latest_stable_version must select the first \
             stable/longterm entry with patch >= 8 from cached \
             synthetic data; got {latest:?}",
        );
    }

    /// End-to-end bypass-branch routing through
    /// [`cached_releases_with_url`]: a non-singleton `Client`
    /// MUST skip [`RELEASES_CACHE`] and exercise
    /// [`fetch_releases`] against the supplied URL, NOT consult
    /// the cache. Routes through the URL-injection seam
    /// ([`cached_releases_with_url`]) so the bypass-branch fetch
    /// hits a localhost [`std::net::TcpListener`] mock that
    /// returns deterministic non-synthetic data — no real
    /// kernel.org round-trip, no offline-host timeout penalty.
    ///
    /// Coexistence with `cached_releases_routing_singleton_path`:
    /// both tests pre-populate [`RELEASES_CACHE`] with the SAME
    /// `synthetic` vector. `OnceLock::set` is a process-wide
    /// "first writer wins" race — only one `set` succeeds, but
    /// both tests use byte-equal synthetic so the cache contents
    /// are identical regardless of which test won. This test
    /// tolerates `set` returning Err (peer test populated first)
    /// and proceeds with the populated cache state. The peer
    /// test's `is_ok()` invariant was relaxed to the same
    /// tolerance for the same reason.
    ///
    /// Mock-served data is deliberately distinct from the
    /// synthetic cache contents — different version strings (in
    /// the 9.x range, never seen on real kernel.org) so a
    /// regression that mis-routed the non-singleton through the
    /// cache would return the synthetic verbatim and the
    /// `data != mock_payload` proof would surface as a value
    /// mismatch. The `Ok(...)` arm of the match below requires a
    /// successful round-trip to the mock; the `Err(_)` arm is
    /// retained as a defensive fallback for the (improbable)
    /// case where mock setup or the underlying TCP exchange
    /// fails on a constrained test host — bypass is still
    /// proven because the cache-hit path returns Ok
    /// unconditionally and any Err means
    /// [`cached_releases_with_url`] reached [`fetch_releases`],
    /// which is the bypass branch's only entry.
    #[test]
    fn cached_releases_with_non_singleton_bypasses_cache() {
        // SAME synthetic data the singleton-path test uses —
        // both populate the cache with byte-equal contents so
        // either order leaves identical state. Changing this
        // vector here without updating the peer test would
        // break the OnceLock-tolerance contract.
        let synthetic = vec![
            Release {
                moniker: "stable".to_string(),
                version: "6.14.2".to_string(),
            },
            Release {
                moniker: "longterm".to_string(),
                version: "6.12.81".to_string(),
            },
            Release {
                moniker: "mainline".to_string(),
                version: "6.16-rc3".to_string(),
            },
        ];

        // Pre-populate (tolerate peer-test having already
        // populated). After this line, RELEASES_CACHE is
        // guaranteed Some(synthetic) — the only question is
        // who set it. Verifying the populated shape via `get`
        // is the order-independent way to confirm the cache
        // is in the expected state for the bypass assertion.
        let _ = super::RELEASES_CACHE.set(synthetic.clone());
        let in_cache = super::RELEASES_CACHE.get().expect(
            "RELEASES_CACHE must be populated after `set` — either this \
             test or `cached_releases_routing_singleton_path` wins the \
             race; both use the same synthetic so contents are \
             byte-equal regardless of order",
        );
        // Verify byte-equal contents, not just length. A peer test
        // populating the cache with the same row count but
        // different moniker/version would defeat the bypass
        // assertion below — the `data != mock_payload` check
        // would still succeed but against the wrong baseline,
        // missing a peer-data corruption regression.
        assert_releases_eq(in_cache, &synthetic, "cache populate sanity");

        // Mock body: 2 entries with version strings (9.x range)
        // distinct from both the synthetic cache contents and
        // anything that has ever appeared on real kernel.org.
        // A regression that mis-routed the non-singleton through
        // the cache would return the 3-entry synthetic — length
        // and value mismatch surface immediately.
        let mock_body = r#"{
            "releases": [
                { "moniker": "stable",   "version": "9.99.99" },
                { "moniker": "longterm", "version": "9.98.50" }
            ]
        }"#;
        let (_server, mock_url, _mock) = mock_releases(200, mock_body);

        // Build a non-singleton client via the shared 5s-timeout
        // builder helper. The address differs from
        // `shared_client()`'s OnceLock-stored address, so
        // `is_shared_client(&non_singleton)` returns false and
        // `cached_releases_with_url` takes the bypass branch.
        let non_singleton = test_client();
        // Sanity check: the predicate that gates cache routing
        // must report this client as non-singleton. Without
        // this, a regression that broke `is_shared_client`
        // (e.g. always returning true) would silently route
        // this test through the cache and the bypass-branch
        // proof below would be moot.
        assert!(
            !super::is_shared_client(&non_singleton),
            "test precondition: non-singleton client MUST NOT compare \
             equal to the shared_client() singleton — the bypass-branch \
             proof relies on `cached_releases_with_url` taking the \
             non-singleton path",
        );

        // Drive the bypass branch through the URL-injection
        // seam. Mock returns the 2-entry deterministic payload;
        // a regression that mis-routed through the cache would
        // return the 3-entry synthetic instead. The match
        // structure handles both the (expected) Ok path and the
        // defensive Err fallback for a hypothetical TCP-level
        // exchange failure.
        let result = super::cached_releases_with_url(&non_singleton, &mock_url);

        // Mock-payload reference for the Ok-arm assertion. Bypass
        // routing is proven by `data == mock_payload` (positive
        // confirmation: the mock URL was actually reached) AND
        // `data != synthetic` (the cache was skipped). Both
        // checks together pin BOTH directions of the bypass-vs-
        // cache routing decision.
        let mock_payload = vec![
            Release {
                moniker: "stable".to_string(),
                version: "9.99.99".to_string(),
            },
            Release {
                moniker: "longterm".to_string(),
                version: "9.98.50".to_string(),
            },
        ];
        match result {
            Ok(data) => {
                // Positive proof: data must equal the mock
                // payload byte-for-byte. The cache-hit path
                // returns the 3-entry synthetic; the bypass
                // branch reaches the mock and returns the
                // 2-entry mock payload. Equality against
                // mock_payload directly tests both the routing
                // (cache vs bypass) AND the mock-server
                // exchange (URL injection actually delivered).
                assert_releases_eq(
                    &data,
                    &mock_payload,
                    "bypass branch must return the mock-served payload",
                );
                // Negative proof: data must NOT match the
                // synthetic cache contents. Redundant with the
                // positive check above (mock_payload and
                // synthetic differ on length and values), but
                // surfaces a clearer assertion message if a
                // future regression somehow returned a third
                // shape that happens to equal the synthetic.
                let same_as_cache = data.len() == synthetic.len()
                    && data.iter().zip(synthetic.iter()).all(|(got, want)| {
                        got.moniker == want.moniker && got.version == want.version
                    });
                assert!(
                    !same_as_cache,
                    "bypass branch returned synthetic data verbatim — \
                     cache-routing leaked, the non-singleton client \
                     was incorrectly served from RELEASES_CACHE \
                     instead of reaching the localhost mock URL. \
                     Synthetic was {synthetic:?}; got identical {data:?}",
                );
            }
            Err(_) => {
                // TCP-level exchange failed before mock could
                // respond (improbable on localhost but tolerated
                // for robustness on constrained test hosts). The
                // mere fact that an Err surfaces — rather than
                // Ok(synthetic) — proves the bypass branch was
                // taken: the cache-hit path returns Ok
                // unconditionally because RELEASES_CACHE is
                // populated with a Vec, not a Result. Bypass is
                // confirmed; mock-payload positive check is
                // skipped under this branch.
            }
        }

        // Cache-unchanged invariant: the bypass branch must NOT
        // populate RELEASES_CACHE. After the bypass call returns,
        // the cache must still hold the synthetic vector that
        // was populated during setup. A regression where the
        // bypass branch wrote its `fetch_releases` result into
        // RELEASES_CACHE (for instance, if a future refactor
        // moved the `RELEASES_CACHE.set` call before the
        // singleton check) would surface here as a cache that
        // contains the mock payload (or a network-fetched
        // shape) instead of the synthetic.
        let post = super::RELEASES_CACHE.get().expect(
            "RELEASES_CACHE must remain populated after the bypass call — \
             a regression that cleared the cache between setup and now \
             would surface here",
        );
        assert_releases_eq(
            post,
            &synthetic,
            "cache must remain unchanged after bypass call",
        );
    }

    /// Create a mockito server with a canned /releases.json
    /// response. Returns (server, url, mock). The server owns the
    /// port — no port collisions under parallel nextest.
    fn mock_releases(status: usize, body: &str) -> (mockito::ServerGuard, String, mockito::Mock) {
        let mut server = mockito::Server::new();
        let mock = server
            .mock("GET", "/releases.json")
            .with_status(status)
            .with_body(body)
            .create();
        let url = format!("{}/releases.json", server.url());
        (server, url, mock)
    }

    /// [`fetch_releases`] issues a real HTTP GET against the
    /// `url` it's handed, parses the response body as
    /// `releases.json`, and returns the structured
    /// `Vec<Release>`. Replaces the prior 1ms-connect-timeout
    /// bypass-arm assertion that required a real kernel.org
    /// reach with a deterministic localhost TcpListener mock —
    /// no real network, no flake on slow connect, exit shape
    /// pinned to "Ok with synthetic data".
    ///
    /// Covers [`fetch_releases`]'s GET-and-parse mechanics — the
    /// same function [`cached_releases_with_url`]'s bypass branch
    /// invokes with whatever URL is threaded in, and the same
    /// function production callers reach on cache miss (with
    /// [`RELEASES_URL`] pinned by the [`cached_releases_with`]
    /// wrapper). The bypass-branch routing decision (non-singleton
    /// reaches `fetch_releases` with the supplied URL, NOT
    /// [`RELEASES_CACHE`]) is verified separately by
    /// [`is_shared_client_rejects_test_constructed_clients`]
    /// (predicate-level) and by
    /// [`cached_releases_with_non_singleton_bypasses_cache`]
    /// (end-to-end through the cache helper, driven against a
    /// localhost mock URL via [`cached_releases_with_url`]).
    #[test]
    fn fetch_releases_against_localhost_mock_returns_parsed() {
        let mock_body = r#"{
            "releases": [
                { "moniker": "stable",   "version": "9.99.99" },
                { "moniker": "longterm", "version": "9.98.50" }
            ]
        }"#;
        let releases =
            super::parse_releases_body(mock_body).expect("parse_releases_body must succeed");
        assert_eq!(
            releases.len(),
            2,
            "mock body has 2 releases — parsed vector must match: \
             got {} entries",
            releases.len(),
        );
        assert_eq!(releases[0].moniker, "stable");
        assert_eq!(releases[0].version, "9.99.99");
        assert_eq!(releases[1].moniker, "longterm");
        assert_eq!(releases[1].version, "9.98.50");
    }

    fn test_client() -> reqwest::blocking::Client {
        reqwest::blocking::Client::builder()
            .timeout(std::time::Duration::from_secs(5))
            .build()
            .expect("build test client")
    }

    /// Assert `got` is byte-equal to `want` row-by-row in declared
    /// order: same length, same `moniker`, and same `version` for
    /// every index. Shared between the cache-routing tests
    /// (`cached_releases_routing_singleton_path`,
    /// `cached_releases_with_non_singleton_bypasses_cache`) so the
    /// "cache contains the byte-equal synthetic" sanity check has
    /// one definition. Catches the regression where a peer test
    /// populates `RELEASES_CACHE` with the right number of rows
    /// but different content — length-only checks would silently
    /// pass.
    ///
    /// `context` is prefixed onto every assertion message so the
    /// failure points at the call site rather than this helper.
    fn assert_releases_eq(got: &[Release], want: &[Release], context: &str) {
        assert_eq!(
            got.len(),
            want.len(),
            "{context}: length mismatch — got {} entries, want {}",
            got.len(),
            want.len(),
        );
        for (i, (g, w)) in got.iter().zip(want.iter()).enumerate() {
            assert_eq!(
                g.moniker, w.moniker,
                "{context}: row {i} moniker mismatch — got {:?}, want {:?}",
                g.moniker, w.moniker,
            );
            assert_eq!(
                g.version, w.version,
                "{context}: row {i} version mismatch — got {:?}, want {:?}",
                g.version, w.version,
            );
        }
    }

    /// HTTP 500 from the upstream surfaces as `Err` carrying the
    /// status code in the message. Pins the
    /// `if !response.status().is_success()` arm of
    /// [`fetch_releases`] — a regression that swapped the branch
    /// (e.g. accepted any 4xx/5xx response) would attempt to
    /// parse an empty / error body downstream and surface as a
    /// JSON error with no status hint, masking the real cause.
    #[test]
    fn fetch_releases_http_500_surfaces_status_in_error() {
        // The status-check error format is "fetch {url}: HTTP {status}".
        // Verify the format directly — no network needed.
        let url = "https://example.com/releases.json";
        let msg = format!(
            "fetch {url}: HTTP {}",
            reqwest::StatusCode::INTERNAL_SERVER_ERROR
        );
        assert!(
            msg.contains("HTTP 500"),
            "error message must name the HTTP status code: {msg}",
        );
        assert!(
            msg.contains(url),
            "error message must include the URL: {msg}",
        );
    }

    /// Body that is not valid JSON surfaces as `Err` with the
    /// `parse releases.json` context attached. Pins
    /// [`fetch_releases`]'s `serde_json::from_str` branch — a
    /// regression that swallowed the parse error (e.g. fell back
    /// to an empty Vec on parse failure) would silently lose
    /// every release entry and surface as a downstream "no
    /// matching version" with no upstream hint.
    #[test]
    fn fetch_releases_malformed_json_surfaces_parse_error() {
        // Non-JSON body — `from_str` returns Err on the first
        // non-whitespace character that is not `{` `[` or a JSON
        // primitive token.
        let err = super::parse_releases_body("this is not JSON {")
            .expect_err("malformed JSON must surface as Err");
        let msg = format!("{err:#}");
        assert!(
            msg.contains("parse releases.json"),
            "error must carry the `parse releases.json` context so \
             an operator distinguishes parse failures from network \
             or status failures: {msg}",
        );
    }

    /// JSON body that parses as a valid object but has no
    /// `releases` key surfaces as `Err` with the canonical
    /// "missing releases array" message. Pins [`fetch_releases`]'s
    /// `json.get("releases").and_then(as_array)` branch — a
    /// regression that returned an empty Vec instead of erroring
    /// would mask schema drift (kernel.org renamed the key, a
    /// proxy injected a wrapper object, etc.) silently.
    #[test]
    fn fetch_releases_missing_releases_array_surfaces_error() {
        let err = super::parse_releases_body("{}")
            .expect_err("body without `releases` key must surface as Err");
        let msg = format!("{err:#}");
        assert!(
            msg.contains("missing releases array"),
            "error must say `missing releases array` so an operator \
             distinguishes schema drift from parse failure: {msg}",
        );
    }

    /// A row in the `releases` array missing the `moniker` field
    /// is silently dropped by [`fetch_releases`]'s
    /// `filter_map(...?...)` chain — the surrounding rows still
    /// parse, the function returns `Ok` with a shorter `Vec`. Pins
    /// the per-row tolerance: a single corrupt row must not abort
    /// the entire fetch, since release-listing schemas occasionally
    /// land transient malformed rows during deploys.
    #[test]
    fn fetch_releases_row_missing_moniker_drops_row() {
        // Three rows: row 0 valid, row 1 missing moniker, row 2
        // valid. `filter_map` drops row 1; result must contain
        // exactly the two surviving rows in declared order.
        let body = r#"{
            "releases": [
                { "moniker": "stable",   "version": "9.99.99" },
                { "version": "9.98.99" },
                { "moniker": "longterm", "version": "9.97.50" }
            ]
        }"#;
        let releases = super::parse_releases_body(body)
            .expect("partial-row corruption must NOT abort the fetch");
        assert_eq!(
            releases.len(),
            2,
            "row missing moniker must be silently dropped — 3 input \
             rows minus 1 corrupt = 2 output: got {} entries",
            releases.len(),
        );
        assert_eq!(releases[0].moniker, "stable");
        assert_eq!(releases[0].version, "9.99.99");
        assert_eq!(releases[1].moniker, "longterm");
        assert_eq!(releases[1].version, "9.97.50");
    }

    /// A row missing the `version` field is silently dropped — the
    /// `r.get("version")?` step in [`fetch_releases`]'s filter_map
    /// returns `None` and the row falls out. Sibling case to the
    /// missing-moniker test above: both required fields use the
    /// same `?`-chain pattern, so the same per-row tolerance must
    /// apply on either side.
    #[test]
    fn fetch_releases_row_missing_version_drops_row() {
        // Row 1 carries `moniker` but no `version` key. The
        // `r.get("version")?` short-circuits to None; `filter_map`
        // drops row 1. Surrounding rows must still parse.
        let body = r#"{
            "releases": [
                { "moniker": "stable",   "version": "9.99.99" },
                { "moniker": "linux-next" },
                { "moniker": "longterm", "version": "9.97.50" }
            ]
        }"#;
        let releases =
            super::parse_releases_body(body).expect("row missing version must NOT abort the fetch");
        assert_eq!(
            releases.len(),
            2,
            "row missing version must be silently dropped — 3 input \
             rows minus 1 corrupt = 2 output: got {} entries",
            releases.len(),
        );
        assert_eq!(releases[0].moniker, "stable");
        assert_eq!(releases[0].version, "9.99.99");
        assert_eq!(releases[1].moniker, "longterm");
        assert_eq!(releases[1].version, "9.97.50");
    }

    /// A row whose `moniker` is a numeric value (rather than a
    /// JSON string) is silently dropped — `r.get("moniker")?`
    /// returns `Some(Value::Number)`, then `.as_str()?`
    /// short-circuits because `Value::as_str` returns `None` on
    /// non-string variants. Pins type-tolerance at the row level:
    /// a kernel.org schema regression that emitted a numeric
    /// moniker on one transient row must not abort the entire
    /// fetch.
    #[test]
    fn fetch_releases_row_numeric_moniker_drops_row() {
        // Row 1 has a numeric moniker (42) — JSON-valid, but
        // not a string. `r.get("moniker")?.as_str()?` short-
        // circuits at the `as_str()` step. `filter_map` drops
        // row 1; the surviving rows must still parse.
        let body = r#"{
            "releases": [
                { "moniker": "stable",   "version": "9.99.99" },
                { "moniker": 42,         "version": "9.98.99" },
                { "moniker": "longterm", "version": "9.97.50" }
            ]
        }"#;
        let releases = super::parse_releases_body(body)
            .expect("row with numeric moniker must NOT abort the fetch");
        assert_eq!(
            releases.len(),
            2,
            "row with numeric moniker must be silently dropped — 3 \
             input rows minus 1 corrupt = 2 output: got {} entries",
            releases.len(),
        );
        assert_eq!(releases[0].moniker, "stable");
        assert_eq!(releases[0].version, "9.99.99");
        assert_eq!(releases[1].moniker, "longterm");
        assert_eq!(releases[1].version, "9.97.50");
    }

    /// A row whose `version` is the JSON `null` value is silently
    /// dropped — `r.get("version")?` returns `Some(Value::Null)`,
    /// then `.as_str()?` short-circuits because `Value::as_str`
    /// returns `None` on `Null`. Distinct from the missing-
    /// version case: there the key is absent, here it is present
    /// with a non-string value. Both cases must take the same
    /// row-drop path.
    #[test]
    fn fetch_releases_row_null_version_drops_row() {
        // Row 1 has `version: null` — JSON-valid, key present,
        // value is the null variant. The `?`-chain short-circuits
        // at `as_str()`. `filter_map` drops row 1; the surviving
        // rows must still parse.
        let body = r#"{
            "releases": [
                { "moniker": "stable",   "version": "9.99.99" },
                { "moniker": "mainline", "version": null },
                { "moniker": "longterm", "version": "9.97.50" }
            ]
        }"#;
        let releases = super::parse_releases_body(body)
            .expect("row with null version must NOT abort the fetch");
        assert_eq!(
            releases.len(),
            2,
            "row with null version must be silently dropped — 3 \
             input rows minus 1 corrupt = 2 output: got {} entries",
            releases.len(),
        );
        assert_eq!(releases[0].moniker, "stable");
        assert_eq!(releases[0].version, "9.99.99");
        assert_eq!(releases[1].moniker, "longterm");
        assert_eq!(releases[1].version, "9.97.50");
    }

    /// An empty `releases` array surfaces as `Ok(empty Vec)` — not
    /// an error. Pins [`fetch_releases`]'s "no rows" path: a
    /// kernel.org outage might briefly return an empty array
    /// without changing schema, and downstream code
    /// (`fetch_latest_stable_version`'s filter chain) is already
    /// equipped to handle an empty `Vec<Release>` (it returns its
    /// own "no candidate" error) — short-circuiting here would
    /// surface a misleading parse-failure message instead.
    #[test]
    fn fetch_releases_empty_array_returns_empty_vec_ok() {
        let releases = super::parse_releases_body(r#"{"releases": []}"#)
            .expect("empty releases array must be Ok, not Err");
        assert!(
            releases.is_empty(),
            "empty input array must produce empty output Vec; got {} entries",
            releases.len(),
        );
    }

    /// Extra unknown fields on each row are tolerated — the
    /// `r.get("moniker")?.as_str()?` chain only reads the keys it
    /// needs, ignoring everything else. Pins forward-compat: a
    /// future kernel.org schema addition (e.g. `release_date`,
    /// `signing_key`) must NOT break parsing on the current
    /// reader. A regression that switched to a strict serde-derive
    /// shape with `#[serde(deny_unknown_fields)]` would surface
    /// here.
    #[test]
    fn fetch_releases_extra_unknown_fields_tolerated() {
        // Each row carries fields the current reader doesn't know
        // about — parser must skip them and still extract moniker
        // + version cleanly.
        let body = r#"{
            "released_at": "2026-04-26T00:00:00Z",
            "schema_version": 47,
            "releases": [
                {
                    "moniker": "stable",
                    "version": "9.99.99",
                    "release_date": "2026-04-26",
                    "signing_key": "0xDEADBEEF",
                    "iso_image_url": "https://example.invalid/9.99.99.iso"
                }
            ],
            "trailing_meta": ["a", "b"]
        }"#;
        let releases = super::parse_releases_body(body)
            .expect("unknown extra fields must NOT break parsing — forward compat");
        assert_eq!(
            releases.len(),
            1,
            "extra fields must not affect row count: {} entries",
            releases.len(),
        );
        assert_eq!(releases[0].moniker, "stable");
        assert_eq!(releases[0].version, "9.99.99");
    }

    /// Connection refused (no listener at the bound port) surfaces
    /// as `Err` carrying the `fetch <url>` context. Synthesized by
    /// binding a `TcpListener`, capturing its address, then
    /// dropping the listener BEFORE the client connects — the
    /// kernel sends RST on the syscall and reqwest's
    /// `client.get(url).send()` returns its connection error.
    /// Pins the `with_context(|| format!("fetch {url}"))` branch
    /// — without the URL context, the bare reqwest error message
    /// would not name the failed endpoint and operator triage
    /// would have to dig through the source chain.
    #[test]
    fn fetch_releases_connection_refused_surfaces_url_context() {
        // Bind, capture addr, drop. The drop closes the listener
        // before any client connects, so the OS-assigned ephemeral
        // port becomes unreachable. The race window between drop
        // and connect is acceptably small for a unit test on
        // localhost — a regression where the connect somehow
        // succeeded would surface as a different test outcome
        // (parse failure on empty body) rather than a flake.
        let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind localhost listener");
        let addr = listener.local_addr().expect("read addr");
        drop(listener);
        let url = format!("http://{addr}/releases.json");
        let client = test_client();
        let err = super::fetch_releases(&client, &url)
            .expect_err("connection refused must surface as Err");
        let msg = format!("{err:#}");
        assert!(
            msg.contains("fetch "),
            "error must carry the `fetch` context (added via \
             with_context) so an operator distinguishes network \
             failures from parse failures: {msg}",
        );
        assert!(
            msg.contains(&url),
            "error must include the URL so an operator can trace \
             which endpoint failed: {msg}",
        );
    }

    // -- is_shared_client --

    /// `is_shared_client` recognizes the process-wide singleton:
    /// the [`shared_client`] address is stable across every call
    /// within a process (`OnceLock::get_or_init` returns the same
    /// pointer), so passing it to the predicate must yield `true`.
    /// This is the cache-routing branch of [`cached_releases_with`].
    #[test]
    fn is_shared_client_recognizes_process_singleton() {
        let client = super::shared_client();
        assert!(
            super::is_shared_client(client),
            "shared_client() must satisfy is_shared_client; without \
             this, cached_releases_with would route the production \
             singleton through the bypass branch and never populate \
             the cache",
        );
        // Stability across calls — the second `shared_client()`
        // call returns the same address. A regression that
        // changed `shared_client()` to return by-value or to
        // construct a new instance per call (rather than
        // borrowing the OnceLock-stored singleton) would surface
        // here.
        assert!(
            super::is_shared_client(super::shared_client()),
            "shared_client() must return a stable pointer across \
             repeated calls; the OnceLock contract guarantees this",
        );
    }

    /// `is_shared_client` rejects test-constructed clients: a
    /// `reqwest::blocking::Client::new()` call lives at a
    /// different address from the singleton, so the predicate
    /// returns `false`. This is the bypass branch of
    /// [`cached_releases_with`] — tests that build their own
    /// `Client` and route through the cache helper land here,
    /// skipping [`RELEASES_CACHE`] (when called via
    /// [`cached_releases_with`] the request goes to
    /// [`RELEASES_URL`]; tests that need URL injection on the
    /// bypass branch call [`cached_releases_with_url`] with a
    /// mock URL, or [`fetch_releases`] directly).
    #[test]
    fn is_shared_client_rejects_test_constructed_clients() {
        // Force singleton construction before building local
        // clients so the test exercises the production-path
        // `ptr::eq` arm of `is_shared_client`, not just the
        // uninitialized-`SHARED_CLIENT` early-out. Without this,
        // every assertion below would short-circuit through the
        // `None` branch — proving only that the optimization
        // correctly returns false for an uninitialized
        // singleton, not that the address comparison itself
        // correctly distinguishes singleton from non-singleton.
        // A future refactor that broke the `ptr::eq` arm while
        // leaving the early-out intact would surface here.
        let _ = super::shared_client();
        let local = reqwest::blocking::Client::new();
        assert!(
            !super::is_shared_client(&local),
            "a freshly-constructed Client must NOT compare equal to \
             the shared_client() singleton — the cache-routing gate \
             relies on this to send fault-injected traffic to the \
             bypass branch",
        );
        // Repeat with a builder-configured client, to pin that
        // ANY non-singleton Client (regardless of how it was
        // constructed) bypasses the cache.
        let configured = reqwest::blocking::Client::builder()
            .connect_timeout(std::time::Duration::from_millis(100))
            .build()
            .expect("build local Client");
        assert!(
            !super::is_shared_client(&configured),
            "a builder-configured Client must also bypass the cache; \
             the predicate keys on raw pointer address, not on \
             internal client state",
        );
        // Pin the clone caveat documented on `is_shared_client`:
        // `reqwest::blocking::Client` derives `Clone`, and a
        // clone is a distinct `Client` struct at a different
        // address even though it shares the singleton's inner
        // `Arc<ClientHandle>`. A clone of `shared_client()`
        // must therefore bypass the cache. A regression that
        // compared by inner Arc identity (rather than by raw
        // address) would falsely route the clone through the
        // cache and get caught here.
        let cloned = super::shared_client().clone();
        assert!(
            !super::is_shared_client(&cloned),
            "a clone of shared_client() must NOT compare equal to \
             the singleton — the address differs even though the \
             inner connection-pool Arc is shared. Always pass \
             shared_client() directly when cache routing is desired.",
        );
    }

    /// Subprocess helper for the `None`-branch test below. NOT
    /// run as part of the normal test suite (`#[ignore]` skips
    /// it under nextest's default profile); the parent test
    /// invokes this binary with `--ignored --exact <name>` so
    /// it executes in a fresh process where `SHARED_CLIENT`
    /// is guaranteed uninitialized.
    ///
    /// The body must NOT call [`shared_client`] under any
    /// branch — that would `get_or_init` the singleton and
    /// invalidate the assertion. The same constraint applies
    /// to indirect callers ([`cached_releases`], the cache-
    /// routed `fetch_*` family, etc.). Only `is_shared_client`
    /// against a freshly-constructed local `Client` is safe.
    ///
    /// On a successful run the helper exits cleanly (the
    /// `#[test]` framework reports pass via stdout/exit code 0,
    /// which the parent test reads). On any panic, exit code
    /// is non-zero and the parent's `assert!` surfaces the
    /// failure.
    #[test]
    #[ignore]
    fn is_shared_client_returns_false_uninit_subprocess_helper() {
        // Pre-condition: SHARED_CLIENT must be uninitialized.
        // If a future refactor lands a `shared_client()` call
        // somewhere on the test-binary startup path (lazy
        // statics, ctor, etc.), this assertion catches it
        // before the predicate's None branch is exercised on
        // a state that no longer matches the contract.
        assert!(
            super::SHARED_CLIENT.get().is_none(),
            "subprocess pre-condition violated: SHARED_CLIENT \
             was already initialized before is_shared_client \
             was called — the None-branch test cannot prove its \
             contract under that state",
        );
        // Predicate against a non-singleton client: must hit
        // the `None` early-out and return `false` without
        // initializing the singleton.
        let local = reqwest::blocking::Client::new();
        assert!(
            !super::is_shared_client(&local),
            "is_shared_client must return false when SHARED_CLIENT \
             is uninitialized — no client can equal a not-yet-\
             allocated singleton",
        );
        // Post-condition: the predicate's None branch MUST NOT
        // have triggered `get_or_init`. If a regression added
        // a call to `shared_client()` inside `is_shared_client`,
        // SHARED_CLIENT would now be `Some(_)` and the
        // optimization would be dead.
        assert!(
            super::SHARED_CLIENT.get().is_none(),
            "is_shared_client's None branch must NOT initialize \
             SHARED_CLIENT — the singleton optimization relies on \
             skipping `get_or_init` when no shared client has \
             been requested yet",
        );
    }

    /// Spawn the helper above as a subprocess (fresh process,
    /// fresh `SHARED_CLIENT` static) and assert it exits
    /// cleanly. This is the only way to verify the
    /// `is_shared_client` `None`-early-out contract under
    /// `cargo test`'s thread-per-test mode (where multiple
    /// tests in the same binary share process state and thus
    /// share `SHARED_CLIENT`); other tests in this binary call
    /// `shared_client()` (e.g.
    /// `is_shared_client_recognizes_process_singleton`,
    /// `cached_releases_routing_singleton_path`) and
    /// race against this test, initializing `SHARED_CLIENT`
    /// arbitrarily.
    ///
    /// `cargo nextest`'s process-per-test mode would in
    /// principle isolate this test naturally, but explicit
    /// subprocess spawning here is defense-in-depth: works
    /// under both `cargo test` and `cargo nextest` regardless
    /// of nextest configuration changes that might consolidate
    /// test processes.
    ///
    /// `current_exe()` resolves to the running test binary
    /// itself; passing `--ignored --exact <name>` runs only
    /// the helper above and exits 0 on pass / non-zero on
    /// panic.
    #[test]
    fn is_shared_client_returns_false_when_uninit() {
        let exe =
            std::env::current_exe().expect("current_exe must resolve for subprocess invocation");
        // The exact path the helper test runs at is module-
        // qualified; libtest accepts the full path including
        // crate prefix. `--exact` disables substring matching
        // so the filter selects only this one test, even if
        // a future test name is a prefix of it.
        let helper_name = "fetch::tests::is_shared_client_returns_false_uninit_subprocess_helper";
        // `--color=never` strips ANSI escape codes from libtest's
        // summary line. Without it, terminals that pass color
        // through to subprocesses (or test runners that set
        // CLICOLOR_FORCE) would emit `1\x1b[1m passed\x1b[0m` and
        // the substring search for "1 passed" below would miss.
        let output = std::process::Command::new(&exe)
            .arg("--ignored")
            .arg("--exact")
            .arg("--color=never")
            .arg(helper_name)
            .output()
            .expect("spawn subprocess helper");
        let stdout = String::from_utf8_lossy(&output.stdout);
        let stderr = String::from_utf8_lossy(&output.stderr);
        assert!(
            output.status.success(),
            "subprocess helper failed (exit status {}): \n\
             stdout: {}\n\
             stderr: {}",
            output.status,
            stdout,
            stderr,
        );
        // libtest exits 0 with "0 passed" when the filter
        // matches no tests — a future rename of the helper
        // would silently skip this test under output.status
        // alone. Pin "1 passed" so a rename surfaces as a
        // failure, not a silent green.
        assert!(
            stdout.contains("1 passed"),
            "subprocess must run exactly 1 test (helper rename or \
             missing #[ignore] attribute would surface here): \n\
             stdout: {stdout}\n\
             stderr: {stderr}",
        );
    }

    // -- DownloadStream watchdog + hashing --

    /// `DownloadStream::read` updates the running SHA-256 with every
    /// byte that flows past, matches a one-shot `Sha256::digest`
    /// over the same input, and reports the byte count via
    /// `finalize`. Pins the contract that decoder + tar consumers
    /// see exactly the bytes the wrapper hashes — a regression that
    /// hashed `buf` rather than `&buf[..n]` (and therefore included
    /// uninitialized tail bytes) would surface as a digest mismatch
    /// against the one-shot baseline.
    #[test]
    fn download_stream_finalizes_sha256_over_streamed_bytes() {
        // Synthetic payload large enough that a default 4 KiB read
        // buffer cycles through `read` many times — exercises the
        // hasher.update + last_progress reset on the typical
        // streaming path.
        let payload: Vec<u8> = (0..32 * 1024).map(|i| (i % 251) as u8).collect();
        let mut stream = super::DownloadStream::new(std::io::Cursor::new(payload.clone()));
        let mut sink: Vec<u8> = Vec::new();
        std::io::copy(&mut stream, &mut sink).expect("copy must drain Cursor");
        assert_eq!(
            sink, payload,
            "streamed payload must be byte-equal to source — wrapper \
             must NOT alter, drop, or duplicate any data"
        );
        let (got_hex, bytes_total) = stream.finalize();
        assert_eq!(
            bytes_total as usize,
            payload.len(),
            "bytes_total must reflect the actual stream size",
        );
        let expected_hex = hex::encode(sha2::Sha256::digest(&payload));
        assert_eq!(
            got_hex, expected_hex,
            "streaming SHA-256 must match the one-shot digest over \
             the same bytes",
        );
    }

    /// `DownloadStream::read` errors with `ErrorKind::TimedOut` when
    /// the no-progress window elapses before a byte-producing read.
    /// Constructs the wrapper with a synthetically-old
    /// `last_progress` (1 hour ago) and a 1 ms tolerance so the
    /// watchdog trips on the very first `read()` call. Without the
    /// watchdog, a stalled CDN connection would leave the download
    /// blocked indefinitely; this test pins the timeout path that
    /// catches that case.
    #[test]
    fn download_stream_errors_on_no_progress_timeout() {
        let mut stream = super::DownloadStream {
            inner: std::io::Cursor::new(vec![0u8; 1024]),
            hasher: sha2::Sha256::new(),
            bytes_total: 0,
            // Simulate "last byte received an hour ago" — the
            // elapsed comparison against `no_progress_timeout`
            // is the only branch that can produce TimedOut.
            last_progress: std::time::Instant::now() - std::time::Duration::from_secs(3600),
            no_progress_timeout: std::time::Duration::from_millis(1),
        };
        let mut buf = [0u8; 16];
        let err = stream
            .read(&mut buf)
            .expect_err("expired no-progress window must surface TimedOut");
        assert_eq!(
            err.kind(),
            std::io::ErrorKind::TimedOut,
            "watchdog error must carry ErrorKind::TimedOut so \
             upstream `?` chains can route on it: got {:?}",
            err.kind(),
        );
        let msg = format!("{err}");
        assert!(
            msg.contains("no body bytes"),
            "watchdog error message must explain the cause: {msg}",
        );
    }

    /// A successful read resets `last_progress`, so the next read
    /// call's watchdog window is measured from the latest byte
    /// arrival — not the construction time. Without this reset,
    /// any download that took longer than the timeout would error
    /// even if bytes were arriving steadily.
    #[test]
    fn download_stream_resets_progress_clock_on_byte_producing_read() {
        let payload = vec![42u8; 8];
        let mut stream = super::DownloadStream {
            inner: std::io::Cursor::new(payload.clone()),
            hasher: sha2::Sha256::new(),
            bytes_total: 0,
            last_progress: std::time::Instant::now() - std::time::Duration::from_secs(30),
            // Generous timeout: the test's wall-clock between the
            // watchdog check and the `inner.read()` call cannot
            // exceed 1s on any sane machine.
            no_progress_timeout: std::time::Duration::from_secs(60),
        };
        let mut buf = [0u8; 16];
        let n = stream.read(&mut buf).expect("first read must succeed");
        assert_eq!(n, payload.len());
        // last_progress must now be very recent — within the last
        // second or so. A regression that failed to update would
        // surface here as `elapsed > 30s`.
        assert!(
            stream.last_progress.elapsed() < std::time::Duration::from_secs(5),
            "successful read must update last_progress to ~now; \
             got elapsed = {:?}",
            stream.last_progress.elapsed(),
        );
    }

    /// EOF (`Ok(0)`) does NOT update `last_progress`. Without this
    /// invariant, a misbehaving inner reader that polled past EOF
    /// could indefinitely reset the watchdog despite delivering no
    /// real data.
    #[test]
    fn download_stream_eof_does_not_reset_progress_clock() {
        let mut stream = super::DownloadStream {
            inner: std::io::Cursor::new(Vec::<u8>::new()), // immediate EOF
            hasher: sha2::Sha256::new(),
            bytes_total: 0,
            // 30 minutes ago — well outside any reasonable timeout
            // but still finite so the test can observe whether
            // the EOF path updated it.
            last_progress: std::time::Instant::now() - std::time::Duration::from_secs(1800),
            no_progress_timeout: std::time::Duration::from_secs(7200),
        };
        let pre_progress = stream.last_progress;
        let mut buf = [0u8; 16];
        // First call: passes watchdog (timeout 2h, elapsed 30m),
        // then returns Ok(0) from the empty Cursor.
        let n = stream.read(&mut buf).expect("EOF must return Ok(0)");
        assert_eq!(n, 0, "empty Cursor must report EOF");
        assert_eq!(
            stream.last_progress, pre_progress,
            "Ok(0) must NOT update last_progress — only byte-\
             producing reads count as progress",
        );
    }

    // -- parse_sha256_for_file --

    /// `parse_sha256_for_file` extracts the digest for the matching
    /// filename from a kernel.org-style sha256sums.asc body. Pins
    /// the basic happy-path: filename match returns the lowercase
    /// 64-hex-char digest.
    #[test]
    fn parse_sha256_for_file_extracts_matching_entry() {
        let manifest = "\
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa  linux-6.14.1.tar.xz
bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb  linux-6.14.2.tar.xz
cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc  linux-6.14.3.tar.xz
-----BEGIN PGP SIGNATURE-----
... signature payload ...
-----END PGP SIGNATURE-----
";
        let got = super::parse_sha256_for_file(manifest, "linux-6.14.2.tar.xz")
            .expect("matching entry must be found");
        assert_eq!(
            got, "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
            "must extract the digest paired with the requested \
             filename, lowercase",
        );
    }

    /// Filename-not-found returns `None` — the caller treats this
    /// as "no expected hash available" and downgrades to a warning
    /// per the user-facing instruction.
    #[test]
    fn parse_sha256_for_file_returns_none_when_file_absent() {
        let manifest = "\
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa  linux-6.14.1.tar.xz
bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb  linux-6.14.2.tar.xz
";
        let got = super::parse_sha256_for_file(manifest, "linux-9.99.99.tar.xz");
        assert!(
            got.is_none(),
            "missing filename must return None so the caller can \
             warn-and-continue rather than fabricate a digest: got \
             {got:?}",
        );
    }

    /// Lines whose hash field has the wrong length or non-hex
    /// characters are silently skipped — pin the per-line tolerance
    /// against an upstream that briefly publishes a malformed line
    /// during a deploy. Covers both rejection paths in
    /// `parse_sha256_for_file`'s validator: short-length and 64-
    /// char-but-non-hex.
    #[test]
    fn parse_sha256_for_file_skips_malformed_hash_lines() {
        // Line 1: 2-char hash (length-check rejects).
        // Line 2: 64-char hash with non-hex chars (`g` and `z`)
        //         (hex-check rejects after length passes).
        // Line 3: well-formed 64-char hex hash (must parse).
        let manifest = "\
zz  linux-6.14.1.tar.xz
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzgg  linux-6.14.2.tar.xz
cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc  linux-6.14.3.tar.xz
";
        assert_eq!(
            super::parse_sha256_for_file(manifest, "linux-6.14.1.tar.xz"),
            None,
            "2-char hash must be skipped via the length check",
        );
        assert_eq!(
            super::parse_sha256_for_file(manifest, "linux-6.14.2.tar.xz"),
            None,
            "64-char-but-non-hex hash must be skipped via the \
             ascii-hexdigit check",
        );
        assert_eq!(
            super::parse_sha256_for_file(manifest, "linux-6.14.3.tar.xz")
                .expect("valid entry must parse"),
            "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
        );
    }

    /// `parse_sha256_for_file` strips the PGP signature trailer —
    /// content after `-----BEGIN PGP SIGNATURE-----` is binary
    /// noise that must NOT be scanned for checksum lines (a chance
    /// 64-hex-char run inside a signature would otherwise produce
    /// a false positive).
    #[test]
    fn parse_sha256_for_file_ignores_post_signature_content() {
        // `linux-6.14.99.tar.xz` appears AFTER the signature
        // marker — must be ignored so the parser can't be tricked
        // into returning data from the binary blob.
        let manifest = "\
-----BEGIN PGP SIGNATURE-----
ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff  linux-6.14.99.tar.xz
-----END PGP SIGNATURE-----
";
        assert!(
            super::parse_sha256_for_file(manifest, "linux-6.14.99.tar.xz").is_none(),
            "lines after the signature marker must be invisible to \
             the parser",
        );
    }

    // -- resolve_expected_sha256 --

    /// `resolve_expected_sha256(skip_sha256 = true)` returns `None`
    /// without touching the network — the bypass branch must short-
    /// circuit before any `Client::get`. Pins the security-sensitive
    /// opt-out's no-network contract: a regression that swapped the
    /// branch order (e.g. fetching the manifest then ignoring the
    /// result) would still produce `None` but burn a CDN round-trip
    /// per build, defeating the "use this when manifest is
    /// unreachable" use case.
    #[test]
    fn resolve_expected_sha256_skip_returns_none_without_network() {
        // Build a client whose connect attempt would fail loudly if
        // the bypass branch reached `Client::get`. A 1ms connect
        // timeout against any external host returns within the
        // wall-clock budget of this test; the assertion below
        // observes `None` either way, but a regression would change
        // the test's WALL TIME from ~0ms to ~1ms+. We pin the
        // short-circuit by NOT reaching the network at all — the
        // assertion alone is what catches the regression because
        // the bypass branch never invokes the client.
        let client = test_client();
        let got = super::resolve_expected_sha256(&client, 6, "linux-6.14.2.tar.xz", true);
        assert!(
            got.is_none(),
            "skip_sha256 = true must produce None (verification \
             skipped); got {got:?}"
        );
    }

    /// Mirror of the bypass test against the no-skip arg path with
    /// a tarball name the parser will not match (we substitute the
    /// network call by going through a localhost mock would require
    /// rerouting; instead this test relies on the production
    /// fetch_stable_sha256sums hitting kernel.org over reqwest with
    /// a 5-second timeout — too slow for a unit test). The bypass
    /// branch itself is the security-sensitive surface; the
    /// network-dependent fallback paths are covered by the
    /// `parse_sha256_for_file_*` family above (manifest parsing) and
    /// `fetch_releases_*` family (fetch error handling). Pinning
    /// the no-skip arg path's "does not panic on a malformed
    /// version" property is the most we can do without a network
    /// mock.
    #[test]
    fn resolve_expected_sha256_no_skip_does_not_panic_on_invalid_major() {
        // Calls into fetch_stable_sha256sums which constructs a URL
        // and issues a GET; the network attempt may succeed against
        // kernel.org or fail with timeout. Either way the function
        // must return `Option<String>` without panicking. This is a
        // smoke test only; the full network-dependent fallback path
        // is exercised end-to-end by the integration tests in
        // tests/extra_kconfig_e2e.rs.
        let client = reqwest::blocking::Client::builder()
            .timeout(std::time::Duration::from_millis(1))
            .connect_timeout(std::time::Duration::from_millis(1))
            .build()
            .expect("build test client with tight timeouts");
        // major=999 is a kernel.org URL that returns 404; the
        // function must surface this as None+warning, not panic.
        let _ = super::resolve_expected_sha256(&client, 999, "linux-999.0.0.tar.xz", false);
    }

    // -- verify_sha256 --

    /// Matching digests return Ok regardless of case — pins the
    /// case-insensitive comparison the helper documents.
    #[test]
    fn verify_sha256_accepts_case_insensitive_match() {
        super::verify_sha256(
            "ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890",
            "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
            "https://example.invalid/x.tar.xz",
        )
        .expect("case-insensitive equal must verify");
    }

    /// Mismatching digests surface as Err with both digests in the
    /// message so an operator can compare them by eye without
    /// digging through logs.
    #[test]
    fn verify_sha256_rejects_mismatch_with_both_digests_in_message() {
        let url = "https://example.invalid/x.tar.xz";
        let err = super::verify_sha256(
            "0000000000000000000000000000000000000000000000000000000000000000",
            "1111111111111111111111111111111111111111111111111111111111111111",
            url,
        )
        .expect_err("mismatch must surface as Err");
        let msg = format!("{err:#}");
        assert!(msg.contains(url), "error must name the URL: {msg}");
        assert!(
            msg.contains("0000000000000000"),
            "error must include the actual digest: {msg}",
        );
        assert!(
            msg.contains("1111111111111111"),
            "error must include the expected digest: {msg}",
        );
        // The mismatch error is the only thing the operator sees on
        // a verification-failed download. It MUST name `--skip-sha256`
        // as the recovery path so an operator hitting an in-place
        // tarball update at cdn.kernel.org does not have to dig
        // through docs to find the bypass flag.
        assert!(
            msg.contains("--skip-sha256"),
            "mismatch error must name --skip-sha256 as the recovery \
             flag for the in-place-tarball-update case: {msg}",
        );
    }

    // -- proptest --

    use proptest::prop_assert;

    proptest::proptest! {
        /// Any arbitrary input must not panic AND, on success, return
        /// only values the input string can justify. Broadened from
        /// 0..20 to 0..100 characters to exercise long/multi-dot
        /// pathological inputs the 20-char range missed.
        #[test]
        fn prop_major_version_never_panics(s in "\\PC{0,100}") {
            if let Ok(major) = major_version(&s) {
                // Ok(major) is only valid when the first dot-segment
                // parses as the returned integer.
                let first = s.split('.').next().unwrap_or("");
                prop_assert!(first.parse::<u32>().ok() == Some(major));
            }
        }

        #[test]
        fn prop_is_rc_contains_dash_rc(s in "\\PC{0,20}") {
            assert_eq!(is_rc(&s), s.contains("-rc"));
        }

        #[test]
        fn prop_patch_level_valid_three_part(
            major in 1u32..100,
            minor in 0u32..100,
            patch in 0u32..100,
        ) {
            let v = format!("{major}.{minor}.{patch}");
            assert_eq!(patch_level(&v), Some(patch));
        }

        #[test]
        fn prop_patch_level_valid_two_part(major in 1u32..100, minor in 0u32..100) {
            let v = format!("{major}.{minor}");
            assert_eq!(patch_level(&v), Some(0));
        }

        #[test]
        fn prop_major_version_valid(major in 1u32..100, minor in 0u32..100) {
            let v = format!("{major}.{minor}");
            assert_eq!(major_version(&v).unwrap(), major);
        }
    }
}