release_kit/commands/

init.rs

//! `rk init`: land a technology's deterministic files into a target.
//!
//! A front over the direct writer: the target's evidence is gathered
//! once, this binary's projection is computed from its embedded sources,
//! every destination is decided by elementary ownership, and on `--apply`
//! the writer lands the files and the receipt last under one target lock.
//! Dry-run by default: without `--apply` the destinations and what a
//! fresh production invocation would do with them are listed and nothing
//! is touched; `rk stage` is the full-byte comparison surface, and
//! `--stage` lands the answers a stage resolved. A whole-file destination
//! present on disk with no receipt naming it is a conflict: it refuses
//! before any write, every collision collected in one pass, unless
//! `--replace` names it, which saves its bytes first.
//!
//! SATISFIES landing:a-landing-leaves-a-record
//! SATISFIES landing:a-missing-receipt-is-a-classification

use camino::Utf8Path;
use serde::Serialize;

use crate::cli::init::InitArgs;
use crate::diagnostic::{Diagnostic, Reason};
use crate::embedded;
use crate::error::RkError;
use crate::held;
use crate::landing::apply::{self, Action, Collision, Prepared, Replaced};
use crate::landing::manifest::{self, Provider};
use crate::landing::{self, lock};
use crate::output::Output;
use crate::profile::{CapabilityRequests, GitWorkflow, ProfileSnapshot};
use crate::stage::CapabilityNote;

/// One destination and what happened to it.
#[derive(Debug, Serialize)]
struct FileEntry {
    /// The destination, relative to the target.
    path: String,
    /// The declared ownership kind.
    kind: &'static str,
    /// `created`, `replaced`, `matched`, `preserved`, `drift`, `released`,
    /// or `collision` in a preview.
    action: &'static str,
}

/// One sentinel line left for the operator.
#[derive(Debug, Serialize)]
struct SentinelEntry {
    /// The landed file holding the sentinel.
    path: String,
    /// The 1-indexed line.
    line: usize,
    /// The line's text, trimmed.
    text: String,
}

/// The machine form of a landing report.
#[derive(Debug, Serialize)]
struct Report {
    /// The shape version of this document.
    schema: &'static str,
    /// `preview` or `apply`.
    mode: &'static str,
    /// The target directory.
    target: String,
    /// What the project is.
    profile: ProfileSnapshot,
    /// How topic branches reach the trunk.
    git: GitWorkflow,
    /// Which optional products the target requested.
    capabilities: CapabilityRequests,
    /// The resolved project path, where detection or `--repo` named one.
    #[serde(skip_serializing_if = "Option::is_none")]
    repo: Option<String>,
    /// Every capability, in catalog order, with its status.
    selection: Vec<CapabilityNote>,
    /// Why the selected release automation cannot land in this release,
    /// absent where it can or none is selected. A preview reports it and
    /// exits 0; the apply refuses on it.
    #[serde(skip_serializing_if = "Option::is_none")]
    release_unavailable: Option<String>,
    /// Why the provider's licence condition refuses this target, absent
    /// where no condition applies or the licence satisfies it. A preview
    /// reports it and exits 0; the apply refuses on it.
    #[serde(skip_serializing_if = "Option::is_none")]
    licence_refusal: Option<String>,
    /// The Nix destinations this target could not take, each with why;
    /// absent where nothing was withheld.
    #[serde(skip_serializing_if = "Option::is_none")]
    withheld: Option<Vec<landing::Withheld>>,
    /// The destinations a production landing refuses as they stand;
    /// absent where there is none. A preview lists them and exits 0.
    #[serde(skip_serializing_if = "Option::is_none")]
    collisions: Option<Vec<Collision>>,
    /// The conflicts `--replace` named, each with where its bytes were
    /// saved; empty where none was named.
    replaced: Vec<Replaced>,
    config: crate::config::Plan,
    /// Every destination, with its kind and action.
    files: Vec<FileEntry>,
    /// The sentinels an apply left to fill; absent in a preview.
    #[serde(skip_serializing_if = "Option::is_none")]
    sentinels: Option<Vec<SentinelEntry>>,
    /// What plausibly follows.
    next: Vec<String>,
}

