headwater-cli 0.5.0

// SPDX-License-Identifier: Apache-2.0
//! The scratch repository that several targets run over, and the version pin
//! they all take.
//!
//! `diff.rs` and `migration.rs` both build a scratch repository out of this
//! one's `.headwater/packages/`, `docs/taxonomies/` and `.headwater/`, and both then read
//! a step from one package version to the next.
//!
//! [`Root`] moved here from `diff.rs` when `conformance_lock.rs` needed the
//! same root. A second copy would be a second fixture, and two targets that
//! disagreed about what the root declares would each be measuring their own.
//!
//! A target that includes this module is not obliged to use all of it —
//! `migration.rs` takes [`pin`] and builds its own root — so the module allows
//! what it does not use rather than each target carrying a list of exemptions.

#![allow(dead_code)]

use std::path::{Path, PathBuf};
use std::process::Command;

/// This repository, which every scratch root is copied out of.
pub(crate) fn repository() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../..")
        .canonicalize()
        .expect("the repository root resolves")
}

/// A directory for a tree outside every git repository, or `None`, with one
/// line on standard error, when no candidate is one.
///
/// `std::env::temp_dir()` follows `TMPDIR`, and a `TMPDIR` inside a git work
/// tree puts that work tree above every scratch tree, so git finds it (#1192).
/// A case does not set `GIT_CEILING_DIRECTORIES` for the process instead,
/// because cargo shares the process environment between the cases of one
/// target, and the census and `headwater-vcs` suites take the same base.
pub(crate) fn outside_base() -> Option<PathBuf> {
    clean_base(&base_candidates())
        .map_err(|refused| eprintln!("skipped, no scratch base outside git: {refused}"))
        .ok()
}

/// The first of `candidates` that is a directory with no `.git` entry in it
/// or in any directory above it, canonical, or every refusal in one line.
pub(crate) fn clean_base(candidates: &[PathBuf]) -> Result<PathBuf, String> {
    let mut refused = Vec::new();
    for candidate in candidates {
        let at = match candidate.canonicalize() {
            Ok(at) if at.is_dir() => at,
            Ok(_) => {
                refused.push(format!("{} is not a directory", candidate.display()));
                continue;
            }
            Err(error) => {
                refused.push(format!("{}: {error}", candidate.display()));
                continue;
            }
        };
        match at
            .ancestors()
            .map(|dir| dir.join(".git"))
            .find(|git| git.exists())
        {
            Some(git) => refused.push(format!(
                "{} is below {}",
                candidate.display(),
                git.display()
            )),
            None => return Ok(at),
        }
    }
    Err(refused.join("; "))
}

/// The directory [`outside_base`] finds, or `std::env::temp_dir()` with
/// nothing printed where there is none, for a scratch tree whose cases do
/// not all need it outside git.
pub(crate) fn scratch_base() -> PathBuf {
    clean_base(&base_candidates()).unwrap_or_else(|_| std::env::temp_dir())
}

/// Name the parent of `root` as git's ceiling for one command, so neither git
/// nor the engine's own search looks above it for a repository.
///
/// A root under `temp_dir()` has whatever repository `TMPDIR` sits in above
/// it, with whatever that repository declares and ignores (#1192). The
/// variable is set on the one command and never on this process, which cargo
/// shares between the cases of one target. A `.git` in `root` itself is
/// still found, because git reads a ceiling directory's children.
pub(crate) fn fence(command: &mut Command, root: &Path) {
    let parent = root.parent().expect("a scratch root has a parent");
    let parent = parent
        .canonicalize()
        .unwrap_or_else(|_| parent.to_path_buf());
    command.env("GIT_CEILING_DIRECTORIES", parent);
}

/// `std::env::temp_dir()`, then on unix the three directories a host keeps
/// for scratch files, in the order [`outside_base`] tries them.
fn base_candidates() -> Vec<PathBuf> {
    let mut candidates = vec![std::env::temp_dir()];
    if cfg!(unix) {
        candidates.extend(["/tmp", "/var/tmp", "/dev/shm"].map(PathBuf::from));
    }
    candidates
}

