//! `rk profile`: what a target resolves to, and what the catalog selects
//! for it.
//!
//! Read-only. The command resolves the target configuration the way every
//! landing verb does, keeps the source of each value, computes the one
//! projection, and reports every domain value with its source, the
//! unknown categories, the observation's proposal where it answered the
//! release mode, every capability with its status, the omissions, and the
//! conflicts. It writes nothing and judges nothing: judgment belongs to
//! `rk status --check` and `rk setup check`.
//!
//! SATISFIES project-profile:the-profile-command-writes-nothing
use std::collections::BTreeMap;
use serde::Serialize;
use crate::cli::profile::ProfileArgs;
use crate::diagnostic::{Diagnostic, Reason};
use crate::error::RkError;
use crate::landing::manifest::{self, Provider};
use crate::landing::{self, Params};
use crate::output::Output;
use crate::profile::{self, CapabilityRequests, GitWorkflow, ProfileSnapshot, Proposal, Source};
use crate::projection::{Projection, ProjectionInput, TargetEvidence};
use crate::stage::{CapabilityNote, Note};
/// The machine form of a profile report.
#[derive(Debug, Serialize)]
struct Report {
/// The shape version of this document.
schema: &'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 requests.
capabilities: CapabilityRequests,
/// The project path on the forge, empty where the project has none.
repo: String,
/// The two security answers.
security: Security,
/// The setup answers the release gate renders.
setup: Setup,
/// The landing declaration: the rendered destinations the project
/// deliberately edits. Its own domain, never a profile fact or a
/// capability request.
landing: LandingDeclaration,
/// The source of each value, keyed by its configuration path.
sources: BTreeMap<&'static str, Source>,
/// The category names the catalog does not know.
unknown: Vec<String>,
/// What the observation proposed for the release, where nothing above
/// it answered the mode.
#[serde(skip_serializing_if = "Option::is_none")]
proposal: Option<Proposal>,
/// Every capability, in catalog order, with its status and its
/// destinations.
selection: Vec<CapabilityNote>,
/// The destinations the target's own state withholds.
omissions: Vec<Note>,
/// The block destinations whose document offers the block no place.
collisions: Vec<Note>,
/// What plausibly follows.
next: Vec<String>,
}
/// The landing declaration, by destination.
#[derive(Debug, Serialize)]
struct LandingDeclaration {
/// Each accepted deviation, with its reason and accepted digest.
accepted_drift: BTreeMap<String, crate::config::AcceptedDrift>,
}
/// The three security answers.
#[derive(Debug, Serialize)]
struct Security {
/// The contact, empty for the forge's own wording.
contact: String,
/// The acknowledgment window.
response: String,
/// The paragraph naming what the project does not own, empty where the
/// policy states none.
scope: String,
}
/// The setup answers a landing renders.
#[derive(Debug, Serialize)]
struct Setup {
/// The check the release gate believes, empty where nothing answered it.
required_check: String,
/// The workflow whose completion wakes the release gate, empty where
/// nothing answered it.
required_workflow: String,
/// The bot identity's name, empty where the forge's default applies.
bot_name: String,
}
/// One line stating the three domains and the identity, for every human
/// report that names a resolved target.
#[must_use]
pub fn describe(
profile: &ProfileSnapshot,
git: &GitWorkflow,
capabilities: &CapabilityRequests,
repo: &str,
) -> String {
let technologies = if profile.technologies.is_empty() {
"none".to_owned()
} else {
profile.technologies.join(", ")
};
let release = match profile.release.mode {
profile::ReleaseMode::Automatic => format!(
"automatic (driver {}, style {}, line prefix {})",
profile.release.driver.as_deref().unwrap_or("unresolved"),
profile
.release
.style
.map_or("unresolved", crate::landing::Style::as_str),
profile
.release
.line_prefix
.as_deref()
.unwrap_or(crate::config::LINE_PREFIX_DEFAULT)
),
other => other.as_str().to_owned(),
};
let mut requested: Vec<&str> = Vec::new();
if capabilities.nix_packaging {
requested.push("nix_packaging");
}
if capabilities.reporting_policy {
requested.push("reporting_policy");
}
if capabilities.scorecard {
requested.push("scorecard");
}
if capabilities.workflow_guards() {
requested.push("workflow_guards");
}
let scanning = capabilities.code_scanning.map(Provider::as_str);
format!(
"technologies {technologies}; forge {}; repo {}; release {release}; trunk {}; checkout mode {}; integration {}; merge form {}; requests {}{}",
profile.forge.as_deref().unwrap_or("none"),
match repo {
"" => "none",
crate::projection::REPO_PLACEHOLDER => "unresolved",
named => named,
},
git.trunk,
git.checkout_mode.as_str(),
git.integration.as_str(),
git.merge_form.as_str(),
if requested.is_empty() {
"none".to_owned()
} else {
requested.join(", ")
},
scanning.map_or_else(String::new, |provider| format!(
", code_scanning {provider}"
))
)
}
/// Report the target's resolution and selection.
///
/// # Errors
///
/// Returns [`RkError::Missing`] for a target that is not a directory, and
/// the resolution's own refusals for a malformed release intent.
#[allow(
clippy::too_many_lines,
reason = "one pass reports every domain, source, capability, and omission, and splitting it would separate a value from the report line that states it"
)]
pub fn run(args: &ProfileArgs) -> 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 resolve for"),
));
}
let config = crate::config::load(args.target.as_std_path())?;
let record = manifest::load(&args.target)?;
let resolved = profile::resolve(
&args.target,
&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(),
record.as_ref(),
landing::Purpose::Preview,
)?;
let params: &Params = &resolved.params;
let evidence = TargetEvidence::gather(&args.target, record.as_ref())?;
let projection = Projection::compute(&ProjectionInput {
params: params.clone(),
evidence,
})?;
// The landing declaration is a committed answer of class N: only the
// configuration states it, and it must name what this landing selects.
let accepted_drift = config
.as_ref()
.map(|config| config.landing.accepted_drift.clone())
.unwrap_or_default();
landing::accepted_drift_faults(&projection, record.as_ref(), config.as_ref())?;
let mut sources = resolved.sources.clone();
sources.insert(
"landing.accepted_drift",
if accepted_drift.is_empty() {
profile::Source::Default
} else {
profile::Source::Config
},
);
for (destination, entry) in &accepted_drift {
out.result_line(format!(
"landing declaration: accepted drift on {destination} ({}), from config",
entry.reason
));
}
out.result_line(format!(
"profile: {}",
describe(
params.profile(),
params.git(),
params.capabilities(),
params.repo()
)
));
// Where an automatic rust release publishes, stated beside its source
// so an unanswered target reads crates.io as the default it is.
if let Some(answer) = params.registry() {
out.result_line(format!(
"registry: {} ({})",
answer.as_str(),
resolved
.sources
.get("profile.release.registry")
.map_or("default", |source| source.as_str())
));
}
for (key, source) in &resolved.sources {
out.result_line(format!("source {key}: {}", source.as_str()));
}
for name in &resolved.unknown {
out.result_line(format!("unknown {name}: preserved; no adapter drives it"));
}
if let Some(proposal) = &resolved.proposal {
out.result_line(format!(
"proposal: {}",
match proposal {
Proposal::None => "no release-bearing technology, so the release mode is none".to_owned(),
Proposal::Automatic { driver } => format!("an automatic release driven by {driver}"),
Proposal::Ambiguous { drivers } => format!(
"ambiguous: {} are release-bearing; an apply refuses until --release-driver names one",
drivers.join(" and ")
),
}
));
}
let selection: Vec<CapabilityNote> = projection
.capabilities
.iter()
.map(|selection| CapabilityNote::of(selection, &projection))
.collect();
for note in &selection {
let mut line = format!("{} {}", note.status, note.id);
if !note.destinations.is_empty() {
line.push_str(": ");
line.push_str(¬e.destinations.join(", "));
}
if let Some(reason) = ¬e.reason {
line.push_str(" (");
line.push_str(reason);
line.push(')');
}
out.result_line(line);
if let Some(action) = ¬e.action {
out.result_line(format!(" action: {action}"));
}
}
let omissions: Vec<Note> = projection
.omissions
.iter()
.map(|omission| Note {
destination: omission.destination.clone(),
reason: omission.reason.clone(),
action: omission.action.clone(),
})
.collect();
let collisions: Vec<Note> = projection
.collisions
.iter()
.map(|collision| Note {
destination: collision.destination.clone(),
reason: collision.reason.clone(),
action: None,
})
.collect();
for note in &omissions {
out.result_line(format!("withheld {}: {}", note.destination, note.reason));
}
for note in &collisions {
out.result_line(format!("collision {}: {}", note.destination, note.reason));
}
// `rk upgrade` takes each capability as `on|off`, and `rk init` takes
// the boolean ones as bare flags. The follow-up command must parse, so
// it renders the verb's own spelling rather than one of them twice.
let (verb, capabilities) = if record.is_some() {
("upgrade", params.capability_toggles())
} else {
("init", params.capability_flags())
};
let mut next = vec![format!(
"rk {verb}{}{capabilities} --target {} previews the landing under these answers",
params.canonical_flags(),
args.target
)];
if let Some(Proposal::Ambiguous { drivers }) = &resolved.proposal {
next.insert(
0,
format!(
"name the driver before an apply: --release-driver <{}>",
drivers.join("|")
),
);
}
if let Some(reason) = projection.release_unavailable() {
next.insert(
0,
format!("an apply refuses until the release automation resolves: {reason}"),
);
}
next.push(format!(
"rk stage --target {} stages the complete candidate for a byte comparison",
args.target
));
out.next(&next);
out.emit(&Report {
schema: "rk.profile/5",
target: args.target.to_string(),
profile: params.profile().clone(),
git: params.git().clone(),
capabilities: params.capabilities().clone(),
repo: params.repo().to_owned(),
security: Security {
contact: params.security_contact().to_owned(),
response: params.security_response().to_owned(),
scope: params.security_scope().to_owned(),
},
setup: Setup {
required_check: params.required_check().to_owned(),
required_workflow: params.required_workflow().to_owned(),
bot_name: resolved.bot_name.clone(),
},
landing: LandingDeclaration { accepted_drift },
sources,
unknown: resolved.unknown,
proposal: resolved.proposal,
selection,
omissions,
collisions,
next,
})
}
#[cfg(test)]
mod tests {
use super::{Report, Security, Setup};
use crate::landing::{CheckoutMode, Integration};
use crate::profile::{
CapabilityRequests, GitWorkflow, ProfileSnapshot, Proposal, ReleaseIntent, ReleaseMode,
Source,
};
use crate::stage::{CapabilityNote, Note};
/// The complete `rk.profile/5` shape, held by snapshot.
#[test]
fn the_profile_report_schema_snapshot_holds() {
let report = Report {
schema: "rk.profile/5",
target: "/tmp/t".into(),
profile: ProfileSnapshot {
technologies: vec!["python".into(), "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()),
registry: None,
build: None,
},
},
git: GitWorkflow {
trunk: "master".into(),
checkout_mode: CheckoutMode::LinkedWorktree,
integration: Integration::Local,
merge_form: crate::landing::MergeForm::Squash,
},
capabilities: CapabilityRequests {
nix_packaging: false,
reporting_policy: true,
scorecard: false,
code_scanning: None,
workflow_guards: Some(false),
},
repo: "acme/widget".into(),
security: Security {
contact: String::new(),
response: "best-effort".into(),
scope: String::new(),
},
setup: Setup {
required_check: String::new(),
required_workflow: String::new(),
bot_name: String::new(),
},
landing: super::LandingDeclaration {
accepted_drift: std::collections::BTreeMap::new(),
},
sources: std::iter::once(("profile.technologies", Source::Observation)).collect(),
unknown: vec![],
proposal: Some(Proposal::Ambiguous {
drivers: vec!["python".into(), "rust".into()],
}),
selection: vec![CapabilityNote {
id: "git.guards".into(),
status: "selected".into(),
reason: None,
action: None,
destinations: vec!["AGENTS.md".into()],
}],
omissions: vec![Note {
destination: ".gitlab-ci.yml".into(),
reason: "the target owns it".into(),
action: Some("add the include".into()),
}],
collisions: vec![],
next: vec!["rk init --target /tmp/t previews the landing".into()],
};
assert_eq!(
serde_json::to_string(&report).expect("a report serializes"),
r#"{"schema":"rk.profile/5","target":"/tmp/t","profile":{"technologies":["python","rust"],"forge":"github","release":{"mode":"automatic","driver":"rust","style":"trunk","line_prefix":"release/"}},"git":{"trunk":"master","checkout_mode":"linked-worktree","integration":"local","merge_form":"squash"},"capabilities":{"nix_packaging":false,"reporting_policy":true,"scorecard":false,"workflow_guards":false},"repo":"acme/widget","security":{"contact":"","response":"best-effort","scope":""},"setup":{"required_check":"","required_workflow":"","bot_name":""},"landing":{"accepted_drift":{}},"sources":{"profile.technologies":"observation"},"unknown":[],"proposal":{"state":"ambiguous","drivers":["python","rust"]},"selection":[{"id":"git.guards","status":"selected","destinations":["AGENTS.md"]}],"omissions":[{"destination":".gitlab-ci.yml","reason":"the target owns it","action":"add the include"}],"collisions":[],"next":["rk init --target /tmp/t previews the landing"]}"#
);
}
}