fix(config): accept every config key a rule actually reads

Config validation read `default_config_section()`, the same table that backs
`rumdl config --defaults` and `rumdl explain`. That table is a listing of
defaults, so a key whose default cannot be written down is absent from it: an
unset `Option` has no value a user could copy, and inventing one would read as
a real setting. Those keys were therefore rejected as "Unknown option" even
though the rule deserialized and honored them. MD001's
`front-matter-title-pattern` worked and was warned about on every run.

Validation now reads a separate `Rule::config_schema()`, derived from the same
struct `from_config` deserializes, so the accepted keys cannot drift from the
honored ones. A key with no representable default carries a sentinel there: the
name is recognized while its type check is skipped. Sentinels contain a NUL
byte and are unwritable as TOML, which is what keeps them out of the listing.

The two halves are pinned against each other rather than spot-checked: every
published default must be accepted by the validator, every schema key must
survive a real load-and-validate, no user-facing table may carry a sentinel,
and `rumdl config --defaults` must produce a config rumdl itself accepts.
Reported in #794.

Author: rvben

docs/md001.md

@@ -44,7 +44,48 @@ Prevents skipping heading levels (like jumping from # to ### without ##).
 
 ## Configuration
 
-This rule has no configuration options.
+```toml
+[MD001]
+front-matter-title = true  # Count a title in front matter as an implicit level 1 heading (default: true)
+front-matter-title-pattern = "^(title|header):"  # Regex matching the front matter line that holds the title
+```
+
+### `front-matter-title`
+
+A document whose front matter carries a title starts at level 1 already, so its
+first body heading should be a level 2:
+
+```markdown
+---
+title: Getting Started
+---
+
+## Installation
+```
+
+With `front-matter-title = false` the front matter is ignored and that document may
+open at any level.
+
+### `front-matter-title-pattern`
+
+Set this when the title lives under a different key. The pattern is matched against
+the front matter lines, and replaces the default `title:` lookup:
+
+```toml
+[MD001]
+front-matter-title-pattern = "^header:"
+```
+
+```markdown
+---
+header: Getting Started
+---
+
+### Installation
+```
+
+That jumps from the implicit level 1 to a level 3 and is flagged. An empty pattern
+means "no pattern": the default `title:` lookup applies.
 
 ## Automatic fixes
 

src/config/registry.rs

@@ -39,8 +39,8 @@ impl RuleRegistry {
         let mut rule_aliases = std::collections::BTreeMap::new();
 
         for rule in rules {
-            let norm_name = if let Some((name, toml::Value::Table(mut table))) = rule.default_config_section() {
-                let norm_name = normalize_key(&name); // Normalize the name from default_config_section
+            let norm_name = if let Some((name, toml::Value::Table(mut table))) = rule.config_schema() {
+                let norm_name = normalize_key(&name); // Normalize the name from config_schema
                 // Overwrite polymorphic keys with the sentinel so the validator skips
                 // type checking for fields whose deserializer accepts multiple TOML
                 // types. The clean default is preserved for `rumdl config --defaults`
@@ -115,24 +115,26 @@ impl RuleRegistry {
         })
     }
 
-    /// Get the expected value type for a rule's configuration key, trying variants.
-    /// Returns `None` for sentinel values (nullable Option fields, polymorphic fields
-    /// that accept multiple TOML types), which signals the caller to skip type checking
-    /// for that key while still recognizing the key as valid.
-    pub fn expected_value_for(&self, rule: &str, key: &str) -> Option<&toml::Value> {
+    /// Resolve a key as the user wrote it to the schema key it names, trying the rule's
+    /// aliases and the separator/case variants.
+    ///
+    /// Returns `None` when the rule does not accept the key at all. A key that resolves
+    /// may still carry a sentinel value, so this answers "is this key known?" where
+    /// [`RuleRegistry::expected_value_for`] answers "what type must it be?".
+    pub fn canonical_config_key(&self, rule: &str, key: &str) -> Option<&str> {
         let schema = self.rule_schemas.get(rule)?;
 
         // Check if this key is an alias
         if let Some(aliases) = self.rule_aliases.get(rule)
             && let Some(canonical_key) = aliases.get(key)
-            && let Some(value) = schema.get(canonical_key)
+            && let Some((schema_key, _)) = schema.get_key_value(canonical_key)
         {
-            return filter_type_check_sentinels(value);
+            return Some(schema_key);
         }
 
         // Try the original key
-        if let Some(value) = schema.get(key) {
-            return filter_type_check_sentinels(value);
+        if let Some((schema_key, _)) = schema.get_key_value(key) {
+            return Some(schema_key);
         }
 
         // Try key variants
@@ -143,14 +145,25 @@ impl RuleRegistry {
         ];
 
         for variant in &key_variants {
-            if let Some(value) = schema.get(variant) {
-                return filter_type_check_sentinels(value);
+            if let Some((schema_key, _)) = schema.get_key_value(variant) {
+                return Some(schema_key);
             }
         }
 
         None
     }
 
+    /// Get the expected value type for a rule's configuration key, trying variants.
+    /// Returns `None` both for an unknown key and for sentinel values (nullable Option
+    /// fields, polymorphic fields that accept multiple TOML types), which signals the
+    /// caller to skip type checking while still recognizing the key as valid. Use
+    /// [`RuleRegistry::canonical_config_key`] to tell those two cases apart.
+    pub fn expected_value_for(&self, rule: &str, key: &str) -> Option<&toml::Value> {
+        let schema = self.rule_schemas.get(rule)?;
+        let canonical = self.canonical_config_key(rule, key)?;
+        filter_type_check_sentinels(schema.get(canonical)?)
+    }
+
     /// Resolve any rule name (canonical or alias) to its canonical form
     /// Returns None if the rule name is not recognized
     ///

src/rule.rs

@@ -237,10 +237,30 @@ pub trait Rule: DynClone + Send + Sync {
     /// 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 config key aliases for this rule
     /// This allows rules to accept alternative config key names for backwards compatibility
     fn config_aliases(&self) -> Option<std::collections::HashMap<String, String>> {
@@ -252,9 +272,8 @@ pub trait Rule: DynClone + Send + Sync {
     /// 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. Keep `default_config_section()` returning clean defaults
-    /// — the sentinel is a schema concern and must not leak into user-facing output
-    /// like `rumdl config --defaults`.
+    /// 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] {
         &[]
     }

src/rule_config_serde.rs

@@ -108,7 +108,7 @@ pub fn is_polymorphic_sentinel(value: &toml::Value) -> bool {
 /// Construct a polymorphic sentinel TOML value. Used by the `RuleRegistry` to overwrite
 /// schema entries for keys returned by `Rule::polymorphic_config_keys()`, so the validator
 /// skips the type check rather than flagging the alternative form as invalid. Rules must
-/// not call this from `default_config_section()` — the sentinel is a schema-only concern
+/// not call this from `default_config_section()`: a sentinel belongs to `config_schema()`
 /// and would leak into user-facing output (e.g. `rumdl config --defaults`).
 pub fn polymorphic_sentinel_value() -> toml::Value {
     toml::Value::String(POLYMORPHIC_SENTINEL.to_string())
@@ -136,12 +136,13 @@ pub fn config_schema_table<T: RuleConfig>(config: &T) -> Option<toml::map::Map<S
     Some(table)
 }
 
-/// Default config section for a rule backed by a serde `RuleConfig` struct.
+/// User-facing default config section for a rule backed by a serde `RuleConfig` struct.
 ///
 /// Serializes `T::default()` through the JSON→TOML path, which drops nullable
-/// (`None`) fields. Returns `None` when no fields remain. Rules whose
-/// `Option`-typed keys must stay visible to config validation use
-/// [`nullable_config_section_for`] instead.
+/// (`None`) fields: an unset `Option` has no default a user could write down, and
+/// inventing one (an empty string, a zero) would read as a real setting. Returns
+/// `None` when no fields remain. Config validation reads [`config_schema_for`], which
+/// keeps those keys.
 pub fn default_config_section_for<T: RuleConfig>() -> Option<(String, toml::Value)> {
     let json_value = serde_json::to_value(T::default()).ok()?;
     let toml_value = json_to_toml_value(&json_value)?;
@@ -151,44 +152,55 @@ pub fn default_config_section_for<T: RuleConfig>() -> Option<(String, toml::Valu
     }
 }
 
-/// Default config section that keeps nullable (`None`) fields visible as
-/// schema sentinels, so key validation recognizes `Option`-typed settings.
-/// Returns `None` when no fields remain, like [`default_config_section_for`].
-pub fn nullable_config_section_for<T: RuleConfig>() -> Option<(String, toml::Value)> {
+/// Validation schema for a rule backed by a serde `RuleConfig` struct: every field the
+/// struct will deserialize, with nullable (`None`) fields kept as sentinels so key
+/// validation recognizes `Option`-typed settings. Returns `None` when the struct has no
+/// serialized fields, like [`default_config_section_for`].
+pub fn config_schema_for<T: RuleConfig>() -> Option<(String, toml::Value)> {
     let table = config_schema_table(&T::default())?;
     if table.is_empty() {
         return None;
     }
     Some((T::RULE_NAME.to_string(), toml::Value::Table(table)))
 }
 
-/// Implements `default_config_section` and `from_config` for a rule backed by
-/// a serde `RuleConfig` struct. Use inside the rule's `impl Rule` block; the
-/// rule must provide a `from_config_struct(config)` constructor.
+/// Implements `config_schema` for a rule backed by a serde `RuleConfig` struct, so the
+/// set of keys config validation accepts is derived from the same struct `from_config`
+/// deserializes and cannot drift from it. Use inside the rule's `impl Rule` block.
 ///
-/// The default arm drops nullable (`None`) fields from the config section;
-/// the `nullable` arm keeps them visible as schema sentinels so config
-/// validation recognizes `Option`-typed keys.
+/// Rules that also want the derived user-facing defaults use
+/// [`impl_rule_config_sections`]; this macro alone is for a rule that presents its
+/// defaults differently (ordering, commentary) but still deserializes through serde.
 #[macro_export]
-macro_rules! impl_rule_config_methods {
+macro_rules! impl_rule_config_schema {
+    ($config_ty:ty) => {
+        fn config_schema(&self) -> Option<(String, toml::Value)> {
+            $crate::rule_config_serde::config_schema_for::<$config_ty>()
+        }
+    };
+}
+
+/// Implements `default_config_section` and `config_schema` for a rule backed by a serde
+/// `RuleConfig` struct. Use inside the rule's `impl Rule` block. Rules that also want
+/// the derived `from_config` use [`impl_rule_config_methods`].
+#[macro_export]
+macro_rules! impl_rule_config_sections {
     ($config_ty:ty) => {
         fn default_config_section(&self) -> Option<(String, toml::Value)> {
             $crate::rule_config_serde::default_config_section_for::<$config_ty>()
         }
 
-        fn from_config(config: &$crate::config::Config) -> Box<dyn $crate::rule::Rule>
-        where
-            Self: Sized,
-        {
-            Box::new(Self::from_config_struct(
-                $crate::rule_config_serde::load_rule_config::<$config_ty>(config),
-            ))
-        }
+        $crate::impl_rule_config_schema!($config_ty);
     };
-    ($config_ty:ty, nullable) => {
-        fn default_config_section(&self) -> Option<(String, toml::Value)> {
-            $crate::rule_config_serde::nullable_config_section_for::<$config_ty>()
-        }
+}
+
+/// Implements `default_config_section`, `config_schema` and `from_config` for a rule
+/// backed by a serde `RuleConfig` struct. Use inside the rule's `impl Rule` block; the
+/// rule must provide a `from_config_struct(config)` constructor.
+#[macro_export]
+macro_rules! impl_rule_config_methods {
+    ($config_ty:ty) => {
+        $crate::impl_rule_config_sections!($config_ty);
 
         fn from_config(config: &$crate::config::Config) -> Box<dyn $crate::rule::Rule>
         where

src/rules/md001_heading_increment.rs

@@ -1,9 +1,43 @@
 use crate::HeadingStyle;
 use crate::rule::{Fix, LintError, LintResult, LintWarning, Rule, RuleCategory, Severity};
+use crate::rule_config_serde::RuleConfig;
 use crate::rules::front_matter_utils::FrontMatterUtils;
 use crate::rules::heading_utils::HeadingUtils;
 use crate::utils::range_utils::calculate_heading_range;
 use regex::Regex;
+use serde::{Deserialize, Serialize};
+
+/// Configuration for MD001 (Heading increment)
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "kebab-case")]
+pub(super) struct MD001Config {
+    /// Whether a title field in front matter counts as an implicit level-1 heading
+    #[serde(default = "default_front_matter_title", alias = "front_matter_title")]
+    pub front_matter_title: bool,
+
+    /// Regex matching the front matter line that holds the title. When set, it replaces
+    /// the default `title:` lookup, so a document keying its title differently still
+    /// gets the implicit level-1 heading.
+    #[serde(default, alias = "front_matter_title_pattern")]
+    pub front_matter_title_pattern: Option<String>,
+}
+
+fn default_front_matter_title() -> bool {
+    true
+}
+
+impl Default for MD001Config {
+    fn default() -> Self {
+        Self {
+            front_matter_title: default_front_matter_title(),
+            front_matter_title_pattern: None,
+        }
+    }
+}
+
+impl RuleConfig for MD001Config {
+    const RULE_NAME: &'static str = "MD001";
+}
 
 /// Rule MD001: Heading levels should only increment by one level at a time
 ///
@@ -128,6 +162,16 @@ impl MD001HeadingIncrement {
         }
     }
 
+    /// An empty pattern is read as "no pattern": compiled, it would match every line
+    /// and turn any front matter at all into an implicit level-1 heading.
+    fn from_config_struct(config: MD001Config, values_withheld: bool) -> Self {
+        Self::with_pattern_from(
+            config.front_matter_title,
+            config.front_matter_title_pattern.filter(|p| !p.is_empty()),
+            values_withheld,
+        )
+    }
+
     /// Check if the document has a front matter title field
     fn has_front_matter_title(&self, content: &str) -> bool {
         if !self.front_matter_title {
@@ -291,44 +335,14 @@ impl Rule for MD001HeadingIncrement {
     where
         Self: Sized,
     {
-        // Get MD001 config section
-        let (front_matter_title, front_matter_title_pattern) = if let Some(rule_config) = config.rules.get("MD001") {
-            let fmt = rule_config
-                .values
-                .get("front-matter-title")
-                .or_else(|| rule_config.values.get("front_matter_title"))
-                .and_then(toml::Value::as_bool)
-                .unwrap_or(true);
-
-            let pattern = rule_config
-                .values
-                .get("front-matter-title-pattern")
-                .or_else(|| rule_config.values.get("front_matter_title_pattern"))
-                .and_then(|v| v.as_str())
-                .filter(|s: &&str| !s.is_empty())
-                .map(String::from);
-
-            (fmt, pattern)
-        } else {
-            (true, None)
-        };
-
-        Box::new(MD001HeadingIncrement::with_pattern_from(
-            front_matter_title,
-            front_matter_title_pattern,
+        let rule_config = crate::rule_config_serde::load_rule_config::<MD001Config>(config);
+        Box::new(Self::from_config_struct(
+            rule_config,
             config.withheld_rule_values.contains("MD001"),
         ))
     }
 
-    fn default_config_section(&self) -> Option<(String, toml::Value)> {
-        Some((
-            "MD001".to_string(),
-            toml::toml! {
-                front-matter-title = true
-            }
-            .into(),
-        ))
-    }
+    crate::impl_rule_config_sections!(MD001Config);
 }
 
 #[cfg(test)]