wsb 0.258.6441

pub mod families;
pub mod report;
pub mod scan;

use std::collections::{BTreeMap, HashMap};
use std::fmt::Write as FmtWrite;
use std::fs;
use std::path::{Path, PathBuf};

// =============================================================================
// DATA
// =============================================================================

#[derive(Debug, Clone)]
pub struct TestInfo {
    pub number: Option<String>,
    pub function_name: String,
    pub description: String,
    pub file_path: PathBuf,
    pub line_number: usize,
}

impl TestInfo {
    fn is_numbered(&self) -> bool {
        self.number.is_some()
    }

    fn description_number(&self) -> Option<String> {
        let trimmed = self.description.trim();
        let re = regex::Regex::new(r"^TEST(\d+):").unwrap();
        re.captures(trimmed).map(|c| c[1].to_string())
    }
}

// =============================================================================
// PROJECT DETECTION
// =============================================================================

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProjectType {
    Rust,
    Go,
    Python,
    Js,
    Swift,
    /// The differential suites under `scripts/tests/`. They are tests by every
    /// measure that matters — numbered, announced, and the thing wsb is held to
    /// — and nothing had ever catalogued one of them.
    Shell,
}

impl ProjectType {
    pub fn detect(root: &Path) -> Result<Self, String> {
        if root.join("Cargo.toml").exists() {
            return Ok(ProjectType::Rust);
        }
        if root.join("go.mod").exists() {
            return Ok(ProjectType::Go);
        }
        if root.join("pyproject.toml").exists() {
            return Ok(ProjectType::Python);
        }
        if root.join("package.json").exists() {
            return Ok(ProjectType::Js);
        }
        if root.join("Package.swift").exists() {
            return Ok(ProjectType::Swift);
        }
        Err(format!(
            "Cannot detect project type in {} — no Cargo.toml, go.mod, \
             pyproject.toml, package.json, or Package.swift found",
            root.display()
        ))
    }

    pub fn label(self) -> &'static str {
        match self {
            ProjectType::Rust => "Rust",
            ProjectType::Go => "Go",
            ProjectType::Python => "Python",
            ProjectType::Js => "JS",
            ProjectType::Swift => "Swift/ObjC",
            ProjectType::Shell => "Shell",
        }
    }
}

// =============================================================================
// EXTRACTION HELPERS
// =============================================================================

fn extract_comments_above(lines: &[&str], fn_line_idx: usize, comment_prefix: &str) -> String {
    if fn_line_idx == 0 {
        return String::new();
    }
    let mut j = fn_line_idx as isize - 1;

    // Skip blank lines and Rust attribute lines (#[...])
    while j >= 0
        && (lines[j as usize].trim().is_empty() || lines[j as usize].trim().starts_with("#["))
    {
        j -= 1;
    }

    let mut parts: Vec<String> = Vec::new();
    while j >= 0 && lines[j as usize].trim().starts_with(comment_prefix) {
        let raw = lines[j as usize].trim();
        // Strip the whole comment marker, not a fixed number of characters.
        // `///` is `//` plus one more `/`, and cutting exactly two left every
        // Rust doc comment reading `/ TEST8901: …` — which no longer matches
        // `^TEST\d+:`, so the name↔description check silently passed on all 392
        // of them. Same for `//!` and for `##`.
        let text = raw
            .trim_start_matches(comment_prefix.chars().next().expect("empty comment prefix"))
            .trim_start_matches('!')
            .trim()
            .to_string();
        parts.insert(0, text);
        j -= 1;
    }

    // If there's a numbered TEST line in the block, keep only from that line onward.
    let test_re = regex::Regex::new(r"^TEST\d+:").unwrap();
    if let Some(numbered_idx) = parts.iter().position(|p| test_re.is_match(p)) {
        parts = parts[numbered_idx..].to_vec();
    }

    // Strip separator lines (===, ---, ###)
    let sep_re = regex::Regex::new(r"^[=\-#]{3,}$").unwrap();
    parts.retain(|p| !p.is_empty() && !sep_re.is_match(p));

    // Collapse continuation that duplicates first line
    if parts.len() > 1 {
        let continuation = parts[1..].join(" ");
        if !continuation.is_empty() && parts[0].contains(&continuation) {
            parts.truncate(1);
        }
    }

    parts.join(" ")
}

fn extract_python_docstring(lines: &[&str], fn_line_idx: usize) -> String {
    let mut i = fn_line_idx + 1;
    while i < lines.len() && lines[i].trim().is_empty() {
        i += 1;
    }
    if i >= lines.len() {
        return String::new();
    }
    let stripped = lines[i].trim();
    let test_re = regex::Regex::new(r"^TEST\d+:").unwrap();
    for quote in &[r#"""""#, "'''"] {
        if let Some(after) = stripped.strip_prefix(quote) {
            if let Some(end) = after.find(quote) {
                let content = after[..end].trim();
                if test_re.is_match(content) {
                    return content.to_string();
                }
            }
        }
    }
    String::new()
}

fn parse_number(function_name: &str, pattern: &regex::Regex) -> Option<String> {
    pattern.captures(function_name).map(|c| c[1].to_string())
}

// =============================================================================
// EXTRACTION — language-specific
// =============================================================================

