From 71c47d9549ede1f4fa59a4dd5ae2cb624f4c9e8c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:06:14 +0000 Subject: [PATCH 1/8] feat(finishingbot,glambot): read the chora deed, not the retired .scm files Repo facts are clauses of the one _chora.deed at the root (D312, D313). finishingbot still validated legacy STATE/META/... .scm files, and its SCM-005 advised MOVING a root STATE.scm into .machine_readable/, which restores a retired layout; glambot asked for a .machine_readable/ directory and built the retired .scm layout in its fixtures. Neither read the deed. deed-reader/ (new, std-only, read-only): panicbot's grammar-faithful deed reader, extracted so bots read the deed one way, plus deed-field.sh's lookup conventions: find_chora (exactly one *_chora.deed), clause_at (slash path) and field (top-level key only); load_chora requires the repo-deed doc-head. One tightening against deed.abnf: a bare CR is an error (line-end = CRLF / LF). 7 tests. finishingbot (ScmFilesAnalyzer and the scm_files report key keep their names, so the API and JSON shape do not change): - DEED-001 (warning) no chora deed; DEED-002 (error) more than one; DEED-003 (error) unreadable/unparseable (with line)/not a repo-deed; DEED-004 (warning) no (status ...) clause and no descriptiles/STATE.deed. - SCM-006-.scm (warning): a legacy file at the root, .machine_readable/ or 6scm/ is "migrate": not validated, never "move". - SCM-002..005 retired (SCM-001 already was). glambot: MACH-006 (missing .machine_readable/) retired: a repo whose facts are all in its deed needs none. MACH-008 (warning) no chora deed; MACH-009 (error) several, unreadable, unparseable or wrong head. Fixtures now use a chora deed. Neither finding is auto-fixable: bots never write a deed. CI: deed-reader and finishingbot join the rust.yml matrix (finishingbot was never built or tested in CI). glambot stays out: about 60 clippy diagnostics under -D warnings predate this change; with --keep-going this branch has one fewer than main and adds none. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDhFeexmokLqLRfZNce --- .github/workflows/rust.yml | 9 + bots/finishingbot/Cargo.lock | 5 + bots/finishingbot/Cargo.toml | 3 + bots/finishingbot/README.adoc | 6 +- bots/finishingbot/src/analyzers/scm_files.rs | 376 ++++++---- bots/finishingbot/tests/analyzer_tests.rs | 128 ++-- bots/glambot/Cargo.lock | 5 + bots/glambot/Cargo.toml | 3 + bots/glambot/README.adoc | 6 +- bots/glambot/src/analyzers/machine.rs | 154 ++-- bots/glambot/tests/integration.rs | 12 +- deed-reader/Cargo.lock | 7 + deed-reader/Cargo.toml | 18 + deed-reader/README.adoc | 33 + deed-reader/src/lib.rs | 700 +++++++++++++++++++ 15 files changed, 1169 insertions(+), 296 deletions(-) create mode 100644 deed-reader/Cargo.lock create mode 100644 deed-reader/Cargo.toml create mode 100644 deed-reader/README.adoc create mode 100644 deed-reader/src/lib.rs diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 296f8cb3..2b91f423 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -77,6 +77,15 @@ jobs: dir: bots/ponsbot - module: idris-dependents dir: idris-dependents + # deed-reader: the shared, std-only reader for _chora.deed. + - module: deed-reader + dir: deed-reader + # finishingbot reads the chora deed through deed-reader; it was + # never built, tested or linted in CI before (2026-11-17). glambot + # also uses deed-reader but stays out until its pre-existing clippy + # debt (about 60 diagnostics under -D warnings) is paid. + - module: finishingbot + dir: bots/finishingbot defaults: run: working-directory: ${{ matrix.dir }} diff --git a/bots/finishingbot/Cargo.lock b/bots/finishingbot/Cargo.lock index ad7d22e7..78efa80b 100644 --- a/bots/finishingbot/Cargo.lock +++ b/bots/finishingbot/Cargo.lock @@ -480,6 +480,7 @@ dependencies = [ "clap", "criterion", "git2", + "gitbot-deed-reader", "gitbot-shared-context", "glob", "globset", @@ -631,6 +632,10 @@ dependencies = [ "log", ] +[[package]] +name = "gitbot-deed-reader" +version = "0.1.0" + [[package]] name = "gitbot-shared-context" version = "0.1.0" diff --git a/bots/finishingbot/Cargo.toml b/bots/finishingbot/Cargo.toml index db160cb1..1c761248 100644 --- a/bots/finishingbot/Cargo.toml +++ b/bots/finishingbot/Cargo.toml @@ -11,6 +11,9 @@ keywords = ["release", "validation", "ci-cd", "compliance", "gitbot-fleet"] categories = ["development-tools", "command-line-utilities"] [dependencies] +# Repo deed reader (shared, std-only, in-repo) +gitbot-deed-reader = { path = "../../deed-reader" } + # Async runtime tokio = { version = "1.52.3", features = ["full"] } diff --git a/bots/finishingbot/README.adoc b/bots/finishingbot/README.adoc index 8d4e7849..97744c2f 100644 --- a/bots/finishingbot/README.adoc +++ b/bots/finishingbot/README.adoc @@ -48,8 +48,8 @@ the gitbot-fleet shared context layer and makes the final release-readiness dete |Version consistency across files, debug statement detection, sensitive data patterns, SECURITY.md, release profiles |No -|**SCM Files** -|Legacy `.machine_readable/` SCM files (STATE.scm, META.scm, ECOSYSTEM.scm, PLAYBOOK.scm, AGENTIC.scm, NEUROSYM.scm) are validated only if present (SPDX headers, required sections, content completeness); their absence is canonical, since those descriptiles are now clauses of `_chora.deed` +|**Repo Deed** (the `scm_files` report key) +|Reads the one `_chora.deed` at the root (through `deed-reader/`): none is DEED-001 (warning), more than one is DEED-002 (error, D312), unreadable or not a `repo-deed` is DEED-003 (error), no `(status …)` clause and no `descriptiles/STATE.deed` is DEED-004 (warning). A retired STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC or NEUROSYM `.scm` at the root, under `.machine_readable/` or `6scm/` is SCM-006 (warning, "migrate"): it is not validated and is never to be moved |No |**Testing** @@ -179,7 +179,7 @@ The analyzers accept the estate's canonical locations, not only one spelling: * `mise.toml` in place of `.tool-versions` (TOOL-001). * `tests/fuzz/` as well as `fuzz/` and `.clusterfuzzlite/` (TEST-RU-003); a crate with no code yet (no `.rs` line that is not blank or a comment) is exempt from TEST-RU-005 and TEST-RU-006. * A workflow named by file name in prose resolves under `.github/workflows/` (CLM-006). -* SCM-001 is retired: STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC and NEUROSYM are clauses of `_chora.deed`, not files. +* SCM-001 to SCM-005 are retired: STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC and NEUROSYM are clauses of `_chora.deed`, not files, so a legacy `.scm` is neither required nor validated, and SCM-005 no longer advises moving one into `.machine_readable/` (a retired layout). * REL-008 matches key material (PEM headers, AWS key ids, vendor token shapes, long key literals), not the words "private key". A repository can acknowledge a finding in its `.hypatia-baseline.json`, the estate's documented exemption mechanism (`docs/upstream-proposals/standards--hypatia-baseline-consumer/docs/EXEMPTION-MECHANISMS.adoc`, "Layer 2"). `.hypatia-ignore` is not read: that document rejects it. An entry uses this bot's `rule_module`, `finishing_bot`, and the finding id as `type`, with the estate severity word (error = `high`, warning = `medium`, info = `info`, suggestion = `low`) and exactly one of `file` or `file_pattern`: `{"severity": "medium", "rule_module": "finishing_bot", "type": "PH-001", "file_pattern": "build/just/**", "note": "scanner names the tokens"}`. Matching is exact on severity, module and type, so a rule family needs one entry per id. Entries past `expires_at`, or carrying `severity_override` (this bot does not downgrade), acknowledge nothing; other modules' entries (`cicd_rules`, ...) are Hypatia's and are not read. Currently only the placeholder analyzer (PH-nnn, hence PH-100) honours it. See `src/baseline.rs`. diff --git a/bots/finishingbot/src/analyzers/scm_files.rs b/bots/finishingbot/src/analyzers/scm_files.rs index 692c4b2d..b09f049c 100644 --- a/bots/finishingbot/src/analyzers/scm_files.rs +++ b/bots/finishingbot/src/analyzers/scm_files.rs @@ -1,14 +1,56 @@ // SPDX-License-Identifier: MPL-2.0 // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell -//! SCM documentation files analyzer +//! Repo-deed analyzer (formerly the SCM documentation files analyzer). +//! +//! The six descriptive documents that used to be `STATE.scm`, `META.scm`, +//! `ECOSYSTEM.scm`, `PLAYBOOK.scm`, `AGENTIC.scm` and `NEUROSYM.scm` are +//! clauses of the repository's one `_chora.deed` (owner rulings D312, +//! D313), and the project state is its `(status …)` clause, or +//! `.machine_readable/descriptiles/STATE.deed` once standards' A7 migration +//! moves it there (J15). This analyzer therefore reads the deed, through +//! `gitbot-deed-reader`, and treats any surviving `.scm` document as legacy: +//! it says "migrate", never "move" or "complete" (the earlier +//! direct-under-`.machine_readable/` layout is retired and must not be +//! restored). +//! +//! The type and the report key keep their old names (`ScmFilesAnalyzer`, +//! `scm_files`) so the library API and the JSON report shape do not change. +//! +//! Finding ids: +//! - `DEED-001` (warning): no `_chora.deed` at the root. +//! - `DEED-002` (error): more than one chora deed (D312 allows exactly one). +//! - `DEED-003` (error): the chora deed cannot be read or parsed, or its +//! doc-head is not `repo-deed`. +//! - `DEED-004` (warning): no project state: neither a `(status …)` clause in +//! the chora deed nor a `descriptiles/STATE.deed`. +//! - `SCM-006-.scm` (warning): a retired `.scm` document is present. +//! +//! Retired: `SCM-001` (missing `.scm`), `SCM-002`/`003`/`004` (validating a +//! retired file's content) and `SCM-005` (which advised MOVING a root `.scm` +//! into `.machine_readable/`, i.e. restoring a retired layout). use super::{AnalysisResult, Analyzer, Finding, Severity}; use crate::config::Config; use crate::error::Result; +use deed_reader::{load_chora, ChoraError}; use std::path::Path; use tracing::debug; -/// SCM documentation files analyzer +/// The retired descriptive documents and the deed clause each one became. +const LEGACY_SCM: [(&str, &str); 6] = [ + ("STATE.scm", "status"), + ("META.scm", "meta"), + ("ECOSYSTEM.scm", "ecosystem"), + ("PLAYBOOK.scm", "playbook"), + ("AGENTIC.scm", "agentic"), + ("NEUROSYM.scm", "neurosym"), +]; + +/// Where a legacy `.scm` document may still be found: the root, the retired +/// direct-under-`.machine_readable/` layout and the retired `6scm/` layout. +const LEGACY_DIRS: [&str; 3] = ["", ".machine_readable", ".machine_readable/6scm"]; + +/// Repo-deed analyzer (historical name kept for API stability). pub struct ScmFilesAnalyzer; impl Default for ScmFilesAnalyzer { @@ -19,176 +61,140 @@ impl Default for ScmFilesAnalyzer { impl Analyzer for ScmFilesAnalyzer { fn name(&self) -> &str { - "SCM Documentation Files" + "Repo Deed (chora)" } fn analyze(&self, path: &Path, _config: &Config) -> Result { let mut result = AnalysisResult::new(); let start = std::time::Instant::now(); - // Required SCM files for v1.0 - let required_scm_files = [ - ("STATE.scm", "Project state and progress tracking"), - ( - "META.scm", - "Meta-level information and architectural decisions", - ), - ("ECOSYSTEM.scm", "Project's place in the ecosystem"), - ("PLAYBOOK.scm", "Operational playbooks and procedures"), - ("AGENTIC.scm", "Agentic AI integration documentation"), - ("NEUROSYM.scm", "Neurosymbolic AI documentation"), - ]; - - let machine_readable_dir = path.join(".machine_readable"); - - for (filename, _description) in &required_scm_files { - let correct_path = machine_readable_dir.join(filename); - let root_path = path.join(filename); - - if correct_path.exists() { - debug!("Found {} in .machine_readable/", filename); - result.files_checked += 1; + let has_state_deed = path + .join(".machine_readable/descriptiles/STATE.deed") + .is_file(); - // Validate SCM file content - if let Ok(content) = std::fs::read_to_string(&correct_path) { - self.validate_scm_content(filename, &content, &correct_path, &mut result); - } - } else if root_path.exists() { - // File is in root instead of .machine_readable/ + match load_chora(path) { + Ok(Some(chora)) => { result.files_checked += 1; - result.add( - Finding::new( - &format!("SCM-005-{}", filename), - &format!("{} in wrong location", filename), - Severity::Warning, - &format!( - "{} found in repository root but should be in .machine_readable/", - filename + debug!("read {}", chora.path.display()); + if !chora.root.has("status") && !has_state_deed { + result.add( + Finding::new( + "DEED-004", + "Project state not recorded", + Severity::Warning, + "The chora deed has no (status …) clause and there is no \ + .machine_readable/descriptiles/STATE.deed, so the project's \ + phase is not recorded anywhere a bot can read.", + ) + .with_file(chora.path.clone()) + .with_suggestion( + "Add a (status …) clause to the chora deed (standards \ + 1-formats/deed/mappings/clade-to-repo-deed.adoc §3), and check it \ + with `bun 1-formats/deed/tools/deed_lint.js`", ), - ) - .with_file(root_path) - .with_suggestion(&format!( - "Move {} to .machine_readable/{}", - filename, filename - )), - ); - } else { - // SCM-001 (a required .scm file is missing) is retired. The six - // descriptive documents (STATE, META, ECOSYSTEM, PLAYBOOK, - // AGENTIC, NEUROSYM) are clauses of the repository's - // `_chora.deed`, not files, so absence is the canonical - // state. Files that DO exist are still validated above. - debug!( - "{} not present (retired: now a clause of the chora deed)", - filename - ); + ); + } } - } - - result.duration_ms = start.elapsed().as_millis() as u64; - Ok(result) - } - - fn fix(&self, _path: &Path, _config: &Config, _findings: &[Finding]) -> Result> { - // SCM files should be manually created with proper content - Ok(vec![ - "SCM files must be manually created with appropriate content.".to_string(), - "Use templates from existing hyperpolymath repos.".to_string(), - ]) - } -} - -impl ScmFilesAnalyzer { - /// Validate SCM file content - fn validate_scm_content( - &self, - filename: &str, - content: &str, - file_path: &Path, - result: &mut AnalysisResult, - ) { - // Check for SPDX header - if !content.starts_with(";; SPDX-License-Identifier:") { - result.add( - Finding::new( - &format!("SCM-002-{}", filename), - &format!("{} missing SPDX header", filename), - Severity::Warning, - &format!("{} should start with SPDX license identifier.", filename), - ) - .with_file(file_path.to_path_buf()) - .with_suggestion("Add ;; SPDX-License-Identifier: MPL-2.0 at the top"), - ); - } - - // Check minimum content length (should have substantial content) - if content.len() < 200 { - result.add( - Finding::new( - &format!("SCM-003-{}", filename), - &format!("{} appears incomplete", filename), - Severity::Warning, - &format!( - "{} is very short ({} bytes). May be a placeholder.", - filename, - content.len() - ), - ) - .with_file(file_path.to_path_buf()) - .with_suggestion("Ensure file has complete documentation content"), - ); - } - - // Check for specific required sections based on file type - match filename { - "STATE.scm" - if !content.contains("metadata") || !content.contains("current-position") => - { + Ok(None) => { result.add( Finding::new( - "SCM-004-STATE", - "STATE.scm missing required sections", + "DEED-001", + "No chora deed", Severity::Warning, - "STATE.scm should contain 'metadata' and 'current-position' sections.", + "No _chora.deed at the repository root. Repo facts (state, meta, \ + ecosystem, agentic, neurosym, playbook) are clauses of that one deed \ + (D312).", ) - .with_file(file_path.to_path_buf()) + .with_file(path.to_path_buf()) .with_suggestion( - "Add required sections following hyperpolymath STATE.scm format", + "Mint the deed from rsr-template-repo's model \ + (rsr-template-repo_chora.deed); bots read deeds but never write them", ), ); } - "META.scm" - if !content.contains("architecture-decisions") - || !content.contains("development-practices") => - { + Err(ChoraError::Multiple(paths)) => { + let names: Vec = paths + .iter() + .filter_map(|p| p.file_name().map(|n| n.to_string_lossy().into_owned())) + .collect(); result.add( Finding::new( - "SCM-004-META", - "META.scm missing required sections", - Severity::Warning, - "META.scm should contain 'architecture-decisions' and 'development-practices'.", + "DEED-002", + "More than one chora deed", + Severity::Error, + &format!( + "D312 allows exactly one chora deed per repository; found {}.", + names.join(", ") + ), ) - .with_file(file_path.to_path_buf()) - .with_suggestion("Add ADRs and development practices following hyperpolymath META.scm spec"), + .with_file(path.to_path_buf()) + .with_suggestion("Keep the deed whose stem is the repository's name"), + ); + } + Err(e) => { + let (file, line) = match &e { + ChoraError::Parse(p, de) => (p.clone(), Some(de.line)), + ChoraError::Io(p, _) | ChoraError::WrongHead(p, _) => (p.clone(), None), + ChoraError::Multiple(_) => unreachable!("handled above"), + }; + let mut f = Finding::new( + "DEED-003", + "Chora deed cannot be read", + Severity::Error, + &e.to_string(), + ) + .with_file(file) + .with_suggestion( + "Check it with standards' `bun 1-formats/deed/tools/deed_lint.js FILE`", ); + if let Some(l) = line { + f = f.with_line(l); + } + result.add(f); } - "ECOSYSTEM.scm" - if !content.contains("position-in-ecosystem") - || !content.contains("related-projects") => - { + } + + for dir in LEGACY_DIRS { + for (name, clause) in LEGACY_SCM { + let file = if dir.is_empty() { + path.join(name) + } else { + path.join(dir).join(name) + }; + if !file.is_file() { + continue; + } + result.files_checked += 1; result.add( Finding::new( - "SCM-004-ECOSYSTEM", - "ECOSYSTEM.scm missing required sections", + &format!("SCM-006-{name}"), + &format!("Legacy {name} should be migrated"), Severity::Warning, - "ECOSYSTEM.scm should contain 'position-in-ecosystem' and 'related-projects'.", + &format!( + "{name} is retired: its facts belong in the ({clause} …) clause of \ + the chora deed. It is not validated, and it must not be moved or \ + extended." + ), ) - .with_file(file_path.to_path_buf()) - .with_suggestion("Define ecosystem position and relationships"), + .with_file(file) + .with_suggestion(&format!( + "Migrate it into ({clause} …) under the standards mapping specs \ + (1-formats/deed/mappings/), then delete it" + )), ); } - _ => {} } + + result.duration_ms = start.elapsed().as_millis() as u64; + Ok(result) + } + + fn fix(&self, _path: &Path, _config: &Config, _findings: &[Finding]) -> Result> { + // Bots read deeds; they never write one or hand-convert a legacy file. + Ok(vec![ + "The chora deed is owner-authored: finishingbot does not write or convert it." + .to_string(), + ]) } } @@ -197,6 +203,8 @@ mod tests { use super::*; use tempfile::TempDir; + const DEED: &str = ";; SPDX-License-Identifier: MPL-2.0\n(repo-deed\n :schema-version \"1.0.0\"\n :canonical-name \"x\"\n (status :phase beta))\n"; + fn ids(dir: &Path) -> Vec { ScmFilesAnalyzer .analyze(dir, &Config::default()) @@ -208,24 +216,82 @@ mod tests { } #[test] - fn absent_scm_files_are_not_a_finding() { - // The six descriptive documents are clauses of _chora.deed now. + fn a_deed_with_status_and_no_scm_is_clean() { let d = TempDir::new().unwrap(); - std::fs::write(d.path().join("x_chora.deed"), "(deed)").unwrap(); - let got = ids(d.path()); - assert!( - got.iter().all(|i| !i.starts_with("SCM-001")), - "SCM-001 is retired, got {:?}", - got - ); - assert!(got.is_empty(), "got {:?}", got); + std::fs::write(d.path().join("x_chora.deed"), DEED).unwrap(); + assert!(ids(d.path()).is_empty(), "{:?}", ids(d.path())); } #[test] - fn a_misplaced_scm_file_is_still_reported() { - // Negative control: the analyzer still runs for files that exist. + fn no_deed_is_deed_001_and_absent_scm_is_not_a_finding() { let d = TempDir::new().unwrap(); + assert_eq!(ids(d.path()), vec!["DEED-001".to_string()]); + } + + #[test] + fn two_deeds_is_deed_002() { + let d = TempDir::new().unwrap(); + std::fs::write(d.path().join("x_chora.deed"), DEED).unwrap(); + std::fs::write(d.path().join("y_chora.deed"), DEED).unwrap(); + assert_eq!(ids(d.path()), vec!["DEED-002".to_string()]); + } + + #[test] + fn an_unparseable_or_wrong_head_deed_is_deed_003_with_a_line() { + let d = TempDir::new().unwrap(); + std::fs::write(d.path().join("x_chora.deed"), "(repo-deed\n\n :a").unwrap(); + let r = ScmFilesAnalyzer + .analyze(d.path(), &Config::default()) + .unwrap(); + let f = r.findings.iter().find(|f| f.id == "DEED-003").unwrap(); + assert_eq!(f.severity, Severity::Error); + assert_eq!(f.line, Some(3)); + + let d = TempDir::new().unwrap(); + std::fs::write(d.path().join("x_chora.deed"), "(praxis-deed :a \"b\")").unwrap(); + assert_eq!(ids(d.path()), vec!["DEED-003".to_string()]); + } + + #[test] + fn missing_status_is_deed_004_unless_state_deed_exists() { + let d = TempDir::new().unwrap(); + std::fs::write( + d.path().join("x_chora.deed"), + "(repo-deed :canonical-name \"x\")", + ) + .unwrap(); + assert_eq!(ids(d.path()), vec!["DEED-004".to_string()]); + let dd = d.path().join(".machine_readable/descriptiles"); + std::fs::create_dir_all(&dd).unwrap(); + std::fs::write(dd.join("STATE.deed"), "(descriptile-deed)").unwrap(); + assert!(ids(d.path()).is_empty()); + } + + #[test] + fn legacy_scm_is_reported_as_migrate_wherever_it_is_and_never_validated() { + let d = TempDir::new().unwrap(); + std::fs::write(d.path().join("x_chora.deed"), DEED).unwrap(); std::fs::write(d.path().join("STATE.scm"), ";; x\n").unwrap(); - assert!(ids(d.path()).contains(&"SCM-005-STATE.scm".to_string())); + std::fs::create_dir_all(d.path().join(".machine_readable/6scm")).unwrap(); + std::fs::write(d.path().join(".machine_readable/META.scm"), "(meta)").unwrap(); + std::fs::write(d.path().join(".machine_readable/6scm/ECOSYSTEM.scm"), "(e)").unwrap(); + let mut got = ids(d.path()); + got.sort(); + assert_eq!( + got, + vec![ + "SCM-006-ECOSYSTEM.scm".to_string(), + "SCM-006-META.scm".to_string(), + "SCM-006-STATE.scm".to_string() + ] + ); + let r = ScmFilesAnalyzer + .analyze(d.path(), &Config::default()) + .unwrap(); + for f in &r.findings { + assert_eq!(f.severity, Severity::Warning); + let s = f.suggestion.as_deref().unwrap_or(""); + assert!(s.contains("Migrate") && !s.contains("Move"), "{s}"); + } } } diff --git a/bots/finishingbot/tests/analyzer_tests.rs b/bots/finishingbot/tests/analyzer_tests.rs index 85a20070..fc4152fe 100644 --- a/bots/finishingbot/tests/analyzer_tests.rs +++ b/bots/finishingbot/tests/analyzer_tests.rs @@ -644,103 +644,95 @@ mod scm_files_analyzer { } #[test] - fn test_state_scm_in_root_warns_wrong_location() { + fn test_state_scm_in_root_is_migrate_not_move() { + // SCM-005 used to advise MOVING a root STATE.scm into .machine_readable/, + // which restores a retired layout. A legacy file is now "migrate". let (_temp, path) = setup_test_repo(); fs::write( path.join("STATE.scm"), - ";; SPDX-License-Identifier: MPL-2.0\n\ - (define state\n '((metadata (version . \"0.1.0\"))\n\ - (current-position (phase . \"mvp\"))))\n\ - ;; padding content to meet minimum size requirement\n\ - ;; more content here to make the file substantial enough\n\ - ;; and even more lines of content for the validator\n", + ";; SPDX-License-Identifier: MPL-2.0\n(state)\n", ) .unwrap(); - let analyzer = ScmFilesAnalyzer; - let config = default_config(); - let result = analyzer.analyze(&path, &config).unwrap(); + let result = ScmFilesAnalyzer.analyze(&path, &default_config()).unwrap(); - assert!( - result.findings.iter().any(|f| f.id == "SCM-005-STATE.scm"), - "Should warn about STATE.scm in root instead of .machine_readable/" - ); - assert!( - result - .findings - .iter() - .any(|f| f.id == "SCM-005-STATE.scm" && f.severity == Severity::Warning), - "Wrong location should be Warning severity" - ); + assert!(result.findings.iter().all(|f| !f.id.starts_with("SCM-005"))); + let f = result + .findings + .iter() + .find(|f| f.id == "SCM-006-STATE.scm") + .expect("a legacy STATE.scm is reported"); + assert_eq!(f.severity, Severity::Warning); + let s = f.suggestion.as_deref().unwrap_or(""); + assert!(s.contains("(status") && !s.contains("Move"), "{s}"); } #[test] - fn test_all_scm_files_present_in_machine_readable() { + fn test_full_legacy_scm_set_is_six_migrate_findings_and_never_validated() { let (_temp, path) = setup_test_repo(); let mr_dir = path.join(".machine_readable"); fs::create_dir_all(&mr_dir).unwrap(); - - let scm_files = [ - ("STATE.scm", ";; SPDX-License-Identifier: MPL-2.0\n(define state '((metadata (version . \"0.1.0\"))(current-position (phase . \"mvp\"))))\n;; padding\n;; more padding to meet minimum content\n;; and more\n;; and more\n;; and more\n;; and more\n"), - ("META.scm", ";; SPDX-License-Identifier: MPL-2.0\n(define meta '((architecture-decisions ())(development-practices ())))\n;; padding\n;; more padding\n;; and more\n;; and more\n;; and more\n"), - ("ECOSYSTEM.scm", ";; SPDX-License-Identifier: MPL-2.0\n(define ecosystem '((position-in-ecosystem \"tools\")(related-projects ())))\n;; padding\n;; more padding\n;; and more\n;; and more\n"), - ("PLAYBOOK.scm", ";; SPDX-License-Identifier: MPL-2.0\n(define playbook '((operations ())))\n;; padding\n;; more padding\n;; and more\n;; and more content to fill\n;; even more filler for length\n"), - ("AGENTIC.scm", ";; SPDX-License-Identifier: MPL-2.0\n(define agentic '((ai-integration ())))\n;; padding\n;; more padding\n;; and more\n;; and more content to fill\n;; even more filler for length\n"), - ("NEUROSYM.scm", ";; SPDX-License-Identifier: MPL-2.0\n(define neurosym '((neurosymbolic ())))\n;; padding\n;; more padding\n;; and more\n;; and more content to fill\n;; even more filler for length\n"), - ]; - - for (name, content) in &scm_files { - fs::write(mr_dir.join(name), content).unwrap(); + for name in [ + "STATE.scm", + "META.scm", + "ECOSYSTEM.scm", + "PLAYBOOK.scm", + "AGENTIC.scm", + "NEUROSYM.scm", + ] { + // No SPDX header and tiny: the retired SCM-002/003/004 checks + // would have fired; a legacy file is no longer validated. + fs::write(mr_dir.join(name), "(x)").unwrap(); } - let analyzer = ScmFilesAnalyzer; - let config = default_config(); - let result = analyzer.analyze(&path, &config).unwrap(); + let result = ScmFilesAnalyzer.analyze(&path, &default_config()).unwrap(); + let ids: Vec<&str> = result.findings.iter().map(|f| f.id.as_str()).collect(); - let missing_errors: Vec<_> = result - .findings - .iter() - .filter(|f| f.id.starts_with("SCM-001")) - .collect(); - assert!( - missing_errors.is_empty(), - "Should not report missing SCM files when all are present in .machine_readable/" - ); - let wrong_location: Vec<_> = result - .findings - .iter() - .filter(|f| f.id.starts_with("SCM-005")) - .collect(); - assert!( - wrong_location.is_empty(), - "Should not report wrong location for files in .machine_readable/" + assert_eq!( + ids.iter().filter(|i| i.starts_with("SCM-006-")).count(), + 6, + "{ids:?}" ); + for retired in ["SCM-001", "SCM-002", "SCM-003", "SCM-004", "SCM-005"] { + assert!( + ids.iter().all(|i| !i.starts_with(retired)), + "{retired}: {ids:?}" + ); + } } #[test] - fn test_scm_file_missing_spdx_header() { + fn test_chora_deed_with_status_satisfies_the_analyzer() { let (_temp, path) = setup_test_repo(); - let mr_dir = path.join(".machine_readable"); - fs::create_dir_all(&mr_dir).unwrap(); - // STATE.scm without SPDX header fs::write( - mr_dir.join("STATE.scm"), - "(define state '((metadata (version . \"0.1.0\"))(current-position (phase . \"mvp\"))))\n\ - ;; padding to meet length requirements for the validator\n\ - ;; more padding content here for the minimum length check\n\ - ;; and even more padding to ensure we pass the length check\n", + path.join("test_chora.deed"), + ";; SPDX-License-Identifier: MPL-2.0\n\ + (repo-deed\n :schema-version \"1.0.0\"\n :canonical-name \"test\"\n\ + \x20 (status :phase beta))\n", ) .unwrap(); - let analyzer = ScmFilesAnalyzer; - let config = default_config(); - let result = analyzer.analyze(&path, &config).unwrap(); + let result = ScmFilesAnalyzer.analyze(&path, &default_config()).unwrap(); assert!( - result.findings.iter().any(|f| f.id == "SCM-002-STATE.scm"), - "Should warn about missing SPDX header in STATE.scm" + result.findings.is_empty(), + "{:?}", + result.findings.iter().map(|f| &f.id).collect::>() ); } + + #[test] + fn test_unparseable_chora_deed_is_an_error() { + let (_temp, path) = setup_test_repo(); + fs::write(path.join("test_chora.deed"), "(repo-deed\n\t:a b)\n").unwrap(); + + let result = ScmFilesAnalyzer.analyze(&path, &default_config()).unwrap(); + + assert!(result + .findings + .iter() + .any(|f| f.id == "DEED-003" && f.severity == Severity::Error)); + } } // ============================================================================ diff --git a/bots/glambot/Cargo.lock b/bots/glambot/Cargo.lock index cd3a0810..a124e333 100644 --- a/bots/glambot/Cargo.lock +++ b/bots/glambot/Cargo.lock @@ -1033,6 +1033,10 @@ dependencies = [ "log", ] +[[package]] +name = "gitbot-deed-reader" +version = "0.1.0" + [[package]] name = "gitbot-shared-context" version = "0.1.0" @@ -1061,6 +1065,7 @@ dependencies = [ "comrak", "criterion", "dirs", + "gitbot-deed-reader", "gitbot-shared-context", "glob", "globset", diff --git a/bots/glambot/Cargo.toml b/bots/glambot/Cargo.toml index 90eb88d5..1f3ff45c 100644 --- a/bots/glambot/Cargo.toml +++ b/bots/glambot/Cargo.toml @@ -11,6 +11,9 @@ keywords = ["presentation", "accessibility", "seo", "wcag", "gitbot-fleet"] categories = ["development-tools", "command-line-utilities"] [dependencies] +# Repo deed reader (shared, std-only, in-repo) +gitbot-deed-reader = { path = "../../deed-reader" } + # Async runtime tokio = { version = "1.52.3", features = ["full"] } diff --git a/bots/glambot/README.adoc b/bots/glambot/README.adoc index bf289555..d0e36349 100644 --- a/bots/glambot/README.adoc +++ b/bots/glambot/README.adoc @@ -90,7 +90,7 @@ Evaluates repository discoverability through README descriptions, HTML meta tags === Machine-Readability (`MachineAnalyzer`) -Validates JSON/YAML file syntax, structured data presence, robots.txt, and the `.machine_readable/` directory. Legacy SCM files there are validated only if present; their absence is canonical (the descriptiles are clauses of `_chora.deed`). +Validates JSON/YAML file syntax, structured data presence, robots.txt, and the repo deed: the one `_chora.deed` at the root (D312), read through the shared `deed-reader/` crate. The repo's machine-readable facts are that deed's clauses, so a `.machine_readable/` directory is not required and legacy `.scm` files are not read. [cols="1,2,1"] |=== @@ -101,8 +101,10 @@ Validates JSON/YAML file syntax, structured data presence, robots.txt, and the ` | MACH-003 | Missing structured data (HTML) | Warning | MACH-004 | Invalid JSON-LD | Error | MACH-005 | Missing robots.txt | Info -| MACH-006 | Missing .machine_readable/ directory | Warning +| MACH-006 | _Retired_: a missing `.machine_readable/` directory is not reported; a repo whose facts are all in its chora deed needs none | n/a | MACH-007 | _Retired_: the STATE/META/ECOSYSTEM `.scm` files are clauses of the repository's `_chora.deed`, so their absence is not reported | n/a +| MACH-008 | Missing `_chora.deed` | Warning +| MACH-009 | Chora deed cannot be read: more than one (D312), unreadable, unparseable (with its line), or not a `repo-deed` | Error |=== **Auto-fixes:** Adds schema.org JSON-LD template (MACH-003), creates robots.txt (MACH-005). diff --git a/bots/glambot/src/analyzers/machine.rs b/bots/glambot/src/analyzers/machine.rs index ed51a38d..463fd4f7 100644 --- a/bots/glambot/src/analyzers/machine.rs +++ b/bots/glambot/src/analyzers/machine.rs @@ -45,8 +45,8 @@ impl Analyzer for MachineAnalyzer { // Check for robots.txt self.check_robots_txt(path, &mut result); - // Check for .machine_readable/ directory - self.check_machine_readable_dir(path, &mut result); + // Check the repo deed (_chora.deed): where repo facts live + self.check_chora_deed(path, &mut result); result.duration_ms = start.elapsed().as_millis() as u64; Ok(result) @@ -263,31 +263,53 @@ impl MachineAnalyzer { } } - fn check_machine_readable_dir(&self, path: &Path, result: &mut AnalysisResult) { - let mr_dir = path.join(".machine_readable"); - - if !mr_dir.exists() { - result.add( + /// The repo's machine-readable facts live in its one `_chora.deed` + /// at the root (D312), read through `gitbot-deed-reader`. + /// + /// - MACH-008 (warning): no chora deed. + /// - MACH-009 (error): more than one, unreadable, unparseable, or not a + /// `repo-deed`. + /// + /// Retired: MACH-006 (missing `.machine_readable/` directory; a repo whose + /// facts are all in its chora deed needs none) and MACH-007 (missing + /// STATE/META/ECOSYSTEM `.scm`; those are deed clauses now). Neither is + /// auto-fixable: the deed is owner-authored and bots never write one. + fn check_chora_deed(&self, path: &Path, result: &mut AnalysisResult) { + match deed_reader::load_chora(path) { + Ok(Some(chora)) => { + result.files_checked += 1; + debug!("read {}", chora.path.display()); + } + Ok(None) => result.add( Finding::new( - "MACH-006", - "Missing .machine_readable/ directory", + "MACH-008", + "Missing chora deed", Severity::Warning, - "No .machine_readable/ directory found (contractiles and other machine-readable estate metadata live here).", + "No _chora.deed at the repository root: the repo's machine-readable \ + facts (identity, state, meta, ecosystem, agentic, playbook) are its clauses (D312).", ) - .with_file(mr_dir.clone()) - // Not auto-fixable: git cannot track an empty directory, and a - // placeholder file would be invented content. What belongs here - // (contractiles, the chora deed) is owner-authored. - .with_suggestion("Create the .machine_readable/ directory"), - ); - return; + .with_file(path.to_path_buf()) + .with_suggestion( + "Mint the deed from rsr-template-repo's model (rsr-template-repo_chora.deed)", + ), + ), + Err(e) => { + let mut f = Finding::new( + "MACH-009", + "Chora deed cannot be read", + Severity::Error, + &e.to_string(), + ) + .with_file(path.to_path_buf()) + .with_suggestion( + "Check it with standards' `bun 1-formats/deed/tools/deed_lint.js FILE`", + ); + if let deed_reader::ChoraError::Parse(p, de) = &e { + f = f.with_file(p.clone()).with_line(de.line); + } + result.add(f); + } } - - result.files_checked += 1; - - // MACH-007 (missing STATE/META/ECOSYSTEM .scm) is retired: those - // documents are clauses of the repository's `_chora.deed` now, - // not files under .machine_readable/, so their absence is canonical. } } @@ -415,12 +437,12 @@ mod tests { "name: test\nversion: 1.0.0\n", ) .unwrap(); - // Create .machine_readable/ with SCM files - let mr_dir = dir.path().join(".machine_readable"); - std::fs::create_dir_all(&mr_dir).unwrap(); - std::fs::write(mr_dir.join("STATE.scm"), "(state)").unwrap(); - std::fs::write(mr_dir.join("META.scm"), "(meta)").unwrap(); - std::fs::write(mr_dir.join("ECOSYSTEM.scm"), "(ecosystem)").unwrap(); + // The repo's machine-readable facts: its chora deed at the root. + std::fs::write( + dir.path().join("test_chora.deed"), + "(repo-deed :canonical-name \"test\" (status :phase beta))\n", + ) + .unwrap(); // Create robots.txt std::fs::write(dir.path().join("robots.txt"), "User-agent: *\nAllow: /\n").unwrap(); @@ -454,36 +476,31 @@ mod tests { } #[test] - fn test_missing_machine_readable_dir() { + fn test_missing_chora_deed() { let dir = TempDir::new().unwrap(); - // No .machine_readable/ directory - - let analyzer = MachineAnalyzer::default(); - let config = default_config(); - let result = analyzer.analyze(dir.path(), &config).unwrap(); - - let ids: Vec<&str> = result.findings.iter().map(|f| f.id.as_str()).collect(); - assert!( - ids.contains(&"MACH-006"), - "Should report MACH-006 for missing .machine_readable/" - ); + let ids = ids(dir.path()); + assert!(ids.contains(&"MACH-008".to_string()), "{ids:?}"); } #[test] - fn mach_006_is_not_auto_fixable_and_fix_creates_nothing() { + fn mach_008_is_not_auto_fixable_and_fix_creates_nothing() { let dir = TempDir::new().unwrap(); let analyzer = MachineAnalyzer::default(); let config = default_config(); let result = analyzer.analyze(dir.path(), &config).unwrap(); - let f = result.findings.iter().find(|f| f.id == "MACH-006").unwrap(); - assert!(!f.fixable, "an empty dir is untracked by git; not fixable"); - let findings = vec![f.clone()]; - let fixes = analyzer.fix(dir.path(), &config, &findings).unwrap(); + let f = result.findings.iter().find(|f| f.id == "MACH-008").unwrap(); + assert!( + !f.fixable, + "the deed is owner-authored; bots never write one" + ); + let fixes = analyzer + .fix(dir.path(), &config, std::slice::from_ref(f)) + .unwrap(); assert_eq!( fixes, vec!["No machine-readability fixes applicable".to_string()] ); - assert!(!dir.path().join(".machine_readable").exists()); + assert!(deed_reader::find_chora(dir.path()).unwrap().is_none()); } fn ids(dir: &Path) -> Vec { @@ -497,26 +514,39 @@ mod tests { } #[test] - fn mach_007_is_retired() { + fn mach_006_and_007_are_retired_and_a_deed_needs_no_machine_readable_dir() { let dir = TempDir::new().unwrap(); - std::fs::create_dir_all(dir.path().join(".machine_readable")).unwrap(); + std::fs::write(dir.path().join("x_chora.deed"), "(repo-deed)").unwrap(); let got = ids(dir.path()); - assert!(!got.contains(&"MACH-007".to_string()), "{got:?}"); - assert!(!got.contains(&"MACH-006".to_string()), "{got:?}"); - // The directory itself is still expected. - let empty = TempDir::new().unwrap(); - assert!(ids(empty.path()).contains(&"MACH-006".to_string())); + for retired in ["MACH-006", "MACH-007", "MACH-008", "MACH-009"] { + assert!(!got.contains(&retired.to_string()), "{retired}: {got:?}"); + } + assert!(!dir.path().join(".machine_readable").exists()); + // A .machine_readable/ directory alone does not stand in for the deed. + let mr = TempDir::new().unwrap(); + std::fs::create_dir_all(mr.path().join(".machine_readable")).unwrap(); + assert!(ids(mr.path()).contains(&"MACH-008".to_string())); } #[test] - fn mach_006_is_not_auto_fixable() { - // The README documents the auto-fix list; MACH-006 must stay off it. - let dir = TempDir::new().unwrap(); - let a = MachineAnalyzer::default(); - let findings = a.analyze(dir.path(), &default_config()).unwrap().findings; - assert!(findings.iter().any(|f| f.id == "MACH-006")); - a.fix(dir.path(), &default_config(), &findings).unwrap(); - assert!(!dir.path().join(".machine_readable").exists()); + fn mach_009_for_two_deeds_a_parse_error_or_a_wrong_head() { + let two = TempDir::new().unwrap(); + std::fs::write(two.path().join("a_chora.deed"), "(repo-deed)").unwrap(); + std::fs::write(two.path().join("b_chora.deed"), "(repo-deed)").unwrap(); + assert!(ids(two.path()).contains(&"MACH-009".to_string())); + + let bad = TempDir::new().unwrap(); + std::fs::write(bad.path().join("x_chora.deed"), "(repo-deed\n :a").unwrap(); + let r = MachineAnalyzer::default() + .analyze(bad.path(), &default_config()) + .unwrap(); + let f = r.findings.iter().find(|f| f.id == "MACH-009").unwrap(); + assert_eq!(f.severity, Severity::Error); + assert_eq!(f.line, Some(2)); + + let head = TempDir::new().unwrap(); + std::fs::write(head.path().join("x_chora.deed"), "(praxis-deed)").unwrap(); + assert!(ids(head.path()).contains(&"MACH-009".to_string())); } const JSONC: &str = diff --git a/bots/glambot/tests/integration.rs b/bots/glambot/tests/integration.rs index 258b8ea8..b2693425 100644 --- a/bots/glambot/tests/integration.rs +++ b/bots/glambot/tests/integration.rs @@ -35,12 +35,12 @@ fn create_well_formed_repo() -> TempDir { // Valid YAML std::fs::write(path.join("config.yml"), "name: test\nversion: 1.0\n").unwrap(); - // .machine_readable/ with SCM files - let mr_dir = path.join(".machine_readable"); - std::fs::create_dir_all(&mr_dir).unwrap(); - std::fs::write(mr_dir.join("STATE.scm"), "(state (metadata))").unwrap(); - std::fs::write(mr_dir.join("META.scm"), "(meta)").unwrap(); - std::fs::write(mr_dir.join("ECOSYSTEM.scm"), "(ecosystem)").unwrap(); + // The repo deed (its machine-readable facts) + std::fs::write( + path.join("test_chora.deed"), + "(repo-deed :canonical-name \"test\" (status :phase beta))\n", + ) + .unwrap(); // robots.txt std::fs::write(path.join("robots.txt"), "User-agent: *\nAllow: /\n").unwrap(); diff --git a/deed-reader/Cargo.lock b/deed-reader/Cargo.lock new file mode 100644 index 00000000..459d6ec1 --- /dev/null +++ b/deed-reader/Cargo.lock @@ -0,0 +1,7 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "gitbot-deed-reader" +version = "0.1.0" diff --git a/deed-reader/Cargo.toml b/deed-reader/Cargo.toml new file mode 100644 index 00000000..fb74920d --- /dev/null +++ b/deed-reader/Cargo.toml @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: MPL-2.0 +[package] +name = "gitbot-deed-reader" +version = "0.1.0" +edition = "2021" +license = "MPL-2.0" +authors = ["Jonathan D.A. Jewell "] +description = "Read-only, std-only reader for the repo chora deed (_chora.deed), shared by gitbot-fleet bots" +repository = "https://github.com/hyperpolymath/gitbot-fleet" +publish = false + +[lib] +name = "deed_reader" +path = "src/lib.rs" + +[dependencies] + +[dev-dependencies] diff --git a/deed-reader/README.adoc b/deed-reader/README.adoc new file mode 100644 index 00000000..bcf78d7d --- /dev/null +++ b/deed-reader/README.adoc @@ -0,0 +1,33 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += deed-reader + +A small, strict, std-only, read-only reader for the repo deed +(`_chora.deed`), shared by the bots in this fleet. + +Repo facts that used to live in the retired `.scm` and `.a2ml` descriptiles +are clauses of the one chora deed at the repository root (owner rulings D312, +D313). Bots here only read deeds: they never write, extend or hand-convert +one. + +The grammar is `metadatastician/standards` `1-formats/deed/spec/abnf/deed.abnf`. +Lookup follows the estate's shell reader, `scripts/deed-field.sh` +(rsr-template-repo, kyX): + +[cols="1,2"] +|=== +| `deed-field.sh` | `deed_reader` + +| `--find DIR` | `find_chora(dir)`: exactly one `*_chora.deed` (none is `Ok(None)`, several is `ChoraError::Multiple`) +| `--has DEED PATH` | `Clause::has(path)` +| `DEED PATH KEY` | `Clause::clause_at(path)` then `Clause::field(key)`: KEY at the clause's top level only +|=== + +`load_chora(dir)` finds, reads and parses the deed and requires the doc-head +`repo-deed`. Every malformed input is an error with a line number. + +This is a reader, not the validator: `bun 1-formats/deed/tools/deed_lint.js` +in standards stays the conformance gate. + +Users: finishingbot (DEED-001 to DEED-004, SCM-006), glambot (MACH-008, +MACH-009). panicbot and rhodibot still carry their own readers; moving them +onto this crate is a follow-up. diff --git a/deed-reader/src/lib.rs b/deed-reader/src/lib.rs new file mode 100644 index 00000000..40455cf8 --- /dev/null +++ b/deed-reader/src/lib.rs @@ -0,0 +1,700 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell +//! A small, strict, read-only reader for the repo deed (`_chora.deed`). +//! +//! Repo facts that used to live in the retired STATE/META/ECOSYSTEM/... `.scm` +//! and `.a2ml` files are clauses of the one chora deed at the repository root +//! (owner rulings D312, D313). Bots here only READ deeds; they never write, +//! extend or hand-convert one. +//! +//! The grammar is `metadatastician/standards` `1-formats/deed/spec/abnf/deed.abnf`: +//! +//! - `(` is the only bracket; `;` starts a comment that runs to the line end; +//! - a clause is `(head item...)`, an item is a `:keyword value` field or a +//! nested clause, separated by spaces, line ends (LF or CRLF) or comments +//! (a tab, or a CR not followed by LF, is an error); +//! - values: `"strings"` (escapes `\"` `\\` `\n` `\t` only), bare symbols, +//! integers, `#t` / `#f`, the `#u5"..."` / `#u8"..."` / `#uuid"..."` +//! literals, `'quoted` symbols and lists, and `( lists )`; +//! - the whole input must be consumed. +//! +//! Lookup follows the conventions of the estate's shell reader +//! (`scripts/deed-field.sh` in the RSR template and kyX): [`find_chora`] is +//! `--find` (exactly one `*_chora.deed` in the directory), a clause PATH is +//! slash-separated below the root (`status`, `agentic/integrity`), and a KEY is +//! matched only at the top level of that clause, never inside a nested one. +//! +//! This is a reader, not the validator: `deed_lint.js` in standards stays the +//! conformance gate (header, `:schema-version`, line length, UUID shape, +//! filename dispatch). The reader's job is to never guess: every malformed +//! input is an `Err` with a line number, never a silent default. +//! +//! Extracted from panicbot's `src/deed.rs` (2026-11-13) so that finishingbot +//! and glambot read the deed the same way; panicbot and rhodibot keep their +//! own copies until they are moved onto this crate. + +use std::fmt; +use std::path::{Path, PathBuf}; + +/// One parenthesised clause. +#[derive(Debug, Clone, PartialEq)] +pub struct Clause { + /// The symbol after `(`. + pub head: String, + /// Fields and nested clauses, in order. + pub items: Vec, + /// 1-based line of the `(`. + pub line: usize, +} + +/// An item inside a clause. +#[derive(Debug, Clone, PartialEq)] +pub enum Item { + /// `:key value`. + Field { + key: String, + value: Value, + line: usize, + }, + /// A nested clause. + Clause(Clause), +} + +/// A field value. +#[derive(Debug, Clone, PartialEq)] +pub enum Value { + Str(String), + Sym(String), + Int(i64), + Bool(bool), + /// `#u5"..."`, `#u8"..."` or `#uuid"..."`: carried as its text, unused here. + Literal(String), + Quoted(Box), + List(Vec), +} + +impl Value { + fn describe(&self) -> &'static str { + match self { + Value::Str(_) => "a string", + Value::Sym(_) => "a symbol", + Value::Int(_) => "an integer", + Value::Bool(_) => "a boolean", + Value::Literal(_) => "a literal", + Value::Quoted(_) => "a quoted value", + Value::List(_) => "a list", + } + } +} + +/// A deed parse or shape error, with the 1-based line it was found on. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct DeedError { + pub line: usize, + pub message: String, +} + +impl fmt::Display for DeedError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "line {}: {}", self.line, self.message) + } +} + +impl std::error::Error for DeedError {} + +/// Shorthand for results in this module. +pub type Result = std::result::Result; + +impl Clause { + /// The nested clauses with this head. + pub fn clauses<'a>(&'a self, head: &'a str) -> impl Iterator + 'a { + self.items.iter().filter_map(move |i| match i { + Item::Clause(c) if c.head == head => Some(c), + _ => None, + }) + } + + /// The value of `:key` at the top level of this clause (never inside a + /// nested clause), as `deed-field.sh DEED PATH KEY` reads it. The first + /// occurrence wins. + pub fn field(&self, key: &str) -> Option<&Value> { + self.items.iter().find_map(|i| match i { + Item::Field { key: k, value, .. } if k == key => Some(value), + _ => None, + }) + } + + /// The clause at a slash-separated `path` below this one (`status`, + /// `agentic/integrity`), taking the first clause with each head. An empty + /// path is this clause itself, as in `deed-field.sh`. + pub fn clause_at(&self, path: &str) -> Option<&Clause> { + let mut at = self; + for head in path.split('/').filter(|s| !s.is_empty()) { + at = at.items.iter().find_map(|i| match i { + Item::Clause(c) if c.head == head => Some(c), + _ => None, + })?; + } + Some(at) + } + + /// Whether the clause at `path` exists (`deed-field.sh --has`). + pub fn has(&self, path: &str) -> bool { + self.clause_at(path).is_some() + } + + /// The heads of the top-level clauses, in order. + pub fn clause_heads(&self) -> Vec<&str> { + self.items + .iter() + .filter_map(|i| match i { + Item::Clause(c) => Some(c.head.as_str()), + _ => None, + }) + .collect() + } +} + +/// The suffix that names a repo deed (D312: one per repository, at its root). +pub const CHORA_SUFFIX: &str = "_chora.deed"; + +/// Why the chora deed of a directory could not be found or read. +#[derive(Debug)] +pub enum ChoraError { + /// More than one `*_chora.deed` at the root: D312 allows exactly one. + Multiple(Vec), + /// The file exists but could not be read. + Io(PathBuf, std::io::Error), + /// The file is not a deed this reader can parse. + Parse(PathBuf, DeedError), + /// It parses, but its doc-head is not `repo-deed` (deed.abnf filename + /// dispatch: `*_chora.deed` is a `repo-deed`). + WrongHead(PathBuf, String), +} + +impl fmt::Display for ChoraError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + ChoraError::Multiple(ps) => { + let names: Vec = ps.iter().map(|p| p.display().to_string()).collect(); + write!( + f, + "more than one chora deed (D312 allows exactly one): {}", + names.join(", ") + ) + } + ChoraError::Io(p, e) => write!(f, "{}: {e}", p.display()), + ChoraError::Parse(p, e) => write!(f, "{}: {e}", p.display()), + ChoraError::WrongHead(p, h) => write!( + f, + "{}: doc-head is '{h}', but a *_chora.deed must be a repo-deed", + p.display() + ), + } + } +} + +impl std::error::Error for ChoraError {} + +/// True when `name` is a chora deed file name: a non-empty stem of ASCII +/// letters, digits, `-`, `.` or `_` (deed.abnf `stem`), then `_chora.deed`. +pub fn is_chora_name(name: &str) -> bool { + match name.strip_suffix(CHORA_SUFFIX) { + Some(stem) => { + !stem.is_empty() + && stem + .chars() + .all(|c| c.is_ascii_alphanumeric() || "-._".contains(c)) + } + None => false, + } +} + +/// The one `*_chora.deed` directly in `dir` (`deed-field.sh --find`): +/// `Ok(None)` when there is none, `Err(Multiple)` when there are several. +/// Only regular files count; a directory or a dangling link with the name +/// does not. +pub fn find_chora(dir: &Path) -> std::result::Result, ChoraError> { + let entries = match std::fs::read_dir(dir) { + Ok(e) => e, + Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None), + Err(e) => return Err(ChoraError::Io(dir.to_path_buf(), e)), + }; + let mut found: Vec = entries + .filter_map(|e| e.ok()) + .filter(|e| e.file_name().to_str().is_some_and(is_chora_name)) + .map(|e| e.path()) + .filter(|p| p.is_file()) + .collect(); + found.sort(); + match found.len() { + 0 => Ok(None), + 1 => Ok(found.pop()), + _ => Err(ChoraError::Multiple(found)), + } +} + +/// A parsed chora deed and where it was read from. +#[derive(Debug, Clone)] +pub struct Chora { + pub path: PathBuf, + pub root: Clause, +} + +/// Find, read and parse the chora deed of the repository at `dir`. +/// `Ok(None)` when the repository has none. +pub fn load_chora(dir: &Path) -> std::result::Result, ChoraError> { + let Some(path) = find_chora(dir)? else { + return Ok(None); + }; + let text = std::fs::read_to_string(&path).map_err(|e| ChoraError::Io(path.clone(), e))?; + let root = parse(&text).map_err(|e| ChoraError::Parse(path.clone(), e))?; + if root.head != "repo-deed" { + let head = root.head.clone(); + return Err(ChoraError::WrongHead(path, head)); + } + Ok(Some(Chora { path, root })) +} + +impl Value { + /// The value as a bare symbol, or an error naming `what`. + pub fn as_symbol(&self, what: &str, line: usize) -> Result<&str> { + match self { + Value::Sym(s) => Ok(s), + other => Err(DeedError { + line, + message: format!("{what} must be a symbol, found {}", other.describe()), + }), + } + } + + /// The value as a string, or an error naming `what`. + pub fn as_string(&self, what: &str, line: usize) -> Result<&str> { + match self { + Value::Str(s) => Ok(s), + other => Err(DeedError { + line, + message: format!("{what} must be a string, found {}", other.describe()), + }), + } + } + + /// The value as a list of bare symbols, or an error naming `what`. + pub fn as_symbol_list(&self, what: &str, line: usize) -> Result> { + match self { + Value::List(vs) => vs.iter().map(|v| v.as_symbol(what, line)).collect(), + other => Err(DeedError { + line, + message: format!("{what} must be a list, found {}", other.describe()), + }), + } + } +} + +/// Parse a whole deed: one top-level clause, nothing after it. +pub fn parse(text: &str) -> Result { + let mut p = Parser { + s: text.chars().collect(), + i: 0, + line: 1, + }; + p.skip_sep()?; + if p.peek() != Some('(') { + return Err(p.err("a deed starts with '('")); + } + let root = p.clause()?; + p.skip_sep()?; + if p.peek().is_some() { + return Err(p.err("trailing content after the closing ')'")); + } + Ok(root) +} + +struct Parser { + s: Vec, + i: usize, + line: usize, +} + +fn is_sym_start(c: char) -> bool { + c.is_ascii_alphabetic() +} + +fn is_sym_char(c: char) -> bool { + c.is_ascii_alphanumeric() || ".*/<>=!?+-_".contains(c) +} + +impl Parser { + fn err(&self, message: &str) -> DeedError { + DeedError { + line: self.line, + message: message.to_string(), + } + } + + fn peek(&self) -> Option { + self.s.get(self.i).copied() + } + + fn bump(&mut self) -> Option { + let c = self.peek()?; + self.i += 1; + if c == '\n' { + self.line += 1; + } + Some(c) + } + + /// Skip spaces, line ends and comments. Returns whether anything was + /// consumed. A tab, or a CR that does not start a CRLF, is an error + /// (deed.abnf `line-end = CRLF / LF`). + fn skip_sep(&mut self) -> Result { + let start = self.i; + loop { + match self.peek() { + Some(' ' | '\n') => { + self.bump(); + } + Some('\r') => { + if self.s.get(self.i + 1) != Some(&'\n') { + return Err(self.err("a bare CR is not a line end (use LF or CRLF)")); + } + self.bump(); + } + Some('\t') => return Err(self.err("a tab is not a valid separator (use spaces)")), + Some(';') => { + while let Some(c) = self.peek() { + if c == '\n' { + break; + } + self.bump(); + } + } + _ => break, + } + } + Ok(self.i > start) + } + + fn symbol(&mut self) -> Result { + let mut out = String::new(); + match self.peek() { + Some(c) if is_sym_start(c) => { + out.push(c); + self.bump(); + } + _ => return Err(self.err("expected a symbol")), + } + while let Some(c) = self.peek() { + if is_sym_char(c) { + out.push(c); + self.bump(); + } else { + break; + } + } + Ok(out) + } + + fn clause(&mut self) -> Result { + let line = self.line; + self.bump(); // '(' + let head = self.symbol()?; + let mut items = Vec::new(); + loop { + let sep = self.skip_sep()?; + match self.peek() { + None => { + return Err(DeedError { + line, + message: format!("clause '{head}' is never closed"), + }) + } + Some(')') => { + self.bump(); + return Ok(Clause { head, items, line }); + } + Some(_) if !sep => return Err(self.err("expected a space between items")), + Some('(') => items.push(Item::Clause(self.clause()?)), + Some(':') => { + let line = self.line; + self.bump(); + let key = self.symbol()?; + if !self.skip_sep()? { + return Err(self.err("expected a space between a keyword and its value")); + } + let value = self.value()?; + items.push(Item::Field { key, value, line }); + } + Some(c) if head == "bot" && is_sym_start(c) => { + let name = self.symbol()?; + return Err(self.err(&format!( + "bare symbol '{name}' in a (bot) clause: the canonical spelling is (bot :name {name} ...)" + ))); + } + Some(c) => { + return Err(self.err(&format!( + "unexpected '{c}' in clause '{head}' (expected a :field or a clause)" + ))) + } + } + } + } + + fn value(&mut self) -> Result { + match self.peek() { + None => Err(self.err("expected a value, found the end of the file")), + Some('"') => Ok(Value::Str(self.string()?)), + Some('(') => self.list(), + Some('\'') => { + self.bump(); + match self.peek() { + Some('(') => Ok(Value::Quoted(Box::new(self.list()?))), + Some(c) if is_sym_start(c) => { + Ok(Value::Quoted(Box::new(Value::Sym(self.symbol()?)))) + } + _ => Err(self.err("only a symbol or a list can be quoted")), + } + } + Some('#') => self.hash_literal(), + Some(c) if c.is_ascii_digit() || c == '-' => self.integer(), + Some(c) if is_sym_start(c) => Ok(Value::Sym(self.symbol()?)), + Some(c) => Err(self.err(&format!("unexpected '{c}' where a value was expected"))), + } + } + + fn list(&mut self) -> Result { + let line = self.line; + self.bump(); // '(' + let mut out = Vec::new(); + loop { + let sep = self.skip_sep()?; + match self.peek() { + None => { + return Err(DeedError { + line, + message: "list is never closed".into(), + }) + } + Some(')') => { + self.bump(); + return Ok(Value::List(out)); + } + Some(_) if !sep && !out.is_empty() => { + return Err(self.err("expected a space between list values")) + } + Some(_) => out.push(self.value()?), + } + } + } + + fn string(&mut self) -> Result { + self.bump(); // opening quote + let mut out = String::new(); + loop { + match self.bump() { + None => return Err(self.err("string is never closed")), + Some('"') => return Ok(out), + Some('\\') => match self.bump() { + Some('"') => out.push('"'), + Some('\\') => out.push('\\'), + Some('n') => out.push('\n'), + Some('t') => out.push('\t'), + _ => { + return Err(self.err("invalid escape (only \\\" \\\\ \\n \\t are allowed)")) + } + }, + Some(c) if (c as u32) < 0x20 || c as u32 == 0x7f => { + return Err(self.err("a control character in a string")) + } + Some(c) => out.push(c), + } + } + } + + fn integer(&mut self) -> Result { + let mut text = String::new(); + if self.peek() == Some('-') { + text.push('-'); + self.bump(); + } + let digits_from = text.len(); + while let Some(c) = self.peek() { + if c.is_ascii_digit() { + text.push(c); + self.bump(); + } else { + break; + } + } + if text.len() == digits_from { + return Err(self.err("expected digits after '-'")); + } + if self.peek().is_some_and(is_sym_char) { + return Err(self.err("an integer must end at a separator")); + } + text.parse::() + .map(Value::Int) + .map_err(|_| self.err("integer out of range")) + } + + fn hash_literal(&mut self) -> Result { + self.bump(); // '#' + let mut tag = String::new(); + while let Some(c) = self.peek() { + if c.is_ascii_alphanumeric() { + tag.push(c); + self.bump(); + } else { + break; + } + } + match tag.as_str() { + "t" | "f" => { + if self.peek().is_some_and(is_sym_char) { + return Err(self.err("a boolean must end at a separator")); + } + Ok(Value::Bool(tag == "t")) + } + "u5" | "u8" | "uuid" => { + if self.peek() != Some('"') { + return Err(self.err(&format!("#{tag} must be followed by a string"))); + } + Ok(Value::Literal(format!("#{tag}\"{}\"", self.string()?))) + } + _ => Err(self.err(&format!("unknown literal '#{tag}'"))), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reads_fields_clauses_comments_and_every_value_kind() { + let c = parse( + ";; SPDX-License-Identifier: MPL-2.0\n; note\n(repo-deed\n :schema-version \"1.0.0\" ; tail\n :id #u5\"a/b\"\n :n -12\n :on #t\n :off #f\n :sym thing.v1\n :q 'sym\n :ql '(a b)\n :l (\n a \"b\" 3)\n (inner :k \"a\\\"b\\\\c\\nd\\te\"))\n", + ) + .unwrap(); + assert_eq!(c.head, "repo-deed"); + let inner = c.clauses("inner").next().unwrap(); + match &inner.items[0] { + Item::Field { value, .. } => assert_eq!(value, &Value::Str("a\"b\\c\nd\te".into())), + other => panic!("{other:?}"), + } + assert_eq!(c.items.len(), 10); + } + + #[test] + fn a_bare_symbol_is_an_error_everywhere_and_a_bot_clause_names_the_canonical_form() { + assert!(parse("(x (bot :name panicbot :a b))").is_ok()); + let e = parse("(x (bot panicbot :a b))").unwrap_err(); + assert!(e.message.contains("(bot :name panicbot ...)"), "{e}"); + assert!(parse("(x (other panicbot))").is_err()); + } + + #[test] + fn malformed_input_is_an_error_with_a_line() { + for (label, text) in [ + ("unclosed", "(a\n :b c"), + ("trailing", "(a) (b)"), + ("tab", "(a\n\t:b c)"), + ("bad escape", "(a :b \"\\u0041\")"), + ("unclosed string", "(a :b \"x)"), + ("no value", "(a :b)"), + ("no space", "(a :b c(d))"), + ("toml", "key = \"v\""), + ("bare in clause", "(a b)"), + ("bad literal", "(a :b #x)"), + ("bad bool", "(a :b #true)"), + ("quoted string", "(a :b '\"x\")"), + ("empty", ""), + ] { + assert!(parse(text).is_err(), "{label} should not parse"); + } + let e = parse("(a\n\n :b c\n :d").unwrap_err(); + assert!(e.line >= 3, "{e}"); + } + + #[test] + fn a_bare_cr_is_an_error_and_crlf_is_a_line_end() { + assert!(parse("(a\r\n :b c)\r\n").is_ok()); + let e = parse("(a\r :b c)").unwrap_err(); + assert!(e.message.contains("bare CR"), "{e}"); + } + + #[test] + fn field_reads_the_top_level_only_and_clause_at_walks_a_path() { + let c = parse( + "(repo-deed :canonical-name \"x\"\n (status :phase alpha (history (entry :phase old)))\n (agentic (integrity :level 2)))", + ) + .unwrap(); + assert_eq!(c.field("canonical-name"), Some(&Value::Str("x".into()))); + let status = c.clause_at("status").unwrap(); + assert_eq!(status.field("phase"), Some(&Value::Sym("alpha".into()))); + // A nested clause's field is never the clause's own. + assert_eq!(c.clause_at("status/history").unwrap().field("phase"), None); + assert_eq!( + c.clause_at("agentic/integrity").unwrap().field("level"), + Some(&Value::Int(2)) + ); + assert!(c.has("agentic") && !c.has("meta") && !c.has("agentic/missing")); + assert_eq!(c.clause_at("").unwrap().head, "repo-deed"); + assert_eq!(c.clause_heads(), vec!["status", "agentic"]); + } + + #[test] + fn chora_names_follow_the_abnf_stem() { + for ok in [ + "gitbot-fleet_chora.deed", + "a.b_c_chora.deed", + "x1_chora.deed", + ] { + assert!(is_chora_name(ok), "{ok}"); + } + for bad in [ + "_chora.deed", + "x_chora.deed.bak", + "x y_chora.deed", + "STATE.deed", + "x_praxis.deed", + ] { + assert!(!is_chora_name(bad), "{bad}"); + } + } + + fn tmp(tag: &str) -> PathBuf { + let d = std::env::temp_dir().join(format!("deed-reader-{tag}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&d); + std::fs::create_dir_all(&d).unwrap(); + d + } + + #[test] + fn find_and_load_chora_cover_none_one_many_bad_and_wrong_head() { + let d = tmp("none"); + assert!(find_chora(&d).unwrap().is_none()); + assert!(load_chora(&d).unwrap().is_none()); + // A directory with the name does not count. + std::fs::create_dir_all(d.join("dir_chora.deed")).unwrap(); + assert!(find_chora(&d).unwrap().is_none()); + + let d = tmp("one"); + std::fs::write(d.join("r_chora.deed"), ";; SPDX-License-Identifier: MPL-2.0\n(repo-deed :canonical-name \"r\" (status :phase beta))\n").unwrap(); + let c = load_chora(&d).unwrap().unwrap(); + assert!(c.path.ends_with("r_chora.deed") && c.root.has("status")); + + std::fs::write(d.join("s_chora.deed"), "(repo-deed)").unwrap(); + assert!(matches!(find_chora(&d), Err(ChoraError::Multiple(v)) if v.len() == 2)); + + let d = tmp("bad"); + std::fs::write(d.join("r_chora.deed"), "(repo-deed\n :x").unwrap(); + assert!(matches!(load_chora(&d), Err(ChoraError::Parse(_, e)) if e.line == 2)); + + let d = tmp("head"); + std::fs::write(d.join("r_chora.deed"), "(praxis-deed :x \"y\")").unwrap(); + let e = load_chora(&d).unwrap_err(); + assert!(e.to_string().contains("must be a repo-deed"), "{e}"); + } +} From ef205b3c5cb75d19c625ae9b64b6d3d4ebd10b0b Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:36:25 +0000 Subject: [PATCH 2/8] refactor(panicbot): read the deed through deed-reader; fix the finishingbot image SonarCloud failed #689's quality gate on 35.4% duplication: deed-reader was extracted from panicbot's reader while panicbot kept its copy. The duplication is now removed at source: panicbot's `deed` module re-exports gitbot-deed-reader (parse, Clause, Item, Value, DeedError, Result), so there is one reader. Behaviour is unchanged except the canon tightening already in deed-reader (a bare CR is an error, deed.abnf line-end). panicbot: 170 tests pass, clippy -D warnings and fmt clean (--locked). bots/finishingbot/Containerfile copied only its own Cargo.toml, lock and src, so the new in-repo path dependency could not resolve. It now builds from the repository root and keeps the layout (deed-reader at /build/deed-reader). Replaying its builder stage also showed it was already broken on main: Cargo.toml declares a [[bench]] the image never copied, so the manifest did not parse. benches/ is copied now. The replayed builder stage builds, and that binary reports DEED-001 on an empty repo, nothing on a good deed, and DEED-003 (line 2) on a broken one. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDhFeexmokLqLRfZNce --- bots/finishingbot/Containerfile | 18 +- bots/panicbot/Cargo.lock | 5 + bots/panicbot/Cargo.toml | 2 + bots/panicbot/src/deed.rs | 467 +------------------------------- deed-reader/README.adoc | 4 +- deed-reader/src/lib.rs | 3 +- 6 files changed, 31 insertions(+), 468 deletions(-) diff --git a/bots/finishingbot/Containerfile b/bots/finishingbot/Containerfile index 2594227d..5521325d 100644 --- a/bots/finishingbot/Containerfile +++ b/bots/finishingbot/Containerfile @@ -2,10 +2,14 @@ # Cerro Torre - The Challenging Peak # Patagonian mountain known for difficulty and technical climbing # Purpose: Release readiness validation (conquering the final ascent) +# +# Build from the REPOSITORY ROOT, so the in-repo deed-reader crate is in the +# context (finishingbot reads the chora deed through it): +# podman build -f bots/finishingbot/Containerfile -t cerro-torre . FROM docker.io/library/rust:latest AS builder -WORKDIR /build +WORKDIR /build/bots/finishingbot # Install dependencies and nightly toolchain RUN apt-get update && \ @@ -13,9 +17,13 @@ RUN apt-get update && \ rm -rf /var/lib/apt/lists/* && \ rustup default nightly -# Copy source -COPY Cargo.toml Cargo.lock ./ -COPY src ./src +# Copy source, keeping the repository layout so ../../deed-reader resolves +COPY deed-reader /build/deed-reader +COPY bots/finishingbot/Cargo.toml bots/finishingbot/Cargo.lock ./ +COPY bots/finishingbot/src ./src +# Cargo.toml declares a [[bench]]; without it the manifest does not parse +# (this image failed to build on main for that reason alone). +COPY bots/finishingbot/benches ./benches # Remove path dependency that isn't available in container context RUN sed -i '/gitbot-shared-context.*path.*optional/d' Cargo.toml && \ @@ -32,7 +40,7 @@ RUN apt-get update && \ apt-get install -y ca-certificates libssl3 && \ rm -rf /var/lib/apt/lists/* -COPY --from=builder /build/target/release/finishing-bot /usr/local/bin/cerro-torre +COPY --from=builder /build/bots/finishingbot/target/release/finishing-bot /usr/local/bin/cerro-torre # Run as non-root RUN useradd -r -s /bin/false cerro-torre diff --git a/bots/panicbot/Cargo.lock b/bots/panicbot/Cargo.lock index 85da9965..2b33a246 100644 --- a/bots/panicbot/Cargo.lock +++ b/bots/panicbot/Cargo.lock @@ -264,6 +264,10 @@ dependencies = [ "log", ] +[[package]] +name = "gitbot-deed-reader" +version = "0.1.0" + [[package]] name = "gitbot-shared-context" version = "0.1.0" @@ -589,6 +593,7 @@ dependencies = [ "anyhow", "chrono", "clap", + "gitbot-deed-reader", "gitbot-shared-context", "rustix", "serde", diff --git a/bots/panicbot/Cargo.toml b/bots/panicbot/Cargo.toml index c3ba4e7d..15f2ef81 100644 --- a/bots/panicbot/Cargo.toml +++ b/bots/panicbot/Cargo.toml @@ -17,6 +17,8 @@ path = "src/main.rs" [dependencies] # Fleet integration gitbot-shared-context = { path = "../../shared-context" } +# Repo deed reader (shared, std-only, in-repo) +gitbot-deed-reader = { path = "../../deed-reader" } # CLI clap = { version = "4.6.1", features = ["derive"] } diff --git a/bots/panicbot/src/deed.rs b/bots/panicbot/src/deed.rs index dd0bbe14..1363ccd1 100644 --- a/bots/panicbot/src/deed.rs +++ b/bots/panicbot/src/deed.rs @@ -1,463 +1,10 @@ // SPDX-License-Identifier: MPL-2.0 -//! A small, strict reader for the repo deed (`_chora.deed`). +//! The repo deed (`_chora.deed`) reader. //! -//! No other crate in gitbot-fleet reads deeds (checked 2026-11-13: no -//! `chora`/`deed` reader in shared-context or any bot), so this module reads -//! just enough of the grammar (`standards/1-formats/deed/spec/abnf/deed.abnf`) -//! to find one clause and its fields: -//! -//! - `(` is the only bracket; `;` starts a comment that runs to the line end; -//! - a clause is `(head item...)`, an item is a `:keyword value` field or a -//! nested clause, separated by spaces or line ends (a tab is an error); -//! - values: `"strings"` (escapes `\"` `\\` `\n` `\t` only), bare symbols, -//! integers, `#t` / `#f`, the `#u5"..."` / `#u8"..."` / `#uuid"..."` -//! literals, `'quoted` symbols and lists, and `( lists )`; -//! - the whole input must be consumed. -//! -//! There is one spelling of a bot entry: `(bot :name panicbot ...)`. A bare -//! symbol is not a field or a clause, so the grammar rejects `(bot panicbot ...)` -//! and so does this reader, with an error naming the canonical spelling. -//! -//! This is a reader, not the validator: `deed_lint` in standards stays the -//! conformance gate (header, `:schema-version`, line length, UUID shape). The -//! reader's job is to never guess: every malformed input is an `Err` with a -//! line number, never a silent default. - -use std::fmt; - -/// One parenthesised clause. -#[derive(Debug, Clone, PartialEq)] -pub struct Clause { - /// The symbol after `(`. - pub head: String, - /// Fields and nested clauses, in order. - pub items: Vec, - /// 1-based line of the `(`. - pub line: usize, -} - -/// An item inside a clause. -#[derive(Debug, Clone, PartialEq)] -pub enum Item { - /// `:key value`. - Field { - key: String, - value: Value, - line: usize, - }, - /// A nested clause. - Clause(Clause), -} - -/// A field value. -#[derive(Debug, Clone, PartialEq)] -pub enum Value { - Str(String), - Sym(String), - Int(i64), - Bool(bool), - /// `#u5"..."`, `#u8"..."` or `#uuid"..."`: carried as its text, unused here. - Literal(String), - Quoted(Box), - List(Vec), -} - -impl Value { - fn describe(&self) -> &'static str { - match self { - Value::Str(_) => "a string", - Value::Sym(_) => "a symbol", - Value::Int(_) => "an integer", - Value::Bool(_) => "a boolean", - Value::Literal(_) => "a literal", - Value::Quoted(_) => "a quoted value", - Value::List(_) => "a list", - } - } -} - -/// A deed parse or shape error, with the 1-based line it was found on. -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct DeedError { - pub line: usize, - pub message: String, -} - -impl fmt::Display for DeedError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "line {}: {}", self.line, self.message) - } -} - -impl std::error::Error for DeedError {} - -/// Shorthand for results in this module. -pub type Result = std::result::Result; - -impl Clause { - /// The nested clauses with this head. - pub fn clauses<'a>(&'a self, head: &'a str) -> impl Iterator + 'a { - self.items.iter().filter_map(move |i| match i { - Item::Clause(c) if c.head == head => Some(c), - _ => None, - }) - } -} - -impl Value { - /// The value as a bare symbol, or an error naming `what`. - pub fn as_symbol(&self, what: &str, line: usize) -> Result<&str> { - match self { - Value::Sym(s) => Ok(s), - other => Err(DeedError { - line, - message: format!("{what} must be a symbol, found {}", other.describe()), - }), - } - } - - /// The value as a string, or an error naming `what`. - pub fn as_string(&self, what: &str, line: usize) -> Result<&str> { - match self { - Value::Str(s) => Ok(s), - other => Err(DeedError { - line, - message: format!("{what} must be a string, found {}", other.describe()), - }), - } - } - - /// The value as a list of bare symbols, or an error naming `what`. - pub fn as_symbol_list(&self, what: &str, line: usize) -> Result> { - match self { - Value::List(vs) => vs.iter().map(|v| v.as_symbol(what, line)).collect(), - other => Err(DeedError { - line, - message: format!("{what} must be a list, found {}", other.describe()), - }), - } - } -} - -/// Parse a whole deed: one top-level clause, nothing after it. -pub fn parse(text: &str) -> Result { - let mut p = Parser { - s: text.chars().collect(), - i: 0, - line: 1, - }; - p.skip_sep()?; - if p.peek() != Some('(') { - return Err(p.err("a deed starts with '('")); - } - let root = p.clause()?; - p.skip_sep()?; - if p.peek().is_some() { - return Err(p.err("trailing content after the closing ')'")); - } - Ok(root) -} - -struct Parser { - s: Vec, - i: usize, - line: usize, -} - -fn is_sym_start(c: char) -> bool { - c.is_ascii_alphabetic() -} - -fn is_sym_char(c: char) -> bool { - c.is_ascii_alphanumeric() || ".*/<>=!?+-_".contains(c) -} - -impl Parser { - fn err(&self, message: &str) -> DeedError { - DeedError { - line: self.line, - message: message.to_string(), - } - } - - fn peek(&self) -> Option { - self.s.get(self.i).copied() - } - - fn bump(&mut self) -> Option { - let c = self.peek()?; - self.i += 1; - if c == '\n' { - self.line += 1; - } - Some(c) - } - - /// Skip spaces, line ends and comments. Returns whether anything was - /// consumed. A tab is an error. - fn skip_sep(&mut self) -> Result { - let start = self.i; - loop { - match self.peek() { - Some(' ' | '\n') => { - self.bump(); - } - Some('\r') => { - self.bump(); - } - Some('\t') => return Err(self.err("a tab is not a valid separator (use spaces)")), - Some(';') => { - while let Some(c) = self.peek() { - if c == '\n' { - break; - } - self.bump(); - } - } - _ => break, - } - } - Ok(self.i > start) - } - - fn symbol(&mut self) -> Result { - let mut out = String::new(); - match self.peek() { - Some(c) if is_sym_start(c) => { - out.push(c); - self.bump(); - } - _ => return Err(self.err("expected a symbol")), - } - while let Some(c) = self.peek() { - if is_sym_char(c) { - out.push(c); - self.bump(); - } else { - break; - } - } - Ok(out) - } - - fn clause(&mut self) -> Result { - let line = self.line; - self.bump(); // '(' - let head = self.symbol()?; - let mut items = Vec::new(); - loop { - let sep = self.skip_sep()?; - match self.peek() { - None => { - return Err(DeedError { - line, - message: format!("clause '{head}' is never closed"), - }) - } - Some(')') => { - self.bump(); - return Ok(Clause { head, items, line }); - } - Some(_) if !sep => return Err(self.err("expected a space between items")), - Some('(') => items.push(Item::Clause(self.clause()?)), - Some(':') => { - let line = self.line; - self.bump(); - let key = self.symbol()?; - if !self.skip_sep()? { - return Err(self.err("expected a space between a keyword and its value")); - } - let value = self.value()?; - items.push(Item::Field { key, value, line }); - } - Some(c) if head == "bot" && is_sym_start(c) => { - let name = self.symbol()?; - return Err(self.err(&format!( - "bare symbol '{name}' in a (bot) clause: the canonical spelling is (bot :name {name} ...)" - ))); - } - Some(c) => { - return Err(self.err(&format!( - "unexpected '{c}' in clause '{head}' (expected a :field or a clause)" - ))) - } - } - } - } - - fn value(&mut self) -> Result { - match self.peek() { - None => Err(self.err("expected a value, found the end of the file")), - Some('"') => Ok(Value::Str(self.string()?)), - Some('(') => self.list(), - Some('\'') => { - self.bump(); - match self.peek() { - Some('(') => Ok(Value::Quoted(Box::new(self.list()?))), - Some(c) if is_sym_start(c) => { - Ok(Value::Quoted(Box::new(Value::Sym(self.symbol()?)))) - } - _ => Err(self.err("only a symbol or a list can be quoted")), - } - } - Some('#') => self.hash_literal(), - Some(c) if c.is_ascii_digit() || c == '-' => self.integer(), - Some(c) if is_sym_start(c) => Ok(Value::Sym(self.symbol()?)), - Some(c) => Err(self.err(&format!("unexpected '{c}' where a value was expected"))), - } - } - - fn list(&mut self) -> Result { - let line = self.line; - self.bump(); // '(' - let mut out = Vec::new(); - loop { - let sep = self.skip_sep()?; - match self.peek() { - None => { - return Err(DeedError { - line, - message: "list is never closed".into(), - }) - } - Some(')') => { - self.bump(); - return Ok(Value::List(out)); - } - Some(_) if !sep && !out.is_empty() => { - return Err(self.err("expected a space between list values")) - } - Some(_) => out.push(self.value()?), - } - } - } - - fn string(&mut self) -> Result { - self.bump(); // opening quote - let mut out = String::new(); - loop { - match self.bump() { - None => return Err(self.err("string is never closed")), - Some('"') => return Ok(out), - Some('\\') => match self.bump() { - Some('"') => out.push('"'), - Some('\\') => out.push('\\'), - Some('n') => out.push('\n'), - Some('t') => out.push('\t'), - _ => { - return Err(self.err("invalid escape (only \\\" \\\\ \\n \\t are allowed)")) - } - }, - Some(c) if (c as u32) < 0x20 || c as u32 == 0x7f => { - return Err(self.err("a control character in a string")) - } - Some(c) => out.push(c), - } - } - } - - fn integer(&mut self) -> Result { - let mut text = String::new(); - if self.peek() == Some('-') { - text.push('-'); - self.bump(); - } - let digits_from = text.len(); - while let Some(c) = self.peek() { - if c.is_ascii_digit() { - text.push(c); - self.bump(); - } else { - break; - } - } - if text.len() == digits_from { - return Err(self.err("expected digits after '-'")); - } - if self.peek().is_some_and(is_sym_char) { - return Err(self.err("an integer must end at a separator")); - } - text.parse::() - .map(Value::Int) - .map_err(|_| self.err("integer out of range")) - } - - fn hash_literal(&mut self) -> Result { - self.bump(); // '#' - let mut tag = String::new(); - while let Some(c) = self.peek() { - if c.is_ascii_alphanumeric() { - tag.push(c); - self.bump(); - } else { - break; - } - } - match tag.as_str() { - "t" | "f" => { - if self.peek().is_some_and(is_sym_char) { - return Err(self.err("a boolean must end at a separator")); - } - Ok(Value::Bool(tag == "t")) - } - "u5" | "u8" | "uuid" => { - if self.peek() != Some('"') { - return Err(self.err(&format!("#{tag} must be followed by a string"))); - } - Ok(Value::Literal(format!("#{tag}\"{}\"", self.string()?))) - } - _ => Err(self.err(&format!("unknown literal '#{tag}'"))), - } - } -} - -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn reads_fields_clauses_comments_and_every_value_kind() { - let c = parse( - ";; SPDX-License-Identifier: MPL-2.0\n; note\n(repo-deed\n :schema-version \"1.0.0\" ; tail\n :id #u5\"a/b\"\n :n -12\n :on #t\n :off #f\n :sym thing.v1\n :q 'sym\n :ql '(a b)\n :l (\n a \"b\" 3)\n (inner :k \"a\\\"b\\\\c\\nd\\te\"))\n", - ) - .unwrap(); - assert_eq!(c.head, "repo-deed"); - let inner = c.clauses("inner").next().unwrap(); - match &inner.items[0] { - Item::Field { value, .. } => assert_eq!(value, &Value::Str("a\"b\\c\nd\te".into())), - other => panic!("{other:?}"), - } - assert_eq!(c.items.len(), 10); - } - - #[test] - fn a_bare_symbol_is_an_error_everywhere_and_a_bot_clause_names_the_canonical_form() { - assert!(parse("(x (bot :name panicbot :a b))").is_ok()); - let e = parse("(x (bot panicbot :a b))").unwrap_err(); - assert!(e.message.contains("(bot :name panicbot ...)"), "{e}"); - assert!(parse("(x (other panicbot))").is_err()); - } +//! This module was panicbot's own strict reader; it now lives, unchanged in +//! behaviour, in the shared std-only crate `deed-reader/` (gitbot-deed-reader) +//! so every bot reads the deed one way. One tightening came with the move: a +//! bare CR (not part of CRLF) is an error, as deed.abnf `line-end` requires. +//! `deed_lint` in standards stays the conformance gate. - #[test] - fn malformed_input_is_an_error_with_a_line() { - for (label, text) in [ - ("unclosed", "(a\n :b c"), - ("trailing", "(a) (b)"), - ("tab", "(a\n\t:b c)"), - ("bad escape", "(a :b \"\\u0041\")"), - ("unclosed string", "(a :b \"x)"), - ("no value", "(a :b)"), - ("no space", "(a :b c(d))"), - ("toml", "key = \"v\""), - ("bare in clause", "(a b)"), - ("bad literal", "(a :b #x)"), - ("bad bool", "(a :b #true)"), - ("quoted string", "(a :b '\"x\")"), - ("empty", ""), - ] { - assert!(parse(text).is_err(), "{label} should not parse"); - } - let e = parse("(a\n\n :b c\n :d").unwrap_err(); - assert!(e.line >= 3, "{e}"); - } -} +pub use deed_reader::{parse, Clause, DeedError, Item, Result, Value}; diff --git a/deed-reader/README.adoc b/deed-reader/README.adoc index bcf78d7d..befba020 100644 --- a/deed-reader/README.adoc +++ b/deed-reader/README.adoc @@ -29,5 +29,5 @@ This is a reader, not the validator: `bun 1-formats/deed/tools/deed_lint.js` in standards stays the conformance gate. Users: finishingbot (DEED-001 to DEED-004, SCM-006), glambot (MACH-008, -MACH-009). panicbot and rhodibot still carry their own readers; moving them -onto this crate is a follow-up. +MACH-009) and panicbot (its `deed` module re-exports this crate). rhodibot still +carries its own reader; moving it onto this crate waits on #687. diff --git a/deed-reader/src/lib.rs b/deed-reader/src/lib.rs index 40455cf8..011458ef 100644 --- a/deed-reader/src/lib.rs +++ b/deed-reader/src/lib.rs @@ -31,7 +31,8 @@ //! //! Extracted from panicbot's `src/deed.rs` (2026-11-13) so that finishingbot //! and glambot read the deed the same way; panicbot and rhodibot keep their -//! own copies until they are moved onto this crate. +//! own copies until they are moved onto this crate. panicbot's `deed` module +//! now re-exports this crate; rhodibot's move waits on #687. use std::fmt; use std::path::{Path, PathBuf}; From 490420de258cf4cf331aae3fb598d9ae45c25c38 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:36:35 +0000 Subject: [PATCH 3/8] docs(deed-reader): say which bots read through it Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDhFeexmokLqLRfZNce --- deed-reader/src/lib.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/deed-reader/src/lib.rs b/deed-reader/src/lib.rs index 011458ef..cfc5cc79 100644 --- a/deed-reader/src/lib.rs +++ b/deed-reader/src/lib.rs @@ -30,9 +30,8 @@ //! input is an `Err` with a line number, never a silent default. //! //! Extracted from panicbot's `src/deed.rs` (2026-11-13) so that finishingbot -//! and glambot read the deed the same way; panicbot and rhodibot keep their -//! own copies until they are moved onto this crate. panicbot's `deed` module -//! now re-exports this crate; rhodibot's move waits on #687. +//! and glambot read the deed the same way. panicbot's `deed` module now +//! re-exports this crate; rhodibot keeps its own reader until #687 lands. use std::fmt; use std::path::{Path, PathBuf}; From 0ba4595801d4acced5633f0eeed13fea100a8319 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 16:32:24 +0000 Subject: [PATCH 4/8] fix(deed-reader): bound nesting depth so a deep deed is an error, not a crash Review finding on #689: clause() and list() recursed without a limit, so a root deed nested deeply enough overflowed the stack. Rust aborts on stack overflow, so finishingbot's and glambot's whole audit run would die on any repository carrying such a file, with nothing to catch. Both now enter through descend(), which refuses past MAX_DEPTH (64) with an ordinary DeedError naming the limit and the line. Quoted lists go through list() and are covered too. Real deeds nest a handful of levels. Tests: 100,000-deep clauses, lists and quoted lists are errors; nesting at exactly the limit still reads, one past it does not. With the limit disabled the first test aborts the process with a stack overflow (checked). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDhFeexmokLqLRfZNce --- deed-reader/src/lib.rs | 62 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/deed-reader/src/lib.rs b/deed-reader/src/lib.rs index cfc5cc79..ab6bc550 100644 --- a/deed-reader/src/lib.rs +++ b/deed-reader/src/lib.rs @@ -291,12 +291,18 @@ impl Value { } } +/// How deeply clauses and lists may nest. Real deeds nest a handful of levels; +/// the limit exists so a hostile or broken deed is a parse error, not a stack +/// overflow, which aborts the whole process and cannot be caught. +pub const MAX_DEPTH: usize = 64; + /// Parse a whole deed: one top-level clause, nothing after it. pub fn parse(text: &str) -> Result { let mut p = Parser { s: text.chars().collect(), i: 0, line: 1, + depth: 0, }; p.skip_sep()?; if p.peek() != Some('(') { @@ -314,6 +320,7 @@ struct Parser { s: Vec, i: usize, line: usize, + depth: usize, } fn is_sym_start(c: char) -> bool { @@ -332,6 +339,17 @@ impl Parser { } } + /// Enter one level of nesting, refusing past [`MAX_DEPTH`]. + fn descend(&mut self) -> Result<()> { + if self.depth >= MAX_DEPTH { + return Err(self.err(&format!( + "clauses and lists nest deeper than {MAX_DEPTH} levels" + ))); + } + self.depth += 1; + Ok(()) + } + fn peek(&self) -> Option { self.s.get(self.i).copied() } @@ -398,6 +416,13 @@ impl Parser { fn clause(&mut self) -> Result { let line = self.line; + self.descend()?; + let clause = self.clause_body(line); + self.depth -= 1; + clause + } + + fn clause_body(&mut self, line: usize) -> Result { self.bump(); // '(' let head = self.symbol()?; let mut items = Vec::new(); @@ -465,6 +490,13 @@ impl Parser { fn list(&mut self) -> Result { let line = self.line; + self.descend()?; + let list = self.list_body(line); + self.depth -= 1; + list + } + + fn list_body(&mut self, line: usize) -> Result { self.bump(); // '(' let mut out = Vec::new(); loop { @@ -586,6 +618,36 @@ mod tests { assert_eq!(c.items.len(), 10); } + /// `depth` clauses nested inside one another: `(a (a (a)))`. + fn nested_clauses(depth: usize) -> String { + "(a".to_string() + &" (a".repeat(depth - 1) + &")".repeat(depth) + } + + #[test] + fn deep_nesting_is_a_parse_error_not_a_stack_overflow() { + // Far deeper than any stack: without the limit this aborts the test + // process instead of failing it. + let e = parse(&nested_clauses(100_000)).unwrap_err(); + assert!(e.message.contains("nest deeper than 64"), "{e}"); + let lists = format!("(a :v {}{})", "(".repeat(100_000), ")".repeat(100_000)); + let e = parse(&lists).unwrap_err(); + assert!(e.message.contains("nest deeper than 64"), "{e}"); + let quoted = format!("(a :v '{}{})", "(".repeat(100_000), ")".repeat(100_000)); + assert!(parse("ed).is_err()); + } + + #[test] + fn nesting_up_to_the_limit_still_reads() { + assert!(parse(&nested_clauses(MAX_DEPTH)).is_ok()); + assert!(parse(&nested_clauses(MAX_DEPTH + 1)).is_err()); + // The root clause is one level, so a list may nest MAX_DEPTH - 1 deep. + let n = MAX_DEPTH - 1; + let list = format!("(a :v {}{})", "(".repeat(n), ")".repeat(n)); + assert!(parse(&list).is_ok()); + let list = format!("(a :v {}{})", "(".repeat(n + 1), ")".repeat(n + 1)); + assert!(parse(&list).is_err()); + } + #[test] fn a_bare_symbol_is_an_error_everywhere_and_a_bot_clause_names_the_canonical_form() { assert!(parse("(x (bot :name panicbot :a b))").is_ok()); From 3a274be36c5d688146bf8c5d2175ececf44cfe57 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 16:44:24 +0000 Subject: [PATCH 5/8] fix(deed-reader): a bare CR inside a comment is an error; full paths in finishingbot docs Review findings on #689 (CodeRabbit): - The comment loop consumed a CR that did not start a CRLF, so "(repo-deed ; c\rd\n)" parsed even though a bare CR is rejected everywhere else (deed.abnf line-end = CRLF / LF). It is now the same error inside a comment. LF and CRLF still end a comment. The new test fails with the check removed. - finishingbot's README named descriptiles/STATE.deed and 6scm/ without their .machine_readable/ prefix, so a root descriptiles/ or 6scm/ looked like it would be read; it is not. The README, the project-structure line for scm_files.rs, and the module doc now give the paths the code checks. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDhFeexmokLqLRfZNce --- bots/finishingbot/README.adoc | 4 ++-- bots/finishingbot/src/analyzers/scm_files.rs | 2 +- deed-reader/src/lib.rs | 16 ++++++++++++++++ 3 files changed, 19 insertions(+), 3 deletions(-) diff --git a/bots/finishingbot/README.adoc b/bots/finishingbot/README.adoc index 97744c2f..194ade60 100644 --- a/bots/finishingbot/README.adoc +++ b/bots/finishingbot/README.adoc @@ -49,7 +49,7 @@ the gitbot-fleet shared context layer and makes the final release-readiness dete |No |**Repo Deed** (the `scm_files` report key) -|Reads the one `_chora.deed` at the root (through `deed-reader/`): none is DEED-001 (warning), more than one is DEED-002 (error, D312), unreadable or not a `repo-deed` is DEED-003 (error), no `(status …)` clause and no `descriptiles/STATE.deed` is DEED-004 (warning). A retired STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC or NEUROSYM `.scm` at the root, under `.machine_readable/` or `6scm/` is SCM-006 (warning, "migrate"): it is not validated and is never to be moved +|Reads the one `_chora.deed` at the root (through `deed-reader/`): none is DEED-001 (warning), more than one is DEED-002 (error, D312), unreadable or not a `repo-deed` is DEED-003 (error), no `(status …)` clause and no `.machine_readable/descriptiles/STATE.deed` is DEED-004 (warning). A retired STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC or NEUROSYM `.scm` at the root, under `.machine_readable/` or under `.machine_readable/6scm/` is SCM-006 (warning, "migrate"): it is not validated and is never to be moved |No |**Testing** @@ -418,7 +418,7 @@ src/ placeholder.rs Placeholder detection and removal claims.rs Documentation claims verification release.rs Release artifact and security checks - scm_files.rs .machine_readable/ SCM file validation + scm_files.rs Repo deed (_chora.deed) checks; retired .scm reported as "migrate" testing.rs Testing infrastructure analysis tooling.rs Tooling and CI workflow validation v1_readiness.rs V1 release readiness assessment diff --git a/bots/finishingbot/src/analyzers/scm_files.rs b/bots/finishingbot/src/analyzers/scm_files.rs index b09f049c..b9129ea5 100644 --- a/bots/finishingbot/src/analyzers/scm_files.rs +++ b/bots/finishingbot/src/analyzers/scm_files.rs @@ -22,7 +22,7 @@ //! - `DEED-003` (error): the chora deed cannot be read or parsed, or its //! doc-head is not `repo-deed`. //! - `DEED-004` (warning): no project state: neither a `(status …)` clause in -//! the chora deed nor a `descriptiles/STATE.deed`. +//! the chora deed nor a `.machine_readable/descriptiles/STATE.deed`. //! - `SCM-006-.scm` (warning): a retired `.scm` document is present. //! //! Retired: `SCM-001` (missing `.scm`), `SCM-002`/`003`/`004` (validating a diff --git a/deed-reader/src/lib.rs b/deed-reader/src/lib.rs index ab6bc550..3b3b8bcf 100644 --- a/deed-reader/src/lib.rs +++ b/deed-reader/src/lib.rs @@ -381,10 +381,16 @@ impl Parser { } Some('\t') => return Err(self.err("a tab is not a valid separator (use spaces)")), Some(';') => { + // A comment runs to the line end, which is LF or CRLF: a CR + // inside it that does not start a CRLF is a bare CR, an + // error here as everywhere else. while let Some(c) = self.peek() { if c == '\n' { break; } + if c == '\r' && self.s.get(self.i + 1) != Some(&'\n') { + return Err(self.err("a bare CR is not a line end (use LF or CRLF)")); + } self.bump(); } } @@ -636,6 +642,16 @@ mod tests { assert!(parse("ed).is_err()); } + #[test] + fn a_bare_cr_inside_a_comment_is_an_error_but_crlf_and_lf_end_one() { + let e = parse("(repo-deed ; comment\rstill comment\n)").unwrap_err(); + assert!(e.message.contains("bare CR"), "{e}"); + assert_eq!(e.line, 1); + assert!(parse("(repo-deed ; comment\r\n)").is_ok()); + assert!(parse("(repo-deed ; comment\n)").is_ok()); + assert!(parse(";; SPDX-License-Identifier: MPL-2.0\r\n(repo-deed)\r\n").is_ok()); + } + #[test] fn nesting_up_to_the_limit_still_reads() { assert!(parse(&nested_clauses(MAX_DEPTH)).is_ok()); From 49ea765beafde7e1e5630a64376f9fbbd404c309 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 21:55:28 +0000 Subject: [PATCH 6/8] fix(deed-reader): read the grammar strictly: estate deed, comments, header, empty form, big integers, dir errors Per deed.abnf (standards): estate_chora.deed is an estate-file, not a repo chora deed; a comment is text-chars then a line end (no control characters, no EOF); a deed starts with the SPDX header and its top-level form needs an item (parse_deed, used by load_chora; parse stays the lenient form reader for panicbot); an integer is unbounded digits (Value::BigInt past i64); and an error while iterating the directory is an error, not a skipped entry. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDj7XpKyxE4WbsgTsTh --- deed-reader/src/lib.rs | 299 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 267 insertions(+), 32 deletions(-) diff --git a/deed-reader/src/lib.rs b/deed-reader/src/lib.rs index 3b3b8bcf..441d2423 100644 --- a/deed-reader/src/lib.rs +++ b/deed-reader/src/lib.rs @@ -16,7 +16,10 @@ //! - values: `"strings"` (escapes `\"` `\\` `\n` `\t` only), bare symbols, //! integers, `#t` / `#f`, the `#u5"..."` / `#u8"..."` / `#uuid"..."` //! literals, `'quoted` symbols and lists, and `( lists )`; -//! - the whole input must be consumed. +//! - the whole input must be consumed; +//! - [`parse_deed`] (used by [`load_chora`]) also requires the SPDX header and a +//! non-empty top-level form; [`parse`] is the same form grammar without those +//! two document-level rules. //! //! Lookup follows the conventions of the estate's shell reader //! (`scripts/deed-field.sh` in the RSR template and kyX): [`find_chora`] is @@ -66,6 +69,9 @@ pub enum Value { Str(String), Sym(String), Int(i64), + /// An integer outside `i64` (deed.abnf `integer` is unbounded digits), + /// kept as its token text, sign included, so it never invalidates a deed. + BigInt(String), Bool(bool), /// `#u5"..."`, `#u8"..."` or `#uuid"..."`: carried as its text, unused here. Literal(String), @@ -78,7 +84,7 @@ impl Value { match self { Value::Str(_) => "a string", Value::Sym(_) => "a symbol", - Value::Int(_) => "an integer", + Value::Int(_) | Value::BigInt(_) => "an integer", Value::Bool(_) => "a boolean", Value::Literal(_) => "a literal", Value::Quoted(_) => "a quoted value", @@ -202,6 +208,8 @@ pub fn is_chora_name(name: &str) -> bool { match name.strip_suffix(CHORA_SUFFIX) { Some(stem) => { !stem.is_empty() + // deed.abnf: estate_chora.deed is an estate-file, tested before repo-file. + && stem != "estate" && stem .chars() .all(|c| c.is_ascii_alphanumeric() || "-._".contains(c)) @@ -220,12 +228,24 @@ pub fn find_chora(dir: &Path) -> std::result::Result, ChoraError Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None), Err(e) => return Err(ChoraError::Io(dir.to_path_buf(), e)), }; - let mut found: Vec = entries - .filter_map(|e| e.ok()) - .filter(|e| e.file_name().to_str().is_some_and(is_chora_name)) - .map(|e| e.path()) - .filter(|p| p.is_file()) - .collect(); + pick_chora(dir, entries.map(|e| e.map(|e| (e.file_name(), e.path())))) +} + +/// The chora deed among directory `entries` (name, path). An entry that +/// failed to read is an error, never skipped: `read_dir` may fail while +/// advancing, and skipping would turn an unreadable or ambiguous deed set into +/// a false "none" or "one". +fn pick_chora( + dir: &Path, + entries: impl Iterator>, +) -> std::result::Result, ChoraError> { + let mut found: Vec = Vec::new(); + for entry in entries { + let (name, path) = entry.map_err(|e| ChoraError::Io(dir.to_path_buf(), e))?; + if name.to_str().is_some_and(is_chora_name) && path.is_file() { + found.push(path); + } + } found.sort(); match found.len() { 0 => Ok(None), @@ -248,7 +268,7 @@ pub fn load_chora(dir: &Path) -> std::result::Result, ChoraError> return Ok(None); }; let text = std::fs::read_to_string(&path).map_err(|e| ChoraError::Io(path.clone(), e))?; - let root = parse(&text).map_err(|e| ChoraError::Parse(path.clone(), e))?; + let root = parse_deed(&text).map_err(|e| ChoraError::Parse(path.clone(), e))?; if root.head != "repo-deed" { let head = root.head.clone(); return Err(ChoraError::WrongHead(path, head)); @@ -296,19 +316,47 @@ impl Value { /// overflow, which aborts the whole process and cannot be caught. pub const MAX_DEPTH: usize = 64; -/// Parse a whole deed: one top-level clause, nothing after it. +/// Parse a deed's form: one top-level clause, nothing after it. Lexically +/// strict (comments, separators), but it does not demand the document-level +/// rules of [`parse_deed`], so a consumer reading a hand-written fixture or a +/// file the linter has yet to see is not refused for a missing header. pub fn parse(text: &str) -> Result { + parse_with(text, false) +} + +/// Parse a whole deed as deed.abnf defines it: the mandatory SPDX header +/// (`header = 1*spdx-line`), then one form with at least one field or clause, +/// nothing after it. This is what [`load_chora`] applies to a chora deed. +pub fn parse_deed(text: &str) -> Result { + parse_with(text, true) +} + +fn parse_with(text: &str, document: bool) -> Result { let mut p = Parser { s: text.chars().collect(), i: 0, line: 1, depth: 0, }; + if document { + p.header()?; + } p.skip_sep()?; if p.peek() != Some('(') { return Err(p.err("a deed starts with '('")); } let root = p.clause()?; + // deed.abnf `form` is `"(" doc-head 1*(token-sep (field / clause))`: the + // top-level form needs an item, though a nested clause may be empty. + if document && root.items.is_empty() { + return Err(DeedError { + line: root.line, + message: format!( + "the top-level form '{}' needs at least one field or clause", + root.head + ), + }); + } p.skip_sep()?; if p.peek().is_some() { return Err(p.err("trailing content after the closing ')'")); @@ -323,6 +371,12 @@ struct Parser { depth: usize, } +/// deed.abnf `text-char`: printable ASCII, space, or any non-ASCII scalar. +/// Control characters (C0, DEL) are not text. +fn is_text_char(c: char) -> bool { + !((c as u32) < 0x20 || c as u32 == 0x7f) +} + fn is_sym_start(c: char) -> bool { c.is_ascii_alphabetic() } @@ -363,6 +417,67 @@ impl Parser { Some(c) } + /// Consume one comment, from its `;` through its line end (deed.abnf + /// `comment = ";" *text-char line-end`): the content is text characters + /// only, the line end is LF or CRLF, and the end of the file is not one. + /// Leaves the LF (or the CR of a CRLF) for the caller. + fn comment(&mut self) -> Result<()> { + self.bump(); // ';' + loop { + match self.peek() { + None => { + return Err(self.err( + "a comment reaches the end of the file without a line ending (end it with LF or CRLF)", + )) + } + Some('\n') => return Ok(()), + Some('\r') => { + if self.s.get(self.i + 1) != Some(&'\n') { + return Err(self.err("a bare CR is not a line end (use LF or CRLF)")); + } + return Ok(()); + } + Some(c) if !is_text_char(c) => { + return Err(self.err("a control character in a comment")) + } + Some(_) => { + self.bump(); + } + } + } + } + + /// The mandatory header (deed.abnf `header = 1*spdx-line`): at the very + /// start, one or more `;; SPDX-...` lines, each ended by a line end. + fn header(&mut self) -> Result<()> { + let mut lines = 0; + while self.starts_with(";; SPDX-") { + // `1*text-char` after the prefix: it may not end the line. + if matches!(self.s.get(self.i + 8), None | Some('\n' | '\r')) { + return Err(self.err("an SPDX header line has no content after 'SPDX-'")); + } + self.comment()?; + lines += 1; + // comment() leaves the CR of a CRLF or the LF: take the line end. + if self.peek() == Some('\r') { + self.bump(); + } + self.bump(); + } + if lines == 0 { + return Err(self.err( + "a deed starts with an SPDX header: a line beginning ';; SPDX-' (deed.abnf header)", + )); + } + Ok(()) + } + + fn starts_with(&self, lit: &str) -> bool { + lit.chars() + .enumerate() + .all(|(k, c)| self.s.get(self.i + k) == Some(&c)) + } + /// Skip spaces, line ends and comments. Returns whether anything was /// consumed. A tab, or a CR that does not start a CRLF, is an error /// (deed.abnf `line-end = CRLF / LF`). @@ -384,15 +499,7 @@ impl Parser { // A comment runs to the line end, which is LF or CRLF: a CR // inside it that does not start a CRLF is a bare CR, an // error here as everywhere else. - while let Some(c) = self.peek() { - if c == '\n' { - break; - } - if c == '\r' && self.s.get(self.i + 1) != Some(&'\n') { - return Err(self.err("a bare CR is not a line end (use LF or CRLF)")); - } - self.bump(); - } + self.comment()?; } _ => break, } @@ -571,9 +678,8 @@ impl Parser { if self.peek().is_some_and(is_sym_char) { return Err(self.err("an integer must end at a separator")); } - text.parse::() - .map(Value::Int) - .map_err(|_| self.err("integer out of range")) + // deed.abnf `integer` is unbounded digits: past i64 keep the token. + Ok(text.parse::().map_or(Value::BigInt(text), Value::Int)) } fn hash_literal(&mut self) -> Result { @@ -609,6 +715,12 @@ impl Parser { mod tests { use super::*; + /// The fixtures below are bodies; every deed starts with the SPDX header + /// (it is one line, so reported line numbers are one more than the body's). + fn parse(body: &str) -> Result { + parse_deed(&format!(";; SPDX-License-Identifier: MPL-2.0\n{body}")) + } + #[test] fn reads_fields_clauses_comments_and_every_value_kind() { let c = parse( @@ -644,12 +756,12 @@ mod tests { #[test] fn a_bare_cr_inside_a_comment_is_an_error_but_crlf_and_lf_end_one() { - let e = parse("(repo-deed ; comment\rstill comment\n)").unwrap_err(); + let e = parse("(repo-deed :x y ; comment\rstill comment\n)").unwrap_err(); assert!(e.message.contains("bare CR"), "{e}"); - assert_eq!(e.line, 1); - assert!(parse("(repo-deed ; comment\r\n)").is_ok()); - assert!(parse("(repo-deed ; comment\n)").is_ok()); - assert!(parse(";; SPDX-License-Identifier: MPL-2.0\r\n(repo-deed)\r\n").is_ok()); + assert_eq!(e.line, 2); + assert!(parse("(repo-deed ; comment\r\n :x y)").is_ok()); + assert!(parse("(repo-deed ; comment\n :x y)").is_ok()); + assert!(parse("(repo-deed :x y)\r\n").is_ok()); } #[test] @@ -688,11 +800,12 @@ mod tests { ("bad bool", "(a :b #true)"), ("quoted string", "(a :b '\"x\")"), ("empty", ""), + ("empty top-level form", "(a)"), ] { assert!(parse(text).is_err(), "{label} should not parse"); } let e = parse("(a\n\n :b c\n :d").unwrap_err(); - assert!(e.line >= 3, "{e}"); + assert!(e.line >= 4, "{e}"); } #[test] @@ -763,16 +876,138 @@ mod tests { let c = load_chora(&d).unwrap().unwrap(); assert!(c.path.ends_with("r_chora.deed") && c.root.has("status")); - std::fs::write(d.join("s_chora.deed"), "(repo-deed)").unwrap(); + std::fs::write(d.join("s_chora.deed"), "(repo-deed :x y)").unwrap(); assert!(matches!(find_chora(&d), Err(ChoraError::Multiple(v)) if v.len() == 2)); let d = tmp("bad"); - std::fs::write(d.join("r_chora.deed"), "(repo-deed\n :x").unwrap(); - assert!(matches!(load_chora(&d), Err(ChoraError::Parse(_, e)) if e.line == 2)); + std::fs::write(d.join("r_chora.deed"), format!("{SPDX}(repo-deed\n :x")).unwrap(); + assert!(matches!(load_chora(&d), Err(ChoraError::Parse(_, e)) if e.line == 2 + 1)); let d = tmp("head"); - std::fs::write(d.join("r_chora.deed"), "(praxis-deed :x \"y\")").unwrap(); + std::fs::write( + d.join("r_chora.deed"), + format!("{SPDX}(praxis-deed :x \"y\")"), + ) + .unwrap(); let e = load_chora(&d).unwrap_err(); assert!(e.to_string().contains("must be a repo-deed"), "{e}"); } + + // --- Grammar strictness (review of #689) ------------------------------- + + const SPDX: &str = ";; SPDX-License-Identifier: MPL-2.0\n"; + + #[test] + fn estate_chora_deed_is_not_a_repo_deed_name() { + // deed.abnf: estate-file is tested before repo-file; stem "estate" is excluded. + assert!(!is_chora_name("estate_chora.deed")); + assert!(is_chora_name("estate2_chora.deed")); + assert!(is_chora_name("my-estate_chora.deed")); + let d = tmp("estate"); + std::fs::write( + d.join("estate_chora.deed"), + format!("{SPDX}(estate-deed :schema-version \"1.0.0\")\n"), + ) + .unwrap(); + assert!(find_chora(&d).unwrap().is_none()); + std::fs::write( + d.join("r_chora.deed"), + format!("{SPDX}(repo-deed :schema-version \"1.0.0\")\n"), + ) + .unwrap(); + let c = load_chora(&d).unwrap().unwrap(); + assert!(c.path.ends_with("r_chora.deed")); + } + + #[test] + fn a_comment_must_end_in_a_line_end() { + let ok = format!("{SPDX}(repo-deed :schema-version \"1.0.0\")\n; trailing\n"); + assert!(parse_deed(&ok).is_ok()); + let e = parse_deed(&format!( + "{SPDX}(repo-deed :schema-version \"1.0.0\")\n; trailing" + )) + .unwrap_err(); + assert!(e.message.contains("end of the file"), "{e}"); + // An SPDX line is a comment too and needs its line end. + assert!(parse_deed(";; SPDX-License-Identifier: MPL-2.0").is_err()); + } + + #[test] + fn a_comment_holds_text_chars_only() { + let doc = |c: &str| format!("{SPDX}(repo-deed :schema-version \"1.0.0\" ; {c}\n)\n"); + assert!(parse_deed(&doc("plain ascii and utf-8: \u{a9} \u{4e2d}")).is_ok()); + for bad in ["bad\tcomment", "del\u{7f}", "nul\u{0}", "esc\u{1b}"] { + let e = parse_deed(&doc(bad)).unwrap_err(); + assert!(e.message.contains("control character"), "{bad:?}: {e}"); + } + } + + #[test] + fn a_top_level_form_needs_at_least_one_item_but_a_nested_clause_may_be_empty() { + let e = parse_deed(&format!("{SPDX}(repo-deed)\n")).unwrap_err(); + assert!(e.message.contains("at least one"), "{e}"); + assert!(parse_deed(&format!("{SPDX}(repo-deed ; only a comment\n)\n")).is_err()); + assert!(parse_deed(&format!("{SPDX}(repo-deed (status))\n")).is_ok()); + } + + #[test] + fn plain_parse_is_the_form_only_but_lexically_strict() { + assert!(super::parse("(repo-deed)").is_ok()); + assert!(super::parse("(repo-deed :a b)\n; no line end").is_err()); + assert!(super::parse("(repo-deed :a b ; tab\there\n)").is_err()); + } + + #[test] + fn the_spdx_header_is_mandatory() { + let body = "(repo-deed :schema-version \"1.0.0\")\n"; + let e = parse_deed(body).unwrap_err(); + assert!(e.message.contains("SPDX"), "{e}"); + assert!(parse_deed(&format!("; just a note\n{body}")).is_err()); + assert!(parse_deed(&format!(";; not spdx\n{body}")).is_err()); + assert!(parse_deed(&format!("\n{SPDX}{body}")).is_err()); + assert!(parse_deed(&format!("{SPDX}{body}")).is_ok()); + assert!(parse_deed(&format!("{SPDX}{SPDX}; more\n{body}")).is_ok()); + assert!(parse_deed(&format!(";; SPDX-License-Identifier: MPL-2.0\r\n{body}")).is_ok()); + assert!(parse_deed(&format!(";; SPDX-\n{body}")).is_err()); + } + + #[test] + fn an_integer_beyond_i64_is_kept_as_its_digits() { + let c = parse_deed(&format!( + "{SPDX}(repo-deed :schema-version \"1.0.0\" :big 123456789012345678901234567890 :neg -99999999999999999999 :n 7)\n" + )) + .unwrap(); + assert_eq!( + c.field("big"), + Some(&Value::BigInt("123456789012345678901234567890".into())) + ); + assert_eq!( + c.field("neg"), + Some(&Value::BigInt("-99999999999999999999".into())) + ); + assert_eq!(c.field("n"), Some(&Value::Int(7))); + assert_eq!( + c.field("big") + .unwrap() + .as_symbol("x", 1) + .unwrap_err() + .message, + "x must be a symbol, found an integer" + ); + } + + #[test] + fn an_error_while_iterating_the_directory_is_an_error_not_a_skipped_entry() { + let ok = |n: &str| Ok((std::ffi::OsString::from(n), PathBuf::from(n))); + let boom = || Err(std::io::Error::other("transient")); + let none: Vec> = vec![ok("a.txt")]; + assert!(pick_chora(Path::new("d"), none.into_iter()) + .unwrap() + .is_none()); + let failed = vec![ok("r_chora.deed"), boom()]; + assert!(matches!( + pick_chora(Path::new("d"), failed.into_iter()), + Err(ChoraError::Io(p, _)) if p == Path::new("d") + )); + } } From aaf04de82d5d557677b4f1d98aa6375d27c289c0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 21:55:28 +0000 Subject: [PATCH 7/8] fix(finishingbot): a (maturity) clause records the project state (DEED-004) rhodibot's canon overlay lists STATE.deed, (status) and (maturity) as the alternatives; DEED-004 fired when only (maturity) was present. Fixtures gain the SPDX header the reader now requires. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDj7XpKyxE4WbsgTsTh --- bots/finishingbot/README.adoc | 2 +- bots/finishingbot/src/analyzers/scm_files.rs | 39 ++++++++++++++++---- 2 files changed, 32 insertions(+), 9 deletions(-) diff --git a/bots/finishingbot/README.adoc b/bots/finishingbot/README.adoc index 194ade60..1cc8b53e 100644 --- a/bots/finishingbot/README.adoc +++ b/bots/finishingbot/README.adoc @@ -49,7 +49,7 @@ the gitbot-fleet shared context layer and makes the final release-readiness dete |No |**Repo Deed** (the `scm_files` report key) -|Reads the one `_chora.deed` at the root (through `deed-reader/`): none is DEED-001 (warning), more than one is DEED-002 (error, D312), unreadable or not a `repo-deed` is DEED-003 (error), no `(status …)` clause and no `.machine_readable/descriptiles/STATE.deed` is DEED-004 (warning). A retired STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC or NEUROSYM `.scm` at the root, under `.machine_readable/` or under `.machine_readable/6scm/` is SCM-006 (warning, "migrate"): it is not validated and is never to be moved +|Reads the one `_chora.deed` at the root (through `deed-reader/`): none is DEED-001 (warning), more than one is DEED-002 (error, D312), unreadable or not a `repo-deed` is DEED-003 (error), no `(status …)` or `(maturity …)` clause and no `.machine_readable/descriptiles/STATE.deed` is DEED-004 (warning). A retired STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC or NEUROSYM `.scm` at the root, under `.machine_readable/` or under `.machine_readable/6scm/` is SCM-006 (warning, "migrate"): it is not validated and is never to be moved |No |**Testing** diff --git a/bots/finishingbot/src/analyzers/scm_files.rs b/bots/finishingbot/src/analyzers/scm_files.rs index b9129ea5..e6011574 100644 --- a/bots/finishingbot/src/analyzers/scm_files.rs +++ b/bots/finishingbot/src/analyzers/scm_files.rs @@ -5,7 +5,7 @@ //! The six descriptive documents that used to be `STATE.scm`, `META.scm`, //! `ECOSYSTEM.scm`, `PLAYBOOK.scm`, `AGENTIC.scm` and `NEUROSYM.scm` are //! clauses of the repository's one `_chora.deed` (owner rulings D312, -//! D313), and the project state is its `(status …)` clause, or +//! D313), and the project state is its `(status …)` or `(maturity …)` clause, or //! `.machine_readable/descriptiles/STATE.deed` once standards' A7 migration //! moves it there (J15). This analyzer therefore reads the deed, through //! `gitbot-deed-reader`, and treats any surviving `.scm` document as legacy: @@ -21,7 +21,7 @@ //! - `DEED-002` (error): more than one chora deed (D312 allows exactly one). //! - `DEED-003` (error): the chora deed cannot be read or parsed, or its //! doc-head is not `repo-deed`. -//! - `DEED-004` (warning): no project state: neither a `(status …)` clause in +//! - `DEED-004` (warning): no project state: neither a `(status …)` nor a `(maturity …)` clause in //! the chora deed nor a `.machine_readable/descriptiles/STATE.deed`. //! - `SCM-006-.scm` (warning): a retired `.scm` document is present. //! @@ -76,13 +76,13 @@ impl Analyzer for ScmFilesAnalyzer { Ok(Some(chora)) => { result.files_checked += 1; debug!("read {}", chora.path.display()); - if !chora.root.has("status") && !has_state_deed { + if !chora.root.has("status") && !chora.root.has("maturity") && !has_state_deed { result.add( Finding::new( "DEED-004", "Project state not recorded", Severity::Warning, - "The chora deed has no (status …) clause and there is no \ + "The chora deed has neither a (status …) nor a (maturity …) clause and there is no \ .machine_readable/descriptiles/STATE.deed, so the project's \ phase is not recorded anywhere a bot can read.", ) @@ -239,16 +239,24 @@ mod tests { #[test] fn an_unparseable_or_wrong_head_deed_is_deed_003_with_a_line() { let d = TempDir::new().unwrap(); - std::fs::write(d.path().join("x_chora.deed"), "(repo-deed\n\n :a").unwrap(); + std::fs::write( + d.path().join("x_chora.deed"), + ";; SPDX-License-Identifier: MPL-2.0\n(repo-deed\n\n :a", + ) + .unwrap(); let r = ScmFilesAnalyzer .analyze(d.path(), &Config::default()) .unwrap(); let f = r.findings.iter().find(|f| f.id == "DEED-003").unwrap(); assert_eq!(f.severity, Severity::Error); - assert_eq!(f.line, Some(3)); + assert_eq!(f.line, Some(4)); let d = TempDir::new().unwrap(); - std::fs::write(d.path().join("x_chora.deed"), "(praxis-deed :a \"b\")").unwrap(); + std::fs::write( + d.path().join("x_chora.deed"), + ";; SPDX-License-Identifier: MPL-2.0\n(praxis-deed :a \"b\")\n", + ) + .unwrap(); assert_eq!(ids(d.path()), vec!["DEED-003".to_string()]); } @@ -257,7 +265,7 @@ mod tests { let d = TempDir::new().unwrap(); std::fs::write( d.path().join("x_chora.deed"), - "(repo-deed :canonical-name \"x\")", + ";; SPDX-License-Identifier: MPL-2.0\n(repo-deed :canonical-name \"x\")\n", ) .unwrap(); assert_eq!(ids(d.path()), vec!["DEED-004".to_string()]); @@ -267,6 +275,21 @@ mod tests { assert!(ids(d.path()).is_empty()); } + #[test] + fn a_maturity_clause_alone_records_the_project_state() { + // rhodibot's canon overlay lists STATE.deed, (status) and (maturity) as + // the three alternatives; none of them is DEED-004. + for clause in ["(maturity :level experimental)", "(status :phase beta)"] { + let d = TempDir::new().unwrap(); + std::fs::write( + d.path().join("x_chora.deed"), + format!(";; SPDX-License-Identifier: MPL-2.0\n(repo-deed :canonical-name \"x\" {clause})\n"), + ) + .unwrap(); + assert!(ids(d.path()).is_empty(), "{clause}"); + } + } + #[test] fn legacy_scm_is_reported_as_migrate_wherever_it_is_and_never_validated() { let d = TempDir::new().unwrap(); From a5a0cdb35ce559fc3d4b5a2f9357e32b7d5ec8ec Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 21:55:29 +0000 Subject: [PATCH 8/8] fix(glambot): MACH-009 names the offending deed for Io and WrongHead errors Only the Parse branch replaced the repository-root location. Fixtures gain the SPDX header the reader now requires. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDj7XpKyxE4WbsgTsTh --- bots/glambot/src/analyzers/machine.rs | 64 +++++++++++++++++++++++---- bots/glambot/tests/integration.rs | 2 +- 2 files changed, 56 insertions(+), 10 deletions(-) diff --git a/bots/glambot/src/analyzers/machine.rs b/bots/glambot/src/analyzers/machine.rs index 463fd4f7..f984c2e4 100644 --- a/bots/glambot/src/analyzers/machine.rs +++ b/bots/glambot/src/analyzers/machine.rs @@ -304,8 +304,15 @@ impl MachineAnalyzer { .with_suggestion( "Check it with standards' `bun 1-formats/deed/tools/deed_lint.js FILE`", ); - if let deed_reader::ChoraError::Parse(p, de) = &e { - f = f.with_file(p.clone()).with_line(de.line); + match &e { + deed_reader::ChoraError::Parse(p, de) => { + f = f.with_file(p.clone()).with_line(de.line); + } + deed_reader::ChoraError::Io(p, _) | deed_reader::ChoraError::WrongHead(p, _) => { + f = f.with_file(p.clone()); + } + // Several deeds: no single offender, the directory stands. + deed_reader::ChoraError::Multiple(_) => {} } result.add(f); } @@ -440,7 +447,7 @@ mod tests { // The repo's machine-readable facts: its chora deed at the root. std::fs::write( dir.path().join("test_chora.deed"), - "(repo-deed :canonical-name \"test\" (status :phase beta))\n", + ";; SPDX-License-Identifier: MPL-2.0\n(repo-deed :canonical-name \"test\" (status :phase beta))\n", ) .unwrap(); // Create robots.txt @@ -516,7 +523,11 @@ mod tests { #[test] fn mach_006_and_007_are_retired_and_a_deed_needs_no_machine_readable_dir() { let dir = TempDir::new().unwrap(); - std::fs::write(dir.path().join("x_chora.deed"), "(repo-deed)").unwrap(); + std::fs::write( + dir.path().join("x_chora.deed"), + ";; SPDX-License-Identifier: MPL-2.0\n(repo-deed :x y)\n", + ) + .unwrap(); let got = ids(dir.path()); for retired in ["MACH-006", "MACH-007", "MACH-008", "MACH-009"] { assert!(!got.contains(&retired.to_string()), "{retired}: {got:?}"); @@ -531,24 +542,59 @@ mod tests { #[test] fn mach_009_for_two_deeds_a_parse_error_or_a_wrong_head() { let two = TempDir::new().unwrap(); - std::fs::write(two.path().join("a_chora.deed"), "(repo-deed)").unwrap(); - std::fs::write(two.path().join("b_chora.deed"), "(repo-deed)").unwrap(); + std::fs::write(two.path().join("a_chora.deed"), "(repo-deed :x y)").unwrap(); + std::fs::write(two.path().join("b_chora.deed"), "(repo-deed :x y)").unwrap(); assert!(ids(two.path()).contains(&"MACH-009".to_string())); let bad = TempDir::new().unwrap(); - std::fs::write(bad.path().join("x_chora.deed"), "(repo-deed\n :a").unwrap(); + std::fs::write( + bad.path().join("x_chora.deed"), + ";; SPDX-License-Identifier: MPL-2.0\n(repo-deed\n :a", + ) + .unwrap(); let r = MachineAnalyzer::default() .analyze(bad.path(), &default_config()) .unwrap(); let f = r.findings.iter().find(|f| f.id == "MACH-009").unwrap(); assert_eq!(f.severity, Severity::Error); - assert_eq!(f.line, Some(2)); + assert_eq!(f.line, Some(3)); + assert_eq!( + f.file.as_deref(), + Some(bad.path().join("x_chora.deed").as_path()) + ); let head = TempDir::new().unwrap(); - std::fs::write(head.path().join("x_chora.deed"), "(praxis-deed)").unwrap(); + std::fs::write( + head.path().join("x_chora.deed"), + ";; SPDX-License-Identifier: MPL-2.0\n(praxis-deed :x y)\n", + ) + .unwrap(); assert!(ids(head.path()).contains(&"MACH-009".to_string())); } + #[test] + fn mach_009_names_the_offending_deed_file_for_every_single_file_error() { + // A wrong doc-head and an unreadable file (not UTF-8) carry the deed path; + // the finding must point at it, not at the repository directory. + let head = TempDir::new().unwrap(); + let deed = head.path().join("x_chora.deed"); + std::fs::write( + &deed, + ";; SPDX-License-Identifier: MPL-2.0\n(praxis-deed :x y)\n", + ) + .unwrap(); + let unreadable = TempDir::new().unwrap(); + let bad = unreadable.path().join("x_chora.deed"); + std::fs::write(&bad, [0xff, 0xfe, 0xfd]).unwrap(); + for (dir, file) in [(head.path(), &deed), (unreadable.path(), &bad)] { + let r = MachineAnalyzer::default() + .analyze(dir, &default_config()) + .unwrap(); + let f = r.findings.iter().find(|f| f.id == "MACH-009").unwrap(); + assert_eq!(f.file.as_deref(), Some(file.as_path()), "{}", f.message); + } + } + const JSONC: &str = "{\n // a comment\n \"url\": \"http://x//y\", /* inline */\n \"list\": [1, 2,],\n}\n"; diff --git a/bots/glambot/tests/integration.rs b/bots/glambot/tests/integration.rs index b2693425..d91c92f1 100644 --- a/bots/glambot/tests/integration.rs +++ b/bots/glambot/tests/integration.rs @@ -38,7 +38,7 @@ fn create_well_formed_repo() -> TempDir { // The repo deed (its machine-readable facts) std::fs::write( path.join("test_chora.deed"), - "(repo-deed :canonical-name \"test\" (status :phase beta))\n", + ";; SPDX-License-Identifier: MPL-2.0\n(repo-deed :canonical-name \"test\" (status :phase beta))\n", ) .unwrap();