tools: add diff-config to compare two config files

diff-config CONFIG1 CONFIG2 prints a unified diff between two resolved
configs, ignoring password hashes; TOML by default, --json for JSON
representation. Exits 0 when the configs are identical, 1 otherwise.
Configs are loaded without value/env overrides so both sides are compared
on their own contents.

Signed-off-by: Gaëtan Lehmann <gaetan.lehmann@vates.tech>

Author: glehmann

README.md

@@ -211,6 +211,9 @@ To customize settings for your environment:
 - `tools.py dump-config` / `migrate-data-py` print only the values that differ
   from the base `config.toml`; add `--all` to include the values that are the
   same too.
+- `tools.py diff-config CONFIG1 CONFIG2` — compare two config files and print
+  a unified diff (password hashes are ignored); exit code 0 when identical,
+  1 when they differ.
 
 The `--config` flag is optional. When not specified, the `XCPNG_CONFIG` env var
 is used if set. When neither is set:

lib/config_dump.py

@@ -2,6 +2,9 @@
 
 from __future__ import annotations
 
+import difflib
+import json
+
 import tomli_w
 from pygments import highlight
 from pygments.formatters import TerminalFormatter
@@ -114,3 +117,29 @@ def render_toml(config: ConfigDict, with_schema: bool = True) -> str:
     if with_schema:
         data = {"$schema": "./config-schema.json", **data}
     return tomli_w.dumps(data, multiline_strings=True)
+
+
+def config_diff(
+    config_a: ConfigDict,
+    config_b: ConfigDict,
+    name_a: str = "a",
+    name_b: str = "b",
+    as_json: bool = False,
+) -> str:
+    """Return a unified diff between two configs, ignoring password hashes.
+
+    Empty string when the configs are identical (modulo $6$... password hashes).
+    """
+    norm_a = _strip_password_hashes(config_a)
+    norm_b = _strip_password_hashes(config_b)
+    if as_json:
+        text_a = json.dumps(norm_a, indent=2, ensure_ascii=False, sort_keys=True)
+        text_b = json.dumps(norm_b, indent=2, ensure_ascii=False, sort_keys=True)
+    else:
+        text_a = render_toml(norm_a, with_schema=False)
+        text_b = render_toml(norm_b, with_schema=False)
+    return "".join(difflib.unified_diff(
+        text_a.splitlines(keepends=True),
+        text_b.splitlines(keepends=True),
+        fromfile=name_a, tofile=name_b,
+    ))

lib/tools/cli.py

@@ -65,6 +65,18 @@ def _command_migrate(args: argparse.Namespace) -> int:
                            include_defaults=args.all)
 
 
+def _command_diff_config(args: argparse.Namespace) -> int:
+    from lib.config_dump import config_diff
+
+    name_a = str(args.config1)
+    name_b = str(args.config2)
+    config_a = load_config(override=args.config1, apply_value_overrides=False).model_dump(by_alias=True)
+    config_b = load_config(override=args.config2, apply_value_overrides=False).model_dump(by_alias=True)
+    diff = config_diff(config_a, config_b, name_a, name_b, as_json=args.json)
+    print(diff, end="")
+    return 1 if diff else 0
+
+
 def _command_dump_config(args: argparse.Namespace) -> int:
     import json
 
@@ -296,6 +308,31 @@ def _add_config_value_option(target: argparse.ArgumentParser) -> None:
     )
     subparser_cmd_dump.set_defaults(func=_command_dump_config)
 
+    # subparser - command: diff-config
+    subparser_cmd_diff = subparsers.add_parser(
+        name="diff-config",
+        parents=[common_parser],
+        description="Compare two config files and print their differences",
+        help="Compare two config files and print their differences",
+    )
+    subparser_cmd_diff.add_argument(
+        "config1",
+        metavar="CONFIG1",
+        help="First config file (.toml path or short name)",
+    )
+    subparser_cmd_diff.add_argument(
+        "config2",
+        metavar="CONFIG2",
+        help="Second config file (.toml path or short name)",
+    )
+    subparser_cmd_diff.add_argument(
+        "--json",
+        action="store_true",
+        default=False,
+        help="Compare the JSON representations instead of TOML",
+    )
+    subparser_cmd_diff.set_defaults(func=_command_diff_config)
+
     args = parser.parse_args()
 
     if args.debug: