use std::path::{Path, PathBuf};
use anyhow::{Context, Result, bail};
use regex::Regex;
use crate::DocSpec;
use crate::docs::parse_text;
use crate::evidence_mark::EvidenceMark;
const REQUIREMENT_LINE_WIDTH: usize = 88;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FormatDiagnostic {
pub document: String,
pub line: usize,
pub message: String,
}
#[derive(Debug)]
pub struct FormatReport {
pub documents: usize,
pub requirements: usize,
pub changed_documents: Vec<PathBuf>,
pub diagnostics: Vec<FormatDiagnostic>,
}
impl FormatReport {
pub fn is_clean(&self) -> bool {
self.diagnostics.is_empty() && self.changed_documents.is_empty()
}
}
struct PreparedDocument {
path: PathBuf,
formatted: String,
changed: bool,
requirements: usize,
diagnostics: Vec<FormatDiagnostic>,
}
struct FormattedText {
text: String,
requirements: usize,
diagnostics: Vec<FormatDiagnostic>,
}
#[shallguard::enforces("REQ-SPEC-006")]
pub fn check(root: &Path, specs: &[DocSpec]) -> Result<FormatReport> {
run(root, specs, false)
}
#[shallguard::enforces("REQ-SPEC-005")]
pub fn format(root: &Path, specs: &[DocSpec]) -> Result<FormatReport> {
run(root, specs, true)
}
fn run(root: &Path, specs: &[DocSpec], write: bool) -> Result<FormatReport> {
let mut prepared = Vec::with_capacity(specs.len());
for spec in specs {
prepared.push(prepare_document(root, spec, write)?);
}
let diagnostics = prepared
.iter()
.flat_map(|document| document.diagnostics.iter().cloned())
.collect::<Vec<_>>();
if write && diagnostics.is_empty() {
for document in prepared.iter().filter(|document| document.changed) {
write_atomic(&document.path, document.formatted.as_bytes())?;
}
}
Ok(FormatReport {
documents: specs.len(),
requirements: prepared.iter().map(|document| document.requirements).sum(),
changed_documents: prepared
.iter()
.filter(|document| document.changed)
.map(|document| workspace_relative(root, &document.path))
.collect(),
diagnostics,
})
}
fn prepare_document(root: &Path, spec: &DocSpec, add_keywords: bool) -> Result<PreparedDocument> {
let path = root.join(&spec.path);
let original = std::fs::read_to_string(&path)
.with_context(|| format!("reading requirement document {}", path.display()))?;
let formatted = format_text(&original, spec, add_keywords);
if formatted.diagnostics.is_empty() {
verify_semantic_equivalence(&original, &formatted.text, spec)?;
}
Ok(PreparedDocument {
changed: original != formatted.text,
path,
formatted: formatted.text,
requirements: formatted.requirements,
diagnostics: formatted.diagnostics,
})
}
fn format_text(text: &str, spec: &DocSpec, add_keywords: bool) -> FormattedText {
let candidate_re =
Regex::new(r"^\s*-\s+\*\*REQ-").expect("BUG: invalid requirement candidate regex");
let lines = text.lines().collect::<Vec<_>>();
let mut output = Vec::with_capacity(lines.len());
let mut diagnostics = Vec::new();
let mut requirements = 0;
let mut index = 0;
while index < lines.len() {
if !candidate_re.is_match(lines[index]) {
output.push(lines[index].to_string());
index += 1;
continue;
}
let start = index;
index += 1;
while index < lines.len()
&& !lines[index].is_empty()
&& lines[index].chars().next().is_some_and(char::is_whitespace)
{
index += 1;
}
let block = &lines[start..index];
requirements += 1;
let block_diagnostics = lint_block(block, spec, start + 1);
if block_diagnostics.is_empty() {
output.extend(format_block(block, add_keywords));
} else {
output.extend(block.iter().map(|line| (*line).to_string()));
diagnostics.extend(block_diagnostics);
}
}
let mut text = output.join("\n");
text.push('\n');
FormattedText {
text,
requirements,
diagnostics,
}
}
#[shallguard::enforces("REQ-SPEC-001", "REQ-SPEC-002", "REQ-SPEC-004", "REQ-SPEC-007")]
fn lint_block(block: &[&str], spec: &DocSpec, line: usize) -> Vec<FormatDiagnostic> {
let header_re = Regex::new(r"^- \*\*(REQ-([A-Z]{2,})-\d{3})\*\* — \S")
.expect("BUG: invalid requirement header regex");
let normative_re =
Regex::new(r"\b(?:SHALL(?: NOT)?|MAY)\b").expect("BUG: invalid normative regex");
let combined = normalized_block(block);
let mut messages = Vec::new();
if !header_re.is_match(&combined) {
messages.push(
"expected `- **REQ-<AREA>-<NNN>** — <normative statement>` with an uppercase area and three-digit number"
.to_string(),
);
}
let enforced_count = combined.matches("*Enforced:*").count();
let verified_count = combined.matches("*Verified:*").count();
let retired = combined.to_ascii_lowercase().contains("(retired");
if retired && enforced_count == 0 && verified_count == 0 {
return diagnostics(spec, line, messages);
}
if enforced_count != 1 {
messages.push(format!(
"active requirement must contain exactly one `*Enforced:*` segment; found {enforced_count}"
));
}
if verified_count != 1 {
messages.push(format!(
"active requirement must contain exactly one `*Verified:*` segment; found {verified_count}"
));
}
let Some((statement, after_enforced)) = combined.split_once("*Enforced:*") else {
return diagnostics(spec, line, messages);
};
let Some((enforced, verified)) = after_enforced.split_once("*Verified:*") else {
return diagnostics(spec, line, messages);
};
if !normative_re.is_match(statement) && !enforced.contains("not implemented") {
messages.push("active requirement statement must use SHALL, SHALL NOT, or MAY".to_string());
}
if enforced.trim().trim_end_matches('·').trim().is_empty() {
messages.push("`*Enforced:*` segment must name enforcement evidence".to_string());
}
if !enforced.trim_end().ends_with('·') {
messages.push("separate `*Enforced:*` and `*Verified:*` with `·`".to_string());
}
if verified.trim().is_empty() {
messages.push("`*Verified:*` segment must name verification evidence".to_string());
}
if !EvidenceMark::any_claimed_in(verified) {
messages.push(format!(
"`*Verified:*` must contain an evidence mark: {} (the emoji aliases are accepted)",
EvidenceMark::keyword_list()
));
}
diagnostics(spec, line, messages)
}
fn diagnostics(spec: &DocSpec, line: usize, messages: Vec<String>) -> Vec<FormatDiagnostic> {
messages
.into_iter()
.map(|message| FormatDiagnostic {
document: spec.path.clone(),
line,
message,
})
.collect()
}
fn normalized_block(block: &[&str]) -> String {
block
.iter()
.flat_map(|line| line.split_whitespace())
.collect::<Vec<_>>()
.join(" ")
}
fn format_block(block: &[&str], add_keywords: bool) -> Vec<String> {
let lines = if add_keywords {
canonicalize_evidence_marks(block)
} else {
block.iter().map(|line| (*line).to_string()).collect()
};
let mut formatted = Vec::new();
for (index, line) in lines.iter().enumerate() {
wrap_existing_line(line.trim(), index == 0, &mut formatted);
}
formatted
}
#[shallguard::enforces("REQ-SPEC-008")]
fn canonicalize_evidence_marks(block: &[&str]) -> Vec<String> {
let mut in_verified = false;
block
.iter()
.map(|line| {
if in_verified {
return EvidenceMark::canonicalize(line);
}
match line.split_once("*Verified:*") {
Some((head, tail)) => {
in_verified = true;
format!("{head}*Verified:*{}", EvidenceMark::canonicalize(tail))
}
None => (*line).to_string(),
}
})
.collect()
}
fn wrap_existing_line(line: &str, first_line: bool, output: &mut Vec<String>) {
let indent = if first_line { "" } else { " " };
let mut current = indent.to_string();
for word in line.split_whitespace() {
let has_content = current.len() > indent.len();
let separator = usize::from(has_content);
if has_content
&& current.chars().count() + separator + word.chars().count() > REQUIREMENT_LINE_WIDTH
{
output.push(current);
current = " ".to_string();
}
let current_indent = if current.starts_with(" ") { 2 } else { 0 };
if current.len() > current_indent {
current.push(' ');
}
current.push_str(word);
}
if current.len() > indent.len() {
output.push(current);
}
}
fn verify_semantic_equivalence(original: &str, formatted: &str, spec: &DocSpec) -> Result<()> {
let before = parse_text(original, spec);
let after = parse_text(formatted, spec);
if before.requirements.len() != after.requirements.len() {
bail!(
"formatting {} would change the parsed requirement count from {} to {}",
spec.path,
before.requirements.len(),
after.requirements.len()
);
}
for (before, after) in before.requirements.iter().zip(&after.requirements) {
if before.id != after.id
|| before.statement != after.statement
|| before.enforced_text != after.enforced_text
|| before.verified_text != after.verified_text
{
bail!(
"formatting {} would change the parsed meaning of {}",
spec.path,
before.id
);
}
}
Ok(())
}
fn write_atomic(path: &Path, content: &[u8]) -> Result<()> {
let file_name = path
.file_name()
.and_then(|name| name.to_str())
.context("requirement document has no UTF-8 file name")?;
let temporary = path.with_file_name(format!(".{file_name}.fmt-{}", std::process::id()));
std::fs::write(&temporary, content)
.with_context(|| format!("writing formatted document {}", temporary.display()))?;
std::fs::rename(&temporary, path)
.with_context(|| format!("publishing formatted document {}", path.display()))
}
fn workspace_relative(root: &Path, path: &Path) -> PathBuf {
path.strip_prefix(root).unwrap_or(path).to_path_buf()
}
#[cfg(test)]
mod tests {
use super::*;
fn spec() -> DocSpec {
DocSpec::new(
"crate/docs/USER_STORIES_AND_REQUIREMENTS.md",
"crate",
std::collections::BTreeMap::new(),
)
}
#[shallguard::verifies("REQ-SPEC-005")]
#[test]
fn formats_requirement_blocks_without_touching_surrounding_markdown() {
let input = "# Story\n\n- **REQ-AA-001** — The service SHALL retain a deliberately long value across every ordinary processing pass so the formatter has to wrap it.\n *Enforced:* `src/lib.rs` (`apply`) · *Verified:* [test] `src/lib.rs` (`test_apply`)\n\n| prose | stays |\n";
let formatted = format_text(input, &spec(), true);
assert!(formatted.diagnostics.is_empty());
assert_eq!(formatted.requirements, 1);
assert!(
formatted
.text
.lines()
.any(|line| line.starts_with(" ") && line.contains("formatter"))
);
assert!(formatted.text.contains("*Enforced:*"));
assert!(formatted.text.ends_with("\n| prose | stays |\n"));
assert!(
formatted
.text
.lines()
.filter(|line| line.starts_with("- **REQ-") || line.starts_with(" "))
.all(|line| line.chars().count() <= REQUIREMENT_LINE_WIDTH)
);
}
#[shallguard::verifies("REQ-SPEC-005")]
#[test]
fn formatting_is_idempotent_and_semantically_equivalent() {
let input = "- **REQ-AA-001** — The service SHALL retain state.\n *Enforced:* `src/lib.rs` (`apply`) · *Verified:* [test] `src/lib.rs` (`test_apply`)\n";
let once = format_text(input, &spec(), true);
let twice = format_text(&once.text, &spec(), true);
assert!(once.diagnostics.is_empty());
assert_eq!(once.text, twice.text);
verify_semantic_equivalence(input, &once.text, &spec())
.expect("formatting preserves requirement meaning");
}
#[shallguard::verifies("REQ-SPEC-001", "REQ-SPEC-002")]
#[test]
fn rejects_missing_segments_and_evidence_status() {
let missing_verified =
"- **REQ-AA-001** — The service SHALL retain state.\n *Enforced:* `src/lib.rs`\n";
let no_status = "- **REQ-AA-002** — The service SHALL retain state.\n *Enforced:* `src/lib.rs` · *Verified:* `src/lib.rs` (`test_apply`)\n";
let first = format_text(missing_verified, &spec(), true);
let second = format_text(no_status, &spec(), true);
assert!(
first
.diagnostics
.iter()
.any(|diagnostic| diagnostic.message.contains("exactly one `*Verified:*`"))
);
assert!(
second
.diagnostics
.iter()
.any(|diagnostic| diagnostic.message.contains("must contain"))
);
}
#[shallguard::verifies("REQ-SPEC-007", "REQ-SPEC-008")]
#[test]
fn adds_canonical_keywords_next_to_emoji_aliases() {
let input = "- **REQ-AA-001** — The service SHALL retain state.\n *Enforced:* `src/lib.rs` (`apply`) · *Verified:* ✅ `src/lib.rs` (`test_apply`) ·\n 🔬 differential run\n- **REQ-AA-002** — The service SHALL not fail.\n *Enforced:* not implemented · *Verified:* ⏳ pending\n";
let formatted = format_text(input, &spec(), true);
assert!(
formatted.diagnostics.is_empty(),
"{:?}",
formatted.diagnostics
);
let joined = formatted
.text
.split_whitespace()
.collect::<Vec<_>>()
.join(" ");
assert!(joined.contains("*Verified:* [test] ✅ `src/lib.rs` (`test_apply`) ·"));
assert!(joined.contains("[e2e] 🔬 differential run"));
assert!(joined.contains("*Verified:* [pending] ⏳ pending"));
let twice = format_text(&formatted.text, &spec(), true);
assert_eq!(twice.text, formatted.text, "the rewrite is idempotent");
let kept = format_text(input, &spec(), false);
assert!(kept.diagnostics.is_empty());
assert!(
!kept.text.contains("[test]") && kept.text.contains('✅'),
"the check mode keeps an emoji alias without its keyword"
);
verify_semantic_equivalence(input, &formatted.text, &spec())
.expect("an alias and its keyword have the same parsed meaning");
let before = parse_text(input, &spec());
let after = parse_text(&formatted.text, &spec());
assert!(before.requirements[0].automated && after.requirements[0].automated);
assert!(before.requirements[0].e2e && after.requirements[0].e2e);
assert!(before.requirements[1].pending && after.requirements[1].pending);
}
#[shallguard::verifies("REQ-SPEC-008")]
#[test]
fn check_accepts_emoji_aliases_and_format_adds_keywords() {
let dir = tempfile::tempdir().expect("tempdir");
let doc = dir
.path()
.join("crate/docs/USER_STORIES_AND_REQUIREMENTS.md");
std::fs::create_dir_all(doc.parent().expect("BUG: document has a parent")).expect("mkdir");
std::fs::write(
&doc,
"- **REQ-AA-001** — The service SHALL retain state.\n *Enforced:* `src/lib.rs` (`apply`) · *Verified:* ✅ `src/lib.rs` (`test_apply`)\n",
)
.expect("write document");
let report = check(dir.path(), &[spec()]).expect("check runs");
assert!(report.diagnostics.is_empty());
assert!(
report.is_clean(),
"an emoji-only document passes fmt --check"
);
let untouched = std::fs::read_to_string(&doc).expect("read document");
assert!(!untouched.contains("[test]"), "check must not write");
let written = super::format(dir.path(), &[spec()]).expect("format runs");
assert_eq!(written.changed_documents.len(), 1);
let migrated = std::fs::read_to_string(&doc).expect("read document");
assert!(migrated.contains("*Verified:* [test] ✅"), "{migrated}");
assert!(check(dir.path(), &[spec()]).expect("check runs").is_clean());
}
#[shallguard::verifies("REQ-SPEC-004")]
#[test]
fn permits_retired_requirements_without_evidence_segments() {
let input = "- **REQ-AA-001** — *(retired into REQ-AA-002.)*\n";
let formatted = format_text(input, &spec(), true);
assert!(formatted.diagnostics.is_empty());
assert_eq!(formatted.text, input);
}
#[test]
fn formats_files_atomically_and_then_checks_clean() {
let directory = tempfile::tempdir().expect("temporary directory");
let document = directory
.path()
.join("crate/docs/USER_STORIES_AND_REQUIREMENTS.md");
std::fs::create_dir_all(document.parent().expect("document has parent"))
.expect("document directory creates");
std::fs::write(
&document,
"- **REQ-AA-001** — The service SHALL retain state.\n *Enforced:* `src/lib.rs` (`apply`) · *Verified:* [test] `src/lib.rs` (`test_apply`)\n",
)
.expect("fixture writes");
let formatted = super::format(directory.path(), &[spec()]).expect("format succeeds");
assert_eq!(
formatted.changed_documents,
vec![PathBuf::from("crate/docs/USER_STORIES_AND_REQUIREMENTS.md")]
);
let text = std::fs::read_to_string(&document).expect("formatted document reads");
assert!(text.contains("\n *Enforced:*"));
let checked = check(directory.path(), &[spec()]).expect("check succeeds");
assert!(checked.is_clean());
}
#[shallguard::verifies("REQ-SPEC-005")]
#[test]
fn lint_failures_prevent_formatter_writes() {
let directory = tempfile::tempdir().expect("temporary directory");
let document = directory
.path()
.join("crate/docs/USER_STORIES_AND_REQUIREMENTS.md");
std::fs::create_dir_all(document.parent().expect("document has parent"))
.expect("document directory creates");
let malformed =
"- **REQ-AA-001** — The service SHALL retain state.\n *Enforced:* `src/lib.rs`\n";
std::fs::write(&document, malformed).expect("fixture writes");
let report = super::format(directory.path(), &[spec()]).expect("lint report returns");
assert!(!report.diagnostics.is_empty());
assert_eq!(
std::fs::read_to_string(document).expect("unchanged document reads"),
malformed
);
}
}