nornir 0.5.3

//! `nornir release doctor` — the **advisory** release report: the "see it and get
//! hints first" tier. Read-only, no mutation. It answers the question you actually
//! have across the whole constellation — *can I release, what's off, in what order?*
//! — instead of Maven's per-project `dependency:tree`.
//!
//! Three signals composed here:
//! * **dirty trees** — real LOCAL `git status` per repo (via [`crate::gitio`]), not
//!   a server clone.
//! * **external-dependency version skew** — per shared external crate, the target
//!   (highest declared version) and each repo's status (ok / behind / forbidden),
//!   with bump hints. The anti-Maven bit: it surfaces *disagreement across repos*.
//! * (topo publish order + blast radius reuse the existing dep-graph tools.)
//!
//! Policy is **inferred** (target = highest version anyone already uses) plus a tiny
//! `forbidden` override (e.g. `arrow 56`). No pin table to hand-maintain.

use std::collections::BTreeMap;
use std::path::{Path, PathBuf};

use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};

// ─────────────────────────── policy ───────────────────────────

/// A forbidden external-dependency version — matched on the MAJOR component of a
/// declared version (e.g. `arrow` `56` bans `56`, `56.2`, `=56.2.1`).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ForbiddenDep {
    pub crate_name: String,
    pub version: String,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct DepPolicy {
    pub forbidden: Vec<ForbiddenDep>,
}

// ─────────────────────────── inputs ───────────────────────────

/// One repo's declared EXTERNAL dependency versions (crate → declared version req).
#[derive(Debug, Clone)]
pub struct RepoExternals {
    pub repo: String,
    pub deps: BTreeMap<String, String>,
}

// ─────────────────────── skew analysis ───────────────────────

#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub enum SkewStatus {
    Ok,
    Behind,
    Forbidden,
}

#[derive(Debug, Clone, Serialize)]
pub struct RepoCrateStatus {
    pub repo: String,
    pub version: String,
    pub status: SkewStatus,
    /// `true` when this repo is `Behind` on the crate yet the TARGET major already
    /// resolves in its `Cargo.lock` (a dual-major tree). That means a transitive
    /// dependency pins the old major — a direct bump of the declared version won't
    /// take until that dep moves, so the plain "bump" hint would be misleading.
    /// Filled in by [`enrich_transitive_pins`]; `false` until then (and in the
    /// pure [`analyze_skew`], which does no I/O).
    #[serde(default)]
    pub held_by_transitive_pin: bool,
}

#[derive(Debug, Clone, Serialize)]
pub struct CrateSkew {
    pub crate_name: String,
    /// The highest declared version across the repos = the inferred target.
    pub target: String,
    /// `true` when repos declare more than one distinct version.
    pub diverged: bool,
    pub entries: Vec<RepoCrateStatus>,
}

impl CrateSkew {
    /// Repos that should bump (status not Ok) — the hint set.
    pub fn bump_repos(&self) -> Vec<&str> {
        self.entries
            .iter()
            .filter(|e| e.status != SkewStatus::Ok)
            .map(|e| e.repo.as_str())
            .collect()
    }
}

/// Parse a declared version requirement into a comparable `(major, minor, patch)`
/// key, tolerating partials (`"57"` → `(57,0,0)`) and req operators (`"^1.2"`,
/// `">=0.9.0"`, `"=56.2.1"`).
fn version_key(s: &str) -> (u64, u64, u64) {
    let cleaned = s.trim().trim_start_matches(|c: char| !c.is_ascii_digit());
    let mut it = cleaned.split('.').map(|p| {
        p.chars()
            .take_while(|c| c.is_ascii_digit())
            .collect::<String>()
            .parse::<u64>()
            .unwrap_or(0)
    });
    (it.next().unwrap_or(0), it.next().unwrap_or(0), it.next().unwrap_or(0))
}

fn is_forbidden(crate_name: &str, version: &str, policy: &DepPolicy) -> bool {
    policy
        .forbidden
        .iter()
        .any(|f| f.crate_name == crate_name && same_semver_line(&f.version, version))
}

/// Whether two versions share the SemVer-significant leading component: for
/// `major >= 1` that's the major alone (`1.x` ↔ `1.y`); for `0.x` it's
/// `(major, minor)` — `0.9` and `0.10` are DIFFERENT SemVer lines, so a `0.9`
/// forbid must not ban every `0.x` (bug #19).
fn same_semver_line(forbidden: &str, version: &str) -> bool {
    let (fm, fmin, _) = version_key(forbidden);
    let (vm, vmin, _) = version_key(version);
    if fm == 0 { fm == vm && fmin == vmin } else { fm == vm }
}

/// THE BRAIN (pure, no I/O). Per external crate, infer the target = the highest
/// declared version, and classify each repo: `Ok` at the target, `Behind` below it,
/// `Forbidden` if the policy bans that version. Only crates that DIVERGE across
/// repos, or that hit a forbidden version, are surfaced (a single-repo dep at one
/// version isn't a skew worth a hint).
pub fn analyze_skew(repos: &[RepoExternals], policy: &DepPolicy) -> Vec<CrateSkew> {
    let mut by_crate: BTreeMap<&str, Vec<(&str, &str)>> = BTreeMap::new();
    for r in repos {
        for (c, v) in &r.deps {
            by_crate.entry(c.as_str()).or_default().push((r.repo.as_str(), v.as_str()));
        }
    }

    let mut out = Vec::new();
    for (crate_name, mut uses) in by_crate {
        let has_forbidden = uses.iter().any(|(_, v)| is_forbidden(crate_name, v, policy));
        let distinct: std::collections::BTreeSet<(u64, u64, u64)> =
            uses.iter().map(|(_, v)| version_key(v)).collect();
        let diverged = distinct.len() >= 2;
        if !diverged && !has_forbidden {
            continue;
        }

        uses.sort_by(|a, b| a.0.cmp(b.0)); // stable by repo name
        let target_key = uses.iter().map(|(_, v)| version_key(v)).max().unwrap();
        let target = uses
            .iter()
            .find(|(_, v)| version_key(v) == target_key)
            .map(|(_, v)| v.to_string())
            .unwrap();

        let entries = uses
            .iter()
            .map(|(repo, v)| {
                let status = if is_forbidden(crate_name, v, policy) {
                    SkewStatus::Forbidden
                } else if version_key(v) < target_key {
                    SkewStatus::Behind
                } else {
                    SkewStatus::Ok
                };
                RepoCrateStatus {
                    repo: repo.to_string(),
                    version: v.to_string(),
                    status,
                    held_by_transitive_pin: false,
                }
            })
            .collect();

        out.push(CrateSkew { crate_name: crate_name.to_string(), target, diverged, entries });
    }
    out
}

// ─────────────────── patch-fork promote gate ───────────────────
//
// A crate that builds on a local `[patch.crates-io]` override to a NON-registry
// source (a `path=` or `git=` fork — e.g. `iceberg = { path =
// "../iceberg-arrow58" }`) is NOT crates.io-publishable: `cargo publish` strips
// `[patch]`, so the published immutable crate resolves the STOCK dep the fork
// replaced (here stock iceberg 0.9.1 = arrow 57, not the fork's arrow 58) →
// broken. The detector finds those forks; the transitive closure marks every
// workspace-internal dependent blocked too (skade rides the iceberg fork →
// blocked; nornir depends on skade → also blocked).

/// What kind of non-registry source a `[patch.crates-io]` entry points at.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub enum ForkKind {
    /// `dep = { path = "../fork" }`
    Path,
    /// `dep = { git = "https://…" }`
    Git,
}

/// One fork-patched dependency that blocks a crate from a crates.io publish.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct PatchForkBlock {
    /// The workspace crate whose manifest carries (or transitively inherits) the
    /// fork patch. For a direct block this is the crate that declares the
    /// `[patch.crates-io]`; transitive blocks are computed separately.
    pub crate_name: String,
    /// The patched dependency name (e.g. `iceberg`).
    pub patched_dep: String,
    /// Whether the override is a `path=` or `git=` fork.
    pub fork_kind: ForkKind,
    /// The override source string (the path or git url) for the report.
    pub source: String,
    /// Human reason, suitable for a `⛔` line.
    pub reason: String,
    /// `true` when `patched_dep` is NOT produced anywhere in the constellation —
    /// a genuine FOREIGN fork (e.g. `iceberg → ../iceberg-arrow58`, where crates.io
    /// `iceberg` is a third party's crate). Stripping it on publish leaves the crate
    /// resolving to an incompatible stock dep → a hard promote-blocker. `false` for a
    /// path/git override of one of OUR OWN crates (a sibling we also publish, e.g.
    /// `skade → ../skade`): that's just a local dev override, publish-order covers it,
    /// and the strip is safe. Only foreign forks seed the promote-block closure.
    /// Set by [`compute_promote_block`] (the raw [`patch_fork_blockers`] scan leaves
    /// it `false` since foreign-ness needs the cross-workspace produced set).
    pub is_foreign_fork: bool,
}

/// PURE-ish detector (one filesystem scan, no network): walk every `Cargo.toml`
/// under `repo_root`, parse each `[patch.crates-io]` / `[patch."crates-io"]`
/// table, and return one [`PatchForkBlock`] per entry that redirects to a
/// NON-registry source (`path=` or `git=`). Registry-version no-op patches
/// (`foo = "1.2"` or `foo = { version = "1.2" }`, which only pin a registry
/// version) do NOT count — `cargo publish` keeps those resolvable.
///
/// `crate_name` on each block is the `[package].name` of the manifest that
/// declares the patch (or, for a virtual-workspace root manifest with no
/// `[package]`, every workspace member crate produced under that root — see
/// [`patch_fork_blockers`]'s caller, which folds the root patch into the
/// workspace's own crates via the transitive closure).
pub fn patch_fork_blockers(repo_root: &Path) -> Vec<PatchForkBlock> {
    let mut out = Vec::new();
    for toml_path in find_cargo_tomls(repo_root, 4) {
        let Ok(txt) = std::fs::read_to_string(&toml_path) else { continue };
        let Ok(doc) = txt.parse::<toml::Value>() else { continue };
        // The crate this manifest produces (if any). A virtual root manifest has
        // no [package]; we tag those blocks with the workspace dir's folder name
        // so they still attach to *something* and the transitive closure can fold
        // them into the real member crates.
        let owner = doc
            .get("package")
            .and_then(|p| p.get("name"))
            .and_then(|n| n.as_str())
            .map(str::to_string);

        let Some(patch) = doc.get("patch") else { continue };
        let Some(patch_tbl) = patch.as_table() else { continue };
        // `[patch.crates-io]` (and the quoted variants) is `patch."crates-io"`.
        for key in ["crates-io"] {
            let Some(entries) = patch_tbl.get(key).and_then(|t| t.as_table()) else { continue };
            for (dep, spec) in entries {
                let (kind, source) = match spec {
                    // `dep = "1.2"` → registry-version pin, NOT a fork. Skip.
                    toml::Value::String(_) => continue,
                    toml::Value::Table(t) => {
                        if let Some(p) = t.get("path").and_then(|v| v.as_str()) {
                            (ForkKind::Path, p.to_string())
                        } else if let Some(g) = t.get("git").and_then(|v| v.as_str()) {
                            (ForkKind::Git, g.to_string())
                        } else {
                            // `{ version = "1.2" }` registry no-op patch → skip.
                            continue;
                        }
                    }
                    _ => continue,
                };
                let owner_name = owner.clone().unwrap_or_else(|| {
                    // Virtual root: name the block after the repo dir so it is
                    // non-empty; the caller folds it into the member crates.
                    repo_root
                        .file_name()
                        .and_then(|n| n.to_str())
                        .unwrap_or("workspace")
                        .to_string()
                });
                let reason = format!(
                    "publishing strips [patch.crates-io] → stock {dep} is incompatible \
                     (fork: {source}). Unblock: publish the fork, or wait for upstream."
                );
                out.push(PatchForkBlock {
                    crate_name: owner_name,
                    patched_dep: dep.clone(),
                    fork_kind: kind,
                    source,
                    reason,
                    // Foreign-ness needs the cross-workspace produced set, which a
                    // single-repo scan doesn't have — `compute_promote_block` fills it.
                    is_foreign_fork: false,
                });
            }
        }
    }
    out.sort_by(|a, b| {
        (&a.crate_name, &a.patched_dep).cmp(&(&b.crate_name, &b.patched_dep))
    });
    out
}

/// The TRANSITIVE promote-block (REPO-granularity, COARSE). Kept for callers that
/// reason at repo level. NOTE: this over-blocks for the gate — if a repo produces
/// *any* blocked crate it blocks *all* of that repo's crates, so a workspace member
/// that never touches the fork (e.g. `znippy-common` alongside `znippy-iceberg`)
/// gets held too. For the publish gate use [`promote_blocked_crates_precise`] /
/// [`compute_promote_block`], which block per-crate against the foreign fork.
///
/// The TRANSITIVE promote-block: a workspace crate is blocked if it OR any of
/// its workspace-internal dependencies is fork-blocked. Given the directly
/// fork-blocked crate set `directly_blocked` and the workspace graphs, return
/// every blocked crate name (the seed plus the reverse closure over the
/// who-produces-what edges). Pure — operates on the gathered graphs.
///
/// `directly_blocked` is the set of crate names a [`patch_fork_blockers`] scan
/// attached the fork to. A virtual-root patch attaches to the repo-dir name;
/// pass each workspace member's `produces` set so the closure folds it in:
/// callers that scan a single workspace seed with the root's produced crates.
pub fn promote_blocked_crates(
    graphs: &[RepoGraph],
    directly_blocked: &std::collections::BTreeSet<String>,
) -> std::collections::BTreeSet<String> {
    use std::collections::BTreeSet;
    // Map crate → the repos that PRODUCE it, and repo → the crates it produces.
    // Edges run dep → dependent: if crate C is blocked, any repo that declares C
    // as a dep is blocked, and so are all the crates that repo produces.
    let produces: Vec<(&str, &BTreeSet<String>, &BTreeSet<String>)> = graphs
        .iter()
        .map(|g| (g.repo.as_str(), &g.produces, &g.deps))
        .collect();

    let mut blocked: BTreeSet<String> = directly_blocked.clone();
    // Fixed point: keep folding until no new crate joins the blocked set.
    loop {
        let mut grew = false;
        for (_repo, repo_produces, repo_deps) in &produces {
            // This repo is blocked if it produces a blocked crate OR depends on
            // a blocked crate.
            let repo_blocked = repo_produces.iter().any(|c| blocked.contains(c))
                || repo_deps.iter().any(|d| blocked.contains(d));
            if repo_blocked {
                for c in repo_produces.iter() {
                    if blocked.insert(c.clone()) {
                        grew = true;
                    }
                }
            }
        }
        if !grew {
            break;
        }
    }
    blocked
}

/// Per-crate (NOT per-repo) dependency edges: every publishable `[package]` under
/// `root` maps to the set of dependency crate names it declares (internal + external,
/// non-optional, incl. build-deps). Unlike [`gather_repo_graph`], which unions a whole
/// repo's deps, this keeps crates SEPARATE — so a workspace member that doesn't touch a
/// forked dep isn't tarred with a sibling's fork. Mirrors `gather_repo_graph`'s rules
/// (skips `publish = false` crates and optional deps).
pub fn gather_crate_deps(
    root: &Path,
) -> BTreeMap<String, std::collections::BTreeSet<String>> {
    use std::collections::BTreeSet;
    let mut out: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
    for toml_path in find_cargo_tomls(root, 4) {
        let Ok(txt) = std::fs::read_to_string(&toml_path) else { continue };
        let Ok(doc) = txt.parse::<toml::Value>() else { continue };
        let package = doc.get("package");
        let publishable = package
            .and_then(|p| p.get("publish"))
            .and_then(|v| v.as_bool())
            .unwrap_or(true);
        if !publishable {
            continue;
        }
        let Some(name) =
            package.and_then(|p| p.get("name")).and_then(|n| n.as_str())
        else {
            continue;
        };
        let entry = out.entry(name.to_string()).or_default();
        for key in ["dependencies", "build-dependencies"] {
            if let Some(t) = doc.get(key).and_then(|t| t.as_table()) {
                for (dep, spec) in t {
                    let optional = spec
                        .as_table()
                        .and_then(|d| d.get("optional"))
                        .and_then(|o| o.as_bool())
                        .unwrap_or(false);
                    if !optional {
                        entry.insert(dep.clone());
                    }
                }
            }
        }
    }
    out
}

/// CRATE-LEVEL promote-block (PRECISE). A crate is blocked iff its transitive
/// dependency closure (over `crate_deps`) reaches one of `foreign_forks` — a dep that's
/// been `[patch]`-redirected to a path/git fork AND is not produced anywhere in the
/// constellation, so stripping the patch on publish leaves it resolving to an
/// incompatible stock crate. Path-patches to OUR OWN crates (siblings we also publish)
/// are NOT foreign forks — publish order covers them — so a member that never
/// transitively touches a foreign fork stays publishable. Pure; unit-testable.
pub fn promote_blocked_crates_precise(
    crate_deps: &BTreeMap<String, std::collections::BTreeSet<String>>,
    foreign_forks: &std::collections::BTreeSet<String>,
) -> std::collections::BTreeSet<String> {
    use std::collections::BTreeSet;
    let mut blocked: BTreeSet<String> = BTreeSet::new();
    if foreign_forks.is_empty() {
        return blocked;
    }
    for crate_name in crate_deps.keys() {
        // DFS the transitive dep closure; blocked the moment it reaches a foreign fork.
        let mut stack = vec![crate_name.clone()];
        let mut seen: BTreeSet<String> = BTreeSet::new();
        let mut hit = false;
        while let Some(c) = stack.pop() {
            if foreign_forks.contains(&c) {
                hit = true;
                break;
            }
            if !seen.insert(c.clone()) {
                continue;
            }
            if let Some(deps) = crate_deps.get(&c) {
                for d in deps {
                    if foreign_forks.contains(d) {
                        hit = true;
                        break;
                    }
                    // Recurse only into crates we produce (internal edges); unknown
                    // externals are leaves.
                    if crate_deps.contains_key(d) {
                        stack.push(d.clone());
                    }
                }
            }
            if hit {
                break;
            }
        }
        if hit {
            blocked.insert(crate_name.clone());
        }
    }
    blocked
}

/// The full precise promote-block computation across a set of `(name, path)` repos.
/// Scans each repo for crate-level deps + `[patch.crates-io]` forks, classifies each
/// fork as FOREIGN (patched dep not produced anywhere → hard blocker) vs an own-crate
/// path/git override (safe), tags every [`PatchForkBlock`] with `is_foreign_fork`, and
/// returns the per-crate transitive block closure against the foreign forks. Shared by
/// `release doctor`, the publish path, and the viz wizard so all three agree.
pub fn compute_promote_block<I, P>(repos: I) -> PromoteBlockResult
where
    I: IntoIterator<Item = (String, P)>,
    P: AsRef<Path>,
{
    use std::collections::BTreeSet;
    let mut crate_deps: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
    let mut forks: Vec<PatchForkBlock> = Vec::new();
    for (_name, path) in repos {
        let path = path.as_ref();
        for (c, deps) in gather_crate_deps(path) {
            crate_deps.entry(c).or_default().extend(deps);
        }
        forks.extend(patch_fork_blockers(path));
    }
    let produced: BTreeSet<String> = crate_deps.keys().cloned().collect();
    let foreign_forks: BTreeSet<String> = forks
        .iter()
        .map(|b| b.patched_dep.clone())
        .filter(|d| !produced.contains(d))
        .collect();
    for b in forks.iter_mut() {
        b.is_foreign_fork = foreign_forks.contains(&b.patched_dep);
    }
    forks.sort_by(|a, b| {
        (&a.crate_name, &a.patched_dep).cmp(&(&b.crate_name, &b.patched_dep))
    });
    let blocked = promote_blocked_crates_precise(&crate_deps, &foreign_forks);
    // Per-held-crate REASONS so nothing leaves the publish plan silently (--explain).
    let explained = held_fork_reasons(&crate_deps, &forks, &foreign_forks);
    PromoteBlockResult { forks, foreign_forks, blocked, explained }
}

/// Result of [`compute_promote_block`].
#[derive(Debug, Clone, Default)]
pub struct PromoteBlockResult {
    /// Every detected patch-fork, with `is_foreign_fork` set. Foreign ones are hard
    /// blockers; the rest are safe own-crate dev overrides.
    pub forks: Vec<PatchForkBlock>,
    /// The foreign-fork dependency names that seed the block (e.g. `iceberg`).
    pub foreign_forks: std::collections::BTreeSet<String>,
    /// The per-crate transitive promote-block closure.
    pub blocked: std::collections::BTreeSet<String>,
    /// Per HELD crate → its stated reason(s): the foreign fork(s) it rides, whether it
    /// rides them directly, and how to unblock. Populated so NOTHING leaves the publish
    /// plan silently (`release doctor --explain`). One entry per crate in `blocked`.
    pub explained: Vec<HeldExplanation>,
}

/// One foreign fork a held crate rides — the concrete "because" behind a hold.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct HeldFork {
    /// The `[patch.crates-io]`-forked dependency name (e.g. `iceberg`, `arrow`).
    pub patched_dep: String,
    /// Whether the fork override is a `path=` or `git=` source.
    pub fork_kind: ForkKind,
    /// The override source (the path or git url) — surfaced verbatim in the reason.
    pub source: String,
}

/// **Why a crate is held out of the crates.io publish plan.** The `--publish` cascade
/// drops every crate that (transitively) rides a foreign `[patch.crates-io]` fork —
/// stripping the patch on publish would leave the crate resolving an incompatible
/// stock dep. Historically those crates just *vanished* from the plan with no line
/// stating why; this makes the hold EXPLICIT: `fork_kind`, the `patched_dep` it rides,
/// direct-vs-transitive, and concrete unblock advice. Emitted on the decision surface
/// so a human sees exactly what was withheld and how to release it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct HeldExplanation {
    /// The held crate.
    pub crate_name: String,
    /// The foreign fork(s) this crate transitively reaches (the reason it's held),
    /// sorted by patched-dep name for a stable report.
    pub rides: Vec<HeldFork>,
    /// `true` when the crate DIRECTLY depends on a forked dep; `false` when it is held
    /// only because a workspace-internal dependency of it rides the fork.
    pub direct: bool,
    /// Concrete "how to unblock" advice, ready for a `⛔` line.
    pub advice: String,
}

/// Compute the per-crate hold reasons: for every crate whose transitive dep closure
/// (over `crate_deps`) reaches a foreign fork, record WHICH fork(s) it reaches, whether
/// it depends on one directly, and the unblock advice. The crate set returned is exactly
/// [`promote_blocked_crates_precise`]'s `blocked` set — every held crate carries a reason,
/// so nothing leaves the plan unexplained. Pure; `forks` supplies each foreign fork's
/// `fork_kind`/`source` metadata for the message.
pub fn held_fork_reasons(
    crate_deps: &BTreeMap<String, std::collections::BTreeSet<String>>,
    forks: &[PatchForkBlock],
    foreign_forks: &std::collections::BTreeSet<String>,
) -> Vec<HeldExplanation> {
    use std::collections::BTreeSet;
    if foreign_forks.is_empty() {
        return Vec::new();
    }
    // Foreign fork dep name → representative metadata (kind + source) for the message.
    let mut fork_meta: BTreeMap<&str, &PatchForkBlock> = BTreeMap::new();
    for b in forks.iter().filter(|b| b.is_foreign_fork) {
        fork_meta.entry(b.patched_dep.as_str()).or_insert(b);
    }
    let mut out: Vec<HeldExplanation> = Vec::new();
    for crate_name in crate_deps.keys() {
        // Which foreign forks does this crate transitively reach?
        let mut reached: BTreeSet<String> = BTreeSet::new();
        let mut stack = vec![crate_name.clone()];
        let mut seen: BTreeSet<String> = BTreeSet::new();
        while let Some(c) = stack.pop() {
            if !seen.insert(c.clone()) {
                continue;
            }
            if let Some(deps) = crate_deps.get(&c) {
                for d in deps {
                    if foreign_forks.contains(d) {
                        reached.insert(d.clone());
                    } else if crate_deps.contains_key(d) {
                        stack.push(d.clone());
                    }
                }
            }
        }
        if reached.is_empty() {
            continue;
        }
        let direct = crate_deps
            .get(crate_name)
            .map(|deps| deps.iter().any(|d| foreign_forks.contains(d)))
            .unwrap_or(false);
        let rides: Vec<HeldFork> = reached
            .iter()
            .map(|dep| match fork_meta.get(dep.as_str()) {
                Some(b) => HeldFork {
                    patched_dep: dep.clone(),
                    fork_kind: b.fork_kind,
                    source: b.source.clone(),
                },
                None => HeldFork {
                    patched_dep: dep.clone(),
                    fork_kind: ForkKind::Path,
                    source: String::new(),
                },
            })
            .collect();
        let deps_list = reached.iter().cloned().collect::<Vec<_>>().join(", ");
        let advice = if direct {
            format!(
                "publishing strips [patch.crates-io] → stock {deps_list} is incompatible. \
                 Unblock: publish the real (unforked) {deps_list} to crates.io, or wait for \
                 upstream, then this crate promotes."
            )
        } else {
            format!(
                "held transitively — a workspace dependency rides forked {deps_list}. \
                 Unblock: publish the real {deps_list} (and any rider dep) first, then this \
                 crate promotes."
            )
        };
        out.push(HeldExplanation { crate_name: crate_name.clone(), rides, direct, advice });
    }
    out.sort_by(|a, b| a.crate_name.cmp(&b.crate_name));
    out
}

