mdbook-lint-rulesets 0.16.1

//! MDBOOK005: Detect orphaned markdown files not referenced in SUMMARY.md
//!
//! This rule finds markdown files in the book's source directory that are not referenced
//! in SUMMARY.md. Only scans within the directory containing SUMMARY.md, not parent or
//! sibling directories. Orphaned files can indicate incomplete documentation or forgotten content.

use mdbook_lint_core::rule::{Rule, RuleCategory, RuleMetadata};
use mdbook_lint_core::{
    Document,
    ignore::path_is_ignored,
    violation::{Severity, Violation},
};
use std::collections::HashSet;
use std::path::{Path, PathBuf};
use std::{fs, io};

/// MDBOOK005: Detect orphaned markdown files not referenced in SUMMARY.md
///
/// This rule checks for markdown files in the book's source directory that are not
/// referenced in SUMMARY.md. Such files are "orphaned" and won't be included in the
/// generated book, which may indicate:
/// - Incomplete documentation structure
/// - Forgotten content that should be added to the book
/// - Old files that should be removed
///
/// The rule:
/// - Only runs on SUMMARY.md files
/// - Parses all chapter references in SUMMARY.md
/// - Scans for .md and .markdown files ONLY in the book's source directory
/// - Does NOT scan parent directories or sibling directories
/// - Reports files that exist in the source directory but aren't referenced
/// - Ignores common files like README.md by default
/// - Supports configuration for custom ignore patterns
pub struct MDBOOK005 {
    /// Files to ignore when checking for orphans (case-insensitive, by file name)
    ignored_files: HashSet<String>,
    /// Glob patterns (relative to the book source directory) to ignore
    ignore_patterns: Vec<String>,
    /// Whether to scan subdirectories of the book source directory
    check_nested: bool,
}

impl Default for MDBOOK005 {
    fn default() -> Self {
        Self {
            ignored_files: default_ignored_files(true),
            ignore_patterns: Vec::new(),
            check_nested: true,
        }
    }
}

/// Build the default set of ignored file names.
///
/// These are files that are conventionally present in a book source tree but
/// not referenced from SUMMARY.md. `exclude_readme` controls whether README.md
/// is part of that set.
fn default_ignored_files(exclude_readme: bool) -> HashSet<String> {
    let mut ignored_files = HashSet::new();
    if exclude_readme {
        ignored_files.insert("readme.md".to_string());
    }
    ignored_files.insert("contributing.md".to_string());
    ignored_files.insert("license.md".to_string());
    ignored_files.insert("changelog.md".to_string());
    ignored_files.insert("summary.md".to_string()); // Don't report SUMMARY.md itself
    ignored_files
}

impl MDBOOK005 {
    /// Create a new instance with custom ignored files (in addition to defaults)
    #[cfg(test)]
    pub fn with_ignored_files(additional_ignored: Vec<String>) -> Self {
        let mut instance = Self::default();
        for file in additional_ignored {
            instance.ignored_files.insert(file.to_lowercase());
        }
        instance
    }

    /// Create an instance from rule configuration.
    ///
    /// Recognized keys (both `snake_case` and `kebab-case` accepted):
    /// - `ignore_patterns`: array of glob patterns, relative to the book
    ///   source directory, for orphan files to skip.
    /// - `exclude_readme`: whether README.md is ignored by default (default true).
    /// - `check_nested`: whether to scan subdirectories (default true).
    pub fn from_config(config: &toml::Value) -> Self {
        let get = |snake: &str, kebab: &str| config.get(snake).or_else(|| config.get(kebab));

        let exclude_readme = get("exclude_readme", "exclude-readme")
            .and_then(|v| v.as_bool())
            .unwrap_or(true);

        let check_nested = get("check_nested", "check-nested")
            .and_then(|v| v.as_bool())
            .unwrap_or(true);

        let ignore_patterns = get("ignore_patterns", "ignore-patterns")
            .and_then(|v| v.as_array())
            .map(|arr| {
                arr.iter()
                    .filter_map(|v| v.as_str().map(|s| s.to_string()))
                    .collect()
            })
            .unwrap_or_default();

        Self {
            ignored_files: default_ignored_files(exclude_readme),
            ignore_patterns,
            check_nested,
        }
    }
}