/// The withheld list a report carries.
fn withheld_of(prepared: &Prepared) -> Option<Vec<landing::Withheld>> {
    let withheld: Vec<landing::Withheld> = prepared
        .projection
        .omissions
        .iter()
        .map(|omission| landing::Withheld {
            path: omission.destination.clone(),
            reason: omission.reason.clone(),
        })
        .collect();
    (!withheld.is_empty()).then_some(withheld)
}

/// Land the files for `--tech` into `--target`.
///
/// # Errors
///
/// Returns [`RkError::Usage`] for an unknown technology or pair,
/// [`RkError::Refusal`] when the target is missing, already carries a
/// receipt, or a destination collides, [`RkError::Missing`] when an apply
/// resolves no repository, and [`RkError::Io`] on filesystem failure.
pub fn run(args: &InitArgs) -> Result<(), RkError> {
    let out = Output::new(args.json);
    if !args.target.is_dir() {
        return Err(RkError::refusal(
            Diagnostic::new(
                Reason::TargetNotFound,
                format!(
                    "target {} is not a directory; nothing was written",
                    args.target
                ),
            )
            .expected("an existing directory to land into")
            .target_state("unchanged"),
        ));
    }
    // An apply takes the target before it reads anything of it, the
    // receipt and the configuration included, so the world the decisions
    // describe is the world the writer writes. A preview holds nothing.
    let lock = args
        .apply
        .then(|| lock::acquire(&args.target))
        .transpose()?;
    // One directory descriptor, held from here through the receipt write:
    // every read and every write goes through it, so a root exchanged
    // under the pathname later receives nothing.
    // The proof's pause: the lock is held and the directory is not yet.
    held::pause(apply::PAUSE_VAR, "locked", "proceed-locked");
    let held = lock.as_ref().map_or_else(
        || apply::Held::open(&args.target),
        |lock| apply::Held::open_locked(&args.target, lock),
    )?;
    // The proof's pause: the target is held, and nothing has been read.
    held::pause(apply::PAUSE_VAR, "held", "proceed-held");
    let config = crate::config::load(held.base().as_std_path())?;
    let purpose = if args.apply {
        landing::Purpose::Init
    } else {
        landing::Purpose::Preview
    };
    let params = if let Some(root) = args.stage.as_deref() {
        if answered(args) {
            return Err(crate::stage::read::answered_twice());
        }
        let canonical = std::fs::canonicalize(args.target.as_std_path())?;
        let receipt = crate::stage::read::load(root, &canonical)?;
        let params = landing::Params::resolve(
            held.base(),
            &crate::stage::read::inputs(&receipt.parameters),
            config.as_ref(),
            None,
            purpose,
        )?;
        crate::stage::read::confirm(&params, &receipt, root)?;
        params
    } else {
        landing::Params::resolve(
            held.base(),
            &landing::Inputs {
                nix: args.nix_packaging.then_some(true),
                reporting_policy: args.reporting_policy.then_some(true),
                scorecard: args.scorecard.then_some(true),
                workflow_guards: args.workflow_guards.then_some(true),
                code_scanning: args
                    .code_scanning
                    .as_deref()
                    .map(Provider::parse)
                    .transpose()?,
                ..args.profile.inputs()?
            },
            config.as_ref(),
            None,
            purpose,
        )?
    };
    if let Some(lock) = lock {
        refuse_a_recorded_target(&held)?;
        let mut prepared = apply::prepare(&held, None, &params, config.as_ref())?;
        apply::name_replacements(&mut prepared, &args.replace)?;
        let landed = apply::land(&held, None, &prepared, apply::Origin::Init, &lock)?;
        drop(lock);
        report_apply(out, args, &held, &params, &prepared, &landed)
    } else {
        let mut prepared = apply::prepare(&held, None, &params, config.as_ref())?;
        apply::name_replacements(&mut prepared, &args.replace)?;
        let repo = (params.repo() != landing::REPO_PLACEHOLDER && !params.repo().is_empty())
            .then(|| params.repo().to_owned());
        if params.repo() == landing::REPO_PLACEHOLDER {
            out.frame(
                "note: no repository detected; an apply derives the owner from --repo <path>",
            );
        }
        preview(out, args, &params, repo, &prepared)
    }
}

