adrs_core/

lint.rs

//! ADR linting using mdbook-lint rules.
//!
//! This module provides unified linting for ADRs, combining per-file validation
//! (title format, required sections, date format) with repository-level checks
//! (sequential numbering, duplicate detection, broken links).

use crate::{Adr, Repository, Result};
use mdbook_lint_core::Document;
use mdbook_lint_core::rule::{CollectionRule, Rule};
use mdbook_lint_rulesets::adr::{
    Adr001, Adr002, Adr003, Adr004, Adr005, Adr006, Adr007, Adr008, Adr009, Adr010, Adr011, Adr012,
    Adr013, Adr014, Adr015, Adr016, Adr017,
};
use std::path::PathBuf;

/// Severity level for lint issues.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum IssueSeverity {
    /// Informational message.
    Info,
    /// Warning that should be addressed.
    Warning,
    /// Error that needs to be fixed.
    Error,
}

impl std::fmt::Display for IssueSeverity {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            IssueSeverity::Info => write!(f, "info"),
            IssueSeverity::Warning => write!(f, "warning"),
            IssueSeverity::Error => write!(f, "error"),
        }
    }
}

impl From<mdbook_lint_core::Severity> for IssueSeverity {
    fn from(severity: mdbook_lint_core::Severity) -> Self {
        match severity {
            mdbook_lint_core::Severity::Error => IssueSeverity::Error,
            mdbook_lint_core::Severity::Warning => IssueSeverity::Warning,
            mdbook_lint_core::Severity::Info => IssueSeverity::Info,
        }
    }
}

/// A unified issue type for both per-file lint violations and repository-level diagnostics.
#[derive(Debug, Clone)]
pub struct Issue {
    /// The rule that produced this issue (e.g., "ADR001", "adr-title-format").
    pub rule_id: String,
    /// Human-readable rule name.
    pub rule_name: String,
    /// The severity of this issue.
    pub severity: IssueSeverity,
    /// A human-readable message describing the issue.
    pub message: String,
    /// The path to the affected file, if applicable.
    pub path: Option<PathBuf>,
    /// Line number (1-based), if applicable.
    pub line: Option<usize>,
    /// Column number (1-based), if applicable.
    pub column: Option<usize>,
    /// The ADR number, if applicable.
    pub adr_number: Option<u32>,
    /// Related ADR numbers (for issues involving multiple ADRs).
    pub related_adrs: Vec<u32>,
}

impl Issue {
    /// Create a new issue from an mdbook-lint violation.
    fn from_violation(
        violation: mdbook_lint_core::Violation,
        path: Option<PathBuf>,
        adr_number: Option<u32>,
    ) -> Self {
        Self {
            rule_id: violation.rule_id,
            rule_name: violation.rule_name,
            severity: violation.severity.into(),
            message: violation.message,
            path,
            line: Some(violation.line),
            column: Some(violation.column),
            adr_number,
            related_adrs: Vec::new(),
        }
    }
}

/// Results from linting.
#[derive(Debug, Default)]
pub struct LintReport {
    /// All issues found.
    pub issues: Vec<Issue>,
}

impl LintReport {
    /// Create a new empty report.
    pub fn new() -> Self {
        Self::default()
    }

    /// Add an issue to the report.
    pub fn add(&mut self, issue: Issue) {
        self.issues.push(issue);
    }

    /// Check if there are any errors.
    pub fn has_errors(&self) -> bool {
        self.issues
            .iter()
            .any(|i| i.severity == IssueSeverity::Error)
    }

    /// Check if there are any warnings.
    pub fn has_warnings(&self) -> bool {
        self.issues
            .iter()
            .any(|i| i.severity == IssueSeverity::Warning)
    }

    /// Check if the report is clean (no warnings or errors).
    pub fn is_clean(&self) -> bool {
        !self.has_errors() && !self.has_warnings()
    }

    /// Get the count of issues by severity.
    pub fn count_by_severity(&self, severity: IssueSeverity) -> usize {
        self.issues
            .iter()
            .filter(|i| i.severity == severity)
            .count()
    }