// ─────────────────── transitive-pin detection ───────────────────

/// The set of MAJOR versions a crate resolves to in a `Cargo.lock`. `arrow` with
/// both `57.3.1` and `58.3.0` present → `{57, 58}`. Pure (parses the lock text),
/// so it's unit-testable without a real checkout.
pub fn crate_majors_in_lock(lock_text: &str, crate_name: &str) -> std::collections::BTreeSet<u64> {
    let mut out = std::collections::BTreeSet::new();
    let Ok(doc) = lock_text.parse::<toml::Value>() else { return out };
    let Some(pkgs) = doc.get("package").and_then(|p| p.as_array()) else { return out };
    for pkg in pkgs {
        let name = pkg.get("name").and_then(|n| n.as_str());
        let ver = pkg.get("version").and_then(|v| v.as_str());
        if name == Some(crate_name) {
            if let Some(v) = ver {
                out.insert(version_key(v).0);
            }
        }
    }
    out
}

/// Enrich a skew analysis with transitive-pin facts: for each repo that's `Behind`
/// on a crate, set `held_by_transitive_pin` when that repo's `Cargo.lock` ALREADY
/// resolves the target major (a dual-major tree). That's the tell that a transitive
/// dependency pins the old major — so the naive "bump the declared version" hint
/// would be misleading (it can't take until the pinning dep moves). `repo_locks`
/// maps repo name → its `Cargo.lock` contents (absent / unreadable locks are
/// simply skipped, leaving the flag `false`).
pub fn enrich_transitive_pins(
    skew: &mut [CrateSkew],
    repo_locks: &BTreeMap<String, String>,
) {
    for c in skew.iter_mut() {
        let target_major = version_key(&c.target).0;
        for e in c.entries.iter_mut() {
            if e.status != SkewStatus::Behind {
                continue;
            }
            // Only a genuine MAJOR gap can be transitively pinned. A loose
            // declaration like `clap = "4"` reads as "behind 4.5.51" but resolves
            // to it (same major) — that's not a pin, just an imprecise req.
            let declared_major = version_key(&e.version).0;
            if declared_major >= target_major {
                continue;
            }
            if let Some(lock) = repo_locks.get(&e.repo) {
                // Held iff the lock carries BOTH the declared (old) major AND the
                // target major as distinct resolves — a real dual-major tree, the
                // fingerprint of a transitive dep pinning the old line.
                let majors = crate_majors_in_lock(lock, &c.crate_name);
                if majors.contains(&declared_major) && majors.contains(&target_major) {
                    e.held_by_transitive_pin = true;
                }
            }
        }
    }
}

// ─────────────────────── dirty trees ───────────────────────

#[derive(Debug, Clone, Serialize)]
pub struct RepoDirty {
    pub repo: String,
    pub dirty: bool,
    pub error: Option<String>,
}

/// Real per-repo working-tree dirty state, computed against the LOCAL checkout
/// (not a server clone) via [`crate::gitio::worktree_freshness`].
pub fn check_dirty(repos: &[(String, PathBuf)]) -> Vec<RepoDirty> {
    repos
        .iter()
        .map(|(name, path)| match crate::gitio::worktree_freshness(path) {
            Ok(f) => RepoDirty { repo: name.clone(), dirty: f.dirty, error: None },
            Err(e) => RepoDirty { repo: name.clone(), dirty: false, error: Some(e.to_string()) },
        })
        .collect()
}

// ─────────────────────── gatherer ───────────────────────

/// Collect a repo's declared EXTERNAL dependency versions by scanning its
/// `Cargo.toml` files. External = declared with a literal `version` and NO `path`
/// (path deps are workspace-internal). Keeps the highest version seen per crate.
pub fn gather_repo_externals(repo: &str, root: &Path) -> Result<RepoExternals> {
    let mut deps: BTreeMap<String, String> = BTreeMap::new();
    for toml_path in find_cargo_tomls(root, 4) {
        let Ok(txt) = std::fs::read_to_string(&toml_path) else { continue };
        let Ok(doc) = txt.parse::<toml::Value>() else { continue };
        for key in ["dependencies", "build-dependencies"] {
            collect_deps(doc.get(key), &mut deps);
        }
        if let Some(ws) = doc.get("workspace").and_then(|w| w.get("dependencies")) {
            collect_deps(Some(ws), &mut deps);
        }
    }
    Ok(RepoExternals { repo: repo.to_string(), deps })
}

/// Merge a `[dependencies]`-style table into `deps`, taking only external crates
/// (literal version, no `path`) and keeping the highest version per crate.
fn collect_deps(table: Option<&toml::Value>, deps: &mut BTreeMap<String, String>) {
    let Some(table) = table.and_then(|t| t.as_table()) else { return };
    for (name, spec) in table {
        let version = match spec {
            toml::Value::String(v) => Some(v.clone()),
            toml::Value::Table(t) => {
                if t.contains_key("path") {
                    None // workspace-internal
                } else {
                    t.get("version").and_then(|v| v.as_str()).map(str::to_string)
                }
            }
            _ => None,
        };
        if let Some(v) = version {
            deps.entry(name.clone())
                .and_modify(|cur| {
                    if version_key(&v) > version_key(cur) {
                        *cur = v.clone();
                    }
                })
                .or_insert(v);
        }
    }
}

/// Find `Cargo.toml` files under `root` up to `max_depth`, skipping `target`,
/// `.git`, and other hidden directories.
fn find_cargo_tomls(root: &Path, max_depth: usize) -> Vec<PathBuf> {
    let mut out = Vec::new();
    let mut stack = vec![(root.to_path_buf(), 0usize)];
    while let Some((dir, depth)) = stack.pop() {
        let manifest = dir.join("Cargo.toml");
        if manifest.is_file() {
            out.push(manifest);
        }
        if depth >= max_depth {
            continue;
        }
        let Ok(entries) = std::fs::read_dir(&dir) else { continue };
        for e in entries.flatten() {
            let p = e.path();
            // Don't follow symlinks (e.g. `.claude/worktrees/*` → sibling repos) and
            // skip build/dot dirs — same containment as `cargo::walk_cargo_tomls`.
            if e.file_type().map(|t| t.is_symlink()).unwrap_or(false) {
                continue;
            }
            if !p.is_dir() {
                continue;
            }
            let name = p.file_name().and_then(|n| n.to_str()).unwrap_or("");
            if name == "target" || name.starts_with('.') {
                continue;
            }
            stack.push((p, depth + 1));
        }
    }
    out
}

// ──────────── publish preflight: path deps need a version ────────────

/// A `path` dependency of a PUBLISHABLE crate that lacks a `version` requirement.
/// `cargo publish` rejects exactly this ("all dependencies must have a version
/// requirement specified when publishing") — so it's the class of blocker that
/// `--rehearse` otherwise trips on MID-publish, per crate, slowly. This is the
/// STATIC pre-flight for it: found up front, before any registry work, and
/// classified so the fix is obvious.
#[derive(Debug, Clone, Serialize)]
pub struct PathDepVersionGap {
    /// Constellation member whose crate has the gap.
    pub repo: String,
    /// Repo-relative path of the offending `Cargo.toml`.
    pub manifest: String,
    /// The publishable crate carrying the versionless path dep.
    pub crate_name: String,
    /// The path dependency missing a `version =`.
    pub dep: String,
    /// The constellation repo that PRODUCES `dep`, if any. `Some` ⇒ AUTO-FIXABLE
    /// (member-owned — fill `version` from the dep crate's own manifest). `None` ⇒
    /// NEEDS A DECISION: a non-member dep (e.g. `modgunn`, `graphar`) — it must
    /// join the release cascade or be published to crates.io first.
    pub dep_owner: Option<String>,
    /// The dep crate's own declared version, when it's a member we can read — the
    /// value to write into `version = "…"`.
    pub suggested_version: Option<String>,
    /// True when the missing-version declaration lives in `[workspace.dependencies]`
    /// (inherited via `dep.workspace = true`), so the fix is at the workspace root.
    pub via_workspace: bool,
}

/// Read a repo's manifests (path + parsed doc), its `[workspace.package].version`
/// (to resolve `version.workspace = true`), and its `[workspace.dependencies]`
/// specs (to resolve `dep.workspace = true`).
fn read_repo_manifests(
    root: &Path,
) -> (Vec<(PathBuf, toml::Value)>, Option<String>, BTreeMap<String, toml::Value>) {
    let mut docs = Vec::new();
    let mut ws_pkg_ver = None;
    let mut ws_deps = BTreeMap::new();
    for p in find_cargo_tomls(root, 4) {
        let Ok(txt) = std::fs::read_to_string(&p) else { continue };
        let Ok(doc) = txt.parse::<toml::Value>() else { continue };
        if let Some(w) = doc.get("workspace") {
            if let Some(v) =
                w.get("package").and_then(|pk| pk.get("version")).and_then(|v| v.as_str())
            {
                ws_pkg_ver = Some(v.to_string());
            }
            if let Some(t) = w.get("dependencies").and_then(|t| t.as_table()) {
                for (k, spec) in t {
                    ws_deps.insert(k.clone(), spec.clone());
                }
            }
        }
        docs.push((p, doc));
    }
    (docs, ws_pkg_ver, ws_deps)
}

/// A package's own version, resolving `version.workspace = true`
/// (`version = { workspace = true }`) to the workspace `[workspace.package].version`.
fn crate_version_of(pkg: &toml::Value, ws_pkg_ver: &Option<String>) -> Option<String> {
    match pkg.get("version") {
        Some(toml::Value::String(s)) => Some(s.clone()),
        Some(toml::Value::Table(t))
            if t.get("workspace").and_then(|w| w.as_bool()).unwrap_or(false) =>
        {
            ws_pkg_ver.clone()
        }
        _ => None,
    }
}

/// The local (workspace) version of every PUBLISHABLE crate across `repos`: crate
/// name → its `version` (resolving `version.workspace = true`). Feeds the release
/// dep-DAG's registry-state annotation (local-vs-published) — see
/// [`crate::release::depdag`]. Cheap + offline (manifest parse only).
pub fn local_crate_versions(repos: &[(String, PathBuf)]) -> BTreeMap<String, String> {
    let mut out: BTreeMap<String, String> = BTreeMap::new();
    for (_repo, root) in repos {
        let (docs, ws_pkg_ver, _) = read_repo_manifests(root);
        for (_p, doc) in &docs {
            let Some(pkg) = doc.get("package") else { continue };
            if !pkg.get("publish").and_then(|v| v.as_bool()).unwrap_or(true) {
                continue;
            }
            let Some(name) = pkg.get("name").and_then(|n| n.as_str()) else { continue };
            if let Some(ver) = crate_version_of(pkg, &ws_pkg_ver) {
                out.entry(name.to_string()).or_insert(ver);
            }
        }
    }
    out
}

/// Scan every PUBLISHABLE crate across the constellation for Normal/Build `path`
/// deps missing a `version` — the `cargo publish` manifest-verify blocker, caught
/// statically. Dev-deps are exempt (cargo drops a path dev-dep's requirement).
/// Each gap is classified member-owned (auto-fixable, with a suggested version)
/// vs non-member (needs a decision) via the produced-by map built from `repos`.
pub fn scan_path_dep_version_gaps(repos: &[(String, PathBuf)]) -> Vec<PathDepVersionGap> {
    // 1) produced map: crate name → (owning repo, its version), publishable crates.
    let mut produced: BTreeMap<String, (String, Option<String>)> = BTreeMap::new();
    for (repo, root) in repos {
        let (docs, ws_pkg_ver, _) = read_repo_manifests(root);
        for (_p, doc) in &docs {
            let Some(pkg) = doc.get("package") else { continue };
            if !pkg.get("publish").and_then(|v| v.as_bool()).unwrap_or(true) {
                continue;
            }
            let Some(name) = pkg.get("name").and_then(|n| n.as_str()) else { continue };
            let ver = crate_version_of(pkg, &ws_pkg_ver);
            produced.entry(name.to_string()).or_insert((repo.clone(), ver));
        }
    }

    // 2) per publishable crate, flag Normal/Build path deps with no version.
    let mut gaps: Vec<PathDepVersionGap> = Vec::new();
    for (repo, root) in repos {
        let (docs, _ws_pkg_ver, ws_deps) = read_repo_manifests(root);
        for (path, doc) in &docs {
            let Some(pkg) = doc.get("package") else { continue };
            if !pkg.get("publish").and_then(|v| v.as_bool()).unwrap_or(true) {
                continue;
            }
            let Some(crate_name) = pkg.get("name").and_then(|n| n.as_str()) else { continue };
            let rel = path.strip_prefix(root).unwrap_or(path).display().to_string();
            // Normal + Build dep tables, INCLUDING `[target.'cfg(…)'.…]` variants —
            // cargo publish requires a version on those path deps too.
            for tbl in publish_dep_tables(doc) {
                for (dkey, spec) in tbl {
                    // Resolve `dep.workspace = true` to the `[workspace.dependencies]` spec.
                    let via_ws = spec
                        .as_table()
                        .and_then(|t| t.get("workspace"))
                        .and_then(|w| w.as_bool())
                        .unwrap_or(false);
                    let eff = if via_ws { ws_deps.get(dkey).unwrap_or(spec) } else { spec };
                    let Some(et) = eff.as_table() else { continue }; // bare "1.2" → fine
                    if !et.contains_key("path") || et.contains_key("version") {
                        continue; // not a path dep, or already versioned → fine
                    }
                    let real = dep_real_name(dkey, eff);
                    let owner = produced.get(&real);
                    gaps.push(PathDepVersionGap {
                        repo: repo.clone(),
                        manifest: rel.clone(),
                        crate_name: crate_name.to_string(),
                        dep: real,
                        dep_owner: owner.map(|(r, _)| r.clone()),
                        suggested_version: owner.and_then(|(_, v)| v.clone()),
                        via_workspace: via_ws,
                    });
                }
            }
        }
    }
    // needs-decision first, then by repo/dep; dedupe identical (repo, manifest, dep).
    gaps.sort_by(|a, b| {
        (a.dep_owner.is_some(), &a.repo, &a.manifest, &a.dep)
            .cmp(&(b.dep_owner.is_some(), &b.repo, &b.manifest, &b.dep))
    });
    gaps.dedup_by(|a, b| a.repo == b.repo && a.manifest == b.manifest && a.dep == b.dep);
    gaps
}

/// The Normal + Build dependency tables of a manifest that `cargo publish` verifies
/// — the two top-level ones PLUS every `[target.'cfg(…)'.{dependencies,
/// build-dependencies}]` variant. Dev-deps are excluded (cargo drops a dev-dep's
/// path requirement). Returns the tables as `&toml::Table`.
fn publish_dep_tables(doc: &toml::Value) -> Vec<&toml::value::Table> {
    let mut out = Vec::new();
    for key in ["dependencies", "build-dependencies"] {
        if let Some(t) = doc.get(key).and_then(|t| t.as_table()) {
            out.push(t);
        }
    }
    if let Some(targets) = doc.get("target").and_then(|t| t.as_table()) {
        for (_cfg, ct) in targets {
            for key in ["dependencies", "build-dependencies"] {
                if let Some(t) = ct.get(key).and_then(|t| t.as_table()) {
                    out.push(t);
                }
            }
        }
    }
    out
}

/// Mutable access to one dependency table of a `toml_edit` manifest: either a
/// top-level `[dependencies]`/`[build-dependencies]` (`cfg = None`) or a
/// `[target.'<cfg>'.<table_name>]` variant (`cfg = Some(...)`).
fn dep_table_mut<'a>(
    doc: &'a mut toml_edit::DocumentMut,
    cfg: Option<&str>,
    table_name: &str,
) -> Option<&'a mut toml_edit::Table> {
    match cfg {
        None => doc.get_mut(table_name).and_then(|t| t.as_table_mut()),
        Some(c) => doc
            .get_mut("target")
            .and_then(|t| t.as_table_mut())
            .and_then(|t| t.get_mut(c))
            .and_then(|c| c.as_table_mut())
            .and_then(|c| c.get_mut(table_name))
            .and_then(|t| t.as_table_mut()),
    }
}

/// Resolve a crate's own `version`, following `version.workspace = true` by walking
/// up from its manifest dir to the `[workspace.package].version`.
fn resolve_crate_version(dep_manifest: &Path) -> Option<String> {
    let text = std::fs::read_to_string(dep_manifest).ok()?;
    let doc = text.parse::<toml::Value>().ok()?;
    match doc.get("package").and_then(|p| p.get("version")) {
        Some(toml::Value::String(s)) => return Some(s.clone()),
        Some(toml::Value::Table(t))
            if t.get("workspace").and_then(|w| w.as_bool()).unwrap_or(false) => {}
        _ => return None,
    }
    // version.workspace = true → find the nearest ancestor with [workspace.package].version.
    let mut dir = dep_manifest.parent();
    while let Some(d) = dir {
        if let Ok(txt) = std::fs::read_to_string(d.join("Cargo.toml")) {
            if let Ok(doc) = txt.parse::<toml::Value>() {
                if let Some(v) = doc
                    .get("workspace")
                    .and_then(|w| w.get("package"))
                    .and_then(|pk| pk.get("version"))
                    .and_then(|v| v.as_str())
                {
                    return Some(v.to_string());
                }
            }
        }
        dir = d.parent();
    }
    None
}

/// The outcome of `--fix`: how many gaps got a `version=` written, and which were
/// skipped (with why).
#[derive(Debug, Default)]
pub struct FixOutcome {
    pub fixed: usize,
    pub skipped: Vec<String>,
}

/// Auto-apply `version = "…"` to every path-dep-version gap, sourcing the version
/// from the DEP crate's own manifest (follow its `path`), falling back to the
/// report's `suggested_version`. Formatting-preserving (`toml_edit`). Idempotent:
/// a dep that already grew a version is simply not re-found. This is the smart the
/// doctor used to leave to a human — now `nornir release doctor --fix` does it.
pub fn fix_path_dep_versions(
    gaps: &[PathDepVersionGap],
    repos: &[(String, PathBuf)],
) -> Result<FixOutcome> {
    let repo_root: BTreeMap<&str, &Path> =
        repos.iter().map(|(n, p)| (n.as_str(), p.as_path())).collect();
    // Group by absolute manifest path so each file is opened + written once.
    let mut by_file: BTreeMap<PathBuf, Vec<&PathDepVersionGap>> = BTreeMap::new();
    for g in gaps {
        let Some(root) = repo_root.get(g.repo.as_str()) else {
            continue;
        };
        by_file.entry(root.join(&g.manifest)).or_default().push(g);
    }

    let mut out = FixOutcome::default();
    for (manifest, gs) in by_file {
        let text = std::fs::read_to_string(&manifest)
            .with_context(|| format!("read {}", manifest.display()))?;
        let mut doc: toml_edit::DocumentMut =
            text.parse().with_context(|| format!("parse {}", manifest.display()))?;
        let mdir = manifest.parent().unwrap_or_else(|| Path::new("."));
        let mut changed = false;
        // Locators for every Normal/Build dep table: the two top-level ones plus each
        // `[target.'cfg'.…]` variant (collected up front — inserting a version never
        // adds/removes a target table, so the set stays valid across mutation).
        let cfgs: Vec<String> = doc
            .get("target")
            .and_then(|t| t.as_table())
            .map(|t| t.iter().map(|(k, _)| k.to_string()).collect())
            .unwrap_or_default();
        let mut locators: Vec<(Option<String>, &str)> = Vec::new();
        for tn in ["dependencies", "build-dependencies"] {
            locators.push((None, tn));
        }
        for c in &cfgs {
            for tn in ["dependencies", "build-dependencies"] {
                locators.push((Some(c.clone()), tn));
            }
        }
        for g in gs {
            let mut handled = false;
            for (cfg, table_name) in &locators {
                let Some(tbl) = dep_table_mut(&mut doc, cfg.as_deref(), table_name) else {
                    continue;
                };
                // Find the dep KEY whose real name == g.dep with a path and no version.
                let key = tbl.iter().find_map(|(k, item)| {
                    let real =
                        item.get("package").and_then(|p| p.as_str()).unwrap_or(k);
                    let has_path = item.get("path").is_some();
                    let has_ver = item.get("version").is_some();
                    (real == g.dep && has_path && !has_ver).then(|| k.to_string())
                });
                let Some(key) = key else { continue };
                let path_val = tbl
                    .get(&key)
                    .and_then(|i| i.get("path"))
                    .and_then(|p| p.as_str())
                    .map(|p| mdir.join(p).join("Cargo.toml"));
                let ver = path_val
                    .as_deref()
                    .and_then(resolve_crate_version)
                    .or_else(|| g.suggested_version.clone());
                match ver {
                    Some(v) => {
                        if let Some(item) = tbl.get_mut(&key) {
                            if let Some(it) = item.as_inline_table_mut() {
                                it.insert("version", v.into());
                            } else if let Some(t) = item.as_table_mut() {
                                t.insert("version", toml_edit::value(v));
                            }
                            out.fixed += 1;
                            changed = true;
                        }
                    }
                    None => out.skipped.push(format!(
                        "{}/{}: {} (no resolvable version)",
                        g.repo, g.manifest, g.dep
                    )),
                }
                handled = true;
                break;
            }
            if !handled {
                out.skipped.push(format!(
                    "{}/{}: {} (dep entry not found — already fixed?)",
                    g.repo, g.manifest, g.dep
                ));
            }
        }
        if changed {
            std::fs::write(&manifest, doc.to_string())
                .with_context(|| format!("write {}", manifest.display()))?;
        }
    }
    Ok(out)
}

/// One `[dev-dependencies]` (or `[target.'cfg'.dev-dependencies]`) entry that
/// carries BOTH a `path` and a `version` on a workspace sibling — the
/// `VersionedPathDevDep` blocker (preflight #6). cargo strips dev-deps on publish
/// but still RESOLVES a versioned one during `cargo publish --verify`, fail-
/// stopping if that sibling isn't live on crates.io. The fix is to DROP the
/// `version` (a path-only dev-dep is stripped cleanly and resolves locally).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VersionedPathDevDep {
    pub repo: String,
    /// Repo-relative manifest path.
    pub manifest: PathBuf,
    /// The dep name carrying both path + version.
    pub dep: String,
}

/// Scan every repo for `[dev-dependencies]` entries with BOTH `path` and
/// `version` (incl. `[target.'cfg'.dev-dependencies]`). Pure read; the
/// counterpart auto-fix is [`fix_versioned_path_dev_deps`]. This is the
/// nornir-owned healer for the exact blocker class the workspace-wide dry-run
/// surfaced across facett/skade/nornir/znippy.
pub fn scan_versioned_path_dev_deps(repos: &[(String, PathBuf)]) -> Vec<VersionedPathDevDep> {
    let mut out = Vec::new();
    for (repo, root) in repos {
        let _ = crate::release::cargo::for_each_cargo_toml_with_path(root, &mut |path, doc| {
            let rel = path.strip_prefix(root).unwrap_or(path).to_path_buf();
            let mut collect = |tbl: &toml::Value| {
                if let Some(deps) = tbl.get("dev-dependencies").and_then(|d| d.as_table()) {
                    for (name, v) in deps {
                        let Some(t) = v.as_table() else { continue };
                        let has_path = t.get("path").and_then(|p| p.as_str()).is_some();
                        let has_ver = t.get("version").and_then(|v| v.as_str()).is_some();
                        if has_path && has_ver {
                            // The dep's REAL crate name (respect a `package = "…"` rename).
                            let real = t.get("package").and_then(|p| p.as_str()).unwrap_or(name);
                            out.push(VersionedPathDevDep {
                                repo: repo.clone(),
                                manifest: rel.clone(),
                                dep: real.to_string(),
                            });
                        }
                    }
                }
            };
            collect(doc);
            if let Some(targets) = doc.get("target").and_then(|t| t.as_table()) {
                for (_cfg, t) in targets {
                    collect(t);
                }
            }
        });
    }
    out
}