/// The report's shape version.
const SCHEMA: &str = "rk.init/11";

/// Whether any answer flag was given, which `--stage` refuses beside it.
const fn answered(args: &InitArgs) -> bool {
    !args.profile.is_empty()
        || args.nix_packaging
        || args.reporting_policy
        || args.scorecard
        || args.workflow_guards
        || args.code_scanning.is_some()
}

/// The capability notes a report carries, in catalog order.
fn selection_of(prepared: &Prepared) -> Vec<CapabilityNote> {
    prepared
        .projection
        .capabilities
        .iter()
        .map(|selection| CapabilityNote::of(selection, &prepared.projection))
        .collect()
}

/// The human lines naming every capability's answer.
pub(crate) fn describe_selection(out: Output, prepared: &Prepared) {
    for note in selection_of(prepared) {
        let mut line = format!("capability {}: {}", note.id, note.status);
        if let Some(reason) = &note.reason {
            line.push_str(" (");
            line.push_str(reason);
            line.push(')');
        }
        out.result_line(line);
        if let Some(action) = &note.action {
            out.result_line(format!("  action: {action}"));
        }
    }
}

/// List every destination with what a production landing would do, and
/// write nothing.
#[allow(
    clippy::too_many_lines,
    reason = "one pass prints the profile, the selection, every decision, and the follow-up, and splitting it would separate a line from the value behind it"
)]
fn preview(
    out: Output,
    args: &InitArgs,
    params: &landing::Params,
    repo: Option<String>,
    prepared: &Prepared,
) -> Result<(), RkError> {
    let flags = params.canonical_flags();
    let flags = if params.forge().is_some() && repo.is_none() {
        format!("{flags} --repo <owner/name>")
    } else {
        flags
    };
    let capabilities = params.capability_flags();
    let mut next = vec![format!(
        "rk init{flags}{capabilities} --target {} --apply",
        args.target
    )];
    if let Some(reason) = prepared.projection.release_unavailable() {
        next.insert(
            0,
            format!("the apply refuses until the release automation resolves: {reason}"),
        );
    }
    if !prepared.collisions.is_empty() {
        next.insert(
            0,
            "answer each collision above: --replace <path> saves a copy of a conflict and replaces it; the apply refuses every one not named"
                .to_owned(),
        );
    }
    if let Some(reason) = prepared.projection.licence_refusal.as_deref() {
        next.insert(
            0,
            format!("the apply refuses until the licence condition is answered: {reason}"),
        );
    }
    next.push(format!(
        "rk stage --target {} stages the complete candidate for a byte comparison",
        args.target
    ));
    out.result_line(format!(
        "DRY RUN: rk init writes these files into {}; re-run with --apply",
        args.target
    ));
    out.result_line(format!(
        "profile: {}",
        crate::commands::profile::describe(
            params.profile(),
            params.git(),
            params.capabilities(),
            params.repo()
        )
    ));
    describe_selection(out, prepared);
    for decision in &prepared.decisions {
        out.result_line(format!(
            "{} {}",
            decision.action.as_str(),
            decision.destination
        ));
    }
    for collision in &prepared.collisions {
        out.result_line(format!(
            "collision {}: {}",
            collision.path, collision.reason
        ));
    }
    out.result_line(format!(
        "{} {}\n{}",
        prepared.config.action,
        crate::config::CONFIG_PATH,
        prepared.config.content
    ));
    for entry in &prepared.projection.omissions {
        out.result_line(format!("withheld {}: {}", entry.destination, entry.reason));
        if let Some(action) = &entry.action {
            out.result_line(format!("  action: {action}"));
        }
    }
    out.next(&next);
    out.emit(&Report {
        schema: SCHEMA,
        config: prepared.config.clone(),
        mode: "preview",
        target: args.target.to_string(),
        profile: params.profile().clone(),
        git: params.git().clone(),
        capabilities: params.capabilities().clone(),
        repo,
        selection: selection_of(prepared),
        release_unavailable: prepared.projection.release_unavailable().map(str::to_owned),
        licence_refusal: prepared.projection.licence_refusal.clone(),
        withheld: withheld_of(prepared),
        collisions: (!prepared.collisions.is_empty()).then(|| prepared.collisions.clone()),
        replaced: apply::previewed_replacements(prepared),
        files: prepared
            .decisions
            .iter()
            .map(|decision| FileEntry {
                path: decision.destination.clone(),
                kind: decision.kind.as_str(),
                action: decision.action.as_str(),
            })
            .chain(prepared.collisions.iter().map(|collision| FileEntry {
                path: collision.path.clone(),
                kind: landing::kind_of(&collision.path).map_or("unknown", landing::Kind::as_str),
                action: "collision",
            }))
            .collect(),
        sentinels: None,
        next,
    })
}