impl Rule for MDBOOK005 {
    fn id(&self) -> &'static str {
        "MDBOOK005"
    }

    fn name(&self) -> &'static str {
        "orphaned-files"
    }

    fn description(&self) -> &'static str {
        "Detect orphaned markdown files not referenced in SUMMARY.md"
    }

    fn metadata(&self) -> RuleMetadata {
        RuleMetadata::stable(RuleCategory::MdBook).introduced_in("mdbook-lint v0.2.0")
    }

    fn check_with_ast<'a>(
        &self,
        document: &Document,
        _ast: Option<&'a comrak::nodes::AstNode<'a>>,
    ) -> mdbook_lint_core::error::Result<Vec<Violation>> {
        let mut violations = Vec::new();

        // Only check SUMMARY.md files
        if !is_summary_file(document) {
            return Ok(violations);
        }

        // Find the book source directory, scoped to the directory containing
        // SUMMARY.md for both absolute and relative invocations.
        let book_src_dir = book_src_dir_for(&document.path);

        // Scanned files are canonicalized, so canonicalize the root to match.
        // Without this, strip_prefix below fails whenever the two differ (a
        // relative root, or a symlinked prefix such as macOS /tmp), and orphan
        // paths would be reported as absolute rather than book-relative.
        let book_src_dir = book_src_dir.canonicalize().unwrap_or(book_src_dir);

        // Parse referenced files from SUMMARY.md
        let referenced_files = match self.parse_referenced_files(document) {
            Ok(files) => files,
            Err(_) => {
                // If we can't parse SUMMARY.md, we can't check for orphans
                return Ok(violations);
            }
        };

        // Find all markdown files in the book's source directory only
        // This ensures we only check files that are actually part of the book
        let all_markdown_files = match self.find_markdown_files(&book_src_dir) {
            Ok(files) => files,
            Err(_) => {
                // If we can't scan the directory, we can't check for orphans
                return Ok(violations);
            }
        };

        // Find orphaned files
        let orphaned_files =
            self.find_orphaned_files(&referenced_files, &all_markdown_files, &book_src_dir);

        // Create violations for each orphaned file
        for orphaned_file in orphaned_files {
            let relative_path = orphaned_file
                .strip_prefix(&book_src_dir)
                .unwrap_or(orphaned_file.as_path())
                .to_string_lossy()
                .replace('\\', "/") // Ensure consistent forward slashes for cross-platform compatibility
                .to_string();

            violations.push(self.create_violation(
                format!("Orphaned file '{relative_path}' is not referenced in SUMMARY.md"),
                1, // Report on line 1 of SUMMARY.md since it's a structural issue
                1,
                Severity::Warning,
            ));
        }

        Ok(violations)
    }
}

impl MDBOOK005 {
    /// Parse all file paths referenced in SUMMARY.md
    fn parse_referenced_files(
        &self,
        document: &Document,
    ) -> Result<HashSet<PathBuf>, Box<dyn std::error::Error>> {
        let mut referenced = HashSet::new();
        let project_root = document.path.parent().unwrap_or(Path::new("."));

        for line in &document.lines {
            if let Some(path) = self.extract_file_path(line) {
                // Resolve path relative to SUMMARY.md location
                let absolute_path = project_root.join(&path);
                if let Ok(canonical) = absolute_path.canonicalize() {
                    referenced.insert(canonical);
                } else {
                    // If canonicalize fails, use the resolved path
                    referenced.insert(absolute_path);
                }
            }
        }

        Ok(referenced)
    }

