majordomus_cli/release/

version.rs

//! The version: the one place it is authored, what is derived from that place, what the
//! contract requires next and what the commits imply as evidence, and the one writer that
//! raises it.
//!
//! The product version is authored in exactly one place, the `[package] version` line of
//! the crate manifest ([`MANIFEST`]). Every other statement of it is derived from that line
//! and checked, or is a record of a version that was released:
//!
//! ```text
//!   apps/majordomus-cli/Cargo.toml   authored    the one place; `release bump` writes it
//!   crate::VERSION                   compiled    cargo's CARGO_PKG_VERSION
//!   share/version.txt                projected   `majordomus generate`; bin/majordomus reads it
//!   apps/majordomus-cli/Cargo.lock   derived     cargo's record; the writer keeps it in step
//!   generator stamps, the changelog  generated   `majordomus generate`
//!   .ai/repo/releases/*.yaml         records     the release pipeline, after publication
//! ```
//!
//! The shell tool used to state the version a second time, by hand, because an installed
//! tree has no `Cargo.toml` and the tool cannot read one at run time. It reads
//! [`PROJECTION`] instead: a typed generated artifact that ships in every archive beside the
//! tool, that `generate --check` refuses when it falls behind the manifest, and that nobody
//! edits. [`diagnose`] is what refuses a version anybody writes down by hand where the
//! tool's own files live.
//!
//! One reader of the authority per language: [`declared`] here, `scripts/release-version`
//! in shell. Nothing else parses the manifest for its version.
//!
//! ```
//! use majordomus_cli::release::version::{declared_in, parse_projection, render_projection};
//! // the authority, and the one line the shell tool reads back from its projection of it
//! let authority = declared_in("[package]\nversion = \"0.9.0\"\n").unwrap();
//! assert_eq!(parse_projection(&render_projection(&authority)).as_deref(), Some("0.9.0"));
//! ```

use std::collections::BTreeSet;
use std::path::Path;

use super::compat::{Diagnostic, Severity};
use super::model::{Change, ChangeKind, DecidedBy, VersionReport};
use crate::model::Object;

/// The crate manifest: the one place the version is authored.
pub const MANIFEST: &str = "apps/majordomus-cli/Cargo.toml";
/// The projection of the version the shell tool reads at start-up, from beside itself.
///
/// Generated by `majordomus generate` (target `distribution`) from [`MANIFEST`] and never
/// edited: [`render_projection`] writes its body and [`parse_projection`] reads it back.
pub const PROJECTION: &str = "share/version.txt";
/// The lock file, which records the crate's own version alongside every dependency's.
///
/// Not a declaration — cargo derives it from the manifest, and nobody chooses the value.
/// It is a tracked *record*, though, and the build runs `--locked`: a bump that raised the
/// manifest and left the lock behind made the next build fail with `cannot update the lock
/// file ... because --locked was passed`, which reads as a toolchain fault rather than as a
/// half-applied bump, and it fails every launcher call — the git hooks, the MCP server —
/// until something rebuilds without `--locked`. So the writer keeps the crate's own entry
/// in step, by cargo's rule, in the same command that raises the manifest.
pub const LOCK: &str = "apps/majordomus-cli/Cargo.lock";

/// Where the tool's own files live, and so where a version written by hand is refused.
///
/// The shell tool, the libraries it sources, the scripts that build and ship it, and the
/// distribution's data. A version stated in one of these by hand is a second declaration of
/// the fact [`MANIFEST`] owns; [`carriers`] finds it and [`diagnose`] refuses it.
pub const CARRIER_ROOTS: &[&str] = &["bin", "lib", "scripts", "share"];

/// The diagnostic id of a version written down by hand where the tool's files live.
pub const STATED_BY_HAND: &str = "version-stated-by-hand";
/// The diagnostic id of a projection that is behind the manifest, or missing: the state
/// between a bump and the derivation after it. A warning — `generate --check` refuses it.
pub const PROJECTION_STALE: &str = "projection-stale";
/// The diagnostic id of a projection ahead of the manifest, or unrelated to it: a version
/// no derivation produces, so somebody wrote it.
pub const WRITERS_DISAGREE: &str = "writers-disagree";

/// The diagnostic id of a version label — `v0.1`, a major and a minor with no patch —
/// typed into hand-written prose, where it states which version the text describes.
pub const LABEL_IN_PROSE: &str = "version-label-in-prose";
/// The diagnostic id of a [`LABEL_HISTORY`] entry that cannot be honoured: no reason, a
/// path that is not tracked prose, or a document that no longer carries a label.
pub const LABEL_HISTORY_INVALID: &str = "version-label-history-invalid";

/// The documents that describe a past version and are allowed to name it by label, one
/// `<path> <reason>` per line. A record of the design phase says "v0.1" because it is about
/// v0.1; a page describing the tool as it stands says it because nobody changed it.
pub const LABEL_HISTORY: &str = ".ai/repo/version-label-history.txt";

/// Where hand-written prose lives, as `git ls-files` pathspecs. [`prose_files`] narrows
/// these: git's `*` crosses directories, and `site/content/` is mostly generated.
const PROSE_ROOTS: &[&str] = &[
    "README.md",
    "AGENTS.md",
    "CLAUDE.md",
    "docs",
    "site/content-src",
    "site/content",
    "site/data",
    "site/templates",
    ".ai/repo",
    "share/providers",
];

/// Dated records under `.ai/repo/`: a decision or a session names the version it was taken
/// in, and stays true about that moment.
const PROSE_RECORDS: &[&str] = &[".ai/repo/adrs/", ".ai/repo/sessions/"];

/// The generated-artifact manifest: every path in it is written by `majordomus generate`,
/// so a version stamped into one is a projection and never a statement by hand.
const GENERATED_MANIFEST: &str = "docs/generated/artifacts.json";

/// A file larger than this is not a script or a declaration anybody writes by hand.
const LARGEST_READ: u64 = 2 * 1024 * 1024;

/// How much a set of changes raises a version.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Bump {
    /// Nothing since the last release.
    None,
    /// A fix, or anything that is not a feature.
    Patch,
    /// At least one feature.
    Minor,
    /// At least one breaking change.
    Major,
}

impl Bump {
    /// The word the reports use.
    pub fn as_str(self) -> &'static str {
        match self {
            Bump::None => "none",
            Bump::Patch => "patch",
            Bump::Minor => "minor",
            Bump::Major => "major",
        }
    }

    /// The bump named by a word, for `release bump --minor` and friends.
    pub fn parse(word: &str) -> Option<Bump> {
        match word {
            "major" => Some(Bump::Major),
            "minor" => Some(Bump::Minor),
            "patch" => Some(Bump::Patch),
            "none" => Some(Bump::None),
            _ => None,
        }
    }
}

/// What a set of conventional commits *says about itself*.
///
/// The rule is the conventional-commit rule and nothing more: a breaking change is major, a
/// feature is minor, anything else is patch, and no commits at all is none.
///
/// # This is evidence, not authority
///
/// It used to decide what `release bump` wrote, and that was the defect this subsystem
/// exists to remove. A commit message is a label a person chose, and a capability deleted
/// under a `refactor:` heading was a patch to this function and a broken caller to everyone
/// else. The compatibility level is now measured from the public contract by
/// [`crate::release::compat::analyze`]; this answer is carried beside it as
/// [`crate::release::compat::CommitEvidence`], and when the two disagree the plan says which
/// one understated the change. Nothing decides a version from this alone.
pub fn bump_of(changes: &[Change]) -> Bump {
    if changes.is_empty() {
        return Bump::None;
    }
    if changes.iter().any(|c| c.breaking) {
        return Bump::Major;
    }
    if changes.iter().any(|c| c.kind == ChangeKind::Feat) {
        return Bump::Minor;
    }
    Bump::Patch
}

/// A semantic version, only as much as this needs.
///
/// Ordered by the three numbers, which is what lets the writer refuse a version smaller than
/// the one the contract requires rather than only a *bump* smaller than required.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct Version {
    /// Major.
    pub major: u64,
    /// Minor.
    pub minor: u64,
    /// Patch.
    pub patch: u64,
}

impl Version {
    /// Read `1.2.3`; anything else is `None`.
    pub fn parse(text: &str) -> Option<Version> {
        let mut parts = text.trim().split('.');
        let major = parts.next()?.parse().ok()?;
        let minor = parts.next()?.parse().ok()?;
        let patch = parts.next()?.parse().ok()?;
        if parts.next().is_some() {
            return None;
        }
        Some(Version {
            major,
            minor,
            patch,
        })
    }

    /// This version raised by `bump`.
    ///
    /// Arithmetic and nothing else: zero-major is not special-cased here, because whether a
    /// breaking change below 1.0 costs a major or a minor is a *policy* question and this
    /// repository answers it in exactly one place, [`crate::release::compat::Policy`]. A
    /// second answer here is the shape this subsystem was built to remove.
    pub fn raised(self, bump: Bump) -> Version {
        match bump {
            Bump::None => self,
            Bump::Patch => Version {
                patch: self.patch + 1,
                ..self
            },
            Bump::Minor => Version {
                minor: self.minor + 1,
                patch: 0,
                ..self
            },
            Bump::Major => Version {
                major: self.major + 1,
                minor: 0,
                patch: 0,
            },
        }
    }
}

impl Version {
    /// This version raised by a measured compatibility impact.
    ///
    /// The bridge between the engine's verdict and the arithmetic: the policy has already
    /// decided what a `0.x` breaking change costs, so this only has to apply it.
    ///
    /// ```
    /// use majordomus_cli::release::compat::Impact;
    /// use majordomus_cli::release::version::Version;
    /// let v = Version::parse("0.5.0").unwrap();
    /// assert_eq!(v.raised_to(Impact::Minor).to_string(), "0.6.0");
    /// assert_eq!(v.raised_to(Impact::Major).to_string(), "1.0.0");
    /// assert_eq!(v.raised_to(Impact::None).to_string(), "0.5.0");
    /// ```
    pub fn raised_to(self, impact: crate::release::compat::Impact) -> Version {
        use crate::release::compat::Impact;
        self.raised(match impact {
            Impact::None => Bump::None,
            Impact::Patch => Bump::Patch,
            Impact::Minor => Bump::Minor,
            Impact::Major => Bump::Major,
        })
    }
}

