Merge --json/--xml/--lcov into --format=, keeping them as aliases

All four now share dest='format' in the same mutex group -- --json,
--xml, and --lcov become store_const shortcuts for --format=json etc,
so existing scripts keep working unchanged. Verified empirically that
both argparse's mutex conflict detection and _detect_explicit_args'
CLI-precedence tracking work correctly across differently-shaped
actions sharing a dest, with no changes needed to either mechanism.

The config surface becomes just 'format' (validated against the same
choices) instead of three separate booleans -- the test oracle
confirms this naturally, since all four CLI actions sharing one dest
collapse to a single derived key.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: jaltmayerpizzorno

src/slipcover/__main__.py

@@ -128,10 +128,10 @@ def merge_files(args, base_path):
 
     try:
         with args.out.open("w", encoding='utf-8') as jf:
-            if args.xml:
+            if args.format == 'xml':
                 sc.print_xml(merged, source_paths=[str(base_path)], with_branches=args.branch,
                              xml_package_depth=args.xml_package_depth, outfile=jf)
-            elif args.lcov:
+            elif args.format == 'lcov':
                 sc.print_lcov(merged, with_branches=args.branch,
                              test_name=args.lcov_test_name, comments=args.lcov_comments,
                              outfile=jf)
@@ -199,14 +199,19 @@ def build_parser():
     ap = argparse.ArgumentParser(prog='SlipCover')
     ap.add_argument('--branch', action='store_true', help="measure both branch and line coverage")
     fmt = ap.add_mutually_exclusive_group()
-    fmt.add_argument('--json', action='store_true', help="select JSON output")
+    fmt.add_argument('--format', choices=['text', 'json', 'xml', 'lcov'], default='text',
+                     help="select output format")
+    fmt.add_argument('--json', dest='format', action='store_const', const='json',
+                     help="select JSON output (shortcut for --format=json)")
     ap.add_argument('--pretty-print', action='store_true', help="pretty-print JSON output")
-    fmt.add_argument('--xml', action='store_true', help="select XML output")
+    fmt.add_argument('--xml', dest='format', action='store_const', const='xml',
+                     help="select XML output (shortcut for --format=xml)")
     ap.add_argument('--xml-package-depth', type=int, default=99, help=(
         "Controls which directories are identified as packages in the report. "
         "Directories deeper than this depth are not reported as packages. "
         "The default is that all directories are reported as packages."))
-    fmt.add_argument('--lcov', action='store_true', help="select LCOV output")
+    fmt.add_argument('--lcov', dest='format', action='store_const', const='lcov',
+                     help="select LCOV output (shortcut for --format=lcov)")
     ap.add_argument('--lcov-test-name', type=str, help="test name for LCOV TN: entries")
     ap.add_argument('--lcov-comment', action='append', dest='lcov_comments', help="add comment lines at the beginning of LCOV output (can be used multiple times)")
     ap.add_argument('--out', type=Path, help="specify output file name")
@@ -323,12 +328,12 @@ def sci_atexit():
         global output_tmpfile
 
         def printit(coverage, outfile):
-            if args.json:
+            if args.format == 'json':
                 print(json.dumps(coverage, indent=(4 if args.pretty_print else None)), file=outfile)
-            elif args.xml:
+            elif args.format == 'xml':
                 sc.print_xml(coverage, source_paths=[str(base_path)], with_branches=args.branch,
                              xml_package_depth=args.xml_package_depth, outfile=outfile)
-            elif args.lcov:
+            elif args.format == 'lcov':
                 sc.print_lcov(coverage, with_branches=args.branch,
                              test_name=args.lcov_test_name, comments=args.lcov_comments,
                              outfile=outfile)

src/slipcover/config.py

@@ -112,10 +112,7 @@ def derive_configurable_keys(ap):
 # part of the stable, user-facing config surface.
 _BOOL_KEYS = {
     "branch",
-    "json",
     "pretty-print",
-    "xml",
-    "lcov",
     "immediate",
     "skip-covered",
 }
@@ -127,8 +124,16 @@ def _coerce_comments(value):
     return [str(v) for v in value]
 
 
