shipshape_core/release/adapters/

homebrew.rs

//! Homebrew distribution adapter: `homebrew-tap` and `homebrew-core`.
//!
//! Updates a Homebrew formula (a custom tap, or a `homebrew-core` bump PR) so
//! `brew install` resolves the new version. `verify` fetches the destination
//! formula and checks its version and platform URL/checksum stanzas. Engine-owned
//! `homebrew-tap` formulas must also carry shipshape's ownership marker; CI-delegated
//! cargo-dist formulas are intentionally unmarked. A fetch failure is `Unknown`,
//! never a false `Missing`.
//!
//! ## Three formula paths: create, tap-write, bump-PR
//!
//! A release either **creates** the first `<name>.rb` on an empty tap or
//! **updates** an existing one. This adapter chooses by asking the tap whether the
//! formula already exists (through the injected
//! [`CommandRunner`](crate::ports::CommandRunner), so it is testable with no real
//! network or tap):
//!
//! - **configured tap, formula absent** → the *create* path: generate a
//!   source-build formula (the release tarball's `url` + `sha256`, the license, a
//!   cargo build/install stanza), clone the tap, commit the new file on a branch,
//!   and open a PR.
//! - **configured tap, formula present** → the *tap-write* path
//!   (`FormulaPath::TapWrite`): render the updated `<name>.rb` from the verified
//!   `url` + `sha256`, clone the tap, update the file, commit, and **push
//!   directly to the tap's default branch** — no `brew`, no `bump-formula-pr`, no
//!   `brew audit`. This is deterministic, needs no local `brew`/ruby/gem toolchain
//!   on the cutting machine, and mirrors the manual fallback that has always
//!   worked. It **fails closed** without a verified `sha256` (unlike create, which
//!   can open a draft-PR placeholder, a formula on the tap's *default branch* is
//!   what `brew install` resolves — so an unverified digest would ship a broken
//!   install), and it is a **clean no-op** when the tap already carries exactly
//!   this formula (an idempotent resume/re-run at the target version).
//! - **no configured tap** (a `homebrew-core` target, or a `homebrew-tap` with no
//!   resolved tap) → the *bump-PR* path: `brew bump-formula-pr` carrying the
//!   release tarball's `--url` (+ `--sha256` when a digest is available). First
//!   submission to `homebrew-core` is a human review process where the full core
//!   `brew audit` is appropriate, so the PR path is kept for it.
//!
//! ## Why tap-write replaced `brew bump-formula-pr` for the tap-bump case
//!
//! `brew bump-formula-pr` runs a full `brew audit` internally and aborts the whole
//! bump on any finding — including cosmetic core-lint changes irrelevant to a
//! personal tap the maintainer controls (issue `homebrew-dist-brew-audit-fails`:
//! the first engine dogfood cut failed here with a swallowed audit message). The
//! tap-write path removes that dependency entirely and surfaces any real git/`gh`
//! failure verbatim through the shared `run_all` runner rather than as a black box.

use std::fmt::Write as _;
use std::path::PathBuf;
use std::time::Duration;

use crate::contract::schema::Adapter;
use crate::protocol::release::{
    BuildArtifacts, DryRunReport, PlannedCommand, PublishReceipt, VerifyOutcome,
};

use super::{
    make_receipt, run_all, AdapterError, AdapterTarget, EffectCtx, HomebrewAsset, HomebrewFormula,
    ReleaseAdapter, SourceTarball,
};

/// The stable, greppable prefix of the **ownership marker** every shipshape-generated
/// formula carries as its first line. Its presence is how the *tap-write* path tells
/// a Shipshape-managed formula (safe to fully regenerate) from a hand-maintained one
/// (never clobber — surgically edit `url`/`sha256` only, or refuse). The prefix
/// deliberately omits the version integer so a future `template-version` bump still
/// reads as "shipshape-managed". See [`render_formula`] (writer) and
/// [`formula_carries_marker`] (reader).
const FORMULA_MARKER_PREFIX: &str =
    "# Generated by shipshape; do not edit by hand (template-version:";
/// Legacy marker emitted by ossctl. It remains trusted so a renamed installation can
/// safely resume and update formulas created before the product migration (ADR-0005).
const LEGACY_FORMULA_MARKER_PREFIX: &str =
    "# Generated by ossctl; do not edit by hand (template-version:";

/// The current formula-template version, embedded in the ownership marker. Bump this
/// when the generated formula's *shape* changes in a way worth recording; the marker
/// still identifies the file as shipshape-managed regardless of the integer.
const FORMULA_TEMPLATE_VERSION: u32 = 2;

/// Whether `bytes` carry the shipshape ownership marker on their **first line** —
/// exactly where [`render_formula`] writes it. The check is deliberately anchored to
/// the first line (not a search anywhere in the file): a hand-maintained formula that
/// merely *quotes* the marker string in a comment, `desc`, `caveats`, or embedded
/// `__END__`/patch data must NOT be mistaken for shipshape output and fully regenerated
/// (that would clobber the hand-authored stanzas this whole path exists to protect).
/// Operates on bytes so a non-UTF-8 formula needs no lossy conversion; a trailing
/// `\r` (CRLF) after the marker is irrelevant to the `starts_with` prefix test. A
/// marked formula is shipshape-managed → safe to fully regenerate; an unmarked one is
/// hand-maintained → the tap-write path must not clobber it.
fn formula_carries_marker(bytes: &[u8]) -> bool {
    let first_line = match bytes.iter().position(|&b| b == b'\n') {
        Some(i) => &bytes[..i],
        None => bytes,
    };
    first_line.starts_with(FORMULA_MARKER_PREFIX.as_bytes())
        || first_line.starts_with(LEGACY_FORMULA_MARKER_PREFIX.as_bytes())
}

/// The homebrew distribution adapter, operating as `homebrew-tap` or
/// `homebrew-core`.
pub struct HomebrewAdapter {
    adapter: Adapter,
}

/// Which formula operation the adapter resolved for a target.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum FormulaPath {
    /// Generate + PR the initial `<name>.rb` (configured tap, no formula yet).
    Create,
    /// Render + write the updated `<name>.rb` directly to the configured tap's
    /// default branch (configured tap, formula already present) — no `brew`, no
    /// PR. See the module docs' *tap-write* path.
    TapWrite,
    /// `brew bump-formula-pr` an already-present formula — the fallback for a
    /// target with no configured tap (`homebrew-core`, or an unconfigured
    /// `homebrew-tap`), where a reviewed PR + full `brew audit` is the right path.
    BumpPr,
}

impl HomebrewAdapter {
    /// Construct for a resolved homebrew adapter identity.
    #[must_use]
    pub fn new(adapter: Adapter) -> Self {
        debug_assert!(matches!(
            adapter,
            Adapter::HomebrewTap | Adapter::HomebrewCore
        ));
        Self { adapter }
    }