/// Auto-heal every [`VersionedPathDevDep`] by REMOVING the `version` key from the
/// dev-dep entry (leaving the `path`). Formatting-preserving (`toml_edit`),
/// idempotent (an entry already stripped is simply not re-found). This is the
/// inverse operator of [`fix_path_dep_versions`] and closes the
/// `VersionedPathDevDep` blocker class in `nornir release doctor --fix`.
pub fn fix_versioned_path_dev_deps(
    gaps: &[VersionedPathDevDep],
    repos: &[(String, PathBuf)],
) -> Result<FixOutcome> {
    let repo_root: BTreeMap<&str, &Path> =
        repos.iter().map(|(n, p)| (n.as_str(), p.as_path())).collect();
    let mut by_file: BTreeMap<PathBuf, Vec<&VersionedPathDevDep>> = BTreeMap::new();
    for g in gaps {
        let Some(root) = repo_root.get(g.repo.as_str()) else { continue };
        by_file.entry(root.join(&g.manifest)).or_default().push(g);
    }

    let mut out = FixOutcome::default();
    for (manifest, gs) in by_file {
        let text = std::fs::read_to_string(&manifest)
            .with_context(|| format!("read {}", manifest.display()))?;
        let mut doc: toml_edit::DocumentMut =
            text.parse().with_context(|| format!("parse {}", manifest.display()))?;
        let cfgs: Vec<String> = doc
            .get("target")
            .and_then(|t| t.as_table())
            .map(|t| t.iter().map(|(k, _)| k.to_string()).collect())
            .unwrap_or_default();
        // dev-dep table locators: top-level + each target cfg.
        let mut locators: Vec<Option<String>> = vec![None];
        for c in &cfgs {
            locators.push(Some(c.clone()));
        }
        let mut changed = false;
        for g in gs {
            let mut handled = false;
            for cfg in &locators {
                let Some(tbl) = dev_dep_table_mut(&mut doc, cfg.as_deref()) else { continue };
                // Find the dep key whose real name == g.dep with a path AND a version.
                let key = tbl.iter().find_map(|(k, item)| {
                    let real = item.get("package").and_then(|p| p.as_str()).unwrap_or(k);
                    let has_path = item.get("path").is_some();
                    let has_ver = item.get("version").is_some();
                    (real == g.dep && has_path && has_ver).then(|| k.to_string())
                });
                let Some(key) = key else { continue };
                if let Some(item) = tbl.get_mut(&key) {
                    if let Some(it) = item.as_inline_table_mut() {
                        it.remove("version");
                    } else if let Some(t) = item.as_table_mut() {
                        t.remove("version");
                    }
                    out.fixed += 1;
                    changed = true;
                }
                handled = true;
                break;
            }
            if !handled {
                out.skipped.push(format!(
                    "{}/{}: {} (dev-dep entry not found — already fixed?)",
                    g.repo,
                    g.manifest.display(),
                    g.dep
                ));
            }
        }
        if changed {
            std::fs::write(&manifest, doc.to_string())
                .with_context(|| format!("write {}", manifest.display()))?;
        }
    }
    Ok(out)
}

/// Mutable handle to a `[dev-dependencies]` table (top-level `cfg = None`, or a
/// `[target.'<cfg>'.dev-dependencies]`), creating nothing (returns `None` if
/// absent). Mirrors [`dep_table_mut`] for the dev-dep case.
fn dev_dep_table_mut<'a>(
    doc: &'a mut toml_edit::DocumentMut,
    cfg: Option<&str>,
) -> Option<&'a mut toml_edit::Table> {
    match cfg {
        None => doc.get_mut("dev-dependencies").and_then(|i| i.as_table_mut()),
        Some(c) => doc
            .get_mut("target")
            .and_then(|t| t.as_table_mut())
            .and_then(|t| t.get_mut(c))
            .and_then(|i| i.as_table_mut())
            .and_then(|t| t.get_mut("dev-dependencies"))
            .and_then(|i| i.as_table_mut()),
    }
}

// ─────────────── AUTO remedy executors (#18: --auto apply-fns) ───────────────
//
// `fix-versions` reuses `fix_path_dep_versions` above. These are the three other
// AUTO operators the invertive planner (`graph_math::remedy_table`) emits, made
// executable so `release doctor --auto` applies them to a fixpoint instead of
// printing "apply it manually".

/// Outcome of the `tidy-dirty` AUTO remedy.
#[derive(Debug, Default)]
pub struct TidyOutcome {
    /// Noise entries (files + `.claude/` dirs) removed across all dirty repos.
    pub removed: usize,
    /// Repos that became clean after shedding noise.
    pub cleaned: Vec<String>,
    /// Repos still dirty after tidying — real (non-noise) changes remain, so the
    /// dirtiness is a DECISION (commit/stash it), not auto-tidyable.
    pub still_dirty: Vec<String>,
}

/// Working-tree NOISE a dirty repo may shed without a decision, matching the
/// `tidy-dirty` remedy sentence: the agent scratch dir (`.claude/`) and arrow
/// scratch files (`*.arrows`). Everything else is real content — never touched.
fn is_tidy_noise_dir(name: &str) -> bool {
    name == ".claude"
}
fn is_tidy_noise_file(name: &str) -> bool {
    name.ends_with(".arrows")
}

/// Recursively delete `.claude/` dirs and `*.arrows` files under `root`, skipping
/// `.git` and `target`. Returns how many top-level noise entries were removed.
fn remove_tidy_noise(root: &Path) -> Result<usize> {
    let mut removed = 0usize;
    let mut stack = vec![root.to_path_buf()];
    while let Some(dir) = stack.pop() {
        let Ok(entries) = std::fs::read_dir(&dir) else { continue };
        for e in entries.flatten() {
            let p = e.path();
            let name = p.file_name().and_then(|n| n.to_str()).unwrap_or("").to_string();
            let is_dir = e.file_type().map(|t| t.is_dir()).unwrap_or(false);
            if is_dir {
                if name == ".git" || name == "target" {
                    continue;
                }
                if is_tidy_noise_dir(&name) {
                    std::fs::remove_dir_all(&p)
                        .with_context(|| format!("rm -r {}", p.display()))?;
                    removed += 1;
                } else {
                    stack.push(p);
                }
            } else if is_tidy_noise_file(&name) {
                std::fs::remove_file(&p).with_context(|| format!("rm {}", p.display()))?;
                removed += 1;
            }
        }
    }
    Ok(removed)
}

/// The `tidy-dirty` executor: for every DIRTY repo, shed working-tree noise
/// (`.claude/`, `*.arrows`) and re-assess. A repo whose dirtiness was pure noise
/// goes clean (closing the `Dirty` symptom); one with real uncommitted changes
/// stays dirty and is reported (a DECISION for the human). Pure filesystem +
/// gix status — no `git` subprocess.
pub fn tidy_dirty_repos(
    dirty: &[RepoDirty],
    repos: &[(String, PathBuf)],
) -> Result<TidyOutcome> {
    let root_of: BTreeMap<&str, &Path> =
        repos.iter().map(|(n, p)| (n.as_str(), p.as_path())).collect();
    let mut out = TidyOutcome::default();
    for d in dirty.iter().filter(|d| d.dirty) {
        let Some(root) = root_of.get(d.repo.as_str()) else { continue };
        out.removed += remove_tidy_noise(root)?;
        match crate::gitio::worktree_freshness(root) {
            Ok(f) if !f.dirty => out.cleaned.push(d.repo.clone()),
            _ => out.still_dirty.push(d.repo.clone()),
        }
    }
    Ok(out)
}

/// Outcome of the `cut-cycle-cheap` AUTO remedy.
#[derive(Debug, Default)]
pub struct CutOutcome {
    /// The `(from, to)` crate edges physically cut from a manifest.
    pub cut: Vec<(String, String)>,
    /// Cheap cut edges we could not locate in a manifest (reported, not fatal —
    /// e.g. the edge is a `workspace = true` inherit we don't rewrite here).
    pub unresolved: Vec<(String, String)>,
}

/// Drop the dependency on `to_crate` inside a single manifest `[dev-dependencies]`
/// table (incl. `[target.'cfg'.dev-dependencies]`). Returns `true` if removed.
fn cut_dev_edge_in_manifest(doc: &mut toml_edit::DocumentMut, to_crate: &str) -> bool {
    fn real_name<'a>(key: &'a str, item: &'a toml_edit::Item) -> &'a str {
        item.get("package").and_then(|p| p.as_str()).unwrap_or(key)
    }
    // Top-level and per-target dev-dependency tables.
    let mut cut = false;
    if let Some(tbl) = doc.get_mut("dev-dependencies").and_then(|i| i.as_table_like_mut()) {
        let key = tbl.iter().find(|(k, item)| real_name(k, item) == to_crate).map(|(k, _)| k.to_string());
        if let Some(k) = key {
            tbl.remove(&k);
            cut = true;
        }
    }
    if let Some(targets) = doc.get_mut("target").and_then(|i| i.as_table_like_mut()) {
        let cfgs: Vec<String> = targets.iter().map(|(k, _)| k.to_string()).collect();
        for cfg in cfgs {
            if let Some(tbl) = targets
                .get_mut(&cfg)
                .and_then(|i| i.get_mut("dev-dependencies"))
                .and_then(|i| i.as_table_like_mut())
            {
                let key = tbl.iter().find(|(k, item)| real_name(k, item) == to_crate).map(|(k, _)| k.to_string());
                if let Some(k) = key {
                    tbl.remove(&k);
                    cut = true;
                }
            }
        }
    }
    cut
}

/// Cut the edge on `to_crate` inside `repo_root`'s manifests. Preference order
/// matches the MFAS cost model: a **dev** edge (cost 0) is removed outright; an
/// **optional** `[dependencies]` edge (cost 1) is removed together with the
/// `[features]` references that enabled it (gate the feature off). A NORMAL hard
/// dep is NOT cut (that is a crate-split DECISION). Returns `true` if a manifest
/// was edited.
fn cut_edge_in_repo(repo_root: &Path, to_crate: &str) -> Result<bool> {
    for manifest in find_cargo_tomls(repo_root, 3) {
        let text = std::fs::read_to_string(&manifest)
            .with_context(|| format!("read {}", manifest.display()))?;
        let mut doc: toml_edit::DocumentMut =
            text.parse().with_context(|| format!("parse {}", manifest.display()))?;

        // Cost-0: drop a dev edge.
        if cut_dev_edge_in_manifest(&mut doc, to_crate) {
            std::fs::write(&manifest, doc.to_string())
                .with_context(|| format!("write {}", manifest.display()))?;
            return Ok(true);
        }

        // Cost-1: an OPTIONAL normal dep → remove it + scrub the features that
        // enabled it (gate the feature off).
        let opt_key = doc
            .get("dependencies")
            .and_then(|i| i.as_table_like())
            .and_then(|tbl| {
                tbl.iter().find_map(|(k, item)| {
                    let real = item.get("package").and_then(|p| p.as_str()).unwrap_or(k);
                    let optional = item.get("optional").and_then(|o| o.as_bool()).unwrap_or(false);
                    (real == to_crate && optional).then(|| k.to_string())
                })
            });
        if let Some(key) = opt_key {
            if let Some(tbl) = doc.get_mut("dependencies").and_then(|i| i.as_table_like_mut()) {
                tbl.remove(&key);
            }
            scrub_feature_refs(&mut doc, &key);
            std::fs::write(&manifest, doc.to_string())
                .with_context(|| format!("write {}", manifest.display()))?;
            return Ok(true);
        }
    }
    Ok(false)
}

/// Remove every `[features]` reference to the (now-dropped) optional dep `key`:
/// bare `key`, explicit `dep:key`, and weak `key?/feat` / `key/feat` activations.
/// A feature whose only member was that ref is left as an empty array (harmless)
/// rather than deleted, so an external `--features <name>` invocation still
/// resolves.
fn scrub_feature_refs(doc: &mut toml_edit::DocumentMut, key: &str) {
    let Some(features) = doc.get_mut("features").and_then(|i| i.as_table_like_mut()) else {
        return;
    };
    let feat_names: Vec<String> = features.iter().map(|(k, _)| k.to_string()).collect();
    for fname in feat_names {
        if let Some(arr) = features.get_mut(&fname).and_then(|i| i.as_array_mut()) {
            arr.retain(|v| {
                let s = v.as_str().unwrap_or("");
                let dep = s.strip_prefix("dep:").unwrap_or(s);
                let base = dep.split(['/', '?']).next().unwrap_or(dep);
                base != key
            });
        }
    }
}

/// The `cut-cycle-cheap` executor: rebuild the crate graph from the live
/// manifests, and for every CHEAP (MFAS cut cost ≤ 1) dependency cycle, apply
/// its cheapest cut by editing the manifest that declares the edge (see
/// [`cut_edge_in_repo`]). Returns the edges cut; a cheap cut whose manifest edge
/// can't be located is reported in `unresolved` (never fatal).
pub fn apply_cheap_cycle_cuts(repos: &[(String, PathBuf)]) -> Result<CutOutcome> {
    let graphs: Vec<RepoGraph> = repos
        .iter()
        .filter_map(|(n, p)| gather_repo_graph(n, p).ok())
        .collect();
    let (owner, _adj) = crate_graph(&graphs);
    let root_of: BTreeMap<&str, &Path> =
        repos.iter().map(|(n, p)| (n.as_str(), p.as_path())).collect();
    let mut out = CutOutcome::default();
    for cs in cycle_solutions(&graphs) {
        let Some(best) = cs.solutions.first() else { continue };
        if best.cost > 1 {
            continue; // not cheap → a crate-split DECISION, not an AUTO cut
        }
        for (from, to) in &best.edges {
            let located = owner
                .get(from)
                .and_then(|repo| root_of.get(repo.as_str()))
                .map(|root| cut_edge_in_repo(root, to))
                .transpose()?
                .unwrap_or(false);
            if located {
                out.cut.push((from.clone(), to.clone()));
            } else {
                out.unresolved.push((from.clone(), to.clone()));
            }
        }
    }
    Ok(out)
}

// ─────────────── cross-repo graph: topo order + blast radius ───────────────

/// The dependency table an edge was declared in. Dev edges are tracked (for
/// blast-radius / "who tests against whom") but are NEVER publish-order-gating: a
/// `cargo publish` requires a crate's Normal+Build deps on crates.io first, but
/// not its dev-deps (they're not part of the published crate's requirements for
/// consumers). Master-of-deps points #1/#2.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
pub enum DepKind {
    Normal,
    Build,
    Dev,
}

/// What a repo produces (its package names) and the cross-repo dependency facts —
/// enough to compute cross-repo edges LOCALLY (no warehouse, so it's correct even
/// for a monitored workspace where the warehouse `build_order` falls back to
/// alphabetical). The "master of dependencies": `deps` carries ONLY order-gating
/// edges (in-workspace `path=` Normal/Build deps, optional INCLUDED); dev edges,
/// optional/feature-gated deps, target-`cfg` deps, and crates.io version-pins are
/// tracked separately for transparency without polluting the order.
#[derive(Debug, Clone, Default)]
pub struct RepoGraph {
    pub repo: String,
    pub produces: std::collections::BTreeSet<String>,
    /// PUBLISH-ORDER-gating dependency crate names: in-workspace (`path=`, or
    /// `workspace=true` resolving to a path) deps of kind Normal|Build, OPTIONAL
    /// included (an optional path dep is still written into the published manifest
    /// → its producer must publish first). EXCLUDES: dev-deps, `publish=false`
    /// crates' deps, and pure crates.io version-pins (no path → already on the
    /// registry → not gating for a from-source republish).
    pub deps: std::collections::BTreeSet<String>,
    /// Dependency crate names declared under a `[dev-dependencies]` table anywhere
    /// in the repo (path OR version, any member incl. `publish=false` xtasks). NOT
    /// order-gating; surfaced in the "excluded dev-dep cross-repo edges" report so
    /// the exclusion is transparent (master-of-deps point #7).
    pub dev_deps: std::collections::BTreeSet<String>,
    /// Order-gating OPTIONAL (feature-gated) path dep crate name → the feature(s)
    /// that enable it (`[features]`, incl. `dep:foo` and weak `foo?/feat`). These
    /// ARE in `deps` (real publish deps) but are also surfaced in a dedicated
    /// section (master-of-deps point #4).
    pub optional_deps: std::collections::BTreeMap<String, std::collections::BTreeSet<String>>,
    /// Order-gating path dep crate name → the `[target.'cfg(…)']` string(s) it is
    /// gated under. These ARE in `deps`; surfaced tagged with the cfg
    /// (master-of-deps point #5).
    pub cfg_deps: std::collections::BTreeMap<String, std::collections::BTreeSet<String>>,
    /// Cross-repo-by-NAME deps pinned to a crates.io VERSION (no `path=`) — they
    /// would be order edges in the naive name-only model but are NOT gating
    /// (already resolvable from the registry). Tracked so a path-vs-version
    /// surprise is visible (master-of-deps point #8).
    pub version_pinned: std::collections::BTreeSet<String>,
    /// PER-CRATE order-gating in-workspace dep crate names (publishable crate name
    /// → the in-workspace path Normal/Build deps, optional included). cargo publishes
    /// CRATES, not repos, so this is the granularity at which the true publish order
    /// and real cycles live — a repo-level mutual dep (facett⇄knut) is often a clean
    /// crate-level DAG (facett-pipeline→knut-popsim, knut-pipelines→facett-pipeline,
    /// no loop). Used by [`publish_order`] / [`detect_cycles`].
    pub crate_deps: std::collections::BTreeMap<String, std::collections::BTreeSet<String>>,
    /// Order-gating in-workspace dep crate name → the version REQUIREMENT string(s)
    /// this repo declares on it (`version = "0.1"`, or resolved from
    /// `[workspace.dependencies]` under `workspace = true`). A crate can carry more
    /// than one requirement when several members depend on it at different pins.
    /// Used by [`registry_non_gating_crates`] to decide whether crates.io ALREADY
    /// serves a version satisfying the consumer — an already-satisfied edge is not
    /// order-gating even when the producer is also in the publish set. A path dep
    /// with NO `version=` records the empty string (a sentinel: it can never resolve
    /// from the registry → stays gating).
    pub dep_reqs: std::collections::BTreeMap<String, std::collections::BTreeSet<String>>,
}

/// The real crate name a dependency entry resolves to, honoring a `package = "…"`
/// rename (what `cargo metadata`'s `Dependency.name` reports).
fn dep_real_name(key: &str, spec: &toml::Value) -> String {
    spec.as_table()
        .and_then(|t| t.get("package"))
        .and_then(|p| p.as_str())
        .unwrap_or(key)
        .to_string()
}

/// The version REQUIREMENT a dependency entry declares, if any: the `version = …`
/// of a table entry, or a bare `dep = "1.2"` string. `None` when the entry states
/// no version (e.g. a path-only dep, or a `workspace = true` inheritance whose
/// requirement must be looked up in `[workspace.dependencies]` by the caller).
fn dep_version_req_string(spec: &toml::Value) -> Option<String> {
    match spec {
        toml::Value::Table(t) => {
            t.get("version").and_then(|v| v.as_str()).map(str::to_string)
        }
        toml::Value::String(s) => Some(s.clone()),
        _ => None,
    }
}

/// True when `spec` resolves to IN-WORKSPACE SOURCE: a direct `path = …`, or a
/// `workspace = true` inheritance whose `[workspace.dependencies]` entry (looked up
/// by real name in `ws_paths`) itself carries a path. A pure version dep (no path)
/// is crates.io-resolvable and so NOT order-gating for a from-source republish.
fn dep_is_source_path(
    spec: &toml::Value,
    real: &str,
    ws_paths: &BTreeMap<String, bool>,
) -> bool {
    match spec {
        toml::Value::Table(t) => {
            if t.contains_key("path") {
                return true;
            }
            if t.get("workspace").and_then(|w| w.as_bool()).unwrap_or(false) {
                return *ws_paths.get(real).unwrap_or(&false);
            }
            false
        }
        // A bare `foo = "1.2"` is a version pin — never a path.
        _ => false,
    }
}

/// Scan a repo's Cargo.tomls into the cross-repo dependency facts. The master
/// gatherer: resolves workspace inheritance, separates dep KINDS, keeps optional
/// + target-`cfg` deps in the order graph (tagged), and excludes dev / version-pin
/// / `publish=false` edges from ordering while still recording them for the report.
pub fn gather_repo_graph(repo: &str, root: &Path) -> Result<RepoGraph> {
    use std::collections::BTreeSet;
    let manifests: Vec<toml::Value> = find_cargo_tomls(root, 4)
        .into_iter()
        .filter_map(|p| std::fs::read_to_string(&p).ok())
        .filter_map(|t| t.parse::<toml::Value>().ok())
        .collect();

    // Pass 1: the repo's `[workspace.dependencies]` — real name → has-path. Used to
    // resolve `dep.workspace = true` inheritance back to a real path/version. Also
    // captures the inherited version REQUIREMENT so a `workspace = true` path dep
    // still surfaces the `version=` a consumer resolves the registry copy at.
    let mut ws_paths: BTreeMap<String, bool> = BTreeMap::new();
    let mut ws_reqs: BTreeMap<String, String> = BTreeMap::new();
    for doc in &manifests {
        if let Some(t) = doc
            .get("workspace")
            .and_then(|w| w.get("dependencies"))
            .and_then(|t| t.as_table())
        {
            for (key, spec) in t {
                let real = dep_real_name(key, spec);
                let has_path = spec.as_table().map(|s| s.contains_key("path")).unwrap_or(false);
                ws_paths.insert(real.clone(), has_path);
                if let Some(req) = dep_version_req_string(spec) {
                    ws_reqs.insert(real, req);
                }
            }
        }
    }

    let mut g = RepoGraph { repo: repo.to_string(), ..Default::default() };

    for doc in &manifests {
        let package = doc.get("package");
        // `publish = false` (xtask, bench, internal test helpers): ships nothing, so
        // its deps must NEVER gate publish order (that's what turns the
        // nornir↔{holger,znippy,facett} tooling link into a false cycle). Its DEV
        // edges are still captured below for the transparency report.
        let publishable = package
            .and_then(|p| p.get("publish"))
            .and_then(|v| v.as_bool())
            .unwrap_or(true);
        let pkg_name = package
            .and_then(|p| p.get("name"))
            .and_then(|n| n.as_str())
            .map(str::to_string);
        if publishable {
            if let Some(n) = &pkg_name {
                g.produces.insert(n.clone());
                g.crate_deps.entry(n.clone()).or_default();
            }
        }

        // Enumerate every dep table in this manifest: the three top-level kinds plus
        // their `[target.'cfg(…)'.…]` variants (master-of-deps point #5).
        let kinds = [
            ("dependencies", DepKind::Normal),
            ("build-dependencies", DepKind::Build),
            ("dev-dependencies", DepKind::Dev),
        ];
        let mut tables: Vec<(DepKind, Option<String>, &toml::Value)> = Vec::new();
        for (k, kind) in kinds {
            if let Some(t) = doc.get(k) {
                tables.push((kind, None, t));
            }
        }
        if let Some(targets) = doc.get("target").and_then(|t| t.as_table()) {
            for (cfg, ct) in targets {
                for (k, kind) in kinds {
                    if let Some(t) = ct.get(k) {
                        tables.push((kind, Some(cfg.clone()), t));
                    }
                }
            }
        }

        // First find the OPTIONAL order-table dep keys (so `[features]` can be
        // mapped to the deps it enables).
        let mut optional_keys: BTreeSet<String> = BTreeSet::new();
        for (kind, _cfg, t) in &tables {
            if *kind == DepKind::Dev {
                continue;
            }
            let Some(tbl) = t.as_table() else { continue };
            for (key, spec) in tbl {
                if spec.as_table().and_then(|d| d.get("optional")).and_then(|o| o.as_bool()).unwrap_or(false) {
                    optional_keys.insert(key.clone());
                }
            }
        }
        // `[features]` → which optional dep KEYS each feature turns on. Forms:
        // `dep:foo` (explicit), `foo/feat` (enables foo), `foo?/feat` (weak — does
        // NOT enable foo), bare `foo` (enables optional dep foo). An optional dep
        // with no explicit reference gets the implicit same-named feature.
        let mut key_features: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
        if let Some(feats) = doc.get("features").and_then(|f| f.as_table()) {
            for (feat, list) in feats {
                let Some(arr) = list.as_array() else { continue };
                for item in arr {
                    let Some(s) = item.as_str() else { continue };
                    let enabled = if let Some(rest) = s.strip_prefix("dep:") {
                        Some(rest.to_string())
                    } else if let Some((name, _)) = s.split_once('/') {
                        if name.ends_with('?') { None } else { Some(name.to_string()) }
                    } else {
                        Some(s.to_string())
                    };
                    if let Some(dep) = enabled {
                        if optional_keys.contains(&dep) {
                            key_features.entry(dep).or_default().insert(feat.clone());
                        }
                    }
                }
            }
        }
        for key in &optional_keys {
            // Implicit feature `foo` for an optional dep `foo` with no explicit
            // `dep:foo` mention — cargo synthesizes it.
            key_features.entry(key.clone()).or_default().insert(key.clone());
        }

        // Second pass: record edges.
        for (kind, cfg, t) in &tables {
            let Some(tbl) = t.as_table() else { continue };
            for (key, spec) in tbl {
                let real = dep_real_name(key, spec);
                if *kind == DepKind::Dev {
                    // Dev edge — captured for the transparency report, never gating.
                    // (A dep named exactly after its own repo is still its own crate
                    // dev-dep, harmless: cross-repo matching filters to producers.)
                    if real != repo {
                        g.dev_deps.insert(real);
                    }
                    continue;
                }
                // Normal / Build. Only PUBLISHABLE crates' deps gate order.
                if !publishable {
                    continue;
                }
                if dep_is_source_path(spec, &real, &ws_paths) {
                    // Per-CRATE order edge (incl. same-repo crate deps, e.g.
                    // skade-katalog→skade) — the true publish granularity. The topo
                    // filters to produced crate names, so a self-named dep is fine.
                    if let Some(pn) = &pkg_name {
                        if *pn != real {
                            g.crate_deps.entry(pn.clone()).or_default().insert(real.clone());
                        }
                    }
                    // Repo-level set skips a dep named exactly after this repo
                    // (avoids a self-loop in the coarse repo graph).
                    if real == repo {
                        continue;
                    }
                    g.deps.insert(real.clone());
                    // Record the version REQUIREMENT this consumer declares on the dep
                    // (direct `version=`, or the inherited `[workspace.dependencies]`
                    // pin under `workspace = true`). The empty string is a sentinel for
                    // a path dep with NO version = → it can never resolve from the
                    // registry, so it must stay order-gating.
                    let req = dep_version_req_string(spec)
                        .or_else(|| {
                            spec.as_table()
                                .and_then(|d| d.get("workspace"))
                                .and_then(|w| w.as_bool())
                                .unwrap_or(false)
                                .then(|| ws_reqs.get(&real).cloned())
                                .flatten()
                        })
                        .unwrap_or_default();
                    g.dep_reqs.entry(real.clone()).or_default().insert(req);
                    if optional_keys.contains(key) {
                        let feats = key_features.get(key).cloned().unwrap_or_default();
                        g.optional_deps.entry(real.clone()).or_default().extend(feats);
                    }
                    if let Some(c) = cfg {
                        g.cfg_deps.entry(real.clone()).or_default().insert(c.clone());
                    }
                } else {
                    // Cross-repo-by-name but version-pinned to crates.io → not gating.
                    g.version_pinned.insert(real);
                }
            }
        }
    }
    Ok(g)
}