/// Report a landing the writer completed, with the judgment sentinels the
/// operator still owes.
#[allow(
    clippy::too_many_arguments,
    reason = "the report reads the landed files through the held target and names them by the path the operator gave, which are two arguments for one target"
)]
#[allow(
    clippy::too_many_lines,
    reason = "one pass reports the profile, the selection, every decision, and the sentinels the operator still owes"
)]
fn report_apply(
    out: Output,
    args: &InitArgs,
    held: &apply::Held,
    params: &landing::Params,
    prepared: &Prepared,
    landed: &apply::Landed,
) -> Result<(), RkError> {
    let mut file_entries = Vec::new();
    let mut sentinels = Vec::new();
    out.result_line(format!(
        "profile: {}",
        crate::commands::profile::describe(
            params.profile(),
            params.git(),
            params.capabilities(),
            params.repo()
        )
    ));
    describe_selection(out, prepared);
    for decision in &prepared.decisions {
        out.result_line(describe(decision));
        if decision.action != Action::Released {
            let bytes =
                landing::read_recorded(held.base(), &decision.destination)?.unwrap_or_default();
            collect_sentinels(
                held.display(),
                &decision.destination,
                &bytes,
                &mut sentinels,
            );
        }
        file_entries.push(FileEntry {
            path: decision.destination.clone(),
            kind: decision.kind.as_str(),
            action: decision.action.as_str(),
        });
    }
    for entry in &prepared.projection.omissions {
        out.result_line(format!("withheld {}: {}", entry.destination, entry.reason));
        if let Some(action) = &entry.action {
            out.result_line(format!("  action: {action}"));
        }
    }
    out.result_line(format!(
        "{} {}",
        prepared.config.action,
        crate::config::CONFIG_PATH
    ));
    for (key, empty_line) in [
        ("setup.required_check", "required_check = \"\""),
        ("setup.bot.app_id", "app_id = \"\""),
    ] {
        if let Some((index, _)) = prepared
            .config
            .content
            .lines()
            .enumerate()
            .find(|(_, line)| line.starts_with(empty_line))
        {
            sentinels.push(SentinelEntry {
                path: crate::config::CONFIG_PATH.into(),
                line: index + 1,
                text: format!("set {key} before forge setup"),
            });
        }
    }
    for entry in &landed.replaced {
        if let Some(saved) = &entry.saved_to {
            out.result_line(format!("saved {} to {saved}", entry.path));
        }
    }
    out.result_line(format!("wrote {}", manifest::MANIFEST_PATH));
    debug_assert_eq!(
        landed.completed.last().map(String::as_str),
        Some(manifest::MANIFEST_PATH)
    );

    if sentinels.is_empty() {
        out.result_line("no sentinels to fill");
    } else {
        out.result_line("fill these sentinels before the workflow runs:");
        for sentinel in &sentinels {
            out.result_line(format!(
                "{}:{}: {}",
                sentinel.path, sentinel.line, sentinel.text
            ));
        }
    }
    let mut next = vec![
        if sentinels.is_empty() {
            "commit the landed files, the receipt included".to_owned()
        } else {
            "fill each sentinel above, then commit the landed files, the receipt included"
                .to_owned()
        },
        format!("rk status --target {} reports this landing", args.target),
    ];
    // Only an automatic release routes to the bot-operate chapter; an
    // external or none release has no bot to operate.
    if params.release_mode() == crate::profile::ReleaseMode::Automatic {
        next.push("rk method setup orders what follows".to_owned());
    } else if params.forge().is_some() {
        next.push("rk setup --target . previews the applicable forge steps".to_owned());
    }
    out.next(&next);
    out.emit(&Report {
        schema: SCHEMA,
        config: prepared.config.clone(),
        mode: "apply",
        target: args.target.to_string(),
        profile: params.profile().clone(),
        git: params.git().clone(),
        capabilities: params.capabilities().clone(),
        repo: (!params.repo().is_empty()).then(|| params.repo().to_owned()),
        selection: selection_of(prepared),
        release_unavailable: None,
        licence_refusal: prepared.projection.licence_refusal.clone(),
        withheld: withheld_of(prepared),
        collisions: None,
        replaced: landed.replaced.clone(),
        files: file_entries,
        sentinels: Some(sentinels),
        next,
    })
}