    /// Sort issues by severity (errors first), then by path, then by line.
    pub fn sort(&mut self) {
        self.issues.sort_by(|a, b| {
            b.severity
                .cmp(&a.severity)
                .then_with(|| a.path.cmp(&b.path))
                .then_with(|| a.line.cmp(&b.line))
        });
    }
}

/// Lint a single ADR file.
///
/// Runs all per-file lint rules against the ADR content.
pub fn lint_adr(adr: &Adr) -> Result<LintReport> {
    let mut report = LintReport::new();

    // Get the file content
    let Some(path) = &adr.path else {
        return Ok(report); // No path, nothing to lint
    };

    let content = std::fs::read_to_string(path)?;

    // Create mdbook-lint Document
    let doc = match Document::new(content, path.clone()) {
        Ok(d) => d,
        Err(e) => {
            report.add(Issue {
                rule_id: "parse-error".to_string(),
                rule_name: "parse-error".to_string(),
                severity: IssueSeverity::Error,
                message: format!("Failed to parse document: {e}"),
                path: Some(path.clone()),
                line: None,
                column: None,
                adr_number: Some(adr.number),
                related_adrs: Vec::new(),
            });
            return Ok(report);
        }
    };

    // Run all single-document rules
    let rules: Vec<Box<dyn Rule>> = vec![
        Box::new(Adr001::default()),
        Box::new(Adr002::default()),
        Box::new(Adr003::default()),
        Box::new(Adr004::default()),
        Box::new(Adr005::default()),
        Box::new(Adr006::default()),
        Box::new(Adr007::default()),
        Box::new(Adr008::default()),
        Box::new(Adr009::default()),
        Box::new(Adr014::default()),
        Box::new(Adr015::default()),
        Box::new(Adr016::default()),
        Box::new(Adr017::default()),
    ];

    for rule in rules {
        match rule.check(&doc) {
            Ok(violations) => {
                for violation in violations {
                    report.add(Issue::from_violation(
                        violation,
                        Some(path.clone()),
                        Some(adr.number),
                    ));
                }
            }
            Err(e) => {
                report.add(Issue {
                    rule_id: rule.id().to_string(),
                    rule_name: rule.name().to_string(),
                    severity: IssueSeverity::Error,
                    message: format!("Rule failed: {e}"),
                    path: Some(path.clone()),
                    line: None,
                    column: None,
                    adr_number: Some(adr.number),
                    related_adrs: Vec::new(),
                });
            }
        }
    }

    Ok(report)
}

/// Lint all ADRs in a repository (per-file checks only).
pub fn lint_all(repo: &Repository) -> Result<LintReport> {
    let mut report = LintReport::new();
    let adrs = repo.list()?;

    for adr in &adrs {
        let adr_report = lint_adr(adr)?;
        report.issues.extend(adr_report.issues);
    }

    report.sort();
    Ok(report)
}

/// Run repository-level checks (collection rules).
///
/// These checks analyze the ADR set as a whole:
/// - Sequential numbering (ADR011)
/// - Duplicate numbers (ADR012)
/// - Broken links (ADR013)
/// - Superseded ADRs have replacements (ADR010)
pub fn check_repository(repo: &Repository) -> Result<LintReport> {
    let mut report = LintReport::new();
    let adrs = repo.list()?;

    // Build documents for collection rules
    let mut documents = Vec::new();
    for adr in &adrs {
        if let Some(path) = &adr.path {
            let content = std::fs::read_to_string(path)?;
            if let Ok(doc) = Document::new(content, path.clone()) {
                documents.push(doc);
            }
        }
    }

    // Run collection rules
    let collection_rules: Vec<Box<dyn CollectionRule>> = vec![
        Box::new(Adr010),
        Box::new(Adr011),
        Box::new(Adr012),
        Box::new(Adr013),
    ];

    for rule in collection_rules {
        match rule.check_collection(&documents) {
            Ok(violations) => {
                for violation in violations {
                    // Collection rule violations may have path in the message
                    // We need to parse it out or handle it differently
                    report.add(Issue {
                        rule_id: rule.id().to_string(),
                        rule_name: rule.name().to_string(),
                        severity: violation.severity.into(),
                        message: violation.message,
                        path: None, // Collection rules may span multiple files
                        line: if violation.line > 0 {
                            Some(violation.line)
                        } else {
                            None
                        },
                        column: if violation.column > 0 {
                            Some(violation.column)
                        } else {
                            None
                        },
                        adr_number: None,
                        related_adrs: Vec::new(),
                    });
                }
            }
            Err(e) => {
                report.add(Issue {
                    rule_id: rule.id().to_string(),
                    rule_name: rule.name().to_string(),
                    severity: IssueSeverity::Error,
                    message: format!("Rule failed: {e}"),
                    path: None,
                    line: None,
                    column: None,
                    adr_number: None,
                    related_adrs: Vec::new(),
                });
            }
        }
    }

    report.sort();
    Ok(report)
}