/// A repository root that removes itself.
///
/// `label` names the test and not the case. Cargo runs the cases of one target
/// as threads of one process, so a directory keyed on the process identifier
/// alone is a directory one case removes while another is reading it.
pub(crate) struct Root {
    pub(crate) at: PathBuf,
}

impl Root {
    pub(crate) fn new(label: &str) -> Root {
        Root::shaped(label, |_| {})
    }

    /// A root whose bundle order makes one overlay found the kind another one
    /// declares, so the resolution carries a founding and every publish out of
    /// it carries the same founding.
    ///
    /// The two bundles commute, which is the whole point: `zz-a` writes a leaf
    /// under `kinds.zz_thing` and `zz-b` declares that kind, so the declared
    /// order decides which of them creates the key. The consumer is free to
    /// list them either way — `headwater_resolve::package::selected` pushes
    /// bundles in the declared order with no topological pass — so the order
    /// here is a legal one and not a broken root.
    ///
    /// Three things about the pair, each of which cost an earlier attempt.
    /// `taxonomy publish` publishes the package with every bundle it ships, so
    /// a synthetic bundle has to resolve under that maximal set as well as
    /// under this consumer's selection: an address that reads a declaration the
    /// adopter overlay carries resolves for the consumer and fails the publish.
    /// A synthetic concrete kind needs a shelf, or `coverage` refuses the
    /// resolution. And reaching into a key an existing bundle or the adopter
    /// overlay already writes is refused as a collision rather than recorded as
    /// a founding, so the kind name is one nothing else names.
    pub(crate) fn founding(label: &str) -> Root {
        Root::shaped(label, |at| {
            write_bundle(at, "zz-a", FOUNDS);
            write_bundle(at, "zz-b", DECLARES);

            let declaration = at.join(".headwater/taxonomy.yml");
            let text = std::fs::read_to_string(&declaration).expect("the declaration reads");
            let from = "  bundles: [design-spec";
            assert!(text.contains(from), "the declaration lists its bundles");
            std::fs::write(
                &declaration,
                text.replacen(from, "  bundles: [zz-a, zz-b, design-spec", 1),
            )
            .expect("the declaration writes");
        })
    }