/// Blank out the contents of Rust string literals, keeping line structure.
///
/// The scanner reads lines, and a line inside a string literal looks exactly
/// like a line of code. This crate's own catalogue tests hold fixtures like a
/// `#[test]` above a `struct`, inside a raw string, and reading those as source
/// made scanning the workspace fail on a file whose contents are correct.
///
/// Blanking the literal is what lets the parse failure stay fatal where it
/// means something: an attribute in real code that is not followed by a
/// function IS a defect, and skipping it quietly is how a test stops being
/// catalogued without anyone noticing.
///
/// Characters are replaced with spaces rather than removed, so every line
/// number the scanner reports is still the line number in the file.
fn blank_string_literals(source: &str) -> String {
    let chars: Vec<char> = source.chars().collect();
    let mut out: Vec<char> = Vec::with_capacity(chars.len());
    let mut index = 0;

    while index < chars.len() {
        let c = chars[index];

        // A line comment runs to the end of the line, contents and all — a
        // quote inside it starts nothing, and the description scraper needs it.
        if c == '/' && chars.get(index + 1) == Some(&'/') {
            while index < chars.len() && chars[index] != '\n' {
                out.push(chars[index]);
                index += 1;
            }
            continue;
        }

        // A raw string: r, any number of #, then a quote. It ends at a quote
        // followed by the same number of #.
        if c == 'r' {
            let mut hashes = 0;
            let mut probe = index + 1;
            while chars.get(probe) == Some(&'#') {
                hashes += 1;
                probe += 1;
            }
            if chars.get(probe) == Some(&'"') {
                out.push('r');
                for _ in 0..hashes {
                    out.push('#');
                }
                out.push('"');
                index = probe + 1;
                while index < chars.len() {
                    let closes = chars[index] == '"'
                        && (1..=hashes).all(|n| chars.get(index + n) == Some(&'#'));
                    if closes {
                        out.push('"');
                        for _ in 0..hashes {
                            out.push('#');
                        }
                        index += 1 + hashes;
                        break;
                    }
                    out.push(if chars[index] == '\n' { '\n' } else { ' ' });
                    index += 1;
                }
                continue;
            }
        }

        // A character literal. `'"'` is a quote that starts no string: read as
        // one, it opened a "string" that closed at the next real quote, every
        // quote after it was read the wrong way round, and the tests below it
        // were blanked — QuickRust's `trim_matches('"')` hid six of its tests
        // from the catalogue. A literal is one character (`'x'`) or an escape
        // (`'\''`, `'\\'`, `'\u{1F600}'`) between quotes; a lifetime or a loop
        // label (`'a`) has no closing quote two characters on, and is left as
        // it is.
        if c == '\'' {
            let close = if chars.get(index + 1) == Some(&'\\') {
                let mut probe = index + 3;
                while probe < chars.len() && chars[probe] != '\'' && chars[probe] != '\n' {
                    probe += 1;
                }
                (chars.get(probe) == Some(&'\'')).then_some(probe)
            } else if chars.get(index + 1).is_some_and(|inner| *inner != '\n')
                && chars.get(index + 2) == Some(&'\'')
            {
                Some(index + 2)
            } else {
                None
            };
            if let Some(close) = close {
                out.push('\'');
                for _ in index + 1..close {
                    out.push(' ');
                }
                out.push('\'');
                index = close + 1;
                continue;
            }
        }

        // An ordinary string, honouring backslash escapes.
        if c == '"' {
            out.push('"');
            index += 1;
            while index < chars.len() {
                if chars[index] == '\\' {
                    out.push(' ');
                    if index + 1 < chars.len() {
                        out.push(if chars[index + 1] == '\n' { '\n' } else { ' ' });
                    }
                    index += 2;
                    continue;
                }
                if chars[index] == '"' {
                    out.push('"');
                    index += 1;
                    break;
                }
                out.push(if chars[index] == '\n' { '\n' } else { ' ' });
                index += 1;
            }
            continue;
        }

        out.push(c);
        index += 1;
    }

    out.into_iter().collect()
}

pub fn extract_rust(file_path: &Path) -> Result<Vec<TestInfo>, String> {
    let content = fs::read_to_string(file_path)
        .map_err(|e| format!("Could not read {}: {}", file_path.display(), e))?;
    let content = blank_string_literals(&content);
    let raw_lines: Vec<&str> = content.lines().collect();

    let test_attr_re =
        regex::Regex::new(r"^\s*#\[(?:tokio::)?test(?:\([^\]]*\))?\]\s*(?://.*)?$").unwrap();
    let any_attr_re = regex::Regex::new(r"^\s*#\[[^\]]+\]\s*(?://.*)?$").unwrap();
    let fn_re =
        regex::Regex::new(r"^\s*(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(")
            .unwrap();
    let number_re = regex::Regex::new(r"^test(\d+)_").unwrap();

    let mut tests = Vec::new();
    let mut i = 0;
    while i < raw_lines.len() {
        if !test_attr_re.is_match(raw_lines[i]) {
            i += 1;
            continue;
        }
        let attr_line = i + 1; // 1-based for errors
        let mut j = i + 1;
        while j < raw_lines.len()
            && (raw_lines[j].trim().is_empty()
                || raw_lines[j].trim().starts_with("//")
                || any_attr_re.is_match(raw_lines[j]))
        {
            j += 1;
        }
        if j >= raw_lines.len() {
            return Err(format!(
                "{}:{}: test attribute is not followed by a function",
                file_path.display(),
                attr_line
            ));
        }
        let fn_match = fn_re.captures(raw_lines[j]).ok_or_else(|| {
            format!(
                "{}:{}: test attribute is followed by a non-function line: {:?}",
                file_path.display(),
                attr_line,
                raw_lines[j]
            )
        })?;
        let function_name = fn_match[1].to_string();
        tests.push(TestInfo {
            number: parse_number(&function_name, &number_re),
            description: extract_comments_above(&raw_lines, j, "//"),
            file_path: file_path.to_path_buf(),
            line_number: j + 1,
            function_name,
        });
        i = j + 1;
    }
    Ok(tests)
}

pub fn extract_go(file_path: &Path) -> Result<Vec<TestInfo>, String> {
    let content = fs::read_to_string(file_path)
        .map_err(|e| format!("Could not read {}: {}", file_path.display(), e))?;
    let raw_lines: Vec<&str> = content.lines().collect();
    let fn_re = regex::Regex::new(r"^\s*func\s+(Test[A-Za-z0-9_]+)\s*\(").unwrap();
    let number_re = regex::Regex::new(r"^Test(\d+)_").unwrap();

    let mut tests = Vec::new();
    for (i, &line) in raw_lines.iter().enumerate() {
        if let Some(cap) = fn_re.captures(line) {
            let function_name = cap[1].to_string();
            tests.push(TestInfo {
                number: parse_number(&function_name, &number_re),
                description: extract_comments_above(&raw_lines, i, "//"),
                file_path: file_path.to_path_buf(),
                line_number: i + 1,
                function_name,
            });
        }
    }
    Ok(tests)
}