impl std::fmt::Display for Version {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}.{}.{}", self.major, self.minor, self.patch)
    }
}

/// The version the crate manifest declares: the authority.
///
/// The one Rust reader of it. `majordomus generate` asks the same function when it decides
/// whether the executable running is the one the tree declares.
///
/// ```
/// use majordomus_cli::release::version::{declared, MANIFEST};
/// let dir = tempfile::tempdir().unwrap();
/// // No manifest is no version, never a guess.
/// assert_eq!(declared(dir.path()), None);
/// std::fs::create_dir_all(dir.path().join("apps/majordomus-cli")).unwrap();
/// std::fs::write(dir.path().join(MANIFEST), "[package]\nversion = \"0.9.0\"\n").unwrap();
/// assert_eq!(declared(dir.path()).as_deref(), Some("0.9.0"));
/// ```
pub fn declared(root: &Path) -> Option<String> {
    declared_in(&std::fs::read_to_string(root.join(MANIFEST)).ok()?)
}

/// The `[package] version` of a manifest's text.
///
/// The first `version = "..."` inside `[package]`, which is where the manifest puts it: a
/// dependency pinned at a version further down is a different package, a key that merely
/// begins with `version` is a different key, and a trailing comment is not part of the value.
/// Read without a TOML parser, because the value wanted is one quoted scalar in a table whose
/// header is unambiguous, and a dependency to read it would be one this crate argues against.
///
/// ```
/// use majordomus_cli::release::version::declared_in;
/// let manifest = "[package]\nname = \"x\"\nversion = \"1.2.3\"   # bumped\n\n\
///                 [dependencies]\nserde = { version = \"1.2.4\" }\n";
/// assert_eq!(declared_in(manifest).as_deref(), Some("1.2.3"));
/// // outside [package] there is no package version at all
/// assert_eq!(declared_in("[dependencies]\nversion = \"1.0.0\"\n"), None);
/// // a key that only starts with the word is another key
/// assert_eq!(declared_in("[package]\nversioned = \"1.0.0\"\n"), None);
/// ```
pub fn declared_in(manifest: &str) -> Option<String> {
    let mut in_package = false;
    for line in manifest.lines() {
        let line = line.trim();
        if line.starts_with('[') {
            in_package = line == "[package]";
            continue;
        }
        if !in_package {
            continue;
        }
        let Some(rest) = line.strip_prefix("version") else {
            continue;
        };
        let Some(rest) = rest.trim_start().strip_prefix('=') else {
            continue;
        };
        let rest = rest.trim();
        let value = match rest.strip_prefix('"') {
            Some(quoted) => quoted.split('"').next().unwrap_or_default(),
            None => rest.split('#').next().unwrap_or_default().trim(),
        };
        return (!value.is_empty()).then(|| value.to_string());
    }
    None
}

/// The version the lock file records for this crate.
///
/// Only the entry whose `name` is this crate's: a dependency that happens to be at the same
/// version is a different package and is never read or written here.
///
/// ```
/// use majordomus_cli::release::version::locked;
/// let dir = tempfile::tempdir().unwrap();
/// // No lock file at all is `None`, never a guess.
/// assert_eq!(locked(dir.path()), None);
/// ```
pub fn locked(root: &Path) -> Option<String> {
    let text = std::fs::read_to_string(root.join(LOCK)).ok()?;
    let mut in_package = false;
    for line in text.lines() {
        let line = line.trim();
        if line == "[[package]]" {
            in_package = false;
            continue;
        }
        if line == "name = \"majordomus-cli\"" {
            in_package = true;
            continue;
        }
        if in_package {
            if let Some(rest) = line.strip_prefix("version") {
                return rest.split('"').nth(1).map(|v| v.to_string());
            }
        }
    }
    None
}

/// The body of [`PROJECTION`]: one `version=` line, which `bin/majordomus` reads with shell
/// builtins alone. `majordomus generate` puts its provenance banner above it.
///
/// ```
/// use majordomus_cli::release::version::{parse_projection, render_projection};
/// assert_eq!(render_projection("0.9.0"), "version=0.9.0\n");
/// assert_eq!(parse_projection(&render_projection("0.9.0")).as_deref(), Some("0.9.0"));
/// ```
pub fn render_projection(version: &str) -> String {
    format!("version={version}\n")
}

/// The version [`PROJECTION`] states: its first `version=` line, past the `#` banner.
///
/// Exactly what `bin/majordomus` reads at start-up, so the executable and the shell tool
/// cannot disagree about what the file says.
///
/// ```
/// use majordomus_cli::release::version::parse_projection;
/// let file = "# GENERATED FILE — DO NOT EDIT DIRECTLY\n# Generator: majordomus-cli 0.9.0\nversion=0.9.0\n";
/// assert_eq!(parse_projection(file).as_deref(), Some("0.9.0"));
/// // a file that states nothing states no version, and an empty value is not one
/// assert_eq!(parse_projection("# nothing here\n"), None);
/// assert_eq!(parse_projection("version=\n"), None);
/// ```
pub fn parse_projection(text: &str) -> Option<String> {
    text.lines()
        .filter(|l| !l.trim_start().starts_with('#'))
        .find_map(|l| l.strip_prefix("version="))
        .map(|v| v.trim().to_string())
        .filter(|v| !v.is_empty())
}

/// The version the shell tool prints: what [`PROJECTION`] states.
///
/// ```
/// use majordomus_cli::release::version::{tool, PROJECTION};
/// let dir = tempfile::tempdir().unwrap();
/// assert_eq!(tool(dir.path()), None, "no projection, no version");
/// std::fs::create_dir_all(dir.path().join("share")).unwrap();
/// std::fs::write(dir.path().join(PROJECTION), "version=0.9.0\n").unwrap();
/// assert_eq!(tool(dir.path()).as_deref(), Some("0.9.0"));
/// ```
pub fn tool(root: &Path) -> Option<String> {
    parse_projection(&std::fs::read_to_string(root.join(PROJECTION)).ok()?)
}

/// How [`PROJECTION`] stands against the authority.
///
/// Three answers that lead to three different actions: nothing to do, run the derivation,
/// or find out who wrote a version nobody authored.
///
/// ```
/// use majordomus_cli::release::version::ProjectionState;
/// let stale = ProjectionState::Stale { projected: Some("0.8.0".into()), declared: "0.9.0".into() };
/// // the state every bump leaves behind is not the state nothing could have produced
/// assert_ne!(stale, ProjectionState::Disagrees { projected: "0.8.0".into(), declared: Some("0.9.0".into()) });
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProjectionState {
    /// Neither the manifest nor the projection is here: this repository does not carry the
    /// product, so there is nothing to project and nothing to compare.
    NotHere,
    /// The projection states the version the manifest declares.
    Current,
    /// The projection is missing, or states an older version than the manifest: the state
    /// between `release bump` and the derivation that follows it. `generate` fixes it.
    Stale {
        /// What the projection states, when it states anything.
        projected: Option<String>,
        /// What the manifest declares.
        declared: String,
    },
    /// The projection states a version newer than the manifest's, or one that cannot be
    /// compared with it, or there is a projection and no manifest. No derivation writes
    /// that, so somebody did.
    Disagrees {
        /// What the projection states.
        projected: String,
        /// What the manifest declares, when there is one.
        declared: Option<String>,
    },
}

/// How [`PROJECTION`] stands against [`MANIFEST`]: compared as versions, so that a projection
/// behind the manifest — what a bump leaves until the derivation runs — is told apart from
/// one ahead of it or unrelated to it, which no derivation ever writes.
///
/// ```
/// use majordomus_cli::release::version::{projection_state, ProjectionState, MANIFEST, PROJECTION};
/// let dir = tempfile::tempdir().unwrap();
/// let root = dir.path();
/// assert_eq!(projection_state(root), ProjectionState::NotHere);
/// std::fs::create_dir_all(root.join("apps/majordomus-cli")).unwrap();
/// std::fs::create_dir_all(root.join("share")).unwrap();
/// std::fs::write(root.join(MANIFEST), "[package]\nversion = \"0.9.0\"\n").unwrap();
/// // raised and not yet derived: stale, which a derivation fixes
/// std::fs::write(root.join(PROJECTION), "version=0.8.0\n").unwrap();
/// assert!(matches!(projection_state(root), ProjectionState::Stale { .. }));
/// // a version the manifest never declared: nothing derives that
/// std::fs::write(root.join(PROJECTION), "version=1.0.0\n").unwrap();
/// assert!(matches!(projection_state(root), ProjectionState::Disagrees { .. }));
/// std::fs::write(root.join(PROJECTION), "version=0.9.0\n").unwrap();
/// assert_eq!(projection_state(root), ProjectionState::Current);
/// ```
pub fn projection_state(root: &Path) -> ProjectionState {
    match (declared(root), tool(root)) {
        (None, None) => ProjectionState::NotHere,
        (None, Some(projected)) => ProjectionState::Disagrees {
            projected,
            declared: None,
        },
        (Some(declared), None) => ProjectionState::Stale {
            projected: None,
            declared,
        },
        (Some(declared), Some(projected)) if declared == projected => ProjectionState::Current,
        (Some(declared), Some(projected)) => {
            match (Version::parse(&projected), Version::parse(&declared)) {
                (Some(p), Some(d)) if p < d => ProjectionState::Stale {
                    projected: Some(projected),
                    declared,
                },
                _ => ProjectionState::Disagrees {
                    projected,
                    declared: Some(declared),
                },
            }
        }
    }
}

/// Whether [`PROJECTION`] states what [`MANIFEST`] declares — the one comparison every
/// surface reports as `agree`.
///
/// ```
/// use majordomus_cli::release::version::projection_current;
/// let dir = tempfile::tempdir().unwrap();
/// // a repository that carries neither has nothing out of step
/// assert!(projection_current(dir.path()));
/// ```
pub fn projection_current(root: &Path) -> bool {
    matches!(
        projection_state(root),
        ProjectionState::Current | ProjectionState::NotHere
    )
}