    /// The destination tap slug (`owner/repo`) for a `homebrew-tap` create, when
    /// the contract configured one. `None` for `homebrew-core` or an unconfigured
    /// tap — which pins the adapter to the bump path (no bootstrap destination).
    fn tap<'a>(&self, artifacts: Option<&'a HomebrewFormula>) -> Option<&'a str> {
        if self.adapter != Adapter::HomebrewTap {
            return None;
        }
        artifacts.and_then(|h| h.tap.as_deref())
    }

    /// Decide the formula path for `target`. A `homebrew-tap` with a configured
    /// tap probes the tap for the formula: absent → [`FormulaPath::Create`],
    /// present → [`FormulaPath::TapWrite`] (direct write to the tap). Every other
    /// case (no configured tap: `homebrew-core`, or an unconfigured tap) is
    /// [`FormulaPath::BumpPr`].
    ///
    /// The probe runs through the injected runner (`gh api …/contents/…`); a
    /// non-zero exit (a `404`, typically) reads as *absent* → create. A spawn
    /// failure is a real error and is propagated.
    fn resolve_path(
        &self,
        ctx: &EffectCtx<'_>,
        t: &AdapterTarget,
    ) -> Result<FormulaPath, AdapterError> {
        let homebrew = ctx.artifacts.homebrew.as_ref();
        match self.tap(homebrew) {
            Some(tap) => {
                if Self::formula_exists(ctx, tap, &t.package)? {
                    Ok(FormulaPath::TapWrite)
                } else {
                    Ok(FormulaPath::Create)
                }
            }
            None => Ok(FormulaPath::BumpPr),
        }
    }

    /// Ask the tap whether `Formula/<name>.rb` already exists, through the runner.
    ///
    /// Uses `gh api` against the tap's contents endpoint so no local checkout is
    /// needed for the probe. Only three outcomes are safe to act on:
    ///
    /// - exit `0` (the file is served) ⇒ **present** → bump.
    /// - a genuine `404` (`gh` renders it as `Not Found (HTTP 404)`) ⇒ **absent**
    ///   → create.
    /// - **anything else** — auth failure, rate-limit, network error, a private or
    ///   renamed tap, a 5xx — is an [`AdapterError::Command`], **not** "absent".
    ///   Treating an infrastructure error as absence would trigger a spurious
    ///   create that clones the tap and could overwrite an existing formula.
    ///
    /// A spawn failure (the port could not run `gh`) is a genuine
    /// [`AdapterError::Io`].
    fn formula_exists(ctx: &EffectCtx<'_>, tap: &str, name: &str) -> Result<bool, AdapterError> {
        let endpoint = format!("repos/{tap}/contents/Formula/{name}.rb");
        let cmd = PlannedCommand::new("gh", &["api", "--silent", &endpoint]);
        let out = ctx
            .runner
            .run("gh", &["api", "--silent", &endpoint], ctx.repo_root)
            .map_err(|e| AdapterError::Io {
                command: cmd.rendered(),
                source: e.to_string(),
            })?;
        if out.status == Some(0) {
            return Ok(true);
        }
        // A 404 is the only non-zero exit that means "absent". `gh` prints
        // `Not Found (HTTP 404)`; match the stable `404` token on either stream.
        if out.stderr.contains("404") || out.stdout.contains("404") {
            return Ok(false);
        }
        let detail = if out.stderr.trim().is_empty() {
            out.stdout
        } else {
            out.stderr
        };
        Err(AdapterError::Command {
            command: cmd.rendered(),
            code: out.status,
            stderr: detail,
        })
    }

    /// The `brew bump-formula-pr` command for an existing formula, carrying the
    /// threaded release tarball `--url` (+ `--sha256` when a digest is present).
    /// Options precede the `--` terminator so a formula name is never parsed as a
    /// flag. Unchanged from the pre-bootstrap behaviour.
    fn bump_command(&self, tarball: Option<&SourceTarball>, name: &str) -> PlannedCommand {
        let mut args: Vec<String> = match self.adapter {
            Adapter::HomebrewCore => vec!["bump-formula-pr".into(), "--no-fork".into()],
            _ => vec!["bump-formula-pr".into()],
        };
        if let Some(tarball) = tarball {
            args.push("--url".into());
            args.push(tarball.url.clone());
            if let Some(sha256) = &tarball.sha256 {
                args.push("--sha256".into());
                args.push(sha256.clone());
            }
        }
        args.push("--".into());
        args.push(name.to_string());
        PlannedCommand {
            program: "brew".into(),
            args,
        }
    }

    /// A **fresh, unpredictable** scratch checkout the create path clones the tap
    /// into. Unique per attempt (pid + a monotonic-ish nanosecond stamp) so:
    /// concurrent cuts/tests never collide; a retry never trips over a prior
    /// attempt's leftover dir (the old "deterministic" path made `gh repo clone`
    /// fail into a non-empty dir); and the unpredictable name defeats the classic
    /// world-writable-`/tmp` symlink pre-creation (TOCTOU) attack. The file write
    /// additionally uses create-new semantics (see [`Self::write_formula`]).
    fn fresh_workdir(name: &str, version: &str) -> PathBuf {
        let nanos = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map_or(0, |d| d.as_nanos());
        std::env::temp_dir().join(format!(
            "shipshape-homebrew-{name}-{version}-{}-{nanos}",
            std::process::id()
        ))
    }

    /// The branch the create path commits the new formula on.
    fn create_branch(name: &str, version: &str) -> String {
        format!("shipshape-homebrew-{name}-{version}")
    }

    /// The commit/PR title for a first formula.
    fn create_title(name: &str, version: &str) -> String {
        format!("{name} {version} (new formula)")
    }

    /// The ordered git/`gh` commands the create path runs (clone → branch → add →
    /// commit → push → PR), into the pre-computed `workdir`. The generated `.rb`
    /// is written to disk *between* the clone and the `add` (see
    /// [`Self::publish`]); these are only the process steps, shared by
    /// [`Self::dry_run`]'s preview and [`Self::publish`].
    ///
    /// `sha256_present` gates two things: a **draft** PR and a blocker in the body.
    /// When the source-tarball digest is not yet known (the coordinator threads
    /// `sha256: None` pre-tag), the generated formula carries only a `sha256`
    /// TODO and would fail `brew audit` / cannot install — so the PR is opened as a
    /// draft whose body states the one remaining manual step, rather than a
    /// mergeable-looking PR that is silently broken.
    fn create_commands(
        tap: &str,
        name: &str,
        version: &str,
        workdir: &str,
        sha256_present: bool,
    ) -> Vec<PlannedCommand> {
        let branch = Self::create_branch(name, version);
        let title = Self::create_title(name, version);
        let formula_rel = format!("Formula/{name}.rb");
        let body = if sha256_present {
            "Automated first-formula bootstrap by shipshape.".to_string()
        } else {
            "Automated first-formula bootstrap by shipshape.\n\n**Blocked:** the \
             `sha256` of the published release tarball is not yet known at cut \
             time (the tag archive does not exist until after publish). Fill in \
             the `sha256` once the tag is pushed, then mark this PR ready."
                .to_string()
        };
        let mut pr = vec![
            "pr".to_string(),
            "create".to_string(),
            "--repo".to_string(),
            tap.to_string(),
            "--head".to_string(),
            branch.clone(),
            "--title".to_string(),
            title.clone(),
            "--body".to_string(),
            body,
        ];
        if !sha256_present {
            pr.push("--draft".to_string());
        }
        vec![
            PlannedCommand::new("gh", &["repo", "clone", tap, workdir, "--", "--depth", "1"]),
            PlannedCommand::new("git", &["-C", workdir, "checkout", "-b", &branch]),
            PlannedCommand::new("git", &["-C", workdir, "add", &formula_rel]),
            // Set the commit identity explicitly (via `-c`): the freshly-cloned tap
            // inherits no `user.name`/`user.email`, so on a clean CI runner an
            // identity-less `git commit` fails with "Author identity unknown".
            // Disable `commit.gpgsign` so a machine with global signing on cannot
            // hang the automated commit waiting for a passphrase / missing GPG.
            PlannedCommand::new(
                "git",
                &[
                    "-C",
                    workdir,
                    "-c",
                    "user.name=shipshape",
                    "-c",
                    "user.email=shipshape@users.noreply.github.com",
                    "-c",
                    "commit.gpgsign=false",
                    "commit",
                    "-m",
                    &title,
                ],
            ),
            PlannedCommand::new(
                "git",
                &["-C", workdir, "push", "--set-upstream", "origin", &branch],
            ),
            PlannedCommand {
                program: "gh".to_string(),
                args: pr,
            },
        ]
    }

    /// Run the create path: generate the initial formula, clone the tap, write the
    /// file, commit it on a branch, and open a PR — all effects through the runner
    /// except the single filesystem write of the generated `.rb`.
    fn run_create(
        ctx: &EffectCtx<'_>,
        t: &AdapterTarget,
        tap: &str,
    ) -> Result<PublishReceipt, AdapterError> {
        // The package name reaches a filesystem path and a git pathspec; reject any
        // traversal/separator before it can escape the checkout or the `Formula/` dir.
        validate_package_name(&t.package)?;
        let homebrew = ctx.artifacts.homebrew.as_ref();
        let assets = verified_assets(ctx)?;
        let license = homebrew.and_then(|h| h.license.as_deref());
        let description = homebrew.and_then(|h| h.description.as_deref());
        let homepage_slug = ctx.artifacts.repo_slug.as_deref();
        let formula = render_formula(
            &t.package,
            &t.version,
            homepage_slug,
            description,
            assets,
            license,
        );

        // One workdir, computed once, used by both the clone and the write.
        let workdir = Self::fresh_workdir(&t.package, &t.version);
        let workdir_str = workdir.to_string_lossy().to_string();
        let commands = Self::create_commands(tap, &t.package, &t.version, &workdir_str, true);
        // 1. clone the tap.
        run_all(ctx, &commands[..1])?;
        // 2. write the generated formula into the checkout (create-new: refuses to
        //    overwrite a formula that already exists in the clone — the last-line
        //    guard against a probe/clone race or a mis-detected "absent").
        Self::write_formula(&workdir, &t.package, &formula, WriteMode::CreateNew)?;
        // 3. branch → add → commit → push → PR.
        let outputs = run_all(ctx, &commands[1..])?;

        // Record the PR URL `gh pr create` prints as the receipt's `remote_url`
        // (the field already existed — recording it is not a JSON-shape change).
        // `gh` can precede the URL with status lines, so take the last line that
        // looks like a URL rather than the whole stdout blob.
        let remote_url = outputs.last().and_then(|o| {
            o.stdout
                .lines()
                .rev()
                .map(str::trim)
                .find(|line| line.starts_with("https://"))
                .map(str::to_string)
        });
        Ok(make_receipt(ctx, t, None, remote_url))
    }

    /// The commit title for a tap-write formula update.
    fn update_title(name: &str, version: &str) -> String {
        format!("{name} {version}")
    }

    /// The ordered git/`gh` commands the *tap-write* path runs: clone → add →
    /// commit → push **to the tap's default branch** (no branch, no PR — the
    /// generated `.rb` is what `brew install` resolves). The rendered formula is
    /// overwritten onto disk *between* the clone (`commands[..1]`) and the `add`
    /// (`commands[1..]`), exactly like [`Self::create_commands`]; these are only
    /// the process steps, shared by [`Self::dry_run`]'s preview and
    /// [`Self::run_tap_write`].
    ///
    /// `git push origin HEAD` publishes the freshly-committed default branch (the
    /// clone checks the default branch out, so `HEAD` is it) — matching the manual
    /// fallback that pushed the formula straight to the tap.
    fn update_commands(tap: &str, name: &str, version: &str, workdir: &str) -> Vec<PlannedCommand> {
        let title = Self::update_title(name, version);
        let formula_rel = format!("Formula/{name}.rb");
        vec![
            PlannedCommand::new("gh", &["repo", "clone", tap, workdir, "--", "--depth", "1"]),
            PlannedCommand::new("git", &["-C", workdir, "add", &formula_rel]),
            // Set the commit identity explicitly (via `-c`): the freshly-cloned tap
            // inherits no `user.name`/`user.email`, so on a clean CI runner an
            // identity-less `git commit` fails with "Author identity unknown".
            // Disable `commit.gpgsign` so a machine with global signing on cannot
            // hang the automated commit waiting for a passphrase / missing GPG.
            PlannedCommand::new(
                "git",
                &[
                    "-C",
                    workdir,
                    "-c",
                    "user.name=shipshape",
                    "-c",
                    "user.email=shipshape@users.noreply.github.com",
                    "-c",
                    "commit.gpgsign=false",
                    "commit",
                    "-m",
                    &title,
                ],
            ),
            PlannedCommand::new("git", &["-C", workdir, "push", "origin", "HEAD"]),
        ]
    }

    /// Run the *tap-write* path: render the updated formula from the **verified**
    /// `url` + `sha256`, clone the tap, overwrite `Formula/<name>.rb`, commit, and
    /// push to the tap's default branch.
    ///
    /// **Fail-closed contract.** This path pushes to the tap's default branch — the
    /// ref `brew install <tap>/<name>` resolves — so it refuses to write a formula
    /// without a verified `sha256`: a missing tarball, an absent digest, or one that
    /// is not exactly 64 hex chars is a hard [`AdapterError::Command`], never a TODO
    /// placeholder. Unlike the create path's draft PR, there is no human review gate
    /// here, so a guessed/absent/malformed digest would ship a broken install.
    ///
    /// **Must already exist.** `resolve_path` chose this path from a `gh api` probe
    /// that reported the formula present; after cloning, this re-checks that the tap
    /// actually carries `Formula/<name>.rb` as a *regular file* before overwriting.
    /// If a probe/clone race left it absent (or it is a symlink/dir), it fails closed
    /// rather than *synthesize* a new formula straight onto the default branch — that
    /// would bypass the create path's PR review gate (and, for a symlink, clobber a
    /// file outside the checkout).
    ///
    /// **Ownership-marker safety** (issue `homebrew-tapwrite-preserve-formula`). It
    /// never blindly overwrites the existing formula. If the tap's current file
    /// carries the shipshape ownership marker (see [`render_formula`]), it *is* shipshape
    /// output and is safe to fully regenerate. If it does not (a hand-maintained
    /// formula with extra `depends_on`s, `resource`s, `caveats`, a custom `test`, …),
    /// this path refuses with instructions to add the ownership marker deliberately.
    /// It never silently claims or rewrites hand-authored content. The reader accepts
    /// both Shipshape and legacy ossctl ownership markers (ADR-0005).
    ///
    /// **Idempotent.** It compares the regenerated content against the tap's current
    /// bytes; an exact match is a clean no-op
    /// success (a resume/re-run at the target version), so it neither rewrites the
    /// file nor pushes an empty commit.
    fn run_tap_write(
        ctx: &EffectCtx<'_>,
        t: &AdapterTarget,
        tap: &str,
    ) -> Result<PublishReceipt, AdapterError> {
        // The package name reaches a filesystem path and a git pathspec; reject any
        // traversal/separator before it can escape the checkout or the `Formula/` dir.
        validate_package_name(&t.package)?;
        let homebrew = ctx.artifacts.homebrew.as_ref();
        let assets = verified_assets(ctx)?;
        let license = homebrew.and_then(|h| h.license.as_deref());
        let description = homebrew.and_then(|h| h.description.as_deref());
        let homepage_slug = ctx.artifacts.repo_slug.as_deref();

        let workdir = Self::fresh_workdir(&t.package, &t.version);
        let workdir_str = workdir.to_string_lossy().to_string();
        let commands = Self::update_commands(tap, &t.package, &t.version, &workdir_str);
        // 1. clone the tap (its default branch).
        run_all(ctx, &commands[..1])?;
        // 2. the formula must already be a regular file in the clone (see the
        //    "Must already exist" contract above) — read its current bytes.
        let formula_path = workdir.join("Formula").join(format!("{}.rb", t.package));
        let current = Self::read_existing_formula(&formula_path, &t.package)?;
        // 3. ownership marker (issue `homebrew-tapwrite-preserve-formula`): only a
        //    formula Shipshape or ossctl generated (carrying either recognized marker)
        //    is safe to fully regenerate. An unmarked, hand-maintained formula must NOT
        //    be clobbered. The actionable refusal below requires the maintainer to add
        //    the marker explicitly before Shipshape claims full ownership.
        let updated = if formula_carries_marker(&current) {
            render_formula(
                &t.package,
                &t.version,
                homepage_slug,
                description,
                assets,
                license,
            )
        } else {
            return Err(AdapterError::Command {
                command: "homebrew formula update".into(),
                code: None,
                stderr: format!(
                    "refusing to replace an unmarked source-build or hand-maintained formula with a generated prebuilt formula; to explicitly authorize Shipshape ownership, make the file's first line exactly `# Generated by shipshape; do not edit by hand (template-version: {FORMULA_TEMPLATE_VERSION})`"
                ),
            });
        };
        // 4. idempotent no-op: the tap already carries exactly this content.
        let remote_url = Some(format!(
            "https://github.com/{tap}/blob/HEAD/Formula/{}.rb",
            t.package
        ));
        if current == updated.as_bytes() {
            return Ok(make_receipt(ctx, t, None, remote_url));
        }
        // 5. overwrite the existing formula, then add → commit → push.
        Self::write_formula(&workdir, &t.package, &updated, WriteMode::Overwrite)?;
        run_all(ctx, &commands[1..])?;
        Ok(make_receipt(ctx, t, None, remote_url))
    }

    /// Read the tap's current `Formula/<name>.rb` bytes, enforcing the tap-write
    /// invariant that it is an **already-present regular file**. A missing file (a
    /// probe/clone race) or a non-regular node (a symlink the overwrite would follow
    /// out of the checkout, or a directory) is a fail-closed [`AdapterError`] — never
    /// a silent create. Uses `symlink_metadata` so a symlink is *detected*, not
    /// traversed.
    fn read_existing_formula(path: &std::path::Path, name: &str) -> Result<Vec<u8>, AdapterError> {
        let meta = std::fs::symlink_metadata(path).map_err(|e| AdapterError::Command {
            command: "homebrew formula update".into(),
            code: None,
            stderr: format!(
                "the tap was probed as carrying `{name}.rb` but the cloned checkout does not \
                 (`{}`: {e}) — refusing to synthesize a formula on the default branch without the \
                 create-path review gate",
                path.display()
            ),
        })?;
        if !meta.file_type().is_file() {
            return Err(AdapterError::Filesystem {
                path: path.to_string_lossy().to_string(),
                source: "not a regular file (symlink or directory) — refusing to overwrite".into(),
            });
        }
        std::fs::read(path).map_err(|e| AdapterError::Filesystem {
            path: path.to_string_lossy().to_string(),
            source: e.to_string(),
        })
    }

    /// Write the generated formula to `<workdir>/Formula/<name>.rb`, creating the
    /// `Formula/` directory if the freshly-cloned tap does not carry it yet.
    ///
    /// This is the one direct-filesystem effect in the adapter — Homebrew has no
    /// "add a formula" CLI; a new formula *is* a committed file, so `run_all`
    /// (which only *runs processes*) cannot express it. It is deliberately scoped:
    /// it writes exactly one file into a private, unpredictable [`Self::fresh_workdir`]
    /// the calling path just cloned into. A general filesystem port on `EffectCtx`
    /// is the cleaner long-term home (issue `homebrew-adapter-fs-port`); until then
    /// this is mapped to a distinct [`AdapterError::Filesystem`] so the effect is
    /// explicit, not hidden.
    ///
    /// [`WriteMode`] gates the open semantics:
    /// - [`WriteMode::CreateNew`] (the create path) uses **create-new** (`O_EXCL`)
    ///   so it never follows a symlink onto, or truncates, an existing file — which
    ///   also fails loudly if the tap already carries the formula (a last-line guard
    ///   against a mis-detected "absent" formula).
    /// - [`WriteMode::Overwrite`] (the tap-write path) truncates the already-present
    ///   formula **without** `create` — the caller ([`Self::run_tap_write`]) has
    ///   already verified via [`Self::read_existing_formula`] that it is an existing
    ///   regular file, so an open failure here means it vanished under us (a race),
    ///   which is a fail-closed error rather than a silent create.
    fn write_formula(
        workdir: &std::path::Path,
        name: &str,
        formula: &str,
        mode: WriteMode,
    ) -> Result<(), AdapterError> {
        let dir = workdir.join("Formula");
        std::fs::create_dir_all(&dir).map_err(|e| AdapterError::Filesystem {
            path: dir.to_string_lossy().to_string(),
            source: e.to_string(),
        })?;
        let path = dir.join(format!("{name}.rb"));
        let mut opts = std::fs::OpenOptions::new();
        opts.write(true);
        match mode {
            WriteMode::CreateNew => {
                opts.create_new(true);
            }
            WriteMode::Overwrite => {
                opts.truncate(true);
            }
        }
        let mut file = opts.open(&path).map_err(|e| AdapterError::Filesystem {
            path: path.to_string_lossy().to_string(),
            source: e.to_string(),
        })?;
        std::io::Write::write_all(&mut file, formula.as_bytes()).map_err(|e| {
            AdapterError::Filesystem {
                path: path.to_string_lossy().to_string(),
                source: e.to_string(),
            }
        })
    }
}

