release_kit/cli/profile_flags.rs
1//! The flags every verb that resolves a target configuration takes: the
2//! project profile and the Git workflow, as `rk init`, `rk adopt`,
3//! `rk stage`, and `rk profile` read them.
4//!
5//! The canonical names are the long forms below. Three older spellings
6//! stay as hidden aliases, so an existing command line keeps working:
7//! `--tech` for one `--technology`, `--style` for `--release-style`, and
8//! `--workflow` for `--checkout-mode`, whose older values `worktree` and
9//! `branches` the parser still reads.
10
11use clap::Args;
12
13/// The profile and Git workflow answers an invocation states.
14#[derive(Debug, Clone, Default, Args)]
15pub struct ProfileFlags {
16 /// A technology present in the project; repeat it for several. A
17 /// supplied list replaces the configured one whole. Defaults to
18 /// detection from the version files.
19 #[arg(long = "technology", alias = "tech", value_name = "NAME")]
20 pub technology: Vec<String>,
21
22 /// The forge hosting the project: github or gitlab. Defaults to
23 /// detection from the target's git remote; a project with no forge
24 /// resolves to none.
25 #[arg(long)]
26 pub forge: Option<String>,
27
28 /// The project path on the forge, substituted into the rendered files
29 /// and recorded as the landing parameter. Defaults to detection from
30 /// the target's git remote.
31 #[arg(long)]
32 pub repo: Option<String>,
33
34 /// The release intent: automatic, where release-kit drives the
35 /// release; external, where the project releases through a process
36 /// release-kit does not drive; or none. Defaults to the observation's
37 /// proposal: automatic with the one release-bearing technology, none
38 /// where there is none.
39 #[arg(long, value_name = "MODE")]
40 pub release_mode: Option<String>,
41
42 /// The technology that states the version and takes the bot, for an
43 /// automatic release. Required where more than one release-bearing
44 /// technology is present.
45 #[arg(long, value_name = "NAME")]
46 pub release_driver: Option<String>,
47
48 /// The release style of an automatic release: trunk (the bot's
49 /// request carries auto-merge from creation) or lines (every request
50 /// waits for a human's merge).
51 #[arg(long, alias = "style", value_name = "STYLE")]
52 pub release_style: Option<String>,
53
54 /// The one permanent branch. Defaults to the configuration, the
55 /// record, and then master.
56 #[arg(long, value_name = "BRANCH")]
57 pub trunk: Option<String>,
58
59 /// Where a topic branch opens: linked-worktree (every code-changing
60 /// branch in its own linked worktree, the main checkout commits
61 /// nothing) or main-worktree (the original working tree switches to
62 /// it). Recorded as a Git workflow parameter and rendered into the
63 /// landed blocks.
64 #[arg(long, alias = "workflow", value_name = "MODE")]
65 pub checkout_mode: Option<String>,
66
67 /// Which authority moves an implementation onto the trunk: local
68 /// (the checkout squashes and records it, through `rk integrate`) or
69 /// forge (a pull request or merge request does, behind its required
70 /// check). Recorded as a Git workflow parameter and rendered into the
71 /// landed blocks. Defaults to local.
72 #[arg(long, value_name = "MODE")]
73 pub integration: Option<String>,
74
75 /// How the commits of a branch reach the trunk: squash (the branch
76 /// arrives as one commit) or rebase (the branch is rebased on the
77 /// trunk tip and the trunk fast-forwards to it, every commit keeping
78 /// its own message). Recorded as a Git workflow parameter. Defaults
79 /// to squash.
80 #[arg(long, value_name = "FORM")]
81 pub merge_form: Option<String>,
82
83 /// The check the release gate believes: the context the trunk ruleset
84 /// requires under forge integration, and the context the rendered
85 /// release gate judges under local integration. GitHub only.
86 #[arg(long, value_name = "NAME")]
87 pub required_check: Option<String>,
88
89 /// The workflow whose completion wakes the release gate under local
90 /// integration, named by its `name:` key rather than its filename.
91 /// GitHub only.
92 #[arg(long, value_name = "NAME")]
93 pub required_workflow: Option<String>,
94}
95
96impl ProfileFlags {
97 /// Whether no flag answered anything.
98 #[must_use]
99 pub const fn is_empty(&self) -> bool {
100 self.technology.is_empty()
101 && self.forge.is_none()
102 && self.repo.is_none()
103 && self.release_mode.is_none()
104 && self.release_driver.is_none()
105 && self.release_style.is_none()
106 && self.trunk.is_none()
107 && self.checkout_mode.is_none()
108 && self.integration.is_none()
109 && self.merge_form.is_none()
110 && self.required_check.is_none()
111 && self.required_workflow.is_none()
112 }
113
114 /// The parsed answers, as the resolution takes them.
115 ///
116 /// # Errors
117 ///
118 /// Returns [`crate::error::RkError::Usage`] for a value outside its
119 /// vocabulary.
120 pub fn inputs(&self) -> Result<crate::profile::Inputs<'_>, crate::error::RkError> {
121 use crate::landing::{CheckoutMode, Integration, MergeForm, Style};
122 use crate::profile::ReleaseMode;
123 Ok(crate::profile::Inputs {
124 technologies: &self.technology,
125 forge: self.forge.as_deref(),
126 repo: self.repo.as_deref(),
127 release_mode: self
128 .release_mode
129 .as_deref()
130 .map(ReleaseMode::parse)
131 .transpose()?,
132 release_driver: self.release_driver.as_deref(),
133 style: self
134 .release_style
135 .as_deref()
136 .map(Style::parse)
137 .transpose()?,
138 trunk: self.trunk.as_deref(),
139 checkout_mode: self
140 .checkout_mode
141 .as_deref()
142 .map(CheckoutMode::parse)
143 .transpose()?,
144 integration: self
145 .integration
146 .as_deref()
147 .map(Integration::parse)
148 .transpose()?,
149 merge_form: self
150 .merge_form
151 .as_deref()
152 .map(MergeForm::parse)
153 .transpose()?,
154 required_check: self.required_check.as_deref(),
155 required_workflow: self.required_workflow.as_deref(),
156 ..crate::profile::Inputs::default()
157 })
158 }
159}
160
161/// The preset flag's name, as an operator types it.
162pub const WORKFLOW_ONLY: &str = "--workflow-only";
163
164/// Expand `--workflow-only` over the answers an invocation states.
165///
166/// The preset sets four answers: no release, local integration, linked
167/// worktrees, and the workflow guards. It records nothing of its own, so
168/// the expansion is the four answers and nothing else. A flag that states
169/// one of them the same way agrees with it; a flag that states another
170/// answer, or an answer only a release takes, refuses before any write,
171/// naming the flag and the preset. A flag the preset does not set, such
172/// as `--merge-form`, passes through.
173///
174/// # Errors
175///
176/// A [`crate::diagnostic::Reason::PresetContradiction`] refusal naming
177/// every contradicting flag.
178///
179/// SATISFIES project-profile:the-workflow-only-preset-expands-to-recorded-answers
180pub fn workflow_only(
181 mut inputs: crate::profile::Inputs<'_>,
182) -> Result<crate::profile::Inputs<'_>, crate::error::RkError> {
183 use crate::landing::{CheckoutMode, Integration};
184 use crate::profile::ReleaseMode;
185 let mut contradicting: Vec<String> = Vec::new();
186 if let Some(mode) = inputs
187 .release_mode
188 .filter(|mode| *mode != ReleaseMode::None)
189 {
190 contradicting.push(format!(
191 "--release-mode {} (the preset sets profile.release.mode = \"none\")",
192 mode.as_str()
193 ));
194 }
195 if let Some(driver) = inputs.release_driver {
196 contradicting.push(format!(
197 "--release-driver {driver} (an automatic release alone takes a driver)"
198 ));
199 }
200 if let Some(style) = inputs.style {
201 contradicting.push(format!(
202 "--release-style {} (an automatic release alone takes a style)",
203 style.as_str()
204 ));
205 }
206 if let Some(integration) = inputs
207 .integration
208 .filter(|integration| *integration != Integration::Local)
209 {
210 contradicting.push(format!(
211 "--integration {} (the preset sets git.integration = \"local\")",
212 integration.as_str()
213 ));
214 }
215 if let Some(mode) = inputs
216 .checkout_mode
217 .filter(|mode| *mode != CheckoutMode::LinkedWorktree)
218 {
219 contradicting.push(format!(
220 "--checkout-mode {} (the preset sets git.checkout_mode = \"linked-worktree\")",
221 mode.as_str()
222 ));
223 }
224 if inputs.workflow_guards == Some(false) {
225 contradicting.push(
226 "--workflow-guards off (the preset sets capabilities.workflow_guards = true)"
227 .to_owned(),
228 );
229 }
230 if !contradicting.is_empty() {
231 return Err(crate::error::RkError::refusal(
232 crate::diagnostic::Diagnostic::new(
233 crate::diagnostic::Reason::PresetContradiction,
234 format!(
235 "{} contradict{} {WORKFLOW_ONLY}; nothing was written",
236 contradicting.join(", "),
237 if contradicting.len() == 1 { "s" } else { "" }
238 ),
239 )
240 .expected(format!(
241 "{WORKFLOW_ONLY} alone, or beside a flag it does not set, such as --merge-form"
242 ))
243 .action(format!(
244 "drop {WORKFLOW_ONLY} and state each answer by its own flag, or drop the contradicting flag"
245 ))
246 .target_state("unchanged"),
247 ));
248 }
249 inputs.release_mode = Some(ReleaseMode::None);
250 inputs.integration = Some(Integration::Local);
251 inputs.checkout_mode = Some(CheckoutMode::LinkedWorktree);
252 inputs.workflow_guards = Some(true);
253 Ok(inputs)
254}