cordance_advise/lib.rs
1//! Deterministic doctrine checks. Every finding cites a specific doctrine
2//! file path. No prose interpretation; no LLM.
3//!
4//! Each rule targets a specific doctrine principle
5//! (`doctrine/principles/<name>.md`) and includes that path as the
6//! `doctrine_anchor` on every finding it emits. Severity is one of
7//! `Info` / `Warning` / `Error`, with a concrete `remediation` string.
8//!
9//! # Golden path
10//!
11//! ```no_run
12//! use cordance_core::advise::AdviseReport;
13//! use cordance_core::lock::SourceLock;
14//! use cordance_core::pack::{CordancePack, PackTargets, ProjectIdentity};
15//! use cordance_core::schema;
16//!
17//! let pack = CordancePack {
18//! schema: schema::CORDANCE_PACK_V1.into(),
19//! project: ProjectIdentity {
20//! name: "my-project".into(),
21//! repo_root: ".".into(),
22//! kind: "rust-workspace".into(),
23//! host_os: "linux".into(),
24//! axiom_pin: None,
25//! },
26//! sources: vec![],
27//! doctrine_pins: vec![],
28//! targets: PackTargets::all(),
29//! outputs: vec![],
30//! source_lock: SourceLock::empty(),
31//! advise: AdviseReport::empty(),
32//! residual_risk: vec![],
33//! };
34//!
35//! let report = cordance_advise::run_all(&pack).expect("advise");
36//! for finding in &report.findings {
37//! println!(
38//! "[{:?}] {} — see {}",
39//! finding.severity, finding.summary, finding.doctrine_anchor,
40//! );
41//! }
42//! ```
43
44#![forbid(unsafe_code)]
45#![deny(clippy::unwrap_used, clippy::expect_used)]
46
47use cordance_core::advise::AdviseReport;
48use cordance_core::pack::CordancePack;
49
50pub mod rules;
51
52#[derive(Clone, Debug, thiserror::Error)]
53pub enum AdviseError {
54 #[error("rule error: {0}")]
55 Rule(String),
56}
57
58/// Run all deterministic rules over a pack and return the consolidated report.
59#[allow(clippy::missing_errors_doc)]
60pub fn run_all(pack: &CordancePack) -> Result<AdviseReport, AdviseError> {
61 let all = rules::all_rules();
62 let mut findings = Vec::new();
63 for rule in &all {
64 findings.extend(rule.check(pack));
65 }
66 Ok(AdviseReport {
67 schema: cordance_core::schema::CORDANCE_ADVISE_REPORT_V1.into(),
68 findings,
69 })
70}