majordomus_cli/capability/builtin/

release.rs

//! The `release` module: the changelog, the version, and the compatibility analysis behind
//! it — all three derived.
//!
//! Three capabilities, all read-only, all answered by [`crate::release`] — the same code the
//! command line renders, the generated document is written from, and the site page shows.
//! Neither reads a file somebody maintains: the changelog composes the layer's own release
//! records, decisions and the repository's commits, and the version report reads the one
//! place the version is authored and says whether the projection the shell tool prints is
//! current.
//!
//! Raising the version is not here. It writes tracked files, which makes it a repository
//! mutation, and the exposure policy keeps repository mutations off every machine surface —
//! so `release bump` is a command and nothing more, and this module is the read half.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::capability::benchmark::{BenchmarkCases, CaseContext, NamedCase};
use crate::capability::handler::{CapabilityError, Context};
use crate::capability::model::{
    BenchmarkPolicy, Exposure, McpExposure, McpResource, Stability, WaiverReason,
};
use crate::capability::module::ModuleDescriptor;
use crate::capability::registry::CapabilityRegistry;
use crate::release::compat::VersionPlan;
use crate::release::{self, model::ProducedBy, model::VersionReport, Changelog};
use crate::{capability, module};

use super::{get, Empty};

/// The URI under which the changelog is read as an MCP resource.
pub const CHANGELOG_URI: &str = "majordomus://changelog";

/// Which part of the changelog to answer with.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
#[schemars(rename = "ReleaseChangelogInput")]
pub struct ChangelogInput {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// One version, or `unreleased`; every section when absent.
    pub version: Option<String>,
}

impl BenchmarkCases for ChangelogInput {
    /// One real version from the layer's own records, so the narrow case is timed against
    /// something that exists rather than against a filter that matches nothing. A
    /// repository with no records has a narrow case all the same — the coverage gate counts
    /// targets, not repositories, and the OpenAPI operation's example of `version` *is* this
    /// case, which case 92 refuses to see missing — so it falls back to `unreleased`, the
    /// one section a repository has whether it has released anything or not.
    fn benchmark_cases(ctx: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        let version = ctx
            .index
            .objects
            .iter()
            .find(|o| o.kind == crate::release::changelog::RELEASE_KIND)
            .and_then(|o| o.metadata.get("version"))
            .and_then(|v| v.as_str())
            .map_or_else(|| "unreleased".to_string(), str::to_string);
        vec![
            NamedCase::new("all", ChangelogInput::default()),
            NamedCase::new(
                "one-version",
                ChangelogInput {
                    version: Some(version),
                },
            ),
        ]
    }
}

/// Which release to measure this tree against.
///
/// ```
/// use majordomus_cli::capability::builtin::release::AnalysisInput;
/// // Absent means the last release the layer records, which is the canonical baseline.
/// let input = AnalysisInput::default();
/// assert!(input.since.is_none());
/// let explicit = AnalysisInput { since: Some("v0.4.0".into()) };
/// assert_eq!(explicit.since.as_deref(), Some("v0.4.0"));
/// ```
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
#[schemars(rename = "ReleaseAnalysisInput")]
pub struct AnalysisInput {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// A ref to compare with instead of the last release: `v0.4.0`, or any commit that
    /// carries a committed registry.
    pub since: Option<String>,
}

impl BenchmarkCases for AnalysisInput {
    /// None. The capability is waived from the benchmark
    /// ([`WaiverReason::PublishedHistory`]) because its input is a release this repository
    /// has published, and a benchmark fixture has published nothing — so every case here
    /// would time a refusal and be counted as coverage. The trait is still implemented
    /// because the registry asks every input type for its cases; answering "none" is the
    /// honest answer rather than a case that measures an error path.
    fn benchmark_cases(_: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        Vec::new()
    }
}

/// The input of `release.next`: the landing it is asked about.
///
/// ```
/// use majordomus_cli::capability::builtin::release::NextInput;
/// // nothing named is the landing the executor performs: this branch onto the trunk
/// let input = NextInput::default();
/// assert_eq!((input.base(), input.head()), ("origin/master", "HEAD"));
/// ```
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
#[schemars(rename = "ReleaseNextInput")]
pub struct NextInput {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// The trunk the landing raises from; `origin/master` when absent.
    pub base: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// What lands; `HEAD` when absent.
    pub head: Option<String>,
}

