test(docs): gate the current architecture and evidence links

This commit is contained in:
Marqdo Agent committed 2026-11-21 01:38:21 +08:00
1 parent c2730ea445
commit ce70bc4c42
4 files changed
+177

No files matched your search

+2
View File
@@ -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'
+1
View File
@@ -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
+170
View File
@@ -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<String> {
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
}
@@ -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