1use 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
28const DOC_ROOTS: &[&str] = &["docs", "_docs", "doc", "documentation"];
30
31const ROOT_METADATA: &[&str] = &[
33 "readme",
34 "license",
35 "licence",
36 "contributing",
37 "changelog",
38 "agents",
39 "claude",
40 "code_of_conduct",
41];
42
43const SKIPPED: &[&str] = &[".git", ".jj", "target", "node_modules", INSTANCE_DIR];
45
46const DOC_EXTENSIONS: &[&str] = &["md", "markdown", "adoc", "rst", "org"];
48
49#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
51pub struct Repository {
52 pub root: Utf8PathBuf,
54 pub version_controlled: bool,
56 pub empty: bool,
58}
59
60#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
62pub struct RecordedFile {
63 pub path: TargetPath,
65 pub recorded: Sha256,
67 #[serde(default, skip_serializing_if = "Option::is_none")]
69 pub baseline: Option<Sha256>,
70 #[serde(default, skip_serializing_if = "Option::is_none")]
72 pub held: Option<Sha256>,
73}
74
75#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
77pub struct Installation {
78 pub canon_version: CanonVersion,
80 pub profile: ProfileId,
82 pub docs_root: DocsRoot,
84 pub record_sha256: Sha256,
86 #[serde(default, skip_serializing_if = "Option::is_none")]
88 pub declaration_sha256: Option<Sha256>,
89 pub managed: Vec<RecordedFile>,
91 pub adopted: Vec<RecordedFile>,
93 pub blocks: Vec<RecordedBlock>,
95}
96
97#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
99pub struct RecordedBlock {
100 pub path: TargetPath,
102 pub recorded: Sha256,
104 pub held: Option<Sha256>,
107}
108
109impl Installation {
110 #[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#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
129pub struct Host {
130 pub offline: bool,
132 #[serde(default, skip_serializing_if = "Option::is_none")]
134 pub cache_root: Option<Utf8PathBuf>,
135}
136
137#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
139pub struct Corpus {
140 pub populated_doc_roots: Vec<String>,
142 pub documents: Vec<TargetPath>,
144 pub spec_shaped: Vec<TargetPath>,
146 pub spec_without_rule_id: Vec<TargetPath>,
148 pub ordinal_named: Vec<TargetPath>,
150 pub records_outside_decisions: Vec<TargetPath>,
152 pub has_specs_directory: bool,
154}
155
156impl Corpus {
157 #[must_use]
164 pub const fn settled(&self) -> bool {
165 !self.documents.is_empty()
166 }
167}
168
169#[derive(Debug, Clone, PartialEq, Eq)]
171pub struct Observation {
172 pub repository: Repository,
174 pub installation: Option<Installation>,
176 pub invalid: Option<String>,
178 pub host: Host,
180 pub corpus: Corpus,
182}
183
184pub 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
228fn 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
240fn 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 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 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 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
356fn 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
366struct 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 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
423fn 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 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#[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}