//! `rk status`: a target describes itself from its own disk.
//!
//! Read-only and offline: the receipt supplies what landed, this binary's
//! projection supplies what an upgrade would offer, the embedded registry
//! supplies the pin comparison, and no network is ever touched: a fetch
//! is a way for a status command to hang, fail on a network it should not
//! need, or leak a repository's existence. Status compares the current
//! target with this binary's projection and the receipt and nothing else;
//! it reads no stage and resolves no other release. Plain `rk status`
//! reports and exits 0 for every reportable state, drift and no-landing
//! included; `--check` computes the identical report and changes only
//! the final judgment, the one sanctioned bare exit 1.
//!
//! SATISFIES landing:status-judges-only-under-check
use serde::Serialize;
use crate::cli::status::StatusArgs;
use crate::diagnostic::{Diagnostic, Reason};
use crate::digest::Digest;
use crate::error::RkError;
use crate::landing::invariants::{self, InvariantFailure};
use crate::landing::manifest::{self, Alignment, Manifest};
use crate::landing::{self, Kind};
use crate::output::Output;
use crate::projection::{Candidate, Projection, ProjectionInput, TargetEvidence};
use crate::release::EmbeddedReleaseSource;
use crate::{embedded, registry};
/// The one seam name every front carries until the seam path goes: the
/// status verb reads the target and this binary's projection alone.
#[allow(dead_code, reason = "the seam path is deleted in a later phase")]
const SOURCE: EmbeddedReleaseSource = EmbeddedReleaseSource;
/// Drift counts by owned kind; `state` files are never compared.
#[derive(Debug, Serialize)]
struct Drift {
/// Edits to files release-kit owns — the violation class.
rendered: usize,
/// Edits to files the target owns — expected and informational.
seeded: usize,
}
/// One recorded pin that is behind this binary's registry.
#[derive(Debug, Serialize)]
struct StalePin {
/// The tool's registry name.
tool: String,
/// The version the landing recorded.
landed: String,
/// The version this binary's registry pins.
available: String,
}
/// Configuration is informational, independent of every drift comparison.
#[derive(Debug, serde::Serialize)]
struct ConfigState {
state: &'static str,
pending: Vec<String>,
}
fn config_state(config: Option<&crate::config::Config>, record: Option<&Manifest>) -> ConfigState {
let pending = config
.zip(record)
.map_or_else(Vec::new, |(config, record)| {
crate::config::pending(config, record)
});
ConfigState {
state: if config.is_none() {
"absent"
} else if pending.is_empty() {
"aligned"
} else {
"pending"
},
pending,
}
}
/// The machine form of a status report.
#[derive(Debug, Serialize)]
struct Report {
/// The shape version of this document.
schema: &'static str,
/// Whether a landing record exists; every other field needs one.
landed: bool,
config: ConfigState,
#[serde(skip_serializing_if = "Option::is_none")]
tech: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
forge: Option<String>,
/// The recorded working-copy mode.
#[serde(skip_serializing_if = "Option::is_none")]
workflow: Option<&'static str>,
/// The recorded release style; absent on a record predating it.
#[serde(skip_serializing_if = "Option::is_none")]
style: Option<&'static str>,
/// Whether the landing carries the Nix capability; a record predating
/// the parameter reads as opt-out.
#[serde(skip_serializing_if = "Option::is_none")]
nix: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
rk_version: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
binary_version: Option<&'static str>,
#[serde(skip_serializing_if = "Option::is_none")]
alignment: Option<Alignment>,
#[serde(skip_serializing_if = "Option::is_none")]
drift: Option<Drift>,
/// Recorded destinations absent from the disk.
#[serde(skip_serializing_if = "Option::is_none")]
missing: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
stale_pins: Option<Vec<StalePin>>,
/// Unresolved judgment sentinels across the landed files.
#[serde(skip_serializing_if = "Option::is_none")]
sentinels: Option<usize>,
/// Record-set disagreements between the recorded parameters'
/// projection and the recorded destinations — its own count, because
/// no file was edited and the kind counts must stay honest.
#[serde(skip_serializing_if = "Option::is_none")]
record_drift: Option<usize>,
/// Invariants a landed file's effective configuration violates —
/// judged, never rewritten, because the file stays the target's.
#[serde(skip_serializing_if = "Option::is_none")]
invariant_failures: Option<Vec<InvariantFailure>>,
/// How many destinations an upgrade would change: the count this
/// binary's payload projects under the recorded parameters against
/// what the record names. Zero means nothing to take, whatever the two
/// versions say. Absent on a landed target means this binary carries
/// no payload for the recorded pair and cannot answer.
#[serde(skip_serializing_if = "Option::is_none")]
pending: Option<usize>,
/// Present only under `--check`: what the judgment failed on.
#[serde(skip_serializing_if = "Option::is_none")]
violations: Option<Vec<String>>,
}
fn report_absent(
out: Output,
args: &StatusArgs,
config: Option<&crate::config::Config>,
) -> Result<(), RkError> {
out.result_line(format!("config: {}", config_state(config, None).state));
out.result_line(format!("no landing at {}", args.target));
out.next(&[
format!(
"rk init --tech <tech> --target {} lands the workflow",
args.target
),
format!(
"rk adopt --target {} records a landing made before the receipt existed",
args.target
),
format!(
"rk stage --target {} stages this binary's candidate; the rk-setup skill carries the best-effort migration",
args.target
),
]);
out.emit(&Report {
schema: "rk.status/9",
landed: false,
config: config_state(config, None),
tech: None,
forge: None,
workflow: None,
style: None,
nix: None,
rk_version: None,
binary_version: None,
alignment: None,
drift: None,
missing: None,
stale_pins: None,
sentinels: None,
record_drift: None,
invariant_failures: None,
pending: None,
violations: args.check.then(|| vec!["no landing".to_owned()]),
})?;
if args.check {
return Err(RkError::check_failed(
Diagnostic::new(
Reason::StateDrift,
format!("no landing at {}, and --check requires one", args.target),
)
.expected("a target carrying .release-kit/manifest.json")
.action("rk init lands the workflow; rk adopt records an existing landing; rk stage and the rk-setup skill carry the migration"),
));
}
Ok(())
}
/// What one pass over the record and the disk observed.
struct Observed {
drift_rendered: Vec<String>,
drift_seeded: Vec<String>,
/// Recorded block destinations whose recorded digest the record's own
/// parameters do not reproduce: the record was edited, not the file.
parameter_drift: Vec<String>,
/// Set differences between what the recorded parameters project —
/// the withhold judgment applied — and the destinations the record
/// names: a record whose parameters and file list disagree, whichever
/// of the two was edited or outgrown.
record_drift: Vec<String>,
missing: Vec<String>,
stale: Vec<StalePin>,
sentinels: Vec<(String, usize, String)>,
invariants: Vec<InvariantFailure>,
/// The destinations an upgrade would change, or `None` where this
/// binary carries no projection for the recorded pair and so cannot
/// say.
pending: Option<Vec<String>>,
}
/// Report the target's landing.
///
/// # Errors
///
/// Returns [`RkError::Missing`] for a target that is not a directory, the
/// record's own failure taxonomy for an unreadable or unknown record, and
/// [`RkError::CheckFailed`] under `--check` when the report holds a
/// violation.
pub fn run(args: &StatusArgs) -> Result<(), RkError> {
let out = Output::new(args.json);
if !args.target.is_dir() {
return Err(RkError::missing(
Diagnostic::new(
Reason::TargetNotFound,
format!("target {} is not a directory", args.target),
)
.expected("an existing repository to report on"),
));
}
let config = crate::config::load(args.target.as_std_path())?;
let Some(manifest) = manifest::load(&args.target)? else {
return report_absent(out, args, config.as_ref());
};
let config = config_state(config.as_ref(), Some(&manifest));
out.result_line(format!("config: {}", config.state));
for key in &config.pending {
out.result_line(format!(
"config pending: {key}; rk upgrade --apply takes it up"
));
}
let observed = observe(args, &manifest)?;
let alignment = manifest::alignment(&manifest.rk_version, env!("CARGO_PKG_VERSION"));
render_human(out, args, &manifest, alignment, &observed);
let violations = violations_of(&observed);
out.emit(&Report {
schema: "rk.status/9",
landed: true,
config,
tech: Some(manifest.tech),
forge: Some(manifest.forge),
workflow: Some(manifest.parameters.workflow.as_str()),
style: manifest.parameters.style.map(manifest::Style::as_str),
nix: Some(manifest.parameters.nix),
rk_version: Some(manifest.rk_version),
binary_version: Some(env!("CARGO_PKG_VERSION")),
alignment: Some(alignment),
drift: Some(Drift {
rendered: observed.drift_rendered.len() + observed.parameter_drift.len(),
seeded: observed.drift_seeded.len(),
}),
record_drift: Some(observed.record_drift.len()),
missing: Some(observed.missing.clone()),
stale_pins: Some(observed.stale),
sentinels: Some(observed.sentinels.len()),
invariant_failures: Some(observed.invariants),
pending: observed.pending.as_ref().map(Vec::len),
violations: args.check.then(|| violations.clone()),
})?;
if args.check && !violations.is_empty() {
return Err(RkError::check_failed(
Diagnostic::new(
Reason::StateDrift,
format!(
"the landing is not clean: {} violation{}",
violations.len(),
if violations.len() == 1 { "" } else { "s" }
),
)
.expected(
"no rendered drift, no missing recorded file, no unresolved sentinel, no invariant failure",
),
));
}
Ok(())
}
/// The check-mode violation lines: rendered drift, missing recorded
/// files, unresolved sentinels, and invariant failures — the closed set
/// `landing:status-judges-only-under-check` names.
fn violations_of(observed: &Observed) -> Vec<String> {
observed
.drift_rendered
.iter()
.map(|path| format!("rendered drift: {path}"))
.chain(
observed
.parameter_drift
.iter()
.map(|path| format!("parameter drift: {path}")),
)
.chain(
observed
.record_drift
.iter()
.map(|reason| format!("record drift: {reason}")),
)
.chain(
observed
.missing
.iter()
.map(|path| format!("missing: {path}")),
)
.chain(
observed
.sentinels
.iter()
.map(|(path, line, _)| format!("sentinel: {path}:{line}")),
)
.chain(
observed
.invariants
.iter()
.map(|failure| format!("invariant: {}: {}", failure.destination, failure.code)),
)
.collect()
}
/// One pass over the record and the disk: drift, missing files, stale
/// pins, and sentinels.
fn observe(args: &StatusArgs, manifest: &Manifest) -> Result<Observed, RkError> {
let mut observed = Observed {
drift_rendered: Vec::new(),
drift_seeded: Vec::new(),
parameter_drift: Vec::new(),
record_drift: Vec::new(),
missing: Vec::new(),
stale: Vec::new(),
sentinels: Vec::new(),
invariants: Vec::new(),
pending: None,
};
// One projection serves every reader below, because each asks what
// this binary makes of the recorded parameters at this target. A pair
// this binary does not carry cannot be projected at all: under a
// receipt this binary wrote that is a defect and still fails, and
// under a landing from another rk it is a fact to report.
let aligned =
manifest::alignment(&manifest.rk_version, env!("CARGO_PKG_VERSION")) == Alignment::Aligned;
let projected = match project(args, manifest) {
Ok(projection) => Some(projection),
Err(err) if aligned => return Err(err),
Err(_) => None,
};
for file in &manifest.files {
let Some(bytes) = landing::read_recorded(&args.target, &file.destination)? else {
observed.missing.push(file.destination.clone());
continue;
};
if Digest::of(&bytes) != file.sha256 {
match file.kind {
Kind::Rendered => observed.drift_rendered.push(file.destination.clone()),
Kind::Seeded => observed.drift_seeded.push(file.destination.clone()),
Kind::State => {}
}
}
observed.invariants.extend(invariants::failures(
&manifest.tech,
&manifest.forge,
&file.destination,
&bytes,
));
let text = String::from_utf8_lossy(&bytes);
for (idx, line) in text.lines().enumerate() {
if line.contains(embedded::SENTINEL) {
observed.sentinels.push((
file.destination.clone(),
idx + 1,
line.trim().to_owned(),
));
}
}
// A marked document's markers must be well formed even when its
// first block matches the receipt: a duplicate hook block still
// executes, so an ill-formed document reads as rendered drift,
// never as clean.
let defective = projected.as_ref().is_some_and(|projection| {
projection
.collisions
.iter()
.any(|collision| collision.destination == file.destination)
});
if defective && !observed.drift_rendered.contains(&file.destination) {
observed.drift_rendered.push(file.destination.clone());
}
}
// The cross-file step: a landed file can generate the artifact the
// forge actually executes, and the payload ships no copy of it, so no
// recorded digest sees the two disagree. The pair's own rule reads
// both off the target's disk.
observed.invariants.extend(invariants::target_failures(
&manifest.tech,
&manifest.forge,
&args.target,
));
if aligned && let Some(projection) = projected.as_ref() {
observe_parameter_drift(manifest, projection, &mut observed);
observe_record_set(manifest, projection, &mut observed.record_drift);
}
// What an upgrade would change, which is the only honest ground for
// telling an operator to run one. The recorded version says who wrote
// the receipt, and two releases apart can carry identical bytes for
// this pair, so it answers a different question and prompts nothing.
observed.pending = projected
.as_ref()
.map(|projection| pending_of(manifest, &projection.candidates));
// Stale means behind, not merely different: a landing from a newer rk
// can carry pins ahead of this binary's registry, and that is the
// alignment line's story, not a freshness complaint.
for (tool, landed) in &manifest.pins {
if let Some(available) = registry::version_of(tool)
&& manifest::version_is_newer(&available, landed)
{
observed.stale.push(StalePin {
tool: tool.clone(),
landed: landed.clone(),
available,
});
}
}
Ok(observed)
}
/// The receipt-consistency step over every rendered destination.
///
/// Recorded digests alone cannot see a receipt edited only at its
/// parameters, since every file still matches its own record, so every
/// rendered candidate, whole file or region, as this projection renders
/// it from the receipt's own parameters, is compared against the digest
/// the receipt stores for it. Called only where this binary wrote the
/// receipt: an older landing's files legitimately differ from this
/// projection, which is the alignment line's story and the upgrade's job,
/// not parameter drift. A destination already reported as rendered drift
/// is the file's own story, not the receipt's, and is skipped too.
fn observe_parameter_drift(manifest: &Manifest, projection: &Projection, observed: &mut Observed) {
for candidate in &projection.candidates {
if candidate.kind != Kind::Rendered {
continue;
}
let Some(record) = manifest.file(&candidate.destination) else {
continue;
};
if observed.drift_rendered.contains(&candidate.destination)
|| observed.missing.contains(&candidate.destination)
{
continue;
}
if Digest::of(recorded_form(candidate)) != record.sha256 {
observed
.parameter_drift
.push(format!("{} (parameters)", candidate.destination));
}
}
}
/// What this binary projects under the receipt's own parameters at this
/// target, with the same withhold judgment a landing applies, so the
/// comparison stands against what an upgrade would actually offer.
fn project(args: &StatusArgs, manifest: &Manifest) -> Result<Projection, RkError> {
let evidence = TargetEvidence::gather(&args.target, Some(manifest))?;
Projection::compute(&ProjectionInput {
params: landing::Params::from_record(manifest),
evidence,
})
}
/// The bytes the receipt digests for a candidate: the whole file, or the
/// marked region alone.
fn recorded_form(candidate: &Candidate) -> &[u8] {
candidate.region.as_deref().unwrap_or(&candidate.bytes)
}
/// The destinations an upgrade would change, read off the record alone.
///
/// A destination the projection adds or drops changes the record either
/// way, and a `rendered` one whose candidate digest differs from the
/// recorded digest is rewritten. A `seeded` or `state` destination the
/// record already names is never rewritten, so only a change of kind
/// counts for it. Disk drift is a separate story, told by its own lines:
/// an edited file is the target's doing, not a newer payload's.
fn pending_of(manifest: &Manifest, projected: &[Candidate]) -> Vec<String> {
let mut pending = Vec::new();
for entry in projected {
let changed = manifest.file(&entry.destination).is_none_or(|record| {
record.kind != entry.kind
|| (entry.kind == Kind::Rendered
&& record.sha256 != Digest::of(recorded_form(entry)))
});
if changed {
pending.push(entry.destination.clone());
}
}
for file in &manifest.files {
if !projected
.iter()
.any(|entry| entry.destination == file.destination)
{
pending.push(file.destination.clone());
}
}
pending.sort();
pending.dedup();
pending
}
/// The receipt-set consistency step: the recorded digests judge each
/// named file, and the region re-render judges the region records, but
/// neither can see a receipt whose parameters and file list disagree, a
/// nix flag flipped in the receipt with no file landed, or a
/// once-withheld capability whose target grew into the supported shape.
/// So the projection is computed from the receipt's own parameters, the
/// same withhold judgment applied, and the two destination sets compared
/// both ways. A destination the projection withholds at this target is
/// absent because withheld, which is not drift. Called only where this
/// binary wrote the receipt: an older landing's set legitimately differs,
/// and that is the alignment line's story.
fn observe_record_set(
manifest: &Manifest,
projection: &Projection,
record_drift: &mut Vec<String>,
) {
for entry in &projection.candidates {
if manifest.file(&entry.destination).is_none() {
record_drift.push(format!(
"the recorded parameters project {}, which the receipt does not name",
entry.destination
));
}
}
for file in &manifest.files {
let produced = projection
.candidates
.iter()
.any(|entry| entry.destination == file.destination)
|| projection
.omissions
.iter()
.any(|omission| omission.destination == file.destination);
if !produced {
record_drift.push(format!(
"the receipt names {}, which the recorded parameters do not project",
file.destination
));
}
}
}
/// The human lines, identical with and without `--check`.
fn render_human(
out: Output,
args: &StatusArgs,
manifest: &Manifest,
alignment: Alignment,
observed: &Observed,
) {
out.result_line(format!(
"release-kit {} ({}, {}, {} workflow, {} style{}) at {}",
manifest.rk_version,
manifest.tech,
manifest.forge,
manifest.parameters.workflow.as_str(),
manifest
.parameters
.style
.map_or("unrecorded", manifest::Style::as_str),
if manifest.parameters.nix { ", nix" } else { "" },
args.target
));
if alignment == Alignment::TargetNewer {
out.result_line(format!(
"binary {} is older than this landing; install the matching rk",
env!("CARGO_PKG_VERSION")
));
}
match observed.pending.as_deref() {
None => out.result_line(format!(
"this binary carries no {}/{} projection, so what an upgrade would change is unknown",
manifest.tech, manifest.forge
)),
Some(paths) => {
for path in paths {
out.result_line(format!("PENDING {path} (this binary would change it)"));
}
}
}
for path in &observed.drift_rendered {
out.result_line(format!("DRIFT {path} (rendered, release-kit-owned)"));
}
for path in &observed.parameter_drift {
out.result_line(format!(
"DRIFT {path}: the recorded parameters do not render the recorded bytes"
));
}
for reason in &observed.record_drift {
out.result_line(format!("DRIFT record: {reason}"));
}
for path in &observed.drift_seeded {
out.result_line(format!("DRIFT {path} (seeded, target-owned)"));
}
for path in &observed.missing {
out.result_line(format!("MISSING {path}"));
}
for pin in &observed.stale {
out.result_line(format!(
"STALE {} {} landed, {} in this binary",
pin.tool, pin.landed, pin.available
));
}
for (path, line, text) in &observed.sentinels {
out.result_line(format!("SENTINEL {path}:{line}: {text}"));
}
for failure in &observed.invariants {
out.result_line(format!(
"INVARIANT {} ({}): {}",
failure.destination, failure.code, failure.reason
));
}
let mut next = Vec::new();
for failure in &observed.invariants {
next.push(format!("{}: {}", failure.destination, failure.remediation));
}
if !observed.record_drift.is_empty() {
next.push(format!(
"rk upgrade --target {} rewrites the receipt from its parameters",
args.target
));
}
if observed
.pending
.as_deref()
.is_none_or(|paths| !paths.is_empty())
{
next.push(format!(
"rk upgrade --target {} takes this landing to {}",
args.target,
env!("CARGO_PKG_VERSION")
));
}
next.push(format!(
"rk status --check --target {} exits 1 on a violation",
args.target
));
out.next(&next);
}
#[cfg(test)]
mod tests {
use super::{Drift, InvariantFailure, Report, StalePin};
/// The complete `rk.status/9` shape, held by snapshot in both the
/// landed and absent forms.
#[test]
fn the_status_report_schema_snapshot_holds() {
let landed = Report {
schema: "rk.status/9",
landed: true,
config: super::ConfigState {
state: "pending",
pending: vec!["landing.style".into()],
},
tech: Some("rust".into()),
forge: Some("github".into()),
workflow: Some("worktree"),
style: Some("trunk"),
nix: Some(true),
rk_version: Some("0.1.0".into()),
binary_version: Some("0.2.0"),
alignment: Some(crate::landing::manifest::Alignment::BinaryNewer),
drift: Some(Drift {
rendered: 0,
seeded: 1,
}),
missing: Some(vec![]),
stale_pins: Some(vec![StalePin {
tool: "release-plz".into(),
landed: "0.3.160".into(),
available: "0.3.170".into(),
}]),
sentinels: Some(1),
record_drift: Some(0),
invariant_failures: Some(vec![InvariantFailure {
code: "attestations-disabled",
destination: "dist-workspace.toml".into(),
reason: "github-attestations is not effectively true".into(),
remediation: "set github-attestations = true in [dist]",
}]),
pending: Some(2),
violations: None,
};
assert_eq!(
serde_json::to_string(&landed).expect("a report serializes"),
r#"{"schema":"rk.status/9","landed":true,"config":{"state":"pending","pending":["landing.style"]},"tech":"rust","forge":"github","workflow":"worktree","style":"trunk","nix":true,"rk_version":"0.1.0","binary_version":"0.2.0","alignment":"binary-newer","drift":{"rendered":0,"seeded":1},"missing":[],"stale_pins":[{"tool":"release-plz","landed":"0.3.160","available":"0.3.170"}],"sentinels":1,"record_drift":0,"invariant_failures":[{"code":"attestations-disabled","destination":"dist-workspace.toml","reason":"github-attestations is not effectively true","remediation":"set github-attestations = true in [dist]"}],"pending":2}"#
);
let absent = Report {
landed: false,
config: super::ConfigState {
state: "absent",
pending: vec![],
},
tech: None,
forge: None,
workflow: None,
style: None,
nix: None,
rk_version: None,
binary_version: None,
alignment: None,
drift: None,
missing: None,
stale_pins: None,
sentinels: None,
record_drift: None,
invariant_failures: None,
pending: None,
violations: None,
..landed
};
assert_eq!(
serde_json::to_string(&absent).expect("a report serializes"),
r#"{"schema":"rk.status/9","landed":false,"config":{"state":"absent","pending":[]}}"#,
"an absent landing reports one field a caller can branch on"
);
}
}