impl NextInput {
    /// The trunk the landing raises from: the ref named, or `origin/master`, which is the
    /// trunk the integration executor lands on.
    ///
    /// ```
    /// use majordomus_cli::capability::builtin::release::NextInput;
    /// assert_eq!(NextInput { base: Some("main".into()), head: None }.base(), "main");
    /// ```
    pub fn base(&self) -> &str {
        self.base.as_deref().unwrap_or("origin/master")
    }

    /// What lands: the ref named, or `HEAD`, which is the branch this checkout is on.
    ///
    /// ```
    /// use majordomus_cli::capability::builtin::release::NextInput;
    /// assert_eq!(NextInput::default().head(), "HEAD");
    /// ```
    pub fn head(&self) -> &str {
        self.head.as_deref().unwrap_or("HEAD")
    }
}

impl BenchmarkCases for NextInput {
    /// None, for the reason [`AnalysisInput`] gives: the answer reads committed registries
    /// at two refs, and a benchmark fixture has no history to read them from.
    fn benchmark_cases(_: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        Vec::new()
    }
}

/// The module.
pub fn module() -> ModuleDescriptor {
    module! {
        id: "release",
        title: "Release",
        description: "What this project has shipped and what it would ship next, derived rather than maintained: the changelog composes the layer's release records, the decisions dated inside each release's window and the conventional commits in its range; the version report reads the one place the version is authored and the projection the shell tool prints, and says what the public contract requires it to become — or that it cannot be measured, and so decides nothing — with what the commits since the last release imply beside it as evidence.",
        stability: Stability::Implemented,
        capabilities: [
            capability! {
                id: CHANGELOG_ID,
                title: "The changelog",
                description: "Every release the layer records, newest first, with the work that has not been released leading. A section's decisions are the ADRs dated inside that release's window, its changes the conventional commits in its range, its artifacts the record's own evidence. Nothing in it is authored, and a section that could not be read says so rather than appearing empty.",
                input: ChangelogInput,
                output: Changelog,
                stability: Stability::Implemented,
                exposure: Exposure {
                    mcp: Some(McpExposure {
                        tool: Some("majordomus_changelog".into()),
                        resource: Some(McpResource { uri: CHANGELOG_URI.into(), name: "changelog".into() }),
                    }),
                    http: get("/api/v1/changelog"),
                    // Not a CLI projection: `majordomus release changelog` is a local
                    // command that *renders* this capability for a person at a terminal,
                    // and cli::LOCAL says so once (`RendersCapability`). Declaring the
                    // path here as well is the double accounting `tests/quality.rs`
                    // refuses (OPERATION_CLASSIFICATION_CONFLICT).
                    cli: None,
                },
                tags: ["release", "changelog"],
                handler: changelog,
            },
            capability! {
                id: "release.version",
                title: "The version, and the one the contract requires next",
                description: "The version the crate manifest declares — the one place it is authored — the version the shell tool prints from its projection `share/version.txt`, and whether that projection is current — the question `generate --check` refuses and `scripts/release-version --check` gates on. Then the next version, which is the public contract's answer: the version `release analyze` requires against the last release — the declared version when it already satisfies the contract, otherwise the smallest one it allows, and the smallest release above the last when the contract requires none over it — with `decided_by` naming who answered. It is the one release selection `release bump` also raises to when no target is named, so the report and the writer cannot disagree. When the contract cannot be measured — no published baseline, a version that is not three numbers, or any other error that makes the plan unsound, the plan `release bump` refuses to write from — the baseline is refused, not guessed: `next` is absent, `decided_by` is `undecided` and `contract_unreadable` carries every error, one per line. The bump the conventional commits since the last release imply, the version it would produce and the commits themselves are carried beside it as evidence, and never answer `next` in the contract's place.",
                input: Empty,
                output: VersionReport,
                stability: Stability::Implemented,
                exposure: Exposure {
                    mcp: Some(McpExposure {
                        tool: Some("majordomus_release_version".into()),
                        resource: None,
                    }),
                    http: get("/api/v1/release/version"),
                    cli: None,
                },
                tags: ["release", "version"],
                cache: crate::capability::CachePolicy::Checkout { max_entries: 2 },
                handler: version,
            },
            capability! {
                id: ANALYSIS_ID,
                title: "What the public contract did, and the smallest version it allows",
                description: "The public capability surface of this tree against the one the last release published, every movement of it named with the reason it counts for what it does, and the smallest version this tree may therefore declare. The compatibility level is measured from the contract rather than read off the commit subjects: a capability, route, MCP tool, command, or a required field of either schema that a caller could hold and cannot any more is breaking whatever the commit that removed it called itself. What the commits said about themselves is carried beside the verdict as evidence, and the answer says when the two disagree.",
                input: AnalysisInput,
                output: VersionPlan,
                stability: Stability::Implemented,
                exposure: Exposure {
                    mcp: Some(McpExposure {
                        tool: Some("majordomus_release_analysis".into()),
                        resource: None,
                    }),
                    http: get("/api/v1/release/analysis"),
                    // `majordomus release analyze` renders this capability for a person at a
                    // terminal; `cli::LOCAL` declares that once, and declaring the path here
                    // as well is the double accounting `tests/quality.rs` refuses.
                    cli: None,
                },
                tags: ["release", "version", "compatibility"],
                // Timed nowhere, because there is nothing honest to time. The analysis reads
                // what the last release published, and a benchmark fixture is a repository
                // that has published nothing: every case would measure the refusal rather
                // than the comparison. The behavioural case (112) is where it is exercised
                // against a repository with a real publication history.
                benchmark: BenchmarkPolicy::Waived { reason: WaiverReason::PublishedHistory },
                handler: analysis,
            },
            capability! {
                id: NEXT_ID,
                title: "The version a landing allocates, and why",
                description: "What the integration executor raises the trunk's version to when it lands a head (ADR 0134): the version the trunk declares, how far the head moves the public contract measured against the trunk's committed registry, what that movement requires under the version's mode, the repository's floor from `release.floor` in the policy, the exemption class that lowered the floor if every changed path falls in one, the larger of the requirement and the floor, and the trunk's version raised by it — with one sentence per step. Everything is read from git at the two refs, so the answer does not depend on which executable runs or on the branch's own version, which is why a retried landing cannot raise twice. It decides and writes nothing; an input that cannot be read is refused rather than guessed.",
                input: NextInput,
                output: release::landing::LandingDecision,
                stability: Stability::Implemented,
                exposure: Exposure {
                    mcp: Some(McpExposure {
                        tool: Some("majordomus_release_next".into()),
                        resource: None,
                    }),
                    http: get("/api/v1/release/next"),
                    // `majordomus release next` renders this capability; `cli::LOCAL`
                    // declares that once, as it does for `release analyze`.
                    cli: None,
                },
                tags: ["release", "version", "integration"],
                benchmark: BenchmarkPolicy::Waived { reason: WaiverReason::PublishedHistory },
                handler: next,
            },
        ],
    }
}