/// How [`HomebrewAdapter::write_formula`] opens the target `.rb`: create-new
/// (`O_EXCL`, the first-formula create) or truncate-an-existing-file (the tap-write
/// bump, whose caller has already proven the file is a present regular file).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum WriteMode {
    /// Refuse to open an existing file (`O_EXCL`) — the create path's guard.
    CreateNew,
    /// Truncate an existing file; **no** `create`, so a vanished file is an error,
    /// not a silent create — the tap-write path replacing an existing formula.
    Overwrite,
}

impl ReleaseAdapter for HomebrewAdapter {
    fn adapter(&self) -> Adapter {
        self.adapter
    }

    fn dry_run(
        &self,
        ctx: &EffectCtx<'_>,
        t: &AdapterTarget,
    ) -> Result<DryRunReport, AdapterError> {
        let tarball = ctx.artifacts.source_tarball.as_ref();
        let path = self.resolve_path(ctx, t)?;
        let (planned_commands, mut notes) = match path {
            FormulaPath::Create => {
                // `tap` is Some whenever resolve_path returned Create.
                let tap = self
                    .tap(ctx.artifacts.homebrew.as_ref())
                    .unwrap_or_default();
                let workdir = Self::fresh_workdir(&t.package, &t.version);
                let sha256_present = tarball.and_then(|tb| tb.sha256.as_deref()).is_some();
                (
                    Self::create_commands(
                        tap,
                        &t.package,
                        &t.version,
                        &workdir.to_string_lossy(),
                        sha256_present,
                    ),
                    vec![format!(
                        "create path: `{}` has no `{}.rb` yet — generating the initial \
                         source-build formula and opening a{} PR",
                        tap,
                        t.package,
                        if sha256_present { "" } else { " draft" }
                    )],
                )
            }
            FormulaPath::TapWrite => {
                // `tap` is Some whenever resolve_path returned TapWrite.
                let tap = self
                    .tap(ctx.artifacts.homebrew.as_ref())
                    .unwrap_or_default();
                let workdir = Self::fresh_workdir(&t.package, &t.version);
                let mut notes = vec![format!(
                    "tap-write path: `{}` already serves `{}.rb` — rendering the updated \
                     formula and pushing it directly to the tap's default branch (no \
                     `brew`, no PR)",
                    tap, t.package,
                )];
                // Surface the fail-closed requirement rather than let publish fail
                // late: this path refuses to push without a verified 64-hex sha256,
                // which the coordinator threads only in the post-tag dist phase.
                if tarball.and_then(|tb| tb.sha256.as_deref()).is_none() {
                    notes.push(
                        "publish will require a verified post-tag sha256 (absent in this \
                         pre-tag preview); the coordinator supplies it after the tag is pushed"
                            .to_string(),
                    );
                }
                (
                    Self::update_commands(tap, &t.package, &t.version, &workdir.to_string_lossy()),
                    notes,
                )
            }
            FormulaPath::BumpPr => (
                vec![self.bump_command(tarball, &t.package)],
                vec![
                    "bump-PR path: no configured tap — `brew bump-formula-pr` opens a reviewed PR"
                        .to_string(),
                ],
            ),
        };
        match tarball {
            Some(tb) => {
                // The bump-PR path lets `brew` derive the digest from `--url`; the
                // create / tap-write paths get a verified digest threaded post-tag.
                let sha = tb.sha256.as_deref().unwrap_or({
                    if path == FormulaPath::BumpPr {
                        "(computed by brew from --url)"
                    } else {
                        "(resolved and verified by the coordinator post-tag)"
                    }
                });
                notes.push(format!("url: {} ; sha256: {sha}", tb.url));
            }
            None => notes
                .push("source tarball url is resolved by the coordinator at cut time".to_string()),
        }
        Ok(DryRunReport {
            adapter: self.adapter,
            planned_commands,
            notes,
        })
    }