/// One version written down by hand where the tool's own files live.
///
/// Where it is, to the line, and the shape it was written in — enough for the diagnostic to
/// name the edit that removes it.
///
/// ```
/// use majordomus_cli::release::version::{carrier_shape, Carrier};
/// let line = "FOO_VERSION=\"1.2.3\"";
/// let found = Carrier { path: "lib/x.sh".into(), line: 2, shape: carrier_shape(line).unwrap(), text: line.into() };
/// assert_eq!(found.shape, "an assignment to a version name");
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Carrier {
    /// Repository-relative path.
    pub path: String,
    /// One-based line number.
    pub line: usize,
    /// The shape the version was written in.
    pub shape: &'static str,
    /// The line, trimmed.
    pub text: String,
}

/// The shape a line states a version in, when it states one.
///
/// Three shapes, each a place a version is *declared* rather than mentioned:
///
/// - an assignment to a name ending in `version`, in any case and in the languages the
///   tool's files are written in: shell `MJ_VERSION="0.8.0"` and `export FOO_VERSION=1.2.3`,
///   TOML `version = "1.2.3"`, JavaScript `const VERSION = '1.2.3'`, Python
///   `__version__ = "1.2.3"`;
/// - a `version` member of YAML or JSON at the start of a line: `version: 1.2.3`,
///   `"version": "1.2.3"`;
/// - the product's own answer to `version`: `majordomus 0.8.0`.
///
/// A version is three numbers, optionally after a `v`; a schema's `version: 1` is not one.
///
/// ```
/// use majordomus_cli::release::version::carrier_shape;
/// assert!(carrier_shape("MJ_VERSION=\"0.8.0\"").is_some());
/// assert!(carrier_shape("  export FOO_VERSION=v1.2.3").is_some());
/// assert!(carrier_shape("declare -r MJ_VERSION=\"1.2.3\"").is_some());
/// assert!(carrier_shape("version = \"1.2.3\"").is_some());
/// assert!(carrier_shape("export const VERSION = '1.2.3';").is_some());
/// assert!(carrier_shape("let appVersion = `1.2.3`;").is_some());
/// assert!(carrier_shape("__version__ = \"1.2.3\"").is_some());
/// assert!(carrier_shape("version: 1.2.3").is_some());
/// assert!(carrier_shape("  \"version\": \"1.2.3\",").is_some());
/// assert!(carrier_shape("echo \"majordomus 0.8.0\"").is_some());
/// // read, not stated: a variable, a schema version, a generator stamp, a sentinel, a
/// // comparison, a property of something else
/// assert!(carrier_shape("MJ_VERSION=\"${line#version=}\"").is_none());
/// assert!(carrier_shape("version: 1").is_none());
/// assert!(carrier_shape("# Generator: majordomus-cli 0.8.0").is_none());
/// assert!(carrier_shape("MJ_VERSION=\"site\"").is_none());
/// assert!(carrier_shape("version == \"1.2.3\"").is_none());
/// assert!(carrier_shape("pkg.version = \"1.2.3\"").is_none());
/// assert!(carrier_shape("versioned = \"1.2.3\"").is_none());
/// ```
pub fn carrier_shape(line: &str) -> Option<&'static str> {
    let t = line.trim_start();

    // an assignment to a name ending in `version`, once the words that declare it are set aside
    if let Some((name, value)) = declared_name(t).split_once('=') {
        let name = name.trim_end();
        let is_version_name = !name.is_empty()
            && name
                .chars()
                .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '$')
            && name
                .trim_matches('_')
                .to_ascii_lowercase()
                .ends_with("version");
        let value = value.trim_start().trim_start_matches(['"', '\'', '`']);
        if is_version_name && leads_with_version(value) {
            return Some("an assignment to a version name");
        }
    }

    // a `version` member of YAML or JSON, at the start of a line or of a list item
    let member = t.strip_prefix("- ").unwrap_or(t);
    let after_key = member
        .strip_prefix("\"version\"")
        .or_else(|| member.strip_prefix("'version'"))
        .or_else(|| member.strip_prefix("version"));
    if let Some(rest) = after_key {
        if let Some(value) = rest.trim_start().strip_prefix(':') {
            if leads_with_version(value.trim_start().trim_start_matches(['"', '\''])) {
                return Some("a version member");
            }
        }
    }

    // the product's own answer to `majordomus version`
    const PRODUCT: &str = "majordomus ";
    for (at, _) in t.match_indices(PRODUCT) {
        let before = t[..at].chars().next_back();
        let joined = before.is_some_and(|c| c.is_ascii_alphanumeric() || "-_./".contains(c));
        if !joined && leads_with_version(&t[at + PRODUCT.len()..]) {
            return Some("the product's version line");
        }
    }
    None
}

/// A line with the words that declare a name set aside — `export`, `readonly`, `local`,
/// `declare` and `typeset` with their flags, `const`, `let`, `var` — so that what is left
/// begins with the name being assigned.
fn declared_name(mut t: &str) -> &str {
    const DECLARING: &[&str] = &[
        "export", "readonly", "local", "declare", "typeset", "const", "let", "var",
    ];
    const TAKES_FLAGS: &[&str] = &["export", "readonly", "local", "declare", "typeset"];
    while let Some((word, rest)) = t.split_once(char::is_whitespace) {
        if !DECLARING.contains(&word) {
            break;
        }
        t = rest.trim_start();
        if TAKES_FLAGS.contains(&word) {
            while let Some((flag, rest)) = t.split_once(char::is_whitespace) {
                if flag.len() > 1 && flag.starts_with('-') && !flag.contains('=') {
                    t = rest.trim_start();
                } else {
                    break;
                }
            }
        }
    }
    t
}

/// Whether `text` begins with a version: three dot-separated numbers, optionally after a
/// `v`, and not followed by a fourth.
fn leads_with_version(text: &str) -> bool {
    let bytes = text.strip_prefix('v').unwrap_or(text).as_bytes();
    let mut at = 0;
    for group in 0..3 {
        let start = at;
        while at < bytes.len() && bytes[at].is_ascii_digit() {
            at += 1;
        }
        if at == start {
            return false;
        }
        if group < 2 {
            if bytes.get(at) != Some(&b'.') {
                return false;
            }
            at += 1;
        }
    }
    !matches!(bytes.get(at), Some(b) if *b == b'.' || b.is_ascii_digit())
}

/// Every version written down by hand under [`CARRIER_ROOTS`].
///
/// The files git would commit there — tracked, or new and not ignored, so a file is refused
/// before it is staged rather than after — or, where this is not a git checkout, every file
/// under those directories, so that a tree nobody committed is still read rather than
/// passed. [`PROJECTION`] is not a statement by hand, and neither is any path the generated
/// artifact manifest names: `majordomus generate` wrote those, and `generate --check` is
/// what holds them.
///
/// ```
/// use majordomus_cli::release::version::carriers;
/// let dir = tempfile::tempdir().unwrap();
/// std::fs::create_dir_all(dir.path().join("lib")).unwrap();
/// std::fs::write(dir.path().join("lib/x.sh"), "FOO_VERSION=\"1.2.3\"\n").unwrap();
/// let found = carriers(dir.path());
/// assert_eq!(found.len(), 1);
/// assert_eq!((found[0].path.as_str(), found[0].line), ("lib/x.sh", 1));
/// ```
pub fn carriers(root: &Path) -> Vec<Carrier> {
    let files = committable(root).unwrap_or_else(|| walk(root, CARRIER_ROOTS));
    let generated = generated_paths(root);
    let mut out = Vec::new();
    for path in files {
        if path == PROJECTION || generated.contains(&path) {
            continue;
        }
        let full = root.join(&path);
        let small =
            std::fs::symlink_metadata(&full).is_ok_and(|m| m.is_file() && m.len() <= LARGEST_READ);
        if !small {
            continue;
        }
        let Ok(text) = std::fs::read_to_string(&full) else {
            continue;
        };
        for (i, line) in text.lines().enumerate() {
            if let Some(shape) = carrier_shape(line) {
                out.push(Carrier {
                    path: path.clone(),
                    line: i + 1,
                    shape,
                    text: line.trim().to_string(),
                });
            }
        }
    }
    out
}

/// The files under [`CARRIER_ROOTS`] git would commit: tracked, or untracked and not
/// ignored. `None` when git cannot answer, which is not the same as "no files".
fn committable(root: &Path) -> Option<Vec<String>> {
    let out = crate::git::read_only(root)
        .args([
            "ls-files",
            "-z",
            "--cached",
            "--others",
            "--exclude-standard",
            "--",
        ])
        .args(CARRIER_ROOTS)
        .output()
        .ok()?;
    if !out.status.success() {
        return None;
    }
    let mut files: Vec<String> = out
        .stdout
        .split(|b| *b == 0)
        .filter(|s| !s.is_empty())
        .map(|s| String::from_utf8_lossy(s).into_owned())
        .collect();
    crate::order::canonical_strings(&mut files);
    files.dedup();
    Some(files)
}

/// Every file under `roots` — directories walked, files taken as they are —
/// repository-relative, in a stable order: the answer when git cannot list them.
fn walk(root: &Path, roots: &[&str]) -> Vec<String> {
    fn visit(dir: &Path, root: &Path, out: &mut Vec<String>) {
        let Ok(entries) = std::fs::read_dir(dir) else {
            return;
        };
        for entry in entries.flatten() {
            let path = entry.path();
            match entry.file_type() {
                Ok(t) if t.is_dir() => visit(&path, root, out),
                Ok(t) if t.is_file() => {
                    if let Ok(rel) = path.strip_prefix(root) {
                        out.push(rel.to_string_lossy().replace('\\', "/"));
                    }
                }
                _ => {}
            }
        }
    }
    let mut out = Vec::new();
    for dir in roots {
        let full = root.join(dir);
        if full.is_file() {
            out.push((*dir).to_string());
        } else {
            visit(&full, root, &mut out);
        }
    }
    crate::order::canonical_strings(&mut out);
    out
}

/// The paths the committed generated-artifact manifest names.
fn generated_paths(root: &Path) -> BTreeSet<String> {
    std::fs::read_to_string(root.join(GENERATED_MANIFEST))
        .ok()
        .and_then(|t| serde_json::from_str::<serde_json::Value>(&t).ok())
        .and_then(|v| v.get("artifacts").and_then(|a| a.as_array()).cloned())
        .unwrap_or_default()
        .iter()
        .filter_map(|a| a.get("path").and_then(|p| p.as_str()).map(str::to_string))
        .collect()
}