/// The human line for one decision.
pub(crate) fn describe(decision: &apply::Decision) -> String {
    match decision.action {
        Action::Preserved | Action::Drift => format!(
            "{} {} ({}, target-owned)",
            decision.action.as_str(),
            decision.destination,
            decision.kind.as_str()
        ),
        Action::Released => format!(
            "released {} (no longer produced; target-owned from this landing)",
            decision.destination
        ),
        Action::Matched => format!(
            "matched {} (already holds the candidate's bytes)",
            decision.destination
        ),
        Action::Created | Action::Replaced => {
            format!("{} {}", decision.action.as_str(), decision.destination)
        }
    }
}

/// A re-landing over an existing receipt is `rk upgrade`'s job, not a
/// second `rk init`.
fn refuse_a_recorded_target(held: &apply::Held) -> Result<(), RkError> {
    if landing::manifest::load(held.base())?.is_none() {
        return Ok(());
    }
    let target = held.display();
    Err(RkError::refusal(
        Diagnostic::new(
            Reason::StateDrift,
            format!(
                "{target} already carries {}, and nothing was written",
                manifest::MANIFEST_PATH
            ),
        )
        .expected("a target without a landing receipt")
        .action(format!(
            "rk upgrade --target {target} takes it to this binary's projection"
        ))
        .target_state("unchanged"),
    ))
}