/// repo → the set of OTHER repos it depends on (A→B when A declares a dependency
/// on a crate B produces).
fn repo_edges(graphs: &[RepoGraph]) -> BTreeMap<String, std::collections::BTreeSet<String>> {
    repo_edges_gated(graphs, &std::collections::BTreeSet::new())
}

/// Like [`repo_edges`] but treats any dep crate in `non_gating` as ALREADY
/// resolvable from crates.io — its current published version satisfies the
/// dependent's `version=` requirement, so on publish cargo strips the local
/// `path=` and resolves it from the registry (no republish-first needed). An
/// edge justified ONLY by such crates is therefore dropped. This is what stops a
/// STRAGGLER `path=` dep on an already-published crate (the real incident:
/// `tunnr → nornir-testmatrix 0.2.4`) from forging a FALSE repo cycle that
/// collapses to an SCC and mis-orders the cascade (draupnir published before
/// `tunnr-vm` exists → fail-stop). With an empty set it is exactly the naive
/// name-only model (every prior caller keeps its behavior).
fn repo_edges_gated(
    graphs: &[RepoGraph],
    non_gating: &std::collections::BTreeSet<String>,
) -> BTreeMap<String, std::collections::BTreeSet<String>> {
    let mut out: BTreeMap<String, std::collections::BTreeSet<String>> = BTreeMap::new();
    for a in graphs {
        let set = out.entry(a.repo.clone()).or_default();
        for b in graphs {
            if a.repo == b.repo {
                continue;
            }
            // Edge a→b iff a depends on SOME crate b produces that STILL gates —
            // i.e. is not already satisfiable from the registry.
            let gates =
                b.produces.iter().any(|c| a.deps.contains(c) && !non_gating.contains(c));
            if gates {
                set.insert(b.repo.clone());
            }
        }
    }
    out
}

/// Every crate that JUSTIFIES a cross-repo publish-order edge — produced by one
/// repo and (gating-) depended on by another. ONLY these need a registry probe
/// to decide whether they still gate (unpublished) or resolve from crates.io
/// (already live), so the caller can probe a handful of crates instead of the
/// whole constellation. Pure.
pub fn cross_repo_gating_crates(
    graphs: &[RepoGraph],
) -> std::collections::BTreeSet<String> {
    let mut out = std::collections::BTreeSet::new();
    for a in graphs {
        for b in graphs {
            if a.repo == b.repo {
                continue;
            }
            for c in b.produces.intersection(&a.deps) {
                out.insert(c.clone());
            }
        }
    }
    out
}

/// Which cross-repo gating crates are ALREADY resolvable from the registry and so
/// NON-order-gating: crates.io serves a published version satisfying EVERY
/// consumer's declared requirement. This is the general, correct rule the naive
/// order misses — it holds **regardless of whether the crate's producing repo is
/// ALSO in the current publish set**. The consumer resolves the dep from the
/// registry (the required version already exists), so the producer need NOT publish
/// first; order is a hard blocker ONLY when a consumer's requirement can be met
/// solely by a not-yet-published version (a fresh crate, or a pin bumped past every
/// live version — the genuinely-unpublished case, which stays gating).
///
/// A crate is dropped to non-gating iff, for the crate `c`:
///   * at least one consumer in the set gates on it (it justifies a cross-repo
///     edge), AND
///   * EVERY consumer requirement on `c` is satisfied by some published version
///     (`probe.req_satisfied == Some(true)`). A consumer that declares no version
///     (empty-string sentinel: a path dep with no `version=`) can never resolve
///     from the registry, so its presence keeps `c` gating; and a `None` probe
///     (offline / undeterminable) is conservative — it keeps `c` gating.
///
/// Requiring ALL consumers satisfied is the conservative choice for a GLOBAL
/// non-gating set: if one consumer needs an unpublished version while another is
/// happy with a live one, the crate must still be produced first for the former.
/// Pure over `graphs` + the injected `probe`.
pub fn registry_non_gating_crates(
    graphs: &[RepoGraph],
    probe: &dyn crate::release::preflight::RegistryProbe,
) -> std::collections::BTreeSet<String> {
    use std::collections::{BTreeMap, BTreeSet};
    let gating = cross_repo_gating_crates(graphs);
    // Per gating crate → every version requirement a CONSUMER (a different repo that
    // does not itself produce the crate) declares on it. A gating dep with no
    // recorded requirement contributes the empty-string sentinel (stays gating).
    let mut reqs: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
    for a in graphs {
        for c in &gating {
            if a.deps.contains(c) && !a.produces.contains(c) {
                let entry = reqs.entry(c.clone()).or_default();
                match a.dep_reqs.get(c) {
                    Some(rs) if !rs.is_empty() => entry.extend(rs.iter().cloned()),
                    _ => {
                        entry.insert(String::new());
                    }
                }
            }
        }
    }
    let mut out = BTreeSet::new();
    for c in &gating {
        let Some(rs) = reqs.get(c) else { continue };
        if rs.is_empty() {
            continue;
        }
        let all_satisfied = rs
            .iter()
            .all(|r| !r.is_empty() && probe.req_satisfied(c, r) == Some(true));
        if all_satisfied {
            out.insert(c.clone());
        }
    }
    out
}

#[derive(Debug, Clone, Default, Serialize)]
pub struct TopoReport {
    /// Publish order: dependencies before dependents.
    pub order: Vec<String>,
    /// Repos left unordered because they sit on a dependency cycle (empty = DAG).
    pub cycle: Vec<String>,
}

/// Topological PUBLISH order (dependencies first), Kahn's algorithm over local
/// Cargo.toml edges. Deterministic (ties broken by name).
pub fn publish_order(graphs: &[RepoGraph]) -> TopoReport {
    let deps_on = repo_edges(graphs);
    let mut indeg: BTreeMap<String, usize> =
        deps_on.iter().map(|(r, d)| (r.clone(), d.len())).collect();
    let mut dependents: BTreeMap<String, Vec<String>> = BTreeMap::new();
    for (a, ds) in &deps_on {
        for b in ds {
            dependents.entry(b.clone()).or_default().push(a.clone());
        }
    }
    let mut ready: std::collections::BTreeSet<String> =
        indeg.iter().filter(|&(_, &d)| d == 0).map(|(r, _)| r.clone()).collect();
    let mut order = Vec::new();
    while let Some(n) = ready.iter().next().cloned() {
        ready.remove(&n);
        order.push(n.clone());
        if let Some(deps) = dependents.get(&n) {
            for a in deps {
                if let Some(d) = indeg.get_mut(a) {
                    *d -= 1;
                    if *d == 0 {
                        ready.insert(a.clone());
                    }
                }
            }
        }
    }
    let cycle: Vec<String> =
        indeg.keys().filter(|r| !order.contains(r)).cloned().collect();
    TopoReport { order, cycle }
}

/// Transitive dependents of `repo` — the blast radius of changing it (who must be
/// re-validated / re-released).
pub fn blast_radius(graphs: &[RepoGraph], repo: &str) -> Vec<String> {
    let deps_on = repo_edges(graphs);
    let mut result = std::collections::BTreeSet::new();
    let mut stack = vec![repo.to_string()];
    while let Some(cur) = stack.pop() {
        for (a, ds) in &deps_on {
            if ds.contains(&cur) && result.insert(a.clone()) {
                stack.push(a.clone());
            }
        }
    }
    result.into_iter().collect()
}

// ─────────────────── cycle-break advisor ───────────────────

/// A concrete suggestion for breaking ONE dependency cycle: the cycle's members,
/// the single edge cheapest to cut (the one justified by the FEWEST crates), the
/// crates on that edge, and human advice.
#[derive(Debug, Clone, Serialize)]
pub struct CycleAdvice {
    /// The strongly-connected component = the repos mutually entangled.
    pub members: Vec<String>,
    /// Suggested edge to cut: `cut_from` depends on `cut_to`.
    pub cut_from: String,
    pub cut_to: String,
    /// The crates `cut_to` produces that `cut_from` depends on — the thing to
    /// extract or make optional to break the edge.
    pub via: Vec<String>,
    pub rationale: String,
}

/// Crates that justify the edge `from → to`: the ones `to` produces and `from`
/// depends on. The smaller this set, the cheaper the edge is to cut.
fn edge_via(graphs: &[RepoGraph], from: &str, to: &str) -> Vec<String> {
    let (Some(f), Some(t)) = (
        graphs.iter().find(|g| g.repo == from),
        graphs.iter().find(|g| g.repo == to),
    ) else {
        return vec![];
    };
    let mut v: Vec<String> = t.produces.intersection(&f.deps).cloned().collect();
    v.sort();
    v
}

/// Strongly-connected components over a dependency graph — now the CANONICAL
/// Tarjan in [`super::graph_math::tarjan_scc`] (`O(V+E)`, sorted comps,
/// deterministic). Each SCC with >1 node (or a self-loop) is a dependency cycle.
/// Kept as a thin alias so the existing `cycle_advice`/`detect_cycles`/
/// `crate_publish_order` call sites read unchanged while the algorithm lives once.
fn sccs(edges: &BTreeMap<String, std::collections::BTreeSet<String>>) -> Vec<Vec<String>> {
    super::graph_math::tarjan_scc(edges)
}

/// For every dependency CYCLE (SCC > 1, or a self-loop), suggest the cheapest edge
/// to cut: the intra-cycle edge justified by the fewest crates (ties broken by
/// name). Pure — operates on the local Cargo.toml graph. Empty when the graph is a
/// clean DAG.
pub fn cycle_advice(graphs: &[RepoGraph]) -> Vec<CycleAdvice> {
    let edges = repo_edges(graphs);
    let mut advice = Vec::new();
    for comp in sccs(&edges) {
        let in_comp: std::collections::BTreeSet<&str> = comp.iter().map(|s| s.as_str()).collect();
        let self_loop =
            comp.len() == 1 && edges.get(&comp[0]).map(|d| d.contains(&comp[0])).unwrap_or(false);
        if comp.len() < 2 && !self_loop {
            continue;
        }
        // Candidate edges: intra-cycle (from → to, both in the SCC).
        let mut best: Option<(String, String, Vec<String>)> = None;
        for from in &comp {
            if let Some(deps) = edges.get(from) {
                for to in deps {
                    if !in_comp.contains(to.as_str()) {
                        continue;
                    }
                    let via = edge_via(graphs, from, to);
                    let better = match &best {
                        None => true,
                        Some((bf, bt, bv)) => {
                            (via.len(), from.as_str(), to.as_str())
                                < (bv.len(), bf.as_str(), bt.as_str())
                        }
                    };
                    if better {
                        best = Some((from.clone(), to.clone(), via));
                    }
                }
            }
        }
        if let Some((cut_from, cut_to, via)) = best {
            let rationale = if via.is_empty() {
                format!("cut `{cut_from} → {cut_to}` (fewest crates)")
            } else if via.len() == 1 {
                format!(
                    "`{cut_from} → {cut_to}` rides on one crate (`{}`); extract it into a leaf crate both depend on, or make the dep optional/dev-only",
                    via[0]
                )
            } else {
                format!(
                    "`{cut_from} → {cut_to}` rides on {} crates ({}); extract them into a shared leaf crate, or make the dep optional/dev-only",
                    via.len(),
                    via.join(", ")
                )
            };
            advice.push(CycleAdvice { members: comp, cut_from, cut_to, via, rationale });
        }
    }
    advice
}

// ─────────────────────── report ───────────────────────

/// One repo→repo dependency edge: `from` depends on `to` because `to` produces
/// one of the crates `from` declares. Carries the `via` crates so the 🧬 release
/// dashboard can label the edge. This is the same relation `repo_edges` computes
/// for the topo/blast analysis, exposed so the dashboard draws the SAME graph
/// without re-scanning Cargo.tomls.
#[derive(Debug, Clone, Serialize)]
pub struct RepoEdge {
    pub from: String,
    pub to: String,
    pub via: Vec<String>,
}

/// The repo→repo dependency edges (with the `via` crates), as a flat list — the
/// graph the 🧬 dashboard paints. Pure: derived from the gathered repo graphs.
pub fn repo_dep_edges(graphs: &[RepoGraph]) -> Vec<RepoEdge> {
    let mut out = Vec::new();
    for a in graphs {
        for b in graphs {
            if a.repo == b.repo {
                continue;
            }
            let mut via: Vec<String> =
                b.produces.iter().filter(|c| a.deps.contains(*c)).cloned().collect();
            if !via.is_empty() {
                via.sort();
                out.push(RepoEdge { from: a.repo.clone(), to: b.repo.clone(), via });
            }
        }
    }
    out.sort_by(|x, y| (&x.from, &x.to).cmp(&(&y.from, &y.to)));
    out
}

// ───────── master-of-deps: kind-tagged cross-repo sections ─────────

/// A cross-repo DEV-dependency edge — `from` dev-depends on a crate `to` produces.
/// Deliberately EXCLUDED from publish order (a dev-dep isn't part of the published
/// crate's requirements). Listed so the exclusion is transparent.
#[derive(Debug, Clone, Serialize)]
pub struct DevEdge {
    pub from: String,
    pub to: String,
    pub via: Vec<String>,
}

/// A feature-gated (optional) cross-repo dependency — KEPT in the order graph
/// (cargo writes optional deps into the published manifest) but surfaced with the
/// enabling feature(s), e.g. `nornir --[optional, feature=facett-viz]--> facett`.
#[derive(Debug, Clone, Serialize)]
pub struct OptionalCrossDep {
    pub from: String,
    pub to: String,
    pub krate: String,
    pub features: Vec<String>,
}

/// A `[target.'cfg(…)']`-gated cross-repo dependency — a real (order-gating) dep
/// tagged with the platform cfg it's conditional on.
#[derive(Debug, Clone, Serialize)]
pub struct CfgCrossDep {
    pub from: String,
    pub to: String,
    pub krate: String,
    pub cfgs: Vec<String>,
}

/// A real dependency CYCLE that REMAINS in the order-relevant (non-dev, path) graph
/// — these are NOT silently broken; doctor reports the entangled repos and every
/// offending intra-cycle edge so the cause is explicit.
#[derive(Debug, Clone, Serialize)]
pub struct DepCycle {
    pub members: Vec<String>,
    pub edges: Vec<RepoEdge>,
}

/// Map each produced crate name → the repo that produces it (publishable crates).
fn producer_index(graphs: &[RepoGraph]) -> BTreeMap<String, String> {
    let mut idx = BTreeMap::new();
    for g in graphs {
        for c in &g.produces {
            idx.insert(c.clone(), g.repo.clone());
        }
    }
    idx
}

/// Cross-repo DEV edges (excluded from order): for each repo's `dev_deps`, the
/// producer repo of each dev-depended crate. Grouped per `from→to` with the
/// justifying crate names. Master-of-deps point #7.
pub fn excluded_dev_edges(graphs: &[RepoGraph]) -> Vec<DevEdge> {
    let producer = producer_index(graphs);
    let mut grouped: BTreeMap<(String, String), std::collections::BTreeSet<String>> = BTreeMap::new();
    for g in graphs {
        for krate in &g.dev_deps {
            if let Some(to) = producer.get(krate) {
                if *to != g.repo {
                    grouped.entry((g.repo.clone(), to.clone())).or_default().insert(krate.clone());
                }
            }
        }
    }
    grouped
        .into_iter()
        .map(|((from, to), via)| DevEdge { from, to, via: via.into_iter().collect() })
        .collect()
}

/// Feature-gated (optional) cross-repo deps with the feature(s) that enable them.
/// Master-of-deps point #4.
pub fn optional_cross_deps(graphs: &[RepoGraph]) -> Vec<OptionalCrossDep> {
    let producer = producer_index(graphs);
    let mut out = Vec::new();
    for g in graphs {
        for (krate, feats) in &g.optional_deps {
            if let Some(to) = producer.get(krate) {
                if *to != g.repo {
                    out.push(OptionalCrossDep {
                        from: g.repo.clone(),
                        to: to.clone(),
                        krate: krate.clone(),
                        features: feats.iter().cloned().collect(),
                    });
                }
            }
        }
    }
    out.sort_by(|a, b| (&a.from, &a.krate).cmp(&(&b.from, &b.krate)));
    out
}

/// Cross-repo deps a repo declares against a crates.io VERSION (no `path=`) for a
/// crate ANOTHER repo produces — e.g. `facett-matrix`'s `nornir-testmatrix = "0.2"`
/// or `nornir`'s `znippy-zoomies = "0.1.13"`. These resolve from the registry, so
/// they are NOT order-gating (the producer needn't publish first) — surfaced so the
/// path-vs-version split is visible (master-of-deps point #8). The false
/// `facett → nornir` edge that mis-ordered nornir lived here.
pub fn version_pinned_cross_deps(graphs: &[RepoGraph]) -> Vec<RepoEdge> {
    let producer = producer_index(graphs);
    let mut grouped: BTreeMap<(String, String), std::collections::BTreeSet<String>> = BTreeMap::new();
    for g in graphs {
        for krate in &g.version_pinned {
            if let Some(to) = producer.get(krate) {
                if *to != g.repo {
                    grouped.entry((g.repo.clone(), to.clone())).or_default().insert(krate.clone());
                }
            }
        }
    }
    grouped
        .into_iter()
        .map(|((from, to), via)| RepoEdge { from, to, via: via.into_iter().collect() })
        .collect()
}

/// `[target.'cfg(…)']`-gated cross-repo deps, tagged with the cfg. Point #5.
pub fn cfg_cross_deps(graphs: &[RepoGraph]) -> Vec<CfgCrossDep> {
    let producer = producer_index(graphs);
    let mut out = Vec::new();
    for g in graphs {
        for (krate, cfgs) in &g.cfg_deps {
            if let Some(to) = producer.get(krate) {
                if *to != g.repo {
                    out.push(CfgCrossDep {
                        from: g.repo.clone(),
                        to: to.clone(),
                        krate: krate.clone(),
                        cfgs: cfgs.iter().cloned().collect(),
                    });
                }
            }
        }
    }
    out.sort_by(|a, b| (&a.from, &a.krate).cmp(&(&b.from, &b.krate)));
    out
}

/// The CRATE-level order graph: crate name → owning repo, and crate name → its
/// in-workspace order-gating dep crate names (filtered to crates actually produced
/// somewhere). cargo publishes CRATES, so this is the granularity where the true
/// order + real cycles live — a repo-level mutual dep that's a clean crate-level DAG
/// (facett⇄knut: facett-pipeline→knut-popsim, knut-pipelines→facett-pipeline) is NOT
/// a real publish cycle and must not block the order.
fn crate_graph(
    graphs: &[RepoGraph],
) -> (
    BTreeMap<String, String>,
    BTreeMap<String, std::collections::BTreeSet<String>>,
) {
    use std::collections::BTreeSet;
    let mut owner: BTreeMap<String, String> = BTreeMap::new();
    let produced: BTreeSet<String> =
        graphs.iter().flat_map(|g| g.crate_deps.keys().cloned()).collect();
    let mut adj: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
    for g in graphs {
        for (c, deps) in &g.crate_deps {
            owner.entry(c.clone()).or_insert_with(|| g.repo.clone());
            let e = adj.entry(c.clone()).or_default();
            for d in deps {
                if d != c && produced.contains(d) {
                    e.insert(d.clone());
                }
            }
        }
    }
    (owner, adj)
}

/// Dependency CYCLES at CRATE granularity — Tarjan SCCs over [`crate_graph`]. Each
/// SCC>1 (or self-loop) is a REAL publish cycle (no crate-level interleaving can
/// resolve it), reported with its crates + the offending intra-cycle edges. Empty =
/// publishable as a clean crate DAG (even if repos look mutually entangled).
/// Master-of-deps point #3.
pub fn detect_cycles(graphs: &[RepoGraph]) -> Vec<DepCycle> {
    let (_owner, adj) = crate_graph(graphs);
    let mut out = Vec::new();
    for comp in sccs(&adj) {
        let in_comp: std::collections::BTreeSet<&str> = comp.iter().map(|s| s.as_str()).collect();
        let self_loop =
            comp.len() == 1 && adj.get(&comp[0]).map(|d| d.contains(&comp[0])).unwrap_or(false);
        if comp.len() < 2 && !self_loop {
            continue;
        }
        let mut cyc_edges = Vec::new();
        for from in &comp {
            if let Some(deps) = adj.get(from) {
                for to in deps {
                    if in_comp.contains(to.as_str()) {
                        cyc_edges.push(RepoEdge { from: from.clone(), to: to.clone(), via: vec![] });
                    }
                }
            }
        }
        out.push(DepCycle { members: comp, edges: cyc_edges });
    }
    out
}

// ─────────────── MFAS cycle solutions + publish waves (graph_math) ───────────────

/// A serialize-friendly view of a [`super::graph_math::CutSolution`]: one concrete
/// way to break a cycle, with its cost, the edges it removes, the human remedy
/// actions, and the residual topo order that PROVES the cut yields a DAG.
#[derive(Debug, Clone, Serialize)]
pub struct CutSolutionView {
    /// Total cut cost (DEV = 0, OPTIONAL = 1, crate-split = high). Lower is better.
    pub cost: u32,
    /// The `(from, to)` edges to remove.
    pub edges: Vec<(String, String)>,
    /// One remedy sentence per removed edge, cheapest-class first.
    pub actions: Vec<String>,
    /// Proof witness: a topological order over the SCC's crates once the edges are
    /// removed. Its existence certifies the residual graph is acyclic.
    pub proof_order: Vec<String>,
}

/// The MFAS-ranked solution set for ONE dependency cycle: the entangled crates
/// (`members` = the SCC) and a list of candidate cuts, cheapest-first.
#[derive(Debug, Clone, Serialize)]
pub struct CycleSolution {
    pub members: Vec<String>,
    pub solutions: Vec<CutSolutionView>,
}

/// For every crate-level dependency cycle, ENUMERATE + RANK the concrete ways to
/// break it (Minimum Feedback Arc Set over the tiny SCC). Each intra-cycle edge is
/// classified — feature-gated crates → OPTIONAL (cheap: gate the feature off),
/// otherwise NORMAL (dear: split a crate) — and [`super::graph_math::min_feedback_arc_set`]
/// returns the ranked cuts, each with a proof the residual is a DAG. This replaces
/// the single-cheapest-edge heuristic of [`cycle_advice`] with a proper ranked list.
/// Empty when the crate graph is a clean DAG.
pub fn cycle_solutions(graphs: &[RepoGraph]) -> Vec<CycleSolution> {
    use std::collections::BTreeSet;
    let (_owner, adj) = crate_graph(graphs);
    // Coarse feature-gate signal: any crate declared as an optional dep somewhere is
    // treated as gate-off-able (cost 1) when it appears as a cut target.
    let optional_crates: BTreeSet<String> =
        graphs.iter().flat_map(|g| g.optional_deps.keys().cloned()).collect();
    let mut out = Vec::new();
    for comp in super::graph_math::cycles(&adj) {
        let in_comp: BTreeSet<&str> = comp.iter().map(|s| s.as_str()).collect();
        let mut edges = Vec::new();
        for from in &comp {
            if let Some(deps) = adj.get(from) {
                for to in deps {
                    if !in_comp.contains(to.as_str()) {
                        continue;
                    }
                    let class = if optional_crates.contains(to) {
                        super::graph_math::EdgeClass::Optional
                    } else {
                        super::graph_math::EdgeClass::Normal
                    };
                    edges.push(super::graph_math::ClassifiedEdge {
                        from: from.clone(),
                        to: to.clone(),
                        via: vec![to.clone()],
                        class,
                    });
                }
            }
        }
        let sols = super::graph_math::min_feedback_arc_set(&comp, &edges);
        out.push(CycleSolution {
            members: comp,
            solutions: sols
                .into_iter()
                .map(|s| CutSolutionView {
                    cost: s.cost,
                    edges: s.edges,
                    actions: s.actions,
                    proof_order: s.proof_order,
                })
                .collect(),
        });
    }
    out
}

// ─────────── ELF/binary graph cross-check (graph_math over linked binaries) ───────────

/// The ELF/binary symbol-dependency graph projected into the SAME graph_math
/// shape the source [`RepoGraph`] uses — the release doctor's second witness:
/// what the LINKED BINARIES actually reference, alongside what the SOURCE
/// manifests declare. Built by [`graph_from_binary`] over
/// [`crate::graph::extract::binary`] (the extractor the CLI `graph binary` verb
/// drives via `to_symbol_rows` / `to_call_edge_rows`).
#[derive(Debug, Clone, Default)]
pub struct BinaryDerivedGraph {
    /// object-node → the object nodes it links against (`DT_NEEDED` + resolved
    /// symbol edges) — the adjacency graph_math's Tarjan/MFAS consume.
    pub adjacency: BTreeMap<String, std::collections::BTreeSet<String>>,
    /// Non-trivial strongly-connected components (link cycles), Tarjan-sorted.
    pub cycles: Vec<Vec<String>>,
    /// Provide/need symbol facts (mirrors the source syn symbol pass).
    pub symbol_rows: Vec<crate::knowledge::symbols::SymbolRow>,
    /// PLT/GOT call edges (mirrors the source call-edge pass).
    pub call_edge_rows: Vec<crate::knowledge::symbols::CallEdgeRow>,
}