    /// Extract file path from a SUMMARY.md line if present
    fn extract_file_path(&self, line: &str) -> Option<String> {
        // Look for markdown link syntax: [title](path)
        if let Some(start) = line.find("](") {
            let after_bracket = &line[start + 2..];
            if let Some(end) = after_bracket.find(')') {
                let path = &after_bracket[..end];

                // Skip empty paths (draft chapters) and external URLs
                if path.is_empty() || path.starts_with("http://") || path.starts_with("https://") {
                    return None;
                }

                // Remove anchor fragments
                let path_without_anchor = path.split('#').next().unwrap_or(path);

                // Only include markdown files
                if path_without_anchor.ends_with(".md")
                    || path_without_anchor.ends_with(".markdown")
                {
                    return Some(path_without_anchor.to_string());
                }
            }
        }

        None
    }

    /// Find all markdown files in the book's source directory
    fn find_markdown_files(&self, book_src_dir: &Path) -> io::Result<HashSet<PathBuf>> {
        let mut markdown_files = HashSet::new();
        // Only scan within the book's source directory
        scan_directory(book_src_dir, &mut markdown_files, self.check_nested)?;
        Ok(markdown_files)
    }

    /// Find files that exist but are not referenced
    fn find_orphaned_files(
        &self,
        referenced: &HashSet<PathBuf>,
        all_files: &HashSet<PathBuf>,
        book_src_dir: &Path,
    ) -> Vec<PathBuf> {
        all_files
            .iter()
            .filter(|&file| {
                // Skip if file is referenced in SUMMARY.md
                if referenced.contains(file) {
                    return false;
                }

                // Skip files in our ignore list
                if let Some(filename) = file.file_name().and_then(|n| n.to_str())
                    && self.ignored_files.contains(&filename.to_lowercase())
                {
                    return false;
                }

                // Skip files matching any configured ignore glob (matched against
                // the path relative to the book source directory). This uses the
                // same matcher as the CLI/preprocessor `ignore-paths` option, so
                // the two cannot drift apart.
                if !self.ignore_patterns.is_empty() {
                    let relative = file.strip_prefix(book_src_dir).unwrap_or(file.as_path());
                    if path_is_ignored(relative, &self.ignore_patterns) {
                        return false;
                    }
                }

                true
            })
            .cloned()
            .collect()
    }
}

/// Resolve the directory to scan for orphaned files from a SUMMARY.md path.
///
/// SUMMARY.md lives in the book's source directory, so the orphan scan is scoped
/// to its parent. This applies to relative paths as well: linting `docs` must scan
/// `docs`, not the process working directory, or files elsewhere in the repository
/// are reported as orphans of a book they do not belong to.
///
/// A bare `SUMMARY.md` has an empty parent, which is not a usable scan root, so it
/// falls back to the working directory.
fn book_src_dir_for(summary_path: &Path) -> PathBuf {
    match summary_path.parent() {
        Some(parent) if !parent.as_os_str().is_empty() => parent.to_path_buf(),
        _ => PathBuf::from("."),
    }
}

/// Check if the document represents a SUMMARY.md file
fn is_summary_file(document: &Document) -> bool {
    document
        .path
        .file_name()
        .and_then(|name| name.to_str())
        .map(|name| name.eq_ignore_ascii_case("summary.md"))
        .unwrap_or(false)
}

