diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 3ece9b1..e0cb0e0 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -68,6 +68,7 @@ src/ │ ├── classify.rs # Three-way classification: Mitigable/Unmitigable/Informational │ └── registry.rs # Mitigation lifecycle registry (JSON persistence) ├── a2ml/ # AI manifest protocol (TOML-like format support, 0-AI-MANIFEST.a2ml priority lookup) +├── deed.rs # Minimal DEED reader (standards deed.abnf v2.0.0); used by the classification registry ├── panll/ # PanLL event-chain export ├── storage/ # Filesystem + VerisimDB persistence ├── i18n/ # Multi-language support (ISO 639-1, 10 languages) @@ -193,24 +194,55 @@ All five detection categories shipped in v2.5.0 (2026-04-12): - **InputBoundary (PA024)**: Unchecked CBOR/MessagePack (Rust), JSON.parse without try-catch (JS/Julia) - **MutationGap (PA025)**: No cargo-mutants config (Rust), all-type-only assertions (Julia), no property testing (Elixir) -## User-Classification Registry (2026-04-18) +## User-Classification Registry (2026-04-18; deed-first 2026-11-14) Optional project-local classification file that flips audited findings -to `suppressed = true` after the kanren structural-suppression pass: - -- Path: `/audits/assail-classifications.a2ml` (preferred) or - `/.panic-attack-classifications.a2ml` (fallback). -- Format (A2ML S-expression): +to `suppressed = true` after the kanren structural-suppression pass. +Code: `src/assail/classifications.rs` (registry) and `src/deed.rs` +(a minimal reader of the standards deed grammar, `deed.abnf` v2.0.0). + +- Read order, new input first: + 1. `/audits/assail-classifications_praxis.deed` — a DEED + `praxis-deed`. When it exists it *is* the registry; the A2ML files + below are not read at all. + 2. `/audits/assail-classifications.a2ml` (legacy fallback). + 3. `/.panic-attack-classifications.a2ml` (legacy fallback). +- The deed name ends `_praxis.deed` because the deed grammar dispatches the + head on the file name: a bare `assail-classifications.deed` matches no + dispatch pattern and is not a conforming deed. +- Deed form (`bun /1-formats/deed/tools/deed_lint.js FILE` passes): ``` - (assail-classifications + ;; SPDX-License-Identifier: MPL-2.0 + (praxis-deed + :schema-version "1.0.0" + :canonical-name "-assail-classifications" + :beholding-chora #uuid"0889b37b-defb-831f-973c-e119500db00e" ; estate chora + :profile assail-classifications (classification - (file "crates/foo/src/bar.rs") - (category "UnsafeCode") - (audit "audits/audit-ffi-unsafe.md §1") - (rationale "one-line summary"))) + :file "crates/foo/src/bar.rs" + :category UnsafeCode ; a symbol: a WeakPointCategory variant + :audit "audits/audit-ffi-unsafe.md §1" + :rationale "one-line summary")) ``` -- Public API: `UserClassification`, `load_user_classifications(root)`, - `apply_user_classifications(&mut report, root)` in `src/assail/mod.rs`. + Top level: `:schema-version`, `:canonical-name`, `:beholding-chora` and + `:profile assail-classifications` exactly once each, then any number of + `(classification …)` clauses. Per clause: `:file` and `:category` exactly + once, `:audit` and `:rationale` at most once, nothing else. +- **A malformed deed is an error, never a silent pass.** Any grammar or + profile violation (unknown field, string category, unknown category, + missing `:file`, wrong head, trailing content …) makes + `load_user_classifications` / `apply_user_classifications` return `Err`, + and `analyze()` / `analyze_verbose()` fail with the file and line. A + malformed deed never falls back to the A2ML files. +- The legacy A2ML reader is unchanged and lenient: an entry without a quoted + `file` and `category` is skipped. It stays only until the repositories + that still carry an A2ML registry have moved to the deed. Never create a + new `.a2ml` registry; write the deed. +- Public API: `UserClassification`, `load_user_classifications(root) -> + Result>`, `apply_user_classifications(&mut report, root) -> + Result<()>`, `parse_classification_deed(text, path)`, + `USER_CLASSIFICATIONS_DEED_PATH` in `src/assail/` (re-exported from + `assail`). - Called automatically by `analyze()` / `analyze_verbose()` after `apply_suppression`. @@ -221,9 +253,9 @@ suppressions non-gameable by single-side edits while still letting repositories record honest audits of legitimate-FFI and other genuinely-sound residuals. -**Reference implementation**: `hyperpolymath/007` -`audits/assail-classifications.a2ml` (cross-references -`audits/audit-ffi-unsafe.md §1` for `zig_bridge.rs` UnsafeCode). +**Worked example**: `hyperpolymath/hypatia` +`audits/assail-classifications_praxis.deed` (translated entry for entry +from its former A2ML registry). ## Integration Points diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 4116b0e..c2cf0a0 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -2,6 +2,36 @@ === [Unreleased] +==== Added — the classification registry reads a deed first + +* `+load_user_classifications+` now reads +`+/audits/assail-classifications_praxis.deed+` first: a DEED +`+praxis-deed+` with `+:profile assail-classifications+` and one +`+(classification :file "…" :category :audit "…" :rationale "…")+` +clause per audited finding. When the deed exists, the legacy +`+audits/assail-classifications.a2ml+` and +`+.panic-attack-classifications.a2ml+` are not read; otherwise they are, with +their reader unchanged. Suppression semantics are identical: a finding is +suppressed when its location and category match an entry. The name ends +`+_praxis.deed+` because the standards deed grammar (`+deed.abnf+` v2.0.0) +dispatches a deed's head on its file name, and a bare +`+assail-classifications.deed+` matches no pattern. +* New module `+panic_attack::deed+`: a minimal reader of the deed grammar +(header, form, fields, clauses, every value form, filename dispatch, the +`+:schema-version+` and identity-field side conditions), with line-numbered +errors. + +==== Changed — a malformed deed registry is an error + +* `+load_user_classifications+` returns `+Result>+` +and `+apply_user_classifications+` returns `+Result<()>+` (both were +infallible). A deed registry that breaks the grammar or the profile (unknown +field or clause, a string `+:category+`, an unknown category, a missing +`+:file+`, the wrong head, trailing content, over 4 MiB, not UTF-8) is an +`+Err+` naming the file and line, and `+analyze()+` / `+analyze_verbose()+` +fail with it instead of reading it as an empty registry or falling back to +the A2ML files. Library callers must handle the `+Result+`. + === [2.6.0] - 2026-11-14 Release of the work merged on `+main+` since 2.5.5 (143 commits), including diff --git a/src/assail/analyzer.rs b/src/assail/analyzer.rs index 7c376d6..d375d0c 100644 --- a/src/assail/analyzer.rs +++ b/src/assail/analyzer.rs @@ -1167,12 +1167,15 @@ impl Analyzer { super::apply_suppression(&mut report); // Apply user classifications from a project-local registry - // (`/audits/assail-classifications.a2ml` or + // (`/audits/assail-classifications_praxis.deed`, else the + // legacy `/audits/assail-classifications.a2ml` or // `/.panic-attack-classifications.a2ml`). Entries in the // registry flip matching findings to `suppressed = true` after // the structural suppression pass, letting repositories record - // audited residuals alongside their source audit documents. - super::apply_user_classifications(&mut report, &base); + // audited residuals alongside their source audit documents. A + // malformed deed registry fails the analysis rather than being + // read as an empty one. + super::apply_user_classifications(&mut report, &base)?; Ok(report) } diff --git a/src/assail/classifications.rs b/src/assail/classifications.rs new file mode 100644 index 0000000..14085ce --- /dev/null +++ b/src/assail/classifications.rs @@ -0,0 +1,323 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell + +//! The user-classification registry: audited findings a project records +//! out-of-band from the source under scan. +//! +//! Read order (new input first; the legacy A2ML names are a fallback that the +//! standards A7 migration plan lets a shared reader keep until its callers +//! migrate): +//! +//! 1. `/audits/assail-classifications_praxis.deed`, a DEED praxis +//! document (see [`DEED_PATH`] for its form). When it exists it is the +//! registry, and the A2ML files are not read at all. +//! 2. `/audits/assail-classifications.a2ml` (legacy). +//! 3. `/.panic-attack-classifications.a2ml` (legacy). +//! +//! A deed registry is checked in full: a malformed one is an error, never an +//! empty or partial registry. The legacy A2ML reader keeps its historical +//! lenient behaviour unchanged. + +use crate::deed::{self, Item, Value}; +use crate::types::{AssailReport, WeakPointCategory}; +use anyhow::{anyhow, bail, Context, Result}; +use std::fs; +use std::io::Read; +use std::path::Path; + +/// Repo-relative path of the deed registry. +/// +/// The file name dispatches to the `praxis-deed` head under the standards deed +/// grammar (`deed.abnf` v2.0.0: `_praxis.deed`); a bare +/// `assail-classifications.deed` matches no dispatch pattern and is not a +/// conforming deed name. Form: +/// +/// ```text +/// ;; SPDX-License-Identifier: MPL-2.0 +/// (praxis-deed +/// :schema-version "1.0.0" +/// :canonical-name "example-assail-classifications" +/// :beholding-chora #uuid"0889b37b-defb-831f-973c-e119500db00e" +/// :profile assail-classifications +/// (classification +/// :file "crates/foo/src/bar.rs" +/// :category UnsafeCode +/// :audit "audits/audit-ffi-unsafe.md §1" +/// :rationale "one-line summary")) +/// ``` +/// +/// Top level: `:schema-version`, `:canonical-name` (string), +/// `:beholding-chora` (the estate chora's version 8 id) and +/// `:profile assail-classifications`, each exactly once, and any number of +/// `(classification …)` clauses. In a clause: `:file` (string) and +/// `:category` (a symbol naming a weak-point category) exactly once, +/// `:audit` and `:rationale` (strings) at most once. Nothing else. +pub const DEED_PATH: &str = "audits/assail-classifications_praxis.deed"; + +/// The `:profile` symbol that marks a praxis deed as this registry. +pub const DEED_PROFILE: &str = "assail-classifications"; + +/// Legacy A2ML registry paths, in the order they are tried. +pub const LEGACY_A2ML_PATHS: &[&str] = &[ + "audits/assail-classifications.a2ml", + ".panic-attack-classifications.a2ml", +]; + +/// Hand-edited audit registries rarely exceed a few dozen KiB. The cap stops +/// a malicious or accidental input from exhausting memory during a +/// multi-thousand-repo mass-panic sweep. +const READ_LIMIT: u64 = 4 * 1024 * 1024; + +/// A single classification entry read from a project's registry. When one +/// exists, findings matching `(file, category)` are flipped to +/// `suppressed = true` after the kanren suppression pass runs. +/// +/// The registry pattern lets repositories record "this finding has been +/// audited and is sound" out-of-band from the source file — so the +/// suppression is not gameable by code-only edits (adding a new unsafe +/// block cannot also add its own classification without editing the +/// registry, which is reviewable in the same PR). +#[derive(Debug, Clone)] +pub struct UserClassification { + pub file: String, + pub category: String, +} + +/// Load the project's user classifications (see the module docs for the +/// read order). +/// +/// `Ok(vec![])` when no registry exists. An unreadable, oversized or +/// malformed deed registry is an `Err` naming the file and line. +pub fn load_user_classifications(project_root: &Path) -> Result> { + let deed_path = project_root.join(DEED_PATH); + if deed_path.exists() { + let text = read_capped(&deed_path)?; + return parse_classification_deed(&text, &deed_path) + .with_context(|| format!("malformed classification registry {}", deed_path.display())); + } + for rel in LEGACY_A2ML_PATHS { + let p = project_root.join(rel); + if let Ok(f) = fs::File::open(&p) { + let mut buf = String::new(); + if f.take(READ_LIMIT).read_to_string(&mut buf).is_ok() { + return Ok(parse_legacy_a2ml(&buf)); + } + } + } + Ok(Vec::new()) +} + +/// Read a file whole, refusing one over [`READ_LIMIT`] rather than truncating it. +fn read_capped(path: &Path) -> Result { + let f = fs::File::open(path).with_context(|| format!("cannot open {}", path.display()))?; + let mut buf = Vec::new(); + f.take(READ_LIMIT + 1) + .read_to_end(&mut buf) + .with_context(|| format!("cannot read {}", path.display()))?; + if buf.len() as u64 > READ_LIMIT { + bail!( + "{} exceeds the {} byte registry limit", + path.display(), + READ_LIMIT + ); + } + String::from_utf8(buf).map_err(|_| anyhow!("{} is not valid UTF-8", path.display())) +} + +/// Parse a deed registry (form in [`DEED_PATH`]). `path` supplies the file +/// name for doc-head dispatch. +pub fn parse_classification_deed(text: &str, path: &Path) -> Result> { + let d = deed::parse(text, Some(path)).map_err(|e| anyhow!("{e}"))?; + if d.head != "praxis-deed" { + bail!("expected a praxis-deed, found {}", d.head); + } + let mut seen: Vec<&str> = Vec::new(); + let mut out = Vec::new(); + for item in &d.items { + match item { + Item::Field { + key, value, line, .. + } => { + if seen.contains(&key.as_str()) { + bail!("line {line}: :{key} appears more than once"); + } + seen.push(key); + let ok = match key.as_str() { + "schema-version" => true, // checked by the grammar + "canonical-name" => matches!(value, Value::Str(s) if !s.trim().is_empty()), + "beholding-chora" => matches!(value, Value::Uuid(_) | Value::Uuid8(_)), + "profile" => matches!(value, Value::Symbol(s) if s == DEED_PROFILE), + _ => bail!("line {line}: unknown top-level field :{key}"), + }; + if !ok { + bail!( + "line {line}: invalid :{key} ({}); see the registry form in the panic-attack docs", + value.kind() + ); + } + } + Item::Clause { name, items, line } => { + if name != "classification" { + bail!("line {line}: unexpected clause ({name}); only (classification …) is allowed"); + } + out.push(classification(items, *line)?); + } + } + } + for key in ["canonical-name", "beholding-chora", "profile"] { + if !seen.contains(&key) { + bail!("missing top-level :{key}"); + } + } + Ok(out) +} + +fn classification(items: &[Item], at: usize) -> Result { + let mut file = None; + let mut category = None; + let mut seen: Vec<&str> = Vec::new(); + for item in items { + let Item::Field { + key, value, line, .. + } = item + else { + bail!("line {at}: (classification …) holds fields only, no nested clause"); + }; + if seen.contains(&key.as_str()) { + bail!("line {line}: :{key} appears more than once in (classification …)"); + } + seen.push(key); + match (key.as_str(), value) { + ("file", Value::Str(s)) if !s.trim().is_empty() => file = Some(s.clone()), + ("category", Value::Symbol(s)) => { + let known = serde_json::from_value::(serde_json::Value::String( + s.clone(), + )) + .is_ok(); + if !known { + bail!("line {line}: unknown weak-point category {s}"); + } + category = Some(s.clone()); + } + ("audit" | "rationale", Value::Str(_)) => {} + ("file" | "category" | "audit" | "rationale", v) => bail!( + "line {line}: :{key} cannot be a {}{}", + v.kind(), + if key == "category" { + " (a category is a symbol, e.g. :category UnsafeCode)" + } else { + "" + } + ), + _ => bail!("line {line}: unknown field :{key} in (classification …)"), + } + } + match (file, category) { + (Some(file), Some(category)) => Ok(UserClassification { file, category }), + _ => bail!("line {at}: (classification …) needs :file and :category"), + } +} + +/// The legacy A2ML reader, unchanged: entries lacking a quoted `file` or +/// `category` are skipped, and nothing is reported. +/// +/// ```text +/// (assail-classifications +/// (classification +/// (file "crates/oo7-core/src/zig_bridge.rs") +/// (category "UnsafeCode") +/// (audit "audits/audit-ffi-unsafe.md §1")) +/// ...) +/// ``` +fn parse_legacy_a2ml(content: &str) -> Vec { + // Strip `;;` line comments. + let stripped: String = content + .lines() + .map(|l| match l.find(";;") { + Some(idx) => &l[..idx], + None => l, + }) + .collect::>() + .join("\n"); + + let mut classifications = Vec::new(); + let needle = "(classification"; + let mut rest = stripped.as_str(); + while let Some(start) = rest.find(needle) { + let after_keyword = &rest[start + needle.len()..]; + // Walk characters tracking paren depth to find the matching ')'. + let mut depth: i32 = 1; + let mut end_idx: Option = None; + for (i, c) in after_keyword.char_indices() { + match c { + '(' => depth += 1, + ')' => { + depth -= 1; + if depth == 0 { + end_idx = Some(i); + break; + } + } + _ => {} + } + } + let Some(end) = end_idx else { + break; + }; + let body = &after_keyword[..end]; + let file = extract_classification_field(body, "file"); + let category = extract_classification_field(body, "category"); + if let (Some(f), Some(c)) = (file, category) { + classifications.push(UserClassification { + file: f, + category: c, + }); + } + rest = &after_keyword[end + 1..]; + } + + classifications +} + +fn extract_classification_field(body: &str, field: &str) -> Option { + let marker = format!("({} \"", field); + let idx = body.find(&marker)?; + let after = &body[idx + marker.len()..]; + let end = after.find('"')?; + Some(after[..end].to_string()) +} + +/// Apply user classifications to a report in-place. Findings whose file +/// and category match a registry entry are marked `suppressed = true` and +/// counted toward `report.suppressed_count`. +/// +/// Runs after the kanren-based `apply_suppression` so that the +/// structural suppression rules get first pass and the classification +/// registry covers only the genuinely-audited residuals. +/// +/// # Errors +/// A malformed deed registry (see [`load_user_classifications`]); the report +/// is left unchanged. +pub fn apply_user_classifications(report: &mut AssailReport, project_root: &Path) -> Result<()> { + let classifications = load_user_classifications(project_root)?; + if classifications.is_empty() { + return Ok(()); + } + let mut additional: usize = 0; + for wp in &mut report.weak_points { + if wp.suppressed { + continue; + } + let cat = format!("{:?}", wp.category); + let loc = wp.location.as_deref().unwrap_or(""); + for cl in &classifications { + if cl.category == cat && cl.file == loc { + wp.suppressed = true; + additional += 1; + break; + } + } + } + report.suppressed_count += additional; + Ok(()) +} diff --git a/src/assail/mod.rs b/src/assail/mod.rs index 96a7800..62909be 100644 --- a/src/assail/mod.rs +++ b/src/assail/mod.rs @@ -7,6 +7,7 @@ pub mod analyzer; mod build_inputs; +mod classifications; mod configuration; mod configuration_scripts; pub mod coverage; @@ -26,6 +27,10 @@ use anyhow::Result; use std::path::Path; pub use analyzer::Analyzer; +pub use classifications::{ + apply_user_classifications, load_user_classifications, parse_classification_deed, + UserClassification, DEED_PATH as USER_CLASSIFICATIONS_DEED_PATH, +}; /// Run Assail analysis on a target program pub fn analyze>(target: P) -> Result { @@ -43,7 +48,7 @@ pub fn analyze>(target: P) -> Result { } else { target_ref.parent().unwrap_or(Path::new(".")).to_path_buf() }; - apply_user_classifications(&mut report, &root); + apply_user_classifications(&mut report, &root)?; Ok(report) } @@ -60,7 +65,7 @@ pub fn analyze_verbose>(target: P) -> Result { } else { target_ref.parent().unwrap_or(Path::new(".")).to_path_buf() }; - apply_user_classifications(&mut report, &root); + apply_user_classifications(&mut report, &root)?; let active_count = report .weak_points @@ -195,159 +200,6 @@ pub fn analyze_verbose_browser_extension>(target: P) -> Result/audits/assail-classifications.a2ml`. -/// -/// Empty vector if the file is absent or unreadable. Errors are swallowed by -/// design — the classification registry is optional and a missing file must -/// not break the assail pass. -/// -/// Format (A2ML S-expression): -/// -/// ```text -/// (assail-classifications -/// (classification -/// (file "crates/oo7-core/src/zig_bridge.rs") -/// (category "UnsafeCode") -/// (audit "audits/audit-ffi-unsafe.md §1")) -/// ...) -/// ``` -pub fn load_user_classifications(project_root: &Path) -> Vec { - use std::fs; - let candidate_paths = [ - project_root - .join("audits") - .join("assail-classifications.a2ml"), - project_root.join(".panic-attack-classifications.a2ml"), - ]; - // User-classification a2ml files are hand-edited audit registries. A - // legitimate one rarely exceeds a few dozen KiB. Capping at 4 MiB - // stops a malicious or accidental input from exhausting memory during - // a multi-thousand-repo mass-panic sweep. - use std::io::Read; - const CLASSIFICATIONS_FILE_READ_LIMIT: u64 = 4 * 1024 * 1024; - - let mut content = String::new(); - for p in &candidate_paths { - if let Ok(mut f) = fs::File::open(p) { - let mut buf = String::new(); - if (&mut f) - .take(CLASSIFICATIONS_FILE_READ_LIMIT) - .read_to_string(&mut buf) - .is_ok() - { - content = buf; - break; - } - } - } - if content.is_empty() { - return Vec::new(); - } - - // Strip `;;` line comments. - let stripped: String = content - .lines() - .map(|l| match l.find(";;") { - Some(idx) => &l[..idx], - None => l, - }) - .collect::>() - .join("\n"); - - let mut classifications = Vec::new(); - let needle = "(classification"; - let mut rest = stripped.as_str(); - while let Some(start) = rest.find(needle) { - let after_keyword = &rest[start + needle.len()..]; - // Walk characters tracking paren depth to find the matching ')'. - let mut depth: i32 = 1; - let mut end_idx: Option = None; - for (i, c) in after_keyword.char_indices() { - match c { - '(' => depth += 1, - ')' => { - depth -= 1; - if depth == 0 { - end_idx = Some(i); - break; - } - } - _ => {} - } - } - let Some(end) = end_idx else { - break; - }; - let body = &after_keyword[..end]; - let file = extract_classification_field(body, "file"); - let category = extract_classification_field(body, "category"); - if let (Some(f), Some(c)) = (file, category) { - classifications.push(UserClassification { - file: f, - category: c, - }); - } - rest = &after_keyword[end + 1..]; - } - - classifications -} - -fn extract_classification_field(body: &str, field: &str) -> Option { - let marker = format!("({} \"", field); - let idx = body.find(&marker)?; - let after = &body[idx + marker.len()..]; - let end = after.find('"')?; - Some(after[..end].to_string()) -} - -/// Apply user classifications to a report in-place. Findings whose file -/// and category match an entry in the project's -/// `assail-classifications.a2ml` are marked `suppressed = true` and -/// counted toward `report.suppressed_count`. -/// -/// Runs after the kanren-based `apply_suppression` so that the -/// structural suppression rules get first pass and the classification -/// registry covers only the genuinely-audited residuals. -pub fn apply_user_classifications(report: &mut AssailReport, project_root: &Path) { - let classifications = load_user_classifications(project_root); - if classifications.is_empty() { - return; - } - let mut additional: usize = 0; - for wp in &mut report.weak_points { - if wp.suppressed { - continue; - } - let cat = format!("{:?}", wp.category); - let loc = wp.location.as_deref().unwrap_or(""); - for cl in &classifications { - if cl.category == cat && cl.file == loc { - wp.suppressed = true; - additional += 1; - break; - } - } - } - report.suppressed_count += additional; -} - /// Apply context-aware FP suppression to an assail report in-place. /// /// Runs the full kanren logic engine, collects every `suppressed(Category, Location)` @@ -638,7 +490,7 @@ mod classifications_tests { #[test] fn load_empty_when_no_registry() { let tmp = TempDir::new().unwrap(); - let classifications = load_user_classifications(tmp.path()); + let classifications = load_user_classifications(tmp.path()).unwrap(); assert!( classifications.is_empty(), "Missing registry must yield empty classification list" @@ -658,7 +510,7 @@ mod classifications_tests { (audit "audits/audit-ffi-unsafe.md §1"))) "#, ); - let classifications = load_user_classifications(tmp.path()); + let classifications = load_user_classifications(tmp.path()).unwrap(); assert_eq!(classifications.len(), 1); assert_eq!(classifications[0].file, "crates/oo7-core/src/zig_bridge.rs"); assert_eq!(classifications[0].category, "UnsafeCode"); @@ -680,7 +532,7 @@ mod classifications_tests { (audit "doc2"))) "#, ); - let classifications = load_user_classifications(tmp.path()); + let classifications = load_user_classifications(tmp.path()).unwrap(); assert_eq!(classifications.len(), 2); assert_eq!(classifications[0].file, "a/b.rs"); assert_eq!(classifications[1].category, "PanicPath"); @@ -700,32 +552,20 @@ mod classifications_tests { (audit "doc"))) "#, ); - let classifications = load_user_classifications(tmp.path()); + let classifications = load_user_classifications(tmp.path()).unwrap(); assert_eq!(classifications.len(), 1); assert_eq!(classifications[0].file, "real/path.rs"); } - #[test] - fn apply_flips_matching_finding_to_suppressed() { + /// Two UnsafeCode findings: one at the classified path, one elsewhere. + fn sample_report(root: &Path) -> AssailReport { use crate::types::{ - AssailReport, AttackAxis, Language, ProgramStatistics, Severity, WeakPoint, - WeakPointCategory, + AttackAxis, Language, ProgramStatistics, Severity, WeakPoint, WeakPointCategory, }; - let tmp = TempDir::new().unwrap(); - write_registry( - tmp.path(), - r#"(assail-classifications - (classification - (file "crates/oo7-core/src/zig_bridge.rs") - (category "UnsafeCode") - (audit "audits/audit-ffi-unsafe.md §1"))) -"#, - ); - - let mut report = AssailReport { + AssailReport { coverage: Default::default(), schema_version: "2.5".to_string(), - program_path: tmp.path().to_path_buf(), + program_path: root.to_path_buf(), language: Language::Rust, frameworks: vec![], weak_points: vec![ @@ -768,9 +608,25 @@ mod classifications_tests { taint_matrix: Default::default(), migration_metrics: None, suppressed_count: 0, - }; + } + } + + #[test] + fn apply_flips_matching_finding_to_suppressed() { + let tmp = TempDir::new().unwrap(); + write_registry( + tmp.path(), + r#"(assail-classifications + (classification + (file "crates/oo7-core/src/zig_bridge.rs") + (category "UnsafeCode") + (audit "audits/audit-ffi-unsafe.md §1"))) +"#, + ); - apply_user_classifications(&mut report, tmp.path()); + let mut report = sample_report(tmp.path()); + + apply_user_classifications(&mut report, tmp.path()).unwrap(); assert!( report.weak_points[0].suppressed, @@ -782,6 +638,203 @@ mod classifications_tests { ); assert_eq!(report.suppressed_count, 1); } + + // ---- deed registry (audits/assail-classifications_praxis.deed) ---- + + const DEED_HEAD: &str = r#";; SPDX-License-Identifier: MPL-2.0 +(praxis-deed + :schema-version "1.0.0" + :canonical-name "example-assail-classifications" + :beholding-chora #uuid"0889b37b-defb-831f-973c-e119500db00e" + :profile assail-classifications +"#; + + fn write_deed(dir: &Path, content: &str) { + let audits = dir.join("audits"); + fs::create_dir_all(&audits).unwrap(); + fs::write(dir.join(USER_CLASSIFICATIONS_DEED_PATH), content).unwrap(); + } + + fn deed_with(entries: &str) -> String { + format!("{DEED_HEAD}{entries})\n") + } + + const ZIG_BRIDGE_DEED_ENTRY: &str = r#" ;; FFI boundary, audited + (classification + :file "crates/oo7-core/src/zig_bridge.rs" + :category UnsafeCode + :audit "audits/audit-ffi-unsafe.md §1" + :rationale "every unsafe block's invariant is documented at source")"#; + + #[test] + fn deed_registry_suppresses() { + let tmp = TempDir::new().unwrap(); + write_deed(tmp.path(), &deed_with(ZIG_BRIDGE_DEED_ENTRY)); + let classifications = load_user_classifications(tmp.path()).unwrap(); + assert_eq!(classifications.len(), 1); + assert_eq!(classifications[0].file, "crates/oo7-core/src/zig_bridge.rs"); + assert_eq!(classifications[0].category, "UnsafeCode"); + + let mut report = sample_report(tmp.path()); + apply_user_classifications(&mut report, tmp.path()).unwrap(); + assert!(report.weak_points[0].suppressed); + assert!(!report.weak_points[1].suppressed); + assert_eq!(report.suppressed_count, 1); + } + + #[test] + fn empty_deed_registry_suppresses_nothing() { + let tmp = TempDir::new().unwrap(); + write_deed(tmp.path(), &deed_with("")); + assert!(load_user_classifications(tmp.path()).unwrap().is_empty()); + } + + #[test] + fn deed_wins_over_a2ml() { + let tmp = TempDir::new().unwrap(); + // The deed classifies other/file.rs; the legacy a2ml (and the root + // fallback) classify zig_bridge.rs. Only the deed may be read. + write_deed( + tmp.path(), + &deed_with(" (classification :file \"other/file.rs\" :category UnsafeCode)"), + ); + let legacy = r#"(assail-classifications + (classification + (file "crates/oo7-core/src/zig_bridge.rs") + (category "UnsafeCode"))) +"#; + write_registry(tmp.path(), legacy); + fs::write( + tmp.path().join(".panic-attack-classifications.a2ml"), + legacy, + ) + .unwrap(); + + let classifications = load_user_classifications(tmp.path()).unwrap(); + assert_eq!(classifications.len(), 1); + assert_eq!(classifications[0].file, "other/file.rs"); + + let mut report = sample_report(tmp.path()); + apply_user_classifications(&mut report, tmp.path()).unwrap(); + assert!(!report.weak_points[0].suppressed, "a2ml must not be read"); + assert!(report.weak_points[1].suppressed); + } + + #[test] + fn root_a2ml_fallback_still_works() { + let tmp = TempDir::new().unwrap(); + fs::write( + tmp.path().join(".panic-attack-classifications.a2ml"), + r#"(assail-classifications + (classification (file "a/b.rs") (category "PanicPath"))) +"#, + ) + .unwrap(); + let classifications = load_user_classifications(tmp.path()).unwrap(); + assert_eq!(classifications.len(), 1); + assert_eq!(classifications[0].category, "PanicPath"); + } + + #[test] + fn malformed_deed_is_an_error_and_does_not_fall_back() { + let tmp = TempDir::new().unwrap(); + // A valid a2ml sits beside every malformed deed: falling back to it + // would be a silent pass. + write_registry( + tmp.path(), + r#"(assail-classifications + (classification (file "crates/oo7-core/src/zig_bridge.rs") (category "UnsafeCode"))) +"#, + ); + let cases: &[(&str, String)] = &[ + ("unclosed form", DEED_HEAD.to_string()), + ( + "no SPDX header", + deed_with("").replace(";; SPDX-License-Identifier: MPL-2.0\n", ""), + ), + ( + "A2ML shape", + deed_with(" (classification (file \"a.rs\") (category \"UnsafeCode\"))"), + ), + ( + "string category", + deed_with(" (classification :file \"a.rs\" :category \"UnsafeCode\")"), + ), + ( + "unknown category", + deed_with(" (classification :file \"a.rs\" :category UnsafeKode)"), + ), + ( + "missing :file", + deed_with(" (classification :category UnsafeCode)"), + ), + ( + "empty :file", + deed_with(" (classification :file \"\" :category UnsafeCode)"), + ), + ( + "duplicate :file", + deed_with(" (classification :file \"a.rs\" :file \"b.rs\" :category UnsafeCode)"), + ), + ( + "unknown member", + deed_with(" (classification :file \"a.rs\" :category UnsafeCode :line 3)"), + ), + ( + "unknown clause", + deed_with(" (exemption :file \"a.rs\" :category UnsafeCode)"), + ), + ( + "wrong profile", + deed_with("").replace(":profile assail-classifications", ":profile proof-receipt"), + ), + ( + "no profile", + deed_with("").replace(":profile assail-classifications\n", ""), + ), + ( + "no beholding-chora", + deed_with("").replace( + ":beholding-chora #uuid\"0889b37b-defb-831f-973c-e119500db00e\"\n", + "", + ), + ), + ( + "wrong head", + deed_with("").replace("(praxis-deed", "(repo-deed"), + ), + ("key = value", "[assail]\nfile = \"a.rs\"\n".to_string()), + ("trailing content", format!("{}(extra)\n", deed_with(""))), + ]; + for (what, text) in cases { + write_deed(tmp.path(), text); + assert!( + load_user_classifications(tmp.path()).is_err(), + "{what}: a malformed deed must be an error" + ); + let mut report = sample_report(tmp.path()); + assert!( + apply_user_classifications(&mut report, tmp.path()).is_err(), + "{what}: apply must fail" + ); + assert!( + report.weak_points.iter().all(|wp| !wp.suppressed), + "{what}: nothing may be suppressed" + ); + } + } + + #[test] + fn analyze_fails_on_a_malformed_deed() { + let tmp = TempDir::new().unwrap(); + fs::write(tmp.path().join("main.rs"), "fn main() {}\n").unwrap(); + write_deed(tmp.path(), "(praxis-deed)\n"); + let err = analyze(tmp.path()).unwrap_err(); + assert!( + format!("{err:#}").contains("assail-classifications_praxis.deed"), + "error must name the registry: {err:#}" + ); + } } #[cfg(test)] diff --git a/src/deed.rs b/src/deed.rs new file mode 100644 index 0000000..0259597 --- /dev/null +++ b/src/deed.rs @@ -0,0 +1,787 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell + +//! Minimal reader for DEED documents (hyperpolymath standards, +//! `1-formats/deed/spec/abnf/deed.abnf` v2.0.0). +//! +//! A deed is an S-expression document: one or more `;; SPDX-…` header lines, +//! then a single form `( …)`. A field is +//! `:keyword value`; a clause is `(symbol …)`. The only +//! bracket is `(`, booleans are `#t`/`#f`, enums are symbols, and ids are +//! `#uuid"…"` or `#u8"domain:name"` literals. +//! +//! This reader implements the grammar as written, plus the side conditions a +//! consumer needs to refuse a file it cannot trust: the whole input is +//! consumed, `:schema-version` appears exactly once at the top level, no tab +//! appears anywhere, no line exceeds 998 octets, a comment ends in a line-end, +//! the filename dispatches to the doc-head it carries, and an identity field +//! never carries a `#u5` or a non-version-8 `#uuid`. It does not implement the +//! clause profiles (anchor, edict, descriptile …): a consumer checks the +//! profile it reads on top of the parsed tree. +//! +//! Every error carries the 1-based line it was found on. A malformed deed is +//! always an error, never a partial result. + +use std::fmt; +use std::path::Path; + +/// The doc-heads `deed.abnf` v2.0.0 admits. +pub const DOC_HEADS: &[&str] = &[ + "estate-deed", + "repo-deed", + "estate-atlas-deed", + "praxis-deed", + "contractile-deed", + "descriptile-deed", +]; + +/// Identity fields (CHORA-SPEC 7.1): never a `#u5`, and a `#uuid` there is +/// version 8 (owner ruling Q2). +const IDENTITY_FIELDS: &[&str] = &[ + "repo-uuid", + "estate-uuid", + "forge-uuid", + "beholding-chora", + "of-chora", + "uuid", + "estate", + "base", + "forge", + "repo", +]; + +/// Longest line `deed.abnf` allows, in octets, line-end excluded. +pub const MAX_LINE_OCTETS: usize = 998; + +/// A parse or validation 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 {} + +/// A deed value. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Value { + /// A string, escapes resolved. + Str(String), + Symbol(String), + /// An integer, kept as written (leading zeros are not octal). + Integer(String), + Boolean(bool), + /// `#u5"name"`: the body. + Uuid5(String), + /// `#u8"domain:name"`: the body (the profile C preimage). + Uuid8(String), + /// `#uuid"…"`: the lowercase RFC 9562 id. + Uuid(String), + Quoted(Box), + List(Vec), +} + +impl Value { + /// A short name for the value's kind, for error messages. + pub fn kind(&self) -> &'static str { + match self { + Value::Str(_) => "string", + Value::Symbol(_) => "symbol", + Value::Integer(_) => "integer", + Value::Boolean(_) => "boolean", + Value::Uuid5(_) => "#u5 literal", + Value::Uuid8(_) => "#u8 literal", + Value::Uuid(_) => "#uuid literal", + Value::Quoted(_) => "quoted value", + Value::List(_) => "list", + } + } +} + +/// A member of a form or clause. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Item { + Field { + key: String, + value: Value, + /// The v1.5.0 bang token after the value. + bang: bool, + line: usize, + }, + Clause { + name: String, + items: Vec, + line: usize, + }, +} + +/// A parsed deed: its doc-head and its top-level members. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Deed { + pub head: String, + pub items: Vec, +} + +/// The doc-head a deed file name dispatches to, or `None` when the name +/// matches no dispatch pattern (`deed.abnf` v2.0.0, exact names first). +pub fn head_for_filename(name: &str) -> Option<&'static str> { + const VERBS: &[&str] = &["Intent", "Must", "Trust", "Adjust", "Dust", "Bust"]; + const DESCRIPTILES: &[&str] = &[ + "META", + "STATE", + "ECOSYSTEM", + "AGENTIC", + "NEUROSYM", + "PLAYBOOK", + "CLADE", + "INTENT", + "MUST", + "TRUST", + "ADJUST", + "DUST", + "BUST", + ]; + let stem_ok = |s: &str| { + !s.is_empty() + && s.bytes() + .all(|b| b.is_ascii_alphanumeric() || b"-._".contains(&b)) + }; + if name == "estate_chora.deed" { + return Some("estate-deed"); + } + if name == "ATLAS.deed" { + return Some("estate-atlas-deed"); + } + if name == "0-AI-MANIFEST.deed" { + return Some("repo-deed"); + } + if VERBS.iter().any(|v| name == format!("{v}file.deed")) { + return Some("contractile-deed"); + } + if DESCRIPTILES.iter().any(|d| name == format!("{d}.deed")) { + return Some("descriptile-deed"); + } + if let Some(stem) = name.strip_suffix("_praxis.deed") { + return stem_ok(stem).then_some("praxis-deed"); + } + if let Some(stem) = name.strip_suffix("_chora.deed") { + return stem_ok(stem).then_some("repo-deed"); + } + None +} + +/// Parse deed text. When `filename` is given, its base name must dispatch to +/// the doc-head the text carries. +pub fn parse(text: &str, filename: Option<&Path>) -> Result { + check_lines(text)?; + let mut p = Parser { + s: text.as_bytes(), + i: 0, + line: 1, + }; + p.header()?; + p.opt_sep()?; + let deed = p.form()?; + p.opt_sep()?; + if p.i < p.s.len() { + return Err(p.err("content after the closing ')' of the form")); + } + if let Some(path) = filename { + let base = path + .file_name() + .and_then(|n| n.to_str()) + .unwrap_or_default(); + match head_for_filename(base) { + None => { + return Err(DeedError { + line: 1, + message: format!("filename {base:?} matches no deed dispatch pattern"), + }) + } + Some(want) if want != deed.head => { + return Err(DeedError { + line: 1, + message: format!( + "doc-head/filename mismatch: {base} dispatches to {want} but parses as {}", + deed.head + ), + }) + } + Some(_) => {} + } + } + Ok(deed) +} + +/// No tab anywhere, and no line longer than [`MAX_LINE_OCTETS`]. +fn check_lines(text: &str) -> Result<(), DeedError> { + for (k, raw) in text.split('\n').enumerate() { + if raw.contains('\t') { + return Err(DeedError { + line: k + 1, + message: "HTAB (tab) is an invalid separator anywhere in a deed".into(), + }); + } + let body = raw.strip_suffix('\r').unwrap_or(raw); + if body.len() > MAX_LINE_OCTETS { + return Err(DeedError { + line: k + 1, + message: format!( + "line is {} octets; a deed line is at most {MAX_LINE_OCTETS}", + body.len() + ), + }); + } + } + Ok(()) +} + +fn is_symbol_start(b: u8) -> bool { + b.is_ascii_alphabetic() +} + +fn is_symbol_char(b: u8) -> bool { + b.is_ascii_alphanumeric() || b"./*<>=!?+-_".contains(&b) +} + +/// `text-char`: VCHAR, SP, or any byte of a multi-byte UTF-8 sequence (the +/// input is a `&str`, so the sequence is well formed). +fn is_text_byte(b: u8) -> bool { + (0x20..=0x7e).contains(&b) || b >= 0x80 +} + +struct Parser<'a> { + s: &'a [u8], + i: usize, + line: usize, +} + +impl Parser<'_> { + fn err(&self, message: impl Into) -> DeedError { + DeedError { + line: self.line, + message: message.into(), + } + } + + fn peek(&self) -> Option { + self.s.get(self.i).copied() + } + + fn starts_with(&self, lit: &[u8]) -> bool { + self.s[self.i..].starts_with(lit) + } + + /// Consume a line-end (LF or CRLF), or fail. + fn line_end(&mut self) -> Result<(), DeedError> { + if self.starts_with(b"\r\n") { + self.i += 2; + } else if self.peek() == Some(b'\n') { + self.i += 1; + } else if self.i >= self.s.len() { + return Err(self.err("a comment or header line must end in a line-end")); + } else { + return Err(self.err("control character where a line-end was expected")); + } + self.line += 1; + Ok(()) + } + + /// `header = 1*spdx-line`, `spdx-line = ";;" SP "SPDX-" 1*text-char line-end`. + fn header(&mut self) -> Result<(), DeedError> { + let mut count = 0; + while self.starts_with(b";; SPDX-") { + self.i += b";; SPDX-".len(); + let start = self.i; + while self.peek().is_some_and(is_text_byte) { + self.i += 1; + } + if self.i == start { + return Err(self.err("empty SPDX header line")); + } + self.line_end()?; + count += 1; + } + if count == 0 { + return Err(self.err( + "deed must begin with at least one SPDX header line (';; SPDX-License-Identifier: …')", + )); + } + Ok(()) + } + + /// `[token-sep]`; returns whether anything was consumed. + fn opt_sep(&mut self) -> Result { + let start = self.i; + loop { + match self.peek() { + Some(b' ') => self.i += 1, + Some(b'\n') | Some(b'\r') => self.line_end()?, + Some(b';') => { + self.i += 1; + while self.peek().is_some_and(is_text_byte) { + self.i += 1; + } + self.line_end()?; + } + _ => break, + } + } + Ok(self.i > start) + } + + fn symbol(&mut self) -> Result { + if !self.peek().is_some_and(is_symbol_start) { + return Err( + self.err("expected a symbol (a letter, then letters, digits or ./*<>=!?+-_)") + ); + } + let start = self.i; + while self.peek().is_some_and(is_symbol_char) { + self.i += 1; + } + Ok(String::from_utf8_lossy(&self.s[start..self.i]).into_owned()) + } + + /// After a value, the next byte must begin a separator or close a form. + fn delimited(&self) -> Result<(), DeedError> { + match self.peek() { + None | Some(b' ') | Some(b'\n') | Some(b'\r') | Some(b';') | Some(b')') => Ok(()), + Some(b) => Err(self.err(format!( + "unexpected {:?} directly after a value; a separator or ')' must follow", + b as char + ))), + } + } + + /// `form = "(" doc-head 1*(token-sep (field / clause)) [token-sep] ")"`. + fn form(&mut self) -> Result { + if self.peek() != Some(b'(') { + return Err(self.err("expected '(' to open the deed form")); + } + self.i += 1; + let head_line = self.line; + let head = self.symbol()?; + if !DOC_HEADS.contains(&head.as_str()) { + return Err(DeedError { + line: head_line, + message: format!("unknown doc-head {head:?}"), + }); + } + let items = self.members(&head, 0, false)?; + if items.is_empty() { + return Err(self.err("a deed form carries at least one field or clause")); + } + let versions = items + .iter() + .filter(|it| matches!(it, Item::Field { key, .. } if key == "schema-version")) + .collect::>(); + match versions.as_slice() { + [Item::Field { + value: Value::Str(_), + .. + }] => {} + [Item::Field { line, .. }] => { + return Err(DeedError { + line: *line, + message: ":schema-version must be a string".into(), + }) + } + [] => return Err(self.err("missing :schema-version (required exactly once)")), + _ => return Err(self.err(":schema-version appears more than once")), + } + Ok(Deed { head, items }) + } + + /// Members of a form or clause up to and including its closing ")". + /// `in_top_rule` is true only for the members of a top-level `(rule …)` + /// clause, the one place a bang may appear. + fn members( + &mut self, + head: &str, + depth: usize, + in_top_rule: bool, + ) -> Result, DeedError> { + let mut items = Vec::new(); + loop { + let had_sep = self.opt_sep()?; + match self.peek() { + Some(b')') => { + self.i += 1; + return Ok(items); + } + None => return Err(self.err("unexpected end of input: unclosed '('")), + Some(_) if !had_sep => { + return Err(self.err("a separator is required before each field or clause")) + } + Some(b':') => items.push(self.field(head, in_top_rule)?), + Some(b'(') => { + self.i += 1; + let line = self.line; + let name = self.symbol()?; + let inner = self.members(head, depth + 1, depth == 0 && name == "rule")?; + items.push(Item::Clause { + name, + items: inner, + line, + }); + self.delimited()?; + } + Some(b) => { + return Err(self.err(format!( + "expected a :field, a (clause …) or ')', found {:?}", + b as char + ))) + } + } + } + } + + /// `field = keyword token-sep value [token-sep bang]`. + fn field(&mut self, head: &str, in_top_rule: bool) -> Result { + let line = self.line; + self.i += 1; // ':' + let key = self.symbol()?; + if !self.opt_sep()? { + return Err(self.err(format!( + "a separator is required between :{key} and its value (there is no '=' form)" + ))); + } + let value = self.value()?; + // "Never true, false, yes, no": they lex as symbols, so the ban is a + // value-level rule (DEED-GRAMMAR-SPEC; deed_lint does the same). + if matches!(&value, Value::Symbol(s) if ["true", "false", "yes", "no"].contains(&s.as_str())) + { + return Err(DeedError { + line, + message: format!("boolean meaning must use #t/#f, not the bare symbol in :{key}"), + }); + } + if IDENTITY_FIELDS.contains(&key.as_str()) { + match &value { + Value::Uuid5(_) => { + return Err(DeedError { + line, + message: format!( + "identity field :{key} carries a #u5 literal; write #uuid\"\" or #u8\"domain:name\"" + ), + }) + } + Value::Uuid(id) if id.as_bytes()[14] != b'8' => { + return Err(DeedError { + line, + message: format!("identity field :{key} carries a non-version-8 id"), + }) + } + _ => {} + } + } + // An optional bang: a lone "!" after a separator. + let save = (self.i, self.line); + let mut bang = false; + if self.opt_sep()? && self.peek() == Some(b'!') { + let next = self.s.get(self.i + 1).copied(); + if !next.is_some_and(is_symbol_char) { + self.i += 1; + self.delimited()?; + bang = true; + } + } + if !bang { + (self.i, self.line) = save; + } + // The bang is legal only on the :id of a top-level (rule …) clause + // of a contractile-deed (deed.abnf v1.5.0). + if bang && !(head == "contractile-deed" && in_top_rule && key == "id") { + return Err(DeedError { + line, + message: "the bang '!' is allowed only on the :id of a top-level (rule …) clause of a contractile-deed".into(), + }); + } + Ok(Item::Field { + key, + value, + bang, + line, + }) + } + + fn value(&mut self) -> Result { + let v = match self.peek() { + Some(b'"') => Value::Str(self.string()?), + Some(b'#') => self.hash_form()?, + Some(b'\'') => { + self.i += 1; + match self.peek() { + Some(b'(') => Value::Quoted(Box::new(self.list()?)), + Some(b) if is_symbol_start(b) => { + Value::Quoted(Box::new(Value::Symbol(self.symbol()?))) + } + _ => return Err(self.err( + "only a symbol or a list may be quoted, with nothing between \"'\" and it", + )), + } + } + Some(b'(') => self.list()?, + Some(b'-') | Some(b'0'..=b'9') => { + let start = self.i; + if self.peek() == Some(b'-') { + self.i += 1; + } + let digits = self.i; + while self.peek().is_some_and(|b| b.is_ascii_digit()) { + self.i += 1; + } + if self.i == digits { + return Err(self.err("'-' must be followed by digits")); + } + Value::Integer(String::from_utf8_lossy(&self.s[start..self.i]).into_owned()) + } + Some(b) if is_symbol_start(b) => Value::Symbol(self.symbol()?), + Some(b) => return Err(self.err(format!("expected a value, found {:?}", b as char))), + None => return Err(self.err("unexpected end of input: expected a value")), + }; + self.delimited()?; + Ok(v) + } + + /// `list = "(" [token-sep] [value *(token-sep value)] [token-sep] ")"`. + fn list(&mut self) -> Result { + self.i += 1; // '(' + let mut out = Vec::new(); + loop { + let had_sep = self.opt_sep()?; + match self.peek() { + Some(b')') => { + self.i += 1; + return Ok(Value::List(out)); + } + None => return Err(self.err("unexpected end of input: unclosed list")), + Some(_) if !out.is_empty() && !had_sep => { + return Err(self.err("list values must be separated")) + } + Some(b':') => { + return Err( + self.err("a list holds values only; a :keyword cannot appear in one") + ) + } + Some(_) => out.push(self.value()?), + } + } + } + + /// A string with exactly four escapes: `\"`, `\\`, `\n`, `\t`. + fn string(&mut self) -> Result { + self.i += 1; // opening quote + let mut out: Vec = Vec::new(); + loop { + match self.peek() { + None => return Err(self.err("unterminated string")), + Some(b'"') => { + self.i += 1; + return Ok(String::from_utf8_lossy(&out).into_owned()); + } + Some(b'\\') => { + let esc = + match self.s.get(self.i + 1) { + Some(b'"') => b'"', + Some(b'\\') => b'\\', + Some(b'n') => b'\n', + Some(b't') => b'\t', + _ => return Err(self.err( + "invalid escape; a deed string has exactly \\\" \\\\ \\n and \\t", + )), + }; + out.push(esc); + self.i += 2; + } + Some(b) if is_text_byte(b) => { + out.push(b); + self.i += 1; + } + Some(_) => { + return Err( + self.err("control character or raw line break inside a string (use \\n)") + ) + } + } + } + } + + fn hash_form(&mut self) -> Result { + if self.starts_with(b"#uuid") { + self.i += 5; + if self.peek() != Some(b'"') { + return Err(self.err("#uuid must be followed immediately by a string")); + } + let id = self.string()?; + if !valid_uuid_hex(&id) { + return Err(self.err(format!( + "#uuid\"{id}\" is not a lowercase RFC 9562 id of version 5 or 8 and variant 10" + ))); + } + return Ok(Value::Uuid(id)); + } + if self.starts_with(b"#u5") || self.starts_with(b"#u8") { + let eight = self.s[self.i + 2] == b'8'; + self.i += 3; + if self.peek() != Some(b'"') { + return Err(self.err("#u5/#u8 must be followed immediately by a string")); + } + let body = self.string()?; + if eight { + let domain = body.split(':').next().unwrap_or_default(); + if !body.contains(':') + || domain.is_empty() + || !domain.bytes().all(|b| (0x21..=0x7e).contains(&b)) + { + return Err(self.err(format!( + "#u8\"{body}\" must be domain:name with a non-empty printable-ASCII domain" + ))); + } + return Ok(Value::Uuid8(body)); + } + return Ok(Value::Uuid5(body)); + } + if self.starts_with(b"#t") || self.starts_with(b"#f") { + let b = self.s[self.i + 1] == b't'; + self.i += 2; + return Ok(Value::Boolean(b)); + } + Err(self.err("unknown #-form; expected #t, #f, #uuid\"…\", #u8\"…\" or #u5\"…\"")) + } +} + +/// `uuid-hex`: 8-4-4-4-12 lowercase hex, version 5 or 8, variant 10. +fn valid_uuid_hex(s: &str) -> bool { + let b = s.as_bytes(); + if b.len() != 36 { + return false; + } + for (k, &c) in b.iter().enumerate() { + let ok = match k { + 8 | 13 | 18 | 23 => c == b'-', + 14 => c == b'5' || c == b'8', + 19 => matches!(c, b'8' | b'9' | b'a' | b'b'), + _ => c.is_ascii_digit() || (b'a'..=b'f').contains(&c), + }; + if !ok { + return false; + } + } + true +} + +#[cfg(test)] +mod tests { + use super::*; + + const H: &str = ";; SPDX-License-Identifier: MPL-2.0\n"; + + fn ok(body: &str) -> Deed { + parse(&format!("{H}{body}"), None).unwrap_or_else(|e| panic!("{body}: {e}")) + } + + fn bad(body: &str) -> DeedError { + match parse(&format!("{H}{body}"), None) { + Ok(d) => panic!("{body} parsed as {d:?}"), + Err(e) => e, + } + } + + #[test] + fn parses_fields_clauses_and_values() { + let d = ok("(praxis-deed\n :schema-version \"1.0.0\" ; c\n :n -007 :b #t :q 'sym :l (1 \"a\" (x))\n :id #uuid\"0889b37b-defb-831f-973c-e119500db00e\"\n :c #u8\"gv-clade-index:github.com/o/x\"\n (rule :x Type.Software.Lib))\n"); + assert_eq!(d.head, "praxis-deed"); + assert_eq!(d.items.len(), 8); + assert!( + matches!(&d.items[7], Item::Clause { name, items, line: 7 } if name == "rule" && items.len() == 1) + ); + } + + #[test] + fn string_escapes() { + let d = ok("(praxis-deed :schema-version \"1\" :s \"a\\\"b\\\\c\\nd\\te §\")\n"); + assert!( + matches!(&d.items[1], Item::Field { value: Value::Str(s), .. } if s == "a\"b\\c\nd\te §") + ); + } + + #[test] + fn refuses_what_the_grammar_refuses() { + for body in [ + "(praxis-deed :schema-version = \"1\")", + "(praxis-deed :canonical-name \"x\")", + "(praxis-deed :schema-version \"1\" :schema-version \"2\")", + "(praxis-deed :schema-version 1)", + "(not-a-head :schema-version \"1\")", + "(praxis-deed :schema-version \"1\"", + "(praxis-deed :schema-version \"1\") x", + "(praxis-deed :schema-version \"1\")(x)", + "(praxis-deed :schema-version \"1\" :b #T)", + "(praxis-deed :schema-version \"1\" :s \"a\\rb\")", + "(praxis-deed :schema-version \"1\" :s \"a\nb\")", + "(praxis-deed :schema-version \"1\" :q ' sym)", + "(praxis-deed :schema-version \"1\" :q '1)", + "(praxis-deed :schema-version \"1\" :x \"a\"\"b\")", + "(praxis-deed :schema-version \"1\"(c :x 1))", + "(praxis-deed :schema-version \"1\" :id \"x\" !)", + "(contractile-deed :schema-version \"1\" (edict :id \"x\" !))", + "(contractile-deed :schema-version \"1\" (rule (rule :id \"x\" !)))", + "(praxis-deed :schema-version \"1\" :b true)", + "(praxis-deed :schema-version \"1\" (c :b no))", + "(praxis-deed :schema-version \"1\" :u #uuid\"0889B37B-defb-831f-973c-e119500db00e\")", + "(praxis-deed :schema-version \"1\" :u #uuid\"0889b37b-defb-431f-973c-e119500db00e\")", + "(praxis-deed :schema-version \"1\" :u #u8\"nodomain\")", + "(praxis-deed :schema-version \"1\" :beholding-chora #u5\"x\")", + "(praxis-deed :schema-version \"1\" :repo-uuid #uuid\"0889b37b-defb-531f-973c-e119500db00e\")", + "(praxis-deed :schema-version \"1\" :l (:k 1))", + "(praxis-deed :schema-version \"1\") ; no line-end after this comment", + ] { + bad(body); + } + } + + #[test] + fn refuses_a_missing_header_tabs_and_long_lines() { + assert!(parse("(praxis-deed :schema-version \"1\")\n", None).is_err()); + assert!(parse(&format!("{H}(praxis-deed\t:schema-version \"1\")\n"), None).is_err()); + let long = format!( + "{H}(praxis-deed :schema-version \"1\" :s \"{}\")\n", + "a".repeat(1000) + ); + assert_eq!(parse(&long, None).unwrap_err().line, 2); + } + + #[test] + fn bang_on_a_top_level_rule_id() { + let d = ok("(contractile-deed :schema-version \"1\" (rule :id \"r\" ! :x 1))\n"); + assert!(matches!(&d.items[1], Item::Clause { items, .. } + if matches!(&items[0], Item::Field { bang: true, .. }))); + } + + #[test] + fn error_lines_are_reported() { + let e = bad("(praxis-deed\n :schema-version \"1\"\n :x #q)\n"); + assert_eq!(e.line, 4); + } + + #[test] + fn filename_dispatch() { + let text = format!("{H}(praxis-deed :schema-version \"1\")\n"); + assert!(parse(&text, Some(Path::new("a/x_praxis.deed"))).is_ok()); + assert!(parse(&text, Some(Path::new("a/x_chora.deed"))).is_err()); + assert!(parse(&text, Some(Path::new("a/x.deed"))).is_err()); + assert_eq!(head_for_filename("estate_chora.deed"), Some("estate-deed")); + assert_eq!(head_for_filename("Mustfile.deed"), Some("contractile-deed")); + assert_eq!(head_for_filename("MUST.deed"), Some("descriptile-deed")); + assert_eq!(head_for_filename("ANCHOR.deed"), None); + assert_eq!(head_for_filename("_praxis.deed"), None); + } +} diff --git a/src/lib.rs b/src/lib.rs index 5bfc4f0..6c92212 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -31,6 +31,7 @@ pub mod axial; pub mod bridge; pub mod campaign; pub mod comment_marker; +pub mod deed; pub mod ffi_kind; pub mod i18n; pub mod jit_context;