/// Every version label on a line: `v`, a major and a minor, and no patch — `v0.1`, `v1.2`.
///
/// A release is always three numbers (`v0.3.1`), so a label of two names no release: it
/// names the version a text was written about, and it stays where it was typed while the
/// version moves on. A label joined to a word, a path or a URL is not one, and neither is a
/// three-part version or a schema's `version: 1`.
///
/// ```
/// use majordomus_cli::release::version::version_labels;
/// assert_eq!(version_labels("What v0.1 does not do"), ["v0.1"]);
/// assert_eq!(version_labels("(v1.12), and v2.0."), ["v1.12", "v2.0"]);
/// assert!(version_labels("Release `v0.3.1` was published").is_empty());
/// assert!(version_labels("see /releases/v0.1.json and api-v0.1").is_empty());
/// assert!(version_labels("rule v2, schema version: 1, dev0.1").is_empty());
/// assert!(version_labels("v0.1.0 and v0.1x").is_empty());
/// ```
pub fn version_labels(line: &str) -> Vec<String> {
    let bytes = line.as_bytes();
    let joined = |b: u8| b.is_ascii_alphanumeric() || b"./_-".contains(&b);
    let digits = |mut at: usize| {
        while at < bytes.len() && bytes[at].is_ascii_digit() {
            at += 1;
        }
        at
    };
    let mut out = Vec::new();
    for (at, _) in line.match_indices('v') {
        if at > 0 && joined(bytes[at - 1]) {
            continue;
        }
        let major = digits(at + 1);
        if major == at + 1 || bytes.get(major) != Some(&b'.') {
            continue;
        }
        let minor = digits(major + 1);
        if minor == major + 1 {
            continue;
        }
        let patch =
            bytes.get(minor) == Some(&b'.') && bytes.get(minor + 1).is_some_and(u8::is_ascii_digit);
        let glued = bytes
            .get(minor)
            .is_some_and(|b| b.is_ascii_alphanumeric() || b"_-".contains(b));
        if !patch && !glued {
            out.push(line[at..minor].to_string());
        }
    }
    out
}

/// The tracked hand-written prose: documents, the site's authored pages and data, its
/// templates, the layer's own documents and the provider templates.
///
/// Generated files are not prose anybody wrote — a label in one comes from its source, and
/// the source is where it is found — so a path the generated-artifact manifest names, a
/// file stamped by its generator, and a page under `site/content/` that the site generator
/// projects from `site/content-src/` or writes into a subdirectory are all left out. The
/// layer's dated records ([`PROSE_RECORDS`]) are left out too. Where git cannot list the
/// tree — not a checkout — every file under the roots is read instead, as [`carriers`]
/// does, so a tree nobody committed is still read rather than passed.
fn prose_files(root: &Path) -> Vec<String> {
    let listed =
        crate::git::ls_files_any(root, PROSE_ROOTS).unwrap_or_else(|_| walk(root, PROSE_ROOTS));
    let generated = generated_paths(root);
    let prose = |p: &str| match p {
        "README.md" | "AGENTS.md" | "CLAUDE.md" => true,
        _ if PROSE_RECORDS.iter().any(|r| p.starts_with(r)) => false,
        _ if p.starts_with("site/content/") => {
            let name = &p["site/content/".len()..];
            p.ends_with(".md")
                && !name.contains('/')
                && !root.join("site/content-src").join(name).exists()
        }
        _ if p.starts_with("site/data/") => {
            p.ends_with(".toml") && !p["site/data/".len()..].contains('/')
        }
        _ if p.starts_with("share/providers/") || p.starts_with(".ai/repo/providers/") => {
            p.ends_with(".tmpl")
        }
        _ if p.starts_with("site/templates/") => true,
        _ => p.ends_with(".md"),
    };
    listed
        .into_iter()
        .filter(|p| prose(p) && !generated.contains(p))
        .collect()
}

/// A file's text when it is hand-written and small enough to be prose; `None` for one that
/// is missing, binary, oversized or stamped by its generator on its first line.
fn authored_text(root: &Path, path: &str) -> Option<String> {
    const STAMPS: &[&str] = &[
        "<!-- generated by",
        "<!-- GENERATED FILE",
        "# GENERATED FILE",
        "// GENERATED FILE",
    ];
    let full = root.join(path);
    let small =
        std::fs::symlink_metadata(&full).is_ok_and(|m| m.is_file() && m.len() <= LARGEST_READ);
    let text = std::fs::read_to_string(&full).ok().filter(|_| small)?;
    let first = text
        .lines()
        .next()
        .unwrap_or("")
        .trim_start_matches('\u{feff}');
    (!STAMPS.iter().any(|s| first.trim_start().starts_with(s))).then_some(text)
}

/// The entries of [`LABEL_HISTORY`] as `(line, path, reason)`; an absent file declares none.
fn label_history(root: &Path) -> Vec<(usize, String, String)> {
    let text = std::fs::read_to_string(root.join(LABEL_HISTORY)).unwrap_or_default();
    text.lines()
        .enumerate()
        .filter(|(_, l)| !l.trim().is_empty() && !l.trim_start().starts_with('#'))
        .map(|(i, l)| {
            let l = l.trim();
            let (path, reason) = l.split_once(char::is_whitespace).unwrap_or((l, ""));
            (i + 1, path.to_string(), reason.trim().to_string())
        })
        .collect()
}

/// Every version label typed into hand-written prose outside a declared history, and every
/// history entry that cannot be honoured.
///
/// The label is the finding, not the version: `v0.1` on a page that describes the tool as
/// it stands was true the day it was typed and is wrong the day after the next release,
/// while nothing that derives the version can reach it. A document that is *about* a past
/// version names it in [`LABEL_HISTORY`] with a reason. That list is held from both sides:
/// an entry with no reason, one naming a path that is not tracked prose, and one whose
/// document no longer carries a label are each refused, so the list cannot outlive what it
/// exempts.
///
/// ```
/// use majordomus_cli::release::version::{label_diagnostics, LABEL_HISTORY};
/// use std::process::Command;
/// let dir = tempfile::tempdir().unwrap();
/// let root = dir.path();
/// std::fs::create_dir_all(root.join("docs")).unwrap();
/// std::fs::create_dir_all(root.join(".ai/repo")).unwrap();
/// std::fs::write(root.join("README.md"), "What v0.1 does not do.\nRelease v0.3.1 shipped.\n").unwrap();
/// std::fs::write(root.join("docs/DESIGN.md"), "The v0.1 specification.\n").unwrap();
/// std::fs::write(root.join(LABEL_HISTORY), "docs/DESIGN.md the design phase, dated\n").unwrap();
/// let git = |a: &[&str]| {
///     Command::new("git")
///         .env_remove("GIT_DIR").env_remove("GIT_WORK_TREE").env_remove("GIT_INDEX_FILE")
///         .arg("-C").arg(root).args(a).output().unwrap()
/// };
/// git(&["init", "-q"]);
/// git(&["add", "-A"]);
/// let found = label_diagnostics(root);
/// assert_eq!(found.len(), 1, "{found:?}");
/// assert!(found[0].message.starts_with("README.md:1 "), "{}", found[0].message);
///
/// std::fs::write(root.join("docs/DESIGN.md"), "The founding specification.\n").unwrap();
/// let found = label_diagnostics(root);
/// assert_eq!(found[1].id, "version-label-history-invalid", "an exemption outliving its label");
/// ```
pub fn label_diagnostics(root: &Path) -> Vec<Diagnostic> {
    let error = |id: &str, message: String| Diagnostic {
        id: id.into(),
        severity: Severity::Error,
        message,
    };
    let files = prose_files(root);
    let history = label_history(root);
    let exempt: BTreeSet<&str> = history
        .iter()
        .filter(|(_, _, reason)| !reason.is_empty())
        .map(|(_, path, _)| path.as_str())
        .collect();
    let mut out = Vec::new();
    let mut labelled = BTreeSet::new();
    for path in &files {
        let Some(text) = authored_text(root, path) else {
            continue;
        };
        for (i, line) in text.lines().enumerate() {
            let labels = version_labels(line);
            if labels.is_empty() {
                continue;
            }
            labelled.insert(path.as_str());
            if exempt.contains(path.as_str()) {
                continue;
            }
            for label in labels {
                out.push(error(
                    LABEL_IN_PROSE,
                    format!(
                        "{path}:{} names the version it describes as `{label}`: the label \
                         stays while the version moves. Say what is true of the tool as it \
                         stands, without a version; a document about a past version is \
                         declared in {LABEL_HISTORY} with its reason",
                        i + 1
                    ),
                ));
            }
        }
    }
    for (line, path, reason) in &history {
        let at = format!("{LABEL_HISTORY}:{line}");
        if reason.is_empty() {
            out.push(error(
                LABEL_HISTORY_INVALID,
                format!("{at} exempts {path} and says nothing about why: an exemption states its reason"),
            ));
        } else if !files.iter().any(|f| f == path) {
            out.push(error(
                LABEL_HISTORY_INVALID,
                format!("{at} exempts {path}, which is not tracked hand-written prose: remove the entry"),
            ));
        } else if !labelled.contains(path.as_str()) {
            out.push(error(
                LABEL_HISTORY_INVALID,
                format!(
                    "{at} exempts {path}, which names no version label any more: remove the entry"
                ),
            ));
        }
    }
    out
}