pub fn extract_python(file_path: &Path) -> Result<Vec<TestInfo>, String> {
    let content = fs::read_to_string(file_path)
        .map_err(|e| format!("Could not read {}: {}", file_path.display(), e))?;
    let raw_lines: Vec<&str> = content.lines().collect();
    let fn_re = regex::Regex::new(r"^\s*(?:async\s+)?def\s+(test_[A-Za-z0-9_]+)\s*\(").unwrap();
    let number_re = regex::Regex::new(r"^test_(\d+)_").unwrap();
    let decorator_re = regex::Regex::new(r"^\s*@").unwrap();

    let mut tests = Vec::new();
    for (i, &line) in raw_lines.iter().enumerate() {
        if let Some(cap) = fn_re.captures(line) {
            let function_name = cap[1].to_string();
            // Walk back past blank lines and decorators to find comments
            let mut comment_idx = i;
            while comment_idx > 0
                && (raw_lines[comment_idx - 1].trim().is_empty()
                    || decorator_re.is_match(raw_lines[comment_idx - 1]))
            {
                comment_idx -= 1;
            }
            let description = {
                let ds = extract_python_docstring(&raw_lines, i);
                if ds.is_empty() {
                    extract_comments_above(&raw_lines, comment_idx, "#")
                } else {
                    ds
                }
            };
            tests.push(TestInfo {
                number: parse_number(&function_name, &number_re),
                description,
                file_path: file_path.to_path_buf(),
                line_number: i + 1,
                function_name,
            });
        }
    }
    Ok(tests)
}

