fix(#507): warn when CLI defaults conflict with TOML

src/mdformat/_cli.py

@@ -303,6 +303,16 @@ def make_arg_parser(
             plugin.add_cli_argument_group(group)
             for action in group._group_actions:
                 action.dest = f"plugin.{plugin_id}.{action.dest}"
+                if action.default not in {None, argparse.SUPPRESS}:
+                    import warnings
+
+                    plugin_file, plugin_line = get_source_file_and_line(plugin)
+                    warnings.warn_explicit(
+                        f"The `default` ({action.default}) for {action.option_strings} from the '{plugin_id}' plugin, will always override any value configured in TOML. The only supported CLI defaults are `None` or `argparse.SUPPRESS`. To resolve, consider refactoring to `.add_argument(..., default=None)` ",  # noqa: E501
+                        UserWarning,
+                        filename=plugin_file,
+                        lineno=plugin_line,
+                    )
     return parser
 
 

tests/test_plugins.py

@@ -272,6 +272,35 @@ def test_cli_options_group(monkeypatch, tmp_path):
     )
 
 
+def test_plugin_argument_warnings(monkeypatch, tmp_path):
+    """Test for warnings of plugin arguments that conflict with TOML."""
+
+    class ExamplePluginWithStoreTrue:
+        @staticmethod
+        def update_mdit(mdit: MarkdownIt):
+            pass
+
+        @staticmethod
+        def add_cli_argument_group(group: argparse._ArgumentGroup) -> None:
+            group.add_argument("--store-true", action="store_true")
+            group.add_argument("--store-false", action="store_false")
+            group.add_argument("--store-zero", default=0)
+            group.add_argument("--store-const", action="store_const", const=True)
+
+    monkeypatch.setitem(PARSER_EXTENSIONS, "table", ExamplePluginWithStoreTrue)
+    file_path = tmp_path / "test_markdown.md"
+    file_path.touch()
+
+    with patch.object(MDRenderer, "render", return_value=""):
+        with pytest.warns(UserWarning) as warnings:
+            assert run([str(file_path)]) == 0
+
+    assert "--store-true" in str(warnings.pop().message)
+    assert "--store-false" in str(warnings.pop().message)
+    assert "--store-zero" in str(warnings.pop().message)
+    assert len(warnings) == 0
+
+
 def test_cli_options_group__no_toml(monkeypatch, tmp_path):
     """Test add_cli_argument_group plugin API with configuration only from
     CLI."""