/// Scan a directory for markdown files, optionally recursing into subdirectories
fn scan_directory(
    dir: &Path,
    markdown_files: &mut HashSet<PathBuf>,
    recursive: bool,
) -> io::Result<()> {
    let entries = fs::read_dir(dir)?;

    for entry in entries {
        let entry = entry?;
        let path = entry.path();

        if path.is_dir() {
            if !recursive {
                continue;
            }
            // Skip common directories that shouldn't be scanned
            if let Some(dir_name) = path.file_name().and_then(|n| n.to_str())
                && matches!(
                    dir_name,
                    "target" | "node_modules" | ".git" | ".svn" | ".hg"
                )
            {
                continue;
            }
            // Recursively scan subdirectories
            scan_directory(&path, markdown_files, recursive)?;
        } else if let Some(extension) = path.extension().and_then(|e| e.to_str())
            && matches!(extension, "md" | "markdown")
        {
            if let Ok(canonical) = path.canonicalize() {
                markdown_files.insert(canonical);
            } else {
                markdown_files.insert(path);
            }
        }
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fs;
    use tempfile::TempDir;

    fn create_test_document(
        content: &str,
        file_path: &Path,
    ) -> mdbook_lint_core::error::Result<Document> {
        // Ensure parent directory exists
        if let Some(parent) = file_path.parent() {
            fs::create_dir_all(parent)?;
        }
        fs::write(file_path, content)?;
        Document::new(content.to_string(), file_path.to_path_buf())
    }

    #[test]
    fn test_mdbook005_no_orphans() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        // Create SUMMARY.md that references all files
        let summary_content = r#"# Summary

[Introduction](intro.md)
- [Chapter 1](chapter1.md)
- [Chapter 2](chapter2.md)
"#;
        let summary_path = root.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        // Create the referenced files
        create_test_document("# Intro", &root.join("intro.md"))?;
        create_test_document("# Chapter 1", &root.join("chapter1.md"))?;
        create_test_document("# Chapter 2", &root.join("chapter2.md"))?;

        let rule = MDBOOK005::default();
        let violations = rule.check(&doc)?;

        assert_eq!(
            violations.len(),
            0,
            "Should have no violations when all files are referenced"
        );
        Ok(())
    }

    #[test]
    fn test_mdbook005_detect_orphans() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        // Create SUMMARY.md that only references some files
        let summary_content = r#"# Summary

[Introduction](intro.md)
- [Chapter 1](chapter1.md)
"#;
        let summary_path = root.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        // Create referenced files
        create_test_document("# Intro", &root.join("intro.md"))?;
        create_test_document("# Chapter 1", &root.join("chapter1.md"))?;

        // Create orphaned files
        create_test_document("# Orphan", &root.join("orphan.md"))?;
        create_test_document("# Another", &root.join("another.md"))?;

        let rule = MDBOOK005::default();
        let violations = rule.check(&doc)?;

        assert_eq!(violations.len(), 2, "Should detect 2 orphaned files");

        let messages: Vec<_> = violations.iter().map(|v| &v.message).collect();
        assert!(messages.iter().any(|m| m.contains("orphan.md")));
        assert!(messages.iter().any(|m| m.contains("another.md")));

        Ok(())
    }

    #[test]
    fn test_mdbook005_ignore_common_files() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        // Create SUMMARY.md with minimal content
        let summary_content = r#"# Summary

- [Chapter 1](chapter1.md)
"#;
        let summary_path = root.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        create_test_document("# Chapter 1", &root.join("chapter1.md"))?;

        // Create files that should be ignored by default
        create_test_document("# README", &root.join("README.md"))?;
        create_test_document("# Contributing", &root.join("CONTRIBUTING.md"))?;
        create_test_document("# License", &root.join("LICENSE.md"))?;

        let rule = MDBOOK005::default();
        let violations = rule.check(&doc)?;

        assert_eq!(
            violations.len(),
            0,
            "Should ignore common files like README.md"
        );
        Ok(())
    }

    #[test]
    fn test_mdbook005_nested_directories() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        // Create SUMMARY.md that references nested files
        let summary_content = r#"# Summary

- [Chapter 1](guide/chapter1.md)
"#;
        let summary_path = root.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        // Create referenced nested file
        create_test_document("# Chapter 1", &root.join("guide/chapter1.md"))?;

        // Create orphaned nested file
        create_test_document("# Orphan", &root.join("guide/orphan.md"))?;

        let rule = MDBOOK005::default();
        let violations = rule.check(&doc)?;

        assert_eq!(
            violations.len(),
            1,
            "Should detect orphaned files in subdirectories"
        );
        assert!(violations[0].message.contains("guide/orphan.md"));
        Ok(())
    }

    #[test]
    fn test_mdbook005_draft_chapters() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        // Create SUMMARY.md with draft chapters (empty paths)
        let summary_content = r#"# Summary