    fn build(
        &self,
        _ctx: &EffectCtx<'_>,
        _t: &AdapterTarget,
    ) -> Result<BuildArtifacts, AdapterError> {
        // Homebrew has no build phase of its own — it repackages an existing
        // release artifact. Return an empty manifest rather than shelling out.
        Ok(BuildArtifacts {
            adapter: self.adapter,
            artifacts: vec![],
            notes: vec!["homebrew has no build phase (formula create/update only)".to_string()],
        })
    }

    fn publish(
        &self,
        ctx: &EffectCtx<'_>,
        t: &AdapterTarget,
    ) -> Result<PublishReceipt, AdapterError> {
        // PER-TARGET IRREVERSIBLE (pushes a formula to the tap, or opens a PR).
        match self.resolve_path(ctx, t)? {
            FormulaPath::Create => {
                let tap = self
                    .tap(ctx.artifacts.homebrew.as_ref())
                    .expect("resolve_path returns Create only when a tap is configured");
                Self::run_create(ctx, t, tap)
            }
            FormulaPath::TapWrite => {
                let tap = self
                    .tap(ctx.artifacts.homebrew.as_ref())
                    .expect("resolve_path returns TapWrite only when a tap is configured");
                Self::run_tap_write(ctx, t, tap)
            }
            FormulaPath::BumpPr => {
                let cmd = self.bump_command(ctx.artifacts.source_tarball.as_ref(), &t.package);
                let outputs = run_all(ctx, &[cmd])?;
                let remote_url = outputs.last().and_then(|output| {
                    output
                        .stdout
                        .lines()
                        .rev()
                        .map(str::trim)
                        .find(|line| line.starts_with("https://"))
                        .map(str::to_string)
                });
                Ok(make_receipt(ctx, t, None, remote_url))
            }
        }
    }

