//! //! This module defines the Rule trait and related types for implementing linting rules in rumdl. use dyn_clone::DynClone; use serde::{Deserialize, Serialize}; use std::ops::Range; use thiserror::Error; use crate::lint_context::LintContext; // Macro to implement box_clone for Rule implementors #[macro_export] macro_rules! impl_rule_clone { ($ty:ty) => { impl $ty { fn box_clone(&self) -> Box { Box::new(self.clone()) } } }; } #[derive(Debug, Error)] pub enum LintError { #[error("Invalid input: {0}")] InvalidInput(String), #[error("Fix failed: {0}")] FixFailed(String), #[error("IO error: {0}")] IoError(#[from] std::io::Error), #[error("Parsing error: {0}")] ParsingError(String), } pub type LintResult = Result, LintError>; #[derive(Debug, PartialEq, Clone, Serialize, Deserialize)] pub struct LintWarning { pub message: String, pub line: usize, // 1-indexed start line /// 1-indexed start column, measured in **characters** (not bytes). /// When deriving a column from a byte offset (regex match, `str::find`, /// parser byte offset), convert with `range_utils::byte_to_char_count` or a /// character-based range helper. A raw byte offset mis-positions the /// highlight on lines containing multi-byte UTF-8. pub column: usize, pub end_line: usize, // 1-indexed end line /// 1-indexed end column, measured in **characters** (see `column`). Use /// `str::chars().count()`, not `str::len()`, when computing a span width. pub end_column: usize, pub severity: Severity, pub fix: Option, pub rule_name: Option, } impl LintWarning { /// The 1-indexed lines whose content this warning covers, used to decide /// whether an inline disable comment suppresses it. /// /// `end_column` is exclusive, so a range ending at column 1 of a later line /// stops at that line's start and covers none of it: a warning spanning /// whole lines with their terminators ends there. That line is excluded, /// so a `disable-line` comment on the content after a flagged run does not /// suppress the run. An `end_line` before `line` falls back to `line` alone. pub fn covered_lines(&self) -> std::ops::RangeInclusive { let end = if self.end_line > self.line && self.end_column <= 1 { self.end_line - 1 } else { self.end_line.max(self.line) }; self.line..=end } } /// One atomic fix attached to a `LintWarning`. /// /// `range`/`replacement` describe the primary edit. `additional_edits` /// carries any *paired* edits that must apply together with the primary one /// for the result to be a valid document — for example, MD054's conversion /// of an inline link to a reference style produces the in-place link rewrite /// **and** a reference-definition append at end-of-file; applying only one /// half would leave a dangling reference. /// /// All fix consumers (the LSP code-action layer, CLI counters, the /// `apply_warning_fixes` helper) treat the primary edit and the /// `additional_edits` as a single unit. The field is empty by default so /// rules that only need a single-location fix can keep using /// `Fix::new(range, replacement)`; only rules that need multi-location /// atomicity populate it via `Fix::with_additional_edits(...)`. /// /// `additional_edits` is intentionally a flat `Vec` — nesting beyond /// one level isn't needed today and would complicate the apply contract. /// Apply order is "primary first, then additional in their declared order" /// when offsets are non-overlapping; consumers that batch multiple fixes /// across warnings still sort by `range.start` descending so earlier offsets /// remain valid as later edits mutate the buffer. #[derive(Debug, PartialEq, Clone, Default, Serialize, Deserialize)] pub struct Fix { /// Byte range in the text supplied to the producing API. Public document /// linting includes any leading BOM; raw `Rule::check` ranges address the /// rule's `LintContext::content`. pub range: Range, pub replacement: String, /// Edits applied atomically with the primary `range`/`replacement` pair. /// Empty for the common single-edit case. See struct docs for semantics. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub additional_edits: Vec, } impl Fix { /// Construct a single-edit fix. Use this for the overwhelming common case /// where a fix is one in-place replacement. pub fn new(range: Range, replacement: String) -> Self { Self { range, replacement, additional_edits: Vec::new(), } } /// Construct a multi-edit fix bundle. The primary edit is applied first, /// followed by every entry in `additional_edits` as part of the same /// atomic operation. pub fn with_additional_edits(range: Range, replacement: String, additional_edits: Vec) -> Self { Self { range, replacement, additional_edits, } } } #[derive(Debug, PartialEq, Eq, Hash, Clone, Copy, Serialize, schemars::JsonSchema)] #[serde(rename_all = "lowercase")] pub enum Severity { Error, Warning, Info, } impl<'de> serde::Deserialize<'de> for Severity { fn deserialize(deserializer: D) -> Result where D: serde::Deserializer<'de>, { let s = String::deserialize(deserializer)?; match s.to_lowercase().as_str() { "error" => Ok(Severity::Error), "warning" => Ok(Severity::Warning), "info" => Ok(Severity::Info), _ => Err(serde::de::Error::custom(format!( "Invalid severity: '{s}'. Valid values: error, warning, info" ))), } } } /// Type of rule for selective processing #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum RuleCategory { Heading, List, CodeBlock, Link, Image, Html, Emphasis, Whitespace, Blockquote, Table, FrontMatter, Other, } /// Capability of a rule to fix issues #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum FixCapability { /// Rule can automatically fix all violations it detects FullyFixable, /// Rule can fix some violations based on context ConditionallyFixable, /// Rule cannot fix violations (by design) Unfixable, } /// Declares what cross-file data a rule needs /// /// Most rules only need single-file context and should use `None` (the default). /// Rules that need to validate references across files (like MD051) should use `Workspace`. #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] pub enum CrossFileScope { /// Single-file only - no cross-file analysis needed (default for 99% of rules) #[default] None, /// Needs workspace-wide index for cross-file validation Workspace, } /// A warning an inline disable comment kept out of a document's results. #[derive(Debug, Clone, PartialEq, Eq)] pub struct SuppressedWarning { /// Canonical id of the rule that raised the warning, e.g. `MD013` pub rule_name: String, /// 1-indexed line of the warning's range the rule was found disabled on pub line: usize, /// The kind of directive that disabled the rule there pub layer: crate::inline_config::DisableLayer, } /// What a run's inline disable comments actually suppressed. /// /// Assembled once per document, after every single-file rule has run, so a rule /// reading it sees the complete picture. #[derive(Debug, Clone, Default)] pub struct SuppressionReport { /// Every warning an inline disable comment removed, in the order raised pub suppressed: Vec, /// Canonical ids of the rules whose findings this report accounts for. /// /// A rule outside this set produced nothing the report can see, so nothing /// can be concluded about a comment naming it. pub judged_rules: std::collections::HashSet, } pub trait Rule: DynClone + Send + Sync { fn name(&self) -> &'static str; fn description(&self) -> &'static str; /// Return raw diagnostics, including findings covered by inline disables. /// The lint driver filters them and records which comments suppressed them /// for observers such as MD087. Filtering them here loses that accounting. /// Disabled regions may still be excluded from inferred settings, and `fix` /// must honor them when rewriting content. fn check(&self, ctx: &LintContext) -> LintResult; fn fix(&self, ctx: &LintContext) -> Result; /// Return the native fix when computing findings already produces it. /// The result belongs only to this configured instance and exact context; /// callers discard it with the findings after any source rewrite. #[doc(hidden)] fn check_with_prepared_fix(&self, ctx: &LintContext) -> Result<(Vec, Option), LintError> { self.check(ctx).map(|warnings| (warnings, None)) } /// Apply this rule's native fixer using its already-computed findings. /// Callers must supply raw diagnostics from this configured instance and /// this exact immutable context. No findings survive a source rewrite. /// Custom rules keep their normal fixer unless they explicitly opt in. #[doc(hidden)] fn fix_with_diagnostics(&self, ctx: &LintContext, _warnings: &[LintWarning]) -> Result { self.fix(ctx) } /// Whether CLI fixing is exactly the application of this rule's diagnostic /// edits, filtered by inline disables. The engine can then consume the /// already-computed edits without checking the same source a second time. /// /// Opt in only when `fix()` performs no additional transformations. The /// default preserves custom fix implementations and third-party rules. /// When opting in, `should_skip(ctx)` must imply that applying the raw /// check diagnostics would leave the source unchanged as well. #[doc(hidden)] fn fixes_from_diagnostics(&self) -> bool { false } /// Built-in-only certificate for proving that a source revision needs no fix. /// External rules retain their existing check and fix behavior by default. #[doc(hidden)] fn native_format_policy(&self) -> Option { None } /// Check if this rule should quickly skip processing based on content. fn should_skip(&self, _ctx: &LintContext) -> bool { false } /// Get the category of this rule for selective processing fn category(&self) -> RuleCategory { RuleCategory::Other // Default implementation returns Other } /// Whether the content-category prefilter may skip this rule. /// /// The prefilter reads the document's shape alone: a `Link` rule is skipped /// for a document holding no links. A rule whose configuration widens what /// it reads answers `false` for that configuration, so that `should_skip` /// and `check` decide instead. MD051 and MD057 read frontmatter values on /// request, and a document can carry those with no link syntax at all. fn skippable_by_category(&self) -> bool { true } /// Return this concrete rule instance for type-based queries. fn as_any(&self) -> &dyn std::any::Any; // DocumentStructure has been merged into LintContext - this method is no longer used // fn as_maybe_document_structure(&self) -> Option<&dyn MaybeDocumentStructure> { // None // } /// Returns the rule name and default config table if the rule has config. /// If a rule implements this, it MUST be defined on the `impl Rule for ...` block, /// not just the inherent impl. /// /// This is user-facing: it backs `rumdl config`, `rumdl config --defaults` and /// `rumdl explain`, so every value here must be a real default the user could write /// back into a config file. A key whose default cannot be written down (an unset /// `Option`) is therefore absent. Config *validation* reads [`Rule::config_schema`] /// instead, which keeps such keys. fn default_config_section(&self) -> Option<(String, toml::Value)> { None } /// Returns the rule name and every config key the rule accepts, for validation. /// /// A key with no representable default (an unset `Option`, or a deserializer that /// accepts several TOML types) carries a sentinel value: the key name is recognized /// while its type check is skipped. Sentinels contain a NUL byte and must never /// reach user-facing output, which is why this is separate from /// [`Rule::default_config_section`]. /// /// Defaults to the user-facing table, which is correct for a rule whose every key /// has a representable default. fn config_schema(&self) -> Option<(String, toml::Value)> { self.default_config_section() } /// Returns the rule name and a JSON Schema for its config section. /// /// This is what `rumdl.schema.json` publishes for `[MD###]`, so an editor can /// complete the section's keys and explain each one. It comes from the same struct /// [`Rule::config_schema`] reads, so the keys an editor offers and the keys the loader /// accepts are one list. /// /// Rules whose config struct does not derive `schemars::JsonSchema` return `None` and /// keep the schema inferred from their defaults, which still types options but cannot /// describe them. Use [`impl_rule_config_schema`](crate::impl_rule_config_schema!) and /// derive `schemars::JsonSchema` on the struct to opt in. fn config_json_schema(&self) -> Option<(String, serde_json::Value)> { None } /// Returns config key aliases for this rule /// This allows rules to accept alternative config key names for backwards compatibility fn config_aliases(&self) -> Option> { None } /// Returns the list of config keys whose deserializer accepts more than one TOML /// type (e.g. either a scalar or a list). The schema is built from a serialized /// default that can only encode one variant, so the validator would reject the /// alternative form. The registry replaces the schema entry for each listed key /// with a polymorphic sentinel so type checking is skipped while the key name /// is still validated. The registry rewrites [`Rule::config_schema`], so /// `default_config_section()` keeps returning the clean user-facing default. fn polymorphic_config_keys(&self) -> &'static [&'static str] { &[] } /// Declares the fix capability of this rule fn fix_capability(&self) -> FixCapability { FixCapability::FullyFixable // Safe default for backward compatibility } /// Declares cross-file analysis requirements for this rule /// /// Returns `CrossFileScope::None` by default, meaning the rule only needs /// single-file context. Rules that need workspace-wide data should override /// this to return `CrossFileScope::Workspace`. fn cross_file_scope(&self) -> CrossFileScope { CrossFileScope::None } /// Contribute data to the workspace index during linting /// /// Called during the single-file linting phase for rules that return /// `CrossFileScope::Workspace`. Rules should extract headings, links, /// and other data needed for cross-file validation. /// /// This is called as a side effect of linting, so LintContext is already /// created - no duplicate parsing required. fn contribute_to_index(&self, _ctx: &LintContext, _file_index: &mut crate::workspace_index::FileIndex) { // Default: no contribution } /// Perform cross-file validation after all files have been linted /// /// Called once per file after the entire workspace has been indexed. /// Rules receive the file_index (from contribute_to_index) and the full /// workspace_index for cross-file lookups. /// /// Note: This receives the FileIndex instead of LintContext to avoid re-parsing /// each file. The FileIndex was already populated during contribute_to_index. /// /// Rules can use workspace_index methods for cross-file validation: /// - `get_file(path)` - to look up headings in target files (for MD051) /// - `files()` - to iterate all indexed files /// /// Returns additional warnings for cross-file issues. These are appended /// to the single-file warnings. fn cross_file_check( &self, _file_path: &std::path::Path, _file_index: &crate::workspace_index::FileIndex, _workspace_index: &crate::workspace_index::WorkspaceIndex, ) -> LintResult { Ok(Vec::new()) // Default: no cross-file warnings } /// Whether this rule reports on the inline comments that suppressed warnings /// /// Recording every suppression costs work on each file, so the linting driver /// does it only when a rule asks for it. A rule answering `true` receives the /// result through `check_suppressions`. fn observes_suppressions(&self) -> bool { false } /// Report on a document's inline disable comments /// /// Called once per document after every single-file rule has run, for rules /// that return `true` from `observes_suppressions`. The report says which /// warnings the comments removed and which rules the run can account for. /// /// Returns warnings that join the single-file warnings. fn check_suppressions(&self, _ctx: &LintContext, _report: &SuppressionReport) -> LintResult { Ok(Vec::new()) // Default: nothing to report } /// Factory: create a rule from config (if present), or use defaults. fn from_config(_config: &crate::config::Config) -> Box where Self: Sized, { panic!( "from_config not implemented for rule: {}", std::any::type_name::() ); } } // Implement the cloning logic for the Rule trait object dyn_clone::clone_trait_object!(Rule); /// Extension trait to add downcasting capabilities to Rule pub trait RuleExt { fn downcast_ref(&self) -> Option<&T>; } impl RuleExt for Box { fn downcast_ref(&self) -> Option<&T> { if std::any::TypeId::of::() == std::any::TypeId::of::() { unsafe { Some(&*std::ptr::from_ref(self.as_ref()).cast::()) } } else { None } } } #[cfg(test)] mod tests { use super::*; #[test] fn test_severity_serialization() { let warning = LintWarning { message: "Test warning".to_string(), line: 1, column: 1, end_line: 1, end_column: 10, severity: Severity::Warning, fix: None, rule_name: Some("MD001".to_string()), }; let serialized = serde_json::to_string(&warning).unwrap(); assert!(serialized.contains("\"severity\":\"warning\"")); let error = LintWarning { severity: Severity::Error, ..warning }; let serialized = serde_json::to_string(&error).unwrap(); assert!(serialized.contains("\"severity\":\"error\"")); } #[test] fn test_fix_serialization() { let fix = Fix::new(0..10, "fixed text".to_string()); let warning = LintWarning { message: "Test warning".to_string(), line: 1, column: 1, end_line: 1, end_column: 10, severity: Severity::Warning, fix: Some(fix), rule_name: Some("MD001".to_string()), }; let serialized = serde_json::to_string(&warning).unwrap(); assert!(serialized.contains("\"fix\"")); assert!(serialized.contains("\"replacement\":\"fixed text\"")); } #[test] fn test_rule_category_equality() { assert_eq!(RuleCategory::Heading, RuleCategory::Heading); assert_ne!(RuleCategory::Heading, RuleCategory::List); // Test all categories are distinct let categories = [ RuleCategory::Heading, RuleCategory::List, RuleCategory::CodeBlock, RuleCategory::Link, RuleCategory::Image, RuleCategory::Html, RuleCategory::Emphasis, RuleCategory::Whitespace, RuleCategory::Blockquote, RuleCategory::Table, RuleCategory::FrontMatter, RuleCategory::Other, ]; for (i, cat1) in categories.iter().enumerate() { for (j, cat2) in categories.iter().enumerate() { if i == j { assert_eq!(cat1, cat2); } else { assert_ne!(cat1, cat2); } } } } #[test] fn test_lint_error_conversions() { use std::io; // Test From let io_error = io::Error::new(io::ErrorKind::NotFound, "file not found"); let lint_error: LintError = io_error.into(); match lint_error { LintError::IoError(_) => {} _ => panic!("Expected IoError variant"), } // Test Display trait let invalid_input = LintError::InvalidInput("bad input".to_string()); assert_eq!(invalid_input.to_string(), "Invalid input: bad input"); let fix_failed = LintError::FixFailed("couldn't fix".to_string()); assert_eq!(fix_failed.to_string(), "Fix failed: couldn't fix"); let parsing_error = LintError::ParsingError("parse error".to_string()); assert_eq!(parsing_error.to_string(), "Parsing error: parse error"); } }