deps-core 1.0.0

use std::sync::Arc;
use std::time::Duration;

use tower_lsp_server::ls_types::{Hover, HoverContents, MarkupContent, MarkupKind, Position};

use crate::deps_dev::deps_dev_system;
use crate::licenses::resolve_license_entries_for_display;
use crate::osv::ScanOutcome;
use crate::{
    ConcreteVersion, Dependency, DependencySource, Deprecation, LicenseSource, ParseResult,
    ProvenanceStatus, PublishTime, Registry, SupplyChainTrustSignal, Version, VersionReq,
    format_relative_age, is_within_cooldown,
};

use super::{
    EcosystemFormatter, HOVER_RECENT_VERSIONS, VersionData, escape_markdown, in_use_version,
    markdown_code_span, position_in_range, resolve_in_use_version,
};
use crate::github::normalize_tag;

/// Bounds how long [`generate_hover`] *waits* for the spawned deps.dev trust-signal
/// fetch — never the fetch itself, which keeps running to completion and warms
/// [`crate::deps_dev::DepsDevClient`]'s memo even after this deadline elapses
/// (spec 037, plan.md §8's "spawn-and-warm" design). Deliberately not named
/// `..._TOTAL_...`: merging this with the fetch's own per-call timeouts would
/// silently kill spawn-and-warm — an over-budget fetch would then die entirely
/// instead of finishing into the memo, and the next hover would re-fire it under
/// the short error TTL rather than getting a memo hit.
const DEPS_DEV_WAIT_BUDGET: Duration = Duration::from_millis(700);

/// Formats the relative-age suffix for one "Recent versions" hover entry.
///
/// Returns an empty string when the registry doesn't expose a publish timestamp for
/// `version` (`published_at()` is `None`), so the entry renders exactly as it did
/// before this feature existed (graceful degradation, US-003).
///
/// `now` is taken as an explicit parameter rather than read internally so every entry
/// in the same "Recent versions" list is aged against one consistent instant.
fn version_age_suffix(version: &dyn Version, now: PublishTime) -> String {
    version
        .published_at()
        .map(|published| format!(" — {}", format_relative_age(published.age_secs_from(now))))
        .unwrap_or_default()
}

/// Bounds the `Registry::get_latest_matching` fallback (#373) hover fires when the
/// list-based `**Latest**` pick fails on a non-empty live list. Hover responses must
/// return quickly (`.claude/rules/rust-code.md`), and without this the fallback would
/// stack on top of `get_versions_with`'s own up-to-30s `reqwest` client timeout
/// (`HttpCache`), doubling worst-case hover latency to ~60s. `generate_hover` has no
/// `timeout_secs` config threaded in the way `lifecycle.rs`'s background fetch does, so
/// this is a fixed local bound rather than a configurable one — a few seconds is enough
/// slack for the already-rare "list-based pick failed" path without meaningfully
/// delaying the common case, which never reaches this fallback at all.
const HOVER_FALLBACK_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);

/// The `Cmd+.` update-footer markdown this function appends when a code action may exist
/// for the hovered dependency.
///
/// `pub` (re-exported from `lsp_helpers`) so an ecosystem's own `generate_hover` override
/// can restore it post-hoc for an action source this shared gate has no visibility into
/// (e.g. GHA's `TagIndex`-driven SHA-pin quickfix, #501) without hand-copying the literal
/// and risking drift between the two.
pub const CMD_DOT_FOOTER: &str = "\n---\n⌨️ **Press `Cmd+.` to update version**";

/// Builds the hover response for the dependency under `position`, if any.
///
/// Shared by every ecosystem's default [`crate::ecosystem::Ecosystem::generate_hover`]
/// implementation: locates the dependency whose name or version range contains
/// `position`, resolves its version data against `registry`, and renders the
/// result through `formatter`. Returns `None` when no dependency covers the position.
pub async fn generate_hover<R: Registry + ?Sized>(
    parse_result: &dyn ParseResult,
    position: Position,
    versions: VersionData<'_>,
    registry: &R,
    formatter: &dyn EcosystemFormatter,
    freshness: crate::freshness::FreshnessSettings,
    now: PublishTime,
) -> Option<Hover> {
    let dep = parse_result.dependencies().into_iter().find(|d| {
        // Critic finding S1 (#905): a synthetic `name_range()` (`Dependency::
        // name_range_is_synthetic`) is not a real position — `position_in_range` is inclusive
        // on both ends, so without this guard, hovering the document's very first character
        // (the typical `Range::default()` sentinel) would match whichever such dependency
        // `dependencies()` happens to list first, showing hover info for an arbitrary
        // unrelated package.
        let on_name = !d.name_range_is_synthetic() && position_in_range(position, d.name_range());
        let on_version = d
            .version_range()
            .is_some_and(|r| position_in_range(position, r));
        on_name || on_version
    })?;

    // A non-resolvable source (e.g. `CustomRegistry`, Git, Path) doesn't resolve
    // against `registry` at all — fetching by name here would silently check an
    // unrelated or coincidentally-named public-registry package (#248), so hover
    // must skip the registry lookup and every section built from it entirely.
    // `can_resolve_source` (not the bare `DependencySource::is_version_resolvable`)
    // so an ecosystem whose registry routes more sources than the generic default
    // (e.g. `deps-cargo`'s resolved `AlternateRegistry`) gets hover support for
    // them without a new gate here.
    let dep_source = dep.source();
    let resolvable = formatter.can_resolve_source(&dep_source);

    // Hoisted above the registry fetch below (moved from its previous position
    // right before the `**Current**`/`**Requirement**` line) so the deps.dev gate
    // just below can use it: both need "the normalized name", and the gate must be
    // built and the fetch spawned *before* awaiting the registry fetch so the two
    // requests overlap instead of stacking (spec 037, plan.md §8 M6).
    let normalized_name = formatter.normalize_package_name(dep.name());

    // Spawned concurrently with the registry fetch just below, so a slow or
    // cold-memo deps.dev never adds its own latency on top of the registry fetch's.
    let trust_handle = spawn_trust_signal_fetch(
        dep,
        &dep_source,
        &versions,
        formatter,
        normalized_name.as_str(),
    );

    // `now` is a caller-supplied parameter (issue #227 M4) rather than computed
    // internally via `PublishTime::now()` — this is what lets tests pin an exact
    // cooldown-boundary instant deterministically, and guarantees every age rendered
    // in this single hover response (the `**Latest**` line and the "Recent versions"
    // list below) is aged against the same instant.
    //
    // `.ok()`, not `.ok()?`: a fetch failure here (off-VPN, an expired token, a
    // DNS-blocked internal host — routine for a self-hosted registry's normal users)
    // must degrade to the same basic name/requirement/features card the `!resolvable`
    // branch below renders, not vanish the entire hover response. Propagating `None`
    // out of the whole function on any transient fetch error was a real regression
    // once a resolvable source could be a private index rather than always crates.io.
    let available_versions = if resolvable {
        registry
            .get_versions_from(dep.name(), &dep_source, freshness)
            .await
            .ok()
    } else {
        None
    };

    // FR-014: a resolved-but-not-crates.io source (e.g. Cargo's `AlternateRegistry`) must
    // not carry a link to the ecosystem's *default* registry — once live version data from
    // the real registry renders below, an unrelated link reads as confirmation it's real.
    //
    // `.filter(|u| !u.is_empty())`: an `EcosystemFormatter::package_url` implementation can
    // return an empty string for a dependency name it can't turn into a real URL (e.g. a
    // name that isn't a valid identity for that ecosystem's registry) without also
    // overriding `suppress_package_url` — defense-in-depth so an empty URL can never render
    // as a dead `[name]()` markdown link regardless of which ecosystem forgot the override
    // (#474).
    let url = (!formatter.suppress_package_url(&dep_source))
        .then(|| formatter.package_url(dep.name()))
        .filter(|u| !u.is_empty());

    // Pre-allocate with estimated capacity to reduce allocations
    let mut markdown = String::with_capacity(512);
    push_header_hover_section(&mut markdown, dep, url.as_deref());

    let resolved: Option<&str> = if formatter.manifest_requirement_is_resolved_version(dep) {
        dep.version_requirement().map(VersionReq::as_str)
    } else {
        in_use_version::resolve_occurrence_version(
            dep,
            normalized_name.as_str(),
            versions.resolved,
            versions.resolved_version_candidates,
            formatter,
        )
        .map(ConcreteVersion::as_str)
    };
    push_current_or_requirement_hover_section(&mut markdown, dep, resolved);

    push_markers_hover_section(&mut markdown, dep);

    // The `**Latest**` line prefers the just-fetched Ch2 list (`available_versions`) over
    // the Ch1 cache (`versions.cached`, populated by the lifecycle's background fetch)
    // whenever a live fetch is available. Ch1 alone would let this line render a version
    // older than the one the "Recent versions" list right below it shows as `*(latest)*` —
    // a self-contradictory response when a new version is published between the last
    // background fetch and this hover call, with the cooldown callout then decided off the
    // stale operand too (issue #227 F5). Falls back to Ch1 only when there is no live list
    // at all (non-resolvable source) — NOT merely when the live list has no stable entry:
    // a live list that's all pre-release still means a live fetch happened, and rendering
    // a stale Ch1 version that may not even appear in the live "Recent versions" list below
    // would be exactly the self-contradiction #227 F5 fixed, via a different path (#313).
    //
    // Exception (#373): when the list-based pick fails on a non-empty list, `latest_line`
    // can render a version sourced from `list_fallback_latest` — `Registry::get_latest_matching`
    // instead of the list — which the "Recent versions" list below is built from `available_versions`
    // alone and so may not contain (Go's `/@latest` can answer with a pseudo-version `/@v/list`
    // never enumerates). No entry is marked `*(latest)*` in that case, since `live_latest_idx`
    // is `None`. This is an accepted, narrower trade-off than the contradiction #227 F5/#313
    // guard against: rendering *a* correct latest version, even one absent from or unmarked in
    // the list below, beats rendering no `**Latest**` line at all.
    //
    // `live_latest_idx` (not raw index 0) picks the entry: `available_versions` is sorted
    // purely by version number, so a pre-release with the highest number can sort to index 0
    // even though it isn't the ecosystem's "latest stable" pick — mirroring this line to the
    // raw top entry would tag a pre-release as `(latest)` below. The pick is delegated to
    // `Registry::select_latest_matching` — the exact same call `lifecycle.rs`'s background
    // fetch uses to populate `versions.cached`'s `latest` and every cache-backed diagnostic —
    // rather than re-derived here with a generic `is_stable()` scan. The two must never
    // disagree about what "latest" is: an ecosystem whose `select_latest_matching` applies a
    // ranking preference beyond plain resolvability (e.g. npm's #338 NFR-002, which prefers a
    // non-deprecated version over a newer deprecated one) gets that same preference reflected
    // in this hover response instead of hover independently picking a different version and
    // silently dropping that version's `*(deprecated)*`/`*(yanked)*` label because it thinks
    // it's `(latest)` (#347/#348 S1). Recorded as an index rather than a version string so the
    // "Recent versions" marker below can match by position instead of string equality, which
    // could spuriously tag more than one entry if two ever shared a version string.
    let wildcard_req = crate::existence_wildcard_req();
    let live_latest_idx = available_versions
        .as_ref()
        .and_then(|v| registry.select_latest_matching(v, &wildcard_req));
    // #373: `live_latest_idx` can be `None` even though a live fetch DID happen and the
    // list is non-empty — e.g. Go's `/@v/list` never enumerates pseudo-versions, so an
    // untagged module whose whole tagged history is pre-release fails the list-based pick
    // entirely. This must not fall straight to the Ch1 cache (see the comment on
    // `latest_line` below) — instead mirror the exact fallback `lifecycle.rs`'s background
    // fetch already uses for this same case: a second call to `Registry::get_latest_matching`,
    // which some registries (Go's `/@latest`) answer from a source more complete than the
    // list endpoint. Only attempted for a non-empty live list with no list-based pick; an
    // empty or absent live list keeps falling back to Ch1 untouched. Bounded by
    // `HOVER_FALLBACK_TIMEOUT` and logged like `lifecycle.rs`'s own fallback — a failure,
    // timeout, or `None` here degrades gracefully to no `**Latest**` line, same as today:
    // `available_versions` already succeeded, so this fallback's own error must not abort
    // the rest of the hover.
    let list_fallback_latest = if available_versions.as_ref().is_some_and(|v| !v.is_empty())
        && live_latest_idx.is_none()
    {
        match tokio::time::timeout(
            HOVER_FALLBACK_TIMEOUT,
            registry.get_latest_matching_from(dep.name(), &dep_source, &wildcard_req, None),
        )
        .await
        {
            Ok(Ok(found)) => {
                tracing::debug!(package = %dep.name(), found = found.is_some(), "hover latest fallback (get_latest_matching) resolved");
                found
            }
            Ok(Err(error)) => {
                tracing::warn!(package = %dep.name(), %error, "hover latest fallback (get_latest_matching) failed");
                None
            }
            Err(_) => {
                tracing::warn!(
                    package = %dep.name(),
                    timeout_secs = HOVER_FALLBACK_TIMEOUT.as_secs(),
                    "hover latest fallback (get_latest_matching) timed out"
                );
                None
            }
        }
    } else {
        None
    };
    let cached_latest = resolvable
        .then(|| {
            versions
                .cached
                .get(normalized_name.as_str())
                .or_else(|| versions.cached.get(dep.name()))
        })
        .flatten();
    // A non-empty live list with no stable entry is deliberately treated differently from
    // an empty (or absent) live list: the former tries `list_fallback_latest` (#373) first —
    // a second registry call for the rare "list-based pick failed but a live fetch happened"
    // case — before giving up, rather than falling back to the Ch1 cache, since the cache's
    // version wouldn't be part of what the live list just showed. Only once that fallback
    // also yields nothing does the line render nothing at all (no header, matching the empty
    // "Recent versions" list right beneath it). An empty live list carries no such
    // contradiction risk — it has nothing to contradict — so it keeps falling back to Ch1,
    // same as when there's no live fetch.
    // `select_latest_matching` is overridden per-ecosystem (14 implementations) with no
    // documented in-bounds contract for the index it returns, so `.get(idx)` degrades to
    // the fallback below rather than trusting a cross-crate convention (#673 S2).
    let latest_line: Option<(&str, Option<PublishTime>)> = match &available_versions {
        Some(v) if !v.is_empty() => live_latest_idx
            .and_then(|idx| v.get(idx))
            .map(|live| (live.version_string().as_str(), live.published_at()))
            .or_else(|| {
                list_fallback_latest
                    .as_deref()
                    .map(|live| (live.version_string().as_str(), live.published_at()))
            }),
        _ => cached_latest.map(|v| (v.latest.as_str(), v.published_at)),
    };
    push_latest_hover_section(&mut markdown, latest_line, freshness, now);

    // #394 S2: prefer the version-qualified key so a hover on one occurrence
    // of a duplicated name never shows another occurrence's OSV result. See
    // `crate::osv::vulnerability_keys` for when qualification kicks in.
    let vuln_key = versions.ecosystem.and_then(|ecosystem| {
        crate::osv::vulnerability_keys(
            parse_result,
            versions.resolved,
            versions.resolved_version_candidates,
            formatter,
            ecosystem,
        )
        .remove(&dep.name_range())
    });
    let vuln_outcome = versions.vulnerabilities.and_then(|m| {
        vuln_key
            .as_deref()
            .and_then(|key| m.get(key))
            .or_else(|| m.get(&normalized_name))
            .or_else(|| m.get(dep.name().as_str()))
    });
    let deprecation = versions
        .outcomes
        .and_then(|o| o.deprecation(&normalized_name));
    // Package-level context (#205) renders before per-version security advisories:
    // deprecation is a property of the package, advisories of the version.
    push_deprecation_hover_section(&mut markdown, formatter, deprecation);
    push_vulnerability_hover_section(&mut markdown, vuln_outcome);

    // Awaited last, after every other section above that needed no network I/O of
    // its own, so the wait below overlaps as much of this function's own work as
    // possible — by now `available_versions` has already resolved too. Bounds only
    // the *wait*: over budget, the spawned task above keeps running and warms
    // `DepsDevClient`'s memo regardless (see `DEPS_DEV_WAIT_BUDGET`'s docs). A
    // `JoinHandle` `Err` (the task panicked) is swallowed exactly like a timeout or a
    // fetch failure — FR-006 must hold on this path too, not just the network ones.
    let trust_signal = match trust_handle {
        Some(handle) => match tokio::time::timeout(DEPS_DEV_WAIT_BUDGET, handle).await {
            Ok(Ok(signal)) => signal,
            Ok(Err(_)) | Err(_) => None,
        },
        None => None,
    };
    push_trust_signal_hover_section(&mut markdown, trust_signal.as_ref());

    // Issue #204 (spec 010): resolved-version license first tries the already-fetched
    // `available_versions` list (free for ecosystems whose hot-path version list
    // carries license per entry, e.g. Composer), then falls back to `trust_signal`'s
    // `licenses` (deps.dev-covered ecosystems: Cargo, npm, Go, Maven, Bundler, NuGet,
    // PyPI — the version list itself never carries license for these, live-verified).
    // Latest-version license only ever comes from the native list — deps.dev's
    // version-level call only ever targets the *resolved* version
    // (`spawn_trust_signal_fetch`'s `resolve_in_use_version` argument), so a deps.dev-routed
    // ecosystem's latest license degrades to "(unavailable)", the graceful-degradation
    // edge case spec 010 §6 explicitly sanctions rather than a second network call.
    //
    // The native-list lookup keys on `resolve_in_use_version` (the same helper
    // `spawn_trust_signal_fetch` already uses above), not the weaker `resolved`
    // variable the `**Current**`/`**Requirement**` line uses — `resolve_in_use_version` adds
    // a `concrete_pin_version` fallback for an exact manifest pin with no lock file
    // (e.g. a `composer.json` `"3.0.0"` dependency with no `composer.lock`), which
    // `resolved` alone doesn't have. Falls back to `resolved` when no ecosystem is
    // set (`resolve_in_use_version` requires one) — a handful of test fixtures only
    // (impl-critic review M1: keeps this lookup as least as capable as the
    // deps.dev-routed ecosystems', not just consistent with the Current line).
    let in_use_version_str: Option<String> = versions.ecosystem.and_then(|ecosystem| {
        resolve_in_use_version(
            dep,
            normalized_name.as_str(),
            versions.resolved,
            versions.resolved_version_candidates,
            formatter,
            ecosystem,
        )
    });
    // The single "which concrete version is actually in use" key, shared by the
    // resolved-license lookup below *and* the latest-license "is this the same
    // version" shortcut further down — both must agree on the same key, or the
    // shortcut can miss a version the lookup itself found (review round 3 M1
    // regression: an earlier draft compared the shortcut against the weaker
    // `resolved` while the lookup used this stronger key, reintroducing S1's
    // spurious "unavailable" note for exactly the concrete-pin-no-lockfile case
    // this key exists to cover).
    let resolved_key: Option<&str> = in_use_version_str.as_deref().or(resolved);
    // Drives the `resolve_license_entries_for_display` call below and `license_is_detected`
    // further down — see [`crate::LicenseSource`]'s docs (issue #687/#688).
    let license_source = versions.license_source.unwrap_or_default();
    // `normalize_tag` on both sides, not a plain `==` (impl-critic #664 review,
    // finding S1): a bare pin with no `v` (Composer's `"8.1.6"`) must still match a
    // registry entry whose own version string carries one (Packagist's
    // `symfony/console` tags are `v8.1.6`) — and the reverse, a manifest pin that
    // itself carries `v` (legal npm/Composer syntax) must still match an
    // never-`v`-prefixed registry list.
    let resolved_license: Vec<String> = resolved_key
        .and_then(|r| {
            available_versions.as_ref().and_then(|versions| {
                versions
                    .iter()
                    .find(|v| normalize_tag(v.version_string().as_str()) == normalize_tag(r))
            })
        })
        .map(|v| v.license().to_vec())
        .filter(|l| !l.is_empty())
        .or_else(|| {
            trust_signal
                .as_ref()
                .map(|s| s.licenses.clone())
                .filter(|l| !l.is_empty())
        })
        // Tier 3 (issue #660): Dart/Swift/Gradle/Deno have no deps.dev coverage and no
        // license field in their hot-path version-list response, so the only remaining
        // source is `DocumentState`'s background pre-fetch cache, keyed by the dep's raw
        // (unnormalized) manifest name — see `VersionData::license_prefetch`'s docs.
        // Resolved via `resolve_license_entries_for_display` (issue #687 critic S1/S2),
        // not the policy-evaluation `resolve_license_entries`: a Gradle POM name the
        // normalization table doesn't recognize falls back to its raw text instead of
        // vanishing, and a recognized name keeps only its single canonical id instead of
        // the full policy-matching synonym slice (e.g. the GPL family's three ids).
        .or_else(|| {
            versions
                .license_prefetch
                .and_then(|m| m.get(dep.name()))
                .filter(|raw| !raw.is_empty())
                .map(|raw| resolve_license_entries_for_display(license_source, raw))
        })
        .unwrap_or_default();
    // `None` (no latest version at all — `latest_line` is `None`) is distinct from
    // `Some(&[])` (a latest version exists but its license is unknown): the former
    // must render no note at all, the latter renders "(latest version license
    // unavailable)" (impl-critic S1). When the latest version *is* the resolved
    // version (up to date), reuse `resolved_license` instead of re-deriving it —
    // avoids a spurious "unavailable" note on the single most common hover case.
    // Skipped entirely once `resolved_license` is already empty: nothing to compare
    // against, and `push_license_hover_section` discards it on its own early return.
    //
    // Deliberately has no `license_prefetch` fallback of its own, unlike
    // `resolved_license` above (round 3 finding #6) — "License changed" detection is
    // simply unavailable for a tier-3 dependency when `resolved_key != latest_ver`,
    // not a bug: `license_prefetch` is a single per-*package* (Dart/Swift) or
    // per-*resolved-version* (Gradle/Deno) entry, never a per-*latest-version* one (see
    // `VersionData::license_prefetch`'s doc), so there is no genuine "the latest
    // version's license" data to fall back to here. Reusing the same single value
    // `resolved_license` already fell back to would be actively misleading for
    // Gradle/Deno specifically — it would silently pass off the *resolved* version's
    // license as the *latest* version's, which could suppress a real "License changed"
    // note or fabricate a false "no change" the tier-3 fetch never actually checked.
    let latest_license: Option<Vec<String>> = (!resolved_license.is_empty())
        .then(|| {
            latest_line.map(|(latest_ver, _)| {
                if resolved_key == Some(latest_ver) {
                    resolved_license.clone()
                } else {
                    live_latest_idx
                        .and_then(|idx| available_versions.as_ref().and_then(|v| v.get(idx)))
                        .map(|v| v.license().to_vec())
                        .filter(|l| !l.is_empty())
                        .unwrap_or_default()
                }
            })
        })
        .flatten();
    // Dart's license comes from pub.dev's `/score` best-effort detector tag (pana's own
    // license-detection heuristic, not author-declared registry metadata), and Swift's
    // comes from GitHub's `license.spdx_id` — also detector output (the `licensee` gem
    // GitHub runs against the repo's default branch), not a field the package author
    // declared to a registry (spec 010 plan §1 "Dart source"/"Swift source" rows, NFR-005
    // exception; critic S2). Every other ecosystem's license is a genuine
    // registry-declared field (author's own `Cargo.toml`/`package.json`/POM `<licenses>`
    // entry, or deps.dev's pass-through of the same), so only a `DetectedSpdx` source
    // (Dart, Swift — see [`crate::Ecosystem::license_source`], issue #688) gets the
    // "(detected)" qualifier.
    let license_is_detected = license_source == LicenseSource::DetectedSpdx;
    push_license_hover_section(
        &mut markdown,
        &resolved_license,
        latest_license.as_deref(),
        license_is_detected,
    );

    // `!v.is_empty()`, not just `Some(_)` (#550): a resolvable source's live fetch can
    // succeed with a genuinely empty list — e.g. a real GitHub repository whose only
    // tags don't parse as full semver (`dtolnay/rust-toolchain`'s sole tag `v1`) — and
    // a "**Recent versions**:" header with no entries under it is never useful,
    // regardless of ecosystem.
    if let Some(available_versions) = available_versions.as_ref().filter(|v| !v.is_empty()) {
        push_recent_versions_hover_section(
            &mut markdown,
            available_versions,
            live_latest_idx,
            freshness,
            now,
            formatter,
        );
    }

    push_cmd_dot_footer_hover_section(
        &mut markdown,
        resolvable,
        available_versions.as_deref(),
        cached_latest,
        vuln_outcome,
        deprecation,
        versions.offline,
    );

    push_offline_footer_hover_section(&mut markdown, resolvable, versions.offline);

    Some(Hover {
        contents: HoverContents::Markup(MarkupContent {
            kind: MarkupKind::Markdown,
            value: markdown,
        }),
        range: Some(dep.name_range()),
    })
}

