majordomus_cli/release/

changelog.rs

//! Composing the changelog out of what the repository already states.
//!
//! Nothing here is authored. A section per release record, newest first, with an unreleased
//! section leading when there is work after the last one:
//!
//! ```text
//!   release record  ──►  version, tag, date, commit, artifacts
//!   adr objects     ──►  the decisions dated inside this release's window
//!   git log A..B    ──►  the changes, as conventional commits
//! ```
//!
//! The window of a release is `(previous release's date, this release's date]` for the
//! decisions and `previous..this` for the commits. Both are the same interval said in the
//! two vocabularies the two sources have — an ADR carries a date and no commit, and a commit
//! carries no date the layer indexes.

use std::collections::{HashMap, HashSet};
use std::path::Path;
use std::sync::atomic::{AtomicUsize, Ordering};

use serde_json::Value;

use crate::model::Object;

use super::commits;
use super::model::{
    Artifact, Change, ChangeGroup, Changelog, Decision, ReleaseSection, CHANGELOG_SCHEMA,
};
use super::version;

/// The repository the links point into, as the crate manifest declares it.
///
/// Never a literal: `about::REPOSITORY` is `CARGO_PKG_REPOSITORY`, so a fork or a move
/// carries every link with it and nothing here has to be told. A URL that is not a forge
/// this understands yields no links at all rather than a guess — a wrong link is worse than
/// no link, because a reader cannot tell it is wrong until they follow it.
fn forge() -> Option<&'static str> {
    let url = crate::about::REPOSITORY.trim_end_matches('/');
    if url.starts_with("https://github.com/") && url.split('/').count() == 5 {
        Some(url)
    } else {
        None
    }
}

/// The kind the layer gives a published release.
pub const RELEASE_KIND: &str = "release-record";
/// The kind the layer gives a decision.
pub const ADR_KIND: &str = "adr";

/// One release, as read out of its record, before the changes are joined to it.
struct Record {
    version: String,
    tag: String,
    date: String,
    commit: String,
    notes: Option<String>,
    artifacts: Vec<Artifact>,
}

/// Compose the changelog, unreleased section included.
///
/// `objects` is the index's own view of the layer; `root` is the repository git reads. A
/// repository with no records yields one unreleased section, which is the right answer for a
/// project that has never published rather than an error.
///
/// This is what a live reader wants — the API, MCP and the Cockpit answer at request time
/// and HEAD is whatever it is then. It is not what a committed artifact may hold: see
/// [`compose_published`].
pub fn compose(root: &Path, objects: &[Object]) -> Changelog {
    compose_with(root, objects, true)
}

/// Compose the changelog of what has been published, and nothing after it.
///
/// The one form a committed artifact may take. The unreleased section is
/// `<last release>..HEAD`, and a file inside a commit cannot describe the commit it is in:
/// every commit made the committed changelog stale by construction, the pre-commit gate
/// refused until a full derive had run, and every session paid several minutes per commit
/// or worked around the gate. A document that depends only on the release records and the
/// history up to the newest of them is the same bytes at every commit that changes neither,
/// which is what "current" has to mean for a file under `docs/generated/`.
///
/// A repository with no records yields no section at all here — there is nothing published
/// to describe — where [`compose`] yields the unreleased one.
pub fn compose_published(root: &Path, objects: &[Object]) -> Changelog {
    compose_with(root, objects, false)
}

/// The release records among `objects`, newest first by the date each carries: the order a
/// changelog is read in, and so the order in which "the previous release" is the next one.
fn release_records(objects: &[Object], diagnostics: &mut Vec<String>) -> Vec<Record> {
    let mut records: Vec<Record> = objects
        .iter()
        .filter(|o| o.kind == RELEASE_KIND)
        .filter_map(|o| record_of(&o.metadata, diagnostics))
        .collect();
    records.sort_by(|a, b| b.date.cmp(&a.date));
    records
}

fn compose_with(root: &Path, objects: &[Object], unreleased: bool) -> Changelog {
    let mut diagnostics = Vec::new();

    let records = release_records(objects, &mut diagnostics);

    let decisions = decisions_of(root, objects);
    // Which commits each release's tree holds, read once for every release and every
    // decision asked about it (see `Ancestry`).
    let mut ancestry = Ancestry::new(root, records.iter().map(|r| r.commit.as_str()));

    let mut sections = Vec::new();

    // The unreleased section: everything after the newest release, when there is any, and
    // only for a reader that asked for it — a committed document never does (see
    // `compose_published`).
    let newest = records.first();
    let unreleased_range = match newest {
        Some(r) => format!("{}..HEAD", r.commit),
        None => "HEAD".to_string(),
    };
    let unreleased_changes = if unreleased {
        commits::in_range(root, &unreleased_range, objects)
    } else {
        Vec::new()
    };
    if !unreleased || (newest.is_some() && unreleased_changes.is_empty()) {
        // nothing since the last release, or nobody asked; no section rather than an empty one
    } else {
        sections.push(ReleaseSection {
            version: "unreleased".into(),
            tag: None,
            date: None,
            commit: None,
            unreleased: true,
            // Nothing is published yet, so there are no notes; the range is what has landed
            // since the last release, which is exactly what this section lists.
            notes_url: None,
            compare_url: forge()
                .zip(newest)
                .map(|(base, r)| format!("{base}/compare/{}...master", r.tag)),
            tree_url: forge().map(|base| format!("{base}/tree/master")),
            decisions: decisions_after(
                &mut ancestry,
                &decisions,
                newest.map(|r| r.commit.as_str()),
            ),
            groups: grouped(unreleased_changes),
            artifacts: Vec::new(),
        });
    }

    for (i, r) in records.iter().enumerate() {
        let previous = records.get(i + 1);
        let range = match previous {
            Some(p) => format!("{}..{}", p.commit, r.commit),
            // The first release: everything up to it. A clone without that history answers
            // nothing, which the diagnostics below make visible rather than silent.
            None => r.commit.clone(),
        };
        let changes = commits::in_range(root, &range, objects);
        if changes.is_empty() {
            diagnostics.push(format!(
                "no commit was readable for {} ({}); the clone may not carry that history",
                r.version, range
            ));
        }
        sections.push(ReleaseSection {
            version: r.version.clone(),
            tag: Some(r.tag.clone()),
            date: Some(r.date.clone()),
            commit: Some(r.commit.clone()),
            unreleased: false,
            // The record names its own notes; the range and the tree are the forge's own
            // addresses for facts the record already carries, so neither is authored.
            notes_url: r
                .notes
                .clone()
                .or_else(|| forge().map(|base| format!("{base}/releases/tag/{}", r.tag))),
            compare_url: forge().map(|base| match previous {
                Some(p) => format!("{base}/compare/{}...{}", p.tag, r.tag),
                None => format!("{base}/commits/{}", r.tag),
            }),
            tree_url: forge().map(|base| format!("{base}/tree/{}", r.tag)),
            decisions: decisions_between(
                &mut ancestry,
                &decisions,
                previous.map(|p| p.commit.as_str()),
                &r.commit,
            ),
            groups: grouped(changes),
            artifacts: r.artifacts.clone(),
        });
    }

    Changelog {
        schema: CHANGELOG_SCHEMA.into(),
        current: version::declared(root).unwrap_or_else(|| "unknown".into()),
        sections,
        diagnostics,
        // Filled by whoever answers with it: the composer does not know which surface asked.
        produced_by: None,
    }
}