    fn verify(
        &self,
        ctx: &EffectCtx<'_>,
        receipt: &PublishReceipt,
    ) -> Result<VerifyOutcome, AdapterError> {
        // The receipt records the tap URL produced by the publish path; use it,
        // rather than re-reading the mutable contract, to locate the artifact.
        let Some(url) = receipt.remote_url.as_deref() else {
            return Ok(VerifyOutcome::Unknown);
        };
        let parts: Vec<_> = url.split('/').collect();
        let Some(github) = parts.iter().position(|part| *part == "github.com") else {
            return Ok(VerifyOutcome::Unknown);
        };
        let (Some(owner), Some(repo)) = (parts.get(github + 1), parts.get(github + 2)) else {
            return Ok(VerifyOutcome::Unknown);
        };
        Ok(verify_tap_formula(
            ctx,
            &format!("{owner}/{repo}"),
            &receipt.package,
            &receipt.version,
            self.adapter == Adapter::HomebrewTap,
            None,
        ))
    }

    fn timeout(&self) -> Duration {
        Duration::from_secs(600)
    }
}

/// Read a tap formula and verify the released version plus each expected platform
/// stanza. `require_marker` is true only for engine-owned `homebrew-tap` formulas:
/// cargo-dist's CI-owned formulas have no shipshape marker by design.
pub(crate) fn verify_tap_formula(
    ctx: &EffectCtx<'_>,
    tap: &str,
    package: &str,
    version: &str,
    require_marker: bool,
    expected_platforms: Option<&[String]>,
) -> VerifyOutcome {
    // A delegated formula is written asynchronously after the tag. Give each poll
    // a distinct URL so a cached 404 or prior formula body cannot outlive the CI
    // write for the whole bounded verify window.
    let raw = format!(
        "https://raw.githubusercontent.com/{tap}/HEAD/Formula/{package}.rb?shipshape_verify={}",
        ctx.clock.now_unix()
    );
    let (status, body) = match ctx.registry.http_get(&raw) {
        Ok(response) => response,
        Err(_) => return VerifyOutcome::Unknown,
    };
    if status == 404 {
        return VerifyOutcome::Missing;
    }
    if status != 200 {
        return VerifyOutcome::Unknown;
    }
    let formula = match String::from_utf8(body) {
        Ok(formula) => formula,
        Err(_) => return VerifyOutcome::Unknown,
    };
    if require_marker && !formula_carries_marker(formula.as_bytes()) {
        return VerifyOutcome::Missing;
    }
    if !formula
        .lines()
        .any(|line| line.trim() == format!("version \"{version}\""))
    {
        return VerifyOutcome::Missing;
    }
    // Every Homebrew-servable platform declared by a stored plan must retain a
    // URL+sha stanza. Pre-plan-store journals cannot recover that exact set; for
    // them require at least one complete supported-platform stanza rather than
    // falling back to the old structurally-unobservable `Unknown` result.
    let expected = expected_platforms
        .filter(|platforms| !platforms.is_empty())
        .or_else(|| {
            ctx.artifacts
                .homebrew
                .as_ref()
                .map(|homebrew| homebrew.platforms.as_slice())
        });
    let observed = [
        "if OS.mac? && Hardware::CPU.arm?",
        "if OS.mac? && Hardware::CPU.intel?",
        "if OS.linux? && Hardware::CPU.arm?",
        "if OS.linux? && Hardware::CPU.intel?",
    ];
    let conditions: Vec<&str> = match expected {
        Some(platforms) => platforms
            .iter()
            .filter_map(|triple| homebrew_platform_condition(triple))
            .collect(),
        None => observed
            .into_iter()
            .filter(|condition| formula.contains(condition))
            .collect(),
    };
    if conditions.is_empty() {
        return VerifyOutcome::Missing;
    }
    for condition in conditions {
        if !formula_has_platform_stanza(&formula, condition) {
            return VerifyOutcome::Missing;
        }
    }
    VerifyOutcome::Matches
}

