Skip to main content

docsrs_cli/cli/
destructive.rs

1//! The register of verbs that destroy, and the one rule they all obey.
2//!
3//! # Why a register instead of two guards
4//!
5//! `cache clear` learned Explicit Target Designation on 2026-08-10 and the same
6//! plan said `config init --force` would learn it too. Only the first was built.
7//! The gap was not the missing guard — it was that nothing could tell the guard
8//! was missing, because the rule lived inside one `match` arm and could not be
9//! asked a question. A second destructive verb shipped without a waiver and every
10//! gate agreed with the tree.
11//!
12//! So the rule moved here. The runtime reads this list to decide whether to
13//! refuse, and `tests/policy/etd.rs` reads the same list to demand a waiver flag,
14//! a `target_source` in the schema, and a line in both configuration references.
15//! A third verb that destroys is either in this list or the class gate fails; it
16//! cannot be quietly correct the way `config init --force` was.
17//!
18//! # What counts as designation
19//!
20//! Naming the directory in argv designates it. Passing the waiver accepts an
21//! ambient one on purpose. Passing neither means the caller never saw the path
22//! about to be destroyed, which is the confused-deputy shape: the caller names
23//! the verb, the environment names the victim, and nothing compares the two.
24
25use crate::config::PathSource;
26use crate::error::{DestructiveEffect, ErrorDetail};
27
28/// One verb that destroys, with everything needed to refuse it safely.
29#[derive(Debug, Clone, Copy, PartialEq, Eq)]
30pub struct DestructiveVerb {
31    /// Invocation in wire spelling, as the refusal message names it.
32    pub wire: &'static str,
33    /// Flag that designates the target in argv.
34    pub target_flag: &'static str,
35    /// Flag that accepts an ambient target on purpose.
36    pub waiver_flag: &'static str,
37    /// What would happen to the target.
38    pub effect: DestructiveEffect,
39    /// Schema stem under `docs/schemas/`, which must carry `target_source`.
40    pub schema_stem: &'static str,
41}
42
43impl DestructiveVerb {
44    /// Whether this invocation must be refused for want of a designated target.
45    ///
46    /// Only [`PathSource::CliFlag`] counts as designation. `Xdg` is the ambient
47    /// layer the caller never named, and `Unresolved` is worse: there is no
48    /// target at all, so acting would be acting somewhere unknown.
49    pub fn must_refuse(self, waived: bool, source: PathSource) -> bool {
50        !waived && source != PathSource::CliFlag
51    }
52
53    /// The refusal, naming the victim and both ways out of it.
54    ///
55    /// The message names the target because a refusal that hides which path was
56    /// about to be destroyed teaches the caller nothing about what to pass.
57    pub fn refuse(self, target: String) -> ErrorDetail {
58        ErrorDetail::AmbientTargetRefused {
59            verb: self.wire.to_string(),
60            target,
61            target_flag: self.target_flag.to_string(),
62            waiver_flag: self.waiver_flag.to_string(),
63            effect: self.effect,
64        }
65    }
66}
67
68/// `cache clear` empties every cached body under the resolved cache root.
69pub const CACHE_CLEAR: DestructiveVerb = DestructiveVerb {
70    wire: "cache clear",
71    target_flag: "--cache-dir",
72    waiver_flag: "--yes",
73    effect: DestructiveEffect::Delete,
74    schema_stem: "cache-clear",
75};
76
77/// `config init --force` replaces an existing `config.toml` in place.
78///
79/// The waiver is required whenever the target is ambient, even where no file
80/// exists yet. The caller cannot know in advance whether a directory they never
81/// named holds a file, and that uncertainty is precisely the risk: a rule whose
82/// answer depends on the state of the disk gives the same argv two behaviours.
83pub const CONFIG_INIT_FORCE: DestructiveVerb = DestructiveVerb {
84    wire: "config init --force",
85    target_flag: "--config-dir",
86    waiver_flag: "--yes",
87    effect: DestructiveEffect::Overwrite,
88    schema_stem: "config-init",
89};
90
91/// Every verb in this binary that destroys something it did not create.
92///
93/// This is the list the class gate reads. Adding a destructive verb without
94/// adding it here fails `no_verb_that_destroys_escapes_the_register`.
95pub const fn destructive_verbs() -> &'static [DestructiveVerb] {
96    &[CACHE_CLEAR, CONFIG_INIT_FORCE]
97}