+def _coerce_format(value):
+    choices = ("text", "json", "xml", "lcov")
+    if value not in choices:
+        raise ValueError(f"must be one of {choices}, got {value!r}")
+    return value
+
+
 # Keys that take a value
 _VALUE_KEYS = {
+    "format": _coerce_format,
     "out": Path,
     "source": str,
     "omit": str,

tests/test_config.py

@@ -1,4 +1,5 @@
 import argparse
+import json
 import subprocess
 import sys
 from pathlib import Path
@@ -163,8 +164,8 @@ def test_config_keys_match_cli_flags():
 
 def _make_args(**kwargs):
     defaults = dict(
-        branch=False, json=False, pretty_print=False, xml=False,
-        xml_package_depth=99, lcov=False, lcov_test_name=None, lcov_comments=None,
+        branch=False, format='text', pretty_print=False,
+        xml_package_depth=99, lcov_test_name=None, lcov_comments=None,
         out=None, source=None, omit=None,
         immediate=False, skip_covered=False, fail_under=0,
         threshold=50, missing_width=80, silent=False, dis=False,
@@ -176,8 +177,8 @@ def _make_args(**kwargs):
 
 def test_apply_config_lcov_keys():
     args = _make_args()
-    apply_config({"lcov": True, "lcov-test-name": "Suite", "lcov-comments": ["a", "b"]}, args)
-    assert args.lcov is True
+    apply_config({"format": "lcov", "lcov-test-name": "Suite", "lcov-comments": ["a", "b"]}, args)
+    assert args.format == "lcov"
     assert args.lcov_test_name == "Suite"
     assert args.lcov_comments == ["a", "b"]
 
@@ -188,6 +189,22 @@ def test_apply_config_lcov_comments_scalar_becomes_list():
     assert args.lcov_comments == ["just one"]
 
 
+def test_apply_config_format_bad_value_raises():
+    args = _make_args()
+    with pytest.raises(ValueError, match="must be one of"):
+        apply_config({"format": "bogus"}, args)
+
+
+@pytest.mark.parametrize("key", ["json", "xml", "lcov"])
+def test_apply_config_old_boolean_format_keys_now_unknown(key):
+    """json/xml/lcov as individual boolean config keys are no longer
+    recognized -- format = "..." replaces them (see build_parser()).
+    """
+    args = _make_args()
+    with pytest.warns(UserWarning, match="Unknown"):
+        apply_config({key: True}, args)
+
+
 def test_apply_config_sets_values():
     args = _make_args()
     apply_config({"branch": True, "fail-under": 85.5, "source": "src"}, args)
@@ -341,7 +358,7 @@ def test_cli_lcov_config_applied(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     (tmp_path / "pyproject.toml").write_text(
         '[tool.slipcover]\n'
-        'lcov = true\n'
+        'format = "lcov"\n'
         'lcov-test-name = "MySuite"\n'
         'lcov-comments = ["hello", "world"]\n'
     )
@@ -382,3 +399,48 @@ def test_cli_json_alone_still_works(tmp_path, monkeypatch):
     assert p.returncode == 0
     assert 'Traceback' not in p.stderr
 
+
+def test_cli_format_json_equivalent_to_json_flag(tmp_path, monkeypatch):
+    """--format=json is the primary spelling; --json is a shortcut alias
+    for it (dest='format' is shared) -- both must produce identical output.
+    """
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "script.py").write_text("x = 1\n")
+
+    p_flag = subprocess.run([sys.executable, '-m', 'slipcover', '--json', 'script.py'],
+                             capture_output=True, text=True)
+    p_format = subprocess.run([sys.executable, '-m', 'slipcover', '--format=json', 'script.py'],
+                               capture_output=True, text=True)
+
+    assert p_flag.returncode == 0 == p_format.returncode
+
+    flag_out = json.loads(p_flag.stdout)
+    format_out = json.loads(p_format.stdout)
+    del flag_out['meta']['timestamp'], format_out['meta']['timestamp']
+    assert flag_out == format_out
+
+
+def test_cli_format_and_alias_together_is_an_error(tmp_path, monkeypatch):
+    """--format=json and --xml are different actions sharing the same
+    dest -- mixing the new and old spellings must still be rejected.
+    """
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "script.py").write_text("x = 1\n")
+
+    p = subprocess.run([sys.executable, '-m', 'slipcover', '--format=json', '--xml', 'script.py'],
+                        capture_output=True, text=True)
+
+    assert p.returncode != 0
+    assert 'Traceback' not in p.stderr
+
+
+def test_cli_format_bad_choice_is_a_clean_error(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "script.py").write_text("x = 1\n")
+
+    p = subprocess.run([sys.executable, '-m', 'slipcover', '--format=bogus', 'script.py'],
+                        capture_output=True, text=True)
+
+    assert p.returncode != 0
+    assert 'Traceback' not in p.stderr
+