/// Run all checks: per-file lint + repository-level checks.
///
/// Also reports files that look like ADRs (digit-prefixed `.md` files in the
/// ADR directory) but could not be parsed (e.g., invalid YAML frontmatter).
pub fn check_all(repo: &Repository) -> Result<LintReport> {
    let mut report = LintReport::new();

    // Use list_with_errors to capture parse failures
    let (adrs, parse_errors) = repo.list_with_errors()?;

    // Report parse errors as lint issues
    for (path, error) in &parse_errors {
        report.add(Issue {
            rule_id: "parse-error".to_string(),
            rule_name: "adr-parse-error".to_string(),
            severity: IssueSeverity::Error,
            message: format!("Failed to parse ADR: {error}"),
            path: Some(path.clone()),
            line: None,
            column: None,
            adr_number: None,
            related_adrs: Vec::new(),
        });
    }

    // Run per-file lint on successfully parsed ADRs
    for adr in &adrs {
        let adr_report = lint_adr(adr)?;
        report.issues.extend(adr_report.issues);
    }

    // Run repository-level checks (these still use repo.list() internally,
    // which is fine — they only need successfully parsed ADRs)
    let repo_report = check_repository(repo)?;
    report.issues.extend(repo_report.issues);

    report.sort();
    Ok(report)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::Adr;

    #[test]
    fn test_issue_severity_ordering() {
        assert!(IssueSeverity::Error > IssueSeverity::Warning);
        assert!(IssueSeverity::Warning > IssueSeverity::Info);
    }

    #[test]
    fn test_lint_report_empty() {
        let report = LintReport::new();
        assert!(report.is_clean());
        assert!(!report.has_errors());
        assert!(!report.has_warnings());
    }

    #[test]
    fn test_lint_report_with_issues() {
        let mut report = LintReport::new();
        report.add(Issue {
            rule_id: "ADR001".to_string(),
            rule_name: "adr-title-format".to_string(),
            severity: IssueSeverity::Error,
            message: "Title format invalid".to_string(),
            path: Some(PathBuf::from("0001-test.md")),
            line: Some(1),
            column: Some(1),
            adr_number: Some(1),
            related_adrs: Vec::new(),
        });

        assert!(report.has_errors());
        assert!(!report.is_clean());
        assert_eq!(report.count_by_severity(IssueSeverity::Error), 1);
    }

    #[test]
    fn test_lint_valid_nygard_adr() {
        // Uses the actual ADR #0001 text produced by `adrs init`. The word "described"
        // previously triggered an ADR014 false positive (fixed in mdbook-lint-rulesets 0.14.3).
        let content = r#"# 1. Record architecture decisions

Date: 2024-03-04

## Status

Accepted

## Context

We need to record the architectural decisions made on this project.

## Decision

We will use Architecture Decision Records, as described by Michael Nygard in his article "Documenting Architecture Decisions".

## Consequences

See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's adr-tools.
"#;
        let temp_dir = tempfile::tempdir().unwrap();
        let path = temp_dir
            .path()
            .join("adr")
            .join("0001-record-architecture-decisions.md");
        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
        std::fs::write(&path, content).unwrap();

        let mut adr = Adr::new(1, "Record architecture decisions");
        adr.path = Some(path);

        let report = lint_adr(&adr).unwrap();

        // Print any issues for debugging
        for issue in &report.issues {
            println!(
                "{}: {} ({}:{})",
                issue.rule_id,
                issue.message,
                issue.line.unwrap_or(0),
                issue.column.unwrap_or(0)
            );
        }

        assert!(report.is_clean(), "Expected no issues for valid Nygard ADR");
    }

    #[test]
    fn test_lint_invalid_adr_missing_status() {
        let content = r#"# 1. Test decision

Date: 2024-03-04

## Context

Some context.

## Decision

Some decision.

## Consequences

Some consequences.
"#;
        let temp_dir = tempfile::tempdir().unwrap();
        let path = temp_dir.path().join("adr").join("0001-test-decision.md");
        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
        std::fs::write(&path, content).unwrap();

        let mut adr = Adr::new(1, "Test decision");
        adr.path = Some(path);

        let report = lint_adr(&adr).unwrap();

        // Should have at least one issue (missing status)
        assert!(
            !report.is_clean(),
            "Expected issues for ADR missing status section"
        );
        assert!(
            report.issues.iter().any(|i| i.rule_id == "ADR002"),
            "Expected ADR002 (missing status) violation"
        );
    }

    #[test]
    fn test_check_all_reports_parse_errors() {
        use crate::Repository;

        let temp = tempfile::tempdir().unwrap();
        let repo = Repository::init(temp.path(), None, true).unwrap();

        // Write an ADR with invalid YAML (bad date)
        let bad_content =
            "---\nnumber: 2\nstatus: accepted\ndate: not-a-date\n---\n\n# 2. Bad Date\n";
        std::fs::write(repo.adr_path().join("0002-bad-date.md"), bad_content).unwrap();

        let report = check_all(&repo).unwrap();

        let parse_errors: Vec<_> = report
            .issues
            .iter()
            .filter(|i| i.rule_id == "parse-error")
            .collect();

        assert_eq!(parse_errors.len(), 1, "should report 1 parse error");
        assert_eq!(parse_errors[0].severity, IssueSeverity::Error);
        assert!(
            parse_errors[0]
                .path
                .as_ref()
                .unwrap()
                .to_string_lossy()
                .contains("0002-bad-date.md")
        );
    }

    #[test]
    fn test_check_all_no_parse_errors_for_string_decision_makers() {
        use crate::Repository;

        let temp = tempfile::tempdir().unwrap();
        let repo = Repository::init(temp.path(), None, true).unwrap();

        // Issue #216: decision-makers as string should not cause a parse error
        let content = "---\nnumber: 2\nstatus: accepted\ndate: 2026-03-18\ndecision-makers: alice\n---\n\n# 2. Test\n\n## Context\n\nContext.\n\n## Decision\n\nDecision.\n\n## Consequences\n\nConsequences.\n";
        std::fs::write(repo.adr_path().join("0002-test.md"), content).unwrap();

        let report = check_all(&repo).unwrap();

        let parse_errors: Vec<_> = report
            .issues
            .iter()
            .filter(|i| i.rule_id == "parse-error")
            .collect();

        assert!(
            parse_errors.is_empty(),
            "string decision-makers should not cause parse error, got: {:?}",
            parse_errors.iter().map(|i| &i.message).collect::<Vec<_>>()
        );
    }
    // ========== check_repository collection rules (issue #239) ==========

    fn make_nygard_adr(number: u32, title: &str, status: &str, links: &str) -> String {
        format!(
            "# {}. {}\n\nDate: 2024-01-01\n\n## Status\n\n{}{}\n## Context\n\nSome context.\n\n## Decision\n\nA decision.\n\n## Consequences\n\nSome consequences.\n",
            number, title, status, links
        )
    }

    #[test]
    fn test_check_repository_broken_link_adr013() {
        use crate::Repository;

        let temp = tempfile::tempdir().unwrap();
        // init creates ADR #1 automatically
        let repo = Repository::init(temp.path(), None, false).unwrap();
        let adr_dir = repo.adr_path();

        // ADR 2 links to nonexistent ADR 99
        std::fs::write(
            adr_dir.join("0002-second.md"),
            make_nygard_adr(
                2,
                "Second",
                "Accepted",
                "\n\nSupersedes [99. Unknown](0099-unknown.md)\n",
            ),
        )
        .unwrap();

        let report = check_repository(&repo).unwrap();

        // Should have an ADR013 (broken links) issue
        let has_adr013 = report.issues.iter().any(|i| i.rule_id == "ADR013");
        assert!(
            has_adr013,
            "Expected ADR013 broken-link issue, got: {:?}",
            report.issues.iter().map(|i| &i.rule_id).collect::<Vec<_>>()
        );
    }

    #[test]
    fn test_check_repository_sequential_gap_adr011() {
        use crate::Repository;

        let temp = tempfile::tempdir().unwrap();
        // init creates ADR #1 automatically; write #2 and #4 to create a gap at #3
        let repo = Repository::init(temp.path(), None, false).unwrap();
        let adr_dir = repo.adr_path();

        // ADRs 1, 2, 4 -- gap at 3
        std::fs::write(
            adr_dir.join("0002-second.md"),
            make_nygard_adr(2, "Second", "Accepted", ""),
        )
        .unwrap();
        std::fs::write(
            adr_dir.join("0004-fourth.md"),
            make_nygard_adr(4, "Fourth", "Accepted", ""),
        )
        .unwrap();

        let report = check_repository(&repo).unwrap();

        // Should have an ADR011 (sequential gap) issue
        let has_adr011 = report.issues.iter().any(|i| i.rule_id == "ADR011");
        assert!(
            has_adr011,
            "Expected ADR011 sequential-gap issue, got: {:?}",
            report.issues.iter().map(|i| &i.rule_id).collect::<Vec<_>>()
        );
    }

    #[test]
    fn test_check_repository_clean_repo_has_no_issues() {
        use crate::Repository;

        let temp = tempfile::tempdir().unwrap();
        let repo = Repository::init(temp.path(), None, false).unwrap();
        let adr_dir = repo.adr_path();

        // Repository::init creates ADR #1 automatically -- use #2 and #3 to avoid duplicate
        std::fs::write(
            adr_dir.join("0002-second.md"),
            make_nygard_adr(2, "Second", "Accepted", ""),
        )
        .unwrap();
        std::fs::write(
            adr_dir.join("0003-third.md"),
            make_nygard_adr(3, "Third", "Proposed", ""),
        )
        .unwrap();

        let report = check_repository(&repo).unwrap();

        let collection_rule_ids = ["ADR010", "ADR011", "ADR012", "ADR013"];
        let collection_issues: Vec<_> = report
            .issues
            .iter()
            .filter(|i| collection_rule_ids.contains(&i.rule_id.as_str()))
            .collect();

        assert!(
            collection_issues.is_empty(),
            "Clean repo should have no collection-rule issues, got: {:?}",
            collection_issues
                .iter()
                .map(|i| format!("{}: {}", i.rule_id, i.message))
                .collect::<Vec<_>>()
        );
    }

    #[test]
    fn test_check_all_combines_lint_and_repository_checks() {
        use crate::Repository;

        let temp = tempfile::tempdir().unwrap();
        let repo = Repository::init(temp.path(), None, false).unwrap();
        let adr_dir = repo.adr_path();

        // Create a valid ADR so check_all has something to process
        std::fs::write(
            adr_dir.join("0001-first.md"),
            make_nygard_adr(1, "First", "Accepted", ""),
        )
        .unwrap();

        // check_all should succeed and return a report
        let report = check_all(&repo).unwrap();

        // With a valid sequential repo, no collection-rule violations
        let adr011 = report
            .issues
            .iter()
            .filter(|i| i.rule_id == "ADR011")
            .count();
        assert_eq!(
            adr011, 0,
            "Single valid ADR should have no sequential-gap issue"
        );
    }
}