impl BinaryDerivedGraph {
    /// Project a [`WorkspaceGraph`](crate::warehouse::dep_graph::WorkspaceGraph)
    /// — the shared model
    /// [`BinaryGraph::to_workspace_graph`](crate::graph::extract::binary::BinaryGraph::to_workspace_graph)
    /// yields — onto the adjacency + cycle structure. Every node appears even with
    /// no out-edges, so an isolated object is still a graph node.
    pub fn from_workspace(wg: &crate::warehouse::dep_graph::WorkspaceGraph) -> Self {
        let mut adjacency: BTreeMap<String, std::collections::BTreeSet<String>> = BTreeMap::new();
        for name in wg.facts.keys() {
            adjacency.entry(name.clone()).or_default();
        }
        for e in &wg.edges {
            adjacency.entry(e.from.clone()).or_default().insert(e.to.clone());
            adjacency.entry(e.to.clone()).or_default();
        }
        let cycles = super::graph_math::cycles(&adjacency);
        Self { adjacency, cycles, symbol_rows: Vec::new(), call_edge_rows: Vec::new() }
    }
}

/// Extract the ELF/binary symbol graph from `paths` and project it into the
/// graph_math shape — the doctor entry over the same extractor the CLI
/// `graph binary` verb drives. Carries the `symbol_rows` / `call_edge_rows` (the
/// warehouse projection) alongside the adjacency + cycles. An unreadable /
/// non-ELF input is skipped inside the extractor, never fatal.
pub fn graph_from_binary(paths: &[PathBuf]) -> Result<BinaryDerivedGraph> {
    let bg = crate::graph::extract::binary::extract_graph(paths)?;
    let wg = bg.to_workspace_graph();
    let mut d = BinaryDerivedGraph::from_workspace(&wg);
    d.symbol_rows = bg.to_symbol_rows();
    d.call_edge_rows = bg.to_call_edge_rows();
    Ok(d)
}

/// The outcome of cross-checking the SOURCE dependency graph against the
/// ELF-derived graph: whether their cycle structure (SCC partition) and their
/// minimum-feedback-arc cut sizes agree.
#[derive(Debug, Clone, Serialize)]
pub struct GraphCrossCheck {
    /// Non-trivial SCCs (sorted node lists) present in BOTH graphs.
    pub shared_cycles: Vec<Vec<String>>,
    /// Cycles the SOURCE graph has that the binary graph does not.
    pub source_only_cycles: Vec<Vec<String>>,
    /// Cycles the BINARY graph has that the source graph does not.
    pub binary_only_cycles: Vec<Vec<String>>,
    /// Per shared cycle where the MFAS min-cut cost differs: `(members, source, binary)`.
    pub mfas_divergences: Vec<(Vec<String>, u32, u32)>,
}

impl GraphCrossCheck {
    /// The two graphs agree iff neither carries a cycle the other lacks AND every
    /// shared cycle has the same minimum-cut cost in both.
    pub fn agrees(&self) -> bool {
        self.source_only_cycles.is_empty()
            && self.binary_only_cycles.is_empty()
            && self.mfas_divergences.is_empty()
    }
}

/// Cross-check the SOURCE crate-dependency graph (`source`, e.g. from
/// [`repo_edges`]) against the ELF-derived graph (`binary`, from
/// [`graph_from_binary`]'s `adjacency`): compares their cycle partition (Tarjan
/// SCCs) and, per shared cycle, the minimum feedback-arc-set cut cost. A
/// divergence means "what the manifests declare" and "what the binaries link"
/// disagree about where the release is tangled — a doctor-worthy signal that the
/// source graph and the shipped artefacts have drifted.
pub fn cross_check_source_vs_binary(
    source: &BTreeMap<String, std::collections::BTreeSet<String>>,
    binary: &BTreeMap<String, std::collections::BTreeSet<String>>,
) -> GraphCrossCheck {
    use std::collections::BTreeSet;
    let src_set: BTreeSet<Vec<String>> = super::graph_math::cycles(source).into_iter().collect();
    let bin_set: BTreeSet<Vec<String>> = super::graph_math::cycles(binary).into_iter().collect();

    let shared_cycles: Vec<Vec<String>> = src_set.intersection(&bin_set).cloned().collect();
    let source_only_cycles: Vec<Vec<String>> = src_set.difference(&bin_set).cloned().collect();
    let binary_only_cycles: Vec<Vec<String>> = bin_set.difference(&src_set).cloned().collect();

    let mut mfas_divergences = Vec::new();
    for comp in &shared_cycles {
        let s_cost = min_cut_cost(source, comp);
        let b_cost = min_cut_cost(binary, comp);
        if s_cost != b_cost {
            mfas_divergences.push((comp.clone(), s_cost, b_cost));
        }
    }
    GraphCrossCheck { shared_cycles, source_only_cycles, binary_only_cycles, mfas_divergences }
}

/// Minimum feedback-arc-set cut cost for one cyclic component `comp` under `adj`
/// — every intra-component edge classed `Normal` (a structural link cut). `0`
/// when the component carries no intra-cycle edges.
fn min_cut_cost(
    adj: &BTreeMap<String, std::collections::BTreeSet<String>>,
    comp: &[String],
) -> u32 {
    let members: std::collections::BTreeSet<&String> = comp.iter().collect();
    let edges: Vec<super::graph_math::ClassifiedEdge> = comp
        .iter()
        .flat_map(|from| {
            adj.get(from)
                .into_iter()
                .flatten()
                .filter(|to| members.contains(to))
                .map(move |to| super::graph_math::ClassifiedEdge {
                    from: from.clone(),
                    to: to.clone(),
                    via: Vec::new(),
                    class: super::graph_math::EdgeClass::Normal,
                })
        })
        .collect();
    super::graph_math::min_feedback_arc_set(comp, &edges)
        .into_iter()
        .map(|s| s.cost)
        .min()
        .unwrap_or(0)
}

/// PARALLELIZABLE PUBLISH WAVES over the crate graph: each wave is an antichain of
/// the SCC condensation = crates publishable CONCURRENTLY (deps-first). A clean DAG
/// yields the finest layering; a cycle keeps its crates together in one wave (they
/// must be untangled first). See [`super::graph_math::Condensation::waves`].
pub fn publish_waves(graphs: &[RepoGraph]) -> Vec<Vec<String>> {
    let (_owner, adj) = crate_graph(graphs);
    super::graph_math::condense(&adj).waves()
}

/// Project a [`DoctorReport`] onto the outcome-space Ω as the open-symptom multiset
/// the invertive planner ([`super::graph_math::plan`]) closes. This is the state
/// projection `s ∈ Ω`: version gaps + skew + dirty + cheap cycles are AUTO classes;
/// non-member deps + hard (split-only) cycles + patch-fork holds are DECISION
/// classes. Cheap-vs-hard is decided by the cycle's cheapest MFAS cut cost.
pub fn symptoms(report: &DoctorReport) -> super::graph_math::Symptoms {
    use super::graph_math::SymptomKind::*;
    let mut s = super::graph_math::Symptoms::new();
    s.set(
        VersionGap,
        report.path_dep_version_gaps.iter().filter(|g| g.dep_owner.is_some()).count(),
    );
    s.set(
        NonMemberDep,
        report.path_dep_version_gaps.iter().filter(|g| g.dep_owner.is_none()).count(),
    );
    // Skew that a plain manifest bump can actually move (not held by a transitive pin).
    s.set(
        Skew,
        report
            .skew
            .iter()
            .filter(|c| {
                c.entries
                    .iter()
                    .any(|e| e.status == SkewStatus::Behind && !e.held_by_transitive_pin)
            })
            .count(),
    );
    s.set(Dirty, report.dirty.iter().filter(|d| d.dirty).count());
    let (mut cheap, mut hard) = (0usize, 0usize);
    for cs in &report.cycle_solutions {
        match cs.solutions.first() {
            Some(best) if best.cost <= 1 => cheap += 1,
            _ => hard += 1, // no solution, or only a crate-split → a decision
        }
    }
    s.set(CheapCycle, cheap);
    s.set(HardCycle, hard);
    s.set(PromoteBlock, report.promote_blocked.len());
    s
}

/// PUBLISH order over REPOS, made cycle-proof by SCC CONDENSATION: repo-level
/// mutual deps (facett⇄knut) collapse into one super-node, the condensation DAG is
/// topo-sorted deps-first, and each super-node expands to its member repos
/// (alphabetical). A repo nothing publishable depends on (e.g. `nornir`) is a sink →
/// sorts LAST, exactly as the user expects. `cycle` carries repos on a REAL
/// crate-level cycle (from [`detect_cycles`]) — empty when the entanglement is a
/// clean interleaved crate DAG, so a repo-level SCC alone does NOT flag a "cycle".
/// Deterministic (ties by smallest member name). Master-of-deps points #2/#3.
pub fn crate_publish_order(graphs: &[RepoGraph]) -> TopoReport {
    crate_publish_order_gated(graphs, &std::collections::BTreeSet::new())
}

/// [`crate_publish_order`] made REGISTRY-AWARE: dep crates in `non_gating` (their
/// current published version already satisfies dependents — see
/// [`repo_edges_gated`]) are dropped from the order graph, so an already-published
/// straggler `path=` dep can't forge a false cycle that mis-orders the cascade.
/// `crate_publish_order(graphs)` is exactly this with an empty set.
pub fn crate_publish_order_gated(
    graphs: &[RepoGraph],
    non_gating: &std::collections::BTreeSet<String>,
) -> TopoReport {
    use std::collections::BTreeSet;
    let edges = repo_edges_gated(graphs, non_gating); // from → repos it depends on
    let comps = sccs(&edges); // each: sorted member list
    let n = comps.len();
    let mut comp_of: BTreeMap<String, usize> = BTreeMap::new();
    for (i, c) in comps.iter().enumerate() {
        for r in c {
            comp_of.insert(r.clone(), i);
        }
    }
    // Condensation: comp → the comps it depends on.
    let mut cadj: Vec<BTreeSet<usize>> = vec![BTreeSet::new(); n];
    for (from, tos) in &edges {
        let cf = comp_of[from];
        for to in tos {
            let ct = comp_of[to];
            if cf != ct {
                cadj[cf].insert(ct);
            }
        }
    }
    // Kahn deps-first over the condensation. indeg(comp) = #comps it depends on.
    let mut indeg: Vec<usize> = (0..n).map(|c| cadj[c].len()).collect();
    let mut consumers: Vec<Vec<usize>> = vec![Vec::new(); n];
    for (cf, deps) in cadj.iter().enumerate() {
        for &ct in deps {
            consumers[ct].push(cf);
        }
    }
    // Ready set ordered by the comp's smallest member name → stable, readable order.
    let key = |c: usize| comps[c].first().cloned().unwrap_or_default();
    let mut ready: BTreeSet<(String, usize)> = (0..n)
        .filter(|&c| indeg[c] == 0)
        .map(|c| (key(c), c))
        .collect();
    let mut order: Vec<String> = Vec::new();
    while let Some((k, c)) = ready.iter().next().cloned() {
        ready.remove(&(k, c));
        // Expand the SCC into its member repos (already sorted).
        order.extend(comps[c].iter().cloned());
        for &con in &consumers[c] {
            indeg[con] -= 1;
            if indeg[con] == 0 {
                ready.insert((key(con), con));
            }
        }
    }
    // REAL cycles are crate-level: only those block publishability. A repo-level SCC
    // that's a clean crate DAG is fully ordered above and reported as NO cycle. Map
    // the crate-cycle members back to their owning repos for the `cycle` field.
    let owner = crate_graph(graphs).0;
    let cycle: Vec<String> = detect_cycles(graphs)
        .iter()
        .flat_map(|c| c.members.iter().filter_map(|kr| owner.get(kr).cloned()))
        .collect::<BTreeSet<_>>()
        .into_iter()
        .collect();
    TopoReport { order, cycle }
}

/// One publish-order defect: `repo` is scheduled to publish BEFORE a gating
/// cross-repo dependency it needs is available on crates.io.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct OrderViolation {
    /// The repo that would `cargo publish` too early.
    pub repo: String,
    /// The dep crate that isn't on the registry yet when `repo` publishes.
    pub dep_crate: String,
    /// The repo that PRODUCES `dep_crate` (scheduled later, or absent from the
    /// plan). Empty string when no repo in the set produces it.
    pub producer: String,
}

/// SELF-CHECK the computed publish `order` BEFORE the irreversible cascade (the
/// "find topological errors at once, before start" guard). Walking repos in
/// `order`, every gating cross-repo dep of a repo must be satisfiable the moment
/// that repo publishes — either already live on crates.io (`available`, the
/// registry-satisfied set) or produced by a repo EARLIER in `order`. A dep that
/// is neither is an [`OrderViolation`]: the cascade would hand `cargo publish` a
/// crate whose sibling isn't on the registry yet and FAIL-STOP mid-run, leaving
/// a torn release (the real `draupnir`-before-`tunnr-vm` incident). Empty ⇒ the
/// order is sound. Pure and deterministic (`BTree`-ordered).
pub fn cascade_order_violations(
    graphs: &[RepoGraph],
    order: &[String],
    available: &std::collections::BTreeSet<String>,
) -> Vec<OrderViolation> {
    use std::collections::{BTreeMap, BTreeSet};
    // Which repo produces each crate.
    let mut producer: BTreeMap<String, String> = BTreeMap::new();
    for g in graphs {
        for c in &g.produces {
            producer.insert(c.clone(), g.repo.clone());
        }
    }
    let by_repo: BTreeMap<&str, &RepoGraph> =
        graphs.iter().map(|g| (g.repo.as_str(), g)).collect();
    // Everything already resolvable, plus crates produced by repos seen so far.
    let mut satisfied: BTreeSet<String> = available.clone();
    let mut viol = Vec::new();
    for repo in order {
        let Some(g) = by_repo.get(repo.as_str()) else { continue };
        for dep in &g.deps {
            // A dep the repo ITSELF produces is intra-repo (the promote publishes a
            // repo's crates together, deps-first internally) — never a cross-repo
            // violation. This also correctly handles a same-NAME collision across
            // repos (e.g. `facett-timeline` exists in both facett and ordning with
            // different APIs): each repo satisfies its own from within.
            if g.produces.contains(dep) {
                continue;
            }
            // Only cross-repo deps produced somewhere in the plan can be ordered;
            // an external crate (not produced here) resolves from crates.io.
            let Some(pr) = producer.get(dep) else { continue };
            if pr == repo || satisfied.contains(dep) {
                continue; // same repo, or already available / produced earlier.
            }
            viol.push(OrderViolation {
                repo: repo.clone(),
                dep_crate: dep.clone(),
                producer: pr.clone(),
            });
        }
        // This repo now publishes → its crates become available downstream.
        for c in &g.produces {
            satisfied.insert(c.clone());
        }
    }
    viol
}

#[derive(Debug, Clone, Default, Serialize)]
pub struct DoctorReport {
    pub dirty: Vec<RepoDirty>,
    pub skew: Vec<CrateSkew>,
    pub topo: TopoReport,
    /// Per dirty repo → its blast radius (transitive dependents to re-validate).
    pub blast: BTreeMap<String, Vec<String>>,
    /// One suggestion per dependency cycle for how to break it. Empty = clean DAG.
    #[serde(default)]
    pub cycle_advice: Vec<CycleAdvice>,
    /// The repo→repo dependency edges (A depends on B). The 🧬 release dashboard
    /// draws its gate-overlaid graph from this. Empty = no inter-repo edges.
    #[serde(default)]
    pub repo_edges: Vec<RepoEdge>,
    /// Direct patch-fork blocks: each `[patch.crates-io]` redirect to a
    /// non-registry (`path`/`git`) fork. Empty = nothing patched to a fork.
    #[serde(default)]
    pub patch_forks: Vec<PatchForkBlock>,
    /// The TRANSITIVE promote-blocked crate set: every workspace crate that, or
    /// whose workspace-internal dep, rides a patch-fork. These are EXCLUDED from
    /// a crates.io publish. Empty = nothing blocked.
    #[serde(default)]
    pub promote_blocked: Vec<String>,
    /// Cross-repo DEV edges deliberately EXCLUDED from publish order (a dev-dep is
    /// not part of the published crate's requirements). Listed for transparency.
    #[serde(default)]
    pub excluded_dev_edges: Vec<DevEdge>,
    /// Feature-gated (optional) cross-repo deps — KEPT in the order graph, surfaced
    /// with the enabling feature(s).
    #[serde(default)]
    pub optional_cross_deps: Vec<OptionalCrossDep>,
    /// `[target.'cfg(…)']`-gated cross-repo deps, tagged with the cfg.
    #[serde(default)]
    pub cfg_cross_deps: Vec<CfgCrossDep>,
    /// Real dependency cycles remaining in the order-relevant graph. Empty = clean.
    #[serde(default)]
    pub cycles: Vec<DepCycle>,
    /// Cross-repo deps pinned to a crates.io VERSION (no path) — NOT order-gating
    /// (resolve from the registry). Surfaces the path-vs-version split.
    #[serde(default)]
    pub version_pinned_cross_deps: Vec<RepoEdge>,
    /// PUBLISH PRE-FLIGHT: publishable crates whose Normal/Build `path` deps lack a
    /// `version` — the `cargo publish` manifest-verify blocker, caught statically
    /// (no rehearse needed). Empty = every path dep is publish-ready.
    #[serde(default)]
    pub path_dep_version_gaps: Vec<PathDepVersionGap>,
    /// MFAS: per real crate cycle, the RANKED list of concrete cuts to break it
    /// (cheapest-first, each proven to yield a DAG). Empty = clean crate DAG.
    #[serde(default)]
    pub cycle_solutions: Vec<CycleSolution>,
    /// PARALLELIZABLE PUBLISH WAVES: the crate-graph condensation layered into
    /// antichains — each wave = crates publishable concurrently (deps-first).
    #[serde(default)]
    pub waves: Vec<Vec<String>>,
    /// SEMANTIC blast radius (EPIC item 7): per bumped repo → the EXACT call sites
    /// in its dependents that touch the changed crate's API, read from the warehouse
    /// SCIP call-graph. This is the sharpening of `blast`: where `blast` is
    /// crate-level reachability ("who depends on it → might break"), this is the
    /// actual call-site delta ("these 12 sites call the 2 symbols that changed").
    /// Empty unless [`run_with_semantic_blast`] was called with a warehouse + the
    /// per-repo changed-symbol sets (a version bump's API diff).
    #[serde(default)]
    pub semantic_blast: BTreeMap<String, crate::release::semantic_blast::SemanticBlast>,
    /// EXPLAINED HELD SET (`--explain`): one entry per crate in `promote_blocked`,
    /// stating the foreign fork it rides (`fork_kind` + `patched_dep`), whether the
    /// dependency is direct, and how to unblock. The publish cascade withholds these
    /// crates; this guarantees none of them leaves the plan without a stated reason.
    #[serde(default)]
    pub held_explained: Vec<HeldExplanation>,
}

/// Gather + analyze: dirty trees, version skew, publish order, and the blast
/// radius of each dirty repo, for the given repos.
pub fn run(repos: &[(String, PathBuf)], policy: &DepPolicy) -> Result<DoctorReport> {
    let externals = repos
        .iter()
        .map(|(name, path)| gather_repo_externals(name, path))
        .collect::<Result<Vec<_>>>()?;
    let graphs = repos
        .iter()
        .map(|(name, path)| gather_repo_graph(name, path))
        .collect::<Result<Vec<_>>>()?;

    let dirty = check_dirty(repos);
    let blast = dirty
        .iter()
        .filter(|d| d.dirty)
        .map(|d| (d.repo.clone(), blast_radius(&graphs, &d.repo)))
        .collect();

    // Read each repo's lockfile so skew hints can tell a free bump from one a
    // transitive dependency pins (e.g. `iceberg 0.9` holding `arrow` at 57).
    let repo_locks: BTreeMap<String, String> = repos
        .iter()
        .filter_map(|(name, path)| {
            std::fs::read_to_string(path.join("Cargo.lock")).ok().map(|t| (name.clone(), t))
        })
        .collect();

    let mut skew = analyze_skew(&externals, policy);
    enrich_transitive_pins(&mut skew, &repo_locks);

    // Patch-fork promote gate (CRATE-precise): scan every repo for `[patch.crates-io]`
    // redirects to a path/git fork, classify each as a FOREIGN fork (patched dep not
    // produced anywhere → hard blocker) vs a safe own-crate override, and take the
    // PER-CRATE transitive block closure against the foreign forks. This blocks only
    // crates that genuinely (transitively) depend on the forked dep — so a workspace
    // member like `znippy-common` next to `znippy-iceberg` stays publishable.
    let block = compute_promote_block(
        repos.iter().map(|(n, p)| (n.clone(), p.as_path())),
    );
    let patch_forks = block.forks;
    let held_explained = block.explained;
    let promote_blocked: Vec<String> = block.blocked.into_iter().collect();

    // The publish order + cycles are computed at CRATE granularity (cargo publishes
    // crates, not repos), so a repo-level mutual dep that's a clean crate DAG doesn't
    // create a false cycle. `cycle_advice` (repo-level cut suggestions) is only
    // meaningful when a REAL crate-level cycle remains — otherwise the repo
    // entanglement resolves by publishing crates in interleaved order, no cut needed.
    let cycles = detect_cycles(&graphs);
    let cycle_advice = if cycles.is_empty() { Vec::new() } else { cycle_advice(&graphs) };

    Ok(DoctorReport {
        dirty,
        skew,
        topo: crate_publish_order(&graphs),
        blast,
        cycle_advice,
        repo_edges: repo_dep_edges(&graphs),
        patch_forks,
        promote_blocked,
        excluded_dev_edges: excluded_dev_edges(&graphs),
        optional_cross_deps: optional_cross_deps(&graphs),
        cfg_cross_deps: cfg_cross_deps(&graphs),
        cycles,
        version_pinned_cross_deps: version_pinned_cross_deps(&graphs),
        path_dep_version_gaps: scan_path_dep_version_gaps(repos),
        cycle_solutions: cycle_solutions(&graphs),
        waves: publish_waves(&graphs),
        semantic_blast: BTreeMap::new(),
        held_explained,
    })
}

/// [`run`] + the **semantic blast radius** (EPIC item 7): for each bumped repo in
/// `changed_by_repo` (repo → the symbols its version bump changed/removed), read the
/// warehouse SCIP call-graph of its dependents and attach the exact impacted call
/// sites to [`DoctorReport::semantic_blast`].
///
/// This is the warehouse-aware entry point; the plain [`run`] (no `wh`) leaves
/// `semantic_blast` empty. Only repos whose bump touches at least one dependent call
/// site are recorded (a bump that changes only internal symbols is not surfaced).
pub fn run_with_semantic_blast<'a>(
    repos: &[(String, PathBuf)],
    policy: &DepPolicy,
    wh: &crate::warehouse::iceberg::IcebergWarehouse,
    changed_by_repo: impl IntoIterator<
        Item = (&'a str, &'a [crate::release::semantic_blast::ChangedSymbol]),
    >,
) -> Result<DoctorReport> {
    let mut report = run(repos, policy)?;
    let graphs = repos
        .iter()
        .map(|(name, path)| gather_repo_graph(name, path))
        .collect::<Result<Vec<_>>>()?;
    report.semantic_blast =
        crate::release::semantic_blast::compute_for_dirty(wh, &graphs, changed_by_repo)?;
    Ok(report)
}

/// Audit of how the CLI release path populated (or skipped) the semantic blast, so
/// a skipped [`crate::release::gate::semantic_link_gate`] always states WHY. This is
/// the graceful-degrade transparency the release doctor needs: an empty blast can
/// mean "clean tree", "no persisted warehouse surface", or "a real bump with no
/// cross-crate call-site impact", and an operator must be able to tell which.
#[derive(Debug, Default, Clone)]
pub struct SemanticBlastAudit {
    /// The dirty repos whose exported surface was diffed against the warehouse.
    pub dirty_considered: Vec<String>,
    /// repo → number of changed/removed exported symbols the bump introduced.
    pub changed_symbols: BTreeMap<String, usize>,
    /// `true` when at least one repo produced a populated semantic blast (the gate
    /// is then live over real data); `false` = degraded to an empty blast.
    pub populated: bool,
    /// Human one-liner explaining the outcome — logged by the CLI before the gate.
    pub note: String,
}