/// Spawns the deps.dev supply-chain trust-signal fetch (spec 037) as a detached
/// background task. Only `handlers/hover.rs` (deps-lsp) ever sets `versions.trust`,
/// which is what makes FR-010's hover-only scope structural: every other surface
/// (diagnostics, code actions, inlay hints, code lenses) is never handed a client and
/// so can never reach deps.dev.
///
/// Gated on all of: a client was handed in, `network.offline` is not set, the source
/// resolves against a **public** registry, the ecosystem is one of the seven
/// `deps_dev_system` maps, and a concrete in-use version exists — the last two
/// checked with **no** network I/O, so an ecosystem `deps_dev_system` excludes
/// (Composer, Dart, Swift, ...) spawns nothing at all.
///
/// `formatter.source_is_public_registry_content(dep_source)`, not the weaker
/// `EcosystemFormatter::can_resolve_source`: that predicate is deliberately widened
/// by some ecosystems (e.g. `deps-cargo`'s `AlternateRegistry`) to cover *any*
/// configured registry, private/internal ones included — reusing it here would send
/// a private package's name and version to deps.dev by default (security audit M2).
/// `source_is_public_registry_content` is the same, stricter predicate this server's
/// other third-party lookup (OSV) already gates on (`lifecycle.rs`).
///
/// `!versions.offline`: every other network-gated hover section [`generate_hover`]
/// builds checks `versions.offline` (the `Cmd+.` footer, the offline footer) —
/// without it here, offline mode still spawns a task per hover and writes a 90s
/// negative memo entry, keeping the signal absent for up to 90s per package after
/// reconnecting for no reason (critic C4).
///
/// `tokio::spawn` panics outside a Tokio runtime — every caller of [`generate_hover`]
/// is `#[tokio::test]`-async or the real LSP server, so this is safe here, but no
/// doc-test may call it directly. The spawned future captures only owned/`'static`
/// data (`Arc<DepsDevClient>`, `&'static str`, owned `String`s) so it satisfies
/// `Send + 'static` with no borrow from `dep`.
fn spawn_trust_signal_fetch(
    dep: &dyn Dependency,
    dep_source: &DependencySource,
    versions: &VersionData<'_>,
    formatter: &dyn EcosystemFormatter,
    normalized_name: &str,
) -> Option<tokio::task::JoinHandle<Option<SupplyChainTrustSignal>>> {
    versions.trust.and_then(|client| {
        let ecosystem = versions.ecosystem?;
        let system = deps_dev_system(ecosystem)?;
        if versions.offline || !formatter.source_is_public_registry_content(dep_source) {
            return None;
        }
        let version = resolve_in_use_version(
            dep,
            normalized_name,
            versions.resolved,
            versions.resolved_version_candidates,
            formatter,
            ecosystem,
        )?;
        let client = Arc::clone(client);
        let name = dep.name().to_string();
        Some(tokio::spawn(async move {
            client.trust_signal(system, &name, &version).await
        }))
    })
}

/// Appends the hover header: the dependency name, linked to its registry page when
/// `url` (from [`crate::lsp_helpers::PackageRendering::package_url`]) is present.
fn push_header_hover_section(markdown: &mut String, dep: &dyn Dependency, url: Option<&str>) {
    use std::fmt::Write as _;

    // `write!` to a `&mut String` via `std::fmt::Write` is infallible — the `Result` is
    // discarded rather than `.unwrap()`ed (#673 M3).
    let _ = match url {
        Some(url) => write!(
            markdown,
            "# [{}]({})\n\n",
            escape_markdown(dep.name().as_str()),
            url
        ),
        None => write!(markdown, "# {}\n\n", escape_markdown(dep.name().as_str())),
    };
}

/// Appends the hover "Current"/"Requirement" line. `resolved` — already selecting
/// between an ecosystem's resolved manifest requirement and the lockfile-resolved
/// version, per [`crate::lsp_helpers::RequirementResolution::manifest_requirement_is_resolved_version`] —
/// wins over the bare manifest requirement when present.
fn push_current_or_requirement_hover_section(
    markdown: &mut String,
    dep: &dyn Dependency,
    resolved: Option<&str>,
) {
    use std::fmt::Write as _;

    // `write!` to a `&mut String` via `std::fmt::Write` is infallible — the `Result` is
    // discarded rather than `.unwrap()`ed (#673 M3).
    if let Some(resolved_ver) = resolved {
        let _ = write!(
            markdown,
            "**Current**: {}\n\n",
            markdown_code_span(resolved_ver)
        );
    } else if let Some(version_req) = dep.version_requirement() {
        let _ = write!(
            markdown,
            "**Requirement**: {}\n\n",
            markdown_code_span(version_req.as_str())
        );
    }
}

/// Appends the hover "Active when" line for an environment-marker-gated dependency
/// (e.g. PEP 508's `python_version >= '3.8'`). Ecosystem-specific; renders nothing
/// when [`Dependency::markers`] is `None`.
fn push_markers_hover_section(markdown: &mut String, dep: &dyn Dependency) {
    use std::fmt::Write as _;

    if let Some(marker_expr) = dep.markers() {
        // `write!` to a `&mut String` via `std::fmt::Write` is infallible — the `Result` is
        // discarded rather than `.unwrap()`ed (#673 M3).
        let _ = write!(
            markdown,
            "**Active when**: {}\n\n",
            markdown_code_span(marker_expr)
        );
    }
}

/// Appends the hover "Latest" line and, when the version is still within the
/// configured cooldown window, the "Recently published" callout beneath it.
///
/// `latest_line` renders nothing when `None` — no header, matching an empty "Recent
/// versions" list below. See [`generate_hover`]'s derivation of `latest_line` for the
/// full Ch1/Ch2/fallback precedence rules (issue #227 F5, #313, #373).
fn push_latest_hover_section(
    markdown: &mut String,
    latest_line: Option<(&str, Option<PublishTime>)>,
    freshness: crate::freshness::FreshnessSettings,
    now: PublishTime,
) {
    use std::fmt::Write as _;

    let Some((latest_ver, raw_published_at)) = latest_line else {
        return;
    };
    let published_at = freshness.enabled.then_some(raw_published_at).flatten();
    let age_secs = published_at.map(|p| p.age_secs_from(now));
    // `write!` to a `&mut String` via `std::fmt::Write` is infallible — the `Result` is
    // discarded rather than `.unwrap()`ed (#673 M3).
    let _ = write!(markdown, "**Latest**: {}", markdown_code_span(latest_ver));
    if let Some(age_secs) = age_secs {
        let _ = write!(markdown, " *(published {})*", format_relative_age(age_secs));
    }
    markdown.push_str("\n\n");
    if age_secs.is_some_and(|age| is_within_cooldown(age, freshness.cooldown_secs)) {
        markdown.push_str(
            "> ⏳ **Recently published** — this release is still within the cooldown window.\n\
             > It may still be yanked or superseded; consider verifying before upgrading.\n\n",
        );
    }
}

/// Appends the "Recent versions" list: up to [`HOVER_RECENT_VERSIONS`] entries drawn from
/// `available_versions`, each optionally aged (freshness-gated) and marked
/// `*(latest)*` at `live_latest_idx` — matched by position against the header's
/// stable-latest pick rather than raw index 0 or string equality: `available_versions`
/// is sorted purely by version number, so index 0 can be a pre-release the header
/// itself doesn't call "latest" (issue #313), and matching by version string instead
/// of index could tag more than one entry if two ever shared a version string.
///
/// If `live_latest_idx` falls outside the raw-order `HOVER_RECENT_VERSIONS`-entry
/// window (e.g. 9+ consecutive pre-releases ahead of the first stable release), the
/// pick is bumped into the window as its final entry instead of being silently
/// dropped from the list — mirroring
/// [`crate::completion::prepare_version_display_items`]'s identical bounded-scan
/// fix for completion/code-actions (#956, #961). Unlike that helper, no separate
/// filter pass is needed first: this list already renders every entry regardless of
/// removal status (flagged ones just gain `formatter.yanked_label()`), so the pick
/// can be looked up by direct index instead of a bounded scan over survivors.
///
/// Renders nothing when `available_versions` is empty (issue #550): an empty
/// "Recent versions" header with no entries under it is never useful.
fn push_recent_versions_hover_section(
    markdown: &mut String,
    available_versions: &[Box<dyn Version>],
    live_latest_idx: Option<usize>,
    freshness: crate::freshness::FreshnessSettings,
    now: PublishTime,
    formatter: &dyn EcosystemFormatter,
) {
    use std::fmt::Write as _;

    if available_versions.is_empty() {
        return;
    }

    let mut entries: Vec<(usize, &Box<dyn Version>)> = available_versions
        .iter()
        .enumerate()
        .take(HOVER_RECENT_VERSIONS)
        .collect();

    if let Some(idx) = live_latest_idx
        && idx >= HOVER_RECENT_VERSIONS
        && let Some(pick) = available_versions.get(idx)
    {
        entries.truncate(HOVER_RECENT_VERSIONS - 1);
        entries.push((idx, pick));
    }

    markdown.push_str("**Recent versions**:\n");
    for (i, version) in entries {
        let version_span = markdown_code_span(version.version_string().as_str());
        let age_suffix = if freshness.enabled {
            version_age_suffix(version.as_ref(), now)
        } else {
            String::new()
        };
        // `writeln!` to a `&mut String` via `std::fmt::Write` is infallible — the `Result`
        // is discarded rather than `.unwrap()`ed (#673 M3).
        if Some(i) == live_latest_idx {
            if version.removal_status().is_flagged() {
                // The resolved "latest" can itself be flagged (e.g. npm's ranking
                // preference falls through to a deprecated version when no clean one
                // exists) — the deprecation/yank warning must not silently vanish just
                // because this entry also carries the `(latest)` marker (#347/#348 S1).
                let _ = writeln!(
                    markdown,
                    "- {version_span} *(latest)* {}{age_suffix}",
                    formatter.yanked_label()
                );
            } else {
                let _ = writeln!(markdown, "- {version_span} *(latest)*{age_suffix}");
            }
        } else if version.removal_status().is_flagged() {
            let _ = writeln!(
                markdown,
                "- {} {}{}",
                version_span,
                formatter.yanked_label(),
                age_suffix
            );
        } else {
            let _ = writeln!(markdown, "- {version_span}{age_suffix}");
        }
    }
}

/// Appends the `Cmd+.` code-action footer — advertised only when a fix action could
/// actually exist for this dependency, since none is ever offered for a source that
/// is deliberately non-resolvable (e.g. a local composite action or a Docker image
/// ref), so rendering it unconditionally is misleading there (#474).
///
/// Gated on `resolvable` alone, not on `available_versions`/`cached_latest` also
/// being populated: a vulnerability-fix or unsatisfiable-fix code action
/// (`code_actions.rs`) can exist from `vuln_outcome` — populated independently of the
/// registry fetch (`lifecycle.rs`) — even when both of those are empty (e.g. a
/// registry fetch failure), so requiring them too would silently drop the footer
/// while `Cmd+.` still offers a fix.
///
/// Also gated on offline data availability (#501): `HttpCache` deliberately serves
/// warm entries while offline (it force-enables caching in that mode), and doc-state
/// fields — vulnerabilities/cached latest/deprecation — survive an online-to-offline
/// transition via `preserve_cache`, so `Cmd+.` can still produce a real
/// REFACTOR/fix/replacement action offline as long as *some* version, vulnerability,
/// or deprecation data was actually rendered above. Only suppress when offline AND
/// none of that data is present — a cold process with nothing cached yet, where no
/// producer in `generate_code_actions` has anything to act on.
///
/// `matches!(vuln_outcome, Some(ScanOutcome::Vulnerable(_)))`, not
/// `vuln_outcome.is_some()` (#501 C5): offline does not skip the OSV scan, it lets it
/// run and fail, which writes `ScanOutcome::Skipped(_)` for every dependency —
/// `is_some()` would be true in exactly #501's own cold-start repro and only
/// `Vulnerable` ever backs `build_vulnerability_fix_action` (`code_actions.rs`).
///
/// A live fetch that genuinely succeeded with zero entries (`Some(&[])`, distinct
/// from `None` — a fetch that errored or never ran, where an unrelated Cmd+. action
/// such as an unsatisfiable-fix might still exist per the reasoning above) is
/// definitive proof there is nothing version-wise to update to (#550): combined with
/// no cached/vulnerability/deprecation data either, the footer would otherwise
/// advertise an action that provably does not exist — the "empty Recent versions
/// section plus a stray footer" bug reported against GHA's
/// `dtolnay/rust-toolchain@stable` but not specific to any one ecosystem. Every other
/// online case (a non-empty live list, or no live fetch at all) keeps the pre-#550
/// unconditional-when-resolvable behavior.
fn push_cmd_dot_footer_hover_section(
    markdown: &mut String,
    resolvable: bool,
    available_versions: Option<&[Box<dyn Version>]>,
    cached_latest: Option<&super::PackageVersions>,
    vuln_outcome: Option<&ScanOutcome>,
    deprecation: Option<&Deprecation>,
    offline: bool,
) {
    let has_offline_actionable_data = available_versions.is_some_and(|v| !v.is_empty())
        || cached_latest.is_some()
        || matches!(vuln_outcome, Some(ScanOutcome::Vulnerable(_)))
        || deprecation.is_some();
    let live_fetch_definitively_empty = available_versions.is_some_and(<[_]>::is_empty);
    let footer_actionable =
        has_offline_actionable_data || (!live_fetch_definitively_empty && !offline);
    if resolvable && footer_actionable {
        markdown.push_str(CMD_DOT_FOOTER);
    }
}