/// The compatibility analysis, named beside its declaration.
pub const ANALYSIS_ID: &str = "release.analysis";

/// The landing decision, named beside its declaration.
pub const NEXT_ID: &str = "release.next";

/// The capability's own id. Beside its declaration, so the two cannot drift apart without
/// the test below noticing; the document carries it so that no page has to enumerate where
/// this value is served.
pub const CHANGELOG_ID: &str = "release.changelog";

/// Where else the changelog can be had, read off the declarations that already say so.
///
/// One answer for every writer of the document: the handler that serves it and the generator
/// that commits it both ask here, so the committed artifact and the live answer name the same
/// surfaces. The route, the tool and the resource are the capability's own declaration; the
/// command line is the local command that renders this capability, which `cli::LOCAL`
/// declares once beside the reason it is local. Nothing is spelled out a second time, and a
/// page that lists these resolves each against the datasets the registry generates rather
/// than typing a route of its own. `None` only when the registry does not carry the
/// capability at all, which the module's own test refuses.
///
/// ```
/// use majordomus_cli::capability::builtin::release::{module, produced_by};
/// use majordomus_cli::capability::registry::CapabilityRegistry;
///
/// let registry = CapabilityRegistry::builder()
///     .with_modules(vec![module()])
///     .build()
///     .expect("the release module composes on its own");
/// let by = produced_by(&registry).expect("the registry carries release.changelog");
/// assert_eq!(by.capability, "release.changelog");
/// assert_eq!(by.cli.as_deref(), Some("majordomus release changelog"));
/// assert_eq!(by.http.as_deref(), Some("/api/v1/changelog"));
/// assert_eq!(by.mcp_tool.as_deref(), Some("majordomus_changelog"));
/// assert_eq!(by.mcp_resource.as_deref(), Some("majordomus://changelog"));
/// ```
pub fn produced_by(registry: &CapabilityRegistry) -> Option<ProducedBy> {
    let c = registry.get(CHANGELOG_ID)?;
    let cli = crate::cli::local::LOCAL
        .iter()
        .find(|l| l.reason.renders() == Some(CHANGELOG_ID))
        .map(|l| format!("majordomus {}", l.command));
    Some(ProducedBy {
        capability: c.id.to_string(),
        cli,
        http: c.exposure.http.as_ref().map(|h| h.path.clone()),
        mcp_tool: c.exposure.mcp.as_ref().and_then(|m| m.tool.clone()),
        mcp_resource: c
            .exposure
            .mcp
            .as_ref()
            .and_then(|m| m.resource.as_ref().map(|r| r.uri.clone())),
    })
}

