Skip to main content

spec_driven_docs/landing/
observe.rs

1//! What the planner is told, and the one place that reads it.
2//!
3//! The planner is pure, so everything it needs arrives as a value: the
4//! repository, the installation, the host, and the corpus. This module is
5//! the impure half that produces those values, and it is the only part of
6//! the plan tree that touches a disk.
7//!
8//! Reading is bounded. An observation that cannot be made is recorded as
9//! not observed, with the reason, so the readiness policy can weigh it.
10//! An observation whose failure has no bound — an unreadable target — is a
11//! command error rather than a plan built on a guess.
12
13use std::collections::BTreeMap;
14
15use camino::{Utf8Path, Utf8PathBuf};
16use serde::{Deserialize, Serialize};
17
18use crate::domain::instance_config::CONFIG_PATH;
19use crate::domain::manifest::{INSTANCE_DIR, MANIFEST_PATH};
20use crate::domain::ownership::Sha256;
21use crate::domain::paths::UserEnv;
22use crate::domain::profile::{DocsRoot, ProfileId};
23use crate::domain::version::CanonVersion;
24use crate::error::AppError;
25use crate::landing::finding::{is_ordinal_name, is_record_shaped, is_spec_shaped};
26use crate::landing::path::TargetPath;
27
28/// The documentation roots a corpus conventionally lives under.
29const DOC_ROOTS: &[&str] = &["docs", "_docs", "doc", "documentation"];
30
31/// Root-level filename stems that are metadata rather than a corpus.
32const ROOT_METADATA: &[&str] = &[
33    "readme",
34    "license",
35    "licence",
36    "contributing",
37    "changelog",
38    "agents",
39    "claude",
40    "code_of_conduct",
41];
42
43/// Directory names no observation walks into.
44const SKIPPED: &[&str] = &[".git", ".jj", "target", "node_modules", INSTANCE_DIR];
45
46/// Extensions a durable document conventionally carries.
47const DOC_EXTENSIONS: &[&str] = &["md", "markdown", "adoc", "rst", "org"];
48
49/// The target itself.
50#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
51pub struct Repository {
52    /// Where it is.
53    pub root: Utf8PathBuf,
54    /// Whether version control is there to restore a retirement.
55    pub version_controlled: bool,
56    /// Whether it holds anything at all.
57    pub empty: bool,
58}
59
60/// One file the instance records.
61#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
62pub struct RecordedFile {
63    /// Where, relative to the target.
64    pub path: TargetPath,
65    /// What the record says the tool wrote there.
66    pub recorded: Sha256,
67    /// What the baseline was, for an adopted file.
68    #[serde(default, skip_serializing_if = "Option::is_none")]
69    pub baseline: Option<Sha256>,
70    /// What the target holds now, or nothing where the file is gone.
71    #[serde(default, skip_serializing_if = "Option::is_none")]
72    pub held: Option<Sha256>,
73}
74
75/// What is installed at the target.
76#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
77pub struct Installation {
78    /// The release the record names.
79    pub canon_version: CanonVersion,
80    /// The profile the record names.
81    pub profile: ProfileId,
82    /// The documentation root the record names.
83    pub docs_root: DocsRoot,
84    /// The record's own digest.
85    pub record_sha256: Sha256,
86    /// The project's declaration digest, where it has one.
87    #[serde(default, skip_serializing_if = "Option::is_none")]
88    pub declaration_sha256: Option<Sha256>,
89    /// Every managed file, as recorded and as found.
90    pub managed: Vec<RecordedFile>,
91    /// Every adopted file, as recorded and as found.
92    pub adopted: Vec<RecordedFile>,
93    /// Every marked region the canon owns, as recorded and as found.
94    pub blocks: Vec<RecordedBlock>,
95}
96
97/// One marked region a file the project owns carries.
98#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
99pub struct RecordedBlock {
100    /// The host file, relative to the target.
101    pub path: TargetPath,
102    /// The region's digest as the record has it.
103    pub recorded: Sha256,
104    /// The region's digest now, or nothing where the host or the markers
105    /// are gone.
106    pub held: Option<Sha256>,
107}
108
109impl Installation {
110    /// Whether any recorded file or region has moved or gone.
111    ///
112    /// An adopted edit counts: the project keeps it, and a landing still
113    /// owes the record its bytes.
114    #[must_use]
115    pub fn drifted(&self) -> bool {
116        self.managed
117            .iter()
118            .chain(&self.adopted)
119            .any(|file| file.held.as_ref() != Some(&file.recorded))
120            || self
121                .blocks
122                .iter()
123                .any(|block| block.held.as_ref() != Some(&block.recorded))
124    }
125}
126
127/// The host the command ran on.
128#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
129pub struct Host {
130    /// Whether this run may reach the network.
131    pub offline: bool,
132    /// Where this tool keeps what it can fetch again.
133    #[serde(default, skip_serializing_if = "Option::is_none")]
134    pub cache_root: Option<Utf8PathBuf>,
135}
136
137/// What the corpus looks like, as counts and paths a detector reads.
138#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
139pub struct Corpus {
140    /// Documentation roots at the top level that hold anything.
141    pub populated_doc_roots: Vec<String>,
142    /// Every durable document, relative to the target, sorted.
143    pub documents: Vec<TargetPath>,
144    /// Documents shaped like a specification of this convention.
145    pub spec_shaped: Vec<TargetPath>,
146    /// Specification-shaped documents that define no rule identifier.
147    pub spec_without_rule_id: Vec<TargetPath>,
148    /// Documents named by their position rather than their subject.
149    pub ordinal_named: Vec<TargetPath>,
150    /// Decision records outside a decisions directory.
151    pub records_outside_decisions: Vec<TargetPath>,
152    /// Whether a specifications directory exists under a documentation root.
153    pub has_specs_directory: bool,
154}
155
156impl Corpus {
157    /// Whether the target documents itself already.
158    ///
159    /// Documents, not directories. A documentation root holding empty
160    /// directories is a layout somebody started and not a corpus somebody
161    /// wrote, and refusing to land beside it would refuse a repository
162    /// that has written nothing.
163    #[must_use]
164    pub const fn settled(&self) -> bool {
165        !self.documents.is_empty()
166    }
167}
168
169/// Everything the planner is told about one target.
170#[derive(Debug, Clone, PartialEq, Eq)]
171pub struct Observation {
172    /// The target itself.
173    pub repository: Repository,
174    /// What is installed, where anything is.
175    pub installation: Option<Installation>,
176    /// Why no installation was read, where metadata exists and is broken.
177    pub invalid: Option<String>,
178    /// The host.
179    pub host: Host,
180    /// The corpus.
181    pub corpus: Corpus,
182}
183
184/// Read one target.
185///
186/// # Errors
187///
188/// [`AppError::Usage`] when the target is not a directory, and
189/// [`AppError::Io`] when the walk cannot complete. Both are failures whose
190/// scope cannot be bounded: a plan built on half a reading would describe
191/// a repository nobody looked at.
192pub fn observe(target: &Utf8Path) -> Result<Observation, AppError> {
193    match std::fs::metadata(target) {
194        Ok(metadata) if !metadata.is_dir() => {
195            return Err(AppError::Usage(format!(
196                "target is not a directory: {target}"
197            )));
198        }
199        Ok(_) => {}
200        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
201            return Err(AppError::Usage(format!("unresolved target: {target}")));
202        }
203        Err(error) => return Err(AppError::Io(error)),
204    }
205
206    let env = UserEnv::from_process();
207    let host = Host {
208        offline: crate::domain::paths::variable(crate::domain::paths::OFFLINE_VAR).is_some(),
209        cache_root: env.user_paths().map(|paths| paths.cache_root.path),
210    };
211
212    let (installation, invalid) = read_installation(target);
213    let corpus = read_corpus(target)?;
214    let repository = Repository {
215        root: target.to_owned(),
216        version_controlled: target.join(".git").exists(),
217        empty: is_empty(target)?,
218    };
219    Ok(Observation {
220        repository,
221        installation,
222        invalid,
223        host,
224        corpus,
225    })
226}
227
228/// Whether a target holds anything but version control.
229fn is_empty(target: &Utf8Path) -> Result<bool, AppError> {
230    for entry in std::fs::read_dir(target)? {
231        let entry = entry?;
232        let name = entry.file_name().to_string_lossy().to_string();
233        if name != ".git" && name != ".jj" {
234            return Ok(false);
235        }
236    }
237    Ok(true)
238}
239
240/// Read the instance record, or say why it could not be trusted.
241///
242/// Every failure here is one of the two answers rather than an error: a
243/// record that is absent and one that is broken are both things the plan
244/// reports, and neither stops the observation.
245fn read_installation(target: &Utf8Path) -> (Option<Installation>, Option<String>) {
246    let path = target.join(MANIFEST_PATH);
247    let text = match std::fs::read_to_string(&path) {
248        Ok(text) => text,
249        // Absent is absent. Anything else — unreadable, not UTF-8, a
250        // permission refusal — is a record that exists and cannot be
251        // trusted, and reporting it as absence would land seeds over it.
252        Err(source) if source.kind() == std::io::ErrorKind::NotFound => return (None, None),
253        Err(source) => {
254            return (
255                None,
256                Some(format!("{path} exists and cannot be read: {source}")),
257            );
258        }
259    };
260    // The record's schema is its own axis. A record an older release wrote
261    // is a record this engine reads well enough to classify: what it needs
262    // is the version, the profile, the root, and the two file lists, and
263    // every schema this tool has written carries those under those names.
264    // Only a record it cannot read at all is invalid, because absence and
265    // breakage are different findings.
266    let Some(manifest) = read_any_schema(&text) else {
267        return (
268            None,
269            Some(format!(
270                "{MANIFEST_PATH} is not a record this engine can read"
271            )),
272        );
273    };
274    let held = |destination: &str| -> Option<Sha256> {
275        std::fs::read(target.join(destination))
276            .ok()
277            .map(|bytes| Sha256::of(&bytes))
278    };
279    let mut managed = Vec::new();
280    for (destination, recorded) in &manifest.managed_files {
281        let Ok(path) = TargetPath::new(destination) else {
282            return (
283                None,
284                Some(format!(
285                    "{MANIFEST_PATH} records the destination {destination}, which no operation may name"
286                )),
287            );
288        };
289        managed.push(RecordedFile {
290            held: held(destination),
291            path,
292            recorded: recorded.clone(),
293            baseline: None,
294        });
295    }
296    let mut adopted = Vec::new();
297    for (destination, recorded, baseline) in &manifest.adopted_files {
298        let Ok(path) = TargetPath::new(destination) else {
299            return (
300                None,
301                Some(format!(
302                    "{MANIFEST_PATH} records the destination {destination}, which no operation may name"
303                )),
304            );
305        };
306        adopted.push(RecordedFile {
307            held: held(destination),
308            path,
309            recorded: recorded.clone(),
310            baseline: Some(baseline.clone()),
311        });
312    }
313    // A marked region is managed too. The host file is the project's and
314    // its other bytes are none of this tool's business, so the region is
315    // compared by its own hash: an edit inside the markers is a conflict
316    // the next landing would overwrite, and an edit outside them is not.
317    let mut blocks = Vec::new();
318    for (host, recorded) in &manifest.integration_blocks {
319        let Ok(path) = TargetPath::new(host) else {
320            return (
321                None,
322                Some(format!(
323                    "{MANIFEST_PATH} records the block host {host}, which no operation may name"
324                )),
325            );
326        };
327        let (begin, end) = markers_for(host);
328        let held = std::fs::read_to_string(target.join(host))
329            .ok()
330            .and_then(|text| crate::domain::marker::block_hash_with(&text, begin, end));
331        blocks.push(RecordedBlock {
332            path,
333            recorded: recorded.clone(),
334            held,
335        });
336    }
337
338    let declaration_sha256 = std::fs::read(target.join(CONFIG_PATH))
339        .ok()
340        .map(|bytes| Sha256::of(&bytes));
341    (
342        Some(Installation {
343            canon_version: manifest.canon_version,
344            profile: manifest.profile,
345            docs_root: manifest.docs_root,
346            record_sha256: Sha256::of(text.as_bytes()),
347            declaration_sha256,
348            managed,
349            adopted,
350            blocks,
351        }),
352        None,
353    )
354}
355
356/// The markers one integration host carries.
357fn markers_for(path: &str) -> (&'static str, &'static str) {
358    use crate::domain::marker::{AGENTS_BEGIN, AGENTS_END, BEGIN, END};
359    if path == crate::domain::paths::HOOKS_CONFIG_PATH {
360        (BEGIN, END)
361    } else {
362        (AGENTS_BEGIN, AGENTS_END)
363    }
364}
365
366/// One record's facts, whichever schema wrote it.
367struct AnyRecord {
368    canon_version: CanonVersion,
369    profile: ProfileId,
370    docs_root: DocsRoot,
371    managed_files: Vec<(String, Sha256)>,
372    adopted_files: Vec<(String, Sha256, Sha256)>,
373    integration_blocks: Vec<(String, Sha256)>,
374}
375
376fn read_any_schema(text: &str) -> Option<AnyRecord> {
377    let held: serde_json::Value = serde_json::from_str(text).ok()?;
378    let files = |key: &str| -> Vec<serde_json::Value> {
379        held.get(key)
380            .and_then(|value| value.as_array())
381            .cloned()
382            .unwrap_or_default()
383    };
384    let digest = |entry: &serde_json::Value, key: &str| -> Option<Sha256> {
385        entry.get(key)?.as_str()?.parse().ok()
386    };
387    let destination = |entry: &serde_json::Value| -> Option<String> {
388        Some(entry.get("destination")?.as_str()?.to_string())
389    };
390    Some(AnyRecord {
391        canon_version: held.get("canon_version")?.as_str()?.parse().ok()?,
392        profile: serde_json::from_value(held.get("profile")?.clone()).ok()?,
393        docs_root: serde_json::from_value(held.get("docs_root")?.clone()).ok()?,
394        managed_files: files("managed_files")
395            .iter()
396            .filter_map(|entry| Some((destination(entry)?, digest(entry, "sha256")?)))
397            .collect(),
398        // All or nothing. An entry this engine cannot read is a record it
399        // cannot vouch for, and dropping it would report a managed region
400        // as absent, which is what lets the next landing overwrite it.
401        integration_blocks: files("integration_blocks")
402            .iter()
403            .map(|entry| {
404                Some((
405                    entry.get("path")?.as_str()?.to_string(),
406                    digest(entry, "marker_hash")?,
407                ))
408            })
409            .collect::<Option<Vec<_>>>()?,
410        adopted_files: files("adopted_files")
411            .iter()
412            .filter_map(|entry| {
413                Some((
414                    destination(entry)?,
415                    digest(entry, "sha256")?,
416                    digest(entry, "baseline_sha256")?,
417                ))
418            })
419            .collect(),
420    })
421}
422
423/// Walk the corpus, reading only what a detector can prove.
424fn read_corpus(target: &Utf8Path) -> Result<Corpus, AppError> {
425    let mut corpus = Corpus::default();
426    for root in DOC_ROOTS {
427        let path = target.join(root);
428        if path.is_dir() && std::fs::read_dir(&path)?.next().is_some() {
429            corpus.populated_doc_roots.push((*root).to_string());
430        }
431        if path.join("specs").is_dir() {
432            corpus.has_specs_directory = true;
433        }
434    }
435
436    for entry in walkdir::WalkDir::new(target)
437        .into_iter()
438        .filter_entry(|entry| {
439            entry.depth() == 0
440                || !entry.file_type().is_dir()
441                || !SKIPPED.contains(&entry.file_name().to_string_lossy().as_ref())
442        })
443    {
444        let entry = entry.map_err(|source| AppError::Io(std::io::Error::from(source)))?;
445        if !entry.file_type().is_file() {
446            continue;
447        }
448        let Ok(path) = Utf8PathBuf::from_path_buf(entry.path().to_path_buf()) else {
449            continue;
450        };
451        let Ok(relative) = path.strip_prefix(target) else {
452            continue;
453        };
454        let Ok(held) = TargetPath::new(relative.as_str()) else {
455            continue;
456        };
457        let name = relative.file_name().unwrap_or_default();
458        let extension = relative.extension().unwrap_or_default();
459        if !DOC_EXTENSIONS.contains(&extension) {
460            continue;
461        }
462        // Root metadata is what every repository carries, whether or not
463        // it documents itself.
464        let stem = relative.file_stem().unwrap_or_default().to_lowercase();
465        if relative
466            .parent()
467            .is_none_or(|parent| parent.as_str().is_empty())
468            && ROOT_METADATA.contains(&stem.as_str())
469        {
470            continue;
471        }
472        corpus.documents.push(held.clone());
473        if is_spec_shaped(name) {
474            corpus.spec_shaped.push(held.clone());
475            let text = std::fs::read_to_string(&path).unwrap_or_default();
476            if crate::embedded::rule_ids_in(&text).next().is_none() {
477                corpus.spec_without_rule_id.push(held.clone());
478            }
479        }
480        if is_ordinal_name(name) {
481            corpus.ordinal_named.push(held.clone());
482        }
483        if is_record_shaped(name)
484            && relative
485                .parent()
486                .is_none_or(|parent| parent.file_name() != Some("decisions"))
487        {
488            corpus.records_outside_decisions.push(held);
489        }
490    }
491    corpus.documents.sort();
492    corpus.spec_shaped.sort();
493    corpus.spec_without_rule_id.sort();
494    corpus.ordinal_named.sort();
495    corpus.records_outside_decisions.sort();
496    Ok(corpus)
497}
498
499/// What the recorded destinations hold, keyed by path.
500#[must_use]
501pub fn held_by_path(installation: Option<&Installation>) -> BTreeMap<String, Sha256> {
502    let mut held = BTreeMap::new();
503    let Some(installation) = installation else {
504        return held;
505    };
506    for file in installation.managed.iter().chain(&installation.adopted) {
507        if let Some(digest) = file.held.clone() {
508            held.insert(file.path.as_str().to_string(), digest);
509        }
510    }
511    held
512}
513
514#[cfg(test)]
515mod tests {
516    #![allow(
517        clippy::unwrap_used,
518        reason = "a test panics as its failure signal, not as control flow"
519    )]
520
521    use super::*;
522
523    fn scratch() -> (tempfile::TempDir, Utf8PathBuf) {
524        let dir = tempfile::tempdir().unwrap();
525        let root = Utf8PathBuf::from(dir.path().to_str().unwrap());
526        std::fs::create_dir(root.join(".git")).unwrap();
527        (dir, root)
528    }
529
530    #[test]
531    fn an_empty_target_reads_as_empty_and_unsettled() {
532        let (_dir, root) = scratch();
533        let held = observe(&root).unwrap();
534        assert!(held.repository.empty);
535        assert!(held.repository.version_controlled);
536        assert!(held.installation.is_none());
537        assert_eq!(held.invalid, None);
538        assert!(!held.corpus.settled());
539    }
540
541    #[test]
542    fn root_metadata_is_not_a_corpus() {
543        let (_dir, root) = scratch();
544        std::fs::write(root.join("README.md"), "# x\n").unwrap();
545        std::fs::write(root.join("CHANGELOG.md"), "# x\n").unwrap();
546        let held = observe(&root).unwrap();
547        assert!(!held.repository.empty);
548        assert!(!held.corpus.settled(), "{:?}", held.corpus.documents);
549    }
550
551    #[test]
552    fn a_populated_documentation_root_is_a_settled_corpus() {
553        let (_dir, root) = scratch();
554        crate::adapters::fs::write_file(&root.join("docs/guide.md"), b"# guide\n").unwrap();
555        let held = observe(&root).unwrap();
556        assert_eq!(held.corpus.populated_doc_roots, ["docs"]);
557        assert!(held.corpus.settled());
558        assert_eq!(held.corpus.documents.len(), 1);
559    }
560
561    #[test]
562    fn a_documentation_root_of_empty_directories_is_not_a_corpus() {
563        let (_dir, root) = scratch();
564        std::fs::create_dir_all(root.join("_docs/specs")).unwrap();
565        let held = observe(&root).unwrap();
566        assert_eq!(held.corpus.populated_doc_roots, ["_docs"]);
567        assert!(!held.corpus.settled(), "a layout is not a corpus");
568    }
569
570    #[test]
571    fn the_corpus_reads_only_what_a_detector_can_prove() {
572        let (_dir, root) = scratch();
573        crate::adapters::fs::write_file(&root.join("docs/specs/SPEC-x.md"), b"# x\n").unwrap();
574        crate::adapters::fs::write_file(&root.join("docs/specs/SPEC-y.md"), b"### `a-b:c-d` - t\n")
575            .unwrap();
576        crate::adapters::fs::write_file(&root.join("docs/01-intro.md"), b"# x\n").unwrap();
577        crate::adapters::fs::write_file(&root.join("docs/ADR-a-choice.md"), b"# x\n").unwrap();
578        crate::adapters::fs::write_file(&root.join("docs/decisions/ADR-b-choice.md"), b"# x\n")
579            .unwrap();
580        crate::adapters::fs::write_file(&root.join("docs/specs/notes.md"), b"# x\n").unwrap();
581
582        let corpus = observe(&root).unwrap().corpus;
583        assert!(corpus.has_specs_directory);
584        assert_eq!(corpus.spec_shaped.len(), 2);
585        assert_eq!(
586            corpus
587                .spec_without_rule_id
588                .iter()
589                .map(TargetPath::as_str)
590                .collect::<Vec<_>>(),
591            ["docs/specs/SPEC-x.md"]
592        );
593        assert_eq!(
594            corpus
595                .ordinal_named
596                .iter()
597                .map(TargetPath::as_str)
598                .collect::<Vec<_>>(),
599            ["docs/01-intro.md"]
600        );
601        assert_eq!(
602            corpus
603                .records_outside_decisions
604                .iter()
605                .map(TargetPath::as_str)
606                .collect::<Vec<_>>(),
607            ["docs/ADR-a-choice.md"]
608        );
609    }
610
611    #[test]
612    fn a_record_that_does_not_parse_is_invalid_and_never_absent() {
613        let (_dir, root) = scratch();
614        crate::adapters::fs::write_file(&root.join(MANIFEST_PATH), b"{not json").unwrap();
615        let held = observe(&root).unwrap();
616        assert!(held.installation.is_none());
617        assert!(held.invalid.is_some(), "a broken record read as absent");
618    }
619
620    #[test]
621    fn an_unreadable_target_is_a_command_error_and_not_a_plan() {
622        let (_dir, root) = scratch();
623        std::fs::write(root.join("a-file"), b"x").unwrap();
624        let error = observe(&root.join("a-file")).unwrap_err();
625        assert_eq!(error.exit_code(), 64);
626        assert!(observe(&root.join("absent")).is_err());
627    }
628}