/// **THE CLI RELEASE ENTRY POINT** — [`run`] with `semantic_blast` actually
/// POPULATED from the warehouse, so [`crate::release::gate::semantic_link_gate`] is
/// REACHABLE in production. The plain [`run`] hard-sets an empty map (the gate could
/// never fire — the inert-gate bug); this derives the real per-repo changed-symbol
/// set from the working tree and feeds [`run_with_semantic_blast`].
///
/// For every DIRTY repo (a working tree with a pending bump) it diffs the
/// last-persisted exported surface the warehouse holds (`symbol_facts`, via
/// [`crate::knowledge::query::load_latest`]) against a fresh, build-free syn scan of
/// the current tree ([`crate::knowledge::symbols::scan_repo`]) with
/// [`crate::release::semantic_blast::diff_exported_symbols`]. Removed/changed
/// exported symbols become the bump's API-surface delta, which
/// [`run_with_semantic_blast`] resolves against the dependents' call-graph.
///
/// GRACEFUL DEGRADE — never panics, never hard-fails on missing data:
///   * no dirty repo → nothing to diff → plain [`run`] (empty blast, gate skips),
///   * a dirty repo with NO persisted warehouse surface → empty OLD side → no
///     removals derivable → it contributes nothing (the runtime SCIP/symbol data
///     dependency; a clean checkout with an unseeded warehouse lands here),
///   * a dirty repo whose surface is unchanged → empty delta → contributes nothing.
///
/// If NO repo yields a delta the result is byte-identical to the plain [`run`]
/// (empty `semantic_blast`), and the returned [`SemanticBlastAudit`] states which
/// degrade path was taken. Opening the warehouse is the CALLER's job (it owns the
/// read-only-vs-locked policy); this never opens it, so a warehouse that won't open
/// is the caller's fall-back to plain [`run`].
pub fn run_with_warehouse_semantic_blast(
    repos: &[(String, PathBuf)],
    policy: &DepPolicy,
    wh: &crate::warehouse::iceberg::IcebergWarehouse,
) -> Result<(DoctorReport, SemanticBlastAudit)> {
    use crate::release::semantic_blast::{diff_exported_symbols, ChangedSymbol};

    let mut audit = SemanticBlastAudit::default();
    let dirty: Vec<String> = check_dirty(repos)
        .into_iter()
        .filter(|d| d.dirty)
        .map(|d| d.repo)
        .collect();
    audit.dirty_considered = dirty.clone();

    if dirty.is_empty() {
        audit.note =
            "no dirty repos → no pending bump to diff; semantic blast empty (link gate skipped)"
                .to_string();
        return Ok((run(repos, policy)?, audit));
    }

    // Per DIRTY repo: OLD exported surface (warehouse) vs NEW (fresh syn scan) →
    // the bump's changed/removed symbol delta.
    let mut changed_by_repo: Vec<(String, Vec<ChangedSymbol>)> = Vec::new();
    for (name, path) in repos {
        if !dirty.iter().any(|d| d == name) {
            continue;
        }
        // OLD: the last snapshot's symbols the warehouse persisted for this repo.
        // A read failure / no rows ⇒ no OLD surface to diff (degrade, not fatal).
        let old = match crate::knowledge::query::load_latest(wh, name) {
            Ok(view) => view.symbols,
            Err(_) => Vec::new(),
        };
        if old.is_empty() {
            continue;
        }
        // NEW: a fresh, build-free syn scan of the current working tree.
        let new = match crate::knowledge::symbols::scan_repo(
            path,
            name,
            uuid::Uuid::new_v4(),
            chrono::Utc::now(),
        ) {
            Ok(scan) => scan.symbols,
            Err(_) => continue,
        };
        let delta = diff_exported_symbols(&old, &new);
        if !delta.is_empty() {
            audit.changed_symbols.insert(name.clone(), delta.len());
            changed_by_repo.push((name.clone(), delta));
        }
    }

    if changed_by_repo.is_empty() {
        audit.note = format!(
            "{} dirty repo(s), but no exported-surface delta \
             (unchanged API or no persisted warehouse surface) → semantic blast empty (link gate skipped)",
            dirty.len()
        );
        return Ok((run(repos, policy)?, audit));
    }

    let refs: Vec<(&str, &[ChangedSymbol])> = changed_by_repo
        .iter()
        .map(|(r, cs)| (r.as_str(), cs.as_slice()))
        .collect();
    let report = run_with_semantic_blast(repos, policy, wh, refs)?;
    audit.populated = !report.semantic_blast.is_empty();
    audit.note = format!(
        "semantic blast: diffed {} dirty repo(s), {} with a surface delta; \
         {} carry a populated cross-crate blast (link gate LIVE)",
        dirty.len(),
        changed_by_repo.len(),
        report.semantic_blast.len(),
    );
    Ok((report, audit))
}

/// Human-readable advisory report (the CLI-parity table). All hints, no mutation.
pub fn format_report(report: &DoctorReport) -> String {
    let mut s = String::new();
    s.push_str("nornir release doctor — advisory\n\n");

    s.push_str("Working trees:\n");
    let dirty: Vec<_> = report.dirty.iter().filter(|d| d.dirty).collect();
    if dirty.is_empty() {
        s.push_str("  ✅ all clean\n");
    } else {
        for d in &dirty {
            s.push_str(&format!("  🟡 {} — uncommitted changes\n", d.repo));
        }
    }
    for d in report.dirty.iter().filter(|d| d.error.is_some()) {
        s.push_str(&format!("  ⚠ {} — {}\n", d.repo, d.error.as_deref().unwrap_or("")));
    }

    // Publish pre-flight: the exact `cargo publish` manifest blocker, found up front.
    s.push_str("\nPublish preflight — path deps need a version:\n");
    if report.path_dep_version_gaps.is_empty() {
        s.push_str("  ✅ every path dep of a publishable crate carries a version\n");
    } else {
        let fixable: Vec<_> =
            report.path_dep_version_gaps.iter().filter(|g| g.dep_owner.is_some()).collect();
        let decide: Vec<_> =
            report.path_dep_version_gaps.iter().filter(|g| g.dep_owner.is_none()).collect();
        if !fixable.is_empty() {
            s.push_str("  auto-fixable (member-owned — add version=):\n");
            for g in &fixable {
                let ver = g
                    .suggested_version
                    .as_deref()
                    .map(|v| format!("version = \"{v}\""))
                    .unwrap_or_else(|| "version = \"<its version>\"".to_string());
                let ws = if g.via_workspace { " [via workspace.dependencies]" } else { "" };
                s.push_str(&format!(
                    "    🔧 {}/{}: {} → {}  💡 {}{}\n",
                    g.repo, g.manifest, g.crate_name, g.dep, ver, ws
                ));
            }
        }
        if !decide.is_empty() {
            s.push_str(
                "  ⛔ needs decision (NON-member dep — join the release cascade or publish it first):\n",
            );
            for g in &decide {
                s.push_str(&format!(
                    "    ⛔ {}/{}: {} → {}  (not a release member)\n",
                    g.repo, g.manifest, g.crate_name, g.dep
                ));
            }
        }
    }

    s.push_str("\nExternal dependency skew:\n");
    if report.skew.is_empty() {
        s.push_str("  ✅ no divergence\n");
    } else {
        for c in &report.skew {
            let forbidden = c.entries.iter().any(|e| e.status == SkewStatus::Forbidden);
            s.push_str(&format!("  {} (target {})", c.crate_name, c.target));
            if forbidden {
                s.push_str("  ⚠ FORBIDDEN version present");
            }
            s.push('\n');
            for e in &c.entries {
                let mark = match e.status {
                    SkewStatus::Ok => "✓",
                    // Advisory, NOT a hard blocker: a transitive pin already resolves the
                    // target version, so `--publish` proceeds. `ℹ` distinguishes it from a
                    // real ⛔ promote-gate blocker (release-improvements #4).
                    SkewStatus::Behind if e.held_by_transitive_pin => "ℹ",
                    SkewStatus::Behind => "·",
                    SkewStatus::Forbidden => "⚠",
                };
                let note = if e.held_by_transitive_pin {
                    format!("  (held: lock already resolves {}, a transitive dep pins {})", c.target, e.version)
                } else {
                    String::new()
                };
                s.push_str(&format!("      {} {} {}{}\n", mark, e.repo, e.version, note));
            }
            // Split the bump hint: repos that can bump freely vs ones a transitive
            // pin holds back (where a manifest bump alone won't take).
            let held: Vec<&str> = c
                .entries
                .iter()
                .filter(|e| e.status == SkewStatus::Behind && e.held_by_transitive_pin)
                .map(|e| e.repo.as_str())
                .collect();
            let free: Vec<&str> = c
                .entries
                .iter()
                .filter(|e| e.status != SkewStatus::Ok && !e.held_by_transitive_pin)
                .map(|e| e.repo.as_str())
                .collect();
            if !free.is_empty() {
                s.push_str(&format!("    💡 bump → {}: {}\n", c.target, free.join(", ")));
            }
            if !held.is_empty() {
                s.push_str(&format!(
                    "    ⛔ blocked → {}: a transitive dep pins {} (run `cargo tree -i {}` to find it)\n",
                    held.join(", "),
                    c.crate_name,
                    c.crate_name,
                ));
            }
        }
    }

    s.push_str("\nPublish order (dependencies first):\n");
    if report.topo.order.is_empty() {
        s.push_str("  (no repos)\n");
    } else {
        s.push_str(&format!("  {}\n", report.topo.order.join(" → ")));
    }
    if !report.topo.cycle.is_empty() {
        s.push_str(&format!("  ⚠ dependency cycle, unordered: {}\n", report.topo.cycle.join(", ")));
    }

    // Publish waves: each antichain = crates publishable CONCURRENTLY (deps-first).
    if !report.waves.is_empty() {
        s.push_str("\nPublish waves (each wave = crates publishable concurrently):\n");
        for (i, wave) in report.waves.iter().enumerate() {
            s.push_str(&format!("  wave {}: {}\n", i, wave.join(", ")));
        }
    }

    if !report.cycle_advice.is_empty() {
        s.push_str("\nBreak the cycle (suggested cuts):\n");
        for a in &report.cycle_advice {
            s.push_str(&format!("  ⟲ {} — 💡 {}\n", a.members.join(" ⇄ "), a.rationale));
        }
    }

    // MFAS: the RANKED, proven solution list per real crate cycle (cheapest-first).
    if !report.cycle_solutions.is_empty() {
        s.push_str("\nMFAS — ranked cycle solutions (proven to yield a DAG):\n");
        for cs in &report.cycle_solutions {
            s.push_str(&format!("  ⛓ {}\n", cs.members.join(" ⇄ ")));
            if cs.solutions.is_empty() {
                s.push_str("      (no single-arc cut found)\n");
                continue;
            }
            for (rank, sol) in cs.solutions.iter().take(4).enumerate() {
                let edges = sol
                    .edges
                    .iter()
                    .map(|(f, t)| format!("{f}→{t}"))
                    .collect::<Vec<_>>()
                    .join(" + ");
                s.push_str(&format!(
                    "      #{}. cost {} — cut {}  ✓ residual DAG: {}\n",
                    rank + 1,
                    sol.cost,
                    edges,
                    sol.proof_order.join(" → ")
                ));
                for act in &sol.actions {
                    s.push_str(&format!("          💡 {act}\n"));
                }
            }
        }
    }

    // Cycles: empty = good. Otherwise the offending edges, made explicit (never
    // silently broken). Detected at CRATE granularity — a repo-level mutual dep that
    // publishes fine as an interleaved crate DAG is NOT reported as a cycle.
    s.push_str("\nCycles (crate-level publish graph):\n");
    if report.cycles.is_empty() {
        s.push_str("  ✅ none\n");
    } else {
        for c in &report.cycles {
            s.push_str(&format!("  ⛔ {}\n", c.members.join(" ⇄ ")));
            for e in &c.edges {
                let via = if e.via.is_empty() { String::new() } else { format!(" (via {})", e.via.join(", ")) };
                s.push_str(&format!("      {} → {}{}\n", e.from, e.to, via));
            }
        }
    }

    // Excluded dev-dep cross-repo edges — transparency for what is NOT order-gating.
    if !report.excluded_dev_edges.is_empty() {
        s.push_str("\nExcluded dev-dep cross-repo edges (not order-gating):\n");
        for e in &report.excluded_dev_edges {
            let via = if e.via.is_empty() { String::new() } else { format!(" [{}]", e.via.join(", ")) };
            s.push_str(&format!("  {} --dev--> {}{}\n", e.from, e.to, via));
        }
    }

    // Feature-gated / optional cross-repo deps (kept in order, surfaced).
    if !report.optional_cross_deps.is_empty() {
        s.push_str("\nFeature-gated / optional cross-repo deps:\n");
        for d in &report.optional_cross_deps {
            let feats = if d.features.is_empty() {
                "optional".to_string()
            } else {
                format!("optional, feature={}", d.features.join("|"))
            };
            s.push_str(&format!("  {} --[{}]--> {} ({})\n", d.from, feats, d.krate, d.to));
        }
    }

    // target-cfg cross-repo deps.
    if !report.cfg_cross_deps.is_empty() {
        s.push_str("\nTarget-cfg cross-repo deps:\n");
        for d in &report.cfg_cross_deps {
            s.push_str(&format!("  {} --[{}]--> {} ({})\n", d.from, d.cfgs.join(" | "), d.krate, d.to));
        }
    }

    // crates.io-pinned cross-repo deps — the path-vs-version split (point #8).
    if !report.version_pinned_cross_deps.is_empty() {
        s.push_str("\nCrates.io version-pinned cross-repo deps (not order-gating):\n");
        for e in &report.version_pinned_cross_deps {
            s.push_str(&format!("  {} --version--> {} [{}]\n", e.from, e.to, e.via.join(", ")));
        }
    }

    if !report.patch_forks.is_empty() {
        s.push_str("\nPatch-fork promote gate:\n");
        let kind_of = |b: &PatchForkBlock| match b.fork_kind {
            ForkKind::Path => "path",
            ForkKind::Git => "git",
        };
        // A fork whose patched dep we don't (re)publish ourselves is a HARD blocker:
        // either a third-party crate we forked (iceberg) or one of our own crates that
        // itself rides the fork (skade) — both leave stock resolution incompatible.
        let foreign: Vec<&PatchForkBlock> =
            report.patch_forks.iter().filter(|b| b.is_foreign_fork).collect();
        for b in &foreign {
            s.push_str(&format!(
                "  ⛔ promote-blocked: {} rides a patch-fork ({} → {} [{}]); \
                 publishing strips it → stock {} would be incompatible. \
                 Unblock: publish {}'s real version, or wait for upstream.\n",
                b.crate_name, b.patched_dep, b.source, kind_of(b), b.patched_dep, b.patched_dep,
            ));
        }
        // Own-crate path/git overrides are SAFE — publish-order covers them.
        let overrides: Vec<&PatchForkBlock> =
            report.patch_forks.iter().filter(|b| !b.is_foreign_fork).collect();
        for b in &overrides {
            s.push_str(&format!(
                "  ℹ️  local dev override (safe): {} → {} [{}] — our own crate; \
                 stripped on publish, publish-order resolves it.\n",
                b.patched_dep, b.source, kind_of(b),
            ));
        }
        // The full transitive crate set the foreign forks hold from crates.io.
        if !report.promote_blocked.is_empty() {
            s.push_str(&format!(
                "  ⛔ held from crates.io ({} crate(s) that transitively need a forked dep): {}\n",
                report.promote_blocked.len(),
                report.promote_blocked.join(", "),
            ));
            s.push_str("     ↳ run `release doctor --explain` for the per-crate reason + unblock advice\n");
        }
        // Only safe overrides, nothing genuinely held → say so explicitly.
        if foreign.is_empty() && report.promote_blocked.is_empty() {
            s.push_str("  ✅ no foreign forks — all crates promotable\n");
        }
    }

    let blast: Vec<_> = report.blast.iter().filter(|(_, d)| !d.is_empty()).collect();
    if !blast.is_empty() {
        s.push_str("\nBlast radius of dirty repos (re-validate on change):\n");
        for (repo, deps) in blast {
            s.push_str(&format!("  {} → {}\n", repo, deps.join(", ")));
        }
    }

    // SEMANTIC blast (EPIC item 7): the exact call sites, not just "who depends on".
    if !report.semantic_blast.is_empty() {
        s.push_str("\nSemantic blast radius (exact call sites touching the changed API):\n");
        for sb in report.semantic_blast.values() {
            s.push_str(&crate::release::semantic_blast::format_semantic_blast(sb));
        }
        // LINK ERRORS: a removed symbol a dependent still calls fails the release like
        // a linker. Surface the headline; the gate (`semantic_link_gate`) enforces it.
        let link_errs: usize = report
            .semantic_blast
            .values()
            .map(|sb| sb.link_errors().len())
            .sum();
        if link_errs > 0 {
            let sites: usize = report
                .semantic_blast
                .values()
                .map(|sb| sb.link_error_sites())
                .sum();
            s.push_str(&format!(
                "  ⛔ {link_errs} LINK ERROR(s): {sites} call site(s) invoke a REMOVED symbol — \
                 release BLOCKED (a linker would fail the same way)\n"
            ));
        }
    }
    s
}

/// Render the EXPLAINED HELD SET (`release doctor --explain`) — one block per crate
/// the publish cascade withholds, stating the foreign fork it rides (`fork_kind` +
/// `patched_dep` + source), whether the dependency is direct, and the unblock advice.
/// Empty held set → an explicit "nothing held" line (so `--explain` always answers).
pub fn format_held_explanations(report: &DoctorReport) -> String {
    let mut s = String::new();
    s.push_str("\nHeld set — every crate withheld from the crates.io plan, with its reason:\n");
    if report.held_explained.is_empty() {
        s.push_str("  ✅ nothing held — every crate is promotable\n");
        return s;
    }
    for h in &report.held_explained {
        let rides = h
            .rides
            .iter()
            .map(|f| {
                let kind = match f.fork_kind {
                    ForkKind::Path => "path",
                    ForkKind::Git => "git",
                };
                if f.source.is_empty() {
                    format!("{} [{}]", f.patched_dep, kind)
                } else {
                    format!("{} → {} [{}]", f.patched_dep, f.source, kind)
                }
            })
            .collect::<Vec<_>>()
            .join(", ");
        let how = if h.direct { "directly rides" } else { "transitively rides" };
        s.push_str(&format!("  ⛔ held: {} — {} fork {}\n", h.crate_name, how, rides));
        s.push_str(&format!("        ↳ {}\n", h.advice));
    }
    s
}
#[cfg(test)]
mod tests {
    use super::*;

    fn repo(name: &str, deps: &[(&str, &str)]) -> RepoExternals {
        RepoExternals {
            repo: name.to_string(),
            deps: deps.iter().map(|(c, v)| (c.to_string(), v.to_string())).collect(),
        }
    }

    /// ACCEPTANCE: reproduce the 2026-06-19 arrow-58 hand analysis automatically —
    /// znippy on 58 (target), skade/nornir/knut on 57 (behind), facett/korp on 56
    /// (behind + FORBIDDEN), and the bump set = everyone but znippy.
    #[test]
    fn arrow58_case_matches_hand_analysis() {
        let repos = [
            repo("znippy", &[("arrow", "58.3.0"), ("serde", "1")]),
            repo("skade", &[("arrow", "57.1"), ("serde", "1")]),
            repo("nornir", &[("arrow", "57"), ("serde", "1")]),
            repo("knut", &[("arrow", "57"), ("serde", "1")]),
            repo("facett", &[("arrow", "56"), ("serde", "1")]),
            repo("korp", &[("arrow", "56"), ("serde", "1")]),
        ];
        let policy = DepPolicy {
            forbidden: vec![ForbiddenDep { crate_name: "arrow".into(), version: "56".into() }],
        };

        let skew = analyze_skew(&repos, &policy);

        // serde is identical everywhere → not surfaced. Only arrow skews.
        assert_eq!(skew.len(), 1, "only arrow should be flagged");
        let arrow = &skew[0];
        assert_eq!(arrow.crate_name, "arrow");
        assert_eq!(arrow.target, "58.3.0", "target = highest declared (znippy)");
        assert!(arrow.diverged);

        let status = |r: &str| {
            arrow.entries.iter().find(|e| e.repo == r).map(|e| e.status.clone()).unwrap()
        };
        assert_eq!(status("znippy"), SkewStatus::Ok);
        assert_eq!(status("skade"), SkewStatus::Behind);
        assert_eq!(status("nornir"), SkewStatus::Behind);
        assert_eq!(status("knut"), SkewStatus::Behind);
        assert_eq!(status("facett"), SkewStatus::Forbidden);
        assert_eq!(status("korp"), SkewStatus::Forbidden);

        let mut bump = arrow.bump_repos();
        bump.sort();
        assert_eq!(bump, vec!["facett", "knut", "korp", "nornir", "skade"]);
    }

    /// Bug #19: a `0.x` forbid must ban only that minor line, not every `0.x`.
    #[test]
    fn forbidden_zero_x_compares_on_minor() {
        let policy = DepPolicy {
            forbidden: vec![ForbiddenDep { crate_name: "tokio".into(), version: "0.9".into() }],
        };
        // 0.9.x is forbidden…
        assert!(is_forbidden("tokio", "0.9.3", &policy));
        // …but a DIFFERENT 0.x minor (0.10) is NOT.
        assert!(!is_forbidden("tokio", "0.10.1", &policy));
        // A >=1.0 forbid still bans on major alone.
        let p1 = DepPolicy {
            forbidden: vec![ForbiddenDep { crate_name: "arrow".into(), version: "56".into() }],
        };
        assert!(is_forbidden("arrow", "56.2.1", &p1));
        assert!(!is_forbidden("arrow", "57.0.0", &p1));
    }

    #[test]
    fn no_skew_when_all_agree() {
        let repos = [repo("a", &[("arrow", "58")]), repo("b", &[("arrow", "58")])];
        assert!(analyze_skew(&repos, &DepPolicy::default()).is_empty());
    }

    #[test]
    fn forbidden_surfaces_even_without_divergence() {
        // Both on 56 (no divergence) but 56 is forbidden → still flagged.
        let repos = [repo("a", &[("arrow", "56")]), repo("b", &[("arrow", "56")])];
        let policy = DepPolicy {
            forbidden: vec![ForbiddenDep { crate_name: "arrow".into(), version: "56".into() }],
        };
        let skew = analyze_skew(&repos, &policy);
        assert_eq!(skew.len(), 1);
        assert!(skew[0].entries.iter().all(|e| e.status == SkewStatus::Forbidden));
    }

    #[test]
    fn crate_majors_in_lock_collects_all_majors() {
        let lock = r#"
[[package]]
name = "arrow"
version = "57.3.1"

[[package]]
name = "arrow"
version = "58.3.0"

[[package]]
name = "serde"
version = "1.0.2"
"#;
        assert_eq!(crate_majors_in_lock(lock, "arrow"), [57u64, 58].into_iter().collect());
        assert_eq!(crate_majors_in_lock(lock, "serde"), [1u64].into_iter().collect());
        assert!(crate_majors_in_lock(lock, "absent").is_empty());
    }

    /// The real nornir/arrow case: nornir declares arrow 57 (behind znippy's 58.3.0)
    /// but its lock resolves BOTH 57 and 58 (58 pulled transitively via znippy), so a
    /// manifest bump alone can't take — `iceberg 0.9` pins 57. Mark it held.
    #[test]
    fn transitive_pin_marks_dual_major_behind_repo() {
        let repos = [
            repo("znippy", &[("arrow", "58.3.0")]),
            repo("nornir", &[("arrow", "57")]),
        ];
        let mut skew = analyze_skew(&repos, &DepPolicy::default());
        let nornir_lock = r#"
[[package]]
name = "arrow"
version = "57.3.1"

[[package]]
name = "arrow"
version = "58.3.0"
"#;
        // znippy's lock has only 58 → its Ok entry is untouched anyway.
        let locks: BTreeMap<String, String> =
            [("nornir".to_string(), nornir_lock.to_string())].into_iter().collect();
        enrich_transitive_pins(&mut skew, &locks);

        let arrow = skew.iter().find(|c| c.crate_name == "arrow").unwrap();
        let nornir = arrow.entries.iter().find(|e| e.repo == "nornir").unwrap();
        assert_eq!(nornir.status, SkewStatus::Behind);
        assert!(nornir.held_by_transitive_pin, "dual-major lock ⇒ held by transitive pin");

        // A behind repo whose lock does NOT yet pull the target is a free bump.
        let mut skew2 = analyze_skew(&repos, &DepPolicy::default());
        let only_57 = "[[package]]\nname = \"arrow\"\nversion = \"57.3.1\"\n";
        let locks2: BTreeMap<String, String> =
            [("nornir".to_string(), only_57.to_string())].into_iter().collect();
        enrich_transitive_pins(&mut skew2, &locks2);
        let nornir2 = skew2[0].entries.iter().find(|e| e.repo == "nornir").unwrap();
        assert!(!nornir2.held_by_transitive_pin, "single-major lock ⇒ free bump");
    }

    #[test]
    fn version_key_tolerates_partials_and_operators() {
        assert_eq!(version_key("58.3.0"), (58, 3, 0));
        assert_eq!(version_key("57"), (57, 0, 0));
        assert_eq!(version_key("^1.2"), (1, 2, 0));
        assert_eq!(version_key(">=0.9.0"), (0, 9, 0));
        assert_eq!(version_key("=56.2.1"), (56, 2, 1));
    }