/// The changes of a section, grouped by kind and ordered by the rank each kind carries.
///
/// Done here rather than in each renderer: the Markdown, the site and any other reader get
/// the same order because they are given it, not because they each reimplemented it.
///
/// One group per kind, exactly. The rank is a *presentation* order and two kinds may share
/// one — `Ci` and `Build` are both rank 6, `Chore` and `Style` both rank 7 — so a sort keyed
/// on the rank alone leaves equal-ranked kinds interleaved in the order their commits
/// arrived, and `dedup`, which removes only *adjacent* repeats, then leaves the same kind
/// standing several times. That is what put six `chore` groups and five `style` ones on the
/// changelog page, each rendering all of its changes again under an id the page had already
/// used, and what repeated their headings in the Markdown. The key is therefore total: the
/// rank first, then the kind's own order, so equal ranks are adjacent and one survives.
fn grouped(mut changes: Vec<Change>) -> Vec<ChangeGroup> {
    if let Some(base) = forge() {
        for c in &mut changes {
            c.url = Some(format!("{base}/commit/{}", c.commit));
        }
    }
    let mut kinds: Vec<_> = changes.iter().map(|c| c.kind).collect();
    kinds.sort_by_key(|k| (k.rank(), *k));
    kinds.dedup();
    kinds
        .into_iter()
        .map(|kind| ChangeGroup {
            kind,
            heading: kind.heading().to_string(),
            rank: kind.rank(),
            changes: changes.iter().filter(|c| c.kind == kind).cloned().collect(),
        })
        .collect()
}

/// One release record, from its metadata.
fn record_of(metadata: &Value, diagnostics: &mut Vec<String>) -> Option<Record> {
    let version = metadata.get("version")?.as_str()?.to_string();
    let tag = metadata
        .get("tag")
        .and_then(|v| v.as_str())
        .unwrap_or(&version)
        .to_string();
    let date = metadata
        .get("published_at")
        .and_then(|v| v.as_str())
        .unwrap_or_default()
        .to_string();
    let Some(commit) = metadata.get("commit").and_then(|v| v.as_str()) else {
        diagnostics.push(format!(
            "the record for {version} names no commit, so its changes cannot be read"
        ));
        return None;
    };
    let artifacts = metadata
        .get("artifacts")
        .and_then(|v| v.as_array())
        .map(|a| {
            a.iter()
                .filter_map(|v| {
                    Some(Artifact {
                        target: v.get("target")?.as_str()?.to_string(),
                        name: v.get("name")?.as_str()?.to_string(),
                        sha256: v
                            .get("sha256")
                            .and_then(|s| s.as_str())
                            .unwrap_or_default()
                            .to_string(),
                    })
                })
                .collect()
        })
        .unwrap_or_default();
    Some(Record {
        version,
        tag,
        date,
        commit: commit.to_string(),
        notes: metadata
            .get("notes_url")
            .and_then(|v| v.as_str())
            .map(|s| s.to_string()),
        artifacts,
    })
}

/// The releases whose window this repository's object database cannot read, by version.
///
/// A section of the published changelog is the history between two release commits, and a
/// repository made from a tree rather than from that history — a fixture exported with
/// `git archive`, a shallow clone — holds the tree and not the commits. Composed there, every
/// such section came out with no changes: a different document rather than a newer one, which
/// `generate --check` reported as stale and `generate` wrote over the committed changelog
/// (I1409). A release is unreadable when its commit or the previous release's is not an object
/// here, or when the repository is shallow, whose history ends at a graft whatever it holds.
/// Asked of git twice, whatever the number of releases.
pub(crate) fn unreadable_releases(root: &Path, objects: &[Object]) -> Vec<String> {
    let mut ignored = Vec::new();
    // the order `compose_with` reads them in, so "the previous release" is the same one
    let records = release_records(objects, &mut ignored);
    if records.is_empty() {
        return Vec::new();
    }
    let shallow = std::process::Command::new("git")
        .arg("-C")
        .arg(root)
        .args(["rev-parse", "--is-shallow-repository"])
        .output()
        .is_ok_and(|o| o.status.success() && String::from_utf8_lossy(&o.stdout).trim() == "true");
    let commits: Vec<&str> = records.iter().map(|r| r.commit.as_str()).collect();
    let held = held_commits(root, &commits);
    records
        .iter()
        .enumerate()
        .filter(|(i, r)| {
            shallow
                || !held.contains(r.commit.as_str())
                || records
                    .get(i + 1)
                    .is_some_and(|p| !held.contains(p.commit.as_str()))
        })
        .map(|(_, r)| r.version.clone())
        .collect()
}

/// Which of `commits` this repository holds as commits, asked in one `git cat-file`. Nothing
/// when git cannot answer, which is the same as holding none of them.
fn held_commits<'c>(root: &Path, commits: &[&'c str]) -> HashSet<&'c str> {
    use std::io::Write;
    use std::process::{Command, Stdio};
    let Ok(mut child) = Command::new("git")
        .arg("-C")
        .arg(root)
        .args(["cat-file", "--batch-check=%(objecttype)"])
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::null())
        .spawn()
    else {
        return HashSet::new();
    };
    let names: String = commits
        .iter()
        .map(|c| format!("{c}^{{commit}}\n"))
        .collect();
    // a write that fails leaves fewer answers than questions, which the zip reads as absent
    let _ = child
        .stdin
        .take()
        .map(|mut stdin| stdin.write_all(names.as_bytes()));
    let out = match child.wait_with_output() {
        Ok(out) if out.status.success() => out,
        _ => return HashSet::new(),
    };
    // one answer per question, in order: `commit`, or `<name> missing`
    commits
        .iter()
        .zip(String::from_utf8_lossy(&out.stdout).lines())
        .filter(|(_, answer)| *answer == "commit")
        .map(|(c, _)| *c)
        .collect()
}