/// Collect every judgment-sentinel line one landed file carries, so
/// nothing stays half-configured silently.
fn collect_sentinels(
    target: &Utf8Path,
    destination: &str,
    bytes: &[u8],
    found: &mut Vec<SentinelEntry>,
) {
    let text = String::from_utf8_lossy(bytes);
    for (idx, line) in text.lines().enumerate() {
        if line.contains(embedded::SENTINEL) {
            found.push(SentinelEntry {
                path: target.join(destination).to_string(),
                line: idx + 1,
                text: line.trim().to_owned(),
            });
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{FileEntry, Report, SentinelEntry};
    use crate::landing::CheckoutMode;
    use crate::landing::Integration;
    use crate::profile::{
        CapabilityRequests, GitWorkflow, ProfileSnapshot, ReleaseIntent, ReleaseMode,
    };
    use crate::stage::CapabilityNote;

    /// The complete `rk.init/11` shape, held by snapshot in both modes: a
    /// field rename or removal fails here and becomes a schema-version
    /// bump instead of a silent parser break at some agent.
    #[test]
    fn the_init_report_schema_snapshot_holds() {
        let apply = Report {
            schema: super::SCHEMA,
            config: crate::config::Plan {
                action: "added",
                changes: vec![],
                content: "schema_version = 2\n".into(),
            },
            mode: "apply",
            target: "/tmp/t".into(),
            profile: ProfileSnapshot {
                technologies: vec!["rust".into()],
                forge: Some("github".into()),
                release: ReleaseIntent {
                    mode: ReleaseMode::Automatic,
                    driver: Some("rust".into()),
                    style: Some(crate::landing::Style::Trunk),
                    line_prefix: Some("release/".into()),
                },
            },
            git: GitWorkflow {
                trunk: "master".into(),
                checkout_mode: CheckoutMode::LinkedWorktree,
                integration: Integration::Local,
            },
            capabilities: CapabilityRequests {
                nix_packaging: true,
                reporting_policy: true,
                scorecard: true,
                code_scanning: Some(crate::landing::Provider::CodeQl),
                workflow_guards: Some(false),
            },
            repo: Some("acme/widget".into()),
            selection: vec![CapabilityNote {
                id: "git.guards".into(),
                status: "selected".into(),
                reason: None,
                action: None,
                destinations: vec!["AGENTS.md".into()],
            }],
            release_unavailable: None,
            licence_refusal: None,
            withheld: Some(vec![crate::landing::Withheld {
                path: "flake.nix".into(),
                reason: "the target already carries flake.nix".into(),
            }]),
            collisions: None,
            replaced: vec![],
            files: vec![FileEntry {
                path: "release-plz.toml".into(),
                kind: "seeded",
                action: "created",
            }],
            sentinels: Some(vec![SentinelEntry {
                path: "/tmp/t/release-plz.toml".into(),
                line: 3,
                text: "# TODO(release-kit): keep false for a binary-only crate".into(),
            }]),
            next: vec!["commit the landed files, the receipt included".into()],
        };
        assert_eq!(
            serde_json::to_string(&apply).expect("a report serializes"),
            r##"{"schema":"rk.init/11","mode":"apply","target":"/tmp/t","profile":{"technologies":["rust"],"forge":"github","release":{"mode":"automatic","driver":"rust","style":"trunk","line_prefix":"release/"}},"git":{"trunk":"master","checkout_mode":"linked-worktree","integration":"local"},"capabilities":{"nix_packaging":true,"reporting_policy":true,"scorecard":true,"code_scanning":"codeql","workflow_guards":false},"repo":"acme/widget","selection":[{"id":"git.guards","status":"selected","destinations":["AGENTS.md"]}],"withheld":[{"path":"flake.nix","reason":"the target already carries flake.nix"}],"replaced":[],"config":{"action":"added","changes":[],"content":"schema_version = 2\n"},"files":[{"path":"release-plz.toml","kind":"seeded","action":"created"}],"sentinels":[{"path":"/tmp/t/release-plz.toml","line":3,"text":"# TODO(release-kit): keep false for a binary-only crate"}],"next":["commit the landed files, the receipt included"]}"##
        );
        let preview = Report {
            sentinels: None,
            repo: None,
            mode: "preview",
            capabilities: CapabilityRequests {
                nix_packaging: false,
                reporting_policy: false,
                scorecard: false,
                code_scanning: None,
                workflow_guards: Some(false),
            },
            selection: vec![],
            release_unavailable: Some(
                "the release automation at (python, gitlab) has no landable files".to_owned(),
            ),
            licence_refusal: Some("the target's Cargo.toml declares no license field".to_owned()),
            withheld: None,
            collisions: Some(vec![super::Collision {
                path: "SECURITY.md".into(),
                reason: "exists, and no receipt attributes it to release-kit".into(),
                replaceable: true,
            }]),
            replaced: vec![super::Replaced {
                path: "SECURITY.md".into(),
                saved_to: None,
            }],
            ..apply
        };
        assert_eq!(
            serde_json::to_string(&preview).expect("a report serializes"),
            r#"{"schema":"rk.init/11","mode":"preview","target":"/tmp/t","profile":{"technologies":["rust"],"forge":"github","release":{"mode":"automatic","driver":"rust","style":"trunk","line_prefix":"release/"}},"git":{"trunk":"master","checkout_mode":"linked-worktree","integration":"local"},"capabilities":{"nix_packaging":false,"reporting_policy":false,"scorecard":false,"workflow_guards":false},"selection":[],"release_unavailable":"the release automation at (python, gitlab) has no landable files","licence_refusal":"the target's Cargo.toml declares no license field","collisions":[{"path":"SECURITY.md","reason":"exists, and no receipt attributes it to release-kit","replaceable":true}],"replaced":[{"path":"SECURITY.md","saved_to":null}],"config":{"action":"added","changes":[],"content":"schema_version = 2\n"},"files":[{"path":"release-plz.toml","kind":"seeded","action":"created"}],"next":["commit the landed files, the receipt included"]}"#,
            "a preview omits the sentinels, the unresolved repo, and an empty withheld list rather than serializing null"
        );
    }
}