    pub(crate) fn shaped(label: &str, prepare: impl FnOnce(&Path)) -> Root {
        // Under a directory outside every git repository where one is found.
        // Where none is, the root sits under `temp_dir()`, and every run of
        // the binary through [`Root::command`] still sees no repository above
        // the root, because it names the root's parent as a ceiling (#1192).
        let at = scratch_base().join(format!("headwater-cli-root-{}-{label}", std::process::id()));
        let _ = std::fs::remove_dir_all(&at);
        std::fs::create_dir_all(&at).expect("the root is made");

        let repository = repository();
        // `.headwater/packages/headwater-standard/` is a vendored artifact since #366
        // (it carries a `release.yml`, and `taxonomy publish` now refuses to
        // publish a directory in that state — the guard this fixture would
        // otherwise trip, since every case here calls `taxonomy publish` by
        // name with no `--from`). The maintained source is
        // `taxonomy-source/headwater-standard/`, copied here to the path the
        // by-name lookup expects.
        copy(
            &repository.join("taxonomy-source/headwater-standard"),
            &at.join(".headwater/packages/headwater-standard"),
        );
        repoint_bundles(&at.join(".headwater/packages/headwater-standard"));
        copy(
            &repository.join("docs/taxonomies"),
            &at.join("docs/taxonomies"),
        );
        copy(
            &repository.join("engine/crates/cli/fixtures/change/docs"),
            &at.join("docs"),
        );
        for name in ["taxonomy.yml", "overlay.yml"] {
            let to = at.join(".headwater").join(name);
            std::fs::create_dir_all(to.parent().expect("it has a parent"))
                .expect("the declaration directory is there");
            std::fs::copy(repository.join(".headwater").join(name), to)
                .expect("the declaration copies");
        }
        // The package here is the source, copied, and not the artifact this
        // repository's pin names, so the pin would be drift that `validate`
        // and `check` now refuse (#1186). A root that takes its package from
        // source declares no pin, and this one does the same.
        let declaration = at.join(".headwater/taxonomy.yml");
        let text = std::fs::read_to_string(&declaration).expect("the declaration reads");
        let unpinned: String = text
            .lines()
            .filter(|line| !line.trim_start().starts_with("digest: sha256:"))
            .map(|line| format!("{line}\n"))
            .collect();
        assert_ne!(unpinned, text, "the copied declaration carried a pin");
        std::fs::write(&declaration, unpinned).expect("the declaration writes");

        // The overlay declares a governed scope, and the copy carries `docs/`,
        // which is a tree. `taxonomy validate` refuses a scope pattern that
        // matches no entry of a tree (#951), so one entry under each pattern
        // stands in for the code the copy does not carry.
        for entry in [
            "engine/crates/stub/src/lib.rs",
            ".githooks/stub",
            ".claude/hooks/stub",
            ".claude/agents/stub",
            ".claude/skills/stub",
            "tools/stub",
            "site/stub",
        ] {
            let to = at.join(entry);
            std::fs::create_dir_all(to.parent().expect("it has a parent"))
                .expect("the scope directory is there");
            std::fs::write(to, "").expect("the scope entry writes");
        }
        // The overlay lists four paths outside the corpus root under
        // `regimes.language.ste_house.outside_root` (HW-DR-0084), and
        // `taxonomy validate` names a pattern that matches no file, so each
        // gets a stub that obeys the regime.
        for entry in [
            "README.md",
            ".github/CONTRIBUTING.md",
            ".github/SECURITY.md",
            ".github/ISSUE_TEMPLATE/issue.md",
        ] {
            let to = at.join(entry);
            std::fs::create_dir_all(to.parent().expect("it has a parent"))
                .expect("the directory is there");
            std::fs::write(to, "# A stub\n\nThis file stands in for the real one.\n")
                .expect("the stub writes");
        }

        prepare(&at);
        pin(&at, "1.0.0");

        let root = Root { at };
        let resolved = root.run(&["taxonomy", "resolve"]);
        assert_eq!(resolved.code, Some(0), "the fixture resolves: {resolved:?}");
        root
    }

    pub(crate) fn run(&self, arguments: &[&str]) -> Ran {
        self.run_with(arguments, "")
    }

    /// The binary, with the root fenced off from any repository above it.
    pub(crate) fn command(&self) -> Command {
        let mut command = Command::new(env!("CARGO_BIN_EXE_headwater"));
        fence(&mut command, &self.at);
        command
    }

    /// Run the binary with `input` on its standard input, which is how a case
    /// talks to `headwater mcp` (#1161).
    pub(crate) fn run_with(&self, arguments: &[&str], input: &str) -> Ran {
        use std::io::Write;
        let mut child = self
            .command()
            .args(arguments)
            .arg("--root")
            .arg(&self.at)
            .stdin(std::process::Stdio::piped())
            .stdout(std::process::Stdio::piped())
            .stderr(std::process::Stdio::piped())
            .spawn()
            .expect("the binary runs");
        child
            .stdin
            .take()
            .expect("the standard input is piped")
            .write_all(input.as_bytes())
            .expect("the input writes");
        let output = child.wait_with_output().expect("the binary finishes");
        Ran {
            code: output.status.code(),
            out: String::from_utf8_lossy(&output.stdout).into_owned(),
            err: String::from_utf8_lossy(&output.stderr).into_owned(),
        }
    }
}

/// The `add:` block that writes a leaf under a kind nothing has declared yet,
/// so the resolver creates the parent on the way down and records a founding.
pub(crate) const FOUNDS: &str = "add:\n  kinds.zz_thing.voice: declarative\n";

/// The `add:` block that declares the kind, and the shelf `coverage` requires
/// of a concrete one.
pub(crate) const DECLARES: &str = "add:\n  kinds.zz_thing:\n    is_a: governed_document\n    \
                                   purpose: behavior\n    lifecycle: standard\n  \
                                   shelves.zz_things:\n    title: Zz Things\n    path: \
                                   docs/zz/**\n    homogeneous: true\n    kind: zz_thing\n";