/// Keep, for each release in `unreadable`, what the committed changelog already says it
/// changed, and return the versions kept.
///
/// What a release changed is read from history (its commits and the decisions its tree first
/// holds), and where the history is absent the committed document is the projection that was
/// made where it was present: keeping its groups and decisions is the one answer that is not
/// invented. Everything a record carries — version, tag, date, notes, artifacts — is still
/// composed from the record, so a changed record is still stale; and a section is kept only
/// when the committed one names the same commit, so a new release, or a record whose commit
/// changed, is composed and judged rather than passed on an older document.
pub(crate) fn keep_committed(
    log: &mut Changelog,
    committed: &Changelog,
    unreadable: &[String],
) -> Vec<String> {
    let mut kept = Vec::new();
    for section in log
        .sections
        .iter_mut()
        .filter(|s| !s.unreleased && unreadable.contains(&s.version))
    {
        let Some(was) = committed
            .sections
            .iter()
            .find(|c| !c.unreleased && c.version == section.version && c.commit == section.commit)
        else {
            continue;
        };
        section.groups = was.groups.clone();
        section.decisions = was.decisions.clone();
        kept.push(section.version.clone());
    }
    // the composition said it read nothing for these; what it now carries was read elsewhere
    log.diagnostics.retain(|d| {
        !kept
            .iter()
            .any(|v| d.starts_with(&format!("no commit was readable for {v} (")))
    });
    kept
}

/// When the file that states a decision was added, as git knows it.
///
/// The date in an ADR's front matter is when the decision was *made*, which is not the same
/// question as which release carried it — and using it put two decisions written on 2026-09-09
/// into a release published on 2026-09-08, because both ends were compared as calendar days.
/// The commits half of this module already asks git; the decisions half asks git now too.
fn added_at(root: &Path, path: &str) -> Option<String> {
    let out = std::process::Command::new("git")
        .arg("-C")
        .arg(root)
        .args([
            "log",
            "--diff-filter=A",
            "--format=%H",
            "--max-count=1",
            "--",
            path,
        ])
        .output()
        .ok()?;
    if !out.status.success() {
        return None;
    }
    let sha = String::from_utf8_lossy(&out.stdout).trim().to_string();
    if sha.is_empty() {
        None
    } else {
        Some(sha)
    }
}

/// When each of `paths` was added, as [`added_at`] answers it, in the order given.
///
/// One `git log` per decision walks the whole history each time, and asked one after the
/// other they were 43% of `generate --check` — some ten of the twenty seconds the pre-commit
/// gate is bounded by (case 56). A single walk over every path is not the same question:
/// git simplifies history per pathspec, so a merge that leaves one decision untouched but
/// changes another prunes a side branch for the first and follows it for the second, and on
/// this repository's history three of 95 answers moved. The question is unchanged here; the
/// processes run side by side instead, and they mostly wait on git rather than on this
/// process.
fn added_at_each(root: &Path, paths: &[&str]) -> Vec<Option<String>> {
    // as many at once as the machine runs, and no more: it runs other sessions' work too
    let threads = std::thread::available_parallelism()
        .map(|n| n.get())
        .unwrap_or(4)
        .clamp(1, 16)
        .min(paths.len());
    if threads < 2 {
        return paths.iter().map(|p| added_at(root, p)).collect();
    }
    let next = AtomicUsize::new(0);
    let answered: Vec<(usize, Option<String>)> = std::thread::scope(|scope| {
        let workers: Vec<_> = (0..threads)
            .map(|_| {
                scope.spawn(|| {
                    let mut mine = Vec::new();
                    loop {
                        let i = next.fetch_add(1, Ordering::Relaxed);
                        let Some(path) = paths.get(i) else {
                            return mine;
                        };
                        mine.push((i, added_at(root, path)));
                    }
                })
            })
            .collect();
        workers
            .into_iter()
            // `added_at` has no panic site, so a worker always returns: no panic to carry on
            .flat_map(|w| w.join().expect("added_at does not panic"))
            .collect()
    });
    let mut out = vec![None; paths.len()];
    for (i, added) in answered {
        out[i] = added;
    }
    out
}

/// Which commits a tree already holds, asked of git once for every tree.
///
/// The question the two window functions ask is "was the commit that added this decision
/// already in that release's tree?", for every decision against every release, twice for
/// most. Asked as `git merge-base --is-ancestor` it was one process per pair: some six hundred
/// at 62 decisions and six releases, about 6.5 of the 13.7 seconds an unoptimised
/// `generate --check` spent, and so of the pre-commit gate that runs it on every commit, and
/// it grows with the product of the two. Listing each tree's history once (`git rev-list
/// <tree>`) made every question a lookup, but still cost one process and one full walk per
/// release: at 21 releases that was 9 of the 37 seconds `generate --check` spent on
/// 2026-10-15 under load, and `scripts/derive` pays it twice.
///
/// So the trees the caller names are listed together, once, with their parents
/// (`git rev-list --parents <trees>`), and a tree's history is what it reaches over those
/// edges: the same answer, since the listing holds every commit any named tree reaches and
/// every parent of each, so the walk from a tree visits exactly what `git rev-list <tree>`
/// lists (the tree's own commit included, as `--is-ancestor` includes it). A tree the
/// listing does not name — not a full commit name, or one git cannot resolve, which fails
/// the whole listing — is listed alone as before, and a name git cannot resolve holds
/// nothing, as `--is-ancestor` refuses it.
struct Ancestry<'a> {
    root: &'a Path,
    /// The trees asked about, listed together on the first question.
    trees: Vec<String>,
    graph: Option<Graph>,
    held: HashMap<String, Held>,
}

/// What one tree holds: its reach over the shared listing, or its own listing.
enum Held {
    Reached(Vec<bool>),
    Listed(HashSet<String>),
}

impl<'a> Ancestry<'a> {
    fn new<'t>(root: &'a Path, trees: impl IntoIterator<Item = &'t str>) -> Self {
        Ancestry {
            root,
            trees: trees.into_iter().map(str::to_string).collect(),
            graph: None,
            held: HashMap::new(),
        }
    }

    /// Whether `commit` — a full commit name, as [`added_at`] gives it — was already in the
    /// tree `of`: whether it is `of` or one of its ancestors.
    fn holds(&mut self, of: &str, commit: &str) -> bool {
        let Ancestry {
            root,
            trees,
            graph,
            held,
        } = self;
        let graph = graph.get_or_insert_with(|| Graph::list(root, trees));
        let held = held
            .entry(of.to_string())
            .or_insert_with(|| match graph.index.get(of) {
                Some(&tree) => Held::Reached(graph.reach(tree)),
                None => Held::Listed(history(root, of)),
            });
        match held {
            Held::Reached(reached) => graph.index.get(commit).is_some_and(|&c| reached[c]),
            Held::Listed(listed) => listed.contains(commit),
        }
    }
}

/// Every commit some trees reach, each with its parents, from one `git rev-list --parents`.
#[derive(Default)]
struct Graph {
    index: HashMap<String, usize>,
    parents: Vec<Vec<usize>>,
}