/// Everything wrong with where the version is stated: the projection against the
/// authority, and every version written down by hand where the tool's own files live.
///
/// A stale projection is a [`Severity::Warning`] — it is the state every bump leaves until
/// `scripts/derive` runs, `generate --check` is what refuses it, and a writer that refused
/// its own un-derived state could not correct a bump it had just made. A projection nothing
/// could have derived, and a version written by hand, are [`Severity::Error`]s. Asked only
/// where the product lives: a repository without the crate has its own `scripts/` and its
/// own versions, and they are none of this module's business.
///
/// ```
/// use majordomus_cli::release::compat::Severity;
/// use majordomus_cli::release::version::{diagnose, MANIFEST, PROJECTION};
/// let dir = tempfile::tempdir().unwrap();
/// let root = dir.path();
/// std::fs::create_dir_all(root.join("apps/majordomus-cli")).unwrap();
/// std::fs::create_dir_all(root.join("share")).unwrap();
/// std::fs::create_dir_all(root.join("lib")).unwrap();
/// std::fs::write(root.join(MANIFEST), "[package]\nversion = \"0.9.0\"\n").unwrap();
/// std::fs::write(root.join(PROJECTION), "version=0.9.0\n").unwrap();
/// assert!(diagnose(root).is_empty(), "authored once, projected once");
///
/// std::fs::write(root.join("lib/x.sh"), "FOO_VERSION=\"1.2.3\"\n").unwrap();
/// let found = diagnose(root);
/// assert_eq!(found.len(), 1);
/// assert_eq!(found[0].id, "version-stated-by-hand");
/// assert_eq!(found[0].severity, Severity::Error);
/// ```
pub fn diagnose(root: &Path) -> Vec<Diagnostic> {
    let mut out = Vec::new();
    match projection_state(root) {
        ProjectionState::NotHere | ProjectionState::Current => {}
        ProjectionState::Stale {
            projected,
            declared,
        } => out.push(Diagnostic {
            id: PROJECTION_STALE.into(),
            severity: Severity::Warning,
            message: format!(
                "{PROJECTION} states '{}' and {MANIFEST} declares '{declared}': the projection \
                 is stale — run scripts/derive, which builds and then generates it; never edit \
                 it or bin/majordomus",
                projected.as_deref().unwrap_or("nothing")
            ),
        }),
        ProjectionState::Disagrees {
            projected,
            declared,
        } => out.push(Diagnostic {
            id: WRITERS_DISAGREE.into(),
            severity: Severity::Error,
            message: format!(
                "{PROJECTION} states '{projected}' and {MANIFEST} declares '{}': no derivation \
                 writes a version the manifest does not declare, so it was written by hand — \
                 run scripts/derive, and raise the version only with `majordomus release bump`",
                declared.as_deref().unwrap_or("nothing")
            ),
        }),
    }
    if root.join(MANIFEST).is_file() {
        for c in carriers(root) {
            out.push(Diagnostic {
                id: STATED_BY_HAND.into(),
                severity: Severity::Error,
                message: format!(
                    "{}:{} states a version by hand, as {}: `{}`. The version is authored \
                     only in {MANIFEST}; read it with `scripts/release-version` in shell, \
                     `release::version::declared` in Rust, or `bin/majordomus version`",
                    c.path, c.line, c.shape, c.text
                ),
            });
        }
        out.extend(label_diagnostics(root));
    }
    out
}

/// Write `to` into the one place the version is authored, keep the lock's record of it in
/// step, and say which files changed.
///
/// Byte-exact and narrow: the manifest's `version` line inside `[package]`, and the `version`
/// line of the lock's own `majordomus-cli` entry — the one line cargo would rewrite. Nothing
/// else in either file is read or rewritten, so a dependency at the same version is
/// untouched. [`PROJECTION`], the generator stamps and the changelog are not written here:
/// they are derived, and `scripts/derive` derives them.
///
/// ```
/// use majordomus_cli::release::version::{declared, write, MANIFEST};
/// let dir = tempfile::tempdir().unwrap();
/// std::fs::create_dir_all(dir.path().join("apps/majordomus-cli")).unwrap();
/// std::fs::write(dir.path().join(MANIFEST), "[package]\nversion = \"0.8.0\"\n").unwrap();
/// assert_eq!(write(dir.path(), "0.9.0").unwrap(), vec![MANIFEST.to_string()]);
/// assert_eq!(declared(dir.path()).as_deref(), Some("0.9.0"));
/// ```
pub fn write(root: &Path, to: &str) -> std::io::Result<Vec<String>> {
    let mut written = Vec::new();

    let manifest = root.join(MANIFEST);
    let text = std::fs::read_to_string(&manifest)?;
    let mut out = String::with_capacity(text.len());
    let mut in_package = false;
    let mut done = false;
    for line in text.lines() {
        let trimmed = line.trim();
        if trimmed.starts_with('[') {
            in_package = trimmed == "[package]";
        }
        if in_package && !done && trimmed.starts_with("version") && trimmed.contains('"') {
            out.push_str(&format!("version = \"{to}\"\n"));
            done = true;
            continue;
        }
        out.push_str(line);
        out.push('\n');
    }
    if out != text {
        std::fs::write(&manifest, out)?;
        written.push(MANIFEST.to_string());
    }

    // The lock's own entry, and only it: the `version` line that follows
    // `name = "majordomus-cli"`. Every other `version` in the file belongs to a dependency.
    let lock = root.join(LOCK);
    if let Ok(text) = std::fs::read_to_string(&lock) {
        let mut out = String::with_capacity(text.len());
        let mut here = false;
        let mut done = false;
        for line in text.lines() {
            let trimmed = line.trim();
            if trimmed == "[[package]]" {
                here = false;
            } else if trimmed == "name = \"majordomus-cli\"" {
                here = true;
            } else if here && !done && trimmed.starts_with("version") && trimmed.contains('"') {
                out.push_str(&format!("version = \"{to}\"\n"));
                here = false;
                done = true;
                continue;
            }
            out.push_str(line);
            out.push('\n');
        }
        if out != text {
            std::fs::write(&lock, out)?;
            written.push(LOCK.to_string());
        }
    }

    Ok(written)
}

/// The version the commit subjects imply: the last release raised by their bump — from the
/// declared version only when nothing was released. Evidence, never the answer on its own.
///
/// It raises the last release and not the declared version, because a declared version
/// already raised for the window must not be raised again by the same commits.
///
/// ```
/// use majordomus_cli::release::version::{commits_imply, Bump};
/// // released 0.10.0, already declared 0.11.0, only features since: 0.11.0, not 0.12.0
/// assert_eq!(commits_imply(Some("0.10.0"), "0.11.0", Bump::Minor).as_deref(), Some("0.11.0"));
/// // nothing released: the declared version is the only base there is
/// assert_eq!(commits_imply(None, "0.3.0", Bump::Patch).as_deref(), Some("0.3.1"));
/// ```
pub fn commits_imply(last: Option<&str>, declared: &str, bump: Bump) -> Option<String> {
    last.and_then(Version::parse)
        .or_else(|| Version::parse(declared))
        .map(|v| v.raised(bump).to_string())
}

/// Who answers `next`, and with what: the contract when it could be measured, and no one
/// when it could not.
///
/// `contract` is the analysis' measured version ([`crate::release::compat::VersionPlan::
/// measured_version`]), or why none could be measured. ADR 0051 refuses an unmeasurable
/// baseline rather than guessing one, so an `Err` leaves `next` absent, [`DecidedBy::
/// Undecided`] and the reason carried — the commit inference stays evidence beside it and
/// never stands in for the measurement. The contract's answer is a minimum: when it is no
/// greater than `last` — only behaviour behind the public boundary changed, so the contract
/// requires no release — it is the release already made, never the next one. Then the
/// commits decide whether anything is released at all, and the contract decides how much:
/// the smallest release above the last, a patch, labelled [`DecidedBy::ContractAndCommits`].
/// The commits never raise `next` beyond what the contract requires.
///
/// ```
/// use majordomus_cli::release::model::DecidedBy;
/// use majordomus_cli::release::version::{decide, Bump};
/// // the commits say BREAKING, the contract only grew: below 1.0 that owes a minor
/// let (next, by, why) = decide(Some("0.10.0"), Bump::Major, Ok("0.11.0".into()));
/// assert_eq!((next.as_deref(), by, why), (Some("0.11.0"), DecidedBy::Contract, None));
/// // only fixes, the surface unchanged: the contract's minimum is the release already made
/// let (next, by, _) = decide(Some("0.10.0"), Bump::Patch, Ok("0.10.0".into()));
/// assert_eq!((next.as_deref(), by), (Some("0.10.1"), DecidedBy::ContractAndCommits));
/// // no published baseline: no one decides, and the reason is carried
/// let (next, by, why) = decide(None, Bump::Minor, Err("no release".into()));
/// assert_eq!((next, by), (None, DecidedBy::Undecided));
/// assert_eq!(why.as_deref(), Some("no release"));
/// ```
pub fn decide(
    last: Option<&str>,
    bump: Bump,
    contract: Result<String, String>,
) -> (Option<String>, DecidedBy, Option<String>) {
    let required = match contract {
        Ok(required) => required,
        Err(why) => return (None, DecidedBy::Undecided, Some(why)),
    };
    match (Version::parse(&required), last.and_then(Version::parse)) {
        (Some(r), Some(l)) if r <= l => match bump {
            Bump::None => (None, DecidedBy::Contract, None),
            _ => (
                Some(l.raised(Bump::Patch).to_string()),
                DecidedBy::ContractAndCommits,
                None,
            ),
        },
        _ => (Some(required), DecidedBy::Contract, None),
    }
}

/// The whole version answer: what is declared, whether the projection the shell tool reads
/// states it, what the public contract requires next, and what the commits since the last
/// release imply — as evidence.
///
/// `contract` is the analysis' answer ([`decide`] says how it is used); [`select`] is the
/// caller that asks it, and the one every surface goes through. The last release is
/// [`crate::release::compat::last_release`] — the same baseline `release analyze` measures
/// from, the highest version the layer records — so the contract and the commit evidence
/// always measure one window. The commit inference raises that release ([`commits_imply`]).
pub fn report(root: &Path, objects: &[Object], contract: Result<String, String>) -> VersionReport {
    let declared = declared(root).unwrap_or_else(|| "unknown".into());
    let tool_version = tool(root).unwrap_or_else(|| "unknown".into());

    let last = super::compat::last_release(root, objects);
    let changes = match &last {
        Some(l) => super::commits::in_range(root, &format!("{}..HEAD", l.read_at), objects),
        None => super::commits::in_range(root, "HEAD", objects),
    };
    let bump = bump_of(&changes);
    let last_version = last.map(|l| l.version);
    let commits_imply = commits_imply(last_version.as_deref(), &declared, bump);
    let (next, decided_by, contract_unreadable) = decide(last_version.as_deref(), bump, contract);

    VersionReport {
        agree: projection_current(root),
        declared,
        tool: tool_version,
        last_release: last_version,
        bump: bump.as_str().to_string(),
        commits_imply,
        next,
        decided_by,
        contract_unreadable,
        changes,
    }
}