pub fn extract_js(file_path: &Path) -> Result<Vec<TestInfo>, String> {
    let content = fs::read_to_string(file_path)
        .map_err(|e| format!("Could not read {}: {}", file_path.display(), e))?;
    let raw_lines: Vec<&str> = content.lines().collect();
    // A test function is declared plain or `async`: a suite that awaits its
    // tests declares them async, and a reader that saw only the plain ones
    // would leave those out of the catalogue without a word.
    let fn_re = regex::Regex::new(r"^\s*(?:async\s+)?function\s+(test[A-Za-z0-9_]+)\s*\(").unwrap();
    // The runner forms: `test("…", …)` and `it("…", …)`, node:test and vitest
    // alike. These declare no function, so the title IS the test's name — which
    // is also where a number would be written if one were claimed.
    let title_re =
        regex::Regex::new(r#"^\s*(?:it|test)\s*\(\s*["'`](.+?)["'`]\s*,"#).unwrap();
    let number_re = regex::Regex::new(r"^test(\d+)_").unwrap();
    let title_number_re = regex::Regex::new(r"^TEST(\d+)\b").unwrap();

    let mut tests = Vec::new();
    for (i, &line) in raw_lines.iter().enumerate() {
        if let Some(cap) = fn_re.captures(line) {
            let function_name = cap[1].to_string();
            tests.push(TestInfo {
                number: parse_number(&function_name, &number_re),
                description: extract_comments_above(&raw_lines, i, "//"),
                file_path: file_path.to_path_buf(),
                line_number: i + 1,
                function_name,
            });
        } else if let Some(cap) = title_re.captures(line) {
            let title = cap[1].to_string();
            let number = title_number_re.captures(&title).map(|c| c[1].to_string());
            let description = {
                let above = extract_comments_above(&raw_lines, i, "//");
                if above.is_empty() {
                    title.clone()
                } else {
                    above
                }
            };
            tests.push(TestInfo {
                number,
                description,
                file_path: file_path.to_path_buf(),
                line_number: i + 1,
                function_name: title,
            });
        }
    }
    Ok(tests)
}

/// Every numbered assertion a shell suite announces.
///
/// A suite announces each test as it reaches it — `echo "TEST9490 — …"` — and
/// that line is the assertion's identity: its number, its description, and the
/// point in the file it happens at, all in one place. There is no function to
/// read a name from, so the announcement is the name.
///
/// Only announcements at the start of a line count. The suites also list their
/// numbers in a header comment and refer to other tests mid-explanation, and
/// counting those would report the same test three times.
pub fn extract_shell(file_path: &Path) -> Result<Vec<TestInfo>, String> {
    let content = fs::read_to_string(file_path)
        .map_err(|e| format!("Could not read {}: {}", file_path.display(), e))?;
    let announce_re =
        regex::Regex::new(r#"^echo\s+"TEST(\d+)\s*(?:—|--|-)?\s*(.*?)"\s*$"#).unwrap();

    let mut tests = Vec::new();
    for (i, line) in content.lines().enumerate() {
        let Some(cap) = announce_re.captures(line) else {
            continue;
        };
        let number = cap[1].to_string();
        tests.push(TestInfo {
            function_name: format!("TEST{number}"),
            number: Some(number),
            description: cap[2].trim().to_string(),
            file_path: file_path.to_path_buf(),
            line_number: i + 1,
        });
    }
    Ok(tests)
}

pub fn extract_swift(file_path: &Path) -> Result<Vec<TestInfo>, String> {
    let content = fs::read_to_string(file_path)
        .map_err(|e| format!("Could not read {}: {}", file_path.display(), e))?;
    let raw_lines: Vec<&str> = content.lines().collect();
    let fn_re = regex::Regex::new(r"^\s*func\s+(test[A-Za-z0-9_]+)\s*\(").unwrap();
    let number_re = regex::Regex::new(r"^test(\d+)_").unwrap();

    let mut tests = Vec::new();
    for (i, &line) in raw_lines.iter().enumerate() {
        if let Some(cap) = fn_re.captures(line) {
            let function_name = cap[1].to_string();
            tests.push(TestInfo {
                number: parse_number(&function_name, &number_re),
                description: extract_comments_above(&raw_lines, i, "//"),
                file_path: file_path.to_path_buf(),
                line_number: i + 1,
                function_name,
            });
        }
    }
    Ok(tests)
}

pub fn extract_objc(file_path: &Path) -> Result<Vec<TestInfo>, String> {
    let content = fs::read_to_string(file_path)
        .map_err(|e| format!("Could not read {}: {}", file_path.display(), e))?;
    let raw_lines: Vec<&str> = content.lines().collect();
    let fn_re = regex::Regex::new(r"^\s*-\s*\(void\)\s*(test[A-Za-z0-9_]+)\s*\{").unwrap();
    let number_re = regex::Regex::new(r"^test(\d+)_").unwrap();

    let mut tests = Vec::new();
    for (i, &line) in raw_lines.iter().enumerate() {
        if let Some(cap) = fn_re.captures(line) {
            let function_name = cap[1].to_string();
            tests.push(TestInfo {
                number: parse_number(&function_name, &number_re),
                description: extract_comments_above(&raw_lines, i, "//"),
                file_path: file_path.to_path_buf(),
                line_number: i + 1,
                function_name,
            });
        }
    }
    Ok(tests)
}

// =============================================================================
// SCANNING
// =============================================================================

/// Directories that hold no source of ours.
///
/// Build output and vendored dependencies contain thousands of test functions
/// belonging to other people. Counting them does not make the catalogue more
/// complete, it makes it wrong.
const NOT_OURS: &[&str] = &[
    "target",
    "node_modules",
    ".git",
    ".scrap",
    ".build",
    "build",
    "dist",
    "logs",
    "vendor",
    ".venv",
    "__pycache__",
];

/// The language a file is a test in, or `None` if it is not one.
///
/// Named by file rather than by project, because a repository is not written in
/// one language: this workspace's Rust crates ship shell suites, and its Swift
/// app ships Objective-C tests. Asking each repository to declare a single type
/// is what made the shell suites — 191 numbered assertions, the ones wsb itself
/// is held to — invisible to every tool that has ever counted tests here.
pub fn language_of_path(path: &Path) -> Option<ProjectType> {
    let name = path.file_name()?.to_string_lossy().to_string();
    // An AppleDouble sidecar. macOS writes `._Foo.swift` beside `Foo.swift`
    // whenever a tree crosses a filesystem that cannot hold a resource fork —
    // a tar to the Mac build host and back is enough — and it carries the
    // source file's name with two characters in front of it, so every rule
    // below matches it. It holds binary, so reading it as source ended the
    // whole scan with "stream did not contain valid UTF-8" and left the
    // catalogue table empty.
    if name.starts_with("._") {
        return None;
    }
    if name.ends_with(".rs") {
        return Some(ProjectType::Rust);
    }
    if name.ends_with("_test.go") {
        return Some(ProjectType::Go);
    }
    if name.starts_with("test_") && name.ends_with(".py") {
        return Some(ProjectType::Python);
    }
    if [".test.js", ".test.ts", ".test.cjs", ".test.mjs"]
        .iter()
        .any(|suffix| name.ends_with(suffix))
    {
        return Some(ProjectType::Js);
    }
    if name.ends_with(".swift") || name.ends_with(".m") {
        return Some(ProjectType::Swift);
    }
    if name.starts_with("test-") && name.ends_with(".sh") {
        return Some(ProjectType::Shell);
    }
    None
}

/// Every test in a tree, in every language it is written in.
pub fn scan_tree(root: &Path) -> Result<Vec<TestInfo>, String> {
    let mut all_tests = Vec::new();
    for entry in walkdir::WalkDir::new(root)
        .into_iter()
        .filter_entry(|e| {
            !NOT_OURS.contains(&e.file_name().to_string_lossy().as_ref()) || e.depth() == 0
        })
    {
        let entry = entry.map_err(|e| e.to_string())?;
        if !entry.file_type().is_file() {
            continue;
        }
        let path = entry.path();
        let Some(language) = language_of_path(path) else {
            continue;
        };
        let found = match language {
            ProjectType::Rust => extract_rust(path)?,
            ProjectType::Go => extract_go(path)?,
            ProjectType::Python => extract_python(path)?,
            ProjectType::Js => extract_js(path)?,
            ProjectType::Swift => {
                if path.extension().is_some_and(|e| e == "m") {
                    extract_objc(path)?
                } else {
                    extract_swift(path)?
                }
            }
            ProjectType::Shell => extract_shell(path)?,
        };
        all_tests.extend(found);
    }
    Ok(all_tests)
}

pub fn scan_project(root: &Path, project_type: ProjectType) -> Result<Vec<TestInfo>, String> {
    let mut all_tests = Vec::new();

    match project_type {
        ProjectType::Rust => {
            for entry in walkdir::WalkDir::new(root)
                .into_iter()
                .filter_entry(|e| e.file_name() != "target" && e.file_name() != ".scrap")
            {
                let entry = entry.map_err(|e| e.to_string())?;
                if entry.path().extension().map(|x| x == "rs").unwrap_or(false) {
                    all_tests.extend(extract_rust(entry.path())?);
                }
            }
        }
        ProjectType::Go => {
            for entry in walkdir::WalkDir::new(root).into_iter() {
                let entry = entry.map_err(|e| e.to_string())?;
                let name = entry.file_name().to_string_lossy();
                if name.ends_with("_test.go") {
                    all_tests.extend(extract_go(entry.path())?);
                }
            }
        }
        ProjectType::Python => {
            for entry in walkdir::WalkDir::new(root).into_iter() {
                let entry = entry.map_err(|e| e.to_string())?;
                let name = entry.file_name().to_string_lossy();
                if name.starts_with("test_") && name.ends_with(".py") {
                    all_tests.extend(extract_python(entry.path())?);
                }
            }
        }
        ProjectType::Js => {
            for entry in walkdir::WalkDir::new(root)
                .into_iter()
                .filter_entry(|e| e.file_name() != "node_modules")
            {
                let entry = entry.map_err(|e| e.to_string())?;
                let name = entry.file_name().to_string_lossy();
                // Every extension the runners accept. The glob was `.test.js`
                // alone, so every TypeScript and ESM suite in the workspace
                // reported zero tests and read as "this repo has none".
                if [".test.js", ".test.ts", ".test.cjs", ".test.mjs"]
                    .iter()
                    .any(|suffix| name.ends_with(suffix))
                {
                    all_tests.extend(extract_js(entry.path())?);
                }
            }
        }
        ProjectType::Swift => {
            for entry in walkdir::WalkDir::new(root)
                .into_iter()
                .filter_entry(|e| e.file_name() != ".build" && e.file_name() != ".scrap")
            {
                let entry = entry.map_err(|e| e.to_string())?;
                let name = entry.file_name().to_string_lossy();
                if name.ends_with(".swift") {
                    all_tests.extend(extract_swift(entry.path())?);
                } else if name.ends_with(".m") {
                    all_tests.extend(extract_objc(entry.path())?);
                }
            }
        }
        ProjectType::Shell => {
            for entry in walkdir::WalkDir::new(root).into_iter() {
                let entry = entry.map_err(|e| e.to_string())?;
                let name = entry.file_name().to_string_lossy();
                if name.starts_with("test-") && name.ends_with(".sh") {
                    all_tests.extend(extract_shell(entry.path())?);
                }
            }
        }
    }

    Ok(all_tests)
}

// =============================================================================
// DUPLICATES + FREE NUMBER SUGGESTIONS
// =============================================================================

fn find_duplicates(tests: &[TestInfo]) -> BTreeMap<String, Vec<&TestInfo>> {
    let mut by_number: BTreeMap<String, Vec<&TestInfo>> = BTreeMap::new();
    for test in tests {
        if let Some(ref n) = test.number {
            by_number.entry(n.clone()).or_default().push(test);
        }
    }
    by_number.retain(|_, v| v.len() > 1);
    by_number
}

fn suggest_free_numbers(
    duplicates: &BTreeMap<String, Vec<&TestInfo>>,
    all_tests: &[TestInfo],
) -> HashMap<String, Vec<u64>> {
    let taken: std::collections::HashSet<u64> = all_tests
        .iter()
        .filter_map(|t| t.number.as_ref())
        .filter_map(|n| n.parse::<u64>().ok())
        .collect();

    let mut reserved: std::collections::HashSet<u64> = std::collections::HashSet::new();
    let mut suggestions: HashMap<String, Vec<u64>> = HashMap::new();

    let mut sorted_keys: Vec<(&String, u64)> = duplicates
        .keys()
        .filter_map(|k| k.parse::<u64>().ok().map(|n| (k, n)))
        .collect();
    sorted_keys.sort_by_key(|(_, n)| *n);

    for (number, n) in sorted_keys {
        let needed = duplicates[number].len() - 1;
        let mut found: Vec<u64> = Vec::new();
        let mut delta: u64 = 1;
        while found.len() < needed {
            for candidate in [n + delta, n.saturating_sub(delta)] {
                if candidate == 0 {
                    continue;
                }
                if taken.contains(&candidate) || reserved.contains(&candidate) {
                    continue;
                }
                found.push(candidate);
                reserved.insert(candidate);
                if found.len() == needed {
                    break;
                }
            }
            delta += 1;
        }
        suggestions.insert(number.clone(), found);
    }

    suggestions
}

fn find_numbering_mismatches(tests: &[TestInfo]) -> Vec<&TestInfo> {
    let mut mismatches: Vec<&TestInfo> = tests
        .iter()
        .filter(|t| {
            t.description_number()
                .map(|dn| Some(dn) != t.number)
                .unwrap_or(false)
        })
        .collect();
    mismatches.sort_by(|a, b| {
        let an = a
            .number
            .as_ref()
            .and_then(|n| n.parse::<u64>().ok())
            .unwrap_or(u64::MAX);
        let bn = b
            .number
            .as_ref()
            .and_then(|n| n.parse::<u64>().ok())
            .unwrap_or(u64::MAX);
        an.cmp(&bn).then(a.function_name.cmp(&b.function_name))
    });
    mismatches
}

// =============================================================================
// RELATIVE PATH HELPER
// =============================================================================

fn rel_location(test: &TestInfo, proj_root: &Path) -> Result<String, String> {
    let rel = test.file_path.strip_prefix(proj_root).map_err(|_| {
        format!(
            "Test path {} is outside the project root {}",
            test.file_path.display(),
            proj_root.display()
        )
    })?;
    Ok(format!("{}:{}", rel.display(), test.line_number))
}

// =============================================================================
// MARKDOWN GENERATION
// =============================================================================

pub fn generate_markdown(
    tests: &[TestInfo],
    project_type: ProjectType,
    proj_root: &Path,
) -> Result<String, String> {
    let duplicates = find_duplicates(tests);
    let duplicate_numbers: std::collections::HashSet<&String> = duplicates.keys().collect();
    let suggestions = if duplicates.is_empty() {
        HashMap::new()
    } else {
        suggest_free_numbers(&duplicates, tests)
    };

    let numbered_tests: Vec<&TestInfo> = tests.iter().filter(|t| t.is_numbered()).collect();
    let unnumbered_tests: Vec<&TestInfo> = tests.iter().filter(|t| !t.is_numbered()).collect();
    let numbered_missing_desc: Vec<&TestInfo> = numbered_tests
        .iter()
        .filter(|t| t.description.trim().is_empty())
        .copied()
        .collect();
    let numbering_mismatches = find_numbering_mismatches(tests);

    let mut unique_numbered: Vec<&TestInfo> = numbered_tests
        .iter()
        .filter(|t| !duplicate_numbers.contains(t.number.as_ref().unwrap()))
        .copied()
        .collect();
    unique_numbered.sort_by(|a, b| {
        let an = a
            .number
            .as_ref()
            .unwrap()
            .parse::<u64>()
            .unwrap_or(u64::MAX);
        let bn = b
            .number
            .as_ref()
            .unwrap()
            .parse::<u64>()
            .unwrap_or(u64::MAX);
        an.cmp(&bn).then(a.function_name.cmp(&b.function_name))
    });

    let mut duplicate_entries: Vec<&TestInfo> = numbered_tests
        .iter()
        .filter(|t| duplicate_numbers.contains(t.number.as_ref().unwrap()))
        .copied()
        .collect();
    duplicate_entries.sort_by(|a, b| {
        let an = a
            .number
            .as_ref()
            .unwrap()
            .parse::<u64>()
            .unwrap_or(u64::MAX);
        let bn = b
            .number
            .as_ref()
            .unwrap()
            .parse::<u64>()
            .unwrap_or(u64::MAX);
        an.cmp(&bn).then(a.function_name.cmp(&b.function_name))
    });

    let mut sorted_unnumbered: Vec<&TestInfo> = unnumbered_tests.clone();
    sorted_unnumbered.sort_by(|a, b| {
        a.function_name
            .cmp(&b.function_name)
            .then(a.file_path.cmp(&b.file_path))
            .then(a.line_number.cmp(&b.line_number))
    });

    let label = project_type.label();
    let mut out = String::new();

    writeln!(out, "# {} Test Catalog\n", label).unwrap();
    writeln!(out, "**Total Tests:** {}\n", tests.len()).unwrap();
    writeln!(out, "**Numbered Tests:** {}\n", numbered_tests.len()).unwrap();
    writeln!(out, "**Unnumbered Tests:** {}\n", unnumbered_tests.len()).unwrap();
    writeln!(
        out,
        "**Numbered Tests Missing Descriptions:** {}\n",
        numbered_missing_desc.len()
    )
    .unwrap();
    writeln!(
        out,
        "**Numbering Mismatches:** {}\n",
        numbering_mismatches.len()
    )
    .unwrap();

    if !duplicates.is_empty() {
        writeln!(
            out,
            "**⚠ Duplicate test numbers detected: {} number(s) used more than once.**",
            duplicates.len()
        )
        .unwrap();
        writeln!(
            out,
            "Unique numbered tests are listed first. Duplicate-number entries are grouped \
             after them and marked with ⚠. Unnumbered tests are listed in their own group.\n"
        )
        .unwrap();
    } else {
        writeln!(out, "All numbered test numbers are unique.\n").unwrap();
    }

    writeln!(
        out,
        "This catalog lists all tests in the {} codebase.\n",
        label
    )
    .unwrap();
    writeln!(out, "| Test # | Function Name | Description | File |").unwrap();
    writeln!(out, "|--------|---------------|-------------|------|").unwrap();

    let write_row = |out: &mut String, test: &TestInfo, flag: &str| -> Result<(), String> {
        let description = test.description.replace('|', "\\|");
        let location = rel_location(test, proj_root)?.replace('|', "\\|");
        let test_label = match &test.number {
            Some(n) => format!("test{}", n),
            None => "unnumbered".to_string(),
        };
        writeln!(
            out,
            "| {}{} | `{}` | {} | {} |",
            test_label, flag, test.function_name, description, location
        )
        .unwrap();
        Ok(())
    };

    for test in &unique_numbered {
        write_row(&mut out, test, "")?;
    }

    if !duplicate_entries.is_empty() {
        writeln!(out, "| | | | |").unwrap();
        for test in &duplicate_entries {
            write_row(&mut out, test, " ⚠")?;
        }
    }

    if !sorted_unnumbered.is_empty() {
        writeln!(out, "| | | | |").unwrap();
        for test in &sorted_unnumbered {
            write_row(&mut out, test, "")?;
        }
    }

    if !duplicates.is_empty() {
        writeln!(out, "\n---\n\n## ⚠ Duplicate Test Numbers\n").unwrap();
        writeln!(
            out,
            "The following test numbers are assigned to more than one function. \
             Keep the first occurrence at the existing number and renumber the rest \
             using the suggested free numbers below.\n"
        )
        .unwrap();
        let mut sorted_dup_keys: Vec<&String> = duplicates.keys().collect();
        sorted_dup_keys.sort_by_key(|k| k.parse::<u64>().unwrap_or(u64::MAX));
        for number in sorted_dup_keys {
            let mut entries: Vec<&&TestInfo> = duplicates[number].iter().collect();
            entries.sort_by_key(|t| &t.function_name);
            let free = &suggestions[number];
            writeln!(out, "### test{} ({} occurrences)\n", number, entries.len()).unwrap();
            for entry in &entries {
                writeln!(
                    out,
                    "- `{}` — {}",
                    entry.function_name,
                    rel_location(entry, proj_root)?
                )
                .unwrap();
            }
            let suggested_str: Vec<String> = free.iter().map(|n| format!("test{}", n)).collect();
            writeln!(
                out,
                "\n**Suggested free number(s):** {}\n",
                suggested_str.join(", ")
            )
            .unwrap();
        }
    }

    if !sorted_unnumbered.is_empty() {
        writeln!(out, "---\n\n## Unnumbered Tests\n").unwrap();
        writeln!(
            out,
            "The following tests are cataloged but do not currently participate in numeric \
             test indexing.\n"
        )
        .unwrap();
        for test in &sorted_unnumbered {
            writeln!(
                out,
                "- `{}` — {}",
                test.function_name,
                rel_location(test, proj_root)?
            )
            .unwrap();
        }
        writeln!(out).unwrap();
    }

    if !numbered_missing_desc.is_empty() {
        writeln!(out, "---\n\n## Numbered Tests Missing Descriptions\n").unwrap();
        writeln!(
            out,
            "These tests still participate in numeric indexing, but the cataloger did not \
             find an authoritative immediate comment/docstring description for them. \
             This is reported explicitly so intentional blank-description parity and \
             accidental comment drift are both visible.\n"
        )
        .unwrap();
        let mut sorted_missing = numbered_missing_desc.clone();
        sorted_missing.sort_by(|a, b| {
            let an = a
                .number
                .as_ref()
                .unwrap()
                .parse::<u64>()
                .unwrap_or(u64::MAX);
            let bn = b
                .number
                .as_ref()
                .unwrap()
                .parse::<u64>()
                .unwrap_or(u64::MAX);
            an.cmp(&bn).then(a.function_name.cmp(&b.function_name))
        });
        for test in sorted_missing {
            writeln!(
                out,
                "- `test{}` / `{}` — {}",
                test.number.as_ref().unwrap(),
                test.function_name,
                rel_location(test, proj_root)?
            )
            .unwrap();
        }
        writeln!(out).unwrap();
    }

    if !numbering_mismatches.is_empty() {
        writeln!(out, "---\n\n## Numbering Mismatches\n").unwrap();
        writeln!(
            out,
            "These tests have a numbering disagreement between the function name and the \
             authoritative immediate TEST comment/docstring above the test. This is reported \
             explicitly so comment sync does not silently overwrite a misnumbered test.\n"
        )
        .unwrap();
        for test in &numbering_mismatches {
            let function_number = test
                .number
                .as_ref()
                .map(|n| format!("test{}", n))
                .unwrap_or_else(|| "unnumbered".to_string());
            let description_number = format!("test{}", test.description_number().unwrap());
            writeln!(
                out,
                "- `{}` / `{}` / `{}` — {}",
                function_number,
                description_number,
                test.function_name,
                rel_location(test, proj_root)?
            )
            .unwrap();
        }
        writeln!(out).unwrap();
    }

    writeln!(out, "---\n").unwrap();
    writeln!(out, "*Generated from {} source tree*", label).unwrap();
    writeln!(out, "*Total tests: {}*", tests.len()).unwrap();
    writeln!(out, "*Total numbered tests: {}*", numbered_tests.len()).unwrap();
    writeln!(out, "*Total unnumbered tests: {}*", unnumbered_tests.len()).unwrap();
    writeln!(
        out,
        "*Total numbered tests missing descriptions: {}*",
        numbered_missing_desc.len()
    )
    .unwrap();
    writeln!(
        out,
        "*Total numbering mismatches: {}*",
        numbering_mismatches.len()
    )
    .unwrap();

    Ok(out)
}

// =============================================================================
// CONSOLE SUMMARY
// =============================================================================

pub fn print_summary(tests: &[TestInfo], root: &Path, label: &str) -> Result<(), String> {
    let numbered: Vec<&TestInfo> = tests.iter().filter(|t| t.is_numbered()).collect();
    let unnumbered: Vec<&TestInfo> = tests.iter().filter(|t| !t.is_numbered()).collect();
    let missing_desc: Vec<&TestInfo> = numbered
        .iter()
        .filter(|t| t.description.trim().is_empty())
        .copied()
        .collect();
    let mismatches = find_numbering_mismatches(tests);
    let duplicates = find_duplicates(tests);
    let suggestions = if duplicates.is_empty() {
        HashMap::new()
    } else {
        suggest_free_numbers(&duplicates, tests)
    };

    crate::outln!("Project root : {}", root.display());
    crate::outln!("Project type : {}", label);
    crate::outln!("Scanning for tests...");
    crate::outln!("  Found {} tests", tests.len());
    crate::outln!("  Numbered   : {}", numbered.len());
    crate::outln!("  Unnumbered : {}", unnumbered.len());
    crate::outln!(
        "  Missing descriptions on numbered tests: {}",
        missing_desc.len()
    );
    crate::outln!("  Numbering mismatches              : {}", mismatches.len());

    let rel = |file_path: &Path| -> Result<String, String> {
        file_path
            .strip_prefix(root)
            .map(|p| p.display().to_string())
            .map_err(|_| {
                format!(
                    "Path {} is outside the project root {}",
                    file_path.display(),
                    root.display()
                )
            })
    };

    if !duplicates.is_empty() {
        crate::outln!(
            "\nWARNING: {} duplicate test number(s) detected:",
            duplicates.len()
        );
        let mut sorted_keys: Vec<&String> = duplicates.keys().collect();
        sorted_keys.sort_by_key(|k| k.parse::<u64>().unwrap_or(u64::MAX));
        for number in sorted_keys {
            let entries = &duplicates[number];
            let free = &suggestions[number];
            crate::outln!("  test{} used {} times:", number, entries.len());
            for entry in entries {
                crate::outln!(
                    "    {}  ({}:{})",
                    entry.function_name,
                    rel(&entry.file_path)?,
                    entry.line_number
                );
            }
            let free_str: Vec<String> = free.iter().map(|n| format!("test{}", n)).collect();
            crate::outln!("    → suggested free number(s): {}", free_str.join(", "));
        }
    } else {
        crate::outln!("All numbered test numbers are unique.");
    }

    if !unnumbered.is_empty() {
        crate::outln!("\nUnnumbered tests detected: {}", unnumbered.len());
        let mut sorted = unnumbered.clone();
        sorted.sort_by(|a, b| {
            a.function_name
                .cmp(&b.function_name)
                .then(a.file_path.cmp(&b.file_path))
                .then(a.line_number.cmp(&b.line_number))
        });
        for test in sorted {
            crate::outln!(
                "  {}  ({}:{})",
                test.function_name,
                rel(&test.file_path)?,
                test.line_number
            );
        }
    }

    if !missing_desc.is_empty() {
        crate::outln!(
            "\nNumbered tests missing descriptions: {}",
            missing_desc.len()
        );
        let mut sorted = missing_desc.clone();
        sorted.sort_by(|a, b| {
            let an = a
                .number
                .as_ref()
                .unwrap()
                .parse::<u64>()
                .unwrap_or(u64::MAX);
            let bn = b
                .number
                .as_ref()
                .unwrap()
                .parse::<u64>()
                .unwrap_or(u64::MAX);
            an.cmp(&bn).then(a.function_name.cmp(&b.function_name))
        });
        for test in sorted {
            crate::outln!(
                "  test{}  {}  ({}:{})",
                test.number.as_ref().unwrap(),
                test.function_name,
                rel(&test.file_path)?,
                test.line_number
            );
        }
    }

    if !mismatches.is_empty() {
        crate::outln!("\nNumbering mismatches: {}", mismatches.len());
        for test in &mismatches {
            let fn_num = test
                .number
                .as_ref()
                .map(|n| format!("test{}", n))
                .unwrap_or_else(|| "unnumbered".to_string());
            let desc_num = format!("test{}", test.description_number().unwrap());
            crate::outln!(
                "  {} vs {}  {}  ({}:{})",
                fn_num,
                desc_num,
                test.function_name,
                rel(&test.file_path)?,
                test.line_number
            );
        }
    }

    // Test range distribution
    let mut ranges: BTreeMap<u64, usize> = BTreeMap::new();
    for test in &numbered {
        if let Some(n) = test.number.as_ref().and_then(|n| n.parse::<u64>().ok()) {
            let century = (n / 100) * 100;
            *ranges.entry(century).or_insert(0) += 1;
        }
    }
    if !ranges.is_empty() {
        crate::outln!("\nNumbered test distribution by range:");
        for (century, count) in &ranges {
            crate::outln!("  {:03}-{:03}: {} tests", century, century + 99, count);
        }
    }

    Ok(())
}

// =============================================================================
// ENTRY POINT
// =============================================================================

pub fn run(root: &Path, output: Option<&Path>, quiet: bool) -> Result<(), String> {
    let project_type = match ProjectType::detect(root) {
        Ok(pt) => pt,
        Err(_) => {
            if !quiet {
                crate::outln!("  (no recognized project type at {})", root.display());
            }
            return Ok(());
        }
    };
    let tests = scan_project(root, project_type)?;
    if !quiet {
        print_summary(&tests, root, project_type.label())?;
    }

    let output_path = output
        .map(|p| p.to_path_buf())
        .unwrap_or_else(|| root.join("TEST_CATALOG.md"));

    let markdown = generate_markdown(&tests, project_type, root)?;
    fs::write(&output_path, &markdown)
        .map_err(|e| format!("Failed to write {}: {}", output_path.display(), e))?;

    if !quiet {
        crate::outln!("\n✓ Catalog generated successfully!");
        crate::outln!("  File: {}", output_path.display());
    }

    Ok(())
}

#[cfg(test)]
mod js_tests {
    use super::extract_js;

    /// TEST12846: the JavaScript reader sees every form a suite declares a
    /// test in — a function, an `async` function, and the runner forms
    /// `test("…")` and `it("…")` — each with its number, and nothing else.
    #[test]
    fn test12846_javascript_tests_are_read_plain_async_and_by_title() {
        let dir = tempfile::tempdir().unwrap();
        let file = dir.path().join("suite.test.js");
        std::fs::write(
            &file,
            "// TEST1: plain\nfunction test1_plain() {}\n\n\
             // TEST2: awaited\nasync function test2_awaited() {}\n\n\
             test('TEST3: by title', () => {});\nit(\"TEST4 by it\", async () => {});\n\n\
             function helper() {}\nconst testLike = async function testNotDeclared() {};\n",
        )
        .unwrap();
        let tests = extract_js(&file).unwrap();
        let found: Vec<(Option<String>, String)> =
            tests.iter().map(|t| (t.number.clone(), t.function_name.clone())).collect();
        assert_eq!(
            found,
            vec![
                (Some("1".to_string()), "test1_plain".to_string()),
                (Some("2".to_string()), "test2_awaited".to_string()),
                (Some("3".to_string()), "TEST3: by title".to_string()),
                (Some("4".to_string()), "TEST4 by it".to_string()),
            ]
        );
        assert_eq!(tests[1].description, "TEST2: awaited", "the comment above an async test is its description");
    }
}

#[cfg(test)]
mod attribute_tests {
    use std::path::{Path, PathBuf};

    /// Every Rust file under a directory, skipping what is generated or built.
    fn rust_files(root: &Path, out: &mut Vec<PathBuf>) {
        let Ok(entries) = std::fs::read_dir(root) else {
            return;
        };
        for entry in entries.flatten() {
            let path = entry.path();
            let name = path.file_name().and_then(|n| n.to_str()).unwrap_or_default();
            if path.is_dir() {
                if matches!(name, "target" | "node_modules" | ".git" | ".wsb") {
                    continue;
                }
                rust_files(&path, out);
            } else if name.ends_with(".rs") {
                out.push(path);
            }
        }
    }

    /// TEST11584: a numbered test function actually runs.
    ///
    /// `fn test9789_…` without `#[test]` above it compiles, is never run by
    /// cargo, and is invisible to the catalogue scanner — which walks forward
    /// from each attribute, so a function with none is not a test it can see.
    /// The result is a test that exists in the source, is read by anyone
    /// looking at the file, and has never once been executed.
    ///
    /// That happened here: a doc comment and its `#[test]` were stranded above
    /// a LATER test, which then carried two attributes, and
    /// `test9789_every_credential_in_the_example_is_read_by_something` sat
    /// unrun. It passed the moment it was attributed, so nothing was hiding
    /// behind it — but nothing was being checked by it either.
    ///
    /// Asked of the name, because the name is the claim: a function called
    /// `testNNNN_` says it is test NNNN, and this is what makes that true.
    #[test]
    fn test11584_every_numbered_test_function_carries_a_test_attribute() {
        let root = Path::new(env!("CARGO_MANIFEST_DIR"));
        let mut files = Vec::new();
        rust_files(root, &mut files);
        assert!(files.len() > 50, "only {} files were read", files.len());

        let numbered =
            regex::Regex::new(r"^\s*(?:pub\s+)?(?:async\s+)?fn\s+(test\d{3,5}_\w+)\s*\(").unwrap();
        let attribute = regex::Regex::new(r"^\s*#\[[^\]]*\btest\b").unwrap();
        let ignorable = regex::Regex::new(r"^\s*(///|//|#\[|$)").unwrap();

        let mut unrun = Vec::new();
        let mut seen = 0usize;
        for file in &files {
            let Ok(text) = std::fs::read_to_string(file) else {
                continue;
            };
            let lines: Vec<&str> = text.lines().collect();
            for (index, line) in lines.iter().enumerate() {
                let Some(caught) = numbered.captures(line) else {
                    continue;
                };
                seen += 1;
                // Back over the doc comment and any other attributes above it.
                let attributed = lines[..index]
                    .iter()
                    .rev()
                    .take_while(|above| ignorable.is_match(above))
                    .any(|above| attribute.is_match(above));
                if !attributed {
                    unrun.push(format!(
                        "{}:{}  {}",
                        file.strip_prefix(root).unwrap_or(file).display(),
                        index + 1,
                        &caught[1]
                    ));
                }
            }
        }

        // A floor, not a count: what it catches is a walk or a pattern that
        // silently matches nothing, which would pass the check below vacuously.
        assert!(seen > 100, "only {seen} numbered tests were found to check");
        assert!(
            unrun.is_empty(),
            "named as tests and never run — cargo does not execute them and the \
             catalogue cannot see them:\n  {}",
            unrun.join("\n  ")
        );
    }
}