impl Graph {
    /// The trees named by a full commit name, listed together; empty when there are none or
    /// git cannot list them all, and then every tree is listed alone.
    fn list(root: &Path, trees: &[String]) -> Graph {
        // each distinct name once, in byte order: a set, not a sort
        let named: Vec<&str> = trees
            .iter()
            .map(String::as_str)
            .filter(|t| is_full_name(t))
            .collect::<std::collections::BTreeSet<&str>>()
            .into_iter()
            .collect();
        if named.is_empty() {
            return Graph::default();
        }
        let Ok(out) = std::process::Command::new("git")
            .arg("-C")
            .arg(root)
            .args(["rev-list", "--parents"])
            .args(&named)
            .arg("--")
            .output()
        else {
            return Graph::default();
        };
        if !out.status.success() {
            return Graph::default();
        }
        Graph::from_listing(&String::from_utf8_lossy(&out.stdout))
    }

    /// The graph a `git rev-list --parents` listing describes: one row per commit, its full
    /// name and then its parents'. Empty when a row names a parent no row lists.
    fn from_listing(text: &str) -> Graph {
        let rows: Vec<Vec<&str>> = text
            .lines()
            .map(|l| l.split_whitespace().collect::<Vec<_>>())
            .filter(|r| !r.is_empty())
            .collect();
        let index: HashMap<String, usize> = rows
            .iter()
            .enumerate()
            .map(|(i, r)| (r[0].to_string(), i))
            .collect();
        let mut parents = Vec::with_capacity(rows.len());
        for row in &rows {
            let mut of = Vec::with_capacity(row.len() - 1);
            for p in &row[1..] {
                // Every parent of a listed commit is itself listed; one that is not means the
                // listing is not the whole history, and a partial graph would answer "no" where
                // git answers "yes". Each tree is then listed alone.
                let Some(&i) = index.get(*p) else {
                    return Graph::default();
                };
                of.push(i);
            }
            parents.push(of);
        }
        Graph { index, parents }
    }

    /// Which listed commits `tree` reaches, itself included.
    fn reach(&self, tree: usize) -> Vec<bool> {
        let mut reached = vec![false; self.parents.len()];
        let mut stack = vec![tree];
        while let Some(c) = stack.pop() {
            if std::mem::replace(&mut reached[c], true) {
                continue;
            }
            stack.extend(self.parents[c].iter().copied().filter(|&p| !reached[p]));
        }
        reached
    }
}

/// Whether `name` is a full commit name as git prints one: what the listing is keyed by, so
/// any other spelling of a tree (a tag, a branch, an abbreviation) is listed alone.
fn is_full_name(name: &str) -> bool {
    matches!(name.len(), 40 | 64) && name.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f'))
}

/// Every commit `of` reaches, by full name; nothing when git cannot resolve it.
fn history(root: &Path, of: &str) -> HashSet<String> {
    let Ok(out) = std::process::Command::new("git")
        .arg("-C")
        .arg(root)
        .args(["rev-list", of, "--"])
        .output()
    else {
        return HashSet::new();
    };
    if !out.status.success() {
        return HashSet::new();
    }
    String::from_utf8_lossy(&out.stdout)
        .lines()
        .map(str::to_string)
        .collect()
}

/// Every decision the layer holds, newest first.
fn decisions_of(root: &Path, objects: &[Object]) -> Vec<Decision> {
    let adrs: Vec<(&Object, String)> = objects
        .iter()
        .filter(|o| o.kind == ADR_KIND)
        .filter_map(|o| Some((o, o.metadata.get("id")?.as_str()?.to_string())))
        .collect();
    let paths: Vec<&str> = adrs
        .iter()
        .map(|(o, _)| o.provenance.path.as_str())
        .collect();
    let mut out: Vec<Decision> = adrs
        .into_iter()
        .zip(added_at_each(root, &paths))
        .map(|((o, id), added)| {
            Decision {
                title: o
                    .title
                    .clone()
                    .or_else(|| {
                        o.metadata
                            .get("title")
                            .and_then(|v| v.as_str())
                            .map(|s| s.to_string())
                    })
                    .unwrap_or_else(|| id.clone()),
                status: o
                    .metadata
                    .get("status")
                    .and_then(|v| v.as_str())
                    .unwrap_or("unknown")
                    .to_string(),
                date: o
                    .metadata
                    .get("date")
                    .and_then(|v| v.as_str())
                    .unwrap_or_default()
                    .to_string(),
                url: forge().map(|base| format!("{base}/blob/master/{}", o.provenance.path)),
                // Which release carried it is a question for git, not for the front matter:
                // the date says when the decision was made, and two ADRs written the day
                // after a release were claimed by it while this read that field instead.
                added,
                id,
            }
        })
        .collect();
    out.sort_by(|a, b| b.date.cmp(&a.date).then_with(|| b.id.cmp(&a.id)));
    out
}

/// The decisions not yet in any release: their file was added after the newest release's tree.
fn decisions_after(
    ancestry: &mut Ancestry<'_>,
    decisions: &[Decision],
    newest: Option<&str>,
) -> Vec<Decision> {
    decisions
        .iter()
        .filter(|d| match (newest, d.added.as_deref()) {
            // added, and not already in the last release's tree
            (Some(rel), Some(added)) => !ancestry.holds(rel, added),
            // nothing released yet, or git could not say when it was added: an unreleased
            // section that omits a decision is worse than one that shows an early arrival
            _ => true,
        })
        .cloned()
        .collect()
}

/// The decisions this release carried: in its tree, and not in the one before it.
fn decisions_between(
    ancestry: &mut Ancestry<'_>,
    decisions: &[Decision],
    previous: Option<&str>,
    release: &str,
) -> Vec<Decision> {
    decisions
        .iter()
        .filter(|d| {
            let Some(added) = d.added.as_deref() else {
                return false;
            };
            ancestry.holds(release, added) && previous.is_none_or(|p| !ancestry.holds(p, added))
        })
        .cloned()
        .collect()
}

/// The `YYYY-MM-DD` of an ISO-8601 date or timestamp.
fn day(text: &str) -> &str {
    text.split('T').next().unwrap_or(text)
}