- [Chapter 1](chapter1.md)
- [Draft Chapter]()
"#;
        let summary_path = root.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        create_test_document("# Chapter 1", &root.join("chapter1.md"))?;
        create_test_document("# Orphan", &root.join("orphan.md"))?;

        let rule = MDBOOK005::default();
        let violations = rule.check(&doc)?;

        // Should still detect the orphan, but not complain about the draft
        assert_eq!(violations.len(), 1);
        assert!(violations[0].message.contains("orphan.md"));
        Ok(())
    }

    #[test]
    fn test_mdbook005_non_summary_files() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;

        // Test on a non-SUMMARY.md file
        let content = "# Regular File";
        let doc_path = temp_dir.path().join("README.md");
        let doc = create_test_document(content, &doc_path)?;

        let rule = MDBOOK005::default();
        let violations = rule.check(&doc)?;

        assert_eq!(
            violations.len(),
            0,
            "Should not run on non-SUMMARY.md files"
        );
        Ok(())
    }

    #[test]
    fn test_mdbook005_scope_limited_to_src_dir() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        // Create a book structure with files outside the src directory
        let book_src = root.join("src");
        fs::create_dir_all(&book_src)?;

        // Create SUMMARY.md in src/
        let summary_content = r#"# Summary

- [Chapter 1](chapter1.md)
"#;
        let summary_path = book_src.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        // Create referenced file in src/
        create_test_document("# Chapter 1", &book_src.join("chapter1.md"))?;

        // Create orphaned file in src/
        create_test_document("# Orphan in src", &book_src.join("orphan_in_src.md"))?;

        // Create files outside src/ that should NOT be detected
        create_test_document("# Outside", &root.join("outside.md"))?;
        create_test_document("# Config docs", &root.join("CONFIGURATION.md"))?;

        // Create a sibling directory with markdown files that should NOT be detected
        let docs_dir = root.join("docs");
        fs::create_dir_all(&docs_dir)?;
        create_test_document("# Docs", &docs_dir.join("documentation.md"))?;

        let rule = MDBOOK005::default();
        let violations = rule.check(&doc)?;

        // Should only detect the orphan in src/, not files outside
        assert_eq!(
            violations.len(),
            1,
            "Should only detect orphans within src/"
        );
        assert!(violations[0].message.contains("orphan_in_src.md"));
        assert!(!violations[0].message.contains("outside.md"));
        assert!(!violations[0].message.contains("CONFIGURATION.md"));
        assert!(!violations[0].message.contains("documentation.md"));

        Ok(())
    }

    #[test]
    fn test_extract_file_path() {
        let rule = MDBOOK005::default();

        // Valid paths
        assert_eq!(
            rule.extract_file_path("- [Chapter](chapter.md)"),
            Some("chapter.md".to_string())
        );
        assert_eq!(
            rule.extract_file_path("[Intro](intro.md)"),
            Some("intro.md".to_string())
        );
        assert_eq!(
            rule.extract_file_path("    - [Nested](sub/nested.md)"),
            Some("sub/nested.md".to_string())
        );

        // Paths with anchors
        assert_eq!(
            rule.extract_file_path("- [Link](file.md#section)"),
            Some("file.md".to_string())
        );

        // Invalid or ignored paths
        assert_eq!(rule.extract_file_path("- [Draft]()"), None);
        assert_eq!(
            rule.extract_file_path("- [External](https://example.com)"),
            None
        );
        assert_eq!(rule.extract_file_path("- [Non-MD](image.png)"), None);
        assert_eq!(rule.extract_file_path("Regular text"), None);
    }

    #[test]
    fn test_custom_ignored_files() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        let summary_content = r#"# Summary

