Skip to main content

release_kit/self_depend/
advice.rs

1//! The texts that guide a pin move.
2//!
3//! They are the warning that a newer release is out, the route to the
4//! setup skill of the rk that the move brings, and the follows lines that
5//! keep a consumer's `flake.lock` free of nested copies.
6//!
7//! The two sentences are one shared wording with sdd, word for word, so
8//! a reader who moves both pins reads one procedure. Every verb that
9//! warns or routes takes its text from here, so the wording has one
10//! owner. Reading the follows lines is pure: lock bytes in, lines out.
11//!
12//! SATISFIES packaging:the-unattended-caller-never-fails-the-shell
13
14use super::discover::version_order;
15
16/// The skill that runs an upgrade.
17pub const SKILL: &str = "rk-setup";
18
19/// The inputs of rk's own flake that serve only its development shell.
20/// A consumer that has no input of the same name points each at its own
21/// flake, so its lock holds no node for them.
22const DEV_ONLY_INPUTS: &[&str] = &["spec-driven-docs", "exobrain-tech"];
23
24/// The input name the consumer gives rk, and rk's own input for itself.
25const SELF_INPUT: &str = "release-kit";
26
27/// The warning that a newer release is out and the pin is behind it.
28#[must_use]
29pub fn pending(latest: &str, pin: &str) -> String {
30    format!(
31        "rk {} is out, this project pins {}. To move: rk self-depend sync --apply, then upgrade through the {SKILL} skill of the new rk.",
32        latest.trim_start_matches('v'),
33        pin.trim_start_matches('v'),
34    )
35}
36
37/// The route after a pin move: the setup skill of the rk in the
38/// devshell runs the upgrade.
39#[must_use]
40pub fn after_move() -> String {
41    format!(
42        "After the pin move, load the devshell and run the upgrade through the {SKILL} skill of the rk in that devshell, and do every migration it names. Before `rk upgrade`, read it with `rk skill show {SKILL}`. After it, the project's .claude/skills/{SKILL} is that skill. Never use a host copy or an older skill."
43    )
44}
45
46/// The pending warning, where the pin is behind the latest release that
47/// the check cache knows. It reads the cache and fetches nothing.
48#[must_use]
49pub fn pending_from_cache(key: &str, pin: &str) -> Option<String> {
50    let latest = cached_latest(key)?;
51    version_order(&latest, pin)
52        .is_gt()
53        .then(|| pending(&latest, pin))
54}
55
56/// The latest release the check cache of one checkout records.
57#[must_use]
58pub fn cached_latest(key: &str) -> Option<String> {
59    let paths = super::check::Paths::for_key(key)?;
60    super::check::read(&paths.cache)?.latest
61}
62
63/// The follows lines that rk's flake input lacks, from the consumer's
64/// `flake.lock`, each as the exact line to add.
65///
66/// Only an input that the lock gives a node of its own counts: a follows
67/// path is already chosen. rk's copy of itself points at the consumer's
68/// flake. An input whose name the consumer's flake also declares follows
69/// that input. A development-only input that the consumer lacks points
70/// at the consumer's flake. Every other input keeps its own node.
71#[must_use]
72pub fn follows_lines(lock: &[u8]) -> Vec<String> {
73    let Ok(value) = serde_json::from_slice::<serde_json::Value>(lock) else {
74        return Vec::new();
75    };
76    let nodes = &value["nodes"];
77    let root = value["root"].as_str().unwrap_or("root");
78    let Some(rk) = super::input_node(nodes, root, root, SELF_INPUT, 0) else {
79        return Vec::new();
80    };
81    let Some(inputs) = nodes[rk.as_str()]["inputs"].as_object() else {
82        return Vec::new();
83    };
84    let root_inputs = &nodes[root]["inputs"];
85    let mut lines = Vec::new();
86    for (name, target) in inputs {
87        if !target.is_string() {
88            continue;
89        }
90        let follows = if name == SELF_INPUT {
91            ""
92        } else if root_inputs.get(name).is_some() {
93            name.as_str()
94        } else if DEV_ONLY_INPUTS.contains(&name.as_str()) {
95            ""
96        } else {
97            continue;
98        };
99        lines.push(format!("inputs.{name}.follows = \u{22}{follows}\u{22};"));
100    }
101    lines
102}
103
104/// The next line that names the missing follows lines, where any is
105/// missing.
106#[must_use]
107pub fn follows_next(lines: &[String]) -> Option<String> {
108    (!lines.is_empty()).then(|| {
109        format!(
110            "the release-kit input of flake.nix lacks these lines: {} Add them beside its url, then run nix flake lock, which drops the nested nodes",
111            lines.join(" ")
112        )
113    })
114}
115
116#[cfg(test)]
117mod tests {
118    use super::{after_move, follows_lines, follows_next, pending};
119
120    #[test]
121    fn the_pending_warning_names_both_versions_and_the_skill() {
122        assert_eq!(
123            pending("v0.11.0", "v0.10.0"),
124            "rk 0.11.0 is out, this project pins 0.10.0. To move: rk self-depend sync --apply, then upgrade through the rk-setup skill of the new rk."
125        );
126    }
127
128    #[test]
129    fn the_route_names_the_devshell_skill_and_refuses_other_copies() {
130        let text = after_move();
131        assert!(text.starts_with("After the pin move, load the devshell"));
132        assert!(text.contains("`rk skill show rk-setup`"));
133        assert!(text.ends_with("Never use a host copy or an older skill."));
134    }
135
136    /// A lock in the shape a consumer that pins rk 0.10.0 alone writes:
137    /// rk's own copy of itself and its sdd input nest, nixpkgs follows.
138    const RK_ALONE: &str = r#"{"root":"root","version":7,"nodes":{
139        "root":{"inputs":{"nixpkgs":"nixpkgs","release-kit":"release-kit_2"}},
140        "nixpkgs":{},
141        "release-kit_2":{"inputs":{"nixpkgs":["nixpkgs"],"release-kit":"release-kit_3",
142            "rust-overlay":"rust-overlay","spec-driven-docs":"spec-driven-docs","exobrain-tech":"exobrain-tech"}},
143        "release-kit_3":{},"rust-overlay":{},"spec-driven-docs":{},"exobrain-tech":{}}}"#;
144
145    #[test]
146    fn a_consumer_that_pins_rk_alone_drops_every_nested_copy() {
147        assert_eq!(
148            follows_lines(RK_ALONE.as_bytes()),
149            vec![
150                r#"inputs.exobrain-tech.follows = "";"#,
151                r#"inputs.release-kit.follows = "";"#,
152                r#"inputs.spec-driven-docs.follows = "";"#,
153            ]
154        );
155    }
156
157    #[test]
158    fn a_consumer_that_pins_sdd_too_points_rk_at_it() {
159        let lock = RK_ALONE.replace(
160            r#""root":{"inputs":{"nixpkgs":"nixpkgs","#,
161            r#""root":{"inputs":{"nixpkgs":"nixpkgs","spec-driven-docs":"spec-driven-docs_2","#,
162        );
163        let lines = follows_lines(lock.as_bytes());
164        assert!(
165            lines.contains(&r#"inputs.spec-driven-docs.follows = "spec-driven-docs";"#.to_owned())
166        );
167    }
168
169    #[test]
170    fn a_followed_input_needs_no_line() {
171        let lock = RK_ALONE
172            .replace(r#""release-kit":"release-kit_3""#, r#""release-kit":[]"#)
173            .replace(
174                r#""spec-driven-docs":"spec-driven-docs","exobrain-tech":"exobrain-tech""#,
175                r#""spec-driven-docs":[],"exobrain-tech":[]"#,
176            );
177        assert!(follows_lines(lock.as_bytes()).is_empty());
178        assert_eq!(follows_next(&[]), None);
179    }
180
181    #[test]
182    fn an_unreadable_lock_advises_nothing() {
183        assert!(follows_lines(b"not json").is_empty());
184    }
185}