Skip to main content

spec_driven_docs/self_depend/
pin.rs

1//! The pin each manager records, read and rewritten in its own form.
2//!
3//! ```text
4//! flake input      github:<owner>/<repo>/<tag> in flake.nix, locked in flake.lock
5//! mise, registry   "cargo:<crate>" = "<version>"
6//! mise, release    "ubi:<owner>/<repo>" = { version = "<version>", exe = "<binary>" }
7//! asdf             <tool> <version>, one line in .tool-versions
8//! devbox           "github:<owner>/<repo>/<tag>#<output>", one entry in packages
9//! ```
10//!
11//! A registry entry names the crate as the registry knows it, and an archive
12//! entry names the binary inside the archive. The reader below accepts each
13//! form where its manager writes it and nowhere else.
14
15use semver::Version;
16use serde::Serialize;
17
18use crate::self_depend::manager::Manager;
19use crate::self_depend::registry::CRATE_NAME;
20use crate::self_depend::venue::Venue;
21use crate::self_depend::{BINARY_NAME, slug};
22
23/// One recorded pin, located in its file.
24#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
25pub struct Pin {
26    /// The released triple the pin names.
27    pub version: Version,
28    /// The version as the file spells it, `v` prefix included where present.
29    pub spelled: String,
30    /// The venue the entry's form selects, where the form says.
31    pub venue: Option<Venue>,
32    /// The one-based line the pin sits on.
33    pub line: usize,
34    /// How many lines in the file pin this tool.
35    pub lines: usize,
36    /// The byte span of the spelled version in the file text.
37    #[serde(skip)]
38    pub span: (usize, usize),
39}
40
41/// The pin a manager file records for this tool, where it records one.
42#[must_use]
43pub fn read(manager: Manager, text: &str) -> Option<Pin> {
44    let mut found: Vec<Pin> = Vec::new();
45    let mut offset = 0;
46    for (index, line) in text.split_inclusive('\n').enumerate() {
47        if let Some((start, end, venue)) = locate(manager, line) {
48            let spelled = line[start..end].to_string();
49            let bare = spelled.strip_prefix('v').unwrap_or(&spelled);
50            if let Ok(version) = bare.parse::<Version>() {
51                found.push(Pin {
52                    version,
53                    spelled,
54                    venue,
55                    line: index + 1,
56                    lines: 0,
57                    span: (offset + start, offset + end),
58                });
59            }
60        }
61        offset += line.len();
62    }
63    let lines = found.len();
64    let mut first = found.into_iter().next()?;
65    first.lines = lines;
66    Some(first)
67}
68
69/// Where one line spells the version, and which venue the form selects.
70fn locate(manager: Manager, line: &str) -> Option<(usize, usize, Option<Venue>)> {
71    match manager {
72        Manager::Flake => {
73            let needle = format!("github:{}/", slug());
74            let start = line.find(&needle)? + needle.len();
75            let end = start
76                + line[start..]
77                    .find(['"', '#', '?', '\''])
78                    .unwrap_or(line.len() - start);
79            (end > start).then_some((start, end, Some(Venue::Flake)))
80        }
81        Manager::Devbox => {
82            let needle = format!("github:{}/", slug());
83            let start = line.find(&needle)? + needle.len();
84            let end = start + line[start..].find(['#', '"']).unwrap_or(line.len() - start);
85            (end > start).then_some((start, end, Some(Venue::Flake)))
86        }
87        Manager::Mise => {
88            let trimmed = line.trim_start();
89            let registry = format!("\"cargo:{CRATE_NAME}\"");
90            let archive = format!("\"ubi:{}\"", slug());
91            if trimmed.starts_with(&registry) {
92                let (start, end) = quoted_after(line, "=")?;
93                return Some((start, end, Some(Venue::Crates)));
94            }
95            if trimmed.starts_with(&archive) {
96                let (start, end) = quoted_after(line, "version")?;
97                return Some((start, end, Some(Venue::GithubRelease)));
98            }
99            None
100        }
101        Manager::Asdf => {
102            let mut parts = line.split_whitespace();
103            let tool = parts.next()?;
104            if tool != CRATE_NAME && tool != BINARY_NAME {
105                return None;
106            }
107            let version = parts.next()?;
108            let start = line.find(version)?;
109            Some((start, start + version.len(), None))
110        }
111    }
112}
113
114/// The span of the first quoted string after `marker` in `line`.
115fn quoted_after(line: &str, marker: &str) -> Option<(usize, usize)> {
116    let at = line.find(marker)? + marker.len();
117    let open = at + line[at..].find('"')? + 1;
118    let close = open + line[open..].find('"')?;
119    Some((open, close))
120}
121
122/// The same file text with the pin moved to `to`, in the spelling the file
123/// already uses.
124///
125/// # Errors
126///
127/// A message where the file no longer records the pin it was read with.
128pub fn rewrite(manager: Manager, text: &str, to: &Version) -> Result<(String, Pin), String> {
129    let held = read(manager, text).ok_or_else(|| "the file no longer records a pin".to_string())?;
130    let spelled = if held.spelled.starts_with('v') {
131        format!("v{to}")
132    } else {
133        to.to_string()
134    };
135    let mut moved = String::with_capacity(text.len());
136    moved.push_str(&text[..held.span.0]);
137    moved.push_str(&spelled);
138    moved.push_str(&text[held.span.1..]);
139    Ok((moved, held))
140}
141
142/// The deepest chain of follows paths [`input_node`] walks before it gives
143/// up: a lock that loops reads as one naming no input.
144const MAX_FOLLOWS: usize = 32;
145
146/// The revision `flake.lock` holds for this tool's input, where it holds one.
147///
148/// A lock names a node after the input that first introduced it, so a
149/// dependency's own input on this tool can hold the plain name while the
150/// project's input reads `spec-driven-docs_2`. The root node, which the
151/// lock's `root` key names, is the one owner of the project's inputs, so
152/// the revision is read from the node one of its inputs resolves to. That
153/// input is found by the repository its node names, never by its name.
154#[must_use]
155pub fn locked_rev(lock: &str) -> Option<String> {
156    let value: serde_json::Value = serde_json::from_str(lock).ok()?;
157    let (_, node) = own_input(&value)?;
158    value["nodes"][node.as_str()]["locked"]["rev"]
159        .as_str()
160        .map(str::to_string)
161}
162
163/// Whether a lock node names this tool's repository.
164fn names_this_tool(node: &serde_json::Value) -> bool {
165    let (owner, repo) = crate::self_depend::coordinates();
166    let original = &node["original"];
167    let same = |key: &str, want: &str| {
168        original[key]
169            .as_str()
170            .is_some_and(|held| held.eq_ignore_ascii_case(want))
171    };
172    same("owner", owner) && same("repo", repo)
173}
174
175/// The root input that resolves to this tool, and the node it resolves to.
176fn own_input(value: &serde_json::Value) -> Option<(String, String)> {
177    let nodes = &value["nodes"];
178    let root = value["root"].as_str().unwrap_or("root");
179    let inputs = nodes[root]["inputs"].as_object()?;
180    inputs.keys().find_map(|input| {
181        let name = input_node(nodes, root, root, input, 0)?;
182        names_this_tool(&nodes[name.as_str()]).then(|| (input.clone(), name))
183    })
184}
185
186/// The inputs of this tool's own flake that only its development shell reads.
187///
188/// The package never reads them. A consumer that lacks one points it at its
189/// own flake with an empty follows, so the lock holds no node for it. Read
190/// from this repository's `flake.nix`: the package output builds from
191/// `nixpkgs` and `rust-overlay` alone.
192pub const DEVELOPMENT_ONLY_INPUTS: [&str; 2] = ["release-kit", "exobrain-tech"];
193
194/// One follows line a consumer's flake lacks on this tool's input.
195#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
196pub struct Follows {
197    /// The consumer's input that pins this tool, which holds the line.
198    pub input: String,
199    /// The nested input the line points.
200    pub nested: String,
201    /// The line, as `flake.nix` carries it inside the input's attribute set.
202    pub line: String,
203}
204
205/// The follows lines that remove a nested copy from a consumer's lock.
206///
207/// For each input of this tool's node that still holds its own node: this
208/// tool's own previous release follows nothing, an input the root also
209/// declares follows the root's, and a development-only input the root
210/// lacks follows nothing. Every other input keeps its node, because the
211/// package build needs it. The lock grammar alone decides, and nothing is
212/// written.
213///
214/// SATISFIES acquisition:sync-advises-the-follows-lines-and-writes-none
215#[must_use]
216pub fn follows_advice(lock: &str) -> Vec<Follows> {
217    let Ok(value) = serde_json::from_str::<serde_json::Value>(lock) else {
218        return Vec::new();
219    };
220    let Some((input, node)) = own_input(&value) else {
221        return Vec::new();
222    };
223    let nodes = &value["nodes"];
224    let root = value["root"].as_str().unwrap_or("root");
225    let declared = |name: &str| nodes[root]["inputs"].get(name).is_some();
226    let Some(nested) = nodes[node.as_str()]["inputs"].as_object() else {
227        return Vec::new();
228    };
229    nested
230        .iter()
231        .filter_map(|(name, held)| {
232            // A follows path is a list: the line is already there.
233            let own = held.as_str()?;
234            let target = if names_this_tool(&nodes[own]) {
235                String::new()
236            } else if declared(name) {
237                name.clone()
238            } else if DEVELOPMENT_ONLY_INPUTS.contains(&name.as_str()) {
239                String::new()
240            } else {
241                return None;
242            };
243            Some(Follows {
244                input: input.clone(),
245                nested: name.clone(),
246                line: format!("inputs.{name}.follows = \"{target}\";"),
247            })
248        })
249        .collect()
250}
251
252/// The node one input of `node` resolves to. The input names a node, or
253/// holds a follows path: a list of input names walked from the root node.
254fn input_node(
255    nodes: &serde_json::Value,
256    root: &str,
257    node: &str,
258    input: &str,
259    depth: usize,
260) -> Option<String> {
261    match &nodes[node]["inputs"][input] {
262        serde_json::Value::String(name) => Some(name.clone()),
263        serde_json::Value::Array(path) if depth < MAX_FOLLOWS => {
264            let mut at = root.to_owned();
265            for step in path {
266                at = input_node(nodes, root, &at, step.as_str()?, depth + 1)?;
267            }
268            Some(at)
269        }
270        _ => None,
271    }
272}
273
274/// The name of the flake input whose URL names this tool.
275///
276/// The input is found by the URL it names, never by its name: a consumer
277/// calls the input whatever it likes. The name is read from the attribute
278/// that holds the URL, either `name.url = "..."` or `name = { url = ... }`.
279#[must_use]
280pub fn input_name(flake: &str) -> Option<String> {
281    let needle = format!("github:{}/", slug());
282    let lines: Vec<&str> = flake.lines().collect();
283    let at = lines.iter().position(|line| line.contains(&needle))?;
284    if let Some(name) = attribute_before(lines[at], ".url") {
285        return Some(name);
286    }
287    lines[..at]
288        .iter()
289        .rev()
290        .find_map(|line| attribute_before(line, " ="))
291        .or_else(|| {
292            lines[..at]
293                .iter()
294                .rev()
295                .find_map(|line| attribute_before(line, "="))
296        })
297}
298
299/// The identifier that opens `line` before `suffix`, where the line reads
300/// `  <ident><suffix>...` and the identifier is an attribute name.
301fn attribute_before(line: &str, suffix: &str) -> Option<String> {
302    let trimmed = line.trim_start();
303    let end = trimmed.find(suffix)?;
304    let name = &trimmed[..end];
305    let is_ident = !name.is_empty()
306        && name
307            .bytes()
308            .all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_');
309    if !is_ident || name == "url" || name == "inputs" {
310        return None;
311    }
312    // `name = {` opens an attribute set; `name = "..."` does not hold a URL.
313    if suffix != ".url"
314        && !trimmed[end..]
315            .trim_start_matches(suffix)
316            .trim_start()
317            .starts_with('{')
318    {
319        return None;
320    }
321    Some(name.to_string())
322}
323
324#[cfg(test)]
325mod tests {
326    #![allow(clippy::unwrap_used, reason = "a test panics as its failure signal")]
327
328    use super::*;
329
330    fn flake() -> String {
331        format!(
332            "{{\n  inputs = {{\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    sdd = {{\n      url = \"github:{}/v0.10.1\";\n      inputs.nixpkgs.follows = \"nixpkgs\";\n    }};\n  }};\n}}\n",
333            slug()
334        )
335    }
336
337    /// VERIFIES acquisition:a-fragment-names-the-venue-form
338    #[test]
339    fn a_flake_pin_reads_and_rewrites_in_place() {
340        let text = flake();
341        let pin = read(Manager::Flake, &text).unwrap();
342        assert_eq!(pin.version.to_string(), "0.10.1");
343        assert_eq!(pin.spelled, "v0.10.1");
344        assert_eq!(pin.venue, Some(Venue::Flake));
345        assert_eq!(pin.line, 5);
346        assert_eq!(pin.lines, 1);
347        let (moved, _) = rewrite(Manager::Flake, &text, &"0.10.2".parse().unwrap()).unwrap();
348        assert!(moved.contains(&format!("github:{}/v0.10.2\"", slug())));
349        assert_eq!(moved.len(), text.len());
350        assert_eq!(input_name(&text).as_deref(), Some("sdd"));
351    }
352
353    #[test]
354    fn a_dotted_flake_input_names_itself_on_the_url_line() {
355        let text = format!(
356            "{{ inputs = {{\n  tool.url = \"github:{}/v0.9.0\";\n }}; }}\n",
357            slug()
358        );
359        assert_eq!(input_name(&text).as_deref(), Some("tool"));
360    }
361
362    #[test]
363    fn a_mise_pin_reads_both_forms() {
364        let registry = format!("[tools]\n\"cargo:{CRATE_NAME}\" = \"0.10.1\"\n");
365        let pin = read(Manager::Mise, &registry).unwrap();
366        assert_eq!(pin.venue, Some(Venue::Crates));
367        assert_eq!(pin.spelled, "0.10.1");
368        let archive = format!(
369            "[tools]\n\"ubi:{}\" = {{ version = \"0.10.1\", exe = \"{BINARY_NAME}\" }}\n",
370            slug()
371        );
372        let pin = read(Manager::Mise, &archive).unwrap();
373        assert_eq!(pin.venue, Some(Venue::GithubRelease));
374        let (moved, _) = rewrite(Manager::Mise, &archive, &"0.11.0".parse().unwrap()).unwrap();
375        assert!(moved.contains("version = \"0.11.0\""));
376    }
377
378    #[test]
379    fn an_asdf_pin_reads_the_second_token() {
380        let text = format!("nodejs 20.0.0\n{CRATE_NAME} 0.10.1\n");
381        let pin = read(Manager::Asdf, &text).unwrap();
382        assert_eq!(pin.version.to_string(), "0.10.1");
383        assert_eq!(pin.venue, None);
384        assert!(read(Manager::Asdf, "nodejs 20.0.0\n").is_none());
385    }
386
387    #[test]
388    fn a_devbox_pin_reads_up_to_the_output() {
389        let text = format!(
390            "{{ \"packages\": [\"github:{}/v0.10.1#default\"] }}\n",
391            slug()
392        );
393        let pin = read(Manager::Devbox, &text).unwrap();
394        assert_eq!(pin.spelled, "v0.10.1");
395        let (moved, _) = rewrite(Manager::Devbox, &text, &"0.10.2".parse().unwrap()).unwrap();
396        assert!(moved.contains("v0.10.2#default"));
397    }
398
399    #[test]
400    fn the_lock_revision_is_found_by_the_repository_it_names() {
401        let (owner, repo) = crate::self_depend::coordinates();
402        let lock = format!(
403            "{{\"nodes\":{{\"root\":{{\"inputs\":{{\"sdd\":\"sdd\"}}}},\"sdd\":{{\"locked\":{{\"rev\":\"abc123\"}},\"original\":{{\"owner\":\"{owner}\",\"repo\":\"{repo}\",\"type\":\"github\"}}}}}},\"version\":7}}"
404        );
405        assert_eq!(locked_rev(&lock).as_deref(), Some("abc123"));
406        assert_eq!(locked_rev("{\"nodes\":{}}"), None);
407    }
408
409    /// A node that names this tool's repository, locked at `rev`.
410    fn node(rev: &str) -> String {
411        let (owner, repo) = crate::self_depend::coordinates();
412        format!(
413            "{{\"locked\":{{\"rev\":\"{rev}\"}},\"original\":{{\"owner\":\"{owner}\",\"repo\":\"{repo}\",\"type\":\"github\"}}}}"
414        )
415    }
416
417    #[test]
418    fn a_nested_node_does_not_shadow_the_root_input() {
419        let lock = format!(
420            "{{\"nodes\":{{\"exobrain-tech\":{{\"inputs\":{{\"spec-driven-docs\":\"spec-driven-docs\"}}}},\"spec-driven-docs\":{},\"spec-driven-docs_2\":{},\"top\":{{\"inputs\":{{\"exobrain-tech\":\"exobrain-tech\",\"sdd\":\"spec-driven-docs_2\"}}}}}},\"root\":\"top\",\"version\":7}}",
421            node("nested"),
422            node("own")
423        );
424        assert_eq!(locked_rev(&lock).as_deref(), Some("own"));
425    }
426
427    #[test]
428    fn a_followed_root_input_resolves_through_its_path() {
429        let lock = format!(
430            "{{\"nodes\":{{\"exobrain-tech\":{{\"inputs\":{{\"spec-driven-docs\":\"spec-driven-docs_2\"}}}},\"spec-driven-docs_2\":{},\"root\":{{\"inputs\":{{\"exobrain-tech\":\"exobrain-tech\",\"sdd\":[\"exobrain-tech\",\"spec-driven-docs\"]}}}}}},\"root\":\"root\",\"version\":7}}",
431            node("followed")
432        );
433        assert_eq!(locked_rev(&lock).as_deref(), Some("followed"));
434        let chained = format!(
435            "{{\"nodes\":{{\"a\":{{\"inputs\":{{\"tool\":[\"b\",\"tool\"]}}}},\"b\":{{\"inputs\":{{\"tool\":\"tool_3\"}}}},\"tool_3\":{},\"root\":{{\"inputs\":{{\"a\":\"a\",\"b\":\"b\",\"sdd\":[\"a\",\"tool\"]}}}}}},\"version\":7}}",
436            node("chained")
437        );
438        assert_eq!(locked_rev(&chained).as_deref(), Some("chained"));
439    }
440
441    #[test]
442    fn a_looped_or_broken_follows_path_names_no_input() {
443        let looped = format!(
444            "{{\"nodes\":{{\"spec-driven-docs\":{},\"root\":{{\"inputs\":{{\"sdd\":[\"sdd\"]}}}}}},\"version\":7}}",
445            node("never")
446        );
447        assert_eq!(locked_rev(&looped), None, "a loop names no input");
448        let broken = format!(
449            "{{\"nodes\":{{\"spec-driven-docs\":{},\"root\":{{\"inputs\":{{\"sdd\":[\"absent\",\"sdd\"]}}}}}},\"version\":7}}",
450            node("never")
451        );
452        assert_eq!(locked_rev(&broken), None);
453    }
454
455    #[test]
456    fn a_node_the_root_does_not_reach_is_not_the_project_input() {
457        let lock = format!(
458            "{{\"nodes\":{{\"spec-driven-docs\":{},\"root\":{{\"inputs\":{{\"nixpkgs\":\"nixpkgs\"}}}},\"nixpkgs\":{{\"locked\":{{\"rev\":\"n1\"}}}}}},\"version\":7}}",
459            node("stray")
460        );
461        assert_eq!(locked_rev(&lock), None);
462    }
463
464    /// A lock whose root pins this tool as `sdd`, with `root_extra` more
465    /// root inputs and `nested` the inputs of this tool's node.
466    fn advice_lock(root_extra: &[&str], nested: &str, extra_nodes: &str) -> String {
467        let (owner, repo) = crate::self_depend::coordinates();
468        let root: String = std::iter::once("\"sdd\":\"sdd\"".to_string())
469            .chain(
470                root_extra
471                    .iter()
472                    .map(|name| format!("\"{name}\":\"{name}\"")),
473            )
474            .collect::<Vec<_>>()
475            .join(",");
476        format!(
477            "{{\"nodes\":{{\"root\":{{\"inputs\":{{{root}}}}},\"sdd\":{{\"inputs\":{{{nested}}},\"locked\":{{\"rev\":\"r\"}},\"original\":{{\"owner\":\"{owner}\",\"repo\":\"{repo}\",\"type\":\"github\"}}}}{extra_nodes}}},\"root\":\"root\",\"version\":7}}"
478        )
479    }
480
481    fn lines(advice: &[Follows]) -> Vec<&str> {
482        advice.iter().map(|follows| follows.line.as_str()).collect()
483    }
484
485    /// VERIFIES acquisition:sync-advises-the-follows-lines-and-writes-none
486    #[test]
487    fn a_nested_input_the_root_declares_follows_the_roots() {
488        let lock = advice_lock(
489            &["release-kit"],
490            "\"release-kit\":\"release-kit_2\"",
491            ",\"release-kit\":{},\"release-kit_2\":{}",
492        );
493        let advice = follows_advice(&lock);
494        assert_eq!(
495            lines(&advice),
496            ["inputs.release-kit.follows = \"release-kit\";"]
497        );
498        assert_eq!(advice[0].input, "sdd");
499    }
500
501    /// VERIFIES acquisition:sync-advises-the-follows-lines-and-writes-none
502    #[test]
503    fn a_development_only_input_the_root_lacks_follows_nothing() {
504        let lock = advice_lock(
505            &[],
506            "\"exobrain-tech\":\"exobrain-tech\",\"release-kit\":\"release-kit\"",
507            ",\"exobrain-tech\":{},\"release-kit\":{}",
508        );
509        assert_eq!(
510            lines(&follows_advice(&lock)),
511            [
512                "inputs.exobrain-tech.follows = \"\";",
513                "inputs.release-kit.follows = \"\";"
514            ]
515        );
516    }
517
518    /// VERIFIES acquisition:sync-advises-the-follows-lines-and-writes-none
519    #[test]
520    fn a_nested_nixpkgs_the_root_lacks_gets_no_advice() {
521        let lock = advice_lock(
522            &[],
523            "\"nixpkgs\":\"nixpkgs\",\"rust-overlay\":\"rust-overlay\"",
524            ",\"nixpkgs\":{},\"rust-overlay\":{}",
525        );
526        assert!(follows_advice(&lock).is_empty());
527    }
528
529    /// VERIFIES acquisition:sync-advises-the-follows-lines-and-writes-none
530    #[test]
531    fn a_nested_older_release_of_this_tool_follows_nothing() {
532        let (owner, repo) = crate::self_depend::coordinates();
533        let lock = advice_lock(
534            &[],
535            "\"spec-driven-docs\":\"spec-driven-docs\"",
536            &format!(
537                ",\"spec-driven-docs\":{{\"original\":{{\"owner\":\"{owner}\",\"repo\":\"{repo}\",\"type\":\"github\"}}}}"
538            ),
539        );
540        assert_eq!(
541            lines(&follows_advice(&lock)),
542            ["inputs.spec-driven-docs.follows = \"\";"]
543        );
544    }
545
546    /// VERIFIES acquisition:sync-advises-the-follows-lines-and-writes-none
547    #[test]
548    fn a_lock_with_every_follows_line_in_place_advises_nothing() {
549        let lock = advice_lock(
550            &["nixpkgs", "release-kit"],
551            "\"nixpkgs\":[\"nixpkgs\"],\"release-kit\":[\"release-kit\"],\"exobrain-tech\":[],\"spec-driven-docs\":[]",
552            ",\"nixpkgs\":{},\"release-kit\":{}",
553        );
554        assert!(follows_advice(&lock).is_empty());
555        assert!(follows_advice("not json").is_empty());
556    }
557}