/// Whether a formula contains a URL and checksum in the exact block for
/// `condition`. shipshape's renderer uses one combined condition, while cargo-dist
/// 0.28.x nests a CPU block inside an OS block and later repeats combined guards
/// in `install` without download fields. Block-scoped matching prevents those
/// later guards from shadowing a complete nested download stanza.
fn formula_has_platform_stanza(formula: &str, condition: &str) -> bool {
    fn block_for_condition<'a>(lines: &'a [&str], condition: &str) -> Option<&'a [&'a str]> {
        let start = lines.iter().position(|line| line.trim() == condition)?;
        let indent = lines[start].len() - lines[start].trim_start().len();
        let end = lines[start + 1..].iter().position(|line| {
            line.trim() == "end" && line.len() - line.trim_start().len() == indent
        })?;
        Some(&lines[start + 1..start + 1 + end])
    }

    fn has_url_and_sha(lines: &[&str]) -> bool {
        lines
            .iter()
            .any(|line| line.trim_start().starts_with("url \""))
            && lines
                .iter()
                .any(|line| line.trim_start().starts_with("sha256 \""))
    }

    let (os, cpu) = match condition {
        "if OS.mac? && Hardware::CPU.arm?" => ("if OS.mac?", "if Hardware::CPU.arm?"),
        "if OS.mac? && Hardware::CPU.intel?" => ("if OS.mac?", "if Hardware::CPU.intel?"),
        "if OS.linux? && Hardware::CPU.arm?" => ("if OS.linux?", "if Hardware::CPU.arm?"),
        "if OS.linux? && Hardware::CPU.intel?" => ("if OS.linux?", "if Hardware::CPU.intel?"),
        _ => return false,
    };
    let lines: Vec<&str> = formula.lines().collect();

    // Prefer cargo-dist's nested download shape. Its later install method uses
    // combined guards with the same platform identity but deliberately has no URL.
    if let Some(os_block) = block_for_condition(&lines, os) {
        if let Some(cpu_block) = block_for_condition(os_block, cpu) {
            if has_url_and_sha(cpu_block) {
                return true;
            }
        }
    }

    block_for_condition(&lines, condition).is_some_and(has_url_and_sha)
}