- [Chapter 1](chapter1.md)
"#;
        let summary_path = root.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        create_test_document("# Chapter 1", &root.join("chapter1.md"))?;
        create_test_document("# Custom", &root.join("custom.md"))?;
        create_test_document("# Orphan", &root.join("orphan.md"))?;

        // Create rule that ignores custom.md
        let rule = MDBOOK005::with_ignored_files(vec!["custom.md".to_string()]);
        let violations = rule.check(&doc)?;

        // Should only report orphan.md, not custom.md
        assert_eq!(violations.len(), 1);
        assert!(violations[0].message.contains("orphan.md"));
        assert!(!violations[0].message.contains("custom.md"));
        Ok(())
    }

    // The glob matching semantics themselves (bare name, directory prefix,
    // `*` vs `**`, ...) are pinned by the tests in `mdbook_lint_core::ignore`.
    // The tests below cover this rule's use of that shared matcher: reading
    // `ignore_patterns` from config and applying it to orphan detection.

    #[test]
    fn test_from_config_defaults() {
        // Empty config yields the same behavior as default()
        let cfg: toml::Value = toml::from_str("").unwrap();
        let rule = MDBOOK005::from_config(&cfg);
        assert!(rule.ignore_patterns.is_empty());
        assert!(rule.check_nested);
        assert!(rule.ignored_files.contains("readme.md"));
    }

    #[test]
    fn test_ignore_patterns_config() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        let summary_content = r#"# Summary

- [Chapter 1](chapter1.md)
"#;
        let summary_path = root.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        create_test_document("# Chapter 1", &root.join("chapter1.md"))?;
        create_test_document("# Not Found", &root.join("not-found.md"))?;
        create_test_document("# Real Orphan", &root.join("orphan.md"))?;

        // Reproduces issue #412: ignore_patterns should suppress not-found.md
        let cfg: toml::Value =
            toml::from_str("ignore_patterns = [\"not-found.md\", \"**/not-found.md\"]").unwrap();
        let rule = MDBOOK005::from_config(&cfg);
        let violations = rule.check(&doc)?;

        assert_eq!(violations.len(), 1, "only the real orphan should remain");
        assert!(violations[0].message.contains("orphan.md"));
        assert!(!violations[0].message.contains("not-found.md"));
        Ok(())
    }

    #[test]
    fn test_ignore_patterns_config_nested_dir() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        let summary_content = r#"# Summary

- [Chapter 1](chapter1.md)
"#;
        let summary_path = root.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        create_test_document("# Chapter 1", &root.join("chapter1.md"))?;
        create_test_document("# Draft", &root.join("drafts/wip.md"))?;
        create_test_document("# Draft 2", &root.join("drafts/nested/wip2.md"))?;
        create_test_document("# Real Orphan", &root.join("orphan.md"))?;

        let cfg: toml::Value = toml::from_str("ignore_patterns = [\"drafts/\"]").unwrap();
        let rule = MDBOOK005::from_config(&cfg);
        let violations = rule.check(&doc)?;

        assert_eq!(violations.len(), 1, "drafts/ should be fully ignored");
        assert!(violations[0].message.contains("orphan.md"));
        Ok(())
    }

    #[test]
    fn test_exclude_readme_false_reports_readme() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        let summary_content = r#"# Summary

