Refactor test-readme into generic docs code block verifier

3 files changed, 186 insertions, 353 deletions

diff --git a/dev_tools/src/bin/ci.rs b/dev_tools/src/bin/ci.rs
index 21763d1..ce8f058 100644
--- a/dev_tools/src/bin/ci.rs
+++ b/dev_tools/src/bin/ci.rs
@@ -73,7 +73,7 @@ fn ci() -> Result<(), i32> {
     clippy_all()?;
     test_all()?;
     test_examples()?;
-    test_readme()?;
+    test_docs_code_blocks()?;
     docs_refresh()?;
 
     run_cmd!("git add --renormalize .")?;
@@ -86,9 +86,9 @@ fn test_examples() -> Result<(), i32> {
     run_cmd!("cargo run --manifest-path dev_tools/Cargo.toml --bin test-examples")
 }
 
-fn test_readme() -> Result<(), i32> {
-    println_cargo_style!("Testing: readme code blocks");
-    run_cmd!("cargo run --manifest-path dev_tools/Cargo.toml --bin test-readme")
+fn test_docs_code_blocks() -> Result<(), i32> {
+    println_cargo_style!("Testing: documentation code blocks");
+    run_cmd!("cargo run --manifest-path dev_tools/Cargo.toml --bin test-all-markdown-code")
 }
 
 fn build_all() -> Result<(), i32> {
diff --git a/dev_tools/src/bin/test-all-markdown-code.rs b/dev_tools/src/bin/test-all-markdown-code.rs
new file mode 100644
index 0000000..c4e89be
--- /dev/null
+++ b/dev_tools/src/bin/test-all-markdown-code.rs
@@ -0,0 +1,182 @@
+use std::path::{Path, PathBuf};
+
+use colored::Colorize;
+use tools::verify::{
+    build_block, generate_cargo_toml, generate_main_rs, is_block_testable, parse_code_blocks,
+    write_summary_report,
+};
+use tools::{eprintln_cargo_style, println_cargo_style};
+
+/// Config from verified-docs.toml
+#[derive(serde::Deserialize)]
+struct Config {
+    verified: VerifiedPaths,
+}
+
+#[derive(serde::Deserialize)]
+struct VerifiedPaths {
+    readme: String,
+    #[serde(default)]
+    documents_en_us: Option<String>,
+    #[serde(default)]
+    documents_zh_cn: Option<String>,
+}
+
+fn main() {
+    #[cfg(windows)]
+    let _ = colored::control::set_virtual_terminal(true);
+
+    let config_path = PathBuf::from("verified-docs.toml");
+    if !config_path.exists() {
+        eprintln_cargo_style!("verified-docs.toml not found in current directory");
+        std::process::exit(1);
+    }
+
+    let config: Config = {
+        let content = std::fs::read_to_string(&config_path).unwrap_or_else(|_e| {
+            eprintln_cargo_style!("Failed to read verified-docs.toml");
+            std::process::exit(1);
+        });
+        toml::from_str(&content).unwrap_or_else(|_e| {
+            eprintln_cargo_style!("Failed to parse verified-docs.toml");
+            std::process::exit(1);
+        })
+    };
+
+    // Collect all markdown files from config
+    let mut files: Vec<(String, PathBuf)> = Vec::new();
+
+    // README
+    let readme_path = PathBuf::from(&config.verified.readme);
+    if readme_path.exists() {
+        files.push(("README".to_string(), readme_path));
+        println_cargo_style!("Source: found README.md");
+    }
+
+    // English docs
+    if let Some(pattern) = &config.verified.documents_en_us {
+        let base = pattern.trim_end_matches("/**").trim_end_matches('*');
+        let dir = PathBuf::from(base);
+        if dir.exists() && dir.is_dir() {
+            collect_md_files(&dir, &mut files, "en");
+            println_cargo_style!("Source: found docs/pages/");
+        }
+    }
+
+    // Chinese docs
+    if let Some(pattern) = &config.verified.documents_zh_cn {
+        let base = pattern.trim_end_matches("/**").trim_end_matches('*');
+        let dir = PathBuf::from(base);
+        if dir.exists() && dir.is_dir() {
+            collect_md_files(&dir, &mut files, "zh_CN");
+            println_cargo_style!("Source: found docs/_zh_CN/pages/");
+        }
+    }
+
+    if files.is_empty() {
+        eprintln_cargo_style!("No markdown files found to verify");
+        std::process::exit(1);
+    }
+
+    // Ensure temp directory exists
+    let temp_dir = PathBuf::from(".temp/docs-test");
+    let _ = std::fs::remove_dir_all(&temp_dir);
+
+    let mut all_blocks: Vec<(String, Vec<tools::verify::CodeBlock>)> = Vec::new();
+
+    for (label, path) in &files {
+        let content = std::fs::read_to_string(path).unwrap_or_else(|e| {
+            eprintln_cargo_style!("Failed to read {}: {}", path.display(), e);
+            String::new()
+        });
+        let source_file = format!("{label}/{}", path.file_name().unwrap().to_string_lossy());
+        let blocks = parse_code_blocks(&content, &source_file);
+        let testable: Vec<_> = blocks.into_iter().filter(is_block_testable).collect();
+        if !testable.is_empty() {
+            all_blocks.push((label.clone(), testable));
+        }
+    }
+
+    let total_testable: usize = all_blocks.iter().map(|(_, b)| b.len()).sum();
+
+    if total_testable == 0 {
+        println_cargo_style!("No testable code blocks found");
+        return;
+    }
+
+    println_cargo_style!(
+        "Test: found {total_testable} testable code blocks across {} files",
+        all_blocks.len()
+    );
+
+    // Build each block
+    let mut block_index = 0usize;
+    let mut passed = 0usize;
+    let mut failed = 0usize;
+    let mut results: Vec<(String, usize, bool, String)> = Vec::new();
+
+    for (_label, blocks) in &all_blocks {
+        for block in blocks {
+            block_index += 1;
+
+            let block_label = format!(
+                "Block {} ({}:{})",
+                block_index, block.source_file, block.line
+            );
+            print!("  Testing {block_label} ... ");
+
+            let package_name = format!("test-block-{block_index}");
+
+            let cargo_toml = generate_cargo_toml(block, &package_name);
+            let main_rs = generate_main_rs(block);
+            let src_dir = temp_dir.join("src");
+            let manifest_path = temp_dir.join("Cargo.toml");
+
+            let (ok, err) = build_block(&src_dir, &manifest_path, &cargo_toml, &main_rs);
+            if ok {
+                println!("{}", "passed".bold().bright_green());
+                passed += 1;
+                results.push((block.source_file.clone(), block.line, true, String::new()));
+            } else {
+                println!("{}", "failed".bold().bright_red());
+                failed += 1;
+                results.push((block.source_file.clone(), block.line, false, err.clone()));
+                eprintln_cargo_style!(format!("  {block_label} FAILED:\n{err}"));
+            }
+        }
+    }
+
+    let result_msg = format!("Result: {passed}/{total_testable} blocks passed");
+    println_cargo_style!(result_msg);
+
+    write_summary_report(
+        Path::new(".temp/DOCS-TEST-RESULT.md"),
+        "Documentation Code Block Test Report",
+        &results,
+        total_testable,
+        passed,
+        failed,
+    );
+
+    if failed > 0 {
+        let fail_msg = format!("{failed} block(s) failed to build");
+        eprintln_cargo_style!(fail_msg);
+        std::process::exit(1);
+    }
+
+    println_cargo_style!("Done: All verified code blocks build successfully!");
+}
+
+/// Recursively collect all `.md` files under a directory
+fn collect_md_files(dir: &Path, files: &mut Vec<(String, PathBuf)>, lang: &str) {
+    if let Ok(entries) = std::fs::read_dir(dir) {
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.is_dir() {
+                collect_md_files(&path, files, lang);
+            } else if path.extension().is_some_and(|ext| ext == "md") {
+                files.push((lang.to_string(), path));
+            }
+        }
+    }
+}
diff --git a/dev_tools/src/bin/test-readme.rs b/dev_tools/src/bin/test-readme.rs
deleted file mode 100644
index fd1962f..0000000
--- a/dev_tools/src/bin/test-readme.rs
+++ /dev/null
@@ -1,349 +0,0 @@
-use colored::Colorize;
-use std::path::{Path, PathBuf};
-
-use tools::{eprintln_cargo_style, println_cargo_style, run_cmd_and_capture_stderr};
-
-/// Represents a parsed code block from README.md
-struct CodeBlock {
-    /// The line number in README.md where this block starts
-    line: usize,
-    /// The raw Rust source code
-    code: String,
-    /// Feature flags extracted from `// Features: [...]` comment
-    features: Vec<String>,
-    /// External dependencies extracted from `// Dependencies:` comments
-    external_deps: Vec<(String, String)>,
-    /// Whether this block has a `fn main` entry point
-    has_main: bool,
-    /// Whether this block has `gen_program!()` call
-    has_gen_program: bool,
-}
-
-fn main() {
-    #[cfg(windows)]
-    let _ = colored::control::set_virtual_terminal(true);
-
-    let readme_path = PathBuf::from("README.md");
-    if !readme_path.exists() {
-        eprintln_cargo_style!("README.md not found in current directory");
-        std::process::exit(1);
-    }
-
-    let content = std::fs::read_to_string(&readme_path).unwrap_or_else(|e| {
-        eprintln_cargo_style!("Failed to read README.md: {}", e);
-        std::process::exit(1);
-    });
-
-    let blocks = parse_code_blocks(&content);
-    if blocks.is_empty() {
-        eprintln_cargo_style!("No Rust code blocks found in README.md");
-        std::process::exit(1);
-    }
-
-    println_cargo_style!("Test: found {} Rust code blocks in README.md", blocks.len());
-
-    // Ensure temp directory exists
-    let temp_dir = PathBuf::from(".temp/readme-test");
-    let _ = std::fs::remove_dir_all(&temp_dir);
-    std::fs::create_dir_all(temp_dir.join("src")).unwrap_or_else(|e| {
-        eprintln_cargo_style!("Failed to create temp directory: {}", e);
-        std::process::exit(1);
-    });
-
-    let mut passed = 0usize;
-    let mut failed = 0usize;
-    let mut results: Vec<(usize, bool, String)> = Vec::new();
-
-    for (i, block) in blocks.iter().enumerate() {
-        let label = format!("Block {} (line {})", i + 1, block.line);
-        print!("  {label} ... ");
-
-        let (ok, err) = build_block(&temp_dir, block);
-        if ok {
-            println!("{}", "passed".bold().bright_green());
-            passed += 1;
-            results.push((block.line, true, String::new()));
-        } else {
-            println!("{}", "failed".bold().bright_red());
-            failed += 1;
-            results.push((block.line, false, err.clone()));
-            eprintln_cargo_style!("  {} FAILED:\n{}", label, err);
-        }
-    }
-
-    println_cargo_style!(
-        "Result: {passed}/{total} blocks passed",
-        total = blocks.len()
-    );
-
-    write_summary_report(
-        Path::new(".temp/README-TEST-RESULT.md"),
-        &results,
-        blocks.len(),
-        passed,
-        failed,
-    );
-
-    if failed > 0 {
-        eprintln_cargo_style!("{failed} block(s) failed to build");
-        std::process::exit(1);
-    }
-
-    println_cargo_style!("Done: All README code blocks build successfully!");
-}
-
-/// Parse all ```rust code blocks from README content
-fn parse_code_blocks(content: &str) -> Vec<CodeBlock> {
-    let mut blocks = Vec::new();
-    let lines: Vec<&str> = content.lines().collect();
-    let mut i = 0;
-
-    while i < lines.len() {
-        if lines[i].trim() == "```rust" {
-            if let Some(block) = parse_single_block(&lines, i) {
-                blocks.push(block);
-            }
-            i += 1;
-            while i < lines.len() && lines[i].trim() != "```" {
-                i += 1;
-            }
-        }
-        i += 1;
-    }
-
-    blocks
-}
-
-/// Parse a single code block starting at the ```rust line
-fn parse_single_block(lines: &[&str], start: usize) -> Option<CodeBlock> {
-    let line_num = start + 1; // 1-based line number
-
-    let mut code_lines: Vec<String> = Vec::new();
-    let mut features: Vec<String> = Vec::new();
-    let mut external_deps: Vec<(String, String)> = Vec::new();
-    let mut has_main = false;
-    let mut has_gen_program = false;
-
-    let mut idx = start + 1;
-    let mut in_header = true;
-
-    while idx < lines.len() {
-        let raw_line = lines[idx];
-        let trimmed = raw_line.trim();
-
-        if trimmed == "```" {
-            break;
-        }
-
-        // Parse header comments
-        if in_header && trimmed.starts_with("// ") {
-            if trimmed.starts_with("// Features:") {
-                let feat_str = trimmed.trim_start_matches("// Features:").trim();
-                if feat_str.starts_with('[') && feat_str.ends_with(']') {
-                    let inner = &feat_str[1..feat_str.len() - 1];
-                    if !inner.is_empty() {
-                        features = inner
-                            .split(',')
-                            .map(|s| s.trim().trim_matches('"').to_string())
-                            .filter(|s| !s.is_empty())
-                            .collect();
-                    }
-                }
-                idx += 1;
-                continue;
-            }
-            if trimmed == "// Dependencies:" {
-                idx += 1;
-                // Collect subsequent `// crate = "version"` lines
-                while idx < lines.len() {
-                    let next = lines[idx].trim();
-                    if next == "```" {
-                        break;
-                    }
-                    if next.starts_with("// ") {
-                        let dep_line = next.trim_start_matches("// ").trim();
-                        if let Some((name, ver)) = dep_line.split_once(" = ") {
-                            external_deps.push((
-                                name.trim().to_string(),
-                                ver.trim().trim_matches('"').to_string(),
-                            ));
-                        }
-                        idx += 1;
-                    } else {
-                        break;
-                    }
-                }
-                continue;
-            }
-        }
-
-        in_header = false;
-
-        if raw_line.contains("fn main") {
-            has_main = true;
-        }
-        if raw_line.contains("gen_program!") {
-            has_gen_program = true;
-        }
-
-        code_lines.push(raw_line.to_string());
-        idx += 1;
-    }
-
-    if code_lines.is_empty() {
-        return None;
-    }
-
-    Some(CodeBlock {
-        line: line_num,
-        code: code_lines.join("\n"),
-        features,
-        external_deps,
-        has_main,
-        has_gen_program,
-    })
-}
-
-/// Generate a Cargo.toml for a block
-fn generate_cargo_toml(block: &CodeBlock) -> String {
-    let features_str = if !block.features.is_empty() {
-        let feats: Vec<String> = block.features.iter().map(|f| format!("\"{f}\"")).collect();
-        format!("features = [{}]", feats.join(", "))
-    } else {
-        String::new()
-    };
-
-    let mut extra_deps = String::new();
-    for (name, version) in &block.external_deps {
-        if !version.starts_with('{') {
-            // Plain version string, e.g. "1"
-            if name == "serde" || name == "clap" {
-                extra_deps.push_str(&format!(
-                    "{name} = {{ version = \"{version}\", features = [\"derive\"] }}\n"
-                ));
-            } else {
-                extra_deps.push_str(&format!("{name} = \"{version}\"\n"));
-            }
-        } else {
-            // Already in TOML inline table format, e.g. { version = "1", features = [...] }
-            extra_deps.push_str(&format!("{name} = {version}\n"));
-        }
-    }
-
-    let deps_section = if features_str.is_empty() {
-        format!("[dependencies]\nmingling = {{ path = \"../../mingling\" }}\n{extra_deps}")
-    } else {
-        format!(
-            "[dependencies]\nmingling = {{ path = \"../../mingling\", {features_str} }}\n{extra_deps}"
-        )
-    };
-
-    format!(
-        r#"[package]
-name = "readme-test-block"
-version = "0.0.0"
-edition = "2024"
-
-{deps_section}
-[workspace]
-"#
-    )
-}
-
-/// Generate main.rs for a block
-fn generate_main_rs(block: &CodeBlock) -> String {
-    let mut output = String::from("#![allow(dead_code)]\n\n");
-
-    output.push_str(&block.code);
-    output.push('\n');
-
-    if !block.has_main {
-        output.push_str("\nfn main() {}\n");
-    }
-
-    if !block.has_gen_program {
-        output.push_str("\nmingling::macros::gen_program!();\n");
-    }
-
-    output
-}
-
-/// Build a single code block as a Cargo project.
-/// Always writes to `{temp_dir}/Cargo.toml` and `{temp_dir}/src/main.rs`.
-/// Returns (success, error_message).
-fn build_block(temp_dir: &Path, block: &CodeBlock) -> (bool, String) {
-    let src_dir = temp_dir.join("src");
-    if let Err(e) = std::fs::create_dir_all(&src_dir) {
-        return (false, format!("mkdir: {e}"));
-    }
-
-    // Write Cargo.toml
-    let cargo_toml = generate_cargo_toml(block);
-    if let Err(e) = std::fs::write(temp_dir.join("Cargo.toml"), &cargo_toml) {
-        return (false, format!("write Cargo.toml: {e}"));
-    }
-
-    // Write main.rs
-    let main_rs = generate_main_rs(block);
-    if let Err(e) = std::fs::write(src_dir.join("main.rs"), &main_rs) {
-        return (false, format!("write main.rs: {e}"));
-    }
-
-    // Build with release (single run via shared macro)
-    let manifest_path = temp_dir.join("Cargo.toml");
-    match run_cmd_and_capture_stderr!(
-        "cargo build --release --manifest-path {}",
-        manifest_path.to_string_lossy()
-    ) {
-        Ok(_) => (true, String::new()),
-        Err((code, log)) => {
-            let mut last_lines: Vec<&str> = log.lines().rev().take(20).collect();
-            last_lines.reverse();
-            let detail = last_lines.join("\n");
-            (false, format!("exit code {code}\n{detail}"))
-        }
-    }
-}
-
-/// Write the .temp/README-TEST-RESULT.md summary report
-fn write_summary_report(
-    path: &Path,
-    results: &[(usize, bool, String)],
-    total: usize,
-    passed: usize,
-    failed: usize,
-) {
-    let mut content = String::new();
-    content.push_str("# README Code Block Test Report\n\n");
-    content.push_str(&format!(
-        "Tested **{total}** code blocks: **{passed}** passed, **{failed}** failed.\n\n"
-    ));
-    content.push_str("## Results\n\n");
-    content.push_str("| Block | Line | Status |\n");
-    content.push_str("|-------|------|--------|\n");
-
-    for (i, (line, ok, _)) in results.iter().enumerate() {
-        let status = if *ok { "PASS" } else { "FAIL" };
-        content.push_str(&format!("| {} | {} | {status} |\n", i + 1, line));
-    }
-
-    let has_failures = results.iter().any(|(_, ok, _)| !ok);
-    if has_failures {
-        content.push_str("\n## Failed Blocks\n\n");
-        for (i, (line, ok, err)) in results.iter().enumerate() {
-            if !ok {
-                content.push_str(&format!(
-                    "### Block {} (line {})\n\n```\n{err}\n```\n\n",
-                    i + 1,
-                    line
-                ));
-            }
-        }
-    }
-
-    std::fs::write(path, &content).unwrap_or_else(|e| {
-        eprintln!("Warning: failed to write {path:?}: {e}");
-    });
-
-    println_cargo_style!("Report: written to {}", path.display());
-}