From ce70bc4c4295c940d5d9b0b46beb7bdf4ee4097b Mon Sep 17 00:00:00 2001 From: Marqdo Agent Date: Sat, 21 Nov 2026 01:38:21 +0800 Subject: [PATCH] test(docs): gate the current architecture and evidence links --- .github/workflows/ci.yml | 2 + .woodpecker.yml | 1 + crates/cli/tests/docs_consistency.rs | 170 ++++++++++++++++++++++ docs/evidence/2026-11-21-stdio-streams.md | 4 + 4 files changed, 177 insertions(+) create mode 100644 crates/cli/tests/docs_consistency.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7a86503..bc64cd8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,6 +25,8 @@ jobs: run: cargo clippy --workspace --all-targets -- -D warnings - name: Tests run: cargo test --workspace + - name: Documentation consistency + run: cargo test -p marqdo-cli --test docs_consistency - name: Validate public JSON schemas run: | python3 - <<'PY' diff --git a/.woodpecker.yml b/.woodpecker.yml index c8920ea..40fcd60 100644 --- a/.woodpecker.yml +++ b/.woodpecker.yml @@ -16,6 +16,7 @@ steps: - cargo fmt --all -- --check - cargo clippy --workspace --all-targets -- -D warnings - cargo test --workspace --locked + - cargo test -p marqdo-cli --test docs_consistency build: image: rust:1.100-bookworm diff --git a/crates/cli/tests/docs_consistency.rs b/crates/cli/tests/docs_consistency.rs new file mode 100644 index 0000000..02644b3 --- /dev/null +++ b/crates/cli/tests/docs_consistency.rs @@ -0,0 +1,170 @@ +//! Documentation consistency gate (review RFC-CM P0). +//! +//! The current architecture lives in one file, the status file must link it, +//! relative links must resolve, and a removed "running status" claim must not +//! come back. This is a source check, not a release proof. + +use std::collections::BTreeSet; +use std::path::{Path, PathBuf}; + +fn repo_root() -> PathBuf { + Path::new(env!("CARGO_MANIFEST_DIR")) + .parent() + .unwrap() + .parent() + .unwrap() + .to_path_buf() +} + +fn read(path: &Path) -> String { + std::fs::read_to_string(path).unwrap_or_else(|error| { + panic!("read {}: {error}", path.display()); + }) +} + +#[test] +fn current_architecture_has_one_overview_and_four_state_dimensions() { + let current = read(&repo_root().join("docs/architecture/CURRENT.md")); + for heading in [ + "## 1. Four state dimensions", + "## 2. Responsibility layers", + "## 3. Dependency direction and public contracts", + "## 4. Extension path classification", + "## 5. Gap and closure backlog", + "## 6. Documentation governance", + ] { + assert!(current.contains(heading), "CURRENT.md is missing {heading}"); + } + for dimension in [ + "Implemented", + "Tested locally", + "Bundled stdlib released", + "Multi-platform verified", + ] { + assert!( + current.contains(dimension), + "CURRENT.md is missing the `{dimension}` state dimension" + ); + } + let baseline = current + .lines() + .find(|line| line.starts_with("- Baseline:")) + .expect("CURRENT.md has no Baseline line"); + let sha = baseline + .split('`') + .nth(1) + .expect("Baseline line has no backtick-quoted SHA"); + assert_eq!(sha.len(), 40, "Baseline SHA is not 40 hex digits: {sha}"); + assert!( + sha.chars().all(|c| c.is_ascii_hexdigit()), + "Baseline SHA is not hex: {sha}" + ); +} + +#[test] +fn index_and_status_point_at_the_current_overview_and_history() { + let root = repo_root(); + let index = read(&root.join("docs/architecture/README.md")); + for target in ["CURRENT.md", "../STATUS.md", "../history/README.md"] { + assert!( + index.contains(target), + "architecture index does not link {target}" + ); + } + // The index is an index, not a second running-status page. + assert!( + !index.contains("P5 providers") && !index.contains("P5 Provider"), + "architecture index must not duplicate the current P5 status" + ); + + let status = read(&root.join("docs/STATUS.md")); + assert!( + status.contains("architecture/CURRENT.md"), + "STATUS.md does not link the current overview" + ); + assert!( + !status.contains("is still `c9f01aa8"), + "STATUS.md still claims the stale `c9f01aa8` remote baseline" + ); +} + +#[test] +fn current_relative_markdown_links_resolve() { + let root = repo_root(); + for relative in [ + "docs/architecture/CURRENT.md", + "docs/architecture/README.md", + "docs/STATUS.md", + "docs/history/README.md", + ] { + let path = root.join(relative); + let text = read(&path); + let mut checked = BTreeSet::new(); + for target in markdown_targets(&text) { + if target.starts_with("http://") + || target.starts_with("https://") + || target.starts_with('#') + { + continue; + } + let file = target.split('#').next().unwrap(); + if file.is_empty() || !checked.insert(file.to_string()) { + continue; + } + let resolved = path.parent().unwrap().join(file); + assert!( + resolved.exists(), + "{} links missing `{target}` (resolved {})", + path.display(), + resolved.display() + ); + } + } +} + +#[test] +fn evidence_files_are_sha_pinned() { + let evidence = repo_root().join("docs/evidence"); + for entry in std::fs::read_dir(&evidence).expect("read evidence dir") { + let path = entry.unwrap().path(); + if path.extension().and_then(|ext| ext.to_str()) != Some("md") { + continue; + } + let text = read(&path); + assert!( + has_hex_sha(&text), + "{} has no 7–40 hex commit/security SHA", + path.display() + ); + } +} + +fn markdown_targets(text: &str) -> Vec { + let bytes = text.as_bytes(); + let mut out = Vec::new(); + let mut i = 0; + while i + 1 < bytes.len() { + if bytes[i] == b']' && bytes[i + 1] == b'(' { + let start = i + 2; + let mut end = start; + while end < bytes.len() && bytes[end] != b')' && bytes[end] != b'\n' { + end += 1; + } + if end < bytes.len() && bytes[end] == b')' { + out.push(text[start..end].to_string()); + i = end; + } + } + i += 1; + } + out +} + +fn has_hex_sha(text: &str) -> bool { + for word in text.split(|c: char| !c.is_ascii_hexdigit()) { + if (7..=40).contains(&word.len()) { + return true; + } + } + false +} diff --git a/docs/evidence/2026-11-21-stdio-streams.md b/docs/evidence/2026-11-21-stdio-streams.md index 99c5d69..430c80f 100644 --- a/docs/evidence/2026-11-21-stdio-streams.md +++ b/docs/evidence/2026-11-21-stdio-streams.md @@ -1,9 +1,13 @@ # Evidence: stdio stdin/stderr and stdlib streams Date: 2026-11-21 (Asia/Shanghai) +Code baseline: `24c88bcc78b1c705eb2319e7aaa8822a415eb01f` Repository: `marqdo-cli` Decision record: [ADR-0040](../adr/0040-stdio-stdin-stderr-and-stdlib-streams.md) +This snapshot predates the documentation/test migration; re-run the gate +commands below before citing a current pass. + ## Local gate ```text