/// Write one bundle of the founding pair.
///
/// The two blocks are held apart from the two names because the pair commutes:
/// a case that swaps which bundle carries which block writes a root that founds
/// the same kind out of the other file, and it does that with these two
/// constants rather than with a second copy of both bundles.
pub(crate) fn write_bundle(at: &Path, name: &str, add: &str) {
    let directory = at.join("docs/taxonomies").join(name);
    std::fs::create_dir_all(&directory).expect("the bundle directory is made");
    std::fs::write(
        directory.join("bundle.yml"),
        format!(
            "# SPDX-License-Identifier: Apache-2.0\n\nbundle: {name}\nextends: \
             headwater/standard@4.1.0\nrequires: []\n\n{add}"
        ),
    )
    .expect("the bundle writes");
}

impl Drop for Root {
    fn drop(&mut self) {
        let _ = std::fs::remove_dir_all(&self.at);
    }
}

#[derive(Debug)]
pub(crate) struct Ran {
    pub(crate) code: Option<i32>,
    pub(crate) out: String,
    pub(crate) err: String,
}

pub(crate) fn copy(from: &Path, to: &Path) {
    std::fs::create_dir_all(to).expect("the directory is there");
    for entry in std::fs::read_dir(from).expect("the fixture directory reads") {
        let entry = entry.expect("the entry reads");
        let target = to.join(entry.file_name());
        match entry.file_type().expect("the file type reads").is_dir() {
            true => copy(&entry.path(), &target),
            false => {
                std::fs::copy(entry.path(), &target).expect("the fixture copies");
            }
        }
    }
}

/// Fix the copied package at one version, whatever this repository's own
/// package is at.
///
/// Every case in both targets reads a step from 1.0.0 to 2.0.0. Without this
/// the base version is inherited from `.headwater/packages/`, so a major of the real
/// package rewrites a literal in every case at once. The version under test is
/// a property of the case and not of the repository the fixture is copied from.
///
/// Three files carry the number and all three move together: the manifest that
/// `resolve::package::sources` holds a consumer to, the taxonomy source beside
/// it, and the consumer declaration that pins what this root takes. The
/// manifest is read first, because it is the one the resolver compares.
pub(crate) fn pin(at: &Path, version: &str) {
    let manifest = at.join(".headwater/packages/headwater-standard/package.yml");
    let text = std::fs::read_to_string(&manifest).expect("the manifest reads");
    let found = text
        .lines()
        .find_map(|line| line.strip_prefix("version: "))
        .expect("the manifest declares a version")
        .to_string();

    for (relative, indent) in [
        (".headwater/packages/headwater-standard/package.yml", ""),
        (".headwater/packages/headwater-standard/taxonomy.yml", ""),
        (".headwater/taxonomy.yml", "  "),
    ] {
        let path = at.join(relative);
        let text = std::fs::read_to_string(&path).expect("the source reads");
        let from = format!("\n{indent}version: {found}\n");
        assert!(
            text.contains(&from),
            "{relative} does not declare version {found}"
        );
        let to = format!("\n{indent}version: {version}\n");
        std::fs::write(&path, text.replacen(&from, &to, 1)).expect("the source writes");
    }
}

/// Repoint `contents.bundles` in a scratch copy of the authored manifest.
///
/// The scalar is relative to the package directory, and
/// [`package::PACKAGES`] put that directory one level deeper in #792. The
/// prefix is computed from the constant rather than written out, so a root
/// that moves again moves this with it. `taxonomy publish` rewrites this same
/// scalar on every artifact it writes, so a fixture that does it here is not
/// inventing a mechanism.
fn repoint_bundles(package: &std::path::Path) {
    let up = "../".repeat(headwater_resolve::package::PACKAGES.split('/').count() + 1);
    let manifest = package.join(headwater_resolve::package::MANIFEST);
    let text = std::fs::read_to_string(&manifest).expect("the scratch manifest reads");
    let from = "  bundles: ../../docs/taxonomies";
    assert!(text.contains(from), "the authored manifest states `{from}`");
    let to = format!("  bundles: {up}docs/taxonomies");
    std::fs::write(&manifest, text.replace(from, &to)).expect("the scratch manifest writes");
}