Skip to main content

spec_driven_docs/domain/
migration.rs

1//! The registry an open migration keeps, and the rules that move it.
2//!
3//! A migration archives a corpus, lands a greenfield instance, and rebuilds
4//! the documentation from the archive over many runs. The registry is the
5//! one record of that work: every source with its checksum, its kind, the
6//! group the agent filed it in, and a dated history of each status it took.
7//! Only the `sdd migrate` verbs write it, so every entry in that history is
8//! one the binary appended.
9//!
10//! This module is pure: it parses, renders, and changes a registry in
11//! memory. Where the registry lives and what touches the disk is the
12//! migration service's business.
13
14use camino::{Utf8Path, Utf8PathBuf};
15use serde::{Deserialize, Serialize};
16
17/// The file the registry is written to, inside the workspace.
18pub const REGISTRY_FILE: &str = "registry.yaml";
19/// The directory the archived sources sit under, inside the workspace.
20pub const SOURCES_DIR: &str = "sources";
21/// The registry shape this binary reads and writes.
22pub const REGISTRY_SCHEMA: u32 = 1;
23
24/// Where one source stands.
25#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, clap::ValueEnum)]
26#[serde(rename_all = "kebab-case")]
27pub enum Status {
28    /// Archived or registered, and not yet mapped.
29    Pending,
30    /// Filed into a group whose destinations the operator approved.
31    Mapped,
32    /// Its destinations are written.
33    Written,
34    /// Its destinations are written and read against the source.
35    Verified,
36    /// Deliberately carried nowhere, with the reason recorded.
37    Dropped,
38}
39
40impl Status {
41    /// The word the command line and the registry spell.
42    #[must_use]
43    pub const fn as_str(self) -> &'static str {
44        match self {
45            Self::Pending => "pending",
46            Self::Mapped => "mapped",
47            Self::Written => "written",
48            Self::Verified => "verified",
49            Self::Dropped => "dropped",
50        }
51    }
52
53    /// Whether a source in this status is finished.
54    #[must_use]
55    pub const fn finished(self) -> bool {
56        matches!(self, Self::Verified | Self::Dropped)
57    }
58}
59
60/// What kind of document a source is, read from its name and its home.
61#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
62#[serde(rename_all = "kebab-case")]
63pub enum Kind {
64    /// A decision record of a previous convention.
65    Decision,
66    /// A specification.
67    Spec,
68    /// A step-by-step guide.
69    Guide,
70    /// Root metadata the project needs during the migration.
71    Metadata,
72    /// Any other document.
73    Document,
74}
75
76/// Whether a source moves into the archive or is rewritten where it is.
77#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
78#[serde(rename_all = "kebab-case")]
79pub enum Placement {
80    /// Moved into the archive, and rebuilt from there.
81    Archived,
82    /// Root metadata the project still needs, rewritten in place.
83    InPlace,
84}
85
86/// One dated status change.
87#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
88#[serde(deny_unknown_fields)]
89pub struct Event {
90    /// When, in UTC.
91    pub at: String,
92    /// The status the source took.
93    pub status: Status,
94    /// Why, where the status is `dropped`.
95    #[serde(default, skip_serializing_if = "Option::is_none")]
96    pub reason: Option<String>,
97}
98
99/// One source document of the previous corpus.
100#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
101#[serde(deny_unknown_fields)]
102pub struct Source {
103    /// A slug unique within the registry.
104    pub id: String,
105    /// Where it sat in the repository at the base commit.
106    pub path: Utf8PathBuf,
107    /// The SHA-256 of its bytes at the base commit.
108    pub sha256: String,
109    /// What kind of document it is.
110    pub kind: Kind,
111    /// Whether it was archived or stays in place.
112    pub placement: Placement,
113    /// The topics the agent tagged it with.
114    #[serde(default)]
115    pub tags: Vec<String>,
116    /// The group the agent filed it in.
117    #[serde(default, skip_serializing_if = "Option::is_none")]
118    pub group: Option<String>,
119    /// Where it stands now.
120    pub status: Status,
121    /// Every status it took, oldest first. Never rewritten.
122    #[serde(default)]
123    pub history: Vec<Event>,
124}
125
126/// Sources the agent reads into one context and rebuilds together.
127#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
128#[serde(deny_unknown_fields)]
129pub struct Group {
130    /// A slug unique within the registry.
131    pub id: String,
132    /// The source ids filed in it.
133    #[serde(default)]
134    pub sources: Vec<String>,
135    /// The documents of the instance the group becomes.
136    #[serde(default)]
137    pub destinations: Vec<Utf8PathBuf>,
138}
139
140/// The whole registry of one open migration.
141#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
142#[serde(deny_unknown_fields)]
143pub struct Registry {
144    /// The registry shape.
145    pub schema_version: u32,
146    /// The migration id the declaration names.
147    pub id: String,
148    /// The commit that held every source byte when the archive ran.
149    pub base_commit: String,
150    /// Every source, in path order.
151    pub sources: Vec<Source>,
152    /// Every group, in the order the agent filed them.
153    #[serde(default)]
154    pub groups: Vec<Group>,
155}
156
157/// A registry change this binary refuses.
158#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
159pub enum RegistryError {
160    /// The file is not a registry of this shape.
161    #[error("the registry does not parse: {0}")]
162    Shape(String),
163    /// No source and no group carries this id or path.
164    #[error("the registry names no source or group `{0}`")]
165    Unknown(String),
166    /// A drop with no reason.
167    #[error("a source is dropped with its reason: pass --reason")]
168    NoReason,
169    /// A group flag on a group, or a destination on a single source.
170    #[error("{0}")]
171    Misplaced(String),
172    /// An id that is not a slug.
173    #[error("`{0}` is not a slug of lowercase letters, digits, and hyphens")]
174    NotASlug(String),
175}
176
177/// What one `mark` asks for, beyond the status.
178#[derive(Debug, Clone, Default, PartialEq, Eq)]
179pub struct Marking {
180    /// File the source into this group, creating the group where it is new.
181    pub group: Option<String>,
182    /// Tag the source with each of these topics.
183    pub tags: Vec<String>,
184    /// Give the group each of these destinations.
185    pub destinations: Vec<Utf8PathBuf>,
186    /// Why the source is dropped.
187    pub reason: Option<String>,
188}
189
190/// Whether `value` is a lowercase slug.
191#[must_use]
192pub fn is_slug(value: &str) -> bool {
193    !value.is_empty()
194        && !value.starts_with('-')
195        && !value.ends_with('-')
196        && value
197            .bytes()
198            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
199}
200
201/// The slug a path reads as: lowercase, every other character a hyphen.
202#[must_use]
203pub fn slug_of(path: &Utf8Path) -> String {
204    let mut out = String::new();
205    for character in path.as_str().chars() {
206        if character.is_ascii_alphanumeric() {
207            out.push(character.to_ascii_lowercase());
208        } else if !out.ends_with('-') && !out.is_empty() {
209            out.push('-');
210        }
211    }
212    out.trim_end_matches('-').to_string()
213}
214
215/// The kind a document is, read from its name and the directories it sits
216/// in. Root metadata is read by the caller, which knows the metadata names.
217#[must_use]
218pub fn kind_of(path: &Utf8Path, metadata: bool) -> Kind {
219    if metadata {
220        return Kind::Metadata;
221    }
222    let name = path.file_name().unwrap_or_default();
223    let within = |names: &[&str]| {
224        path.parent().is_some_and(|parent| {
225            parent
226                .components()
227                .any(|part| names.contains(&part.as_str().to_ascii_lowercase().as_str()))
228        })
229    };
230    let shaped = |prefix: &str| {
231        name.starts_with(prefix) && path.extension().is_some_and(|extension| extension == "md")
232    };
233    if shaped("ADR-") || within(&["decisions", "adr", "adrs"]) {
234        Kind::Decision
235    } else if shaped("SPEC-") || within(&["specs"]) {
236        Kind::Spec
237    } else if within(&["guides"]) {
238        Kind::Guide
239    } else {
240        Kind::Document
241    }
242}
243
244impl Registry {
245    /// Parse a registry.
246    ///
247    /// # Errors
248    ///
249    /// [`RegistryError::Shape`] when the text is not a registry of this
250    /// shape.
251    pub fn parse(text: &str) -> Result<Self, RegistryError> {
252        let parsed: Self =
253            yaml_serde::from_str(text).map_err(|error| RegistryError::Shape(error.to_string()))?;
254        if parsed.schema_version != REGISTRY_SCHEMA {
255            return Err(RegistryError::Shape(format!(
256                "schema_version {} is not {REGISTRY_SCHEMA}",
257                parsed.schema_version
258            )));
259        }
260        Ok(parsed)
261    }
262
263    /// The registry as the file spells it.
264    ///
265    /// # Errors
266    ///
267    /// [`RegistryError::Shape`] where the registry cannot be rendered.
268    pub fn render(&self) -> Result<String, RegistryError> {
269        yaml_serde::to_string(self).map_err(|error| RegistryError::Shape(error.to_string()))
270    }
271
272    /// Apply one `mark`: set the status of a source, or of every source in a
273    /// group, and append a dated event to each.
274    ///
275    /// A group flag and tags apply to a single source. Destinations apply to
276    /// a group, because a group is what becomes the documents. An earlier
277    /// event is never touched.
278    ///
279    /// # Errors
280    ///
281    /// [`RegistryError`] naming what the request cannot mean. Nothing is
282    /// changed when it refuses.
283    pub fn mark(
284        &mut self,
285        target: &str,
286        status: Status,
287        marking: &Marking,
288        at: &str,
289    ) -> Result<Vec<String>, RegistryError> {
290        if status == Status::Dropped && marking.reason.is_none() {
291            return Err(RegistryError::NoReason);
292        }
293        for slug in marking.group.iter().chain(&marking.tags) {
294            if !is_slug(slug) {
295                return Err(RegistryError::NotASlug(slug.clone()));
296            }
297        }
298        let event = Event {
299            at: at.to_string(),
300            status,
301            reason: marking.reason.clone(),
302        };
303        if let Some(index) = self.groups.iter().position(|group| group.id == target) {
304            if marking.group.is_some() || !marking.tags.is_empty() {
305                return Err(RegistryError::Misplaced(format!(
306                    "`{target}` is a group; --group and --tag file a single source"
307                )));
308            }
309            for destination in &marking.destinations {
310                if !self.groups[index].destinations.contains(destination) {
311                    self.groups[index].destinations.push(destination.clone());
312                }
313            }
314            let members = self.groups[index].sources.clone();
315            for source in &mut self.sources {
316                if members.contains(&source.id) {
317                    source.status = status;
318                    source.history.push(event.clone());
319                }
320            }
321            return Ok(members);
322        }
323        let index = self
324            .sources
325            .iter()
326            .position(|source| source.id == target || source.path.as_str() == target)
327            .ok_or_else(|| RegistryError::Unknown(target.to_string()))?;
328        if !marking.destinations.is_empty() {
329            return Err(RegistryError::Misplaced(format!(
330                "`{target}` is a source; --destination belongs to its group"
331            )));
332        }
333        let id = self.sources[index].id.clone();
334        if let Some(group) = &marking.group {
335            for existing in &mut self.groups {
336                existing.sources.retain(|member| *member != id);
337            }
338            match self
339                .groups
340                .iter_mut()
341                .find(|existing| existing.id == *group)
342            {
343                Some(existing) => existing.sources.push(id.clone()),
344                None => self.groups.push(Group {
345                    id: group.clone(),
346                    sources: vec![id.clone()],
347                    destinations: Vec::new(),
348                }),
349            }
350            self.sources[index].group = Some(group.clone());
351        }
352        let source = &mut self.sources[index];
353        for tag in &marking.tags {
354            if !source.tags.contains(tag) {
355                source.tags.push(tag.clone());
356            }
357        }
358        source.status = status;
359        source.history.push(event);
360        Ok(vec![id])
361    }
362
363    /// Why the migration cannot close yet, one line per reason.
364    ///
365    /// A source is finished when it is verified or dropped. A verified
366    /// source needs a group whose every destination exists, because a fact
367    /// with no destination is not migrated.
368    #[must_use]
369    pub fn unfinished(&self, exists: impl Fn(&Utf8Path) -> bool) -> Vec<String> {
370        let mut reasons = Vec::new();
371        for source in &self.sources {
372            if !source.status.finished() {
373                reasons.push(format!("{} is {}", source.id, source.status.as_str()));
374                continue;
375            }
376            if source.status == Status::Dropped {
377                continue;
378            }
379            let group = source
380                .group
381                .as_ref()
382                .and_then(|id| self.groups.iter().find(|group| group.id == *id));
383            match group {
384                None => reasons.push(format!("{} is verified and filed in no group", source.id)),
385                Some(group) if group.destinations.is_empty() => reasons.push(format!(
386                    "{} is verified and its group {} names no destination",
387                    source.id, group.id
388                )),
389                Some(group) => {
390                    for destination in &group.destinations {
391                        if !exists(destination) {
392                            reasons.push(format!(
393                                "{}: the destination {destination} does not exist",
394                                group.id
395                            ));
396                        }
397                    }
398                }
399            }
400        }
401        reasons.sort();
402        reasons.dedup();
403        reasons
404    }
405}
406
407#[cfg(test)]
408mod tests {
409    use super::*;
410
411    fn registry() -> Registry {
412        let source = |id: &str, path: &str| Source {
413            id: id.to_string(),
414            path: Utf8PathBuf::from(path),
415            sha256: "00".to_string(),
416            kind: Kind::Decision,
417            placement: Placement::Archived,
418            tags: Vec::new(),
419            group: None,
420            status: Status::Pending,
421            history: Vec::new(),
422        };
423        Registry {
424            schema_version: REGISTRY_SCHEMA,
425            id: "20261009T213000Z".to_string(),
426            base_commit: "4f1c2e0".to_string(),
427            sources: vec![
428                source("docs-adr-0003-md", "docs/adr/0003.md"),
429                source("docs-adr-0007-md", "docs/adr/0007.md"),
430            ],
431            groups: Vec::new(),
432        }
433    }
434
435    #[test]
436    fn a_path_reads_as_one_slug() {
437        assert_eq!(
438            slug_of(Utf8Path::new("docs/adr/0007-Use Postgres.md")),
439            "docs-adr-0007-use-postgres-md"
440        );
441    }
442
443    #[test]
444    fn a_kind_is_read_from_the_name_and_the_home() {
445        assert_eq!(
446            kind_of(Utf8Path::new("docs/adr/0007.md"), false),
447            Kind::Decision
448        );
449        assert_eq!(kind_of(Utf8Path::new("x/SPEC-a.md"), false), Kind::Spec);
450        assert_eq!(
451            kind_of(Utf8Path::new("docs/guides/a.md"), false),
452            Kind::Guide
453        );
454        assert_eq!(kind_of(Utf8Path::new("README.md"), true), Kind::Metadata);
455        assert_eq!(
456            kind_of(Utf8Path::new("docs/intro.md"), false),
457            Kind::Document
458        );
459    }
460
461    /// VERIFIES setup:mark-appends-and-never-rewrites
462    #[test]
463    fn mark_appends_history_and_never_rewrites_an_earlier_entry() {
464        let mut registry = registry();
465        let filing = Marking {
466            group: Some("storage".to_string()),
467            tags: vec!["storage".to_string()],
468            ..Marking::default()
469        };
470        registry
471            .mark("docs-adr-0003-md", Status::Mapped, &filing, "t1")
472            .unwrap();
473        registry
474            .mark("docs/adr/0007.md", Status::Mapped, &filing, "t2")
475            .unwrap();
476        let first = registry.sources[0].history.clone();
477        let destinations = Marking {
478            destinations: vec![Utf8PathBuf::from("_docs/decisions/ADR-store-state.md")],
479            ..Marking::default()
480        };
481        let marked = registry
482            .mark("storage", Status::Verified, &destinations, "t3")
483            .unwrap();
484        assert_eq!(marked, ["docs-adr-0003-md", "docs-adr-0007-md"]);
485        assert_eq!(registry.sources[0].history[..1], first[..]);
486        assert_eq!(registry.sources[0].history.len(), 2);
487        assert_eq!(registry.groups[0].sources.len(), 2);
488        assert_eq!(registry.groups[0].destinations.len(), 1);
489    }
490
491    #[test]
492    fn a_drop_needs_its_reason_and_a_refusal_changes_nothing() {
493        let mut registry = registry();
494        let before = registry.clone();
495        assert_eq!(
496            registry.mark(
497                "docs-adr-0003-md",
498                Status::Dropped,
499                &Marking::default(),
500                "t"
501            ),
502            Err(RegistryError::NoReason)
503        );
504        assert!(
505            registry
506                .mark("nope", Status::Mapped, &Marking::default(), "t")
507                .is_err()
508        );
509        assert_eq!(registry, before);
510        let reason = Marking {
511            reason: Some("superseded by 0007".to_string()),
512            ..Marking::default()
513        };
514        registry
515            .mark("docs-adr-0003-md", Status::Dropped, &reason, "t")
516            .unwrap();
517        let text = registry.render().unwrap();
518        assert_eq!(Registry::parse(&text).unwrap(), registry);
519    }
520
521    /// VERIFIES setup:close-refuses-an-unfinished-source
522    #[test]
523    fn close_waits_for_every_source_and_every_destination() {
524        let mut registry = registry();
525        assert_eq!(registry.unfinished(|_| true).len(), 2);
526        let filing = Marking {
527            group: Some("storage".to_string()),
528            ..Marking::default()
529        };
530        registry
531            .mark("docs-adr-0003-md", Status::Verified, &filing, "t")
532            .unwrap();
533        registry
534            .mark("docs-adr-0007-md", Status::Verified, &filing, "t")
535            .unwrap();
536        assert!(
537            !registry.unfinished(|_| true).is_empty(),
538            "no destination yet"
539        );
540        let destinations = Marking {
541            destinations: vec![Utf8PathBuf::from("ADR-x.md")],
542            ..Marking::default()
543        };
544        registry
545            .mark("storage", Status::Verified, &destinations, "t")
546            .unwrap();
547        assert!(
548            !registry.unfinished(|_| false).is_empty(),
549            "the file is absent"
550        );
551        assert!(registry.unfinished(|_| true).is_empty());
552    }
553
554    /// VERIFIES setup:close-refuses-an-unfinished-source
555    #[test]
556    fn a_group_with_no_live_source_does_not_block_close() {
557        let mut registry = registry();
558        let into = |group: &str| Marking {
559            group: Some(group.to_string()),
560            ..Marking::default()
561        };
562        let aimed = |path: &str| Marking {
563            destinations: vec![Utf8PathBuf::from(path)],
564            ..Marking::default()
565        };
566        // One group loses its source to another group, and one loses its
567        // only source to a drop. Neither destination exists.
568        registry
569            .mark("docs-adr-0003-md", Status::Mapped, &into("first"), "t")
570            .unwrap();
571        registry
572            .mark("first", Status::Mapped, &aimed("gone.md"), "t")
573            .unwrap();
574        registry
575            .mark("docs-adr-0003-md", Status::Verified, &into("kept"), "t")
576            .unwrap();
577        registry
578            .mark("kept", Status::Verified, &aimed("kept.md"), "t")
579            .unwrap();
580        registry
581            .mark("docs-adr-0007-md", Status::Mapped, &into("dropped"), "t")
582            .unwrap();
583        registry
584            .mark("dropped", Status::Mapped, &aimed("never.md"), "t")
585            .unwrap();
586        let reason = Marking {
587            reason: Some("said elsewhere".to_string()),
588            ..Marking::default()
589        };
590        registry
591            .mark("docs-adr-0007-md", Status::Dropped, &reason, "t")
592            .unwrap();
593        assert!(
594            registry
595                .unfinished(|path| path == Utf8Path::new("kept.md"))
596                .is_empty()
597        );
598    }
599}