use std::collections::{BTreeMap, HashMap, HashSet};
use std::fmt::Write as _;
use std::path::{Path, PathBuf};
use anyhow::{Result, bail};
use crate::DocSpec;
use crate::baseline::{Baseline, BaselineEntry, GapKey, GapKind};
use crate::config::RepositoryConfig;
use crate::docs::{Requirement, parse_doc};
use crate::evidence_mark::EvidenceMark;
use crate::scan::{Anchors, scan};
#[derive(Debug, Clone)]
pub struct Finding {
pub file: String,
pub line: usize,
pub message: String,
}
pub struct Report {
pub errors: Vec<Finding>,
pub warnings: Vec<Finding>,
pub summary: String,
}
pub struct BaselineChange {
pub path: PathBuf,
pub entries: usize,
pub removed: usize,
}
#[derive(Default)]
struct BaselineStats {
known: usize,
resolved: usize,
new: usize,
}
struct TraceabilityGap {
area: String,
findings: Vec<Finding>,
}
struct Analysis {
errors: Vec<Finding>,
warnings: Vec<Finding>,
requirements: Vec<Requirement>,
gaps: BTreeMap<GapKey, TraceabilityGap>,
stats: BTreeMap<String, AreaStats>,
anchors: Anchors,
}
impl Report {
pub fn passed(&self) -> bool {
self.errors.is_empty()
}
pub fn print(&self, warning_limit: usize) -> bool {
print!("{}", self.summary);
if !self.warnings.is_empty() {
println!("\nwarnings ({}):", self.warnings.len());
print_grouped(&self.warnings, warning_limit, false);
}
if !self.errors.is_empty() {
eprintln!("\nerrors ({}):", self.errors.len());
print_grouped(&self.errors, usize::MAX, true);
return false;
}
println!("\ncargo shallguard: OK");
true
}
}
fn print_grouped(findings: &[Finding], limit: usize, to_stderr: bool) {
let mut by_file: BTreeMap<&str, Vec<&Finding>> = BTreeMap::new();
for finding in findings {
by_file.entry(&finding.file).or_default().push(finding);
}
let mut printed = 0usize;
let out = |line: String| {
if to_stderr {
eprintln!("{line}");
} else {
println!("{line}");
}
};
for (file, mut group) in by_file {
if printed >= limit {
break;
}
group.sort_by_key(|f| f.line);
out(format!(" {file}:"));
for finding in group {
if printed >= limit {
break;
}
out(format!(" {:>5} {}", finding.line, finding.message));
printed += 1;
}
}
let rest = findings.len().saturating_sub(printed);
if rest > 0 {
out(format!(" ... and {rest} more"));
}
}
pub fn run(root: &Path, docs: &[DocSpec], config: &RepositoryConfig) -> Result<Report> {
let mut analysis = analyze(root, docs, config)?;
let baseline = Baseline::load(root, &config.baseline)?;
let baseline_stats = apply_baseline(
&mut analysis,
&baseline,
covers_configured_documents(docs, config),
true,
config,
);
let summary = render_summary(&analysis.stats, &analysis.anchors, &baseline_stats, config);
Ok(Report {
errors: analysis.errors,
warnings: analysis.warnings,
summary,
})
}
pub fn initialize_baseline(
root: &Path,
docs: &[DocSpec],
config: &RepositoryConfig,
) -> Result<BaselineChange> {
require_complete_scope(docs, config, "initialize")?;
let analysis = analyze(root, docs, config)?;
ensure_no_non_gap_errors(&analysis, "initialize")?;
if let Some((key, _)) = analysis
.gaps
.iter()
.find(|(key, gap)| gap_is_hard(key.kind, &gap.area, config))
{
bail!(
"cannot initialize baseline: hard-area gap {} ({}) must be fixed",
key.requirement,
key.kind
);
}
let entries = analysis
.gaps
.keys()
.map(|key| BaselineEntry {
requirement: key.requirement.clone(),
kind: key.kind,
})
.collect();
let baseline = Baseline::from_entries(entries);
let count = baseline.gaps.len();
let path = baseline.create_new(root, &config.baseline)?;
Ok(BaselineChange {
path,
entries: count,
removed: 0,
})
}
pub fn prune_baseline(
root: &Path,
docs: &[DocSpec],
config: &RepositoryConfig,
) -> Result<BaselineChange> {
require_complete_scope(docs, config, "prune")?;
let mut analysis = analyze(root, docs, config)?;
let mut baseline = Baseline::load(root, &config.baseline)?;
let before = baseline.gaps.len();
apply_baseline(&mut analysis, &baseline, true, false, config);
ensure_no_non_gap_errors(&analysis, "prune")?;
let current: HashSet<GapKey> = analysis.gaps.keys().cloned().collect();
let retired: HashSet<&str> = analysis
.requirements
.iter()
.filter(|req| req.retired)
.map(|req| req.id.as_str())
.collect();
baseline.gaps.retain(|entry| {
current.contains(&entry.key()) && !retired.contains(entry.requirement.as_str())
});
let removed = before - baseline.gaps.len();
let path = if removed == 0 {
root.join(&config.baseline)
} else {
baseline.write_pruned(root, &config.baseline)?
};
Ok(BaselineChange {
path,
entries: baseline.gaps.len(),
removed,
})
}
#[shallguard::enforces(
"REQ-SPEC-001",
"REQ-SPEC-003",
"REQ-SPEC-004",
"REQ-TRACE-005",
"REQ-TRACE-006",
"REQ-TRACE-007",
"REQ-PORT-004",
"REQ-PORT-008"
)]
fn analyze(root: &Path, docs: &[DocSpec], config: &RepositoryConfig) -> Result<Analysis> {
let mut errors = Vec::new();
let mut warnings = Vec::new();
let mut requirements: Vec<Requirement> = Vec::new();
let mut path_spans: Vec<(String, usize, PathBuf)> = Vec::new();
for spec in docs {
let doc = parse_doc(root, spec)?;
if doc.requirements.len() < config.minimum_requirements {
errors.push(Finding {
file: spec.path.clone(),
line: 1,
message: format!(
"parsed only {} requirements - document format drifted \
from the configured minimum of {}",
doc.requirements.len(),
config.minimum_requirements
),
});
}
path_spans.extend(
doc.path_spans
.into_iter()
.map(|(l, p)| (spec.path.clone(), l, p)),
);
requirements.extend(doc.requirements);
}
let mut unknown_areas = HashSet::new();
for requirement in &requirements {
if !config.areas.contains_key(&requirement.area)
&& unknown_areas.insert(requirement.area.clone())
{
errors.push(Finding {
file: requirement.doc.clone(),
line: requirement.line,
message: format!(
"requirement area {} has no [areas.{}] policy in shallguard.toml",
requirement.area, requirement.area
),
});
}
}
let scan_roots = docs
.iter()
.flat_map(DocSpec::scan_roots)
.collect::<std::collections::BTreeSet<_>>()
.into_iter()
.collect::<Vec<_>>();
let mut by_id: HashMap<&str, &Requirement> = HashMap::new();
for req in &requirements {
if let Some(prev) = by_id.insert(&req.id, req) {
errors.push(Finding {
file: req.doc.clone(),
line: req.line,
message: format!(
"duplicate requirement ID {} (also at {}:{})",
req.id, prev.doc, prev.line
),
});
}
}
let mut seen_spans = HashSet::new();
for (doc, line, path) in &path_spans {
if config.allow_missing_paths.contains(path) {
continue;
}
if !root.join(path).exists() && seen_spans.insert(path.clone()) {
errors.push(Finding {
file: doc.clone(),
line: *line,
message: format!("cited path does not exist: {}", path.display()),
});
}
}
let scan_root_refs: Vec<&str> = scan_roots.iter().map(String::as_str).collect();
let anchors = scan(root, &scan_root_refs)?;
let mut unknown: BTreeMap<&str, &(PathBuf, usize)> = BTreeMap::new();
for (id, sites) in &anchors.references {
let site = sites.first().expect("BUG: reference entry without site");
match by_id.get(id.as_str()) {
None => {
unknown.insert(id, site);
}
Some(req) if req.retired => warnings.push(Finding {
file: site.0.display().to_string(),
line: site.1,
message: format!("references retired requirement {id}"),
}),
Some(_) => {}
}
}
for (id, (file, line)) in unknown {
errors.push(Finding {
file: file.display().to_string(),
line: *line,
message: format!("unknown requirement ID {id} (not defined in any document)"),
});
}
for invalid in &anchors.invalid {
warnings.push(Finding {
file: invalid.file.display().to_string(),
line: invalid.line,
message: invalid.message.clone(),
});
}
let mut enforcing_files: HashMap<&str, HashSet<&Path>> = HashMap::new();
for anchor in &anchors.enforcement {
for id in &anchor.ids {
enforcing_files
.entry(id.as_str())
.or_default()
.insert(anchor.file.as_path());
}
}
let mut stale_verified: BTreeMap<&str, (&Path, usize)> = BTreeMap::new();
for anchor in &anchors.verification {
for id in &anchor.ids {
if let Some(req) = by_id.get(id.as_str())
&& !req.automated
&& !req.retired
{
stale_verified
.entry(id.as_str())
.or_insert((anchor.file.as_path(), anchor.line));
}
}
}
for (id, (file, line)) in stale_verified {
warnings.push(Finding {
file: file.display().to_string(),
line,
message: format!(
"test anchor cites {id}, which does not claim {} automated \
evidence - the document or the anchor is stale",
EvidenceMark::Test.keyword()
),
});
}
let mut stats: BTreeMap<String, AreaStats> = BTreeMap::new();
let mut gaps: BTreeMap<GapKey, TraceabilityGap> = BTreeMap::new();
let verified_ids: HashSet<&str> = anchors.verified_ids().collect();
for req in &requirements {
let stat = stats.entry(req.area.clone()).or_default();
stat.total += 1;
if req.retired {
stat.retired += 1;
continue;
}
if req.automated {
stat.automated += 1;
} else if req.e2e {
stat.e2e += 1;
} else if req.pending {
stat.pending += 1;
} else if req.review_only {
stat.review_only += 1;
}
if !req.not_implemented && !req.enforced_paths.is_empty() {
stat.anchorable += 1;
let files = enforcing_files.get(req.id.as_str());
let missing = req
.enforced_paths
.iter()
.filter(|enforced| !enforced_path_has_anchor(enforced, files))
.map(|path| path.display().to_string())
.collect::<Vec<_>>();
if missing.is_empty() {
stat.anchored += 1;
} else {
let finding = Finding {
file: req.doc.to_string(),
line: req.line,
message: format!(
"{} \"{}\" - no enforcement anchor (#[shallguard::enforces] or \
shallguard::enforces_here!) in documented file(s): {}",
req.id,
req.title,
missing.join(", ")
),
};
record_gap(&mut gaps, req, GapKind::EnforcementAnchor, finding);
}
}
if req.automated {
if verified_ids.contains(req.id.as_str()) {
stat.test_anchored += 1;
} else {
record_gap(
&mut gaps,
req,
GapKind::VerificationAnchor,
Finding {
file: req.doc.to_string(),
line: req.line,
message: format!(
"{} \"{}\" - claims automated-test evidence but no \
test anchor verifies it",
req.id, req.title
),
},
);
}
if req.evidence.is_empty() {
record_gap(
&mut gaps,
req,
GapKind::EvidenceCitation,
Finding {
file: req.doc.to_string(),
line: req.line,
message: format!(
"{} \"{}\" - claims {} but cites no concrete test \
file in its Verified line",
req.id,
req.title,
EvidenceMark::Test.keyword()
),
},
);
}
for evidence in &req.evidence {
let resolved = anchors.verification.iter().any(|anchor| {
anchor.ids.contains(&req.id)
&& anchor.file == evidence.file
&& evidence
.test_fn
.as_ref()
.is_none_or(|name| *name == anchor.test_fn)
});
if !resolved {
let cited = match &evidence.test_fn {
Some(name) => format!("{} ({name})", evidence.file.display()),
None => evidence.file.display().to_string(),
};
record_gap(
&mut gaps,
req,
GapKind::EvidenceCitation,
Finding {
file: req.doc.to_string(),
line: req.line,
message: format!(
"{} - cited evidence {cited} does not resolve to \
a #[shallguard::verifies] anchor for this requirement",
req.id
),
},
);
} else if evidence.test_fn.is_none() {
warnings.push(Finding {
file: req.doc.to_string(),
line: req.line,
message: format!(
"{} - evidence cites {} but names no test function",
req.id,
evidence.file.display()
),
});
}
}
}
}
for anchor in &anchors.verification {
if anchor.ids.len() >= config.verify_outlier_threshold {
warnings.push(Finding {
file: anchor.file.display().to_string(),
line: anchor.line,
message: format!(
"`{}` claims {} requirements - review whether the claim \
is that broad",
anchor.test_fn,
anchor.ids.len()
),
});
}
}
Ok(Analysis {
errors,
warnings,
requirements,
gaps,
stats,
anchors,
})
}
fn enforced_path_has_anchor(enforced: &Path, files: Option<&HashSet<&Path>>) -> bool {
files.is_some_and(|files| {
files.iter().any(|file| {
if enforced.to_string_lossy().ends_with('/') {
file.starts_with(enforced)
} else {
*file == enforced
}
})
})
}
#[shallguard::enforces("REQ-BASE-002")]
fn record_gap(
gaps: &mut BTreeMap<GapKey, TraceabilityGap>,
req: &Requirement,
kind: GapKind,
finding: Finding,
) {
gaps.entry(GapKey::new(&req.id, kind))
.or_insert_with(|| TraceabilityGap {
area: req.area.clone(),
findings: Vec::new(),
})
.findings
.push(finding);
}
#[shallguard::enforces("REQ-BASE-002", "REQ-BASE-004")]
fn apply_baseline(
analysis: &mut Analysis,
baseline: &Baseline,
complete_scope: bool,
stale_is_error: bool,
config: &RepositoryConfig,
) -> BaselineStats {
let mut stats = BaselineStats::default();
let requirements: HashMap<&str, &Requirement> = analysis
.requirements
.iter()
.map(|req| (req.id.as_str(), req))
.collect();
let mut entries: BTreeMap<GapKey, &BaselineEntry> = BTreeMap::new();
for duplicate in baseline.duplicate_keys() {
analysis.errors.push(baseline_finding(
config,
format!(
"duplicate baseline entry for {} ({})",
duplicate.requirement, duplicate.kind
),
));
}
for entry in &baseline.gaps {
entries.entry(entry.key()).or_insert(entry);
}
for (key, gap) in &analysis.gaps {
if gap_is_hard(key.kind, &gap.area, config) {
analysis.errors.extend(
gap.findings
.iter()
.cloned()
.map(|finding| annotate_gap(finding, "hard-area", key.kind)),
);
} else if entries.contains_key(key) {
stats.known += 1;
analysis.warnings.extend(
gap.findings
.iter()
.cloned()
.map(|finding| annotate_gap(finding, "grandfathered", key.kind)),
);
} else {
stats.new += 1;
analysis.errors.extend(
gap.findings
.iter()
.cloned()
.map(|finding| annotate_gap(finding, "new regression", key.kind)),
);
}
}
for (key, entry) in entries {
let Some(req) = requirements.get(entry.requirement.as_str()) else {
if complete_scope {
analysis.errors.push(baseline_finding(
config,
format!(
"baseline entry {} ({}) references a missing requirement",
entry.requirement, entry.kind
),
));
}
continue;
};
if gap_is_hard(entry.kind, &req.area, config) {
analysis.errors.push(baseline_finding(
config,
format!(
"baseline entry {} ({}) is forbidden because area {} is already hard",
entry.requirement, entry.kind, req.area
),
));
continue;
}
let stale_reason = if req.retired {
Some("the requirement is retired")
} else if !analysis.gaps.contains_key(&key) {
Some("the gap is resolved")
} else {
None
};
if let Some(reason) = stale_reason {
stats.resolved += 1;
if stale_is_error {
analysis.errors.push(baseline_finding(
config,
format!(
"stale baseline entry {} ({}): {reason}; remove it with `cargo \
shallguard baseline prune`",
entry.requirement, entry.kind
),
));
}
}
}
stats
}
fn annotate_gap(mut finding: Finding, status: &str, kind: GapKind) -> Finding {
finding.message = format!("[{status} {kind}] {}", finding.message);
finding
}
fn baseline_finding(config: &RepositoryConfig, message: String) -> Finding {
Finding {
file: config.baseline.to_string_lossy().into_owned(),
line: 1,
message,
}
}
#[shallguard::enforces("REQ-BASE-003")]
fn gap_is_hard(kind: GapKind, area: &str, config: &RepositoryConfig) -> bool {
match kind {
GapKind::EnforcementAnchor => config.area_is_hard(area, false),
GapKind::VerificationAnchor | GapKind::EvidenceCitation => config.area_is_hard(area, true),
}
}
fn covers_configured_documents(docs: &[DocSpec], config: &RepositoryConfig) -> bool {
let paths: HashSet<&str> = docs.iter().map(|doc| doc.path.as_str()).collect();
config
.documents()
.iter()
.all(|doc| paths.contains(doc.path.as_str()))
}
fn require_complete_scope(
docs: &[DocSpec],
config: &RepositoryConfig,
operation: &str,
) -> Result<()> {
if !covers_configured_documents(docs, config) {
bail!(
"cannot {operation} traceability baseline with a partial document set; use the \
default workspace documents"
);
}
Ok(())
}
fn ensure_no_non_gap_errors(analysis: &Analysis, operation: &str) -> Result<()> {
if let Some(first) = analysis.errors.first() {
bail!(
"cannot {operation} traceability baseline while checks fail: {}:{}: {}",
first.file,
first.line,
first.message
);
}
Ok(())
}
#[derive(Default)]
struct AreaStats {
total: usize,
retired: usize,
automated: usize,
e2e: usize,
review_only: usize,
pending: usize,
anchorable: usize,
anchored: usize,
test_anchored: usize,
}
fn render_summary(
stats: &BTreeMap<String, AreaStats>,
anchors: &Anchors,
baseline: &BaselineStats,
config: &RepositoryConfig,
) -> String {
let label_width = stats
.keys()
.map(|area| config.area_label(area).chars().count())
.max()
.unwrap_or(0)
.max("area".len());
let mut out = String::new();
let _ = writeln!(
out,
"{:<label_width$} {:>5} {:>5} {:>4} {:>7} {:>8} {:>16} {:>13}",
"area", "total", "test", "e2e", "review", "pending", "code-anchored", "test-anchored"
);
let mut totals = AreaStats::default();
for (area, s) in stats {
let _ = writeln!(
out,
"{:<label_width$} {:>5} {:>5} {:>4} {:>7} {:>8} {:>13}/{:<3} {:>9}/{:<3}",
config.area_label(area),
s.total,
s.automated,
s.e2e,
s.review_only,
s.pending,
s.anchored,
s.anchorable,
s.test_anchored,
s.automated
);
totals.total += s.total;
totals.automated += s.automated;
totals.e2e += s.e2e;
totals.review_only += s.review_only;
totals.pending += s.pending;
totals.anchorable += s.anchorable;
totals.anchored += s.anchored;
totals.test_anchored += s.test_anchored;
}
let _ = writeln!(
out,
"{:<label_width$} {:>5} {:>5} {:>4} {:>7} {:>8} {:>13}/{:<3} {:>9}/{:<3}",
"all",
totals.total,
totals.automated,
totals.e2e,
totals.review_only,
totals.pending,
totals.anchored,
totals.anchorable,
totals.test_anchored,
totals.automated
);
let _ = writeln!(
out,
"anchors found in code: {} enforcement, {} verification \
({} textual reference(s))",
anchors.enforcement.len(),
anchors.verification.len(),
anchors.references.values().map(Vec::len).sum::<usize>(),
);
let _ = writeln!(
out,
"traceability baseline: {} known gap(s), {} resolved/stale, {} new regression(s)",
baseline.known, baseline.resolved, baseline.new
);
out
}
#[cfg(test)]
#[path = "check_tests.rs"]
mod tests;