    #[test]
    fn gatherer_reads_external_versions_and_skips_path_deps() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join("Cargo.toml"),
            r#"
[package]
name = "demo"
[dependencies]
arrow = "58.3.0"
serde = { version = "1.0", features = ["derive"] }
znippy-common = { version = "0.9.4", path = "../znippy-common" }
gitdep = { git = "https://example.com/x" }
"#,
        )
        .unwrap();

        let ext = gather_repo_externals("demo", dir.path()).unwrap();
        assert_eq!(ext.deps.get("arrow").map(String::as_str), Some("58.3.0"));
        assert_eq!(ext.deps.get("serde").map(String::as_str), Some("1.0"));
        assert!(!ext.deps.contains_key("znippy-common"), "path dep is workspace-internal");
        assert!(!ext.deps.contains_key("gitdep"), "git dep has no version");
    }

    #[test]
    fn scan_and_fix_versioned_path_dev_deps_strips_version_keeps_path() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        // A crate with TWO versioned path dev-deps (one inline, one target-cfg) plus
        // a legit path-only dev-dep (must be left alone) and a normal versioned dep.
        std::fs::write(
            root.join("Cargo.toml"),
            r#"[package]
name = "consumer"
version = "0.5.0"

[dependencies]
serde = { version = "1", path = "../serde-fork" }

[dev-dependencies]
sibling-a = { path = "../sibling-a", version = "0.1" }
sibling-ok = { path = "../sibling-ok" }

[target.'cfg(unix)'.dev-dependencies]
sibling-b = { version = "0.2.1", path = "../sibling-b" }
"#,
        )
        .unwrap();

        let repos = vec![("consumer".to_string(), root.to_path_buf())];
        let mut gaps = scan_versioned_path_dev_deps(&repos);
        gaps.sort_by(|a, b| a.dep.cmp(&b.dep));
        let deps: Vec<&str> = gaps.iter().map(|g| g.dep.as_str()).collect();
        assert_eq!(deps, vec!["sibling-a", "sibling-b"], "only path+version DEV-deps");

        let out = fix_versioned_path_dev_deps(&gaps, &repos).unwrap();
        assert_eq!(out.fixed, 2);
        let after = std::fs::read_to_string(root.join("Cargo.toml")).unwrap();
        // Reparse (formatting-tolerant): the two dev-deps lost their version but
        // kept their path; the path-only dev-dep and the normal dep are untouched.
        let doc: toml::Value = after.parse().unwrap();
        let dev = |v: &toml::Value, table: &str, name: &str| -> toml::Value {
            v.get(table).and_then(|t| t.get(name)).cloned().unwrap()
        };
        let a = dev(&doc, "dev-dependencies", "sibling-a");
        assert!(a.get("version").is_none(), "sibling-a version dropped");
        assert_eq!(a.get("path").and_then(|p| p.as_str()), Some("../sibling-a"));
        let b = doc["target"]["cfg(unix)"]["dev-dependencies"]["sibling-b"].clone();
        assert!(b.get("version").is_none(), "sibling-b version dropped");
        assert_eq!(b.get("path").and_then(|p| p.as_str()), Some("../sibling-b"));
        // Untouched: the path-only dev-dep, and the NORMAL versioned path dep.
        let ok = dev(&doc, "dev-dependencies", "sibling-ok");
        assert_eq!(ok.get("path").and_then(|p| p.as_str()), Some("../sibling-ok"));
        let serde = dev(&doc, "dependencies", "serde");
        assert_eq!(serde.get("version").and_then(|v| v.as_str()), Some("1"), "normal dep kept");

        // Idempotent: a second scan finds nothing.
        assert!(scan_versioned_path_dev_deps(&repos).is_empty(), "healed → nothing left");
    }

    /// Build a workspace member manifest under `root/<name>/Cargo.toml`.
    fn member(root: &Path, name: &str, deps: &[&str]) {
        let dir = root.join(name);
        std::fs::create_dir_all(&dir).unwrap();
        let mut t = format!("[package]\nname = \"{name}\"\nversion = \"0.1.0\"\n[dependencies]\n");
        for d in deps {
            t.push_str(&format!("{d} = \"1\"\n"));
        }
        std::fs::write(dir.join("Cargo.toml"), t).unwrap();
    }

    #[test]
    fn precise_gate_blocks_only_crates_that_reach_the_foreign_fork() {
        // crate_deps: a workspace where only some crates touch the forked `iceberg`.
        //   skade        → iceberg (FOREIGN fork)         ⇒ blocked
        //   znippy-iceberg → iceberg                       ⇒ blocked
        //   nornir       → skade                           ⇒ blocked (transitive)
        //   znippy-common → (nothing forky)                ⇒ FREE
        //   lgz          → (nothing forky)                 ⇒ FREE
        let mut cd: BTreeMap<String, std::collections::BTreeSet<String>> = BTreeMap::new();
        let set = |xs: &[&str]| xs.iter().map(|s| s.to_string()).collect();
        cd.insert("skade".into(), set(&["iceberg", "serde"]));
        cd.insert("znippy-iceberg".into(), set(&["iceberg"]));
        cd.insert("nornir".into(), set(&["skade", "clap"]));
        cd.insert("znippy-common".into(), set(&["serde"]));
        cd.insert("lgz".into(), set(&["znippy-common"]));

        let foreign: std::collections::BTreeSet<String> =
            ["iceberg".to_string()].into_iter().collect();
        let blocked = promote_blocked_crates_precise(&cd, &foreign);

        assert!(blocked.contains("skade"), "skade rides the fork");
        assert!(blocked.contains("znippy-iceberg"), "znippy-iceberg rides the fork");
        assert!(blocked.contains("nornir"), "nornir → skade → iceberg (transitive)");
        assert!(!blocked.contains("znippy-common"), "znippy-common never touches iceberg → FREE");
        assert!(!blocked.contains("lgz"), "lgz → znippy-common only → FREE");
    }

    #[test]
    fn compute_promote_block_classifies_foreign_vs_own_overrides() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();

        // A workspace ("nordic") whose ROOT patches both a FOREIGN crate (iceberg → a
        // local fork) and an OWN sibling (skade → ../skade, a dev override). Members:
        // skade (uses iceberg), znippy-common (clean), znippy-iceberg (uses iceberg).
        let ws = root.join("nordic");
        std::fs::create_dir_all(&ws).unwrap();
        std::fs::write(
            ws.join("Cargo.toml"),
            r#"
[workspace]
members = ["skade", "znippy-common", "znippy-iceberg"]
[patch.crates-io]
iceberg = { path = "../iceberg-arrow58" }
skade = { path = "../skade" }
"#,
        )
        .unwrap();
        member(&ws, "skade", &["iceberg"]);
        member(&ws, "znippy-common", &["serde"]);
        member(&ws, "znippy-iceberg", &["iceberg", "znippy-common"]);

        let repos = vec![("nordic".to_string(), ws.clone())];
        let block = compute_promote_block(repos.iter().map(|(n, p)| (n.clone(), p.as_path())));

        // iceberg is foreign (not produced here); skade is OUR crate → safe override.
        assert!(block.foreign_forks.contains("iceberg"), "iceberg is a foreign fork");
        assert!(!block.foreign_forks.contains("skade"), "skade is our own crate, not foreign");
        let iceberg_block = block.forks.iter().find(|b| b.patched_dep == "iceberg").unwrap();
        assert!(iceberg_block.is_foreign_fork);
        let skade_block = block.forks.iter().find(|b| b.patched_dep == "skade").unwrap();
        assert!(!skade_block.is_foreign_fork, "skade override is safe, not a blocker");

        // The block holds only iceberg-touchers; znippy-common stays publishable.
        assert!(block.blocked.contains("skade"));
        assert!(block.blocked.contains("znippy-iceberg"));
        assert!(!block.blocked.contains("znippy-common"), "clean sibling is FREE");
    }

    /// `--explain`: EVERY held crate carries a stated reason (nothing leaves the plan
    /// silently). The explained set equals the blocked set; each reason names the
    /// foreign fork it rides, distinguishes direct vs transitive, and gives advice.
    #[test]
    fn held_explanations_cover_every_blocked_crate_with_a_reason() {
        let mut cd: BTreeMap<String, std::collections::BTreeSet<String>> = BTreeMap::new();
        let set = |xs: &[&str]| xs.iter().map(|s| s.to_string()).collect();
        cd.insert("skade".into(), set(&["iceberg", "serde"])); // direct
        cd.insert("znippy-iceberg".into(), set(&["iceberg"])); // direct
        cd.insert("nornir".into(), set(&["skade", "clap"])); // transitive (via skade)
        cd.insert("znippy-common".into(), set(&["serde"])); // free
        let foreign: std::collections::BTreeSet<String> =
            ["iceberg".to_string()].into_iter().collect();
        let forks = vec![PatchForkBlock {
            crate_name: "nordic".into(),
            patched_dep: "iceberg".into(),
            fork_kind: ForkKind::Path,
            source: "../iceberg-arrow58".into(),
            reason: String::new(),
            is_foreign_fork: true,
        }];

        let explained = held_fork_reasons(&cd, &forks, &foreign);
        let blocked = promote_blocked_crates_precise(&cd, &foreign);

        // 1. Explained set == blocked set — nothing held is left unexplained.
        let explained_names: std::collections::BTreeSet<String> =
            explained.iter().map(|h| h.crate_name.clone()).collect();
        let sets_match = explained_names == blocked;
        // 2. Every reason names the fork + carries advice.
        let all_have_reason = explained.iter().all(|h| {
            !h.rides.is_empty()
                && h.rides.iter().any(|r| r.patched_dep == "iceberg")
                && !h.advice.is_empty()
        });
        // 3. direct/transitive classification is right.
        let by = |n: &str| explained.iter().find(|h| h.crate_name == n).unwrap();
        let direct_ok = by("skade").direct
            && by("znippy-iceberg").direct
            && !by("nornir").direct;
        let source_surfaced = by("skade").rides.iter().any(|r| r.source == "../iceberg-arrow58");

        nornir_testmatrix::functional_status(
            "release-doctor",
            "held_explain_covers_every_crate",
            sets_match && all_have_reason && direct_ok && source_surfaced,
            &format!(
                "explained={:?} blocked={:?}",
                explained_names,
                blocked,
            ),
        );
        assert!(sets_match, "every blocked crate has an explanation: {explained_names:?} vs {blocked:?}");
        assert!(all_have_reason, "each held crate names its fork + advice");
        assert!(direct_ok, "skade/znippy-iceberg are direct, nornir is transitive");
        assert!(source_surfaced, "the fork source string is surfaced in the reason");
        assert!(!explained.iter().any(|h| h.crate_name == "znippy-common"), "free crate is not held");
    }

    /// The full `compute_promote_block` populates `explained` end-to-end, and
    /// `format_held_explanations` renders a `⛔ held` line + advice for each.
    #[test]
    fn compute_promote_block_populates_and_formats_held_explanations() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let ws = root.join("nordic");
        std::fs::create_dir_all(&ws).unwrap();
        std::fs::write(
            ws.join("Cargo.toml"),
            "\n[workspace]\nmembers = [\"skade\", \"znippy-common\"]\n[patch.crates-io]\niceberg = { path = \"../iceberg-arrow58\" }\n",
        )
        .unwrap();
        member(&ws, "skade", &["iceberg"]);
        member(&ws, "znippy-common", &["serde"]);

        let repos = vec![("nordic".to_string(), ws.clone())];
        let block = compute_promote_block(repos.iter().map(|(n, p)| (n.clone(), p.as_path())));
        assert!(block.explained.iter().any(|h| h.crate_name == "skade"), "skade explained");

        let mut report = DoctorReport::default();
        report.promote_blocked = block.blocked.iter().cloned().collect();
        report.held_explained = block.explained.clone();
        let text = format_held_explanations(&report);
        assert!(text.contains("⛔ held: skade"), "renders a held line for skade: {text}");
        assert!(text.contains("iceberg"), "names the forked dep: {text}");
        assert!(text.contains("Unblock"), "gives unblock advice: {text}");

        // Empty held set → an explicit 'nothing held' line.
        let empty = format_held_explanations(&DoctorReport::default());
        assert!(empty.contains("nothing held"), "empty set answers explicitly: {empty}");
    }

    fn graph(repo: &str, produces: &[&str], deps: &[&str]) -> RepoGraph {
        RepoGraph {
            repo: repo.to_string(),
            produces: produces.iter().map(|s| s.to_string()).collect(),
            deps: deps.iter().map(|s| s.to_string()).collect(),
            ..Default::default()
        }
    }

    /// Publish order is dependencies-first, computed from who-produces-what:
    /// nornir depends on znippy-common + skade-katalog, so znippy & skade precede it.
    #[test]
    fn publish_order_is_dependencies_first() {
        let graphs = [
            graph("znippy", &["znippy-common", "lgz"], &["serde"]),
            graph("skade", &["skade-katalog"], &["arrow"]),
            graph("nornir", &["nornir"], &["znippy-common", "skade-katalog", "serde"]),
        ];
        let topo = publish_order(&graphs);
        assert!(topo.cycle.is_empty(), "clean DAG");
        let pos = |r: &str| topo.order.iter().position(|x| x == r).unwrap();
        assert!(pos("znippy") < pos("nornir"), "znippy before nornir");
        assert!(pos("skade") < pos("nornir"), "skade before nornir");
        assert_eq!(topo.order.len(), 3);
    }

    /// The `tunnr-vm` incident, modelled exactly: an ALREADY-PUBLISHED crate
    /// (`nornir-testmatrix`) reached only by a straggler `path=` dep forges a FALSE
    /// repo cycle `draupnir → tunnr → edda → draupnir`. The naive order collapses
    /// the SCC and expands it ALPHABETICALLY (draupnir before tunnr) — the bug that
    /// published draupnir before `tunnr-vm` existed. Treating `nornir-testmatrix` as
    /// non-gating dissolves the false cycle → correct order (tunnr before draupnir).
    #[test]
    fn registry_aware_order_dissolves_false_cycle_from_published_dep() {
        let graphs = [
            // draupnir needs tunnr-vm (NOT yet published → real gate).
            graph("draupnir", &["draupnir"], &["tunnr-vm"]),
            // tunnr needs nornir-testmatrix (already on crates.io → false gate).
            graph("tunnr", &["tunnr-vm"], &["nornir-testmatrix"]),
            // edda produces nornir-testmatrix + jera; jera needs draupnir.
            graph("edda", &["nornir-testmatrix", "jera"], &["draupnir"]),
        ];

        // NAIVE order: false cycle → SCC → alphabetical → draupnir BEFORE tunnr (bug).
        let naive = crate_publish_order(&graphs);
        let npos = |r: &str| naive.order.iter().position(|x| x == r).unwrap();
        assert!(
            npos("draupnir") < npos("tunnr"),
            "naive order reproduces the bug (draupnir before tunnr): {:?}",
            naive.order
        );

        // GATED order: nornir-testmatrix already-published → non-gating → no cycle,
        // tunnr (produces tunnr-vm) publishes BEFORE draupnir (needs it).
        let non_gating: std::collections::BTreeSet<String> =
            ["nornir-testmatrix".to_string()].into_iter().collect();
        let gated = crate_publish_order_gated(&graphs, &non_gating);
        assert!(gated.cycle.is_empty(), "false cycle dissolved: {:?}", gated.cycle);
        let gpos = |r: &str| gated.order.iter().position(|x| x == r).unwrap();
        assert!(
            gpos("tunnr") < gpos("draupnir"),
            "gated order is correct (tunnr before draupnir): {:?}",
            gated.order
        );
    }

    /// The up-front guard: it FLAGS an order that publishes a repo before a gating
    /// dep is available, and PASSES the corrected order. This is what refuses a
    /// doomed cascade before the first irreversible upload.
    #[test]
    fn cascade_order_violations_catches_bad_order_passes_good() {
        let graphs = [
            graph("draupnir", &["draupnir"], &["tunnr-vm"]),
            graph("tunnr", &["tunnr-vm"], &["nornir-testmatrix"]),
            graph("edda", &["nornir-testmatrix", "jera"], &["draupnir"]),
        ];
        // nornir-testmatrix is already live (available up front).
        let available: std::collections::BTreeSet<String> =
            ["nornir-testmatrix".to_string()].into_iter().collect();

        // BAD order (the naive SCC-alphabetical one) → draupnir before tunnr-vm.
        let bad = vec!["draupnir".to_string(), "edda".to_string(), "tunnr".to_string()];
        let v = cascade_order_violations(&graphs, &bad, &available);
        assert!(
            v.iter().any(|x| x.repo == "draupnir" && x.dep_crate == "tunnr-vm"
                && x.producer == "tunnr"),
            "guard names draupnir→tunnr-vm as the violation: {v:?}"
        );

        // GOOD order → no violations.
        let good = vec!["tunnr".to_string(), "draupnir".to_string(), "edda".to_string()];
        assert!(
            cascade_order_violations(&graphs, &good, &available).is_empty(),
            "corrected order is sound"
        );
    }

    /// Only crates that justify a cross-repo edge are collected for probing.
    #[test]
    fn cross_repo_gating_crates_are_the_edge_justifiers() {
        let graphs = [
            graph("draupnir", &["draupnir"], &["tunnr-vm"]),
            graph("tunnr", &["tunnr-vm"], &["nornir-testmatrix"]),
            graph("edda", &["nornir-testmatrix", "jera"], &["draupnir"]),
        ];
        let via = cross_repo_gating_crates(&graphs);
        let expect: std::collections::BTreeSet<String> =
            ["tunnr-vm", "nornir-testmatrix", "draupnir"].iter().map(|s| s.to_string()).collect();
        assert_eq!(via, expect, "exactly the cross-repo edge crates");
        assert!(!via.contains("jera"), "jera gates nothing cross-repo here");
    }

    /// Build a graph carrying per-dep version requirements (consumer `version=`).
    fn graph_reqs(repo: &str, produces: &[&str], deps: &[(&str, &str)]) -> RepoGraph {
        let mut g = RepoGraph {
            repo: repo.to_string(),
            produces: produces.iter().map(|s| s.to_string()).collect(),
            ..Default::default()
        };
        for (dep, req) in deps {
            g.deps.insert((*dep).to_string());
            g.dep_reqs.entry((*dep).to_string()).or_default().insert((*req).to_string());
        }
        g
    }

    /// A probe with a fixed table of published (non-yanked) versions per crate,
    /// mirroring `CratesIoProbe`: an unknown crate ⇒ `None` (conservative), a known
    /// crate ⇒ `Some(bool)` for whether a live version matches the requirement.
    struct MapProbe(std::collections::BTreeMap<&'static str, Vec<&'static str>>);
    impl crate::release::preflight::RegistryProbe for MapProbe {
        fn version_live(&self, k: &str, v: &str) -> Option<bool> {
            self.0.get(k).map(|vs| vs.iter().any(|x| *x == v))
        }
        fn req_satisfied(&self, k: &str, req: &str) -> Option<bool> {
            let req = semver::VersionReq::parse(req).ok()?;
            let vs = self.0.get(k)?;
            Some(vs.iter().any(|s| {
                semver::Version::parse(s).map(|v| req.matches(&v)).unwrap_or(false)
            }))
        }
    }

    /// The exact false-positive this fix targets: a cross-repo dep whose PRODUCER is
    /// ALSO in the publish set (and about to bump) is NON-gating when crates.io
    /// already serves a version satisfying the consumer's `^` requirement. Models
    /// the real incident — `draupnir → tunnr-vm` (^0.1, live 0.1.2) and
    /// `dwarves/holger → nornir-build-thing` (^0.1.0, live 0.1.1) — where the old
    /// producer-target probe wrongly gated on the bumped 0.1.3 / 0.1.2 target.
    #[test]
    fn registry_satisfied_cross_repo_dep_is_non_gating_even_when_producer_in_set() {
        let graphs = [
            graph_reqs("draupnir", &["draupnir"], &[("tunnr-vm", "0.1")]),
            graph_reqs("tunnr", &["tunnr-vm"], &[]),
            graph_reqs("dwarves", &["dwarves"], &[("nornir-build-thing", "0.1.0")]),
            graph_reqs("holger", &["holger"], &[("nornir-build-thing", "0.1.0")]),
            graph_reqs("nornir", &["nornir-build-thing"], &[]),
        ];
        // crates.io serves versions that SATISFY the consumers' `^` requirements —
        // even though the producers (tunnr, nornir) would bump to 0.1.3 / 0.1.2.
        let probe = MapProbe(
            [("tunnr-vm", vec!["0.1.1", "0.1.2"]), ("nornir-build-thing", vec!["0.1.0", "0.1.1"])]
                .into_iter()
                .collect(),
        );
        let non_gating = registry_non_gating_crates(&graphs, &probe);
        assert!(non_gating.contains("tunnr-vm"), "tunnr-vm ^0.1 satisfied by live 0.1.2");
        assert!(
            non_gating.contains("nornir-build-thing"),
            "nornir-build-thing ^0.1.0 satisfied by live 0.1.1"
        );

        // With these non-gating, an order that publishes the CONSUMERS before their
        // producers is sound (0 order violations) — the false positive is gone.
        let order = vec![
            "draupnir".to_string(),
            "dwarves".to_string(),
            "holger".to_string(),
            "tunnr".to_string(),
            "nornir".to_string(),
        ];
        let viol = cascade_order_violations(&graphs, &order, &non_gating);
        assert!(viol.is_empty(), "no order violations once registry-satisfied deps are non-gating: {viol:?}");
    }

    /// The guardrail: a genuinely-UNPUBLISHED cross-repo dep (or one whose only live
    /// version does NOT satisfy the consumer's requirement) STAYS gating — the
    /// producer must still publish first, and a producer-after-consumer order is
    /// correctly flagged.
    #[test]
    fn unpublished_or_unsatisfied_cross_repo_dep_stays_gating() {
        let graphs = [
            // draupnir needs tunnr-vm ^0.1 — but crates.io has NO tunnr-vm at all.
            graph_reqs("draupnir", &["draupnir"], &[("tunnr-vm", "0.1")]),
            graph_reqs("tunnr", &["tunnr-vm"], &[]),
            // dwarves needs nornir-build-thing ^0.2 — only 0.1.x is live (no match).
            graph_reqs("dwarves", &["dwarves"], &[("nornir-build-thing", "0.2")]),
            graph_reqs("nornir", &["nornir-build-thing"], &[]),
        ];
        let probe = MapProbe(
            [("nornir-build-thing", vec!["0.1.0", "0.1.1"])].into_iter().collect(),
        );
        let non_gating = registry_non_gating_crates(&graphs, &probe);
        assert!(
            !non_gating.contains("tunnr-vm"),
            "unpublished tunnr-vm must stay gating"
        );
        assert!(
            !non_gating.contains("nornir-build-thing"),
            "^0.2 unsatisfied by live 0.1.x — stays gating"
        );

        // Publishing the consumers before the producers now IS a violation.
        let bad = vec![
            "draupnir".to_string(),
            "dwarves".to_string(),
            "tunnr".to_string(),
            "nornir".to_string(),
        ];
        let viol = cascade_order_violations(&graphs, &bad, &non_gating);
        assert!(
            viol.iter().any(|v| v.repo == "draupnir" && v.dep_crate == "tunnr-vm"),
            "draupnir→tunnr-vm still flagged: {viol:?}"
        );
        assert!(
            viol.iter().any(|v| v.repo == "dwarves" && v.dep_crate == "nornir-build-thing"),
            "dwarves→nornir-build-thing still flagged: {viol:?}"
        );
    }

    /// A path dep with NO `version=` (empty-string sentinel) can never resolve from
    /// the registry, so it keeps its crate gating even if some other consumer is
    /// satisfied — the conservative ALL-consumers rule.
    #[test]
    fn versionless_path_dep_keeps_crate_gating() {
        let mut consumer_no_ver = graph_reqs("holger", &["holger"], &[]);
        consumer_no_ver.deps.insert("nornir-build-thing".to_string());
        // No dep_reqs entry ⇒ treated as the empty-string sentinel (unsatisfiable).
        let graphs = [
            graph_reqs("dwarves", &["dwarves"], &[("nornir-build-thing", "0.1.0")]),
            consumer_no_ver,
            graph_reqs("nornir", &["nornir-build-thing"], &[]),
        ];
        let probe =
            MapProbe([("nornir-build-thing", vec!["0.1.1"])].into_iter().collect());
        let non_gating = registry_non_gating_crates(&graphs, &probe);
        assert!(
            !non_gating.contains("nornir-build-thing"),
            "a versionless consumer keeps the crate gating (ALL-consumers rule)"
        );
    }

    #[test]
    fn blast_radius_is_transitive_dependents() {
        let graphs = [
            graph("skade", &["skade-katalog"], &[]),
            graph("nornir", &["nornir"], &["skade-katalog"]),
            graph("cli", &["cli"], &["nornir"]),
        ];
        let mut radius = blast_radius(&graphs, "skade");
        radius.sort();
        assert_eq!(radius, vec!["cli", "nornir"], "changing skade re-validates nornir + cli");
    }

    /// Diamond fan-out: `core` feeds two independent mids, both feeding one `app`.
    /// The blast radius is the WHOLE transitive closure with no duplicates, and the
    /// changed repo is never in its own radius.
    #[test]
    fn blast_radius_diamond_is_full_closure_without_self() {
        let graphs = [
            graph("core", &["core"], &[]),
            graph("left", &["left"], &["core"]),
            graph("right", &["right"], &["core"]),
            graph("app", &["app"], &["left", "right"]),
        ];
        let mut radius = blast_radius(&graphs, "core");
        radius.sort();
        assert_eq!(radius, vec!["app", "left", "right"], "closure over both diamond arms, deduped");
        assert!(!radius.contains(&"core".to_string()), "a repo is not in its own blast radius");
        // A pure sink has an EMPTY blast radius — nothing depends on it.
        assert!(blast_radius(&graphs, "app").is_empty(), "nobody depends on the sink app");
    }

    /// A repo nobody depends on (a disconnected island / leaf) has an empty radius.
    #[test]
    fn blast_radius_empty_for_undepended_repo() {
        let graphs = [
            graph("a", &["a"], &["b"]),
            graph("b", &["b"], &[]),
            graph("island", &["island"], &[]), // no one depends on island
        ];
        assert!(blast_radius(&graphs, "island").is_empty());
        // b IS depended on by a → radius {a}.
        assert_eq!(blast_radius(&graphs, "b"), vec!["a".to_string()]);
    }

    #[test]
    fn publish_order_flags_cycle() {
        let graphs = [
            graph("a", &["a-crate"], &["b-crate"]),
            graph("b", &["b-crate"], &["a-crate"]),
        ];
        let topo = publish_order(&graphs);
        assert!(topo.order.is_empty(), "all on a cycle → none ordered");
        assert_eq!(topo.cycle.len(), 2);
    }

    #[test]
    fn cycle_advice_empty_on_clean_dag() {
        let graphs = [
            graph("znippy", &["znippy-common"], &["serde"]),
            graph("nornir", &["nornir"], &["znippy-common"]),
        ];
        assert!(cycle_advice(&graphs).is_empty(), "a DAG has no cycle to break");
    }

    #[test]
    fn cycle_advice_two_node_picks_deterministic_edge() {
        let graphs = [
            graph("a", &["a-crate"], &["b-crate"]),
            graph("b", &["b-crate"], &["a-crate"]),
        ];
        let advice = cycle_advice(&graphs);
        assert_eq!(advice.len(), 1, "one cycle");
        let c = &advice[0];
        assert_eq!(c.members, vec!["a", "b"]);
        // Both edges ride one crate → tie broken by (len, from, to): a→b wins.
        assert_eq!((c.cut_from.as_str(), c.cut_to.as_str()), ("a", "b"));
        assert_eq!(c.via, vec!["b-crate"]);
    }

    #[test]
    fn cycle_advice_cuts_the_cheapest_edge() {
        // x→y rides on TWO crates, y→x on ONE → cut y→x (cheaper to untangle).
        let graphs = [
            graph("x", &["x1"], &["y1", "y2"]),
            graph("y", &["y1", "y2"], &["x1"]),
        ];
        let advice = cycle_advice(&graphs);
        assert_eq!(advice.len(), 1);
        let c = &advice[0];
        assert_eq!((c.cut_from.as_str(), c.cut_to.as_str()), ("y", "x"));
        assert_eq!(c.via, vec!["x1"], "the single-crate edge is the cut");
    }

    // ─── patch-fork promote gate ───

    #[test]
    fn patch_fork_detects_path_and_git_but_not_registry_pin() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        std::fs::write(root.join("Cargo.toml"), r#"[package]
name = "skade"
version = "0.1.0"

[dependencies]
iceberg = "0.9"

[patch.crates-io]
iceberg = { path = "../iceberg-arrow58" }
forkgit = { git = "https://example.com/forkgit" }
serde = "1.0.200"
toml = { version = "0.8" }
"#).unwrap();

        let blocks = patch_fork_blockers(root);
        // iceberg (path) + forkgit (git) → 2 blocks; serde + toml registry no-ops skipped.
        assert_eq!(blocks.len(), 2, "{blocks:#?}");
        let iceberg = blocks.iter().find(|b| b.patched_dep == "iceberg").unwrap();
        assert_eq!(iceberg.fork_kind, ForkKind::Path);
        assert_eq!(iceberg.crate_name, "skade");
        assert!(iceberg.source.contains("iceberg-arrow58"));
        let git = blocks.iter().find(|b| b.patched_dep == "forkgit").unwrap();
        assert_eq!(git.fork_kind, ForkKind::Git);
        assert!(!blocks.iter().any(|b| b.patched_dep == "serde"));
        assert!(!blocks.iter().any(|b| b.patched_dep == "toml"));
    }

    #[test]
    fn patch_fork_registry_only_patch_is_not_blocked() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        std::fs::write(root.join("Cargo.toml"), r#"[package]
name = "clean"
version = "0.1.0"

[patch.crates-io]
foo = "1.2"
bar = { version = "2.0" }
"#).unwrap();
        assert!(patch_fork_blockers(root).is_empty(), "registry-version patches are publishable");
    }

    #[test]
    fn promote_block_is_transitive_over_workspace_deps() {
        // skade rides the iceberg fork → directly blocked. nornir depends on
        // skade-katalog (which skade produces) → transitively blocked. facett is
        // independent → publishable.
        let graphs = [
            graph("skade", &["skade-katalog"], &["iceberg"]),
            graph("nornir", &["nornir"], &["skade-katalog"]),
            graph("facett", &["facett"], &["serde"]),
        ];
        let directly: std::collections::BTreeSet<String> =
            ["skade-katalog".to_string()].into_iter().collect();
        let blocked = promote_blocked_crates(&graphs, &directly);
        assert!(blocked.contains("skade-katalog"), "the fork rider is blocked");
        assert!(blocked.contains("nornir"), "nornir depends on skade-katalog → blocked");
        assert!(!blocked.contains("facett"), "facett is independent → publishable");
    }

    #[test]
    fn cycle_advice_handles_three_node_cycle() {
        let graphs = [
            graph("a", &["a-c"], &["b-c"]),
            graph("b", &["b-c"], &["c-c"]),
            graph("c", &["c-c"], &["a-c"]),
        ];
        let advice = cycle_advice(&graphs);
        assert_eq!(advice.len(), 1, "one 3-node SCC");
        assert_eq!(advice[0].members, vec!["a", "b", "c"]);
    }
}