fn changelog(ctx: &Context, input: ChangelogInput) -> Result<Changelog, CapabilityError> {
    let root = std::path::Path::new(&ctx.index.repository.root);
    let mut log = release::compose(root, &ctx.index.objects);
    log.produced_by = produced_by(&ctx.registry);
    if let Some(wanted) = input.version.as_deref() {
        log.sections.retain(|s| {
            s.version == wanted
                || s.tag.as_deref() == Some(wanted)
                || (wanted == "unreleased" && s.unreleased)
        });
        if log.sections.is_empty() {
            return Err(CapabilityError::NotFound(format!(
                "no release section carries the version '{wanted}'"
            )));
        }
    }
    Ok(log)
}

/// The version report, whose `next` is the contract's answer (ADR 0051).
///
/// [`release::version::select`] — the same selection `release bump` takes its default target
/// from, so the two never answer differently. When the analysis cannot be made — no published
/// baseline carries a registry, or a version is not three numbers and the analysis could only
/// guess — the report is still answered: `next` is absent, `decided_by` is `undecided` and the
/// reason is carried, beside the commit evidence that does not depend on it.
fn version(ctx: &Context, _: Empty) -> Result<VersionReport, CapabilityError> {
    let root = std::path::Path::new(&ctx.index.repository.root);
    Ok(release::version::select(root, &ctx.registry, &ctx.index.objects).report)
}

/// The one analysis, behind every surface that shows a version verdict.
///
/// A surface that cannot be read is a refusal and never an empty diff: an empty diff means
/// "nothing changed", and answering that when the truth is "the baseline could not be read"
/// is the false negative this whole subsystem exists to stop.
fn analysis(ctx: &Context, input: AnalysisInput) -> Result<VersionPlan, CapabilityError> {
    let root = std::path::Path::new(&ctx.index.repository.root);
    release::compat::analyze(
        root,
        &ctx.registry,
        &ctx.index.objects,
        input.since.as_deref(),
    )
    .map_err(|e| CapabilityError::NotFound(e.to_string()))
}