/// Render a prebuilt-archive Homebrew formula. The archives are fetched and
/// hashed by the post-tag coordinator before this is called; there is deliberately
/// no source-build fallback.
pub(super) fn render_formula(
    name: &str,
    version: &str,
    homepage_slug: Option<&str>,
    description: Option<&str>,
    assets: &[HomebrewAsset],
    license: Option<&str>,
) -> String {
    let class = formula_class(name);
    let name_lit = ruby_escape(name);
    let homepage = homepage_slug.map_or_else(
        || "https://github.com".to_string(),
        |s| format!("https://github.com/{s}"),
    );
    let desc = ruby_escape(description.unwrap_or(name));
    let mut platforms = String::new();
    for asset in assets {
        let Some(condition) = homebrew_platform_condition(&asset.triple) else {
            continue;
        };
        let _ = write!(
            platforms,
            "  {condition}\n    url \"{}\"\n    sha256 \"{}\"\n  end\n",
            ruby_escape(&asset.url),
            ruby_escape(&asset.sha256)
        );
    }
    let license_line = license
        .map(|l| format!("  license \"{}\"\n", ruby_escape(l)))
        .unwrap_or_default();
    let marker = format!("{FORMULA_MARKER_PREFIX} {FORMULA_TEMPLATE_VERSION})");
    format!("{marker}\nclass {class} < Formula\n  desc \"{desc}\"\n  homepage \"{}\"\n  version \"{}\"\n{platforms}{license_line}\n  def install\n    bin.install \"{name_lit}\"\n  end\n\n  test do\n    system bin/\"{name_lit}\", \"version\"\n  end\nend\n", ruby_escape(&homepage), ruby_escape(version))
}

/// Return the Homebrew formula condition for a cargo-dist target triple, if
/// Homebrew can serve it. Other distribution platforms, such as Windows, are
/// served through the GitHub Release instead.
pub(crate) fn homebrew_platform_condition(triple: &str) -> Option<&'static str> {
    match triple {
        "aarch64-apple-darwin" => Some("if OS.mac? && Hardware::CPU.arm?"),
        "x86_64-apple-darwin" => Some("if OS.mac? && Hardware::CPU.intel?"),
        "aarch64-unknown-linux-musl" => Some("if OS.linux? && Hardware::CPU.arm?"),
        "x86_64-unknown-linux-musl" => Some("if OS.linux? && Hardware::CPU.intel?"),
        _ => None,
    }
}

/// Return only a complete, checked archive set. A default-branch tap is user-facing,
/// so a missing, duplicate, or malformed release asset is a hard failure rather than
/// a source-build fallback or an unchecked formula.
fn verified_assets<'a>(ctx: &'a EffectCtx<'a>) -> Result<&'a [HomebrewAsset], AdapterError> {
    let assets = &ctx.artifacts.homebrew_assets;
    if assets.is_empty()
        || assets
            .iter()
            .any(|a| !is_sha256_hex(&a.sha256) || a.url.is_empty())
    {
        return Err(AdapterError::Command {
            command: "homebrew formula update".into(),
            code: None,
            stderr: "refusing to write a Homebrew formula without verified prebuilt release assets and SHA-256 checksums".into(),
        });
    }
    Ok(assets)
}

/// Escape a value for inclusion in a Ruby double-quoted string literal:
/// backslashes first, then double quotes, then `#`. Prevents a contract-supplied
/// `"` or `\` from terminating the literal, and — critically — escaping `#` closes
/// Ruby's `#{…}` string **interpolation**, which would otherwise evaluate arbitrary
/// Ruby (code execution when `brew` loads the formula) from a value like
/// `#{system('…')}`. `\#` renders as a literal `#`, so escaping every `#` is safe.
fn ruby_escape(s: &str) -> String {
    s.replace('\\', "\\\\")
        .replace('"', "\\\"")
        .replace('#', "\\#")
}

/// Surgically update **only** the double-quoted value of the single `url "…"` and
/// `sha256 "…"` stanzas of a hand-maintained (unmarked) formula, preserving every
/// other byte verbatim — `depends_on`s, `resource` blocks, `caveats`, `service`,
/// custom `test`, comments, blank lines, the file's indentation, any trailing
/// stanza options (`url "…", using: :git`, `sha256 "…" => :arm64`), inline `#`
/// comments, and the original line endings (LF or CRLF).
///
/// **Only the quoted value is rewritten, in place** (not the whole line): the bytes
/// before the opening quote (indent + keyword + spacing) and everything after the
/// closing quote are copied through untouched. This is what keeps trailing options,
/// comments, and a CRLF `\r` intact, so an already-current formula stays a
/// byte-for-byte no-op.
///
/// **Fail-closed.** The tap-write path pushes straight to the tap's default branch,
/// so this refuses to guess. A stanza matches only Homebrew's canonical
/// `<indent><keyword> "<value>"` shape (keyword as a whole token, its argument the
/// immediately-following double-quoted literal); anything else — `url = x`,
/// `url(...)`, a parenthesized/heredoc form — simply does not match. It then requires
/// **exactly one** `url` line and **exactly one** `sha256` line, and every matched
/// literal to be properly closed. Zero matches (no editable stanza), multiple matches
/// (a `resource` block's own pair, an arch-conditional bottle/`sha256` set), or an
/// unterminated literal (a continuation line) is a hard [`AdapterError`] — never a
/// partial or ambiguous rewrite. The interpolated `url`/`sha256` are [`ruby_escape`]d
/// exactly as the full renderer escapes them.
#[allow(dead_code)]
fn surgical_url_sha_edit(current: &str, url: &str, sha256: &str) -> Result<String, AdapterError> {
    // A canonical stanza line: `<indent><keyword> "<value>"…` — the keyword is a
    // whole token (whitespace follows it, so `url` never matches `urls`/`url_x`), and
    // its argument is the immediately-following double-quoted literal (so `url = x`
    // and `url(...)` do not match and are left for the fail-closed hit-count guard).
    fn is_stanza_line(line: &str, keyword: &str) -> bool {
        let trimmed = line.trim_start();
        let Some(rest) = trimmed.strip_prefix(keyword) else {
            return false;
        };
        rest.starts_with(|c: char| c.is_ascii_whitespace()) && rest.trim_start().starts_with('"')
    }

    // Replace the contents of the first double-quoted literal on `line` with
    // `new_value` (ruby-escaped), preserving the prefix (indent + keyword + spacing)
    // and the entire suffix after the closing quote (trailing options, `# comments`,
    // and the CRLF `\r`). Returns `None` if the literal is not closed (a malformed or
    // continuation line) so the caller can fail closed. The closing quote is the next
    // un-escaped `"`; `"`/`\` are ASCII, so byte scanning never splits a UTF-8 char.
    fn rewrite_quoted_value(line: &str, new_value: &str) -> Option<String> {
        let open = line.find('"')?;
        let after = &line[open + 1..];
        let bytes = after.as_bytes();
        let mut i = 0;
        let close = loop {
            match bytes.get(i)? {
                b'\\' => i += 2, // skip the escaped char (a trailing `\` runs off → None)
                b'"' => break i,
                _ => i += 1,
            }
        };
        let prefix = &line[..open];
        let suffix = &after[close + 1..];
        Some(format!("{prefix}\"{}\"{suffix}", ruby_escape(new_value)))
    }

    let mut url_hits = 0usize;
    let mut sha_hits = 0usize;
    let mut malformed = false;
    // Preserve the input's exact line structure — indentation, blank lines, a
    // trailing newline (a final empty segment rejoins to reproduce it), and each
    // line's own `\r` — by splitting on '\n' and writing back with '\n'.
    let mut rebuilt = String::with_capacity(current.len() + 64);
    for (idx, line) in current.split('\n').enumerate() {
        if idx > 0 {
            rebuilt.push('\n');
        }
        let (hits, new_value) = if is_stanza_line(line, "url") {
            (Some(&mut url_hits), url)
        } else if is_stanza_line(line, "sha256") {
            (Some(&mut sha_hits), sha256)
        } else {
            (None, "")
        };
        if let Some(counter) = hits {
            *counter += 1;
            if let Some(rewritten) = rewrite_quoted_value(line, new_value) {
                rebuilt.push_str(&rewritten);
            } else {
                malformed = true;
                rebuilt.push_str(line);
            }
        } else {
            rebuilt.push_str(line);
        }
    }

    if url_hits != 1 || sha_hits != 1 || malformed {
        return Err(AdapterError::Command {
            command: "homebrew formula update".into(),
            code: None,
            stderr: format!(
                "refusing to update the hand-maintained tap formula: it carries no shipshape \
                 ownership marker, and a safe surgical `url`/`sha256` edit needs exactly one \
                 canonical `url \"…\"` line and one `sha256 \"…\"` line with a properly closed \
                 literal, but found {url_hits} `url` and {sha_hits} `sha256`{} — update the \
                 formula by hand, or add the shipshape marker \
                 (`{FORMULA_MARKER_PREFIX} {FORMULA_TEMPLATE_VERSION})`) as the first line to \
                 opt into full regeneration",
                if malformed {
                    " (a matched stanza's quoted value was not closed on its line)"
                } else {
                    ""
                }
            ),
        });
    }
    Ok(rebuilt)
}

