test(cli): cover --deny-config-warnings silent, precedence, and fmt; document the flag

Locks in that the flag still exits 2 under --silent (no stderr noise), that a
config problem takes precedence over Markdown violations (exit 2, not 1) while a
plain violation still exits 1, and that fmt honors the flag. Documents the flag
and its exit-code semantics in the CLI reference.

Refs #726

Author: rvben

docs/usage/cli.md

@@ -20,19 +20,20 @@ rumdl check --fix .              # Lint and auto-fix issues
 
 **Options:**
 
-| Option                 | Description                                          |
-| ---------------------- | ---------------------------------------------------- |
-| `--fix`                | Auto-fix issues (exits 1 if unfixable issues remain) |
-| `--config <PATH>`      | Path to configuration file                           |
-| `--disable <RULES>`    | Disable specific rules (e.g., `MD013,MD033`)         |
-| `--enable <RULES>`     | Enable only specific rules                           |
-| `--exclude <PATTERNS>` | Exclude files matching patterns                      |
-| `--include <PATTERNS>` | Include only files matching patterns                 |
-| `--watch`              | Watch for changes and re-lint                        |
-| `--verbose`            | Show detailed output                                 |
-| `--quiet`              | Print diagnostics, but suppress summaries            |
-| `--silent`             | Suppress diagnostics and summaries                   |
-| `--no-exclude`         | Disable exclude patterns defined in config           |
+| Option                   | Description                                          |
+| ------------------------ | ---------------------------------------------------- |
+| `--fix`                  | Auto-fix issues (exits 1 if unfixable issues remain) |
+| `--config <PATH>`        | Path to configuration file                           |
+| `--disable <RULES>`      | Disable specific rules (e.g., `MD013,MD033`)         |
+| `--enable <RULES>`       | Enable only specific rules                           |
+| `--exclude <PATTERNS>`   | Exclude files matching patterns                      |
+| `--include <PATTERNS>`   | Include only files matching patterns                 |
+| `--watch`                | Watch for changes and re-lint                        |
+| `--verbose`              | Show detailed output                                 |
+| `--quiet`                | Print diagnostics, but suppress summaries            |
+| `--silent`               | Suppress diagnostics and summaries                   |
+| `--no-exclude`           | Disable exclude patterns defined in config           |
+| `--deny-config-warnings` | Treat configuration warnings as errors (exit code 2) |
 
 ### `fmt [PATHS...]`
 
@@ -57,6 +58,7 @@ rumdl fmt --silent -             # Format stdin to stdout without diagnostics
 | `--watch`                 | Re-run formatting when files change                         |
 | `--quiet`                 | Print diagnostics, but suppress summaries                   |
 | `--silent`                | Suppress diagnostics and summaries                          |
+| `--deny-config-warnings`  | Treat configuration warnings as errors (exit code 2)        |
 
 Use `--silent` whenever stdout should contain only formatted Markdown. Plain `rumdl fmt -` may also emit remaining diagnostics.
 
@@ -187,6 +189,15 @@ These options are commonly used with `check` and `fmt`:
     - `rumdl fmt` always exits 0 (formatter mode)
     - `rumdl check --fix` exits 1 if unfixable issues remain
 
+!!! note "Failing on configuration problems"
+    Configuration problems (an unknown rule or option in a config file or a CLI
+    flag, an unknown rule in an inline `rumdl-disable-line` comment, or a
+    shadowed config file) are non-fatal warnings by default and do not affect the
+    exit code. Pass `--deny-config-warnings` to make any of them exit with code
+    `2`, so CI catches a typo'd rule name. This is distinct from `--fail-on`,
+    which governs the severity of Markdown violations (exit `1`); a config
+    problem exits `2` and takes precedence over Markdown violations.
+
 ## Usage Examples
 
 ### Basic Linting

tests/cli/cli_exit_codes_test.rs

@@ -273,3 +273,77 @@ fn stdin_inline_config_warning_non_fatal_by_default() {
         "stdin inline config warning must not affect exit code by default"
     );
 }
+
+/// --silent suppresses the printed notice but the flag must still exit 2.
+#[test]
+fn deny_config_warnings_silent_still_exits_two() {
+    let dir = tempdir().unwrap();
+    std::fs::write(dir.path().join("clean.md"), "# Title\n\nText.\n").unwrap();
+    std::fs::write(dir.path().join(".rumdl.toml"), "[global]\nenable = [\"MD999\"]\n").unwrap();
+
+    let output = rumdl()
+        .args(["check", "--no-cache", "--deny-config-warnings", "--silent", "clean.md"])
+        .current_dir(dir.path())
+        .output()
+        .expect("run rumdl check");
+    assert_eq!(output.status.code(), Some(TOOL_ERROR));
+    assert!(
+        String::from_utf8_lossy(&output.stderr).is_empty(),
+        "--silent must suppress the printed warning even while the flag makes it fatal. stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+}
+
+/// A config warning outranks a real Markdown violation: exit 2, not 1.
+#[test]
+fn deny_config_warnings_take_precedence_over_violations() {
+    let dir = tempdir().unwrap();
+    // MD041: first line is not a top-level heading -> a real violation.
+    std::fs::write(dir.path().join("dirty.md"), "no heading here\n").unwrap();
+    std::fs::write(dir.path().join(".rumdl.toml"), "[global]\nenable = [\"MD999\"]\n").unwrap();
+
+    let status = rumdl()
+        .args(["check", "--no-cache", "--deny-config-warnings", "dirty.md"])
+        .current_dir(dir.path())
+        .status()
+        .expect("run rumdl check");
+    assert_eq!(
+        status.code(),
+        Some(TOOL_ERROR),
+        "a config problem must exit 2 even when Markdown violations (exit 1) are also present"
+    );
+}
+
+/// Sanity check the precedence test's premise: the same violation WITHOUT a
+/// config problem exits 1, not 2.
+#[test]
+fn violations_without_config_problem_exit_one() {
+    let dir = tempdir().unwrap();
+    std::fs::write(dir.path().join("dirty.md"), "no heading here\n").unwrap();
+
+    let status = rumdl()
+        .args(["check", "--no-cache", "--deny-config-warnings", "dirty.md"])
+        .current_dir(dir.path())
+        .status()
+        .expect("run rumdl check");
+    assert_eq!(
+        status.code(),
+        Some(1),
+        "a plain Markdown violation exits 1; the flag only changes config-problem exits"
+    );
+}
+
+/// `fmt` shares config loading and the flag; it also exits 2 on a config problem.
+#[test]
+fn deny_config_warnings_applies_to_fmt() {
+    let dir = tempdir().unwrap();
+    std::fs::write(dir.path().join("clean.md"), "# Title\n\nText.\n").unwrap();
+    std::fs::write(dir.path().join(".rumdl.toml"), "[global]\nenable = [\"MD999\"]\n").unwrap();
+
+    let status = rumdl()
+        .args(["fmt", "--no-cache", "--deny-config-warnings", "clean.md"])
+        .current_dir(dir.path())
+        .status()
+        .expect("run rumdl fmt");
+    assert_eq!(status.code(), Some(TOOL_ERROR));
+}