/// WAREHOUSE-BACKED integration test for [`run_with_semantic_blast`] — Wave-1
/// tested the pure blast-radius maths but deferred the warehouse-aware doctor
/// entry point. This drives it over REAL on-disk repos (so `run` computes the
/// crate graph + blast) plus a SEEDED temporary [`IcebergWarehouse`] (so the SCIP/
/// syn call-graph read attaches the exact impacted call sites).
#[cfg(test)]
mod semantic_blast_run_tests {
    use super::*;
    use crate::knowledge::symbols::{CallEdgeRow, SymbolRow, SymbolScan};
    use crate::release::semantic_blast::ChangedSymbol;
    use crate::warehouse::iceberg::IcebergWarehouse;

    fn write(path: &Path, body: &str) {
        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
        std::fs::write(path, body).unwrap();
    }

    /// Two on-disk crates: `facett` (the API owner) and `korp`, which depends on the
    /// `facett` crate via a `path=` dep — so `blast_radius(facett) == [korp]`.
    fn build_repos(root: &Path) -> Vec<(String, PathBuf)> {
        let facett = root.join("facett");
        let korp = root.join("korp");
        write(&facett.join("Cargo.toml"),
            "[package]\nname = \"facett\"\nversion = \"0.1.0\"\nedition = \"2021\"\n");
        write(&korp.join("Cargo.toml"),
            "[package]\nname = \"korp\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n\
             [dependencies]\nfacett = { path = \"../facett\", version = \"0.1.0\" }\n");
        vec![("facett".to_string(), facett), ("korp".to_string(), korp)]
    }

    /// Seed the warehouse so `korp` calls `facett::render` (one cross-crate site).
    fn seed_korp_calls_facett(wh: &IcebergWarehouse) {
        let scan = SymbolScan {
            snapshot_id: uuid::Uuid::new_v4(),
            ts: chrono::Utc::now(),
            repo: "korp".into(),
            symbols: vec![SymbolRow {
                crate_name: "korp".into(),
                module_path: "korp::view".into(),
                item_kind: "fn".into(),
                item_name: "draw".into(),
                visibility: "pub".into(),
                file: "korp/src/view.rs".into(),
                line: 1,
                doc_lines: 0,
                signature: None,
            }],
            calls: vec![CallEdgeRow {
                crate_name: "korp".into(),
                caller_path: "korp::view::draw".into(),
                callee_ident: "facett::render".into(),
                call_kind: "call".into(),
                file: "korp/src/view.rs".into(),
                line: 40,
            }],
            features: vec![],
            tests: vec![],
        };
        wh.append_symbol_scan(&scan).unwrap();
    }

    #[test]
    fn run_with_semantic_blast_equals_run_plus_populated_map() {
        let dir = tempfile::tempdir().unwrap();
        let repos = build_repos(dir.path());
        let wh = IcebergWarehouse::open(&dir.path().join("wh")).unwrap();
        seed_korp_calls_facett(&wh);
        let policy = DepPolicy::default();

        // Baseline: plain run leaves semantic_blast empty.
        let base = run(&repos, &policy).unwrap();
        assert!(base.semantic_blast.is_empty(), "plain run has no semantic blast");
        // Crate-level blast already knows korp depends on facett.
        assert_eq!(base.blast.get("facett"), None, "facett clean → not in dirty blast (non-git)");
        // Sanity: the crate graph resolved the cross-repo edge.
        assert_eq!(blast_radius_for(&repos, "facett"), vec!["korp".to_string()]);

        // Warehouse-aware run: a `render` removal on facett attaches korp's call site.
        let render = [ChangedSymbol::removed("render")];
        let changed: Vec<(&str, &[ChangedSymbol])> = vec![("facett", &render)];
        let report = run_with_semantic_blast(&repos, &policy, &wh, changed).unwrap();

        // Everything OTHER than semantic_blast equals the plain run.
        assert_eq!(report.topo.order, base.topo.order, "topo order unchanged");
        assert_eq!(report.blast, base.blast, "crate-level blast unchanged");
        assert_eq!(report.repo_edges.len(), base.repo_edges.len(), "repo edges unchanged");

        // …PLUS a populated semantic_blast for facett with korp's exact call site.
        let sb = report.semantic_blast.get("facett").expect("facett semantic blast present");
        assert_eq!(sb.source, "syn");
        assert_eq!(sb.total_call_sites, 1);
        assert_eq!(sb.impacts.len(), 1);
        let site = &sb.impacts[0].call_sites[0];
        assert_eq!(site.crate_name, "korp");
        assert_eq!(site.caller, "korp::view::draw");
        assert_eq!(site.file, "korp/src/view.rs");
        assert_eq!(site.line, 40);

        // An INTERNAL-only change (nobody calls it) leaves the map empty.
        let internal = [ChangedSymbol::changed("private_helper")];
        let changed2: Vec<(&str, &[ChangedSymbol])> = vec![("facett", &internal)];
        let report2 = run_with_semantic_blast(&repos, &policy, &wh, changed2).unwrap();
        assert!(report2.semantic_blast.is_empty(), "internal-only bump surfaces nothing");
    }

    /// `git init` a repo so [`check_dirty`]'s `gix::open` succeeds; the files stay
    /// UNTRACKED, which `worktree_freshness` reports as dirty — exactly the "pending
    /// bump" state the CLI release path diffs.
    fn git_init(root: &Path) {
        std::fs::create_dir_all(root).unwrap();
        let ok = std::process::Command::new("git")
            .arg("-C").arg(root).arg("init")
            .status().map(|s| s.success()).unwrap_or(false);
        assert!(ok, "git init failed (is git installed?)");
    }

    /// Seed one repo's persisted exported surface (the OLD side the CLI diffs a
    /// fresh working-tree scan against). Each `(name, vis)` is one `SymbolRow`.
    fn seed_symbols(wh: &IcebergWarehouse, repo: &str, syms: &[(&str, &str)]) {
        let symbols = syms
            .iter()
            .map(|(name, vis)| SymbolRow {
                crate_name: repo.into(),
                module_path: format!("{repo}::api"),
                item_kind: "fn".into(),
                item_name: (*name).into(),
                visibility: (*vis).into(),
                file: format!("{repo}/src/lib.rs"),
                line: 1,
                doc_lines: 0,
                signature: None,
            })
            .collect();
        let scan = SymbolScan {
            snapshot_id: uuid::Uuid::new_v4(),
            ts: chrono::Utc::now(),
            repo: repo.into(),
            symbols,
            calls: vec![],
            features: vec![],
            tests: vec![],
        };
        wh.append_symbol_scan(&scan).unwrap();
    }

    /// END-TO-END through the WIRED CLI entry point (the inert-gate bug fix): a
    /// DIRTY `facett` that REMOVED an exported `render` a dependent `korp` still
    /// calls. [`run_with_warehouse_semantic_blast`] diffs facett's warehouse surface
    /// against its working tree, populates `semantic_blast`, and
    /// [`crate::release::gate::semantic_link_gate`] then FIRES on the real data —
    /// where before it read an always-empty map and could never fail.
    #[test]
    fn wired_path_populates_blast_and_link_gate_fires() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let facett = root.join("facett");
        let korp = root.join("korp");

        // facett: exports `render` + `open`; a git repo (untracked ⇒ dirty). The
        // working tree DROPS `render` (the bump) — only `open` remains scannable.
        write(&facett.join("Cargo.toml"),
            "[package]\nname = \"facett\"\nversion = \"0.1.0\"\nedition = \"2021\"\n");
        write(&facett.join("src/lib.rs"), "pub fn open() {}\n");
        git_init(&facett);
        // korp depends on the facett crate → blast_radius(facett) == [korp].
        write(&korp.join("Cargo.toml"),
            "[package]\nname = \"korp\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n\
             [dependencies]\nfacett = { path = \"../facett\", version = \"0.1.0\" }\n");
        write(&korp.join("src/lib.rs"), "pub fn draw() {}\n");

        // Warehouse: facett's LAST-PERSISTED surface still had `render` (pub); korp
        // calls facett::render (the live cross-crate site the removal breaks).
        let wh = IcebergWarehouse::open(&root.join("wh")).unwrap();
        seed_symbols(&wh, "facett", &[("render", "pub"), ("open", "pub")]);
        seed_korp_calls_facett(&wh);

        let repos = vec![
            ("facett".to_string(), facett.clone()),
            ("korp".to_string(), korp.clone()),
        ];
        let policy = DepPolicy::default();

        let (report, audit) =
            run_with_warehouse_semantic_blast(&repos, &policy, &wh).unwrap();

        // The wiring saw facett as dirty, derived the one removed symbol, populated.
        assert!(
            audit.dirty_considered.contains(&"facett".to_string()),
            "facett must be considered dirty: {:?}", audit.dirty_considered,
        );
        assert_eq!(
            audit.changed_symbols.get("facett"), Some(&1),
            "the removed `render` is the sole surface delta: {:?}", audit.changed_symbols,
        );
        assert!(audit.populated, "semantic blast must be populated: {}", audit.note);

        let sb = report.semantic_blast.get("facett")
            .expect("facett carries a populated semantic blast");
        assert!(sb.has_link_error(), "removed `render` + a live korp call site = link error");

        // THE FIX: the gate SEES the populated map and FAILS (was inert on an empty map).
        let gate = crate::release::gate::semantic_link_gate(&report.semantic_blast);
        let fired = gate.is_err();
        let msg = gate.err().map(|e| e.to_string()).unwrap_or_default();

        nornir_testmatrix::functional_status(
            "release-doctor",
            "wired_semantic_link_gate_fires",
            fired && audit.populated && msg.contains("render"),
            &format!("note={:?} gate_msg={msg:?}", audit.note),
        );

        assert!(fired, "semantic_link_gate must FIRE on the wired blast (was inert): {}", audit.note);
        assert!(msg.contains("LINK ERROR") && msg.contains("render"),
            "gate names the removed symbol: {msg}");
    }

    /// The GRACEFUL-DEGRADE path: a dirty repo with NO persisted warehouse surface
    /// (a clean checkout against an unseeded warehouse) yields an empty blast, so the
    /// gate SKIPS — never a spurious failure, never a panic.
    #[test]
    fn wired_path_degrades_to_empty_when_no_warehouse_surface() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let facett = root.join("facett");
        write(&facett.join("Cargo.toml"),
            "[package]\nname = \"facett\"\nversion = \"0.1.0\"\nedition = \"2021\"\n");
        write(&facett.join("src/lib.rs"), "pub fn open() {}\n");
        git_init(&facett); // dirty (untracked), but the warehouse holds nothing.

        let wh = IcebergWarehouse::open(&root.join("wh")).unwrap();
        let repos = vec![("facett".to_string(), facett.clone())];
        let policy = DepPolicy::default();

        let (report, audit) =
            run_with_warehouse_semantic_blast(&repos, &policy, &wh).unwrap();
        assert!(report.semantic_blast.is_empty(), "no OLD surface ⇒ empty blast");
        assert!(!audit.populated, "degraded, not populated: {}", audit.note);
        // And the gate trivially passes over the empty map (skipped, not failed).
        assert!(crate::release::gate::semantic_link_gate(&report.semantic_blast).is_ok());
    }

    /// Helper: build the crate graph the doctor would and return `repo`'s blast.
    fn blast_radius_for(repos: &[(String, PathBuf)], repo: &str) -> Vec<String> {
        let graphs: Vec<RepoGraph> = repos
            .iter()
            .map(|(n, p)| gather_repo_graph(n, p).unwrap())
            .collect();
        blast_radius(&graphs, repo)
    }

    // ─── #18 AUTO remedy executors ───

    #[test]
    fn tidy_dirty_sheds_noise_but_keeps_real_changes() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path().join("myrepo");
        write(&root.join("Cargo.toml"), "[package]\nname=\"m\"\nversion=\"0.1.0\"\n");
        write(&root.join("src/lib.rs"), "pub fn a() {}\n");
        crate::gitio::init(&root).unwrap();
        crate::gitio::commit_all(&root, "seed").unwrap();
        assert!(!crate::gitio::worktree_freshness(&root).unwrap().dirty, "clean baseline");

        // Case 1: dirtiness is PURE noise → tidy removes it → repo goes clean.
        write(&root.join(".claude/scratch.txt"), "junk\n");
        write(&root.join("data.arrows"), "\x00arrow\n");
        write(&root.join("src/deep/nested.arrows"), "\x00\n");
        assert!(crate::gitio::worktree_freshness(&root).unwrap().dirty);
        let repos = vec![("myrepo".to_string(), root.clone())];
        let dirty = check_dirty(&repos);
        let out = tidy_dirty_repos(&dirty, &repos).unwrap();
        assert_eq!(out.removed, 3, "two .arrows files + one .claude dir");
        assert_eq!(out.cleaned, vec!["myrepo".to_string()]);
        assert!(out.still_dirty.is_empty());
        assert!(!root.join(".claude").exists());
        assert!(!root.join("data.arrows").exists());
        assert!(!crate::gitio::worktree_freshness(&root).unwrap().dirty, "clean after tidy");

        // Case 2: a REAL untracked file → tidy can't fix it → still dirty.
        write(&root.join("src/new_real.rs"), "pub fn b() {}\n");
        write(&root.join("more.arrows"), "\x00\n");
        let dirty2 = check_dirty(&repos);
        let out2 = tidy_dirty_repos(&dirty2, &repos).unwrap();
        assert_eq!(out2.removed, 1, "only the .arrows noise is shed");
        assert!(out2.cleaned.is_empty());
        assert_eq!(out2.still_dirty, vec!["myrepo".to_string()], "real change remains");
        assert!(root.join("src/new_real.rs").exists(), "real file untouched");
    }

    #[test]
    fn cut_cycle_cheap_drops_the_optional_edge_and_scrubs_features() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        // acrate → bcrate (normal path); bcrate → acrate (OPTIONAL path, gated).
        // The MFAS cheapest cut (cost 1) is the optional edge bcrate→acrate.
        write(&root.join("repoA/Cargo.toml"), r#"[package]
name = "acrate"
version = "0.1.0"
edition = "2021"

[dependencies]
bcrate = { path = "../repoB" }
"#);
        write(&root.join("repoB/Cargo.toml"), r#"[package]
name = "bcrate"
version = "0.1.0"
edition = "2021"

[dependencies]
acrate = { path = "../repoA", optional = true }

[features]
withA = ["dep:acrate"]
"#);
        let repos = vec![
            ("repoA".to_string(), root.join("repoA")),
            ("repoB".to_string(), root.join("repoB")),
        ];
        // Precondition: the crate graph really has the cheap cycle.
        let graphs: Vec<RepoGraph> =
            repos.iter().map(|(n, p)| gather_repo_graph(n, p).unwrap()).collect();
        let sols = cycle_solutions(&graphs);
        assert_eq!(sols.len(), 1, "one crate cycle: {sols:#?}");
        assert!(sols[0].solutions.first().unwrap().cost <= 1, "cheap (optional) cut");

        let out = apply_cheap_cycle_cuts(&repos).unwrap();
        assert_eq!(out.cut, vec![("bcrate".to_string(), "acrate".to_string())]);
        assert!(out.unresolved.is_empty(), "{:#?}", out.unresolved);

        // repoB no longer declares acrate, and the feature no longer references it.
        let b = std::fs::read_to_string(root.join("repoB/Cargo.toml")).unwrap();
        assert!(!b.contains("acrate = {"), "optional dep removed:\n{b}");
        assert!(!b.contains("dep:acrate"), "feature ref scrubbed:\n{b}");
        // And the cycle is gone.
        let graphs2: Vec<RepoGraph> =
            repos.iter().map(|(n, p)| gather_repo_graph(n, p).unwrap()).collect();
        assert!(cycle_solutions(&graphs2).is_empty(), "cycle broken");
    }
}

#[cfg(test)]
mod binary_graph_cross_check_tests {
    use super::*;
    use crate::warehouse::dep_graph::{CrossRepoEdge, WorkspaceGraph};
    use std::collections::BTreeSet;

    fn adj(pairs: &[(&str, &str)]) -> BTreeMap<String, BTreeSet<String>> {
        let mut m: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
        for (a, b) in pairs {
            m.entry(a.to_string()).or_default().insert(b.to_string());
            m.entry(b.to_string()).or_default();
        }
        m
    }

    /// The ELF-derived graph, built through the SAME projection production uses
    /// (`BinaryGraph::to_workspace_graph` → `BinaryDerivedGraph::from_workspace`),
    /// matches the source graph's cycle structure AND its MFAS min-cut cost when
    /// the two constellations carry the same link cycle.
    #[test]
    fn binary_derived_scc_and_mfas_match_source() {
        // Source crate graph: a ⇄ b cycle, plus a→c tail (c is a clean leaf).
        let source = adj(&[("a", "b"), ("b", "a"), ("a", "c")]);

        // ELF constellation with the identical topology, projected via the shared
        // WorkspaceGraph model (what to_workspace_graph yields for real objects).
        let bin_edges = vec![
            CrossRepoEdge::normal("a", "b", ["s_ab".to_string()].into_iter().collect()),
            CrossRepoEdge::normal("b", "a", ["s_ba".to_string()].into_iter().collect()),
            CrossRepoEdge::normal("a", "c", ["s_ac".to_string()].into_iter().collect()),
        ];
        let wg = WorkspaceGraph::from_query_parts(Default::default(), bin_edges);
        let derived = BinaryDerivedGraph::from_workspace(&wg);

        // The binary projection found exactly the one a⇄b cycle.
        assert_eq!(derived.cycles, vec![vec!["a".to_string(), "b".to_string()]]);

        // Cross-check: SCC partition + MFAS cut cost agree.
        let cc = cross_check_source_vs_binary(&source, &derived.adjacency);
        assert!(cc.agrees(), "source and ELF graphs agree: {cc:?}");
        assert_eq!(cc.shared_cycles, vec![vec!["a".to_string(), "b".to_string()]]);
        assert!(cc.source_only_cycles.is_empty());
        assert!(cc.binary_only_cycles.is_empty());
        assert!(cc.mfas_divergences.is_empty());
    }

    /// A DIVERGENCE — the binaries link a cycle the source manifests do not
    /// declare (or vice-versa) — is flagged, not silently passed. This is the
    /// doctor signal that source and shipped artefacts have drifted.
    #[test]
    fn binary_derived_divergence_from_source_is_flagged() {
        // Source is a clean DAG a→b→c (no cycle).
        let source = adj(&[("a", "b"), ("b", "c")]);
        // The linked binaries, though, carry a b⇄c back-edge (a real link cycle).
        let bin_edges = vec![
            CrossRepoEdge::normal("a", "b", ["s".to_string()].into_iter().collect()),
            CrossRepoEdge::normal("b", "c", ["s".to_string()].into_iter().collect()),
            CrossRepoEdge::normal("c", "b", ["s".to_string()].into_iter().collect()),
        ];
        let wg = WorkspaceGraph::from_query_parts(Default::default(), bin_edges);
        let derived = BinaryDerivedGraph::from_workspace(&wg);

        let cc = cross_check_source_vs_binary(&source, &derived.adjacency);
        assert!(!cc.agrees(), "a binary-only cycle must NOT pass the cross-check");
        assert_eq!(cc.binary_only_cycles, vec![vec!["b".to_string(), "c".to_string()]]);
        assert!(cc.source_only_cycles.is_empty());
        assert!(cc.shared_cycles.is_empty());
    }

    /// `graph_from_binary` drives the real ELF extractor end-to-end: point it at
    /// the test binary's own executable (a genuine ELF on this Linux target) and
    /// assert it yields a non-empty symbol graph with the object as a node. Guards
    /// the extraction → projection wiring, not just the pure cross-check math.
    #[test]
    fn graph_from_binary_reads_a_real_elf() {
        let exe = std::env::current_exe().expect("test exe path");
        let derived = graph_from_binary(&[exe]).expect("extract ELF graph from the test binary");
        assert!(!derived.adjacency.is_empty(), "the ELF object is a graph node");
        assert!(
            !derived.symbol_rows.is_empty(),
            "a dynamically-linked ELF exposes .dynsym symbol rows"
        );
    }
}