/// What a landing of the input's head onto its base allocates, under this repository's
/// policy. An unreadable policy is refused: a decision made without its floor would
/// understate what the repository asks.
fn next(
    ctx: &Context,
    input: NextInput,
) -> Result<release::landing::LandingDecision, CapabilityError> {
    let root = std::path::Path::new(&ctx.index.repository.root);
    let repo = crate::repository::Repository::open(root).map_err(|e| {
        CapabilityError::NotFound(format!("the repository could not be opened: {e}"))
    })?;
    let policy = crate::policy::LoadedPolicy::load(&repo)
        .map_err(|e| CapabilityError::NotFound(format!("the policy could not be read: {e}")))?
        .policy
        .release;
    release::landing::next_for(root, input.base(), input.head(), &policy)
        .map_err(|e| CapabilityError::NotFound(e.to_string()))
}

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

    /// A repository whose manifest cannot be read is refused by name, never guessed at.
    #[test]
    fn a_landing_in_a_repository_that_cannot_be_opened_is_refused() {
        let repo = crate::synthetic::SyntheticRepository::small().expect("a synthetic repository");
        let ctx = repo.context().expect("a context");
        std::fs::remove_file(repo.root().join(crate::repository::MANIFEST)).expect("the manifest");
        match next(&ctx, NextInput::default()) {
            Err(CapabilityError::NotFound(m)) => {
                assert!(m.contains("could not be opened"), "{m}")
            }
            other => panic!("not refused as not found: {other:?}"),
        }
    }

    /// A policy that cannot be read is refused by name, never taken as no allocation.
    #[test]
    fn a_landing_under_an_unreadable_policy_is_refused() {
        let repo = crate::synthetic::SyntheticRepository::small().expect("a synthetic repository");
        let ctx = repo.context().expect("a context");
        let policy = repo.root().join(".ai/repo/policy.yaml");
        let text = std::fs::read_to_string(&policy).expect("the policy");
        std::fs::write(&policy, format!("{text}release:\n  allocation: sideways\n"))
            .expect("the policy");
        match next(&ctx, NextInput::default()) {
            Err(CapabilityError::NotFound(m)) => {
                assert!(m.contains("the policy could not be read"), "{m}")
            }
            other => panic!("not refused as not found: {other:?}"),
        }
    }

    /// Two capabilities, and every surface that carries them is derived from this
    /// declaration: the MCP tools, the changelog resource, the HTTP routes, the OpenAPI
    /// operations. A refactor that renamed a route, dropped the resource or added a third
    /// would still compile, and the suites that exercise the changelog behind it would
    /// still pass. This is the assertion that would not.
    #[test]
    fn the_declaration_yields_the_projections_it_claims() {
        let m = module();
        assert_eq!(m.id.as_str(), "release");
        assert_eq!(
            ANALYSIS_ID, "release.analysis",
            "the id beside the declaration is the declared one"
        );
        let expected: &[(&str, &str, &str)] = &[
            (
                "release.changelog",
                "majordomus_changelog",
                "/api/v1/changelog",
            ),
            (
                "release.version",
                "majordomus_release_version",
                "/api/v1/release/version",
            ),
            (
                "release.analysis",
                "majordomus_release_analysis",
                "/api/v1/release/analysis",
            ),
            (
                "release.next",
                "majordomus_release_next",
                "/api/v1/release/next",
            ),
        ];
        let ids: Vec<&str> = m
            .capabilities
            .iter()
            .map(|e| e.capability.id.as_str())
            .collect();
        let want: Vec<&str> = expected.iter().map(|(id, _, _)| *id).collect();
        assert_eq!(
            ids, want,
            "the module declares a different set of capabilities"
        );
        for (executable, (id, tool, path)) in m.capabilities.iter().zip(expected) {
            let exposure = &executable.capability.exposure;
            assert_eq!(
                exposure.mcp.as_ref().and_then(|m| m.tool.as_deref()),
                Some(*tool),
                "{id} lost or renamed its MCP tool"
            );
            assert_eq!(
                exposure.http.as_ref().map(|h| h.path.as_str()),
                Some(*path),
                "{id} lost or renamed its HTTP route"
            );
        }
        // the changelog is also a resource, so a client may read it without calling a tool
        let changelog = &m.capabilities[0].capability.exposure;
        assert_eq!(
            changelog
                .mcp
                .as_ref()
                .and_then(|m| m.resource.as_ref())
                .map(|r| r.uri.as_str()),
            Some(CHANGELOG_URI),
            "the changelog stopped being an MCP resource"
        );
    }
}