/// Appends the "Offline: version and vulnerability data not checked" footer (issue
/// #483) — the OSV lookup that produced `ScanOutcome::Skipped` for this dependency
/// renders nothing in the vulnerability section, which would otherwise be visually
/// indistinguishable from a scanned, vulnerability-free dependency; this footer calls
/// out that vulnerability data specifically was not checked, not just version data
/// (S2).
///
/// Gated on `resolvable` too, matching the `Cmd+.` footer (#474/#475): a dependency
/// that is never network-resolved under any setting (a local composite action, a
/// Docker image ref, a Git/path dependency) must not claim its version or
/// vulnerability data went unchecked *because of* `network.offline` — nothing there
/// was ever going to be checked regardless.
fn push_offline_footer_hover_section(markdown: &mut String, resolvable: bool, offline: bool) {
    if offline && resolvable {
        markdown.push_str("\n---\n📴 *Offline: version and vulnerability data not checked*");
    }
}

/// Lowercase display label for a [`crate::osv::VulnSeverity`], used only in hover text.
///
/// `Malicious` renders as `"confirmed malicious package"` — deliberately
/// distinct from both `"unknown severity"` (a record this could not grade,
/// carrying no urgency signal of its own) and every graded label
/// (`critical`/`high`/`medium`/`low`), since a confirmed-malicious-package
/// finding is categorically different from a graded-but-uncertain risk.
const fn severity_label(severity: crate::osv::VulnSeverity) -> &'static str {
    match severity {
        crate::osv::VulnSeverity::Critical => "critical",
        crate::osv::VulnSeverity::High => "high",
        crate::osv::VulnSeverity::Medium => "medium",
        crate::osv::VulnSeverity::Low => "low",
        crate::osv::VulnSeverity::Unknown => "unknown severity",
        crate::osv::VulnSeverity::Malicious => "confirmed malicious package",
    }
}

/// Appends the hover "Deprecated" section (issue #205), gated strictly on `deprecation`
/// being present — never rendered as "not deprecated" for a clean package, the same
/// discipline [`push_vulnerability_hover_section`] applies to `Skipped`/`None`.
///
/// Deliberately not deduped against npm's per-row `*(deprecated)*` "Recent versions"
/// labels (S4, plan.md D6): suppressing those would require threading this finding into
/// the version-list renderer, which takes no such parameter today.
fn push_deprecation_hover_section(
    markdown: &mut String,
    formatter: &dyn EcosystemFormatter,
    deprecation: Option<&Deprecation>,
) {
    use std::fmt::Write as _;

    let Some(deprecation) = deprecation else {
        return;
    };

    // I3: each part gets its own blank-line-separated paragraph, mirroring
    // `push_vulnerability_hover_section`'s discipline — three bare consecutive
    // `writeln!` lines with no blank line between them collapse into one CommonMark
    // paragraph, rendering the message/reason/replacement joined instead of as the
    // visually distinct lines the section is meant to show.
    markdown.push_str("### Deprecated\n\n");
    let _ = writeln!(markdown, "{}\n", formatter.deprecated_message());
    if let Some(reason) = deprecation.reason.as_deref().filter(|r| !r.is_empty()) {
        let _ = writeln!(markdown, "{}\n", escape_markdown(reason));
    }
    if let Some(replacement) = deprecation.replacement.as_deref().filter(|r| !r.is_empty()) {
        let _ = writeln!(
            markdown,
            "Suggested replacement: {}\n",
            markdown_code_span(replacement)
        );
    }
}

/// Appends the hover "Security advisories" section, gated strictly on the
/// scan outcome — never on map absence.
///
/// `Vulnerable` gets the advisories list, `Clean` may state the affirmative
/// "no known vulnerabilities", and `Skipped` (or no scan at all) says
/// **nothing**: saying "clean" about a dependency that was never queried is
/// worse than saying nothing at all (`architecture.md` §8 invariant 0).
fn push_vulnerability_hover_section(markdown: &mut String, outcome: Option<&ScanOutcome>) {
    use std::fmt::Write;

    // `writeln!` to a `&mut String` via `std::fmt::Write` is infallible — the `Result` is
    // discarded rather than `.unwrap()`ed (#673 M3).
    match outcome {
        Some(ScanOutcome::Vulnerable(dv)) => {
            markdown.push_str("### Security advisories\n\n");

            for advisory in dv.advisories.items() {
                let _ = writeln!(
                    markdown,
                    "- **[{}]({})** — {}",
                    escape_markdown(&advisory.id),
                    advisory.url,
                    severity_label(advisory.severity)
                );
                let _ = writeln!(
                    markdown,
                    "  {}",
                    escape_markdown(
                        advisory
                            .summary
                            .as_deref()
                            .unwrap_or("(no summary provided)")
                    )
                );

                let mut details = Vec::with_capacity(2);
                if let Some(fixed) = advisory.fixed_versions.last() {
                    details.push(format!("Fixed in: {}", markdown_code_span(fixed)));
                }
                if !advisory.aliases.is_empty() {
                    details.push(format!(
                        "Aliases: {}",
                        escape_markdown(&advisory.aliases.join(", "))
                    ));
                }
                if !details.is_empty() {
                    let _ = writeln!(markdown, "  {}", details.join(" \u{b7} "));
                }
            }

            let remaining = dv.advisories.remaining();
            if remaining > 0 {
                let _ = writeln!(markdown, "- *(+{remaining} more advisories)*");
            }

            if let crate::osv::UpgradeStatus::CandidateVulnerable { version, .. } =
                &dv.upgrade_status
            {
                let _ = writeln!(
                    markdown,
                    "\n\u{26a0}\u{fe0f} Latest version {} is also affected.",
                    markdown_code_span(version)
                );
            }

            markdown.push('\n');
        }
        Some(ScanOutcome::Clean) => {
            markdown.push_str("**No known vulnerabilities** (OSV.dev)\n\n");
        }
        Some(ScanOutcome::Skipped(_)) | None => {}
    }
}

/// Appends the hover "Supply chain" line (spec 037): one line, no `###` header,
/// deliberately lighter than the deprecation/advisory sections above — this signal
/// is informational-only (FR-012) and carries no severity language.
///
/// `signal` is `None` both when no fetch was ever attempted (deps.dev disabled,
/// unsupported ecosystem, no in-use version, ...) and when both deps.dev calls
/// failed or the wait budget elapsed — every case renders nothing, matching
/// FR-006/US-004. A `Some` signal whose scorecard and provenance are *both*
/// `None` (possible only via `SupplyChainTrustSignal::default()`, never returned by
/// `DepsDevClient::trust_signal` itself) also renders nothing, defensively.
fn push_trust_signal_hover_section(markdown: &mut String, signal: Option<&SupplyChainTrustSignal>) {
    use std::fmt::Write;

    let Some(signal) = signal else {
        return;
    };
    if signal.scorecard.is_none() && signal.provenance.is_none() {
        return;
    }

    let mut parts: Vec<String> = Vec::with_capacity(2);
    if let Some(scorecard) = &signal.scorecard {
        let mut part = format!(
            "OpenSSF Scorecard {}/10",
            markdown_code_span(&format!("{:.1}", scorecard.overall_score))
        );
        if scorecard.self_reported {
            part.push_str(" *(self-reported repo)*");
        }
        parts.push(part);
    }
    if let Some(provenance) = signal.provenance {
        let label = match provenance {
            ProvenanceStatus::Verified => "verified",
            ProvenanceStatus::Unverified => "attested but unverified",
            ProvenanceStatus::None => "none found",
        };
        // "Provenance", not "SLSA provenance": `classify_provenance` deliberately unions
        // `slsaProvenances[]` with `attestations[]` (plan-mandated), and an attestation
        // entry's `type` is not necessarily SLSA — labeling every verified entry as SLSA
        // specifically would misrepresent which standard was actually verified for a
        // package whose only verified entry came from `attestations[]` (critic C3).
        parts.push(format!("Provenance: {label}"));
    }

    // `writeln!` to a `&mut String` via `std::fmt::Write` is infallible — the `Result` is
    // discarded rather than `.unwrap()`ed (#673 M3).
    let _ = writeln!(
        markdown,
        "\u{1f510} **Supply chain**: {}",
        parts.join(" \u{b7} ")
    );
    markdown.push('\n');
}

/// Cap on how many license identifiers [`format_license_list`] renders from one
/// version's license list before collapsing the remainder into "(+N more)" —
/// defense-in-depth against a malicious/compromised registry response reporting an
/// excessive number of license entries for a single version (security review S3-1).
const MAX_LICENSE_ENTRIES_RENDERED: usize = 8;

/// Cap on how many characters of a single license identifier
/// [`format_license_list`] renders before truncating it — mirrors
/// `diagnostics::MAX_BLOCKED_REGISTRY_MESSAGE_VALUE_CHARS`'s reasoning for the same
/// untrusted-registry-string concern (security review S3-1).
const MAX_LICENSE_ID_CHARS: usize = 128;

/// Formats a license list as comma-separated Markdown code spans, e.g. `` `MIT`, `Apache-2.0` ``.
/// Each identifier is truncated at [`MAX_LICENSE_ID_CHARS`] and the list itself capped at
/// [`MAX_LICENSE_ENTRIES_RENDERED`] entries (with a "(+N more)" suffix) — `licenses` is
/// registry-reported data, not validated or bounded upstream.
fn format_license_list(licenses: &[String]) -> String {
    let shown = licenses.len().min(MAX_LICENSE_ENTRIES_RENDERED);
    // `shown` is `min(licenses.len(), MAX_LICENSE_ENTRIES_RENDERED)`, always `<= licenses.len()`.
    #[allow(clippy::indexing_slicing)]
    let mut rendered: Vec<String> = licenses[..shown]
        .iter()
        .map(|l| markdown_code_span(&super::truncate_for_diagnostic(l, MAX_LICENSE_ID_CHARS)))
        .collect();
    let remaining = licenses.len() - shown;
    if remaining > 0 {
        rendered.push(format!("(+{remaining} more)"));
    }
    rendered.join(", ")
}

/// Order-insensitive, case-insensitive set comparison for two license lists (spec 010
/// FR-003): a dependency re-declaring the same licenses in a different order or
/// casing (registry `license[]` fields are author-supplied free text, not a
/// normalized enum — e.g. `"MIT"` vs `"mit"`) must not be reported as "changed".
fn license_sets_differ(a: &[String], b: &[String]) -> bool {
    let a_set: std::collections::BTreeSet<String> = a.iter().map(|l| l.to_lowercase()).collect();
    let b_set: std::collections::BTreeSet<String> = b.iter().map(|l| l.to_lowercase()).collect();
    a_set != b_set
}

/// Appends the hover "License" line (issue #204, spec 010): the resolved version's
/// SPDX license identifier(s), and — when the latest version's license is also known
/// and differs (order/case-insensitive) — a "License changed" flag (FR-003).
///
/// `detected` renders the line as "**License (detected)**" instead of "**License**"
/// (issue #660, spec 010 plan §1 "Dart source"/"Swift source" rows, NFR-005 exception;
/// critic S2): Dart's license comes from pub.dev's best-effort `/score` detector tag,
/// and Swift's from GitHub's `licensee`-detected `license.spdx_id`, rather than
/// author-declared registry metadata, so both must be visually distinguished from
/// Gradle/Deno's genuinely registry-declared license fields.
///
/// Renders nothing when `resolved_license` is empty: mirrors
/// [`push_vulnerability_hover_section`]'s discipline of never rendering a positive
/// "License: (unknown)" claim for a dependency this feature never actually checked
/// (no resolved version, an ecosystem/source out of this PR's scope, ...) — spec 010
/// NFR-003 permits either wording or omission for missing data, and omission avoids
/// noise on every dependency this PR simply doesn't cover yet.
///
/// `latest_license` is three-valued (impl-critic review S1): `None` means no latest
/// version exists to compare against at all (no `**Latest**` line was rendered
/// either) — renders no note. `Some(&[])` means a latest version exists but its
/// license could not be determined — renders the "(unavailable)" note. `Some(licenses)`
/// with entries renders a "License changed" flag only when the sets actually differ.
///
/// The "License changed" line is written as its own Markdown paragraph (blank line
/// before it, via `\n\n`) rather than a single `\n` — a lone `\n` is a CommonMark soft
/// break, which strict renderers (e.g. VS Code's hover widget) collapse onto the same
/// visual line as the License line above it (impl-critic review S3).
fn push_license_hover_section(
    markdown: &mut String,
    resolved_license: &[String],
    latest_license: Option<&[String]>,
    detected: bool,
) {
    use std::fmt::Write;

    if resolved_license.is_empty() {
        return;
    }

    // `write!` to a `&mut String` via `std::fmt::Write` is infallible — the `Result` is
    // discarded rather than `.unwrap()`ed (#673 M3).
    let _ = write!(
        markdown,
        "**License{}**: {}",
        if detected { " (detected)" } else { "" },
        format_license_list(resolved_license)
    );

    match latest_license {
        None => {}
        Some([]) => {
            markdown.push_str(" *(latest version license unavailable)*");
        }
        Some(latest) if license_sets_differ(resolved_license, latest) => {
            let _ = write!(
                markdown,
                "\n\n\u{26a0}\u{fe0f} **License changed**: {} \u{2192} {}",
                format_license_list(resolved_license),
                format_license_list(latest)
            );
        }
        Some(_) => {}
    }
    markdown.push_str("\n\n");
}

// #673: fixed test-fixture lengths cast to `u32` for `Position` fixtures never approach
// truncation range; not the request-path cast concern the crate-level `warn` targets.
#[cfg(test)]
#[allow(clippy::cast_possible_truncation)]
mod tests {
    use super::*;
    use crate::RemovalStatus;
    use crate::lsp_helpers::test_support::*;
    use crate::lsp_helpers::*;

    use std::collections::HashMap;
    use std::sync::Arc;

    #[test]
    fn license_sets_differ_is_order_insensitive() {
        let a = vec!["MIT".to_string(), "Apache-2.0".to_string()];
        let b = vec!["Apache-2.0".to_string(), "MIT".to_string()];
        assert!(!license_sets_differ(&a, &b));
    }

    #[test]
    fn license_sets_differ_detects_real_change() {
        let a = vec!["MIT".to_string()];
        let b = vec!["GPL-3.0".to_string()];
        assert!(license_sets_differ(&a, &b));
    }

    /// impl-critic review M2: `license[]` is author-supplied free text, not a
    /// normalized enum — a casing difference alone must not flag a false change.
    #[test]
    fn license_sets_differ_is_case_insensitive() {
        let a = vec!["MIT".to_string()];
        let b = vec!["mit".to_string()];
        assert!(!license_sets_differ(&a, &b));
    }

    #[test]
    fn format_license_list_caps_entries_and_labels_the_remainder() {
        let licenses: Vec<String> = (0..12).map(|i| format!("LICENSE-{i}")).collect();
        let rendered = format_license_list(&licenses);
        assert!(rendered.contains("(+4 more)"), "got: {rendered}");
        assert!(rendered.contains("`LICENSE-0`"));
        assert!(
            !rendered.contains("LICENSE-11"),
            "the 12th entry must not render; got: {rendered}"
        );
    }

    #[test]
    fn format_license_list_truncates_an_overlong_identifier() {
        let long_id = "A".repeat(500);
        let rendered = format_license_list(std::slice::from_ref(&long_id));
        assert!(
            rendered.len() < long_id.len(),
            "an untrusted, excessively long license id must be truncated; got len {}",
            rendered.len()
        );
    }

    #[test]
    fn push_license_hover_section_renders_nothing_when_resolved_unknown() {
        let mut markdown = String::new();
        push_license_hover_section(&mut markdown, &[], Some(&["MIT".to_string()]), false);
        assert!(markdown.is_empty());
    }

    /// impl-critic review S1: no latest version exists at all (`None`, distinct from
    /// `Some(&[])`) — no note should render, since nothing was ever shown to compare
    /// against.
    #[test]
    fn push_license_hover_section_renders_nothing_extra_when_no_latest_version_exists() {
        let mut markdown = String::new();
        push_license_hover_section(&mut markdown, &["MIT".to_string()], None, false);
        assert!(markdown.contains("**License**: `MIT`"));
        assert!(!markdown.contains("unavailable"));
        assert!(!markdown.contains("License changed"));
    }

    #[test]
    fn push_license_hover_section_renders_resolved_only_when_latest_unavailable() {
        let mut markdown = String::new();
        push_license_hover_section(&mut markdown, &["MIT".to_string()], Some(&[]), false);
        assert!(markdown.contains("**License**: `MIT`"));
        assert!(markdown.contains("latest version license unavailable"));
        assert!(!markdown.contains("License changed"));
    }

    #[test]
    fn push_license_hover_section_flags_change_when_licenses_differ() {
        let mut markdown = String::new();
        push_license_hover_section(
            &mut markdown,
            &["MIT".to_string()],
            Some(&["Apache-2.0".to_string()]),
            false,
        );
        assert!(markdown.contains("**License**: `MIT`"));
        assert!(markdown.contains("License changed"));
        assert!(markdown.contains("`MIT` \u{2192} `Apache-2.0`"));
    }

    /// Issue #660: Dart's best-effort detected license must render with the
    /// "(detected)" qualifier, distinguishing it from every other ecosystem's
    /// genuinely registry-declared license field (spec 010 NFR-005 exception).
    #[test]
    fn push_license_hover_section_detected_flag_adds_qualifier() {
        let mut markdown = String::new();
        push_license_hover_section(&mut markdown, &["MIT".to_string()], None, true);
        assert!(markdown.contains("**License (detected)**: `MIT`"));
    }

