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

src/mdformat/_cli.py

@@ -303,6 +303,32 @@ 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 type(action) in {
+                    argparse._StoreTrueAction,
+                    argparse._StoreFalseAction,
+                }:
+                    import warnings
+
+                    is_store_true = type(action) is argparse._StoreTrueAction
+                    plugin_name = (
+                        action.container.title
+                        if hasattr(action, "container")
+                        else str(plugin)
+                    )
+                    text = (
+                        f"For {action.option_strings} from {plugin_name},"
+                        " the default will always override a value configured"
+                        " in TOML. To resolve, replace `.add_argument(...,"
+                        f' action="store_{str(is_store_true).lower()}")` with'
+                        f' `(..., action="store_const", const={is_store_true})`'
+                    )
+                    plugin_file, plugin_line = get_source_file_and_line(action)
+                    warnings.warn_explicit(
+                        text,
+                        UserWarning,
+                        filename=plugin_file,
+                        lineno=plugin_line,
+                    )
     return parser
 
 

tests/test_plugins.py

@@ -272,6 +272,33 @@ 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-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 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."""