fix: harden py38/39 cli typing and backup collision handling

Author: ImYourBoyRoy

src/reqsync/cli.py

@@ -11,7 +11,7 @@
 import json
 from enum import Enum
 from pathlib import Path
-from typing import Any
+from typing import Any, Optional
 
 import typer
 from click.core import ParameterSource
@@ -157,7 +157,7 @@ def _build_options(ctx: typer.Context, use_config: bool) -> Options:
     return merge_options(options, overrides)
 
 
-def _print_human_summary(payload: JsonResult, options: Options, report_path: Path | None) -> None:
+def _print_human_summary(payload: JsonResult, options: Options, report_path: Optional[Path]) -> None:
     mode = "apply"
     if options.check:
         mode = "check"
@@ -197,11 +197,11 @@ def _resolve_output_mode(output: OutputModeEnum, stdout_json: bool) -> OutputMod
 
 def _emit_result(
     payload: JsonResult,
-    result_diff: str | None,
+    result_diff: Optional[str],
     options: Options,
     output_mode: OutputModeEnum,
 ) -> None:
-    report_path: Path | None = None
+    report_path: Optional[Path] = None
     if options.json_report:
         report_path = write_json_report(payload, str(options.json_report))
 
@@ -264,12 +264,12 @@ def run_command(
         help="Allowlisted pip args passed to upgrade command.",
         rich_help_panel="Execution",
     ),
-    only: str | None = typer.Option(
+    only: Optional[str] = typer.Option(
         None,
         help="Comma-separated package globs to include.",
         rich_help_panel="Filtering",
     ),
-    exclude: str | None = typer.Option(
+    exclude: Optional[str] = typer.Option(
         None,
         help="Comma-separated package globs to exclude.",
         rich_help_panel="Filtering",
@@ -296,7 +296,7 @@ def run_command(
         help="Stdout output mode.",
         rich_help_panel="Output",
     ),
-    json_report: Path | None = typer.Option(
+    json_report: Optional[Path] = typer.Option(
         None,
         help="Write machine-readable JSON report to file.",
         rich_help_panel="Output",
@@ -348,7 +348,7 @@ def run_command(
         help="For duplicate packages, rewrite only final occurrence.",
         rich_help_panel="Safety",
     ),
-    log_file: Path | None = typer.Option(
+    log_file: Optional[Path] = typer.Option(
         None,
         help="Optional log file path.",
         rich_help_panel="Logging",

src/reqsync/io.py

@@ -80,15 +80,29 @@ def _prune_old_backups(path: Path, suffix: str, keep_last: int) -> None:
             logging.warning("Unable to prune old backup: %s", stale)
 
 
+def _build_unique_timestamped_backup_path(path: Path, suffix: str) -> Path:
+    """Return a collision-safe timestamped backup path for one source file."""
+
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S-%f")
+    base_name = f"{path.name}{suffix}.{stamp}"
+    backup = path.with_name(base_name)
+
+    counter = 1
+    while backup.exists():
+        backup = path.with_name(f"{base_name}-{counter:02d}")
+        counter += 1
+
+    return backup
+
+
 def backup_file(path: Path, suffix: str, timestamped: bool, keep_last: int) -> Path:
     """Create a backup copy and return its path."""
 
     if not path.exists():
         raise FileNotFoundError(f"Cannot back up missing file: {path}")
 
     if timestamped:
-        stamp = datetime.now().strftime("%Y%m%d-%H%M%S-%f")
-        backup = path.with_name(f"{path.name}{suffix}.{stamp}")
+        backup = _build_unique_timestamped_backup_path(path=path, suffix=suffix)
     else:
         backup = path.with_name(f"{path.name}{suffix}")
 

tests/test_cli.py

@@ -7,11 +7,13 @@
 
 from __future__ import annotations
 
+import inspect
 import textwrap
 from pathlib import Path
 
 from typer.testing import CliRunner
 
+from reqsync import cli as cli_mod
 from reqsync import core as core_mod
 from reqsync._types import ExitCode
 from reqsync.cli import app
@@ -92,3 +94,20 @@ def test_cli_version_option_prints_version() -> None:
     result = runner.invoke(app, ["--version"])
     assert result.exit_code == 0
     assert result.output.startswith("reqsync ")
+
+
+def test_cli_annotations_avoid_pep604_runtime_union_for_py39_typer_compatibility() -> None:
+    callbacks = [
+        cli_mod.app_callback,
+        cli_mod.run_command,
+        cli_mod.help_command,
+        cli_mod.version_command,
+        cli_mod.mcp_server,
+    ]
+
+    for callback in callbacks:
+        for annotation in callback.__annotations__.values():
+            normalized = annotation if isinstance(annotation, str) else repr(annotation)
+            assert "|" not in normalized, f"PEP 604 union found in {callback.__name__}: {normalized}"
+
+        inspect.signature(callback)

tests/test_io.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 from reqsync import core as core_mod
+from reqsync import io as io_mod
 from reqsync._types import Options
 from reqsync.core import sync
 from reqsync.io import backup_file, read_text_preserve, write_text_preserve
@@ -64,3 +65,28 @@ def test_timestamped_backup_pruning_can_be_disabled(tmp_path) -> None:
 
     backups = sorted(tmp_path.glob("requirements.txt.bak.*"))
     assert len(backups) == 4
+
+
+def test_timestamped_backup_naming_avoids_collisions(tmp_path, monkeypatch) -> None:
+    target = tmp_path / "requirements.txt"
+    target.write_text("requests>=2.0\n", encoding="utf-8")
+
+    class _FixedNow:
+        @staticmethod
+        def strftime(_fmt: str) -> str:
+            return "20260223-000000-000000"
+
+    class _FixedDateTime:
+        @staticmethod
+        def now() -> _FixedNow:
+            return _FixedNow()
+
+    monkeypatch.setattr(io_mod, "datetime", _FixedDateTime)
+
+    for i in range(3):
+        target.write_text(f"requests>={i}.0\n", encoding="utf-8")
+        backup_file(target, suffix=".bak", timestamped=True, keep_last=0)
+
+    backups = sorted(tmp_path.glob("requirements.txt.bak.*"))
+    assert len(backups) == 3
+    assert len({backup.name for backup in backups}) == 3