use crate::discovery::PathAliases; use crate::types::LineLength; use globset::{GlobMatcher, GlobSet, GlobSetBuilder}; use indexmap::IndexMap; use serde::{Deserialize, Serialize}; use std::collections::{BTreeMap, HashSet}; use std::fs; use std::io; use std::path::{Path, PathBuf}; use std::sync::{Arc, OnceLock}; use super::flavor::{MarkdownFlavor, normalize_key}; /// Represents a rule-specific configuration #[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, schemars::JsonSchema)] pub struct RuleConfig { /// Severity override for this rule (Error, Warning, or Info) #[serde(default, skip_serializing_if = "Option::is_none")] pub severity: Option, /// Configuration values for the rule #[serde(flatten)] #[schemars(schema_with = "arbitrary_value_schema")] pub values: BTreeMap, } impl RuleConfig { /// Set an option, replacing any equivalent spelling already configured. /// Unknown keys are stored verbatim; callers choose their normalization. pub(crate) fn set_option(&mut self, rule: &str, key: &str, value: toml::Value) { let registry = super::registry::default_registry(); let canonical = registry.canonical_config_key(rule, key); if let Some(canonical) = canonical { self.values .retain(|existing, _| registry.canonical_config_key(rule, existing) != Some(canonical)); } self.values.insert(canonical.unwrap_or(key).to_string(), value); } } /// Generate a JSON schema for arbitrary configuration values fn arbitrary_value_schema(_gen: &mut schemars::SchemaGenerator) -> schemars::Schema { schemars::json_schema!({ "type": "object", "additionalProperties": true }) } /// Represents the complete configuration loaded from rumdl.toml #[derive(Debug, Clone, Serialize, Deserialize, Default, schemars::JsonSchema)] #[schemars( description = "rumdl configuration for linting Markdown files. Rules can be configured individually using [MD###] sections with rule-specific options." )] pub struct Config { /// Path to a base config file to inherit settings from. /// Supports relative paths, absolute paths, `~/` for the home directory, and /// `$VAR` / `${VAR}` environment-variable expansion (a literal `$` is written `$$`). /// Example: `extends = "../base.rumdl.toml"` or `extends = "$GEM_PATH/base.rumdl.toml"` #[serde(default, skip_serializing_if = "Option::is_none")] pub extends: Option, /// Global configuration options #[serde(default)] pub global: GlobalConfig, /// Resolved CLI2 file-selection options; not native rumdl configuration. #[serde(skip)] #[schemars(skip)] pub cli2_ignores: Vec, /// Per-file rule ignores: maps file patterns to lists of rules to ignore. /// Patterns are relative to the project root; a leading `~/` expands to the /// home directory and absolute paths are matched as written. /// Example: { "README.md": ["MD033"], "docs/**/*.md": ["MD013"] } #[serde(default, rename = "per-file-ignores")] pub per_file_ignores: BTreeMap>, /// Per-file flavor overrides: maps file patterns to Markdown flavors. /// Patterns are relative to the project root; a leading `~/` expands to the /// home directory and absolute paths are matched as written. /// Example: { "docs/**/*.md": MkDocs, "**/*.mdx": MDX } /// Uses IndexMap to preserve config file order for "first match wins" semantics #[serde(default, rename = "per-file-flavor")] #[schemars(with = "BTreeMap")] pub per_file_flavor: IndexMap, /// Code block tools configuration for per-language linting and formatting /// using external tools like ruff, prettier, shellcheck, etc. #[serde(default, rename = "code-block-tools")] pub code_block_tools: crate::code_block_tools::CodeBlockToolsConfig, /// Rule-specific configurations (e.g., MD013, MD007, MD044) /// Each rule section can contain options specific to that rule. /// /// Common examples: /// - MD013: line_length, code_blocks, tables, headings /// - MD007: indent /// - MD003: style ("atx", "atx-closed", "setext") /// - MD044: names (array of proper names to check) /// /// See for full rule documentation. #[serde(flatten)] pub rules: BTreeMap, /// Rules holding at least one option value that came from a config file /// whose contents may not be quoted back (an `extends` target, whose path /// is arbitrary and whose text the extending project need not be able to /// read). The values apply as written; only a message about one has to /// leave it out. /// /// Granularity is the rule section, because that is what a rule's options /// are deserialized as: an error names one value but not which key it came /// from, so a section mixing an extended value with a directly named one /// withholds both. Erring that way keeps a message from carrying text the /// project never wrote. /// /// Provenance rather than configuration, so it stays out of the serialized /// form and the JSON schema. #[serde(skip)] #[schemars(skip)] pub withheld_rule_values: std::collections::BTreeSet, /// Project root directory, used for resolving relative paths in per-file-ignores #[serde(skip)] pub project_root: Option, #[serde(skip)] #[schemars(skip)] pub(super) per_file_ignores_cache: Arc>, #[serde(skip)] #[schemars(skip)] pub(super) per_file_flavor_cache: Arc>, /// Lazily-computed canonical form of `project_root`. /// /// `normalize_match_path` needs the canonical project root to strip /// prefixes from absolute file paths. Without this cache, every per-file /// lookup would re-canonicalize the project root (one syscall per file). /// /// ## Invariants /// /// - **Single-shot**: computed once on first use of [`Config::canonical_project_root`]. /// - **Never invalidated**: callers must not mutate `project_root` after /// the first call. `Config` is treated as immutable post-construction /// (the same assumption as `per_file_ignores_cache` and `per_file_flavor_cache`). /// - **Construction-time existence**: the cache stores `None` if /// `project_root` is unset, missing on disk, or otherwise can't be /// canonicalized. In practice `project_root` is set after walking up to /// `.git`, so the directory always exists at the time the cache is first /// read; if a caller sets `project_root` to a not-yet-existing path, /// the cache will permanently store `None`. /// - **`Arc` wrapping**: `Config` derives `Clone`, and clones share the /// same `OnceLock` so a value computed by one clone is observable to all. /// /// `cwd` deliberately is NOT cached symmetrically: callers read it fresh /// from `std::env::current_dir()` per call because tests (and embedding /// hosts like LSP servers) may legitimately mutate the process cwd /// between lookups. #[serde(skip)] #[schemars(skip)] pub(super) canonical_project_root_cache: Arc>>, } impl PartialEq for Config { fn eq(&self, other: &Self) -> bool { self.global == other.global && self.cli2_ignores == other.cli2_ignores && self.per_file_ignores == other.per_file_ignores && self.per_file_flavor == other.per_file_flavor && self.code_block_tools == other.code_block_tools && self.rules == other.rules && self.project_root == other.project_root } } #[derive(Debug)] pub(super) struct PerFileIgnoreCache { globset: GlobSet, rules: Vec>, /// Whether any pattern is absolute, i.e. whether matching has to consider /// the file's absolute path as well as its project-relative form. has_absolute: bool, /// Spellings of the file that absolute patterns reach through a symlink. aliases: PathAliases, } #[derive(Debug)] pub(super) struct PerFileFlavorCache { matchers: Vec<(GlobMatcher, MarkdownFlavor)>, /// See [`PerFileIgnoreCache::has_absolute`]. has_absolute: bool, /// See [`PerFileIgnoreCache::aliases`]. aliases: PathAliases, } /// The file's absolute path, for matching against absolute patterns, resolved /// whether or not the file exists yet. `None` when the caller has no absolute /// pattern to match (the common case, which must not pay for the resolution). fn absolute_match_path(file_path: &Path, has_absolute: bool) -> Option { if !has_absolute { return None; } Some(crate::discovery::resolve_for_matching(file_path)) } /// The file's other spellings, for matching against absolute patterns that /// named a location through a symlink (`/var/folders/**` on macOS, whose files /// canonicalize to `/private/var/folders/…`). Empty for the configurations that /// have no such pattern, which is nearly all of them. fn alias_match_paths(aliases: &PathAliases, absolute: Option<&Path>) -> Vec { match absolute { Some(absolute) if !aliases.is_empty() => aliases.spellings_of(absolute), _ => Vec::new(), } } impl Config { /// Whether CLI2 excludes this file before linting or formatting. pub fn is_cli2_ignored(&self, path: &Path) -> bool { self.cli2_ignores.iter().any(|scope| scope.matches(path)) } /// Check if the Markdown flavor is set to MkDocs pub fn is_mkdocs_flavor(&self) -> bool { self.global.flavor == MarkdownFlavor::MkDocs } // Future methods for when GFM and CommonMark are implemented: // pub fn is_gfm_flavor(&self) -> bool // pub fn is_commonmark_flavor(&self) -> bool /// Get the configured Markdown flavor pub fn markdown_flavor(&self) -> MarkdownFlavor { self.global.flavor } /// Apply per-rule `enabled` config to the global enable/disable lists. /// /// For `[MD060] enabled = true`: adds the rule to `extend_enable` and /// removes it from `disable` and `extend_disable`, ensuring the rule is active. /// /// For `[MD041] enabled = false`: adds the rule to `disable` and /// removes it from `extend_enable`, ensuring the rule is inactive. /// /// Per-rule `enabled` takes precedence over global lists when there /// is a conflict, since it represents a more specific intent. pub fn apply_per_rule_enabled(&mut self) { let mut to_enable: Vec = Vec::new(); let mut to_disable: Vec = Vec::new(); for (name, cfg) in &self.rules { match cfg.values.get("enabled") { Some(toml::Value::Boolean(true)) => { to_enable.push(name.clone()); } Some(toml::Value::Boolean(false)) => { to_disable.push(name.clone()); } _ => {} } } for name in to_enable { if !self.global.extend_enable.contains(&name) { self.global.extend_enable.push(name.clone()); } self.global.disable.retain(|n| n != &name); self.global.extend_disable.retain(|n| n != &name); } for name in to_disable { if !self.global.disable.contains(&name) { self.global.disable.push(name.clone()); } self.global.extend_enable.retain(|n| n != &name); } } /// Get the severity override for a specific rule, if configured pub fn get_rule_severity(&self, rule_name: &str) -> Option { self.rules.get(rule_name).and_then(|r| r.severity) } /// Return the canonical form of `project_root`, computed once and cached. /// /// Returns `None` if `project_root` is unset, doesn't exist on disk, or /// otherwise cannot be canonicalized. Subsequent calls reuse the cached /// value, eliminating the per-file `canonicalize()` syscall that /// `normalize_match_path` would otherwise perform. pub(super) fn canonical_project_root(&self) -> Option<&Path> { self.canonical_project_root_cache .get_or_init(|| { self.project_root .as_deref() .and_then(crate::discovery::canonicalize_for_matching) }) .as_deref() } /// Get the set of rules that should be ignored for a specific file based on per-file-ignores configuration /// Returns a HashSet of rule names (uppercase, e.g., "MD033") that match the given file path pub fn get_ignored_rules_for_file(&self, file_path: &Path) -> HashSet { let mut ignored_rules = HashSet::new(); if self.per_file_ignores.is_empty() { return ignored_rules; } let path_for_matching = normalize_match_path(file_path, self.canonical_project_root(), || { std::env::current_dir().ok() }); let cache = self .per_file_ignores_cache .get_or_init(|| PerFileIgnoreCache::new(&self.per_file_ignores)); // Match the file path against all patterns, by its project-relative // form and - for absolute patterns, including expanded `~` ones - by // its absolute path and by the spellings of that path a pattern named // through a symlink. let absolute = absolute_match_path(file_path, cache.has_absolute); let aliases = alias_match_paths(&cache.aliases, absolute.as_deref()); let matches = cache .globset .matches(path_for_matching.as_ref()) .into_iter() .chain(absolute.iter().flat_map(|abs| cache.globset.matches(abs))) .chain(aliases.iter().flat_map(|alias| cache.globset.matches(alias))); for match_idx in matches { if let Some(rules) = cache.rules.get(match_idx) { for rule in rules { // Normalize rule names to uppercase (MD033, md033 -> MD033) ignored_rules.insert(rule.clone()); } } } ignored_rules } /// Get the MarkdownFlavor for a specific file based on per-file-flavor configuration. /// Returns the first matching pattern's flavor, or falls back to global flavor, /// or auto-detects from extension, or defaults to Standard. pub fn get_flavor_for_file(&self, file_path: &Path) -> MarkdownFlavor { // If no per-file patterns, use fallback logic if self.per_file_flavor.is_empty() { return self.resolve_flavor_fallback(file_path); } let path_for_matching = normalize_match_path(file_path, self.canonical_project_root(), || { std::env::current_dir().ok() }); let cache = self .per_file_flavor_cache .get_or_init(|| PerFileFlavorCache::new(&self.per_file_flavor)); // Iterate in config order and return first match (IndexMap preserves order). // Each pattern sees the file's project-relative form and - for absolute // patterns, including expanded `~` ones - its absolute path and the // spellings of that path a pattern named through a symlink. let absolute = absolute_match_path(file_path, cache.has_absolute); let aliases = alias_match_paths(&cache.aliases, absolute.as_deref()); for (matcher, flavor) in &cache.matchers { if matcher.is_match(path_for_matching.as_ref()) || absolute.as_ref().is_some_and(|abs| matcher.is_match(abs)) || aliases.iter().any(|alias| matcher.is_match(alias)) { return *flavor; } } // No pattern matched, use fallback self.resolve_flavor_fallback(file_path) } /// Fallback flavor resolution: global flavor → auto-detect → Standard fn resolve_flavor_fallback(&self, file_path: &Path) -> MarkdownFlavor { // If global flavor is explicitly set to non-Standard, use it if self.global.flavor != MarkdownFlavor::Standard { return self.global.flavor; } // Auto-detect from extension MarkdownFlavor::from_path(file_path) } /// Canonicalize every rule-name list inside this `Config`. /// /// This is the single enforcement point for the runtime invariant: /// **after a `Config` is fully built, every rule-name list contains /// canonical rule IDs (`"MD033"`) — never aliases (`"no-inline-html"`).** /// /// The invariant lets every consumer (`rules::filter_rules`, the LSP, /// WASM, fix coordinator, per-file-ignore lookups) match against /// `Rule::name()` with simple string equality. Mutation boundaries /// (`From for Config`, LSP `apply_lsp_settings_*`, WASM /// `to_config_with_warnings`) call this before handing the `Config` to /// the linting pipeline. /// /// Covers `global.{enable,disable,extend_enable,extend_disable,fixable,unfixable}` /// and the values of `per_file_ignores`. Idempotent. pub fn canonicalize_rule_lists(&mut self) { use super::registry::canonicalize_rule_list_in_place; self.global.canonicalize_rule_lists(); for rules in self.per_file_ignores.values_mut() { canonicalize_rule_list_in_place(rules); } } /// Merge inline configuration overrides into a copy of this config /// /// This enables automatic inline config support - the engine can merge /// inline overrides and recreate rules without any per-rule changes. /// /// Returns a new Config with the inline overrides merged in. /// If there are no inline overrides, returns a clone of self. pub fn merge_with_inline_config(&self, inline_config: &crate::inline_config::InlineConfig) -> Self { let overrides = inline_config.get_all_rule_configs(); if overrides.is_empty() { return self.clone(); } let mut merged = self.clone(); for (rule_name, json_override) in overrides { // Get or create the rule config entry let rule_config = merged.rules.entry(rule_name.clone()).or_default(); // Merge JSON values into the rule's config if let Some(obj) = json_override.as_object() { for (key, value) in obj { if let Some(toml_value) = json_to_toml(value) { rule_config.set_option(rule_name, &key.replace('_', "-"), toml_value); } } } } merged } } /// Normalize a file path for matching against a glob pattern from configuration. /// /// Glob patterns in `per-file-ignores` and `per-file-flavor` are written relative /// to the project root (e.g. `docs/**/*.md`), and a glob is anchored at the start /// of the string it matches, so an absolute path like `/home/user/proj/docs/x.md` /// will not match `docs/**/*.md`. This helper produces the form the glob expects: /// /// 1. **Relative path** → return as-is. /// 2. **Absolute path under `project_root`** → return path relative to `project_root`. /// 3. **Absolute path under `cwd`** → return path relative to `cwd`. This is the /// safety net for invocations where `project_root` could not be discovered /// (no `.git` upward, LSP/CLI calls outside a project) but the file still /// lives somewhere under the working directory. /// 4. **Anywhere else** → return the raw path. A relative glob simply won't /// match it, which is the desired outcome for files outside any known root. /// /// An absolute path need not exist: an editor buffer or a file about to be /// created is resolved through its deepest existing ancestor (see /// [`crate::discovery::resolve_for_matching`]), so it matches the patterns it /// will match once written. /// /// `canonical_project_root` is expected to already be canonical (via /// `Config::canonical_project_root`). `cwd` yields the working directory, which /// is canonicalized here: it is read fresh on each call, and only once the /// project root has failed to claim the file, since reading it walks the path /// on macOS and a file under the project root never needs it. pub(super) fn normalize_match_path<'a>( file_path: &'a Path, canonical_project_root: Option<&Path>, cwd: impl FnOnce() -> Option, ) -> std::borrow::Cow<'a, Path> { use std::borrow::Cow; if file_path.is_relative() { return Cow::Borrowed(file_path); } let canonical_file = crate::discovery::resolve_for_matching(file_path); if let Some(root) = canonical_project_root && let Ok(rel) = canonical_file.strip_prefix(root) { return Cow::Owned(rel.to_path_buf()); } let cwd = cwd(); if let Some(working_dir) = cwd.as_deref() && let Some(canonical_cwd) = crate::discovery::canonicalize_for_matching(working_dir) && let Ok(rel) = canonical_file.strip_prefix(&canonical_cwd) { return Cow::Owned(rel.to_path_buf()); } // Surface the silent fallback once per process at warn level so users with // per-file glob configs notice when their patterns can't match a file. // Subsequent occurrences stay at debug to avoid log spam. static SILENT_FALLBACK_WARNED: OnceLock<()> = OnceLock::new(); log::log!( first_call_warn_else_debug(&SILENT_FALLBACK_WARNED), "{}", format_silent_fallback_message(file_path, canonical_project_root, cwd.as_deref()), ); Cow::Borrowed(file_path) } /// Returns [`log::Level::Warn`] the first time it is called with a given /// `latch`, and [`log::Level::Debug`] on every subsequent call. The latch /// is consumed by the first caller via `OnceLock::set`; later callers /// observe the latch as already set and downgrade. /// /// Used to flag a fallback condition once per process without flooding /// logs when the same condition recurs (e.g. once per linted file). pub(super) fn first_call_warn_else_debug(latch: &OnceLock<()>) -> log::Level { if latch.set(()).is_ok() { log::Level::Warn } else { log::Level::Debug } } /// Format the diagnostic emitted when [`normalize_match_path`] cannot /// relativise `file_path` against either the project root or the current /// working directory. Extracted so the exact wording can be asserted in /// tests without capturing log output. pub(super) fn format_silent_fallback_message( file_path: &Path, canonical_project_root: Option<&Path>, cwd: Option<&Path>, ) -> String { format!( "Per-file glob patterns will not match {}: file is outside project_root ({}) and cwd ({})", file_path.display(), DisplayPathOrUnset(canonical_project_root), DisplayPathOrUnset(cwd), ) } /// Display adapter for `Option<&Path>` that renders the path via /// [`Path::display`] when present, or the literal `` when absent. /// Angle brackets follow Rust's diagnostic convention (e.g. ``) /// and avoid double-paren rendering when the surrounding format string /// already wraps the value in `(…)`. struct DisplayPathOrUnset<'a>(Option<&'a Path>); impl std::fmt::Display for DisplayPathOrUnset<'_> { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self.0 { Some(path) => std::fmt::Display::fmt(&path.display(), f), None => f.write_str(""), } } } /// Convert a serde_json::Value to a toml::Value pub(super) fn json_to_toml(json: &serde_json::Value) -> Option { match json { serde_json::Value::Null => None, serde_json::Value::Bool(b) => Some(toml::Value::Boolean(*b)), serde_json::Value::Number(n) => n .as_i64() .map(toml::Value::Integer) .or_else(|| n.as_f64().map(toml::Value::Float)), serde_json::Value::String(s) => Some(toml::Value::String(s.clone())), serde_json::Value::Array(arr) => { let toml_arr: Vec = arr.iter().filter_map(json_to_toml).collect(); Some(toml::Value::Array(toml_arr)) } serde_json::Value::Object(obj) => { let mut table = toml::map::Map::new(); for (k, v) in obj { if let Some(tv) = json_to_toml(v) { table.insert(k.clone(), tv); } } Some(toml::Value::Table(table)) } } } impl PerFileIgnoreCache { fn new(per_file_ignores: &BTreeMap>) -> Self { let mut builder = GlobSetBuilder::new(); let mut rules = Vec::new(); let mut has_absolute = false; for (pattern, rules_list) in per_file_ignores { let pattern = crate::discovery::prepare_pattern(pattern); has_absolute |= crate::discovery::has_absolute_spelling(&pattern); if let Ok(glob) = crate::discovery::path_glob(&pattern, false) { builder.add(glob); // Canonicalize defensively: callers should have run // Config::canonicalize_rule_lists already, but per-file-ignores // has reached this cache directly from a few code paths // historically, so we re-canonicalize here to keep the cache // sound regardless of caller discipline. rules.push( rules_list .iter() .map(|rule| super::registry::resolve_rule_name(rule)) .collect(), ); } else { log::warn!("Invalid glob pattern in per-file-ignores: {pattern}"); } } let globset = builder.build().unwrap_or_else(|e| { log::error!("Failed to build globset for per-file-ignores: {e}"); GlobSetBuilder::new().build().unwrap() }); Self { globset, rules, has_absolute, aliases: PathAliases::new(per_file_ignores.keys().map(String::as_str)), } } } impl PerFileFlavorCache { fn new(per_file_flavor: &IndexMap) -> Self { let mut matchers = Vec::new(); let mut has_absolute = false; for (pattern, flavor) in per_file_flavor { let pattern = crate::discovery::prepare_pattern(pattern); has_absolute |= crate::discovery::has_absolute_spelling(&pattern); if let Ok(glob) = crate::discovery::path_glob(&pattern, true) { matchers.push((glob.compile_matcher(), *flavor)); } else { log::warn!("Invalid glob pattern in per-file-flavor: {pattern}"); } } Self { matchers, has_absolute, aliases: PathAliases::new(per_file_flavor.keys().map(String::as_str)), } } } /// Global configuration options #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, schemars::JsonSchema)] #[serde(default, rename_all = "kebab-case")] pub struct GlobalConfig { /// Enabled rules #[serde(default)] pub enable: Vec, /// Disabled rules #[serde(default)] pub disable: Vec, /// Files to exclude. Glob patterns, relative to the project root; a /// leading `~/` expands to the home directory and absolute paths are /// matched as written. #[serde(default)] pub exclude: Vec, /// Files to include. Glob patterns, relative to the project root; a /// leading `~/` expands to the home directory and absolute paths are /// matched as written. #[serde(default)] pub include: Vec, /// Respect .gitignore, .ignore and git exclude files when scanning /// directories. .markdownlintignore applies regardless, and explicitly /// named files bypass both. #[serde(default = "default_respect_gitignore", alias = "respect_gitignore")] pub respect_gitignore: bool, /// Global line length setting (used by MD013 and other rules if not overridden) #[serde(default, alias = "line_length")] pub line_length: LineLength, /// Output format for linting results (e.g., "text", "json", "pylint", etc.) #[serde(skip_serializing_if = "Option::is_none", alias = "output_format")] pub output_format: Option, /// Rules that are allowed to be fixed when --fix is used /// If specified, only these rules will be fixed #[serde(default)] pub fixable: Vec, /// Rules that should never be fixed, even when --fix is used /// Takes precedence over fixable #[serde(default)] pub unfixable: Vec, /// Markdown flavor/dialect to use (mkdocs, gfm, commonmark, etc.) /// When set, adjusts parsing and validation rules for that specific Markdown variant #[serde(default)] pub flavor: MarkdownFlavor, /// \[DEPRECATED\] Whether to enforce exclude patterns for explicitly passed paths. /// This option is deprecated as of v0.0.156 and has no effect. /// Exclude patterns are now always respected, even for explicitly provided files. /// This prevents duplication between rumdl config and tool configs like pre-commit. #[serde(default, alias = "force_exclude")] #[deprecated(since = "0.0.156", note = "Exclude patterns are now always respected")] pub force_exclude: bool, /// Directory to store cache files (default: .rumdl_cache). /// A leading `~/` expands to the home directory; a relative path resolves /// against the project root. /// Can also be set via --cache-dir CLI flag or RUMDL_CACHE_DIR environment variable #[serde(default, alias = "cache_dir", skip_serializing_if = "Option::is_none")] pub cache_dir: Option, /// Whether caching is enabled (default: true) /// Can also be disabled via --no-cache CLI flag #[serde(default = "default_true")] pub cache: bool, /// Additional rules to enable on top of the base set (additive) #[serde(default, alias = "extend_enable")] pub extend_enable: Vec, /// Additional rules to disable on top of the base set (additive) #[serde(default, alias = "extend_disable")] pub extend_disable: Vec, /// Whether to read settings from `.editorconfig` files (default: false). /// When enabled, the `.editorconfig` properties that map onto rumdl /// settings fill in anything no rumdl config sets, resolved per file so /// section globs and nested `.editorconfig` files apply as written. #[serde(default)] pub editorconfig: bool, /// Whether the enable list was explicitly set (even if empty). /// Used to distinguish "no enable list configured" from "enable list is empty" /// (e.g., markdownlint `default: false` with no rules enabled). #[serde(skip)] pub enable_is_explicit: bool, /// How to name the file that supplied [`Self::include`] when a message about /// those patterns may not quote them (an `extends` target, whose path is /// arbitrary and whose text the extending project need not be able to read), /// and `None` when it may. Provenance rather than configuration, so it stays /// out of the serialized form and the JSON schema. #[serde(skip)] pub include_withheld: Option, } fn default_respect_gitignore() -> bool { true } fn default_true() -> bool { true } // Add the Default impl impl Default for GlobalConfig { #[allow(deprecated)] fn default() -> Self { Self { enable: Vec::new(), disable: Vec::new(), exclude: Vec::new(), include: Vec::new(), respect_gitignore: true, line_length: LineLength::default(), output_format: None, fixable: Vec::new(), unfixable: Vec::new(), flavor: MarkdownFlavor::default(), force_exclude: false, cache_dir: None, cache: true, extend_enable: Vec::new(), extend_disable: Vec::new(), editorconfig: false, enable_is_explicit: false, include_withheld: None, } } } impl GlobalConfig { /// Canonicalize every rule-name list in this `GlobalConfig`. /// /// Rewrites `enable`, `disable`, `extend_enable`, `extend_disable`, `fixable`, /// and `unfixable` so that all entries are canonical rule IDs (`"MD033"`) /// rather than aliases (`"no-inline-html"`). Duplicates are removed, /// preserving first-occurrence order; the special `"all"` keyword is /// preserved. /// /// This must be called by every code path that mutates a runtime /// `Config`'s rule lists from external input (markdownlint configs, /// `.rumdl.toml`, LSP `initializationOptions`, WASM bindings, etc.) so /// that downstream consumers (`rules::filter_rules`, the LSP, WASM) can /// match against `Rule::name()` with simple string equality. pub fn canonicalize_rule_lists(&mut self) { use super::registry::canonicalize_rule_list_in_place; canonicalize_rule_list_in_place(&mut self.enable); canonicalize_rule_list_in_place(&mut self.disable); canonicalize_rule_list_in_place(&mut self.extend_enable); canonicalize_rule_list_in_place(&mut self.extend_disable); canonicalize_rule_list_in_place(&mut self.fixable); canonicalize_rule_list_in_place(&mut self.unfixable); } } /// Names of rumdl-native config files, searched in precedence order when /// walking up a directory tree. /// /// This is the single source of truth for config discovery. Both the CLI /// (`SourcedConfig::discover_config_upward`, `discover_config_for_dir`) and /// the LSP (`RumdlLanguageServer::resolve_config_for_file`) must use this /// list; any deviation causes silent config-not-found bugs where the CLI /// recognises a config but the LSP does not (or vice versa). /// /// See `src/lsp/tests.rs::test_lsp_cli_resolver_parity_on_fixtures` for /// the side-by-side resolver parity test that pins this invariant across /// several directory layouts. pub const RUMDL_CONFIG_FILES: &[&str] = &[".rumdl.toml", "rumdl.toml", ".config/rumdl.toml", "pyproject.toml"]; /// Names of markdownlint config files, in precedence order within one directory. /// /// `.markdownlint.*` files come first because markdownlint-cli2 lints with a /// directory's `.markdownlint.*` file in preference to the `config` of its /// `.markdownlint-cli2.*` file. pub const MARKDOWNLINT_CONFIG_FILES: &[&str] = &[ ".markdownlint.jsonc", ".markdownlint.json", ".markdownlint.yaml", ".markdownlint.yml", ".markdownlint-cli2.jsonc", ".markdownlint-cli2.yaml", ".markdownlint-cli2.yml", "markdownlint.json", "markdownlint.jsonc", "markdownlint.yaml", "markdownlint.yml", ]; /// Create a default configuration file at the specified path pub fn create_default_config(path: &str) -> Result<(), ConfigError> { create_preset_config("default", path) } /// Create a configuration file with a specific style preset pub fn create_preset_config(preset: &str, path: &str) -> Result<(), ConfigError> { if Path::new(path).exists() { return Err(ConfigError::FileExists { path: path.to_string() }); } let config_content = match preset { "default" => generate_default_preset(), "google" => generate_google_preset(), "relaxed" => generate_relaxed_preset(), _ => { return Err(ConfigError::UnknownPreset { name: preset.to_string(), }); } }; match fs::write(path, config_content) { Ok(_) => Ok(()), Err(err) => Err(ConfigError::IoError { source: err, path: path.to_string(), }), } } /// Generate the default preset configuration content. /// Returns the same content as `create_default_config`. fn generate_default_preset() -> String { r#"# rumdl configuration file # Inherit settings from another config file (relative to this file's directory) # extends = "../base.rumdl.toml" # Global configuration options [global] # List of rules to disable (uncomment and modify as needed) # disable = ["MD013", "MD033"] # List of rules to enable exclusively (replaces defaults; only these rules will run) # enable = ["MD001", "MD003", "MD004"] # Additional rules to enable on top of defaults (additive, does not replace) # Use this to activate opt-in rules like MD060, MD063, MD072, MD073, MD074 # extend-enable = ["MD060", "MD063"] # Additional rules to disable on top of the disable list (additive) # extend-disable = ["MD041"] # List of file/directory patterns to include for linting (if provided, only these will be linted) # include = [ # "docs/*.md", # "src/**/*.md", # "README.md" # ] # List of file/directory patterns to exclude from linting exclude = [ # Common directories to exclude ".git", ".github", "node_modules", "vendor", "dist", "build", # Specific files or patterns "CHANGELOG.md", "LICENSE.md", ] # Respect .gitignore, .ignore and git exclude files when scanning directories # (default: true). .markdownlintignore applies regardless. respect-gitignore = true # Markdown flavor/dialect (uncomment to enable) # Options: standard (default), gfm, commonmark, mkdocs, mdx, pandoc, quarto, obsidian, kramdown, azure_devops, myst, hugo, mdg, gh-aw # flavor = "mkdocs" # Rule-specific configurations (uncomment and modify as needed) # [MD003] # style = "atx" # Heading style (atx, atx_closed, setext) # [MD004] # style = "asterisk" # Unordered list style (asterisk, plus, dash, consistent) # [MD007] # indent = 4 # Unordered list indentation # [MD013] # line-length = 100 # Line length # code-blocks = false # Exclude code blocks from line length check # tables = false # Exclude tables from line length check # headings = true # Include headings in line length check # [MD044] # names = ["rumdl", "Markdown", "GitHub"] # Proper names that should be capitalized correctly # code-blocks = false # Check code blocks for proper names (default: false, skips code blocks) "# .to_string() } /// Generate Google developer documentation style preset. /// Based on fn generate_google_preset() -> String { r#"# rumdl configuration - Google developer documentation style # Based on https://google.github.io/styleguide/docguide/style.html [global] exclude = [ ".git", ".github", "node_modules", "vendor", "dist", "build", "CHANGELOG.md", "LICENSE.md", ] respect-gitignore = true # ATX-style headings required [MD003] style = "atx" # Unordered list style: dash [MD004] style = "dash" # 4-space indent for nested lists [MD007] indent = 4 # Strict mode: no trailing spaces allowed (Google uses backslash for line breaks) [MD009] strict = true # 80-character line length [MD013] line-length = 80 code-blocks = false tables = false # No trailing punctuation in headings [MD026] punctuation = ".,;:!。,;:!" # Fenced code blocks only (no indented code blocks) [MD046] style = "fenced" # Emphasis with underscores [MD049] style = "underscore" # Strong with asterisks [MD050] style = "asterisk" "# .to_string() } /// Generate relaxed preset for existing projects adopting rumdl incrementally. /// Longer line lengths, fewer rules, lenient settings to minimize initial warnings. fn generate_relaxed_preset() -> String { r#"# rumdl configuration - Relaxed preset # Lenient settings for existing projects adopting rumdl incrementally. # Minimizes initial warnings while still catching important issues. [global] exclude = [ ".git", ".github", "node_modules", "vendor", "dist", "build", "CHANGELOG.md", "LICENSE.md", ] respect-gitignore = true # Disable rules that produce the most noise on existing projects disable = [ "MD013", # Line length - most existing files exceed 80 chars "MD033", # Inline HTML - commonly used in real-world markdown "MD041", # First line heading - not all files need it ] # Consistent heading style (any style, just be consistent) [MD003] style = "consistent" # Consistent list style [MD004] style = "consistent" # Consistent emphasis style [MD049] style = "consistent" # Consistent strong style [MD050] style = "consistent" "# .to_string() } /// How a config file being loaded was reached, which decides how much of it may /// appear in a message about it. /// /// A `Direct` file is one the user named: discovered in their project, or given /// on the command line. Naming its path and quoting the line a parse error /// points at tells them nothing they could not already read. /// /// An `Extends` file was reached by following an `extends` value, and two things /// about it are not the user's to see. Its path is built by substituting /// environment variables, so printing the path prints their values wherever the /// error goes, which under CI is the build log. And `extends` names an arbitrary /// path chosen by whichever config declared it, so the file need not be config /// at all: a repository you merely cloned can point rumdl at a private key and /// have the parse error quote a line of it. Such a file is named by the /// `extends` value as written, and its text is never quoted back. /// /// This governs errors and warnings, which any lint run can emit unasked and /// which therefore reach a build log that had no reason to hold a variable's /// value. Output that answers a question about the configuration itself still /// shows resolved paths, because that is the answer: `rumdl config` reports which /// files took effect, a language server reports the same thing to the editor that /// started it, and debug logging is how an `extends` chain gets diagnosed at all. /// The first two read [`crate::config::SourcedConfig::loaded_files`], which is a /// record of what loaded rather than a message about a problem, and it holds /// resolved paths deliberately. #[derive(Debug, Clone, Copy)] pub(crate) enum ConfigOrigin<'a> { Direct, Extends { /// The reference together with the config that declared it. This is how /// the file is named by a message reporting a problem with the file /// itself, where knowing which config reached for it is what makes the /// problem diagnosable. described_as: &'a str, /// The reference alone, for the places a message only needs to identify /// the file: listing an `extends` chain, or naming it as the config that /// declared a further `extends`. Repeating the full form at every link /// nests one description inside the next. short_name: &'a str, }, } /// Stands in for text that came out of a file reached through `extends`. /// /// Public because the file walk raises one of these messages itself: an `include` /// pattern is judged where it is used rather than where it is parsed. pub const WITHHELD: &str = ""; impl ConfigOrigin<'_> { /// How to name the file this origin describes in a message about the file. pub(crate) fn display_name(&self, path: &str) -> String { match self { Self::Direct => crate::config::validation::to_relative_display_path(path), Self::Extends { described_as, .. } => (*described_as).to_string(), } } /// How to name this file when a message is about something else and only has /// to say which file it means. pub(crate) fn short_name(&self, path: &str) -> String { match self { Self::Direct => crate::config::validation::to_relative_display_path(path), Self::Extends { short_name, .. } => (*short_name).to_string(), } } /// Whether a message about this file may quote the file's own text. pub(crate) fn may_quote_contents(&self) -> bool { matches!(self, Self::Direct) } /// A piece of text read from this file, as a message about the file may /// show it. /// /// A `Direct` file's text is shown as written. An `Extends` target's is /// replaced by [`WITHHELD`], because an unrecognized key or an invalid value /// is still text out of a file rumdl was merely pointed at. The message /// keeps saying what kind of problem it found and which file holds it, and /// leaves the rest to whoever can open that file. pub(crate) fn quote<'t>(&self, text: &'t str) -> &'t str { if self.may_quote_contents() { text } else { WITHHELD } } } /// A config file as a message about it refers to it: the name to use, and /// whether the file's own text may be shown alongside. /// /// Pairs the display name, worked out once when a file is parsed, with the /// [`ConfigOrigin`] that decided it. Every warning a parser emits names the file /// and asks the same question about its contents, so both travel together rather /// than as two parameters that could drift apart. #[derive(Debug, Clone, Copy)] pub(crate) struct ConfigRef<'a> { name: &'a str, origin: ConfigOrigin<'a>, } impl<'a> ConfigRef<'a> { pub(crate) fn new(name: &'a str, origin: ConfigOrigin<'a>) -> Self { Self { name, origin } } /// See [`ConfigOrigin::quote`]. pub(crate) fn quote<'t>(&self, text: &'t str) -> &'t str { self.origin.quote(text) } /// See [`ConfigOrigin::may_quote_contents`]. pub(crate) fn may_quote_contents(&self) -> bool { self.origin.may_quote_contents() } } /// Displays as the file's name, so a message can name the file by interpolating /// the reference itself. impl std::fmt::Display for ConfigRef<'_> { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.write_str(self.name) } } /// Errors that can occur when loading configuration #[derive(Debug, thiserror::Error)] pub enum ConfigError { /// Failed to read the configuration file #[error("Failed to read config file at {path}: {source}")] IoError { source: io::Error, path: String }, /// Failed to parse the configuration content (TOML or JSON) #[error("Failed to parse config: {0}")] ParseError(String), /// Configuration file already exists #[error("Configuration file already exists at {path}")] FileExists { path: String }, /// Circular extends reference detected #[error("Circular extends reference: {path} already in chain {chain:?}")] CircularExtends { path: String, chain: Vec }, /// Extends chain exceeds maximum depth #[error("Extends chain exceeds maximum depth of {max_depth} at {path}")] ExtendsDepthExceeded { path: String, max_depth: usize }, /// Extends target file not found #[error("extends target not found: {path} (referenced from {from})")] ExtendsNotFound { path: String, from: String }, /// An `extends` path referenced an environment variable that is not set #[error("extends path references undefined environment variable {var} (referenced from {from})")] ExtendsUndefinedVar { /// The variable as the message may name it: `$NAME`, or [`WITHHELD`] when /// the file that wrote it was itself reached through `extends` and its /// text may not be repeated. var: String, from: String, }, /// Unknown preset name #[error("Unknown preset: {name}. Valid presets: default, google, relaxed")] UnknownPreset { name: String }, } /// Why a config file found by discovery could not be loaded. /// /// The two cases call for different handling. A discovered project file that /// cannot be parsed is local to one project and a caller may reasonably skip it /// and keep looking. A broken user config is machine-wide: every project that /// merges onto it resolves to something other than what the user configured, so /// it has to be surfaced instead of worked around. #[derive(Debug, thiserror::Error)] pub enum DiscoveredConfigError { /// The discovered file itself is unusable. #[error(transparent)] ProjectConfig(ConfigError), /// The discovered file is fine, but the user config it merges on top of is /// unusable. Only a discovered markdownlint config has such a base. #[error(transparent)] UserConfig(ConfigError), } impl From for ConfigError { fn from(error: DiscoveredConfigError) -> Self { match error { DiscoveredConfigError::ProjectConfig(error) | DiscoveredConfigError::UserConfig(error) => error, } } } /// Get a rule-specific configuration value /// Automatically tries both the original key and normalized variants (kebab-case ↔ snake_case) /// for better markdownlint compatibility pub fn get_rule_config_value(config: &Config, rule_name: &str, key: &str) -> Option { let norm_rule_name = rule_name.to_ascii_uppercase(); // Use uppercase for lookup let rule_config = config.rules.get(&norm_rule_name)?; if let Some(canonical) = super::registry::default_registry().canonical_config_key(&norm_rule_name, key) && let Some(value) = rule_config.values.get(canonical) && let Ok(result) = T::deserialize(value.clone()) { return Some(result); } // Try multiple key variants to support both underscore and kebab-case formats let key_variants = [ key.to_string(), // Original key as provided normalize_key(key), // Normalized key (lowercase, kebab-case) key.replace('-', "_"), // Convert kebab-case to snake_case key.replace('_', "-"), // Convert snake_case to kebab-case ]; // Try each variant until we find a match for variant in &key_variants { if let Some(value) = rule_config.values.get(variant) && let Ok(result) = T::deserialize(value.clone()) { return Some(result); } } None } /// Generate preset configuration for pyproject.toml format. /// Converts the .rumdl.toml preset to pyproject.toml section format. pub fn generate_pyproject_preset_config(preset: &str) -> Result { match preset { "default" => Ok(generate_pyproject_config()), other => { let rumdl_config = match other { "google" => generate_google_preset(), "relaxed" => generate_relaxed_preset(), _ => { return Err(ConfigError::UnknownPreset { name: other.to_string(), }); } }; Ok(convert_rumdl_to_pyproject(&rumdl_config)) } } } /// Convert a .rumdl.toml config string to pyproject.toml format. /// Rewrites `[global]` → `[tool.rumdl]` and `[MDXXX]` → `[tool.rumdl.MDXXX]`. fn convert_rumdl_to_pyproject(rumdl_config: &str) -> String { let mut output = String::with_capacity(rumdl_config.len() + 128); for line in rumdl_config.lines() { let trimmed = line.trim(); if trimmed.starts_with('[') && trimmed.ends_with(']') && !trimmed.starts_with("# [") { let section = &trimmed[1..trimmed.len() - 1]; if section == "global" { output.push_str("[tool.rumdl]"); } else { output.push_str(&format!("[tool.rumdl.{section}]")); } } else { output.push_str(line); } output.push('\n'); } output } /// Generate default rumdl configuration for pyproject.toml pub fn generate_pyproject_config() -> String { let config_content = r#" [tool.rumdl] # Global configuration options line-length = 100 disable = [] # extend-enable = ["MD060"] # Add opt-in rules (additive, keeps defaults) # extend-disable = [] # Additional rules to disable (additive) exclude = [ # Common directories to exclude ".git", ".github", "node_modules", "vendor", "dist", "build", ] respect-gitignore = true # Rule-specific configurations (uncomment and modify as needed) # [tool.rumdl.MD003] # style = "atx" # Heading style (atx, atx_closed, setext) # [tool.rumdl.MD004] # style = "asterisk" # Unordered list style (asterisk, plus, dash, consistent) # [tool.rumdl.MD007] # indent = 4 # Unordered list indentation # [tool.rumdl.MD013] # line-length = 100 # Line length # code-blocks = false # Exclude code blocks from line length check # tables = false # Exclude tables from line length check # headings = true # Include headings in line length check # [tool.rumdl.MD044] # names = ["rumdl", "Markdown", "GitHub"] # Proper names that should be capitalized correctly # code-blocks = false # Check code blocks for proper names (default: false, skips code blocks) "#; config_content.to_string() }