/// Whether `s` is a syntactically valid SHA-256 digest: exactly 64 ASCII hex
/// characters. The tap-write fail-closed check rejects an absent OR malformed digest
/// (`Some("")`, `Some("garbage")`, a wrong length) — `Some(_)` alone is not proof of
/// a verified hash.
fn is_sha256_hex(s: &str) -> bool {
    s.len() == 64 && s.bytes().all(|b| b.is_ascii_hexdigit())
}

/// Reject a package name that could escape the `Formula/` directory or the git
/// pathspec when interpolated into `Formula/<name>.rb` / `<name>.rb` — an empty
/// name, a path separator (`/`, `\`), a `..` traversal component, or a leading `.`.
/// The name is otherwise trusted (it reaches `desc`/`bin` via [`ruby_escape`]); this
/// guards only the filesystem/path uses.
fn validate_package_name(name: &str) -> Result<(), AdapterError> {
    let bad = name.is_empty()
        || name.starts_with('.')
        || name.contains('/')
        || name.contains('\\')
        || name.split(['/', '\\']).any(|seg| seg == "..");
    if bad {
        return Err(AdapterError::Filesystem {
            path: name.to_string(),
            source: "invalid Homebrew package name — must not be empty, start with `.`, or \
                     contain a path separator or `..` traversal component"
                .into(),
        });
    }
    Ok(())
}

/// Homebrew's formula class name for `name`: alphanumeric runs capitalised and
/// concatenated (`my-tool` → `MyTool`, `shipshape` → `Shipshape`). A small, faithful
/// subset of Homebrew's `Formulary.class_s` — enough for the ordinary tap names
/// this generator targets.
///
/// A Ruby constant may not begin with a digit, so a leading-digit name is
/// prefixed with `X` (as Homebrew itself does: `2fa` → `X2fa`); a name that
/// reduces to nothing falls back to `Formula` so the output is always a legal
/// constant rather than a syntax error.
fn formula_class(name: &str) -> String {
    let mut out = String::new();
    for segment in name.split(|c: char| !c.is_ascii_alphanumeric()) {
        let mut chars = segment.chars();
        if let Some(first) = chars.next() {
            out.extend(first.to_uppercase());
            out.push_str(chars.as_str());
        }
    }
    if out.is_empty() {
        return "Formula".to_string();
    }
    if out.starts_with(|c: char| c.is_ascii_digit()) {
        out.insert(0, 'X');
    }
    out
}

#[cfg(test)]
mod platform_stanza_tests {
    use super::{formula_carries_marker, formula_has_platform_stanza};

    #[test]
    fn current_and_legacy_ownership_markers_are_both_trusted() {
        assert!(formula_carries_marker(
            b"# Generated by shipshape; do not edit by hand (template-version: 2)\nclass Tool"
        ));
        assert!(formula_carries_marker(
            b"# Generated by ossctl; do not edit by hand (template-version: 2)\nclass Tool"
        ));
        assert!(!formula_carries_marker(
            b"# hand maintained\n# Generated by ossctl; do not edit by hand (template-version: 2)"
        ));
    }

    const CARGO_DIST_0_28_2_FORMULA: &str =
        include_str!("../fixtures/project-canon-cargo-dist-0.28.2.rb");

    #[test]
    fn cargo_dist_nested_downloads_are_not_shadowed_by_install_guards() {
        for condition in [
            "if OS.mac? && Hardware::CPU.arm?",
            "if OS.linux? && Hardware::CPU.arm?",
            "if OS.linux? && Hardware::CPU.intel?",
        ] {
            assert!(
                formula_has_platform_stanza(CARGO_DIST_0_28_2_FORMULA, condition),
                "cargo-dist 0.28.2 formula should contain {condition}"
            );
        }
    }

    #[test]
    fn a_matching_install_guard_without_a_download_stanza_is_not_enough() {
        let formula = r#"class Tool < Formula
  version "1.0.0"
  def install
    if OS.linux? && Hardware::CPU.arm?
      bin.install "tool"
    end
  end
end
"#;
        assert!(!formula_has_platform_stanza(
            formula,
            "if OS.linux? && Hardware::CPU.arm?"
        ));
    }
}