/// The release selection: the contract's analysis against the last release, and the version
/// report decided from it — made once, by one function.
///
/// `release version` (the capability, and every surface that renders it) and `release bump`
/// without an explicit target both take their answer from here, so the report and the writer
/// cannot disagree about what the next version is: the report's `next` is the version the
/// writer raises to ([`default_target`]).
///
/// ```
/// use majordomus_cli::capability::registry::CapabilityRegistry;
/// use majordomus_cli::release::model::DecidedBy;
/// use majordomus_cli::release::version::{select, Selection};
/// let dir = tempfile::tempdir().unwrap();
/// let registry = CapabilityRegistry::builder().build().unwrap();
/// let selection: Selection = select(dir.path(), &registry, &[]);
/// // nothing published: no plan, and so a report that decides nothing — with the same reason
/// let why = selection.plan.as_ref().unwrap_err();
/// assert_eq!(selection.report.decided_by, DecidedBy::Undecided);
/// assert_eq!(selection.report.contract_unreadable.as_ref(), Some(why));
/// assert_eq!(selection.report.next, None);
/// ```
#[derive(Debug)]
pub struct Selection {
    /// The analysis `release analyze` makes against the last release, or why it could not be
    /// made at all (no release to compare with, a baseline whose registry is not committed).
    pub plan: Result<super::compat::VersionPlan, String>,
    /// The version report decided from that analysis.
    pub report: VersionReport,
}

/// Make the release selection ([`Selection`]): analyse the contract against the last
/// release, refuse a guess ([`crate::release::compat::VersionPlan::measured_version`]), and
/// decide the report from what is left ([`report`]).
///
/// ```
/// use majordomus_cli::capability::registry::CapabilityRegistry;
/// use majordomus_cli::release::version::{default_target, select, Version};
/// let dir = tempfile::tempdir().unwrap();
/// let registry = CapabilityRegistry::builder().build().unwrap();
/// let selection = select(dir.path(), &registry, &[]);
/// // the writer's default target is read from this report, so it refuses with its reason
/// let current = Version::parse("0.1.0").unwrap();
/// assert_eq!(
///     default_target(&selection.report, current).unwrap_err(),
///     selection.report.contract_unreadable.clone().unwrap()
/// );
/// ```
pub fn select(
    root: &Path,
    registry: &crate::capability::registry::CapabilityRegistry,
    objects: &[Object],
) -> Selection {
    let plan = super::compat::analyze(root, registry, objects, None).map_err(|e| e.to_string());
    let contract = match &plan {
        Ok(p) => p.measured_version(),
        Err(why) => Err(why.clone()),
    };
    Selection {
        report: report(root, objects, contract),
        plan,
    }
}