    /// impl-critic review S3: the "License changed" line must be its own Markdown
    /// paragraph (blank line before it), not a bare `\n` soft break that a strict
    /// CommonMark renderer (VS Code's hover widget) would collapse onto the License
    /// line above it.
    #[test]
    fn push_license_hover_section_change_line_is_a_separate_paragraph() {
        let mut markdown = String::new();
        push_license_hover_section(
            &mut markdown,
            &["MIT".to_string()],
            Some(&["Apache-2.0".to_string()]),
            false,
        );
        assert!(
            markdown.contains("`MIT`\n\n\u{26a0}\u{fe0f} **License changed**"),
            "expected a blank line (paragraph break) before the License changed line; got: {markdown:?}"
        );
    }

    #[test]
    fn push_license_hover_section_no_flag_when_licenses_equal() {
        let mut markdown = String::new();
        push_license_hover_section(
            &mut markdown,
            &["MIT".to_string()],
            Some(&["MIT".to_string()]),
            false,
        );
        assert!(markdown.contains("**License**: `MIT`"));
        assert!(!markdown.contains("License changed"));
        assert!(!markdown.contains("unavailable"));
    }

    /// Issue #204 end-to-end: a native version-list source (Composer/tier-1 shape,
    /// via `MockRegistryWithLicensedVersions`) whose resolved and latest versions
    /// carry different licenses renders both the resolved license and the "License
    /// changed" flag in the actual hover response.
    #[tokio::test]
    async fn test_generate_hover_renders_license_changed_from_native_version_list() {
        use std::collections::HashMap;

        let registry = MockRegistryWithLicensedVersions {
            versions: vec![
                MockVersionWithLicense {
                    version: "2.0.0".into(),
                    license: vec!["Apache-2.0".to_string()],
                },
                MockVersionWithLicense {
                    version: "1.0.0".into(),
                    license: vec!["MIT".to_string()],
                },
            ],
        };
        let parse_result = freshness_test_parse_result("example");
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("example".into(), "1.0.0".into());

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**License**: `MIT`"),
            "got: {}",
            content.value
        );
        assert!(
            content.value.contains("License changed"),
            "resolved (1.0.0/MIT) and latest (2.0.0/Apache-2.0) licenses differ; got: {}",
            content.value
        );
    }

    /// Critic finding S1 (#905): `position_in_range` is inclusive on both ends, so without a
    /// guard, hovering the document's very first character — the typical `Range::default()`
    /// sentinel a synthetic `name_range()` resolves to (e.g. `deps-dart`'s container-anchor
    /// alias resolution) — would match whichever such dependency `dependencies()` lists first,
    /// showing hover info for an arbitrary unrelated package instead of nothing.
    #[tokio::test]
    async fn test_generate_hover_does_not_match_a_synthetic_range_dependency_at_position_zero() {
        use std::collections::HashMap;

        let parse_result = MockMixedParseResult {
            deps: vec![
                Box::new(MockSyntheticRangeDep {
                    name: "synthetic-pkg".into(),
                }),
                Box::new(MockDep {
                    name: "real-pkg".into(),
                    version_req: "1.0.0".into(),
                    version_range: Range::new(Position::new(3, 10), Position::new(3, 20)),
                    name_range: Range::new(Position::new(3, 0), Position::new(3, 8)),
                }),
            ],
            uri: crate::test_util::test_uri("/test/pubspec.yaml"),
        };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 0),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await;

        assert!(
            hover.is_none(),
            "position (0,0) must not match the synthetic-range dependency's \
             Range::default() sentinel"
        );
    }

    /// impl-critic review S1: when the resolved version *is* the latest version (the
    /// common up-to-date case), the resolved license must be reused for the latest
    /// comparison instead of re-deriving it — must render neither a spurious
    /// "(unavailable)" note nor a self-vs-self "License changed" flag.
    #[tokio::test]
    async fn test_generate_hover_up_to_date_dependency_shows_no_spurious_unavailable_note() {
        use std::collections::HashMap;

        let registry = MockRegistryWithLicensedVersions {
            versions: vec![MockVersionWithLicense {
                version: "1.0.0".into(),
                license: vec!["MIT".to_string()],
            }],
        };
        let parse_result = freshness_test_parse_result("example");
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("example".into(), "1.0.0".into());

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(content.value.contains("**License**: `MIT`"));
        assert!(
            !content.value.contains("unavailable"),
            "the resolved version is the latest version, so its already-known license \
             must be reused rather than reported unavailable; got: {}",
            content.value
        );
        assert!(
            !content.value.contains("License changed"),
            "resolved and latest are the same version, so no change flag should fire; got: {}",
            content.value
        );
    }

    /// impl-critic review M1: an exact manifest pin (`=1.0.0`) with no lock-file
    /// resolution renders no `**Current**` line (`resolved` stays `None` —
    /// `resolve_occurrence_version` has nothing to match against an empty
    /// `resolved_versions` map), but the license must still be found via the same
    /// `resolve_in_use_version` concrete-pin fallback `spawn_trust_signal_fetch` already
    /// uses for the deps.dev path — the native-list lookup must be at least as
    /// capable, not silently weaker just because it reused the `resolved` variable.
    #[tokio::test]
    async fn test_generate_hover_native_list_license_found_via_concrete_pin_fallback() {
        use std::collections::HashMap;

        let registry = MockRegistryWithLicensedVersions {
            versions: vec![MockVersionWithLicense {
                version: "1.0.0".into(),
                license: vec!["MIT".to_string()],
            }],
        };
        let parse_result = MockParseResult {
            deps: vec![MockDep {
                name: "example".into(),
                version_req: "=1.0.0".into(),
                version_range: Range::new(Position::new(0, 10), Position::new(0, 20)),
                name_range: Range::new(Position::new(0, 0), Position::new(0, 7)),
            }],
            uri: crate::test_util::test_uri("/test/composer.json"),
        };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new())
                .with_ecosystem(crate::EcosystemId::Composer),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("**Current**"),
            "no lock-file resolution exists, so no Current line should render; got: {}",
            content.value
        );
        assert!(
            content.value.contains("**License**: `MIT`"),
            "the concrete-pin fallback (=1.0.0) should still resolve a license even \
             without a lock-file match; got: {}",
            content.value
        );
    }

    /// Issue #660 (spec 010 plan §1 tier 3): with no license in the native version list
    /// and no deps.dev trust signal, the only remaining source is
    /// `VersionData::license_prefetch` — and for the Dart ecosystem specifically, the
    /// line must carry the "(detected)" qualifier (NFR-005 exception).
    #[tokio::test]
    async fn test_generate_hover_dart_license_from_prefetch_is_labeled_detected() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("example");
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("example".into(), "1.0.0".into());
        let mut licenses = HashMap::new();
        licenses.insert(
            crate::PackageName::new("example"),
            vec!["BSD-3-Clause".to_string()],
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Dart)
                .with_license_source(crate::LicenseSource::DetectedSpdx)
                .with_license_prefetch(&licenses),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains("**License (detected)**: `BSD-3-Clause`"),
            "got: {}",
            content.value
        );
    }

    /// Same tier-3 pre-fetch source as above, for Swift: GitHub's `license.spdx_id` is
    /// `licensee` detector output on the repo's default branch, not an author-declared
    /// registry field, so it must carry the same "(detected)" qualifier as Dart's
    /// pana-detected license (critic S2 — the doc comment previously claiming every
    /// non-Dart source is "author-declared registry metadata" was factually wrong for
    /// Swift specifically).
    #[tokio::test]
    async fn test_generate_hover_swift_license_from_prefetch_is_labeled_detected() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("example");
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("example".into(), "1.0.0".into());
        let mut licenses = HashMap::new();
        licenses.insert(
            crate::PackageName::new("example"),
            vec!["Apache-2.0".to_string()],
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Swift)
                .with_license_source(crate::LicenseSource::DetectedSpdx)
                .with_license_prefetch(&licenses),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains("**License (detected)**: `Apache-2.0`"),
            "got: {}",
            content.value
        );
    }

    /// Tier-3 pre-fetch source for Gradle (a genuine registry-declared POM
    /// `<licenses>` field, not detector output): the license line must render as plain
    /// "**License**", with no "(detected)" qualifier — that label is Dart/Swift-only.
    #[tokio::test]
    async fn test_generate_hover_gradle_license_from_prefetch_is_not_labeled_detected() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("example");
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("example".into(), "1.0.0".into());
        let mut licenses = HashMap::new();
        licenses.insert(
            crate::PackageName::new("example"),
            vec!["Apache-2.0".to_string()],
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Gradle)
                .with_license_source(crate::LicenseSource::PomFreeText)
                .with_license_prefetch(&licenses),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**License**: `Apache-2.0`"),
            "got: {}",
            content.value
        );
        assert!(!content.value.contains("(detected)"));
    }

    /// Issue #687: hover must render the *normalized* SPDX id for a recognized Gradle
    /// POM free-text `<license><name>` value, not the raw POM text — matching what
    /// `generate_diagnostics_from_cache`'s license-policy rule evaluates for the same
    /// dependency (`resolve_license_entries_for_display`, driven by
    /// [`crate::LicenseSource::PomFreeText`], is the single normalization call site both
    /// read through). See the two tests below for the unrecognized-entry and
    /// ambiguous-SPDX-convention cases this function's display semantics diverge from
    /// the policy-evaluation `resolve_license_entries` for (issue #687 critic S1/S2).
    #[tokio::test]
    async fn test_generate_hover_gradle_pom_free_text_license_is_normalized() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("example");
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("example".into(), "1.0.0".into());
        let mut licenses = HashMap::new();
        licenses.insert(
            crate::PackageName::new("example"),
            vec!["The Apache Software License, Version 2.0".to_string()],
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Gradle)
                .with_license_source(crate::LicenseSource::PomFreeText)
                .with_license_prefetch(&licenses),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**License**: `Apache-2.0`"),
            "expected the normalized SPDX id, not raw POM text, got: {}",
            content.value
        );
        assert!(!content.value.contains("The Apache Software License"));
    }

    /// Issue #687 critic S1: a Gradle POM free-text license the normalization table
    /// doesn't recognize must still render *something* in hover — falling back to the
    /// raw POM text — rather than vanishing entirely. `KNOWN_POM_LICENSE_NAMES` is
    /// deliberately non-exhaustive (see `deps_core::licenses`' module docs), so this is
    /// the designed-for path, not a rare edge case: before this fix, routing hover
    /// through the same fail-closed function `generate_diagnostics_from_cache` uses for
    /// policy evaluation dropped the entry and `push_license_hover_section` rendered no
    /// License line at all.
    #[tokio::test]
    async fn test_generate_hover_gradle_unrecognized_pom_license_falls_back_to_raw_text() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("example");
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("example".into(), "1.0.0".into());
        let mut licenses = HashMap::new();
        licenses.insert(
            crate::PackageName::new("example"),
            vec!["Some Bespoke Corporate License".to_string()],
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Gradle)
                .with_license_source(crate::LicenseSource::PomFreeText)
                .with_license_prefetch(&licenses),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains("**License**: `Some Bespoke Corporate License`"),
            "expected the raw POM text as a fallback, got: {}",
            content.value
        );
    }

    /// Issue #687 critic S2: a POM free-text license ambiguous between SPDX conventions
    /// (the GPL/LGPL/AGPL families) normalizes to a multi-id synonym slice for policy
    /// matching (`GPL-3.0`/`GPL-3.0-only`/`GPL-3.0-or-later`, so a `deny`/`allow` list
    /// written in any convention still matches) — but hover must render only the single
    /// canonical id, not all three, since this is genuinely one declared license, not
    /// three.
    #[tokio::test]
    async fn test_generate_hover_gradle_gpl_family_renders_single_canonical_id() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("example");
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("example".into(), "1.0.0".into());
        let mut licenses = HashMap::new();
        licenses.insert(
            crate::PackageName::new("example"),
            vec!["GNU General Public License v3".to_string()],
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Gradle)
                .with_license_source(crate::LicenseSource::PomFreeText)
                .with_license_prefetch(&licenses),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**License**: `GPL-3.0`"),
            "expected exactly one canonical id, got: {}",
            content.value
        );
        assert!(
            !content.value.contains("GPL-3.0-only") && !content.value.contains("GPL-3.0-or-later"),
            "must not render the full policy-matching synonym slice in hover, got: {}",
            content.value
        );
    }

    /// Code-review must-fix: unlike the GPL-family case above, `"CDDL + GPLv2 with
    /// classpath exception"` normalizes to two SPDX ids naming two genuinely different
    /// licenses (`CDDL-1.1` and `GPL-2.0-with-classpath-exception`), not synonyms of
    /// one — collapsing this to a single id would misrepresent a dual-licensed
    /// dependency as solely CDDL-licensed. Both ids must render.
    #[tokio::test]
    async fn test_generate_hover_gradle_disjunctive_license_renders_both_ids() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("example");
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("example".into(), "1.0.0".into());
        let mut licenses = HashMap::new();
        licenses.insert(
            crate::PackageName::new("example"),
            vec!["CDDL + GPLv2 with classpath exception".to_string()],
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Gradle)
                .with_license_source(crate::LicenseSource::PomFreeText)
                .with_license_prefetch(&licenses),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("CDDL-1.1")
                && content.value.contains("GPL-2.0-with-classpath-exception"),
            "expected both disjunctive ids, got: {}",
            content.value
        );
    }

    /// Review round 3 regression: for a deps.dev-routed ecosystem, `available_versions[idx]`
    /// entries never carry license (that trait method's default is empty — only the
    /// native-list ecosystems like Composer override it), so the "latest == resolved"
    /// shortcut MUST use the same `resolve_in_use_version`-derived key the resolved-license
    /// lookup itself used, not the weaker bare `resolved`. An earlier draft compared
    /// the shortcut against `resolved` (which stays `None` here — no lock-file entry
    /// matches an exact `=4.19.2` pin) while the lookup used `in_use_version_str`
    /// (which resolves the pin via `concrete_pin_version`): the mismatch made the
    /// shortcut miss, falling through to the empty-by-default native-list branch and
    /// re-introducing S1's spurious "(latest version license unavailable)" note right
    /// next to an already-known, unchanged license.
    #[tokio::test]
    async fn test_generate_hover_deps_dev_no_lockfile_exact_pin_matching_latest_reuses_license() {
        let (mut server, deps_dev) = deps_dev_mock_client().await;
        let _version = server
            .mock("GET", "/v3/systems/npm/packages/express/versions/4.19.2")
            .with_status(200)
            .with_body(
                r#"{"slsaProvenances": [], "attestations": [], "relatedProjects": [], "licenses": ["MIT"]}"#,
            )
            .create_async()
            .await;
        let deps_dev = Arc::new(deps_dev);

        let parse_result = MockParseResult {
            deps: vec![MockDep {
                name: "express".into(),
                version_req: "=4.19.2".into(),
                version_range: Range::new(Position::new(0, 10), Position::new(0, 20)),
                name_range: Range::new(Position::new(0, 0), Position::new(0, 7)),
            }],
            uri: crate::test_util::test_uri("/test/package.json"),
        };
        // No lock-file entries: `versions.resolved` stays empty, so the bare
        // `resolved` variable used for the `**Current**` line has no match — only
        // `resolve_in_use_version`'s `concrete_pin_version` fallback resolves the pin.
        let registry = MockRegistryWithVersions {
            versions: vec![MockVersionWithAge {
                version: "4.19.2".into(),
                yanked: false,
                published_at: None,
            }],
        };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new())
                .with_ecosystem(crate::EcosystemId::Npm)
                .with_trust(&deps_dev),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("**Current**"),
            "no lock-file resolution exists, so no Current line should render; got: {}",
            content.value
        );
        assert!(
            content.value.contains("**License**: `MIT`"),
            "got: {}",
            content.value
        );
        assert!(
            !content.value.contains("unavailable"),
            "the exact pin (4.19.2) equals the only/live-latest version, so the \
             already-known license must be reused, not reported unavailable; got: {}",
            content.value
        );
        assert!(!content.value.contains("License changed"));
    }

    #[test]
    fn severity_label_for_malicious_is_distinct_from_unknown_and_every_graded_label() {
        let malicious = severity_label(crate::osv::VulnSeverity::Malicious);
        assert_ne!(malicious, "unknown severity");
        for graded in [
            crate::osv::VulnSeverity::Critical,
            crate::osv::VulnSeverity::High,
            crate::osv::VulnSeverity::Medium,
            crate::osv::VulnSeverity::Low,
        ] {
            assert_ne!(malicious, severity_label(graded));
        }
    }

    #[tokio::test]
    async fn test_generate_hover_recent_versions_shows_age_when_known() {
        use std::collections::HashMap;

        let registry = MockRegistryWithVersions {
            versions: vec![MockVersionWithAge {
                version: "1.2.3".into(),
                yanked: false,
                // 2 days ago — safely mid-bucket, immune to sub-second test flakiness.
                published_at: Some(PublishTime::from_unix_secs(
                    PublishTime::now().as_unix_secs() - 2 * 24 * 60 * 60,
                )),
            }],
        };
        let parse_result = freshness_test_parse_result("serde");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("- `1.2.3` *(latest)* — 2 days ago"),
            "got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_recent_versions_omits_age_when_unknown() {
        use std::collections::HashMap;

        let registry = MockRegistryWithVersions {
            versions: vec![MockVersionWithAge {
                version: "1.2.3".into(),
                yanked: false,
                published_at: None,
            }],
        };
        let parse_result = freshness_test_parse_result("serde");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        // Exactly the pre-feature line: no trailing age suffix.
        assert!(content.value.contains("- `1.2.3` *(latest)*\n"));
        assert!(!content.value.contains("ago"));
    }

    #[tokio::test]
    async fn test_generate_hover_latest_marker_skips_prerelease_at_raw_top() {
        use std::collections::HashMap;

        // Raw registry order (newest by version number first): a pre-release sorts above
        // the actual stable latest, mirroring NuGet's Newtonsoft.Json 13.0.5-beta1 vs
        // 13.0.4 (#313).
        let registry = MockRegistryWithVersions {
            versions: vec![
                MockVersionWithAge {
                    version: "13.0.5-beta1".into(),
                    yanked: false,
                    published_at: None,
                },
                MockVersionWithAge {
                    version: "13.0.4".into(),
                    yanked: false,
                    published_at: None,
                },
            ],
        };
        let parse_result = freshness_test_parse_result("Newtonsoft.Json");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**Latest**: `13.0.4`"),
            "got: {}",
            content.value
        );
        assert!(
            content.value.contains("- `13.0.4` *(latest)*"),
            "the stable version, not the raw-top pre-release, should carry the marker; got: {}",
            content.value
        );
        assert!(
            !content.value.contains("13.0.5-beta1` *(latest)*"),
            "the pre-release must not be tagged latest; got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_latest_marker_bumped_in_when_stable_outside_top_n() {
        use std::collections::HashMap;

        // Nine pre-releases followed by one stable version: the stable pick sits past
        // `HOVER_RECENT_VERSIONS`, so it must be bumped into the rendered list's final
        // slot rather than silently dropped (#961).
        let mut versions: Vec<MockVersionWithAge> = (0..=HOVER_RECENT_VERSIONS)
            .map(|i| MockVersionWithAge {
                version: format!("2.0.0-alpha{i}").into(),
                yanked: false,
                published_at: None,
            })
            .collect();
        versions.push(MockVersionWithAge {
            version: "1.9.0".into(),
            yanked: false,
            published_at: None,
        });
        let registry = MockRegistryWithVersions { versions };
        let parse_result = freshness_test_parse_result("example");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**Latest**: `1.9.0`"),
            "got: {}",
            content.value
        );
        assert!(
            content.value.contains("- `1.9.0` *(latest)*"),
            "the stable pick must be bumped into the capped list instead of omitted; got: {}",
            content.value
        );
        assert_eq!(
            content.value.matches("*(latest)*").count(),
            1,
            "exactly one entry should carry the marker; got: {}",
            content.value
        );
        assert_eq!(
            content
                .value
                .lines()
                .filter(|l| l.starts_with("- `"))
                .count(),
            HOVER_RECENT_VERSIONS,
            "the list must stay capped at HOVER_RECENT_VERSIONS entries even after the bump-in; got: {}",
            content.value
        );
        assert!(
            !content.value.contains("2.0.0-alpha7"),
            "the displaced 8th natural entry must not remain in the capped list; got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_latest_marker_at_last_window_slot_not_bumped() {
        use std::collections::HashMap;

        // The stable pick sits exactly at `HOVER_RECENT_VERSIONS - 1` — already the last
        // entry the raw-order window naturally displays — so it must render once, in
        // place, without triggering the bump-in path (boundary just inside the window).
        let mut versions: Vec<MockVersionWithAge> = (0..HOVER_RECENT_VERSIONS - 1)
            .map(|i| MockVersionWithAge {
                version: format!("2.0.0-alpha{i}").into(),
                yanked: false,
                published_at: None,
            })
            .collect();
        versions.push(MockVersionWithAge {
            version: "1.9.0".into(),
            yanked: false,
            published_at: None,
        });
        assert_eq!(versions.len(), HOVER_RECENT_VERSIONS);
        let registry = MockRegistryWithVersions { versions };
        let parse_result = freshness_test_parse_result("example");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert_eq!(
            content.value.matches("- `1.9.0` *(latest)*").count(),
            1,
            "the in-window pick must render exactly once, not duplicated by a bump-in; got: {}",
            content.value
        );
        assert_eq!(
            content
                .value
                .lines()
                .filter(|l| l.starts_with("- `"))
                .count(),
            HOVER_RECENT_VERSIONS,
            "got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_latest_marker_one_past_window_triggers_bump() {
        use std::collections::HashMap;

        // The stable pick sits at exactly `HOVER_RECENT_VERSIONS` — the first index the
        // bump-in path must catch (minimal boundary, one past
        // `test_generate_hover_latest_marker_at_last_window_slot_not_bumped` above).
        let mut versions: Vec<MockVersionWithAge> = (0..HOVER_RECENT_VERSIONS)
            .map(|i| MockVersionWithAge {
                version: format!("2.0.0-alpha{i}").into(),
                yanked: false,
                published_at: None,
            })
            .collect();
        versions.push(MockVersionWithAge {
            version: "1.9.0".into(),
            yanked: false,
            published_at: None,
        });
        assert_eq!(versions.len(), HOVER_RECENT_VERSIONS + 1);
        let registry = MockRegistryWithVersions { versions };
        let parse_result = freshness_test_parse_result("example");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("- `1.9.0` *(latest)*"),
            "the pick at index HOVER_RECENT_VERSIONS must be bumped in; got: {}",
            content.value
        );
        assert!(
            !content
                .value
                .contains(&format!("2.0.0-alpha{}", HOVER_RECENT_VERSIONS - 1)),
            "the displaced last natural entry must not remain in the capped list; got: {}",
            content.value
        );
        assert_eq!(
            content
                .value
                .lines()
                .filter(|l| l.starts_with("- `"))
                .count(),
            HOVER_RECENT_VERSIONS,
            "got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_latest_marker_flagged_pick_bumped_in_keeps_yanked_label() {
        use crate::RemovalStatus;
        use std::collections::HashMap;

        // Hover's "Recent versions" list has no removal-status filter pass (unlike
        // completion's `prepare_version_display_items`), so the bumped-in pick can itself
        // be flagged: eight `Yanked` entries fill the raw-order window, so the registry's
        // 3-rung ranking (`select_latest_for_existence`) falls through to the first
        // non-blocking entry — an `AdvisoryDeprecated` one sitting past the window. The
        // bumped-in entry must render both the `*(latest)*` marker and its flag label
        // together (#961).
        let mut versions: Vec<MockVersionWithStatus> = (0..HOVER_RECENT_VERSIONS)
            .map(|i| MockVersionWithStatus {
                version: format!("5.0.{i}").into(),
                status: RemovalStatus::Yanked,
            })
            .collect();
        versions.push(MockVersionWithStatus {
            version: "5.0.99".into(),
            status: RemovalStatus::AdvisoryDeprecated,
        });
        let registry = MockRegistryPreferringUnflagged { versions };
        let parse_result = freshness_test_parse_result("example");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("- `5.0.99` *(latest)* *(yanked)*"),
            "the bumped-in flagged pick must carry both the latest marker and its flag label; got: {}",
            content.value
        );
        assert!(
            !content.value.contains("5.0.7`"),
            "the displaced last natural entry must not remain in the capped list; got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_latest_marker_all_prerelease_degrades_gracefully() {
        use std::collections::HashMap;

        // No stable version exists anywhere in the list: `find_latest_stable` returns
        // `None`, and there is no Ch1 cache to fall back to either (#313 edge case).
        let registry = MockRegistryWithVersions {
            versions: vec![
                MockVersionWithAge {
                    version: "2.0.0-beta2".into(),
                    yanked: false,
                    published_at: None,
                },
                MockVersionWithAge {
                    version: "2.0.0-beta1".into(),
                    yanked: false,
                    published_at: None,
                },
                MockVersionWithAge {
                    version: "1.9.0-alpha1".into(),
                    yanked: false,
                    published_at: None,
                },
            ],
        };
        let parse_result = freshness_test_parse_result("example");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor, not panic");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("**Latest**:"),
            "no stable version exists, so the header should be omitted rather than picking a pre-release; got: {}",
            content.value
        );
        assert!(
            !content.value.contains("*(latest)*"),
            "no stable version exists, so no entry in the list should be marked latest; got: {}",
            content.value
        );
        assert!(
            content.value.contains("2.0.0-beta2"),
            "the raw version list should still render even without a latest marker; got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_latest_marker_all_prerelease_live_list_ignores_stale_cache() {
        use std::collections::HashMap;

        // A live fetch happened (so `available_versions` is `Some`), but every entry in it
        // is a pre-release: `live_latest_idx` is `None`. A stale Ch1 cache is also present,
        // recording a version that isn't part of the live list at all. Falling back to that
        // stale cached value here would render a `**Latest**` line that contradicts the live
        // "Recent versions" list right below it — exactly the self-contradiction #227 F5 was
        // fixed to prevent, just reached through this all-prerelease path instead (#313 S2).
        let registry = MockRegistryWithVersions {
            versions: vec![MockVersionWithAge {
                version: "2.0.0-beta2".into(),
                yanked: false,
                published_at: None,
            }],
        };
        let parse_result = freshness_test_parse_result("example");
        let mut cached_versions = HashMap::new();
        cached_versions.insert("example".into(), PackageVersions::latest_only("1.5.0"));

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor, not panic");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("**Latest**:"),
            "a live fetch with no stable entry must not fall back to a stale cached version \
             that isn't in the live list; got: {}",
            content.value
        );
        assert!(
            !content.value.contains("1.5.0"),
            "the stale cached version must not leak into the response at all; got: {}",
            content.value
        );
    }

    /// #373: Go's `/@v/list` never enumerates pseudo-versions, so an untagged module whose
    /// entire tagged history is pre-release fails `select_latest_matching`'s list-based pick
    /// even though the live fetch succeeded and returned a non-empty list. Hover must fall
    /// back to `Registry::get_latest_matching` (mirroring `lifecycle.rs`'s background-fetch
    /// fallback, which answers this from Go's `/@latest` endpoint) instead of rendering no
    /// `**Latest**` line at all.
    #[tokio::test]
    async fn test_generate_hover_latest_falls_back_to_get_latest_matching_when_list_pick_fails() {
        use std::collections::HashMap;

        let registry = MockRegistryListFailsLatestFallbackSucceeds {
            versions: vec![MockVersionWithAge {
                version: "v0.0.0-20230101000000-abcdef123456".into(),
                yanked: false,
                published_at: None,
            }],
            fallback_latest: MockVersionWithAge {
                version: "v1.2.3".into(),
                yanked: false,
                published_at: None,
            },
            list_pick_index: None,
            get_latest_matching_calls: std::sync::atomic::AtomicUsize::new(0),
        };
        let parse_result = freshness_test_parse_result("example.com/mod");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**Latest**: `v1.2.3`"),
            "the list-based pick failed, so hover must fall back to get_latest_matching's \
             result instead of omitting the Latest line; got: {}",
            content.value
        );
    }

    /// #373 M4: the fallback must not fire on the common "list-based pick already
    /// succeeded" path — asserted via a call counter on the mock, guarding against a
    /// future regression that would make every hover pay for a second registry round
    /// trip regardless of whether the list-based pick worked.
    #[tokio::test]
    async fn test_generate_hover_does_not_call_fallback_when_list_pick_succeeds() {
        use std::collections::HashMap;
        use std::sync::atomic::Ordering;

        let registry = MockRegistryListFailsLatestFallbackSucceeds {
            versions: vec![MockVersionWithAge {
                version: "v1.2.3".into(),
                yanked: false,
                published_at: None,
            }],
            fallback_latest: MockVersionWithAge {
                version: "v9.9.9".into(),
                yanked: false,
                published_at: None,
            },
            list_pick_index: Some(0),
            get_latest_matching_calls: std::sync::atomic::AtomicUsize::new(0),
        };
        let parse_result = freshness_test_parse_result("example.com/mod");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**Latest**: `v1.2.3`"),
            "expected the list-based pick's own version, not the fallback's; got: {}",
            content.value
        );
        assert_eq!(
            registry.get_latest_matching_calls.load(Ordering::Relaxed),
            0,
            "get_latest_matching must not be called when the list-based pick already succeeded"
        );
    }

    /// Review regression: a fetch failure for a resolvable source (off-VPN, an expired
    /// token, a DNS-blocked internal host — routine for a private-registry user) must
    /// degrade to the basic name/requirement/features card, not vanish the whole hover
    /// response. `.ok()?` on the fetch would have propagated `None` out of the entire
    /// function here; `.ok()` must let `available_versions` become `None` instead.
    #[tokio::test]
    async fn test_generate_hover_renders_basic_card_when_fetch_fails() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("serde");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &ErrorRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover must still render on a fetch failure, not disappear entirely");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("serde"),
            "basic card must still render the package name; got: {}",
            content.value
        );
        assert!(
            !content.value.contains("**Latest**"),
            "no version data is available on a fetch failure; got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_go_prefers_manifest_requirement_over_stale_resolved_version() {
        use std::collections::HashMap;

        let parse_result = MockParseResult {
            deps: vec![MockDep {
                name: "example.com/mod".into(),
                version_req: "v0.8.1".into(),
                version_range: Range::new(Position::new(0, 10), Position::new(0, 20)),
                name_range: Range::new(Position::new(0, 0), Position::new(0, 16)),
            }],
            uri: crate::test_util::test_uri("/test/go.mod"),
        };

        // Stale go.sum entry left behind by a downgrade (#235): go.mod's `require`
        // line was downgraded back to v0.8.1, but the ledger-only go.sum still
        // records the higher v0.9.1 and sorts last, so it would win naive
        // last-occurrence-wins parsing if hover trusted `versions.resolved` here.
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("example.com/mod".into(), "v0.9.1".into());
        let cached_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &MockRegistry,
            &MockGoFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**Current**: `v0.8.1`"),
            "expected hover to show go.mod's pinned version, got: {}",
            content.value
        );
        assert!(
            !content.value.contains("v0.9.1"),
            "hover must not surface the stale go.sum version: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_non_go_formatter_uses_resolved_lockfile_version() {
        use std::collections::HashMap;

        let parse_result = MockParseResult {
            deps: vec![MockDep {
                name: "serde".into(),
                version_req: "1.0.0".into(),
                version_range: Range::new(Position::new(0, 10), Position::new(0, 20)),
                name_range: Range::new(Position::new(0, 0), Position::new(0, 5)),
            }],
            uri: crate::test_util::test_uri("/test/Cargo.toml"),
        };

        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("serde".into(), "1.2.0".into());
        let cached_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        // Non-Go formatters must keep showing the lockfile-resolved version
        // ("1.2.0"), not the raw manifest requirement ("1.0.0") — confirms the Go
        // override does not leak into other ecosystems.
        assert!(
            content.value.contains("**Current**: `1.2.0`"),
            "expected hover to show the resolved lockfile version, got: {}",
            content.value
        );
        assert!(!content.value.contains("**Current**: `1.0.0`"));
    }

    #[tokio::test]
    async fn test_generate_hover_recent_versions_preserves_yanked_marker_with_age() {
        use std::collections::HashMap;

        let registry = MockRegistryWithVersions {
            versions: vec![
                MockVersionWithAge {
                    version: "1.2.3".into(),
                    yanked: false,
                    published_at: None,
                },
                MockVersionWithAge {
                    version: "1.2.1".into(),
                    yanked: true,
                    // ~5 months ago.
                    published_at: Some(PublishTime::from_unix_secs(
                        PublishTime::now().as_unix_secs() - 5 * 30 * 24 * 60 * 60,
                    )),
                },
            ],
        };
        let parse_result = freshness_test_parse_result("serde");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains("- `1.2.1` *(yanked)* — 5 months ago"),
            "got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_recent_versions_respects_freshness_disabled() {
        use std::collections::HashMap;

        let registry = MockRegistryWithVersions {
            versions: vec![MockVersionWithAge {
                version: "1.2.3".into(),
                yanked: false,
                published_at: Some(PublishTime::from_unix_secs(
                    PublishTime::now().as_unix_secs() - 2 * 24 * 60 * 60,
                )),
            }],
        };
        let parse_result = freshness_test_parse_result("serde");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings {
                enabled: false,
                cooldown_secs: crate::freshness::DEFAULT_COOLDOWN_SECS,
            },
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(content.value.contains("- `1.2.3` *(latest)*\n"));
        assert!(!content.value.contains("ago"));
    }

    /// Issue #227 §4.2a: the `**Latest**` line gets a publish-age suffix and, within the
    /// cooldown window, the "Recently published" callout.
    #[tokio::test]
    async fn test_generate_hover_latest_line_shows_age_and_cooldown_callout_when_within_cooldown() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("serde");
        let mut cached_versions = HashMap::new();
        cached_versions.insert(
            "serde".into(),
            PackageVersions {
                latest: "2.0.0".into(),
                available: Arc::from(vec!["2.0.0".into()]),
                yanked: Arc::from(Vec::new()),
                // 1 hour ago — well within the default 3-day cooldown.
                published_at: Some(PublishTime::from_unix_secs(
                    PublishTime::now().as_unix_secs() - 60 * 60,
                )),
            },
        );
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains("**Latest**: `2.0.0` *(published 1 hour ago)*"),
            "got: {}",
            content.value
        );
        assert!(
            content.value.contains(
                "> ⏳ **Recently published** — this release is still within the cooldown window."
            ),
            "got: {}",
            content.value
        );
    }

    /// Same setup, but `latest` was published well outside the cooldown window — the age
    /// suffix still renders, but the callout must not.
    #[tokio::test]
    async fn test_generate_hover_latest_line_no_callout_when_outside_cooldown() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("serde");
        let mut cached_versions = HashMap::new();
        cached_versions.insert(
            "serde".into(),
            PackageVersions {
                latest: "2.0.0".into(),
                available: Arc::from(vec!["2.0.0".into()]),
                yanked: Arc::from(Vec::new()),
                // 10 days ago — outside the default 3-day cooldown.
                published_at: Some(PublishTime::from_unix_secs(
                    PublishTime::now().as_unix_secs() - 10 * 24 * 60 * 60,
                )),
            },
        );
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains("**Latest**: `2.0.0` *(published 1 week ago)*"),
            "got: {}",
            content.value
        );
        assert!(!content.value.contains("Recently published"));
    }

    /// A `latest` with no known publish time renders exactly the pre-feature line — no age
    /// suffix, no callout.
    #[tokio::test]
    async fn test_generate_hover_latest_line_omits_age_when_published_at_unknown() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("serde");
        let mut cached_versions = HashMap::new();
        cached_versions.insert("serde".into(), PackageVersions::latest_only("2.0.0"));
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(content.value.contains("**Latest**: `2.0.0`\n\n"));
        assert!(!content.value.contains("published"));
        assert!(!content.value.contains("Recently published"));
    }

    /// `freshness.enabled: false` suppresses both the age suffix and the cooldown callout
    /// on the `**Latest**` line, even when the publish time would otherwise qualify.
    #[tokio::test]
    async fn test_generate_hover_latest_line_respects_freshness_disabled() {
        use std::collections::HashMap;

        let parse_result = freshness_test_parse_result("serde");
        let mut cached_versions = HashMap::new();
        cached_versions.insert(
            "serde".into(),
            PackageVersions {
                latest: "2.0.0".into(),
                available: Arc::from(vec!["2.0.0".into()]),
                yanked: Arc::from(Vec::new()),
                published_at: Some(PublishTime::from_unix_secs(
                    PublishTime::now().as_unix_secs() - 60 * 60,
                )),
            },
        );
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings {
                enabled: false,
                cooldown_secs: crate::freshness::DEFAULT_COOLDOWN_SECS,
            },
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(content.value.contains("**Latest**: `2.0.0`\n\n"));
        assert!(!content.value.contains("published"));
        assert!(!content.value.contains("Recently published"));
    }

    /// Deterministic boundary test (issue #227 M4): `now` is threaded in as a parameter
    /// rather than read internally, so `published_at`/`now`/`cooldown_secs` can be pinned
    /// to fixed absolute values with no wall-clock dependency. `age == cooldown_secs`
    /// exactly must NOT be within cooldown — the bound is exclusive (`age < cooldown`).
    #[tokio::test]
    async fn test_generate_hover_latest_line_cooldown_boundary_is_exclusive() {
        use std::collections::HashMap;

        const COOLDOWN_SECS: u64 = 100;
        let now = PublishTime::from_unix_secs(10_000);
        let published_at_at_boundary =
            PublishTime::from_unix_secs(10_000 - COOLDOWN_SECS.cast_signed());

        let parse_result = freshness_test_parse_result("serde");
        let mut cached_versions = HashMap::new();
        cached_versions.insert(
            "serde".into(),
            PackageVersions {
                latest: "2.0.0".into(),
                available: Arc::from(vec!["2.0.0".into()]),
                yanked: Arc::from(Vec::new()),
                published_at: Some(published_at_at_boundary),
            },
        );
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings {
                enabled: true,
                cooldown_secs: COOLDOWN_SECS,
            },
            now,
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("Recently published"),
            "age exactly equal to cooldown_secs must not be within cooldown, got: {}",
            content.value
        );
    }

    /// Same fixture, one second younger — must flip to within cooldown.
    #[tokio::test]
    async fn test_generate_hover_latest_line_cooldown_boundary_one_second_inside_shows_callout() {
        use std::collections::HashMap;

        const COOLDOWN_SECS: u64 = 100;
        let now = PublishTime::from_unix_secs(10_000);
        let published_at_just_inside =
            PublishTime::from_unix_secs(10_000 - (COOLDOWN_SECS.cast_signed() - 1));

        let parse_result = freshness_test_parse_result("serde");
        let mut cached_versions = HashMap::new();
        cached_versions.insert(
            "serde".into(),
            PackageVersions {
                latest: "2.0.0".into(),
                available: Arc::from(vec!["2.0.0".into()]),
                yanked: Arc::from(Vec::new()),
                published_at: Some(published_at_just_inside),
            },
        );
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings {
                enabled: true,
                cooldown_secs: COOLDOWN_SECS,
            },
            now,
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("Recently published"),
            "age == cooldown_secs - 1 must be within cooldown, got: {}",
            content.value
        );
    }

    /// Issue #227 F5: the Ch1 cache (`versions.cached`, populated by the lifecycle's
    /// background fetch) can go stale relative to the live Ch2 fetch this same hover call
    /// just made (`registry.get_versions_with`) — e.g. a new version published between the
    /// last background fetch and now. Before this fix, the `**Latest**` line and cooldown
    /// callout read Ch1 alone, so hover could render a self-contradictory response: an
    /// older `**Latest**` line sitting above a "Recent versions" list whose own `*(latest)*`
    /// entry is a newer version. The line must prefer the live entry instead.
    #[tokio::test]
    async fn test_generate_hover_latest_line_prefers_live_fetch_over_stale_ch1_cache() {
        use std::collections::HashMap;

        let now = PublishTime::now();
        let live_latest_published = PublishTime::from_unix_secs(now.as_unix_secs() - 60 * 60);
        let registry = MockRegistryWithVersions {
            versions: vec![
                MockVersionWithAge {
                    version: "1.0.214".into(),
                    yanked: false,
                    published_at: Some(live_latest_published),
                },
                MockVersionWithAge {
                    version: "1.0.213".into(),
                    yanked: false,
                    published_at: Some(PublishTime::from_unix_secs(
                        now.as_unix_secs() - 30 * 24 * 60 * 60,
                    )),
                },
            ],
        };

        let parse_result = freshness_test_parse_result("serde");
        let mut cached_versions = HashMap::new();
        // Stale Ch1 entry: an older version, with an even older publish time, standing in
        // for a background fetch that ran before 1.0.214 was published.
        cached_versions.insert(
            "serde".into(),
            PackageVersions {
                latest: "1.0.213".into(),
                available: Arc::from(vec!["1.0.213".into()]),
                yanked: Arc::from(Vec::new()),
                published_at: Some(PublishTime::from_unix_secs(
                    now.as_unix_secs() - 90 * 24 * 60 * 60,
                )),
            },
        );
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            now,
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains("**Latest**: `1.0.214` *(published 1 hour ago)*"),
            "Latest line must reflect the live Ch2 fetch, not the stale Ch1 cache entry \
             `1.0.213`, got: {}",
            content.value
        );
        assert!(
            !content.value.contains("**Latest**: `1.0.213`"),
            "must not render the stale Ch1 version, got: {}",
            content.value
        );
        assert!(
            content
                .value
                .contains("- `1.0.214` *(latest)* — 1 hour ago"),
            "the Recent versions list's own *(latest)* entry must agree with the Latest \
             line above it, got: {}",
            content.value
        );
    }

    /// #347/#348 S1: npm-shaped package `[2.0.0 AdvisoryDeprecated, 1.9.0 Available]`.
    /// `is_stable()` accepts `AdvisoryDeprecated`, so a naive `is_stable()`-based scan for
    /// "latest" picks `2.0.0` — disagreeing with npm's own `select_latest_matching`, which
    /// deliberately ranks a non-deprecated version ahead of a deprecated one (#338 NFR-002)
    /// and would resolve `1.9.0` instead (this is exactly what `lifecycle.rs` caches and
    /// diagnostics read). Hover must delegate to the registry's `select_latest_matching`
    /// instead of re-deriving the pick, so it agrees with that cached value, and the
    /// resolved `2.0.0`-would-be-latest case below must still carry its deprecated label
    /// when a deprecated version *is* the resolved latest.
    #[tokio::test]
    async fn test_generate_hover_latest_agrees_with_npm_shaped_deprecated_ranking() {
        use std::collections::HashMap;

        let now = PublishTime::now();
        let registry = MockRegistryPreferringUnflagged {
            versions: vec![
                MockVersionWithStatus {
                    version: "2.0.0".into(),
                    status: RemovalStatus::AdvisoryDeprecated,
                },
                MockVersionWithStatus {
                    version: "1.9.0".into(),
                    status: RemovalStatus::Available,
                },
            ],
        };

        let parse_result = freshness_test_parse_result("pkg");
        let cached_versions = HashMap::new();
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            now,
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**Latest**: `1.9.0`"),
            "hover must agree with select_latest_matching's non-deprecated-preferred pick \
             (1.9.0), not a naive is_stable() scan that would pick the newer but deprecated \
             2.0.0, got: {}",
            content.value
        );
        assert!(
            content.value.contains("- `1.9.0` *(latest)*"),
            "the Recent versions list's own *(latest)* marker must agree with the Latest \
             line above it, got: {}",
            content.value
        );
        assert!(
            content.value.contains("- `2.0.0` *(yanked)*"),
            "2.0.0 must keep its flagged label even though it isn't the resolved latest, \
             got: {}",
            content.value
        );
    }

    /// #347/#348 S1: when every version is flagged, the registry's own ranking (rung 2 of
    /// `MockRegistryPreferringUnflagged`) can still resolve a flagged version as "latest" —
    /// hover must keep that entry's deprecated/yanked label instead of letting `*(latest)*`
    /// silently replace it (issue #227-F5/#313's self-contradiction class).
    #[tokio::test]
    async fn test_generate_hover_latest_keeps_flagged_label_when_resolved_version_is_flagged() {
        use std::collections::HashMap;

        let now = PublishTime::now();
        let registry = MockRegistryPreferringUnflagged {
            versions: vec![MockVersionWithStatus {
                version: "2.0.0".into(),
                status: RemovalStatus::AdvisoryDeprecated,
            }],
        };

        let parse_result = freshness_test_parse_result("pkg");
        let cached_versions = HashMap::new();
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            now,
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**Latest**: `2.0.0`"),
            "the only version resolves as latest even though it's flagged, got: {}",
            content.value
        );
        assert!(
            content.value.contains("- `2.0.0` *(latest)* *(yanked)*"),
            "the resolved latest must keep its flagged label instead of the warning \
             silently vanishing behind *(latest)*, got: {}",
            content.value
        );
    }

    /// #364 rung 3: an *all-yanked* package (Cargo/PyPI/Dart-shaped —
    /// `RemovalStatus::Yanked` blocks resolution, unlike npm's `AdvisoryDeprecated`) must
    /// still resolve a "latest" via [`crate::select_latest_for_existence`]'s unconditional
    /// last rung, instead of hover rendering no `**Latest**` line at all (the pre-#364
    /// `None` behavior that read as a false "Unknown package").
    #[tokio::test]
    async fn test_generate_hover_latest_resolves_when_all_versions_yanked() {
        use std::collections::HashMap;

        let now = PublishTime::now();
        let registry = MockRegistryPreferringUnflagged {
            versions: vec![
                MockVersionWithStatus {
                    version: "2.0.0".into(),
                    status: RemovalStatus::Yanked,
                },
                MockVersionWithStatus {
                    version: "1.9.0".into(),
                    status: RemovalStatus::Yanked,
                },
            ],
        };

        let parse_result = freshness_test_parse_result("pkg");
        let cached_versions = HashMap::new();
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            now,
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**Latest**: `2.0.0`"),
            "an all-yanked package still exists: hover must resolve the newest yanked \
             version as latest rather than showing no Latest line, got: {}",
            content.value
        );
        assert!(
            content.value.contains("- `2.0.0` *(latest)* *(yanked)*"),
            "the resolved latest must keep its yanked label, got: {}",
            content.value
        );
    }

    /// npm-shaped formatter stub for T7: overrides `yanked_label` to npm's actual
    /// `"*(deprecated)*"` wording (`deps-npm/src/formatter.rs`), everything else default.
    struct NpmLikeFormatter;

    impl PackageNaming for NpmLikeFormatter {}

    impl PackageRendering for NpmLikeFormatter {
        fn format_version_for_text_edit(&self, version: &ConcreteVersion) -> String {
            version.to_string()
        }

        fn package_url(&self, name: &crate::PackageName) -> String {
            format!("https://example.com/{name}")
        }
    }

    impl RequirementResolution for NpmLikeFormatter {}

    impl DiagnosticMessages for NpmLikeFormatter {
        fn yanked_label(&self) -> &'static str {
            "*(deprecated)*"
        }
    }

    impl DiagnosticPolicy for NpmLikeFormatter {}

    impl SourcePolicy for NpmLikeFormatter {}

    impl OsvNaming for NpmLikeFormatter {}

    /// T7 (S4, accepted redundancy): hover for a deprecated npm-shaped package renders
    /// **both** the new `### Deprecated` section (D6) and the pre-existing per-row
    /// `*(deprecated)*` "Recent versions" labels — pinning the deliberate decision not to
    /// dedupe them (plan.md D6), so a later dedupe reads as an intentional change rather
    /// than a silent regression.
    #[tokio::test]
    async fn test_generate_hover_deprecated_section_and_per_row_labels_both_render() {
        use std::collections::HashMap;

        let now = PublishTime::now();
        let registry = MockRegistryPreferringUnflagged {
            versions: vec![MockVersionWithStatus {
                version: "1.0.0".into(),
                status: RemovalStatus::AdvisoryDeprecated,
            }],
        };

        let parse_result = freshness_test_parse_result("pkg");
        let cached_versions = HashMap::new();
        let resolved_versions = HashMap::new();
        let outcomes = crate::lsp_helpers::DependencyOutcomes::new().with_deprecation(
            "pkg",
            crate::Deprecation {
                reason: Some("no longer maintained".to_string()),
                replacement: None,
            },
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions).with_outcomes(&outcomes),
            &registry,
            &NpmLikeFormatter,
            crate::freshness::FreshnessSettings::default(),
            now,
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("### Deprecated"),
            "expected the package-level Deprecated section, got: {}",
            content.value
        );
        assert!(
            content.value.contains("no longer maintained"),
            "expected the deprecation reason, got: {}",
            content.value
        );
        // I3: the message and the reason must render as separate CommonMark paragraphs
        // (blank-line separated), not collapse into one joined paragraph.
        assert!(
            content
                .value
                .contains("This package is deprecated\n\nno longer maintained"),
            "expected the message and reason on separate paragraphs, got: {}",
            content.value
        );
        assert!(
            content
                .value
                .contains("- `1.0.0` *(latest)* *(deprecated)*"),
            "expected the pre-existing per-row label to still render alongside the new \
             section (deliberately not deduped, S4), got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_surfaces_markers() {
        use std::collections::HashMap;
        use tower_lsp_server::ls_types::{Position, Range};

        let parse_result = MockMarkedParseResult {
            dep: MockMarkedDep {
                name: "numpy".into(),
                name_range: Range::new(Position::new(0, 0), Position::new(0, 5)),
                markers: Some("python_full_version >= '3.9'".to_string()),
            },
            uri: crate::test_util::test_uri("/test/pyproject.toml"),
        };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains("**Active when**: `python_full_version >= '3.9'`")
        );
    }

    #[tokio::test]
    async fn test_generate_hover_omits_active_when_without_markers() {
        use std::collections::HashMap;
        use tower_lsp_server::ls_types::{Position, Range};

        let parse_result = MockMarkedParseResult {
            dep: MockMarkedDep {
                name: "requests".into(),
                name_range: Range::new(Position::new(0, 0), Position::new(0, 8)),
                markers: None,
            },
            uri: crate::test_util::test_uri("/test/pyproject.toml"),
        };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(!content.value.contains("Active when"));
    }

    #[tokio::test]
    async fn test_generate_hover_escapes_malicious_dependency_name() {
        use std::collections::HashMap;
        use tower_lsp_server::ls_types::{Position, Range};

        let malicious_name = "real-pkg](https://legit-looking-typosquat.example/download)[real-pkg";

        let parse_result = MockParseResult {
            deps: vec![MockDep {
                name: malicious_name.into(),
                version_req: "1.0.0".into(),
                version_range: Range::new(Position::new(0, 10), Position::new(0, 20)),
                name_range: Range::new(
                    Position::new(0, 0),
                    Position::new(0, malicious_name.len() as u32),
                ),
            }],
            uri: crate::test_util::test_uri("/test/Cargo.toml"),
        };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };

        // The link label (between the H1's "# [" and the "](") must be the fully
        // escaped name, with no raw "](" sequence that could close the label early
        // and splice in an attacker-controlled markdown link.
        let header_line = content
            .value
            .lines()
            .next()
            .expect("hover markdown has a header line");
        let label = header_line
            .strip_prefix("# [")
            .expect("header starts with link label")
            .split("](")
            .next()
            .expect("header contains label/url separator");
        assert_eq!(
            label,
            r"real\-pkg\]\(https\:\/\/legit\-looking\-typosquat\.example\/download\)\[real\-pkg"
        );
    }

    #[tokio::test]
    async fn test_generate_hover_newline_in_name_cannot_forge_new_heading() {
        use std::collections::HashMap;
        use tower_lsp_server::ls_types::{Position, Range};

        // Combines S1 (newline breaks out of the ATX heading line) with an
        // autolink payload that needs no brackets/parens at all.
        let malicious_name = "react\n# [fake](https://evil.example) <https://evil.example>";

        let parse_result = MockParseResult {
            deps: vec![MockDep {
                name: malicious_name.into(),
                version_req: "1.0.0".into(),
                version_range: Range::new(Position::new(0, 10), Position::new(0, 20)),
                name_range: Range::new(
                    Position::new(0, 0),
                    Position::new(0, malicious_name.len() as u32),
                ),
            }],
            uri: crate::test_util::test_uri("/test/Cargo.toml"),
        };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };

        // The link label must be the exact single-line escaped name: no raw
        // newline breaking the ATX heading, and the autolink's `<`/`>` escaped so
        // it cannot render as a live link independent of the `[]`/`()` escaping.
        let header_line = content
            .value
            .lines()
            .next()
            .expect("hover markdown has a header line");
        let label = header_line
            .strip_prefix("# [")
            .expect("header starts with link label")
            .split("](")
            .next()
            .expect("header contains label/url separator");
        assert_eq!(label, escape_markdown(malicious_name));
        assert!(!label.contains('\n'));
        assert!(label.contains(r"\<https"));
    }

    #[tokio::test]
    async fn test_generate_hover_marker_with_parens_renders_unescaped() {
        use std::collections::HashMap;
        use tower_lsp_server::ls_types::{Position, Range};

        // Regression guard (M4): a legitimate PEP 508 marker with parentheses must
        // render as-is inside its code span, not with visible `\(`/`\)` escapes —
        // backslash-escaping does not apply inside code spans.
        let marker = "python_version >= \"3.8\" and (sys_platform == \"linux\")";
        let parse_result = MockMarkedParseResult {
            dep: MockMarkedDep {
                name: "numpy".into(),
                name_range: Range::new(Position::new(0, 0), Position::new(0, 5)),
                markers: Some(marker.to_string()),
            },
            uri: crate::test_util::test_uri("/test/pyproject.toml"),
        };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains(&format!("**Active when**: `{marker}`"))
        );
    }

    #[tokio::test]
    async fn test_generate_hover_registry_sections_suppressed_for_non_registry_sources() {
        use crate::parser::DependencySource;

        let registry = MockRegistryWithVersions {
            versions: vec![MockVersionWithAge {
                version: "9.9.9".into(),
                yanked: false,
                published_at: None,
            }],
        };
        let cached_versions = {
            let mut m = HashMap::new();
            m.insert("dep".into(), PackageVersions::latest_only("9.9.9"));
            m
        };
        let resolved_versions = HashMap::new();
        let uri = crate::test_util::test_uri("/test/Cargo.toml");

        let parse_result = SingleDepParseResult {
            dep: NonRegistryDep(
                dep_at("dep"),
                DependencySource::CustomRegistry {
                    url: "my-corp".into(),
                },
            ),
            uri: uri.clone(),
        };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should still be generated for a non-resolvable-source dependency");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(!content.value.contains("**Latest**"));
        assert!(!content.value.contains("**Recent versions**"));
        assert!(content.value.contains("**Requirement**"));

        // Control: the same fixture on a Registry-source dependency DOES show
        // both registry-derived sections, proving the fixture isn't vacuous.
        let registry_parse_result = SingleDepParseResult {
            dep: dep_at("dep"),
            uri,
        };
        let hover = generate_hover(
            &registry_parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");
        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(content.value.contains("**Latest**"));
        assert!(content.value.contains("**Recent versions**"));
    }

    #[tokio::test]
    async fn test_generate_hover_clean_outcome_states_no_known_vulnerabilities() {
        use crate::osv::{ScanOutcome, VulnerabilityMap};

        let parse_result = MockParseResult {
            deps: vec![dep_at("clean-pkg")],
            uri: crate::test_util::test_uri("/test/Cargo.toml"),
        };
        let cached_versions = HashMap::new();
        let resolved_versions = HashMap::new();

        let mut vulns: VulnerabilityMap = VulnerabilityMap::new();
        vulns.insert("clean-pkg".to_string(), ScanOutcome::Clean);

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions).with_vulnerabilities(&vulns),
            &MockRegistry,
            &MockFormatter,
            crate::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(content.value.contains("No known vulnerabilities"));
    }

    #[tokio::test]
    async fn test_generate_hover_skipped_outcome_says_nothing_about_vulnerabilities() {
        use crate::osv::{ScanOutcome, SkipReason, VulnerabilityMap};

        let parse_result = MockParseResult {
            deps: vec![dep_at("path-pkg")],
            uri: crate::test_util::test_uri("/test/Cargo.toml"),
        };
        let cached_versions = HashMap::new();
        let resolved_versions = HashMap::new();

        let mut vulns: VulnerabilityMap = VulnerabilityMap::new();
        vulns.insert(
            "path-pkg".to_string(),
            ScanOutcome::Skipped(SkipReason::NonRegistrySource),
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions).with_vulnerabilities(&vulns),
            &MockRegistry,
            &MockFormatter,
            crate::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(!content.value.contains("Security advisories"));
        assert!(!content.value.contains("No known vulnerabilities"));
    }

    #[tokio::test]
    async fn test_generate_hover_vulnerable_outcome_shows_advisories_and_more_count() {
        use crate::osv::{
            Capped, DependencyVulnerabilities, ScanOutcome, UpgradeStatus, VulnSeverity,
            VulnerabilityMap,
        };

        let parse_result = MockParseResult {
            deps: vec![dep_at("bad-pkg")],
            uri: crate::test_util::test_uri("/test/Cargo.toml"),
        };
        let cached_versions = HashMap::new();
        let resolved_versions = HashMap::new();

        let mut vulns: VulnerabilityMap = VulnerabilityMap::new();
        vulns.insert(
            "bad-pkg".to_string(),
            ScanOutcome::Vulnerable(DependencyVulnerabilities {
                advisories: Capped::new(
                    vec![sample_advisory("RUSTSEC-2020-0071", VulnSeverity::Critical)],
                    3,
                ),
                fix_target_status: UpgradeStatus::NotChecked,
                upgrade_status: UpgradeStatus::CandidateVulnerable {
                    version: "2.0.0".into(),
                    advisory_ids: Capped::new(vec!["RUSTSEC-2020-0071".to_string()], 1),
                },
            }),
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions).with_vulnerabilities(&vulns),
            &MockRegistry,
            &MockFormatter,
            crate::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(content.value.contains("Security advisories"));
        assert!(content.value.contains("RUSTSEC-2020-0071"));
        assert!(content.value.contains("Fixed in"));
        assert!(
            content.value.contains("1.5.0"),
            "must show highest fixed version"
        );
        assert!(content.value.contains("+2 more advisories"));
        assert!(content.value.contains("also affected"));
    }

    #[tokio::test]
    async fn test_generate_hover_malicious_advisory_never_renders_unknown_severity() {
        // SC-001: a MAL-* advisory (e.g. the live MAL-2025-47141 record for
        // npm `@ctrl/tinycolor`) must never render as "unknown severity".
        use crate::osv::{
            Capped, DependencyVulnerabilities, ScanOutcome, UpgradeStatus, VulnSeverity,
            VulnerabilityMap,
        };

        let parse_result = MockParseResult {
            deps: vec![dep_at("bad-pkg")],
            uri: crate::test_util::test_uri("/test/Cargo.toml"),
        };
        let cached_versions = HashMap::new();
        let resolved_versions = HashMap::new();

        let mut vulns: VulnerabilityMap = VulnerabilityMap::new();
        vulns.insert(
            "bad-pkg".to_string(),
            ScanOutcome::Vulnerable(DependencyVulnerabilities {
                advisories: Capped::new(
                    vec![sample_advisory("MAL-2025-47141", VulnSeverity::Malicious)],
                    1,
                ),
                fix_target_status: UpgradeStatus::NotChecked,
                upgrade_status: UpgradeStatus::NotChecked,
            }),
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions).with_vulnerabilities(&vulns),
            &MockRegistry,
            &MockFormatter,
            crate::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(content.value.contains("MAL-2025-47141"));
        assert!(content.value.contains("confirmed malicious package"));
        assert!(!content.value.contains("unknown severity"));
    }

    #[tokio::test]
    async fn test_generate_hover_vulnerability_not_shared_across_duplicate_name_occurrences() {
        // #394 S2: `pkg` declared twice with different pins — one vulnerable,
        // one patched. Hover on the patched occurrence must not show the
        // vulnerable occurrence's advisory just because they share a name.
        use crate::osv::{
            Capped, DependencyVulnerabilities, ScanOutcome, UpgradeStatus, VulnSeverity,
            VulnerabilityMap,
        };

        let vulnerable_dep = MockDep {
            name: "pkg".into(),
            version_req: "=1.0.0".into(),
            version_range: Range::new(Position::new(0, 10), Position::new(0, 20)),
            name_range: Range::new(Position::new(0, 0), Position::new(0, 5)),
        };
        let patched_dep = MockDep {
            name: "pkg".into(),
            version_req: "=2.0.0".into(),
            version_range: Range::new(Position::new(3, 10), Position::new(3, 20)),
            name_range: Range::new(Position::new(3, 0), Position::new(3, 5)),
        };
        let parse_result = MockParseResult {
            deps: vec![vulnerable_dep, patched_dep],
            uri: crate::test_util::test_uri("/test/Cargo.toml"),
        };
        let cached_versions = HashMap::new();
        let resolved_versions = HashMap::new();

        let keys = crate::osv::vulnerability_keys(
            &parse_result,
            &resolved_versions,
            None,
            &MockFormatter,
            crate::EcosystemId::Cargo,
        );
        let deps = parse_result.dependencies();
        let vulnerable_key = keys.get(&deps[0].name_range()).unwrap().clone();
        let patched_key = keys.get(&deps[1].name_range()).unwrap().clone();
        assert_ne!(vulnerable_key, patched_key);

        let mut vulns: VulnerabilityMap = VulnerabilityMap::new();
        vulns.insert(
            vulnerable_key,
            ScanOutcome::Vulnerable(DependencyVulnerabilities {
                advisories: Capped::new(
                    vec![sample_advisory("RUSTSEC-2020-0071", VulnSeverity::Critical)],
                    1,
                ),
                fix_target_status: UpgradeStatus::NotChecked,
                upgrade_status: UpgradeStatus::NotChecked,
            }),
        );
        vulns.insert(patched_key, ScanOutcome::Clean);

        let versions = VersionData::new(&cached_versions, &resolved_versions)
            .with_vulnerabilities(&vulns)
            .with_ecosystem(crate::EcosystemId::Cargo);

        let hover_on_patched = generate_hover(
            &parse_result,
            Position::new(3, 2),
            versions,
            &MockRegistry,
            &MockFormatter,
            crate::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");
        let HoverContents::Markup(patched_content) = hover_on_patched.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !patched_content.value.contains("RUSTSEC-2020-0071"),
            "the patched occurrence must not show the other occurrence's advisory: {}",
            patched_content.value
        );
        assert!(patched_content.value.contains("No known vulnerabilities"));

        let hover_on_vulnerable = generate_hover(
            &parse_result,
            Position::new(0, 2),
            versions,
            &MockRegistry,
            &MockFormatter,
            crate::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");
        let HoverContents::Markup(vulnerable_content) = hover_on_vulnerable.contents else {
            panic!("expected markup hover contents");
        };
        assert!(vulnerable_content.value.contains("RUSTSEC-2020-0071"));
    }

    /// Issue #649 US-001/US-002/SC-001/SC-002, end-to-end through `generate_hover` with a
    /// real `resolved_version_candidates` map (the largest gap flagged by the pre-review
    /// test-coverage audit — every prior duplicate-name hover test disambiguated via a
    /// concrete manifest pin, never exercising the lockfile-candidates path). Mirrors the
    /// serde/serde_old rename scenario: both occurrences resolve the name `serde`, one
    /// plain (`"1.0"`) and one renamed to an older major (`"0.9"`); the "Current" line must
    /// show each occurrence's own resolved version (SC-001), and an advisory affecting only
    /// the current major must not leak onto the renamed occurrence's hover (SC-002).
    #[tokio::test]
    async fn test_generate_hover_attributed_via_resolved_version_candidates() {
        use crate::osv::{
            Capped, DependencyVulnerabilities, ScanOutcome, UpgradeStatus, VulnSeverity,
            VulnerabilityMap,
        };

        let current_major = MockDep {
            name: "serde".into(),
            version_req: "1.0".into(),
            version_range: Range::new(Position::new(0, 8), Position::new(0, 13)),
            name_range: Range::new(Position::new(0, 0), Position::new(0, 5)),
        };
        let renamed_old_major = MockDep {
            name: "serde".into(),
            version_req: "0.9".into(),
            version_range: Range::new(Position::new(1, 8), Position::new(1, 13)),
            name_range: Range::new(Position::new(1, 0), Position::new(1, 9)),
        };
        let parse_result = MockParseResult {
            deps: vec![current_major, renamed_old_major],
            uri: crate::test_util::test_uri("/test/Cargo.toml"),
        };
        let cached_versions = HashMap::new();
        let mut resolved_versions = HashMap::new();
        resolved_versions.insert("serde".into(), ConcreteVersion::from("1.0.219"));
        let mut resolved_version_candidates = HashMap::new();
        resolved_version_candidates.insert(
            "serde".into(),
            vec![
                ConcreteVersion::from("0.9.15"),
                ConcreteVersion::from("1.0.219"),
            ],
        );

        let keys = crate::osv::vulnerability_keys(
            &parse_result,
            &resolved_versions,
            Some(&resolved_version_candidates),
            &MockFormatter,
            crate::EcosystemId::Cargo,
        );
        let deps = parse_result.dependencies();
        let current_key = keys.get(&deps[0].name_range()).unwrap().clone();
        let renamed_key = keys.get(&deps[1].name_range()).unwrap().clone();
        assert_ne!(current_key, renamed_key);

        let mut vulns: VulnerabilityMap = VulnerabilityMap::new();
        vulns.insert(
            current_key,
            ScanOutcome::Vulnerable(DependencyVulnerabilities {
                advisories: Capped::new(
                    vec![sample_advisory("RUSTSEC-2020-0071", VulnSeverity::Critical)],
                    1,
                ),
                fix_target_status: UpgradeStatus::NotChecked,
                upgrade_status: UpgradeStatus::NotChecked,
            }),
        );
        vulns.insert(renamed_key, ScanOutcome::Clean);

        let versions = VersionData::new(&cached_versions, &resolved_versions)
            .with_resolved_version_candidates(&resolved_version_candidates)
            .with_vulnerabilities(&vulns)
            .with_ecosystem(crate::EcosystemId::Cargo);

        let hover_on_renamed = generate_hover(
            &parse_result,
            Position::new(1, 2),
            versions,
            &MockRegistry,
            &MockFormatter,
            crate::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");
        let HoverContents::Markup(renamed_content) = hover_on_renamed.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            renamed_content.value.contains("0.9.15"),
            "renamed occurrence must show its own resolved version, not the collapsed 1.0.219: {}",
            renamed_content.value
        );
        assert!(
            !renamed_content.value.contains("RUSTSEC-2020-0071"),
            "the renamed (0.9) occurrence must not show the other occurrence's advisory: {}",
            renamed_content.value
        );
        assert!(renamed_content.value.contains("No known vulnerabilities"));

        let hover_on_current = generate_hover(
            &parse_result,
            Position::new(0, 2),
            versions,
            &MockRegistry,
            &MockFormatter,
            crate::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");
        let HoverContents::Markup(current_content) = hover_on_current.contents else {
            panic!("expected markup hover contents");
        };
        assert!(current_content.value.contains("1.0.219"));
        assert!(current_content.value.contains("RUSTSEC-2020-0071"));
    }

    /// #366, revised by the PR-431 review's Critical finding #3: a registry error
    /// classified as `PackageNotFound` (e.g. `deps-maven`'s `metadata_urls` rejecting a
    /// dot-segment coordinate like `com.example:..`, mirrored here by [`NotFoundRegistry`])
    /// used to make hover return `None` entirely via `.ok()?`. That chain was widened to
    /// plain `.ok()` because a *transient* fetch failure (off-VPN, an expired token, a
    /// DNS-blocked internal host) must degrade to the basic name/requirement/features
    /// card instead of vanishing the whole hover response — a real regression once a
    /// resolvable source could be a private registry rather than always crates.io. A
    /// `PackageNotFound` error takes the same, now-shared path: hover still renders (the
    /// basic card, exactly as the non-resolvable-source branch already produces), just
    /// with no version section — never "a broken hover section built from an empty
    /// version list".
    #[tokio::test]
    async fn test_generate_hover_renders_basic_card_when_registry_reports_not_found() {
        let parse_result = MockParseResult {
            deps: vec![dep_at("com.example:..")],
            uri: crate::test_util::test_uri("/test/pom.xml"),
        };
        let cached_versions = HashMap::new();
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &NotFoundRegistry,
            &MockFormatter,
            crate::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover must still render the basic card on a registry error");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("**Latest**"),
            "no version data is available on a registry error; got: {}",
            content.value
        );
        assert!(
            !content.value.contains("Recent versions"),
            "must not render a broken version section from an empty list; got: {}",
            content.value
        );
    }

    /// #474: the "Press `Cmd+.` to update version" footer advertises a code action that
    /// only exists for a resolvable source with actual version data — a resolvable
    /// `Registry` source with a live (even empty) fetch must still show it.
    #[tokio::test]
    async fn test_generate_hover_footer_shown_for_resolvable_source_with_live_versions() {
        let registry = MockRegistryWithVersions {
            versions: vec![MockVersionWithAge {
                version: "1.2.3".into(),
                yanked: false,
                published_at: None,
            }],
        };
        let parse_result = freshness_test_parse_result("serde");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("Press `Cmd+.` to update version"),
            "a resolvable source with live version data must show the update footer; got: {}",
            content.value
        );
    }

    /// #474: a non-resolvable source (e.g. a local path or a Docker-style URL ref,
    /// mirrored here by `DependencySource::Path`) offers no diagnostic, inlay hint, or
    /// code action — the footer advertising `Cmd+.` must not render for it, even though a
    /// cached `latest` value exists in `versions.cached` (which `resolvable.then(...)`
    /// must gate *before* it ever reaches the footer condition).
    #[tokio::test]
    async fn test_generate_hover_footer_omitted_for_non_resolvable_source() {
        use crate::parser::DependencySource;

        let uri = crate::test_util::test_uri("/test/workflow.yml");
        let parse_result = SingleDepParseResult {
            dep: NonRegistryDep(
                dep_at("local-action"),
                DependencySource::Path {
                    path: "./local-action".into(),
                },
            ),
            uri,
        };
        let cached_versions = {
            let mut m = HashMap::new();
            m.insert("local-action".into(), PackageVersions::latest_only("9.9.9"));
            m
        };
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should still be generated for a non-resolvable-source dependency");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("Press `Cmd+.` to update version"),
            "a non-resolvable source offers no update code action, even with a cached \
             latest value present; got: {}",
            content.value
        );
    }

    /// #501: while `network.offline` is set, `HttpCache` can still serve warm data and
    /// doc-state (`versions.vulnerabilities`/`cached_latest`/deprecation) can still survive
    /// the transition (see `test_generate_hover_footer_shown_when_offline_with_warm_cache_versions`),
    /// so the footer isn't suppressed on `offline` alone — only when offline AND no such
    /// actionable data exists at all. This test is that cold-start case: nothing cached,
    /// nothing resolved, and the OSV scan's own offline failure (`Skipped(QueryFailed)`,
    /// not `Vulnerable`) counts as "no data" too (#501 C5).
    #[tokio::test]
    async fn test_generate_hover_footer_omitted_when_offline_with_no_cached_data() {
        use crate::osv::{ScanOutcome, SkipReason, VulnerabilityMap};

        // Cold process, nothing cached yet (#501's actual repro): the registry fetch fails
        // (offline, no warm `HttpCache` entry) and there is no cached/resolved/deprecation
        // doc state either, so no `generate_code_actions` producer has anything to act on.
        //
        // `vulnerabilities` carries a `Skipped(QueryFailed)` entry rather than being empty
        // (#501 C5): offline doesn't skip the OSV scan, it lets it run and fail, which is
        // exactly what a real offline cold start writes for every dependency — the gate must
        // not treat that `Skipped` presence as an actionable `Vulnerable` outcome.
        let parse_result = freshness_test_parse_result("serde");
        let mut vulns: VulnerabilityMap = VulnerabilityMap::new();
        vulns.insert(
            "serde".to_string(),
            ScanOutcome::Skipped(SkipReason::QueryFailed),
        );

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new())
                .with_offline(true)
                .with_vulnerabilities(&vulns),
            &ErrorRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("Press `Cmd+.` to update version"),
            "no code action can be produced while offline with nothing cached, so the \
             footer must not render; got: {}",
            content.value
        );
        assert!(
            content
                .value
                .contains("📴 *Offline: version and vulnerability data not checked*"),
            "the existing offline notice must still render; got: {}",
            content.value
        );
    }

    /// #501 (impl-critic C1): `HttpCache` deliberately serves warm entries while offline, so
    /// a `Cmd+.` REFACTOR "update to X" action is still genuinely available whenever a live
    /// version list came back — the footer must not be suppressed just because
    /// `versions.offline` is set.
    #[tokio::test]
    async fn test_generate_hover_footer_shown_when_offline_with_warm_cache_versions() {
        let registry = MockRegistryWithVersions {
            versions: vec![MockVersionWithAge {
                version: "1.2.3".into(),
                yanked: false,
                published_at: None,
            }],
        };
        let parse_result = freshness_test_parse_result("serde");

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &HashMap::new()).with_offline(true),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("Press `Cmd+.` to update version"),
            "a warm-cache live version list still offers a real REFACTOR action while \
             offline, so the footer must render; got: {}",
            content.value
        );
    }

    /// Issue #483 I1: the offline footer must render for a resolvable source, mirroring
    /// the `Cmd+.` footer's own `resolvable` gate immediately above it.
    #[tokio::test]
    async fn test_generate_hover_offline_footer_shown_for_resolvable_source() {
        let registry = MockRegistryWithVersions {
            versions: vec![MockVersionWithAge {
                version: "1.2.3".into(),
                yanked: false,
                published_at: None,
            }],
        };
        let parse_result = freshness_test_parse_result("serde");
        let cached = HashMap::new();
        let resolved = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached, &resolved).with_offline(true),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated for a dependency at the cursor");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains("Offline: version and vulnerability data not checked"),
            "a resolvable source must show the offline footer when versions.offline is set; \
             got: {}",
            content.value
        );
    }

    /// Issue #483 I1 (regression guard for the #474/#475 bug class): a non-resolvable
    /// source must never render the offline footer — it was never going to be checked
    /// regardless of `network.offline`, so claiming otherwise is misleading, exactly like
    /// the `Cmd+.` footer this mirrors.
    #[tokio::test]
    async fn test_generate_hover_offline_footer_omitted_for_non_resolvable_source() {
        use crate::parser::DependencySource;

        let uri = crate::test_util::test_uri("/test/workflow.yml");
        let parse_result = SingleDepParseResult {
            dep: NonRegistryDep(
                dep_at("local-action"),
                DependencySource::Path {
                    path: "./local-action".into(),
                },
            ),
            uri,
        };
        let cached_versions = {
            let mut m = HashMap::new();
            m.insert("local-action".into(), PackageVersions::latest_only("9.9.9"));
            m
        };
        let resolved_versions = HashMap::new();

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&cached_versions, &resolved_versions).with_offline(true),
            &MockRegistry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should still be generated for a non-resolvable-source dependency");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("Offline:"),
            "a non-resolvable source must not show the offline footer, even with \
             versions.offline set; got: {}",
            content.value
        );
    }

    // --- Supply-chain trust signal (spec 037) ---

    async fn deps_dev_mock_client() -> (mockito::ServerGuard, crate::DepsDevClient) {
        let server = mockito::Server::new_async().await;
        let client =
            crate::DepsDevClient::for_test(Arc::new(crate::HttpCache::new()), server.url());
        (server, client)
    }

    /// A single dependency (`express@4.19.2`) whose in-use version resolves via
    /// `resolved_versions`, ready to attach to `VersionData::with_trust`.
    fn express_fixture() -> (
        MockParseResult,
        HashMap<crate::PackageName, ConcreteVersion>,
    ) {
        let parse_result = freshness_test_parse_result("express");
        let resolved_versions = HashMap::from([(
            crate::PackageName::new("express"),
            ConcreteVersion::new("4.19.2"),
        )]);
        (parse_result, resolved_versions)
    }

    /// SC-001, pinned to the deterministic path per critic N4: the mock responds
    /// instantly, so `generate_hover`'s `DEPS_DEV_WAIT_BUDGET` await reliably
    /// completes well within budget rather than depending on a cold-memo race.
    #[tokio::test]
    async fn test_generate_hover_trust_signal_renders_score_and_verified_provenance() {
        let (mut server, deps_dev) = deps_dev_mock_client().await;
        let _version = server
            .mock("GET", "/v3/systems/npm/packages/express/versions/4.19.2")
            .with_status(200)
            .with_body(
                r#"{"slsaProvenances": [{"verified": true}], "attestations": [], "relatedProjects": [
                    {"projectKey": {"id": "github.com/expressjs/express"}, "relationType": "SOURCE_REPO", "relationProvenance": "SLSA_ATTESTATION"}
                ]}"#,
            )
            .create_async()
            .await;
        let _project = server
            .mock("GET", "/v3/projects/github.com%2Fexpressjs%2Fexpress")
            .with_status(200)
            .with_body(r#"{"scorecard": {"overallScore": 8.5}}"#)
            .create_async()
            .await;
        let deps_dev = Arc::new(deps_dev);

        let (parse_result, resolved_versions) = express_fixture();
        let registry = MockRegistryWithVersions { versions: vec![] };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Npm)
                .with_trust(&deps_dev),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        let line = content
            .value
            .lines()
            .find(|l| l.contains("Supply chain"))
            .unwrap_or_else(|| panic!("expected a Supply chain line, got: {}", content.value));
        insta::assert_snapshot!(line, @"🔐 **Supply chain**: OpenSSF Scorecard `8.5`/10 · Provenance: verified");
    }

    /// Issue #204 (impl-critic review S2 / tester's independent gap): the deps.dev
    /// path is the *only* license source for 7 of this PR's 8 ecosystems
    /// (Cargo/npm/Go/Maven/Bundler/NuGet/PyPI) — only Composer's native-list path had
    /// an end-to-end `generate_hover` test before this one.
    #[tokio::test]
    async fn test_generate_hover_deps_dev_license_renders_license_line() {
        let (mut server, deps_dev) = deps_dev_mock_client().await;
        let _version = server
            .mock("GET", "/v3/systems/npm/packages/express/versions/4.19.2")
            .with_status(200)
            .with_body(
                r#"{"slsaProvenances": [], "attestations": [], "relatedProjects": [], "licenses": ["MIT"]}"#,
            )
            .create_async()
            .await;
        let deps_dev = Arc::new(deps_dev);

        let (parse_result, resolved_versions) = express_fixture();
        let registry = MockRegistryWithVersions { versions: vec![] };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Npm)
                .with_trust(&deps_dev),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("**License**: `MIT`"),
            "expected the deps.dev-sourced license to render; got: {}",
            content.value
        );
        // No live version list was fetched (`MockRegistryWithVersions { versions: vec![] }`),
        // so no `**Latest**` line exists either — the "(latest version license
        // unavailable)" note must not render for a dependency with no latest version
        // at all (impl-critic review S1).
        assert!(
            !content.value.contains("unavailable"),
            "no latest version exists to compare against; got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_trust_signal_unverified_provenance() {
        let (mut server, deps_dev) = deps_dev_mock_client().await;
        let _version = server
            .mock("GET", "/v3/systems/npm/packages/express/versions/4.19.2")
            .with_status(200)
            .with_body(
                r#"{"slsaProvenances": [{"verified": false}], "attestations": [], "relatedProjects": []}"#,
            )
            .create_async()
            .await;
        let deps_dev = Arc::new(deps_dev);

        let (parse_result, resolved_versions) = express_fixture();
        let registry = MockRegistryWithVersions { versions: vec![] };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Npm)
                .with_trust(&deps_dev),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content
                .value
                .contains("Provenance: attested but unverified"),
            "got: {}",
            content.value
        );
    }

    #[tokio::test]
    async fn test_generate_hover_trust_signal_none_provenance_and_self_reported_marker() {
        let (mut server, deps_dev) = deps_dev_mock_client().await;
        let _version = server
            .mock("GET", "/v3/systems/npm/packages/express/versions/4.19.2")
            .with_status(200)
            .with_body(
                r#"{"slsaProvenances": [], "attestations": [], "relatedProjects": [
                    {"projectKey": {"id": "github.com/expressjs/express"}, "relationType": "SOURCE_REPO", "relationProvenance": "UNVERIFIED_METADATA"}
                ]}"#,
            )
            .create_async()
            .await;
        let _project = server
            .mock("GET", "/v3/projects/github.com%2Fexpressjs%2Fexpress")
            .with_status(200)
            .with_body(r#"{"scorecard": {"overallScore": 7.2}}"#)
            .create_async()
            .await;
        let deps_dev = Arc::new(deps_dev);

        let (parse_result, resolved_versions) = express_fixture();
        let registry = MockRegistryWithVersions { versions: vec![] };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Npm)
                .with_trust(&deps_dev),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("Provenance: none found"),
            "got: {}",
            content.value
        );
        assert!(
            content.value.contains("*(self-reported repo)*"),
            "an UNVERIFIED_METADATA-only relation must be disclosed; got: {}",
            content.value
        );
    }

    /// SC-004: every ecosystem `deps_dev_system` does not cover (not just
    /// Composer) must issue zero deps.dev requests — checked before any
    /// spawn, per plan.md §8's gate.
    #[tokio::test]
    async fn test_generate_hover_trust_signal_skips_uncovered_ecosystems() {
        for ecosystem in [
            crate::EcosystemId::Composer,
            crate::EcosystemId::Dart,
            crate::EcosystemId::Swift,
        ] {
            let (mut server, deps_dev) = deps_dev_mock_client().await;
            let never_called = server
                .mock("GET", mockito::Matcher::Regex("^/v3/.*".into()))
                .expect(0)
                .create_async()
                .await;
            let deps_dev = Arc::new(deps_dev);

            let (parse_result, resolved_versions) = express_fixture();
            let registry = MockRegistryWithVersions { versions: vec![] };

            let hover = generate_hover(
                &parse_result,
                Position::new(0, 2),
                VersionData::new(&HashMap::new(), &resolved_versions)
                    .with_ecosystem(ecosystem)
                    .with_trust(&deps_dev),
                &registry,
                &MockFormatter,
                crate::freshness::FreshnessSettings::default(),
                PublishTime::now(),
            )
            .await
            .expect("hover should be generated");

            let HoverContents::Markup(content) = hover.contents else {
                panic!("expected markup hover contents");
            };
            assert!(
                !content.value.contains("Supply chain"),
                "{ecosystem:?}: got: {}",
                content.value
            );
            never_called.assert_async().await;
        }
    }

    /// Regression for security M2 / critic C2: a private/non-mirror
    /// `AlternateRegistry` source must never reach deps.dev, even though it
    /// resolves against this ecosystem's own registry (`resolvable` alone
    /// is the wrong, too-permissive gate — see
    /// `MockWidenedResolveFormatter`'s docs).
    #[tokio::test]
    async fn test_generate_hover_trust_signal_skips_private_registry_source() {
        let (mut server, deps_dev) = deps_dev_mock_client().await;
        let never_called = server
            .mock("GET", mockito::Matcher::Regex("^/v3/.*".into()))
            .expect(0)
            .create_async()
            .await;
        let deps_dev = Arc::new(deps_dev);

        let parse_result = SingleDepParseResult {
            dep: NonRegistryDep(
                dep_at("internal-pkg"),
                crate::parser::DependencySource::AlternateRegistry {
                    index: "https://index.mycorp.internal".to_string(),
                    mirrors_crates_io: false,
                },
            ),
            uri: crate::test_util::test_uri("/test/Cargo.toml"),
        };
        let resolved_versions = HashMap::from([(
            crate::PackageName::new("internal-pkg"),
            ConcreteVersion::new("1.0.0"),
        )]);
        let registry = MockRegistryWithVersions { versions: vec![] };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Cargo)
                .with_trust(&deps_dev),
            &registry,
            &MockWidenedResolveFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("Supply chain"),
            "a private registry's package name/version must never reach deps.dev; got: {}",
            content.value
        );
        never_called.assert_async().await;
    }

    /// Regression for review C4 / critic C4: `versions.offline` must be
    /// checked in the same gate as every other network-gated hover section
    /// — offline must not spawn a task or write a negative memo entry.
    #[tokio::test]
    async fn test_generate_hover_trust_signal_skips_when_offline() {
        let (mut server, deps_dev) = deps_dev_mock_client().await;
        let never_called = server
            .mock("GET", mockito::Matcher::Regex("^/v3/.*".into()))
            .expect(0)
            .create_async()
            .await;
        let deps_dev = Arc::new(deps_dev);

        let (parse_result, resolved_versions) = express_fixture();
        let registry = MockRegistryWithVersions { versions: vec![] };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Npm)
                .with_trust(&deps_dev)
                .with_offline(true),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !content.value.contains("Supply chain"),
            "got: {}",
            content.value
        );
        never_called.assert_async().await;
    }

    /// SC-003: a deps.dev outage must leave every other hover section
    /// byte-identical to a hover generated with no trust client at all.
    #[tokio::test]
    async fn test_generate_hover_trust_signal_failure_leaves_other_content_unchanged() {
        let (mut server, deps_dev) = deps_dev_mock_client().await;
        let _version = server
            .mock("GET", "/v3/systems/npm/packages/express/versions/4.19.2")
            .with_status(500)
            .create_async()
            .await;
        let deps_dev = Arc::new(deps_dev);

        let (parse_result, resolved_versions) = express_fixture();
        let registry = MockRegistryWithVersions {
            versions: vec![MockVersionWithAge {
                version: "4.19.2".into(),
                yanked: false,
                published_at: None,
            }],
        };

        let with_failing_trust = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Npm)
                .with_trust(&deps_dev),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let without_trust = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Npm),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");

        let HoverContents::Markup(a) = with_failing_trust.contents else {
            panic!("expected markup hover contents");
        };
        let HoverContents::Markup(b) = without_trust.contents else {
            panic!("expected markup hover contents");
        };
        assert!(!a.value.contains("Supply chain"), "got: {}", a.value);
        assert_eq!(a.value, b.value);
    }

    /// Exercises `generate_hover`'s own real `tokio::time::timeout(DEPS_DEV_WAIT_BUDGET,
    /// handle)` wrap directly — not a smaller artificial stand-in (review's flagged test
    /// gap: the only prior test of the underlying mechanism drove
    /// `DepsDevClient::trust_signal` with its own 5ms timeout, never through
    /// `generate_hover` at all).
    ///
    /// Both deps.dev calls are delayed just under the internal `DEPS_DEV_CALL_TIMEOUT`
    /// (400ms each) but together exceed the real `DEPS_DEV_WAIT_BUDGET` (700ms) — the only
    /// way to reach the hover-level timeout without either call tripping its own shorter
    /// per-call cap first. `flavor = "multi_thread"` so the blocking `std::thread::sleep`
    /// inside the mock handler runs on a different worker thread than the test's own
    /// timer, matching
    /// `deps_dev::tests::trust_signal_survives_dropped_join_handle_and_warms_memo`'s
    /// technique.
    ///
    /// Deliberately does **not** also assert that a later hover picks up the memo the
    /// background task warms — two prior attempts at that (a tight 50ms poll, then a
    /// spaced 5×1s retry) both passed locally but failed consistently on CI's Linux
    /// runners (stable and beta; macOS and Windows were unaffected), each time burning
    /// its *entire* budget rather than merely running late. That symmetry between two
    /// very different waiting strategies points at the environment, not the margin, and
    /// nothing here can distinguish "the background task is still running, slowly" from
    /// "it already failed and negative-cached the result" from inside this same racing
    /// test — see the sibling test below for a deterministic replacement that proves the
    /// warm-memo path without racing this timeout.
    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
    async fn test_generate_hover_trust_signal_over_real_wait_budget_omits_section() {
        const CALL_DELAY: std::time::Duration = std::time::Duration::from_millis(375);

        let (mut server, deps_dev) = deps_dev_mock_client().await;
        let _version = server
            .mock("GET", "/v3/systems/npm/packages/express/versions/4.19.2")
            .with_status(200)
            .with_body_from_request(move |_req| {
                std::thread::sleep(CALL_DELAY);
                r#"{"slsaProvenances": [{"verified": true}], "attestations": [], "relatedProjects": [
                    {"projectKey": {"id": "github.com/expressjs/express"}, "relationType": "SOURCE_REPO", "relationProvenance": "SLSA_ATTESTATION"}
                ]}"#
                .as_bytes()
                .to_vec()
            })
            .create_async()
            .await;
        let _project = server
            .mock("GET", "/v3/projects/github.com%2Fexpressjs%2Fexpress")
            .with_status(200)
            .with_body_from_request(move |_req| {
                std::thread::sleep(CALL_DELAY);
                r#"{"scorecard": {"overallScore": 8.5}}"#.as_bytes().to_vec()
            })
            .create_async()
            .await;
        let deps_dev = Arc::new(deps_dev);

        let (parse_result, resolved_versions) = express_fixture();
        let registry = MockRegistryWithVersions { versions: vec![] };

        let first = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Npm)
                .with_trust(&deps_dev),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");
        let HoverContents::Markup(first_content) = first.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            !first_content.value.contains("Supply chain"),
            "the real ~750ms two-call sequence must exceed the 700ms wait budget on the \
             first hover; got: {}",
            first_content.value
        );
        // The detached task spawned above keeps running past this point by design
        // (that's the whole point of spawn-and-warm) — deliberately not awaited or
        // polled for here; see this function's doc comment.
    }

    /// The warm-memo half of the spawn-and-warm design (plan.md §12), proved
    /// deterministically rather than by racing the timeout test above: a memo entry
    /// populated by a direct, un-delayed `DepsDevClient::trust_signal` call (no timing
    /// involved — it is simply `.await`ed to completion) is read by a subsequent
    /// `generate_hover` call through the exact same `VersionData::with_trust` /
    /// `push_trust_signal_hover_section` path the timeout test above exercises. Together
    /// the two tests cover `generate_hover`'s real integration with `DepsDevClient` on
    /// both the "too slow, omit" and "already warm, render" branches, without either one
    /// depending on winning a race against the ambient test suite's scheduling.
    #[tokio::test]
    async fn test_generate_hover_renders_trust_signal_from_a_warm_memo() {
        let (mut server, deps_dev) = deps_dev_mock_client().await;
        let _version = server
            .mock("GET", "/v3/systems/npm/packages/express/versions/4.19.2")
            .with_status(200)
            .with_body(
                r#"{"slsaProvenances": [{"verified": true}], "attestations": [], "relatedProjects": [
                    {"projectKey": {"id": "github.com/expressjs/express"}, "relationType": "SOURCE_REPO", "relationProvenance": "SLSA_ATTESTATION"}
                ]}"#,
            )
            .create_async()
            .await;
        let _project = server
            .mock("GET", "/v3/projects/github.com%2Fexpressjs%2Fexpress")
            .with_status(200)
            .with_body(r#"{"scorecard": {"overallScore": 8.5}}"#)
            .create_async()
            .await;

        let warmed = deps_dev
            .trust_signal("npm", "express", "4.19.2")
            .await
            .expect("the direct, un-delayed call must warm the memo deterministically");
        assert!(warmed.scorecard.is_some(), "fixture includes a scorecard");

        let deps_dev = Arc::new(deps_dev);
        let (parse_result, resolved_versions) = express_fixture();
        let registry = MockRegistryWithVersions { versions: vec![] };

        let hover = generate_hover(
            &parse_result,
            Position::new(0, 2),
            VersionData::new(&HashMap::new(), &resolved_versions)
                .with_ecosystem(crate::EcosystemId::Npm)
                .with_trust(&deps_dev),
            &registry,
            &MockFormatter,
            crate::freshness::FreshnessSettings::default(),
            PublishTime::now(),
        )
        .await
        .expect("hover should be generated");
        let HoverContents::Markup(content) = hover.contents else {
            panic!("expected markup hover contents");
        };
        assert!(
            content.value.contains("Supply chain"),
            "a hover reading an already-warm memo must render the trust signal \
             immediately; got: {}",
            content.value
        );
    }
}