/// The changelog as Markdown, which is what the generated document and the site render.
pub fn render(changelog: &Changelog) -> String {
    let mut out = String::new();
    out.push_str("# Changelog\n\n");
    out.push_str(
        "Every entry below is derived: a section per release the layer records, its decisions \
         the ADRs dated inside that release's window, its changes the conventional commits in \
         its range, its artifacts the record's own evidence. Nothing here is written by hand, \
         and `majordomus generate changelog --check` fails when it stops matching the tree.\n\n",
    );
    out.push_str(&format!("Current version: **{}**\n", changelog.current));

    for section in &changelog.sections {
        out.push('\n');
        if section.unreleased {
            out.push_str("## Unreleased\n\n");
        } else {
            let date = section.date.as_deref().unwrap_or("");
            out.push_str(&format!(
                "## {} — {}\n\n",
                section.tag.as_deref().unwrap_or(&section.version),
                day(date)
            ));
        }

        if !section.decisions.is_empty() {
            out.push_str("### Decisions\n\n");
            for d in &section.decisions {
                out.push_str(&format!(
                    "- **{}** {} _({})_\n",
                    d.id.to_uppercase(),
                    d.title,
                    d.status
                ));
            }
            out.push('\n');
        }

        // The groups the document carries, in the order it carries them: this renderer no
        // longer decides the order, it reads it, which is what lets the site agree with it.
        for group in &section.groups {
            out.push_str(&format!("### {}\n\n", group.heading));
            for c in &group.changes {
                let scope = c
                    .scope
                    .as_ref()
                    .map(|s| format!("**{s}**: "))
                    .unwrap_or_default();
                let breaking = if c.breaking { "**BREAKING** " } else { "" };
                out.push_str(&format!(
                    "- {breaking}{scope}{} (`{}`)\n",
                    c.subject, c.commit
                ));
            }
            out.push('\n');
        }

        if !section.artifacts.is_empty() {
            out.push_str("### Published\n\n");
            for a in &section.artifacts {
                out.push_str(&format!(
                    "- `{}` — {} (`{}`)\n",
                    a.target,
                    a.name,
                    &a.sha256[..a.sha256.len().min(12)]
                ));
            }
            out.push('\n');
        }
    }

    if !changelog.diagnostics.is_empty() {
        out.push_str("\n## What could not be read\n\n");
        for d in &changelog.diagnostics {
            out.push_str(&format!("- {d}\n"));
        }
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::release::model::ChangeKind;

    fn decision(id: &str, date: &str) -> Decision {
        Decision {
            id: id.into(),
            title: "t".into(),
            status: "accepted".into(),
            date: date.into(),
            url: None,
            added: None,
        }
    }

    fn git(root: &Path, args: &[&str]) -> String {
        let out = std::process::Command::new("git")
            .arg("-C")
            .arg(root)
            .args(args)
            .env("GIT_AUTHOR_NAME", "t")
            .env("GIT_AUTHOR_EMAIL", "t@t")
            .env("GIT_COMMITTER_NAME", "t")
            .env("GIT_COMMITTER_EMAIL", "t@t")
            .output()
            .expect("git runs");
        assert!(
            out.status.success(),
            "git {args:?}: {}",
            String::from_utf8_lossy(&out.stderr)
        );
        String::from_utf8_lossy(&out.stdout).trim().to_string()
    }

    /// A repository whose decisions arrive one file per commit, so that git can say when each
    /// was added: the fact the two window functions read. Returns the commit of each arrival,
    /// in order.
    fn repo_with_decisions(ids: &[&str]) -> (tempfile::TempDir, Vec<String>) {
        let dir = tempfile::tempdir().expect("a temp dir");
        let root = dir.path();
        git(root, &["init", "-q"]);
        std::fs::create_dir_all(root.join(".ai/repo/decisions")).expect("the decisions dir");
        let mut arrivals = Vec::new();
        for id in ids {
            std::fs::write(
                root.join(format!(".ai/repo/decisions/{id}.md")),
                "decided\n",
            )
            .expect("a decision file");
            git(root, &["add", "-A"]);
            git(root, &["commit", "-q", "-m", &format!("docs(adr): {id}")]);
            arrivals.push(git(root, &["rev-parse", "HEAD"]));
        }
        (dir, arrivals)
    }

    /// An ADR object as the index would hold it, dated on the same day as every other one
    /// here: the date is deliberately useless, so that only git's answer can pass the test.
    fn adr_object(id: &str) -> Object {
        let mut metadata = serde_json::Map::new();
        metadata.insert("id".into(), id.into());
        metadata.insert("status".into(), "accepted".into());
        metadata.insert("date".into(), "2026-09-01".into());
        Object {
            kind: ADR_KIND.into(),
            identity: id.into(),
            uri: format!("majordomus://adr/{id}"),
            title: Some("t".into()),
            description: None,
            metadata: serde_json::Value::Object(metadata),
            body: String::new(),
            content: String::new(),
            media_type: "text/markdown",
            provenance: crate::model::Provenance {
                path: format!(".ai/repo/decisions/{id}.md"),
                directory: ".ai/repo/decisions".into(),
                source_class: "decision".into(),
                section: None,
                bytes: 0,
                member: None,
            },
        }
    }

    #[test]
    fn a_decision_belongs_to_the_release_whose_tree_first_holds_it() {
        let (dir, at) = repo_with_decisions(&["adr-0001", "adr-0002", "adr-0003"]);
        let all = decisions_of(
            dir.path(),
            &[
                adr_object("adr-0001"),
                adr_object("adr-0002"),
                adr_object("adr-0003"),
            ],
        );
        assert!(
            all.iter().all(|d| d.added.is_some()),
            "git says when each file was added"
        );
        let mut ancestry = Ancestry::new(dir.path(), at.iter().map(String::as_str));
        // (first tree, second tree] — the second only, whatever its front matter is dated.
        let between = decisions_between(&mut ancestry, &all, Some(&at[0]), &at[1]);
        assert_eq!(between.len(), 1);
        assert_eq!(between[0].id, "adr-0002");
        // The first release has no predecessor, so it carries everything its tree holds.
        let first = decisions_between(&mut ancestry, &all, None, &at[0]);
        assert_eq!(first.len(), 1);
        assert_eq!(first[0].id, "adr-0001");
    }

    #[test]
    fn the_unreleased_section_holds_what_no_released_tree_holds() {
        let (dir, at) = repo_with_decisions(&["adr-0001", "adr-0003"]);
        let all = decisions_of(
            dir.path(),
            &[adr_object("adr-0001"), adr_object("adr-0003")],
        );
        let mut ancestry = Ancestry::new(dir.path(), [at[0].as_str()]);
        let after = decisions_after(&mut ancestry, &all, Some(&at[0]));
        assert_eq!(after.len(), 1);
        assert_eq!(after[0].id, "adr-0003");
        // No release at all: everything is unreleased.
        assert_eq!(decisions_after(&mut ancestry, &all, None).len(), 2);
    }

    /// Listing the trees' history once answers what `git merge-base --is-ancestor` answered one
    /// process per question: for every pair of commits of a history with a branch and a merge
    /// in it — a commit holds itself, a side branch's commit is held from the merge on and not
    /// before — and a tree git cannot resolve, which is what a clone without that history
    /// has, holds nothing. The answers are the same however the trees are named: listed
    /// together when each is a full commit name, which is the whole of the change; listed
    /// alone when one is a branch or an abbreviation, or when one git cannot resolve fails
    /// the shared listing.
    #[test]
    fn a_tree_holds_exactly_the_commits_merge_base_calls_its_ancestors() {
        let dir = tempfile::tempdir().expect("a temp dir");
        let root = dir.path();
        git(root, &["init", "-q", "-b", "main"]);
        let step = |message: &str| {
            git(root, &["commit", "-q", "--allow-empty", "-m", message]);
            git(root, &["rev-parse", "HEAD"])
        };
        let a = step("a");
        git(root, &["checkout", "-q", "-b", "side"]);
        let s = step("s");
        git(root, &["checkout", "-q", "main"]);
        let b = step("b");
        git(root, &["merge", "-q", "--no-ff", "-m", "m", "side"]);
        let m = git(root, &["rev-parse", "HEAD"]);
        let c = step("c");
        let all = [a, s, b, m, c];
        let unknown = "0".repeat(40);
        let short: Vec<String> = all.iter().map(|c| c[..12].to_string()).collect();

        // every tree as each spelling names it, against every commit, as merge-base answers
        let agrees = |ancestry: &mut Ancestry<'_>, trees: &[&str]| {
            let mut held = 0;
            for of in trees {
                for commit in &all {
                    let asked = std::process::Command::new("git")
                        .arg("-C")
                        .arg(root)
                        .args(["merge-base", "--is-ancestor", commit, of])
                        .status()
                        .expect("git runs")
                        .success();
                    assert_eq!(ancestry.holds(of, commit), asked, "is {commit} in {of}?");
                    held += usize::from(asked);
                }
            }
            // both answers occur, so the agreement is not vacuous
            assert!(held > 0 && held < trees.len() * all.len(), "{held} held");
            assert!(
                !ancestry.holds(&unknown, &all[0]),
                "an unknown tree holds nothing"
            );
        };
        let full: Vec<&str> = all.iter().map(String::as_str).collect();

        // full names: one listing answers every tree
        let mut together = Ancestry::new(root, full.iter().copied());
        agrees(&mut together, &full);
        let listed = together
            .graph
            .as_ref()
            .expect("listed on the first question");
        assert_eq!(
            listed.index.len(),
            all.len(),
            "the listing holds every commit"
        );
        assert!(full
            .iter()
            .all(|t| matches!(together.held[*t], Held::Reached(_))));
        assert!(matches!(together.held[&unknown], Held::Listed(_)));

        // branches and abbreviations: each listed alone, the same answers
        let mut spelled = Ancestry::new(
            root,
            ["main", "side"]
                .into_iter()
                .chain(short.iter().map(String::as_str)),
        );
        let mut names = vec!["main", "side"];
        names.extend(short.iter().map(String::as_str));
        agrees(&mut spelled, &names);
        assert!(spelled.graph.as_ref().is_some_and(|g| g.index.is_empty()));

        // a tree git cannot resolve fails the shared listing: every tree alone, the same answers
        let mut broken = Ancestry::new(root, full.iter().copied().chain([unknown.as_str()]));
        agrees(&mut broken, &full);
        assert!(broken.graph.as_ref().is_some_and(|g| g.index.is_empty()));
        assert!(full
            .iter()
            .all(|t| matches!(broken.held[*t], Held::Listed(_))));
    }

    /// Asked side by side, every decision gets the answer it got asked alone, in its own
    /// place: the order of the paths survives the order the threads finish in, and a path git
    /// never saw added is still nobody's.
    #[test]
    fn decisions_asked_together_are_dated_as_when_asked_alone() {
        let ids: Vec<String> = (1..=12).map(|n| format!("adr-{n:04}")).collect();
        let refs: Vec<&str> = ids.iter().map(String::as_str).collect();
        let (dir, at) = repo_with_decisions(&refs);
        let mut paths: Vec<String> = ids
            .iter()
            .rev()
            .map(|id| format!(".ai/repo/decisions/{id}.md"))
            .collect();
        paths.insert(5, ".ai/repo/decisions/never-added.md".into());
        let asked: Vec<&str> = paths.iter().map(String::as_str).collect();

        let together = added_at_each(dir.path(), &asked);
        let alone: Vec<Option<String>> = asked.iter().map(|p| added_at(dir.path(), p)).collect();
        assert_eq!(together, alone);
        assert_eq!(together[5], None);
        assert_eq!(together[0].as_deref(), Some(at[11].as_str()));
        assert_eq!(together[12].as_deref(), Some(at[0].as_str()));
        assert!(added_at_each(dir.path(), &[]).is_empty());
        // one path is asked in this thread, and answered as it is alone
        assert_eq!(added_at_each(dir.path(), &asked[..1]), alone[..1]);
    }

    /// An ADR the index holds without a string `id` names no decision: it is left out, not
    /// listed under an empty or a numeric name.
    #[test]
    fn an_adr_without_a_string_id_is_no_decision() {
        let (dir, _) = repo_with_decisions(&["adr-0001"]);
        let mut unnamed = adr_object("adr-0002");
        unnamed.metadata.as_object_mut().unwrap().remove("id");
        let mut numbered = adr_object("adr-0003");
        numbered.metadata["id"] = 3.into();
        let all = decisions_of(dir.path(), &[adr_object("adr-0001"), unnamed, numbered]);
        let ids: Vec<&str> = all.iter().map(|d| d.id.as_str()).collect();
        assert_eq!(ids, ["adr-0001"]);
    }

    /// A throwaway repository with `n` commits, the first of them tagged as a release the
    /// records name. What every test of the two compositions needs: a real HEAD that moves.
    fn repo_with_commits(n: usize) -> (tempfile::TempDir, String) {
        let dir = tempfile::tempdir().expect("a temp dir");
        let root = dir.path();
        let git = |args: &[&str]| {
            let out = std::process::Command::new("git")
                .arg("-C")
                .arg(root)
                .args(args)
                .env("GIT_AUTHOR_NAME", "t")
                .env("GIT_AUTHOR_EMAIL", "t@t")
                .env("GIT_COMMITTER_NAME", "t")
                .env("GIT_COMMITTER_EMAIL", "t@t")
                .output()
                .expect("git runs");
            assert!(
                out.status.success(),
                "git {args:?}: {}",
                String::from_utf8_lossy(&out.stderr)
            );
            String::from_utf8_lossy(&out.stdout).trim().to_string()
        };
        git(&["init", "-q"]);
        git(&[
            "commit",
            "-q",
            "--allow-empty",
            "-m",
            "feat(a): the release",
        ]);
        let release = git(&["rev-parse", "HEAD"]);
        for i in 1..n {
            git(&[
                "commit",
                "-q",
                "--allow-empty",
                "-m",
                &format!("fix(b): after the release {i}"),
            ]);
        }
        (dir, release)
    }

    fn release_record(commit: &str) -> Object {
        let mut metadata = serde_json::Map::new();
        metadata.insert("schema".into(), "release/v1".into());
        metadata.insert("version".into(), "0.1.0".into());
        metadata.insert("tag".into(), "v0.1.0".into());
        metadata.insert("channel".into(), "stable".into());
        metadata.insert("commit".into(), commit.into());
        metadata.insert("published_at".into(), "2026-09-01T00:00:00Z".into());
        metadata.insert("artifacts".into(), serde_json::Value::Array(Vec::new()));
        Object {
            kind: RELEASE_KIND.into(),
            identity: "v0.1.0".into(),
            uri: "majordomus://release-record/v0.1.0".into(),
            title: None,
            description: None,
            metadata: serde_json::Value::Object(metadata),
            body: String::new(),
            content: String::new(),
            media_type: "application/yaml",
            provenance: crate::model::Provenance {
                path: ".ai/repo/releases/v0.1.0.yaml".into(),
                directory: ".ai/repo/releases".into(),
                source_class: "release".into(),
                section: None,
                bytes: 0,
                member: None,
            },
        }
    }

    /// The property the committed artifact exists to have: a commit that publishes nothing
    /// does not change it. The live form is the one that follows HEAD.
    #[test]
    fn the_published_changelog_is_the_same_bytes_at_every_commit_after_the_release() {
        let (dir, release) = repo_with_commits(2);
        let objects = vec![release_record(&release)];
        let before = compose_published(dir.path(), &objects);
        let live_before = compose(dir.path(), &objects);

        std::process::Command::new("git")
            .arg("-C")
            .arg(dir.path())
            .args([
                "commit",
                "-q",
                "--allow-empty",
                "-m",
                "fix(c): one more commit",
            ])
            .env("GIT_AUTHOR_NAME", "t")
            .env("GIT_AUTHOR_EMAIL", "t@t")
            .env("GIT_COMMITTER_NAME", "t")
            .env("GIT_COMMITTER_EMAIL", "t@t")
            .status()
            .expect("git runs");

        let after = compose_published(dir.path(), &objects);
        let live_after = compose(dir.path(), &objects);

        assert_eq!(
            serde_json::to_string(&before).unwrap(),
            serde_json::to_string(&after).unwrap(),
            "a commit that publishes nothing must not move the committed changelog"
        );
        assert!(
            !before.sections.iter().any(|s| s.unreleased),
            "the committed form carries no unreleased section"
        );
        assert!(
            live_before.sections.iter().any(|s| s.unreleased),
            "the live form does"
        );
        assert_ne!(
            serde_json::to_string(&live_before).unwrap(),
            serde_json::to_string(&live_after).unwrap(),
            "and the live form follows HEAD"
        );
    }

    /// A repository that has never published: the live form says so with an unreleased
    /// section, and the committed form says so with nothing — there is nothing published to
    /// describe, and an empty section would be a claim.
    #[test]
    fn with_no_release_the_published_form_is_empty_and_the_live_form_is_unreleased() {
        let (dir, _) = repo_with_commits(1);
        let published = compose_published(dir.path(), &[]);
        assert!(published.sections.is_empty());
        let live = compose(dir.path(), &[]);
        assert_eq!(live.sections.len(), 1);
        assert!(live.sections[0].unreleased);
    }

    /// One group per kind, whatever order the commits arrived in and however many kinds
    /// share a rank.
    ///
    /// The page gives each group an id built from its kind, and the Markdown gives each one
    /// a heading; both are unique only if this is. It was not: the sort was keyed on the
    /// rank alone, `Chore` and `Style` share rank 7, and `dedup` removes only adjacent
    /// repeats — so alternating chore and style commits produced a group per commit.
    #[test]
    fn a_kind_gets_one_group_however_the_commits_interleave() {
        let change = |kind: ChangeKind, commit: &str| Change {
            kind,
            scope: None,
            subject: "s".into(),
            breaking: false,
            commit: commit.into(),
            url: None,
            references: Vec::new(),
        };
        // Chore and Style share rank 7; Ci and Build share rank 6.
        let groups = grouped(vec![
            change(ChangeKind::Ci, "a"),
            change(ChangeKind::Chore, "b"),
            change(ChangeKind::Style, "c"),
            change(ChangeKind::Chore, "d"),
            change(ChangeKind::Build, "e"),
            change(ChangeKind::Style, "f"),
            change(ChangeKind::Chore, "g"),
        ]);
        let kinds: Vec<_> = groups.iter().map(|g| g.kind).collect();
        assert_eq!(
            kinds,
            vec![
                ChangeKind::Ci,
                ChangeKind::Build,
                ChangeKind::Chore,
                ChangeKind::Style
            ],
            "a kind appears more than once, or the ranks are out of order"
        );
        // and every change is carried exactly once, by the one group of its kind
        assert_eq!(groups.iter().map(|g| g.changes.len()).sum::<usize>(), 7);
        assert!(groups.windows(2).all(|w| w[0].rank <= w[1].rank));
    }

    #[test]
    fn a_timestamp_and_a_date_compare_on_the_day_they_share() {
        assert_eq!(day("2026-09-09T15:04:05Z"), "2026-09-09");
        assert_eq!(day("2026-09-09"), "2026-09-09");
    }

    #[test]
    fn the_rendering_groups_by_kind_and_marks_what_breaks() {
        let changelog = Changelog {
            schema: CHANGELOG_SCHEMA.into(),
            current: "0.4.0".into(),
            sections: vec![ReleaseSection {
                version: "unreleased".into(),
                tag: None,
                date: None,
                commit: None,
                unreleased: true,
                notes_url: None,
                compare_url: None,
                tree_url: None,
                decisions: vec![decision("adr-0027", "2026-09-09")],
                // Given in the order the commits arrived — a fix first — so that the
                // grouping, not the input, is what decides the order the renderer shows.
                groups: grouped(vec![
                    Change {
                        kind: ChangeKind::Fix,
                        scope: Some("ci".into()),
                        subject: "the gate runs".into(),
                        breaking: false,
                        commit: "aaa1111".into(),
                        url: None,
                        references: Vec::new(),
                    },
                    Change {
                        kind: ChangeKind::Feat,
                        scope: Some("commands".into()),
                        subject: "one graph".into(),
                        breaking: true,
                        commit: "bbb2222".into(),
                        url: None,
                        references: Vec::new(),
                    },
                ]),
                artifacts: Vec::new(),
            }],
            diagnostics: Vec::new(),
            produced_by: None,
        };
        let md = render(&changelog);
        assert!(md.contains("## Unreleased"));
        assert!(md.contains("**ADR-0027**"));
        // Added before Fixed, whatever order the commits arrived in.
        let added = md.find("### Added").expect("no Added heading");
        let fixed = md.find("### Fixed").expect("no Fixed heading");
        assert!(added < fixed, "the headings are out of order:\n{md}");
        assert!(md.contains("**BREAKING** **commands**: one graph"));
    }

    /// I1409: a repository that holds the tree and not the history — the release commit is
    /// not an object in it — names the release as unreadable, and keeping the committed
    /// changelog's changes for it gives back the document composed where the history was.
    #[test]
    fn a_release_without_its_history_keeps_what_the_committed_changelog_says() {
        let (dir, release) = repo_with_commits(2);
        let objects = vec![release_record(&release)];
        assert!(
            unreadable_releases(dir.path(), &objects).is_empty(),
            "a repository holding the release commit can read it"
        );
        let whole = compose_published(dir.path(), &objects);
        assert!(!whole.sections[0].groups.is_empty(), "{whole:?}");

        // the same record, in a repository that never had that commit
        let export = tempfile::tempdir().expect("a temp dir");
        let init = std::process::Command::new("git")
            .arg("-C")
            .arg(export.path())
            .args(["init", "-q"])
            .output()
            .expect("git runs");
        assert!(init.status.success());
        assert_eq!(
            unreadable_releases(export.path(), &objects),
            vec!["0.1.0".to_string()]
        );
        let mut husk = compose_published(export.path(), &objects);
        assert!(
            husk.sections[0].groups.is_empty(),
            "nothing to read: {husk:?}"
        );
        assert!(!husk.diagnostics.is_empty(), "the empty read is said");

        let kept = keep_committed(&mut husk, &whole, &["0.1.0".to_string()]);
        assert_eq!(kept, vec!["0.1.0".to_string()]);
        assert_eq!(
            husk, whole,
            "the kept document is the one composed with history"
        );

        // a committed section for another commit is not this release's: composed, not kept
        let mut other = whole.clone();
        other.sections[0].commit = Some("0".repeat(40));
        let mut husk = compose_published(export.path(), &objects);
        assert!(keep_committed(&mut husk, &other, &["0.1.0".to_string()]).is_empty());
        assert!(husk.sections[0].groups.is_empty());
    }

    /// A shallow clone holds the release commit and still not the history behind it.
    #[test]
    fn a_shallow_clone_cannot_read_a_release() {
        let (dir, release) = repo_with_commits(3);
        let objects = vec![release_record(&release)];
        let shallow = tempfile::tempdir().expect("a temp dir");
        let url = format!("file://{}", dir.path().display());
        let clone = std::process::Command::new("git")
            .args(["clone", "-q", "--depth", "1", &url])
            .arg(shallow.path().join("c"))
            .output()
            .expect("git runs");
        assert!(
            clone.status.success(),
            "{}",
            String::from_utf8_lossy(&clone.stderr)
        );
        assert_eq!(
            unreadable_releases(&shallow.path().join("c"), &objects),
            vec!["0.1.0".to_string()]
        );
    }

    /// A release's window opens at the previous release: with both commits held both read,
    /// and with the previous release's commit absent the newer one cannot be read either.
    #[test]
    fn a_release_is_unreadable_when_the_previous_release_is_not_held() {
        let (dir, first) = repo_with_commits(2);
        let second = git(dir.path(), &["rev-parse", "HEAD"]);
        assert_ne!(first, second);
        let record = |version: &str, commit: &str, at: &str| {
            let mut object = release_record(commit);
            let metadata = object.metadata.as_object_mut().expect("a mapping");
            metadata.insert("version".into(), version.into());
            metadata.insert("tag".into(), format!("v{version}").into());
            metadata.insert("published_at".into(), at.into());
            object
        };
        let both = vec![
            record("0.1.0", &first, "2026-09-01T00:00:00Z"),
            record("0.2.0", &second, "2026-09-02T00:00:00Z"),
        ];
        assert!(
            unreadable_releases(dir.path(), &both).is_empty(),
            "both windows are held"
        );

        let absent = "0".repeat(40);
        let gap = vec![
            record("0.1.0", &absent, "2026-09-01T00:00:00Z"),
            record("0.2.0", &second, "2026-09-02T00:00:00Z"),
        ];
        assert_eq!(
            unreadable_releases(dir.path(), &gap),
            vec!["0.2.0".to_string(), "0.1.0".to_string()],
            "the newer release's window starts at a commit this repository lacks"
        );
    }

    /// A git that cannot be asked — it cannot start, or the directory is no repository —
    /// holds no commit, so every release reads as unreadable rather than as empty.
    #[test]
    fn a_git_that_cannot_answer_holds_no_commit() {
        let (dir, release) = repo_with_commits(1);
        let absent = "0".repeat(40);
        let asked = [release.as_str(), absent.as_str()];
        assert_eq!(
            held_commits(dir.path(), &asked),
            HashSet::from([release.as_str()]),
            "the repository holds its own commit and not an unknown one"
        );

        // a NUL in the path: the command cannot even be started
        let unspawnable = Path::new("no\0where");
        assert!(held_commits(unspawnable, &asked).is_empty());
        assert_eq!(
            unreadable_releases(unspawnable, &[release_record(&release)]),
            vec!["0.1.0".to_string()]
        );

        // a directory that does not exist: git starts and refuses
        let gone = dir.path().join("absent");
        assert!(held_commits(&gone, &asked).is_empty());
    }

    /// The shared listing is all or nothing: a git that cannot start lists nothing, and a
    /// listing that names a parent it does not list is not the whole history.
    #[test]
    fn a_listing_git_cannot_give_whole_is_no_graph() {
        let full = "a".repeat(40);
        let graph = Graph::list(Path::new("no\0where"), &[full]);
        assert!(graph.index.is_empty() && graph.parents.is_empty());

        let (c, p) = ("c".repeat(40), "d".repeat(40));
        let partial = Graph::from_listing(&format!("{c} {p}\n"));
        assert!(partial.index.is_empty(), "a parent outside the listing");
        let whole = Graph::from_listing(&format!("{c} {p}\n{p}\n"));
        assert_eq!(whole.index.len(), 2);
        assert_eq!(whole.parents[whole.index[&c]], vec![whole.index[&p]]);
    }

    /// A commit reached along two paths is reached once: a merge whose first parent is also
    /// the second parent's parent pushes that commit twice before it is popped.
    #[test]
    fn a_commit_reached_twice_is_reached_once() {
        let [m, r, a, x] = ["1", "2", "3", "4"].map(|d| d.repeat(40));
        let graph = Graph::from_listing(&format!("{m} {r} {a}\n{a} {r}\n{r}\n{x}\n"));
        let reached = graph.reach(graph.index[&m]);
        for held in [&m, &r, &a] {
            assert!(reached[graph.index[held]], "{held} is in the merge");
        }
        assert!(!reached[graph.index[&x]], "an unrelated commit is not");
        let from_a = graph.reach(graph.index[&a]);
        assert!(from_a[graph.index[&r]] && !from_a[graph.index[&m]]);
    }
}