/// The version `release bump` raises to when no target is named: the report's `next`, the
/// declared version when nothing would be released — and a refusal, with the report's
/// reason, when the contract could not be measured and so no one decided.
///
/// ```
/// use majordomus_cli::release::model::{DecidedBy, VersionReport};
/// use majordomus_cli::release::version::{default_target, Version};
/// let report = |next: Option<&str>, decided_by, why: Option<&str>| VersionReport {
///     declared: "0.11.0".into(), tool: "0.11.0".into(), agree: true,
///     last_release: Some("0.11.0".into()), bump: "patch".into(),
///     commits_imply: Some("0.11.1".into()), next: next.map(Into::into), decided_by,
///     contract_unreadable: why.map(Into::into), changes: Vec::new() };
/// let current = Version::parse("0.11.0").unwrap();
/// let fix = report(Some("0.11.1"), DecidedBy::ContractAndCommits, None);
/// assert_eq!(default_target(&fix, current).unwrap().to_string(), "0.11.1");
/// let nothing = report(None, DecidedBy::Contract, None);
/// assert_eq!(default_target(&nothing, current), Ok(current));
/// let unread = report(None, DecidedBy::Undecided, Some("no release"));
/// assert_eq!(default_target(&unread, current), Err("no release".into()));
/// ```
pub fn default_target(report: &VersionReport, current: Version) -> Result<Version, String> {
    match (&report.next, report.decided_by) {
        (_, DecidedBy::Undecided) => Err(report
            .contract_unreadable
            .clone()
            .unwrap_or_else(|| "the public contract could not be measured".into())),
        (Some(next), _) => Version::parse(next)
            .ok_or_else(|| format!("the selected version '{next}' is not three numbers")),
        (None, _) => Ok(current),
    }
}

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

    fn change(kind: ChangeKind, breaking: bool) -> Change {
        Change {
            kind,
            scope: None,
            subject: "x".into(),
            breaking,
            commit: "abc1234".into(),
            url: None,
            references: Vec::new(),
        }
    }

    #[test]
    fn the_bump_is_a_total_function_of_the_changes() {
        assert_eq!(bump_of(&[]), Bump::None);
        assert_eq!(bump_of(&[change(ChangeKind::Chore, false)]), Bump::Patch);
        assert_eq!(bump_of(&[change(ChangeKind::Fix, false)]), Bump::Patch);
        assert_eq!(
            bump_of(&[
                change(ChangeKind::Fix, false),
                change(ChangeKind::Feat, false)
            ]),
            Bump::Minor
        );
        assert_eq!(
            bump_of(&[
                change(ChangeKind::Feat, false),
                change(ChangeKind::Fix, true)
            ]),
            Bump::Major
        );
    }

    /// ADR 0051: the contract decides `next`, and an unmeasurable contract is refused, not
    /// guessed — `next` is absent, `undecided`, with the reason, whatever the commits say. The
    /// case this was written for: commits saying BREAKING (1.0.0 from 0.10.0) against a
    /// contract that only grew (0.11.0).
    #[test]
    fn the_contract_decides_next_and_an_unreadable_one_decides_nothing() {
        let last = Some("0.10.0");
        assert_eq!(
            decide(last, Bump::Major, Ok("0.11.0".into())),
            (Some("0.11.0".into()), DecidedBy::Contract, None)
        );
        assert_eq!(
            decide(last, Bump::Major, Err("no baseline".into())),
            (None, DecidedBy::Undecided, Some("no baseline".into()))
        );
        assert_eq!(
            decide(None, Bump::None, Err("no baseline".into())),
            (None, DecidedBy::Undecided, Some("no baseline".into()))
        );
    }

    /// The contract's answer is a minimum, and the minimum of an unchanged surface is the
    /// release already made: `next` must never be the last release.
    #[test]
    fn a_contract_that_requires_no_release_never_answers_the_last_one() {
        let last = Some("0.10.0");
        // only fixes: the smallest release above the last, a patch
        assert_eq!(
            decide(last, Bump::Patch, Ok("0.10.0".into())),
            (Some("0.10.1".into()), DecidedBy::ContractAndCommits, None)
        );
        // a feature the contract cannot see is behind the boundary: a patch, not a minor
        assert_eq!(
            decide(last, Bump::Minor, Ok("0.10.0".into())),
            (Some("0.10.1".into()), DecidedBy::ContractAndCommits, None)
        );
        // nothing at all since the last release: nothing to release
        assert_eq!(
            decide(last, Bump::None, Ok("0.10.0".into())),
            (None, DecidedBy::Contract, None)
        );
        // a declared version already above the minimum is the contract's answer as it stands
        assert_eq!(
            decide(last, Bump::Patch, Ok("0.12.0".into())),
            (Some("0.12.0".into()), DecidedBy::Contract, None)
        );
    }

    /// The report and the writer answer one question with one function: whatever `next` the
    /// selection reports, `release bump` with no target raises to exactly that — the two
    /// Codex found apart (report 0.11.1, writer 0.11.0) on an unchanged contract and a fix.
    #[test]
    fn the_report_and_the_writer_select_the_same_version() {
        let current = Version::parse("0.11.0").unwrap();
        let report_of = |last: &str, declared: &str, bump: Bump, contract| {
            let (next, decided_by, contract_unreadable) = decide(Some(last), bump, contract);
            VersionReport {
                declared: declared.into(),
                tool: declared.into(),
                agree: true,
                last_release: Some(last.into()),
                bump: bump.as_str().into(),
                commits_imply: commits_imply(Some(last), declared, bump),
                next,
                decided_by,
                contract_unreadable,
                changes: Vec::new(),
            }
        };
        // released and declared 0.11.0, the contract unchanged, a fix since: 0.11.1 for both
        let fix = report_of("0.11.0", "0.11.0", Bump::Patch, Ok("0.11.0".into()));
        assert_eq!(fix.next.as_deref(), Some("0.11.1"));
        assert_eq!(
            default_target(&fix, current).map(|v| v.to_string()),
            Ok("0.11.1".to_string())
        );
        // released 0.10.0, declared 0.10.0, the contract requires a minor: 0.11.0 for both
        let minor = report_of("0.10.0", "0.10.0", Bump::Major, Ok("0.11.0".into()));
        assert_eq!(minor.next.as_deref(), Some("0.11.0"));
        assert_eq!(
            default_target(&minor, Version::parse("0.10.0").unwrap()).map(|v| v.to_string()),
            Ok("0.11.0".to_string())
        );
        // the contract unreadable: the report decides nothing and the writer refuses, with
        // the report's reason — the commit inference answers neither
        let unread = report_of("0.10.0", "0.10.0", Bump::Major, Err("no baseline".into()));
        assert_eq!(unread.next, None);
        assert_eq!(unread.commits_imply.as_deref(), Some("1.0.0"));
        assert_eq!(
            default_target(&unread, current),
            Err("no baseline".to_string())
        );
    }

    /// The commit inference raises the last release, not the declared version — a minor
    /// bump tells the two apart, where a major (which resets) would not.
    #[test]
    fn the_commit_inference_raises_the_last_release_not_the_declared_version() {
        assert_eq!(
            commits_imply(Some("0.10.0"), "0.11.0", Bump::Minor).as_deref(),
            Some("0.11.0")
        );
        assert_eq!(
            commits_imply(Some("0.10.0"), "0.11.0", Bump::Patch).as_deref(),
            Some("0.10.1")
        );
        assert_eq!(
            commits_imply(None, "0.11.0", Bump::Minor).as_deref(),
            Some("0.12.0")
        );
        assert_eq!(commits_imply(None, "unknown", Bump::Minor), None);
    }

    #[test]
    fn raising_zeroes_what_the_bump_supersedes() {
        let v = Version::parse("0.3.1").unwrap();
        assert_eq!(v.raised(Bump::Patch).to_string(), "0.3.2");
        assert_eq!(v.raised(Bump::Minor).to_string(), "0.4.0");
        assert_eq!(v.raised(Bump::Major).to_string(), "1.0.0");
        assert_eq!(v.raised(Bump::None).to_string(), "0.3.1");
    }

    #[test]
    fn a_version_that_is_not_three_numbers_is_refused() {
        assert!(Version::parse("0.3").is_none());
        assert!(Version::parse("0.3.1.4").is_none());
        assert!(Version::parse("v0.3.1").is_none());
    }

    /// A tree laid out the way the writer finds this repository: the manifest, the lock, the
    /// projection and the shell tool, each carrying the version, and each carrying it a
    /// second time in a place nothing may touch.
    fn tree(dir: &Path, version: &str) {
        std::fs::create_dir_all(dir.join("apps/majordomus-cli")).unwrap();
        std::fs::create_dir_all(dir.join("bin")).unwrap();
        std::fs::create_dir_all(dir.join("share")).unwrap();
        std::fs::write(
            dir.join(MANIFEST),
            format!("[package]\nname = \"majordomus-cli\"\nversion = \"{version}\"\n\n[dependencies]\nserde = {{ version = \"{version}\" }}\n"),
        )
        .unwrap();
        std::fs::write(
            dir.join(LOCK),
            format!("[[package]]\nname = \"serde\"\nversion = \"{version}\"\n\n[[package]]\nname = \"majordomus-cli\"\nversion = \"{version}\"\ndependencies = [\n \"serde\",\n]\n"),
        )
        .unwrap();
        std::fs::write(
            dir.join(PROJECTION),
            format!(
                "# Generator: majordomus-cli {version}\n{}",
                render_projection(version)
            ),
        )
        .unwrap();
        std::fs::write(
            dir.join("bin/majordomus"),
            "#!/usr/bin/env bash\nMJ_VERSION=\"\"\necho hi\n",
        )
        .unwrap();
    }

    #[test]
    fn writing_touches_the_one_authored_line_and_the_lock_record_of_it() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        tree(root, "0.3.1");
        let projection = std::fs::read(root.join(PROJECTION)).unwrap();
        let entry = std::fs::read(root.join("bin/majordomus")).unwrap();

        let written = write(root, "0.4.0").unwrap();
        assert_eq!(
            written,
            vec![MANIFEST.to_string(), LOCK.to_string()],
            "the authored line and cargo's record of it, and nothing else"
        );
        assert_eq!(declared(root).as_deref(), Some("0.4.0"));
        assert_eq!(locked(root).as_deref(), Some("0.4.0"));

        // derived and generated files are derivation's, never the writer's
        assert_eq!(std::fs::read(root.join(PROJECTION)).unwrap(), projection);
        assert_eq!(std::fs::read(root.join("bin/majordomus")).unwrap(), entry);
        assert!(
            matches!(projection_state(root), ProjectionState::Stale { .. }),
            "a bump leaves the projection stale until scripts/derive runs"
        );

        // a dependency at the same version is a different package, in both files
        let lock = std::fs::read_to_string(root.join(LOCK)).unwrap();
        assert!(
            lock.contains("name = \"serde\"\nversion = \"0.3.1\""),
            "a dependency at the same version was rewritten: {lock}"
        );
        let manifest = std::fs::read_to_string(root.join(MANIFEST)).unwrap();
        assert!(
            manifest.contains("serde = { version = \"0.3.1\" }"),
            "a dependency was rewritten: {manifest}"
        );

        // writing the same version again changes nothing, so a bump is safe to repeat
        assert!(write(root, "0.4.0").unwrap().is_empty());
    }

    #[test]
    fn the_projection_round_trips_through_the_generated_file() {
        // the body the writer of the file renders, under the banner `generate` puts above it
        let file = crate::generate::Artifact::text(
            PROJECTION,
            "version",
            MANIFEST,
            "0.9.0",
            &render_projection("0.9.0"),
        );
        assert!(
            file.content.starts_with("# GENERATED FILE"),
            "{}",
            file.content
        );
        assert_eq!(parse_projection(&file.content).as_deref(), Some("0.9.0"));
        // the stamp names the generator's version too, and is never read as the version
        let stamped = file.content.replace("version=0.9.0", "version=1.2.3");
        assert_eq!(parse_projection(&stamped).as_deref(), Some("1.2.3"));
    }

    #[test]
    fn a_stale_projection_warns_and_one_nothing_derives_is_refused() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        tree(root, "0.9.0");
        assert!(diagnose(root).is_empty(), "{:?}", diagnose(root));

        std::fs::write(root.join(PROJECTION), render_projection("0.8.0")).unwrap();
        let found = diagnose(root);
        assert_eq!(found.len(), 1, "{found:?}");
        assert_eq!(found[0].id, PROJECTION_STALE);
        assert_eq!(found[0].severity, Severity::Warning);
        assert!(
            found[0].message.contains("scripts/derive"),
            "{}",
            found[0].message
        );

        std::fs::remove_file(root.join(PROJECTION)).unwrap();
        assert_eq!(
            diagnose(root)[0].id,
            PROJECTION_STALE,
            "missing is stale too"
        );

        for unrelated in ["1.0.0", "0.9.0-rc1", "banana"] {
            std::fs::write(root.join(PROJECTION), render_projection(unrelated)).unwrap();
            let found = diagnose(root);
            assert_eq!(found[0].id, WRITERS_DISAGREE, "{unrelated}");
            assert_eq!(found[0].severity, Severity::Error, "{unrelated}");
        }
    }

    #[test]
    fn a_version_written_by_hand_is_found_and_a_generated_one_is_not() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        tree(root, "0.9.0");
        std::fs::create_dir_all(root.join("lib")).unwrap();
        std::fs::create_dir_all(root.join("scripts")).unwrap();
        std::fs::create_dir_all(root.join("docs/generated")).unwrap();
        std::fs::write(
            root.join("lib/a.sh"),
            "# 0.9.0 is fine in prose\nFOO_VERSION=\"1.2.3\"\n",
        )
        .unwrap();
        std::fs::write(root.join("scripts/b"), "echo \"majordomus 0.9.0\"\n").unwrap();
        // the same declaration in the other languages the tool's files are written in
        std::fs::write(
            root.join("scripts/c.mjs"),
            "// 0.9.0\nexport const VERSION = '0.9.0';\n",
        )
        .unwrap();
        std::fs::write(root.join("share/c.yaml"), "name: x\nversion: 0.9.0\n").unwrap();
        std::fs::write(root.join("share/d.toml"), "[tool]\nversion = \"0.9.0\"\n").unwrap();
        std::fs::write(root.join("share/gen.yaml"), "version: 0.9.0\n").unwrap();
        // outside the tool's own files a version is somebody else's business
        std::fs::write(root.join("docs/d.md"), "version: 0.9.0\n").unwrap();
        std::fs::write(
            root.join(GENERATED_MANIFEST),
            r#"{"artifacts":[{"path":"share/gen.yaml"}]}"#,
        )
        .unwrap();

        let found: Vec<(String, usize)> = carriers(root)
            .into_iter()
            .map(|c| (c.path, c.line))
            .collect();
        assert_eq!(
            found,
            vec![
                ("lib/a.sh".to_string(), 2),
                ("scripts/b".to_string(), 1),
                ("scripts/c.mjs".to_string(), 2),
                ("share/c.yaml".to_string(), 2),
                ("share/d.toml".to_string(), 2),
            ],
            "every hand-written statement once, the projection and the generated file never"
        );
        assert!(diagnose(root)
            .iter()
            .all(|d| d.id == STATED_BY_HAND && d.severity == Severity::Error));

        // a repository that does not carry the product is not asked
        std::fs::remove_file(root.join(MANIFEST)).unwrap();
        assert!(diagnose(root).iter().all(|d| d.id != STATED_BY_HAND));
    }

    #[test]
    fn a_version_is_three_numbers_and_no_more() {
        assert!(leads_with_version("1.2.3"));
        assert!(leads_with_version("v1.2.3\""));
        assert!(leads_with_version("1.2.3-rc1"));
        assert!(!leads_with_version("1.2"));
        assert!(!leads_with_version("1.2.3.4"));
        assert!(!leads_with_version("x1.2.3"));
        assert!(!leads_with_version(""));
    }

    /// One selection, made against a real release: a tree tagged `v0.1.0` whose surface has
    /// not moved, with a fix committed since. The analysis is sound, so the contract decides
    /// — it requires no release over the last one — and the commits make it a patch; the
    /// report's commit window is the one since that release, and the writer's default
    /// target is exactly the `next` the report states.
    #[test]
    fn a_sound_analysis_decides_the_report_and_the_writers_target_from_the_last_release() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        tree(root, "0.1.0");
        let registry_file = root.join(crate::release::surface::REGISTRY);
        std::fs::create_dir_all(registry_file.parent().unwrap()).unwrap();
        std::fs::write(
            &registry_file,
            r#"{"schema": "majordomus/capability-registry/v1", "capabilities": []}"#,
        )
        .unwrap();
        let git = |args: &[&str]| {
            let out = std::process::Command::new("git")
                .current_dir(root)
                .args(args)
                .output()
                .expect("git runs");
            assert!(out.status.success(), "git {args:?}: {out:?}");
        };
        git(&["init", "-q"]);
        git(&["config", "user.email", "t@example.com"]);
        git(&["config", "user.name", "t"]);
        git(&["add", "-A"]);
        git(&["commit", "-q", "-m", "chore: release 0.1.0"]);
        git(&["tag", "v0.1.0"]);
        std::fs::write(root.join("notes.txt"), "repaired\n").unwrap();
        git(&["add", "-A"]);
        git(&["commit", "-q", "-m", "fix: repair the thing"]);

        let registry = crate::capability::registry::CapabilityRegistry::builder()
            .build()
            .unwrap();
        let selection = select(root, &registry, &[]);
        let plan = selection.plan.as_ref().expect("a sound plan");
        assert_eq!(plan.baseline.reference, "v0.1.0");
        assert_eq!(plan.measured_version(), Ok("0.1.0".to_string()));

        let report = &selection.report;
        assert_eq!(report.last_release.as_deref(), Some("0.1.0"));
        // the window is the one since the release: the fix, and not the release commit
        let subjects: Vec<&str> = report.changes.iter().map(|c| c.subject.as_str()).collect();
        assert_eq!(subjects, ["repair the thing"], "{:?}", report.changes);
        assert_eq!(report.bump, "patch");
        assert_eq!(report.next.as_deref(), Some("0.1.1"));
        assert_eq!(report.decided_by, DecidedBy::ContractAndCommits);
        assert_eq!(report.contract_unreadable, None);
        let current = Version::parse("0.1.0").unwrap();
        assert_eq!(
            default_target(report, current).map(|v| v.to_string()),
            Ok("0.1.1".to_string())
        );
    }

    /// The writer's default target refuses what it cannot raise to, and says why: an
    /// undecided report with or without a reason, a selected version that is not three
    /// numbers — and with nothing to release it stays where it is.
    #[test]
    fn the_default_target_refuses_what_it_cannot_raise_to() {
        let current = Version::parse("0.4.0").unwrap();
        let report = |next: Option<&str>, decided_by, why: Option<&str>| VersionReport {
            declared: "0.4.0".into(),
            tool: "0.4.0".into(),
            agree: true,
            last_release: Some("0.4.0".into()),
            bump: "none".into(),
            commits_imply: None,
            next: next.map(Into::into),
            decided_by,
            contract_unreadable: why.map(Into::into),
            changes: Vec::new(),
        };
        // undecided and no reason given: the refusal still says what was not measured
        assert_eq!(
            default_target(&report(None, DecidedBy::Undecided, None), current),
            Err("the public contract could not be measured".to_string())
        );
        // undecided wins over a stray `next`: no one decided it, so nothing is raised to it
        assert_eq!(
            default_target(
                &report(Some("0.5.0"), DecidedBy::Undecided, Some("why")),
                current
            ),
            Err("why".to_string())
        );
        assert_eq!(
            default_target(&report(Some("0.5"), DecidedBy::Contract, None), current),
            Err("the selected version '0.5' is not three numbers".to_string())
        );
        assert_eq!(
            default_target(&report(None, DecidedBy::Contract, None), current),
            Ok(current)
        );
    }

    /// A tree of files, each written with its parent directories.
    fn prose_tree(root: &Path, files: &[(&str, &str)]) {
        for (path, text) in files {
            let full = root.join(path);
            std::fs::create_dir_all(full.parent().unwrap()).unwrap();
            std::fs::write(full, text).unwrap();
        }
    }

    /// `git init` and `git add -A` in `root`, isolated from any repository the test runs in.
    fn tracked(root: &Path) {
        for args in [&["init", "-q"][..], &["add", "-A"][..]] {
            let out = std::process::Command::new("git")
                .env_remove("GIT_DIR")
                .env_remove("GIT_WORK_TREE")
                .env_remove("GIT_INDEX_FILE")
                .arg("-C")
                .arg(root)
                .args(args)
                .output()
                .unwrap();
            assert!(out.status.success(), "git {args:?}: {out:?}");
        }
    }

    /// Every shape the label scanner decides: a label, and each way a `v` followed by
    /// numbers is not one.
    #[test]
    fn a_label_is_two_numbers_standing_alone() {
        assert_eq!(version_labels("v0.1"), ["v0.1"]);
        assert_eq!(version_labels("in v10.20, not v3."), ["v10.20"]);
        assert_eq!(version_labels("(v0.1) and \"v2.0\""), ["v0.1", "v2.0"]);
        // joined to what comes before it
        assert!(version_labels("dev0.1 api-v0.1 /v0.1 x.v0.1 _v0.1").is_empty());
        // not a version after the v
        assert!(version_labels("via vx.1 v.1 v1 v1. v1.x").is_empty());
        // a release, or glued to what follows
        assert!(version_labels("v0.3.1 v0.1a v0.1_x v0.1-rc").is_empty());
        // a dot that ends a sentence is not a patch
        assert_eq!(version_labels("It is v0.1."), ["v0.1"]);
    }

    /// The prose population: what is hand-written and read, and every way a file is not.
    #[test]
    fn the_prose_is_what_a_person_wrote() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        prose_tree(
            root,
            &[
                ("README.md", "x"),
                ("AGENTS.md", "x"),
                ("CLAUDE.md", "x"),
                ("docs/A.md", "x"),
                ("docs/notes.txt", "x"),
                ("docs/generated/listed.md", "x"),
                ("site/content/limitations.md", "x"),
                ("site/content/architecture.md", "x"),
                ("site/content-src/architecture.md", "x"),
                ("site/content/docs/design.md", "x"),
                ("site/data/nav.toml", "x"),
                ("site/data/generated/x.toml", "x"),
                ("site/data/x.json", "x"),
                ("site/templates/page.html", "x"),
                (".ai/repo/README.md", "x"),
                (".ai/repo/adrs/0001-x.md", "x"),
                (".ai/repo/sessions/s.md", "x"),
                (".ai/repo/policy.yaml", "x"),
                (".ai/repo/providers/claude.tmpl", "x"),
                ("share/providers/claude.tmpl", "x"),
                ("share/providers/notes.md", "x"),
                ("share/providers/x.yaml", "x"),
                (
                    GENERATED_MANIFEST,
                    r#"{"artifacts":[{"path":"docs/generated/listed.md"}]}"#,
                ),
            ],
        );
        tracked(root);
        assert_eq!(
            prose_files(root),
            [
                ".ai/repo/README.md",
                ".ai/repo/providers/claude.tmpl",
                "AGENTS.md",
                "CLAUDE.md",
                "README.md",
                "docs/A.md",
                "share/providers/claude.tmpl",
                "site/content-src/architecture.md",
                "site/content/limitations.md",
                "site/data/nav.toml",
                "site/templates/page.html",
            ]
        );
    }

    /// Where git cannot list the tree, the roots are walked: a file root is taken as it is
    /// and a directory root is read whole, so nothing goes unread for want of a checkout.
    #[test]
    fn a_tree_nobody_committed_is_still_read() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        prose_tree(root, &[("README.md", "x"), ("docs/sub/B.md", "x")]);
        assert_eq!(
            walk(root, &["README.md", "docs", "missing"]),
            ["docs/sub/B.md", "README.md"]
        );
        assert_eq!(prose_files(root), ["docs/sub/B.md", "README.md"]);
    }

    /// Only text somebody wrote is read: not a missing file, an oversized one, or one its
    /// generator stamped.
    #[test]
    fn a_stamped_or_oversized_file_is_not_authored() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let big = "x".repeat(LARGEST_READ as usize + 1);
        prose_tree(
            root,
            &[
                ("a.md", "v0.1\n"),
                ("b.md", "<!-- generated by majordomus -->\nv0.1\n"),
                ("c.md", "\u{feff}  # GENERATED FILE\nv0.1\n"),
                ("d.md", &big),
            ],
        );
        assert_eq!(authored_text(root, "a.md").as_deref(), Some("v0.1\n"));
        assert_eq!(authored_text(root, "b.md"), None);
        assert_eq!(authored_text(root, "c.md"), None);
        assert_eq!(authored_text(root, "d.md"), None);
        assert_eq!(authored_text(root, "gone.md"), None);
    }

    /// The history file: comments and blank lines are not entries, an entry's reason is
    /// everything after its path, and an absent file declares nothing.
    #[test]
    fn the_history_reads_a_path_and_its_reason() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        assert!(label_history(root).is_empty());
        prose_tree(
            root,
            &[(
                LABEL_HISTORY,
                "# a comment\n\n  docs/A.md  the design phase, dated \ndocs/B.md\n",
            )],
        );
        assert_eq!(
            label_history(root),
            [
                (
                    3,
                    "docs/A.md".to_string(),
                    "the design phase, dated".to_string()
                ),
                (4, "docs/B.md".to_string(), String::new()),
            ]
        );
    }

    /// Each finding the label check makes, and the exemption that holds only while its
    /// document still carries a label.
    #[test]
    fn a_label_is_refused_unless_its_document_is_declared_history() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        prose_tree(
            root,
            &[
                (
                    "README.md",
                    "# Tool\nWhat v0.1 does not do, in v0.2.\nRelease v0.3.1.\n",
                ),
                ("docs/DESIGN.md", "The v0.1 specification.\n"),
                ("docs/PLAIN.md", "No label here.\n"),
                // stamped by its generator: the label is its source's, not found here
                (
                    "docs/STAMPED.md",
                    "<!-- generated by x -->\nThe v0.1 notes.\n",
                ),
                (
                    LABEL_HISTORY,
                    "docs/DESIGN.md dated\ndocs/PLAIN.md it once had one\n\
                     docs/GONE.md removed\nREADME.md\n",
                ),
            ],
        );
        tracked(root);
        let found = label_diagnostics(root);
        let messages: Vec<&str> = found.iter().map(|d| d.message.as_str()).collect();
        assert!(found.iter().all(|d| d.severity == Severity::Error));
        assert_eq!(found.len(), 5, "{messages:#?}");
        assert_eq!(found[0].id, LABEL_IN_PROSE);
        assert!(messages[0].starts_with("README.md:2 names the version it describes as `v0.1`"));
        assert!(messages[1].starts_with("README.md:2 names the version it describes as `v0.2`"));
        assert_eq!(found[2].id, LABEL_HISTORY_INVALID);
        assert!(messages[2].contains(":2 exempts docs/PLAIN.md, which names no version label"));
        assert!(messages[3].contains(":3 exempts docs/GONE.md, which is not tracked"));
        assert!(messages[4].contains(":4 exempts README.md and says nothing about why"));
    }

    /// The label check is part of the one diagnosis the gate runs, and only where the
    /// product lives.
    #[test]
    fn the_diagnosis_carries_the_label_check_where_the_product_lives() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        prose_tree(root, &[("README.md", "What v0.1 does not do.\n")]);
        tracked(root);
        assert!(diagnose(root).is_empty(), "not the product's repository");
        prose_tree(
            root,
            &[
                (MANIFEST, "[package]\nversion = \"0.9.0\"\n"),
                (PROJECTION, "version=0.9.0\n"),
            ],
        );
        let found = diagnose(root);
        assert_eq!(found.len(), 1, "{found:?}");
        assert_eq!(found[0].id, LABEL_IN_PROSE);
    }
}