- [Chapter 1](chapter1.md)
"#;
        let summary_path = root.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        create_test_document("# Chapter 1", &root.join("chapter1.md"))?;
        create_test_document("# Readme", &root.join("README.md"))?;

        // Default: README ignored
        assert_eq!(MDBOOK005::default().check(&doc)?.len(), 0);

        // exclude_readme = false: README reported as orphan
        let cfg: toml::Value = toml::from_str("exclude_readme = false").unwrap();
        let violations = MDBOOK005::from_config(&cfg).check(&doc)?;
        assert_eq!(violations.len(), 1);
        assert!(violations[0].message.to_lowercase().contains("readme.md"));
        Ok(())
    }

    #[test]
    fn test_check_nested_false_skips_subdirs() -> mdbook_lint_core::error::Result<()> {
        let temp_dir = TempDir::new()?;
        let root = temp_dir.path();

        let summary_content = r#"# Summary

- [Chapter 1](chapter1.md)
"#;
        let summary_path = root.join("SUMMARY.md");
        let doc = create_test_document(summary_content, &summary_path)?;

        create_test_document("# Chapter 1", &root.join("chapter1.md"))?;
        create_test_document("# Nested Orphan", &root.join("sub/orphan.md"))?;

        // Default recurses and finds the nested orphan
        assert_eq!(MDBOOK005::default().check(&doc)?.len(), 1);

        // check_nested = false: subdirectories are not scanned
        let cfg: toml::Value = toml::from_str("check_nested = false").unwrap();
        assert_eq!(MDBOOK005::from_config(&cfg).check(&doc)?.len(), 0);
        Ok(())
    }

    #[test]
    fn test_book_src_dir_for_scopes_to_summary_parent() {
        // Issue #461: a relative SUMMARY.md previously resolved to the process
        // working directory instead of its own parent.
        assert_eq!(
            book_src_dir_for(Path::new("docs/SUMMARY.md")),
            PathBuf::from("docs")
        );
        assert_eq!(
            book_src_dir_for(Path::new("book/src/SUMMARY.md")),
            PathBuf::from("book/src")
        );
        assert_eq!(
            book_src_dir_for(Path::new("/abs/docs/SUMMARY.md")),
            PathBuf::from("/abs/docs")
        );

        // A bare SUMMARY.md has an empty parent and falls back to the CWD.
        assert_eq!(
            book_src_dir_for(Path::new("SUMMARY.md")),
            PathBuf::from(".")
        );
    }

    /// Serializes the tests that mutate the process working directory, which is
    /// global to the test binary.
    static CWD_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

    /// Restores the previous working directory when dropped, so a failing
    /// assertion cannot leak a changed CWD into other tests.
    struct CwdGuard(PathBuf);

    impl Drop for CwdGuard {
        fn drop(&mut self) {
            let _ = std::env::set_current_dir(&self.0);
        }
    }

    #[test]
    fn test_mdbook005_relative_summary_path_does_not_scan_cwd()
    -> mdbook_lint_core::error::Result<()> {
        let _lock = CWD_LOCK.lock().unwrap_or_else(|e| e.into_inner());

        let temp_dir = TempDir::new()?;
        let root = temp_dir.path().canonicalize()?;

        // A book under docs/, plus markdown at the repository root that is not
        // part of the book.
        let docs = root.join("docs");
        fs::create_dir_all(&docs)?;

        let summary_content = r#"# Summary

- [Chapter 1](chapter1.md)
"#;
        create_test_document(summary_content, &docs.join("SUMMARY.md"))?;
        create_test_document("# Chapter 1", &docs.join("chapter1.md"))?;
        create_test_document("# Orphan", &docs.join("orphan.md"))?;

        // These live outside the book and must never be reported.
        create_test_document("# Claude", &root.join("CLAUDE.md"))?;
        create_test_document("# Readme", &root.join("NOTES.md"))?;
        create_test_document("# Skill", &root.join(".claude/skills/SKILL.md"))?;

        let guard = CwdGuard(std::env::current_dir()?);
        std::env::set_current_dir(&root)?;

        // Relative invocation, the reported failure mode.
        let relative_doc = Document::new(
            summary_content.to_string(),
            PathBuf::from("docs/SUMMARY.md"),
        )?;
        let relative = MDBOOK005::default().check(&relative_doc)?;

        // Absolute invocation, which already worked.
        let absolute_doc = Document::new(summary_content.to_string(), docs.join("SUMMARY.md"))?;
        let absolute = MDBOOK005::default().check(&absolute_doc)?;

        drop(guard);

        assert_eq!(
            relative.len(),
            1,
            "relative path should report only the orphan inside docs/, got: {:?}",
            relative.iter().map(|v| &v.message).collect::<Vec<_>>()
        );
        assert!(relative[0].message.contains("orphan.md"));
        for unexpected in ["CLAUDE.md", "NOTES.md", "SKILL.md"] {
            assert!(
                !relative[0].message.contains(unexpected),
                "must not scan outside the book source directory: {unexpected}"
            );
        }

        // Both invocations describe the same book, so they must agree.
        let messages = |vs: &[Violation]| {
            let mut m: Vec<String> = vs.iter().map(|v| v.message.clone()).collect();
            m.sort();
            m
        };
        assert_eq!(
            messages(&relative),
            messages(&absolute),
            "relative and absolute invocations must produce identical results"
        );

        Ok(())
    }
}