fix(reporting): append UUID only on collision

Author: rioyu123

docs/usage/results-and-reporting.md

@@ -87,9 +87,9 @@ from rampart.reporting import JsonFileReportSink
 sink = JsonFileReportSink(output_dir=Path(".report"))
 ```
 
-Output: `.report/run_report_2026-04-25T14-30-00-123_a3f18c92654d4b75ad15687d383d951b.json`
+Output: `.report/run_report_2026-04-25T14-30-00-123.json`
 
-The filename contains a UTC timestamp (millisecond precision) and a random UUID. Reports created in the same millisecond receive different filenames. An exact filename collision raises `FileExistsError` instead of overwriting an existing report. Reports written within the same millisecond have no defined filename order relative to each other.
+The filename contains a UTC timestamp with millisecond precision. If another report already has the same timestamp, a random UUID is appended to the new filename. Files are created atomically and existing reports are never overwritten. Reports written within the same millisecond have no defined filename order relative to each other.
 
 ### Custom Sinks
 

rampart/reporting/json_file.py

@@ -46,9 +46,10 @@ def rampart_sinks():
 class JsonFileReportSink:
     """Writes the test run report to a JSON file.
 
-    Each run produces a file named ``run_report_<timestamp>_<uuid>.json``.
-    The UTC timestamp includes milliseconds; the UUID distinguishes runs
-    created in the same millisecond. Existing files are never overwritten.
+    Each run normally produces a file named ``run_report_<timestamp>.json``.
+    The UTC timestamp includes milliseconds. If that filename already exists,
+    a UUID suffix distinguishes the colliding run. Existing files are never
+    overwritten.
 
     Args:
         output_dir (Path): Directory to write report files into.
@@ -66,16 +67,29 @@ async def emit_async(self, *, report: TestRunReport) -> None:
             report (TestRunReport): The aggregated test run results.
 
         Raises:
-            FileExistsError: If the generated filename already exists, or
+            FileExistsError: If the random fallback filename also exists, or
                 ``output_dir`` exists and is not a directory.
         """
         self._output_dir.mkdir(parents=True, exist_ok=True)
 
         timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H-%M-%S-%f")[:-3]
-        filepath = self._output_dir / f"run_report_{timestamp}_{uuid4().hex}.json"
         data = self._serialize_report(report)
         content = json.dumps(data, indent=2, default=str)
-        with filepath.open("x", encoding="utf-8") as report_file:
+
+        filepath = self._output_dir / f"run_report_{timestamp}.json"
+        try:
+            report_file = filepath.open("x", encoding="utf-8")
+        except FileExistsError:
+            filepath = self._output_dir / f"run_report_{timestamp}_{uuid4().hex}.json"
+
+            # Leave the exception handler before opening the fallback so a
+            # second collision reports only the path that actually collided.
+            report_file = None
+
+        if report_file is None:
+            report_file = filepath.open("x", encoding="utf-8")
+
+        with report_file:
             report_file.write(content)
 
     def _serialize_report(self, report: TestRunReport) -> dict[str, Any]:

tests/unit/reporting/test_json_file.py

@@ -388,14 +388,21 @@ async def test_same_timestamp_preserves_every_report_async(
             json.loads(path.read_text(encoding="utf-8"))["metadata"]["run"]
             for path in files
         } == {0, 1, 2}
-        for path in files:
+
+        concise = tmp_path / "run_report_2026-08-27T12-00-00-123.json"
+        assert json.loads(concise.read_text(encoding="utf-8"))["metadata"] == {
+            "run": 0,
+        }
+        colliding_files = [path for path in files if path != concise]
+        assert len(colliding_files) == 2
+        for path in colliding_files:
             assert path.name.startswith("run_report_2026-08-27T12-00-00-123_")
             identifier = path.stem.rsplit("_", 1)[1]
             assert len(identifier) == 32
             assert UUID(hex=identifier).version == 4
 
     async def test_existing_report_is_not_replaced_async(self, tmp_path: Path) -> None:
-        original = tmp_path / "run_report_2026-08-27T12-00-00.json"
+        original = tmp_path / "run_report_2026-08-27T12-00-00-000.json"
         original.write_text("keep me", encoding="utf-8")
         sink = JsonFileReportSink(output_dir=tmp_path)
         fixed = datetime(2026, 8, 27, 12, 0, 0, tzinfo=UTC)
@@ -416,10 +423,12 @@ async def test_uuid_collision_does_not_overwrite_existing_report_async(
         tmp_path: Path,
     ) -> None:
         identifier = UUID("a3f18c92-654d-4b75-ad15-687d383d951b")
-        original = (
+        timestamp_file = tmp_path / "run_report_2026-08-27T12-00-00-000.json"
+        timestamp_file.write_text("keep timestamp", encoding="utf-8")
+        uuid_file = (
             tmp_path / f"run_report_2026-08-27T12-00-00-000_{identifier.hex}.json"
         )
-        original.write_text("keep me", encoding="utf-8")
+        uuid_file.write_text("keep uuid", encoding="utf-8")
         sink = JsonFileReportSink(output_dir=tmp_path)
         fixed = datetime(2026, 8, 27, 12, 0, 0, tzinfo=UTC)
 
@@ -431,8 +440,9 @@ async def test_uuid_collision_does_not_overwrite_existing_report_async(
             with pytest.raises(FileExistsError, match=identifier.hex):
                 await sink.emit_async(report=TestRunReport())
 
-        assert original.read_text(encoding="utf-8") == "keep me"
-        assert list(tmp_path.glob("run_report_*.json")) == [original]
+        assert timestamp_file.read_text(encoding="utf-8") == "keep timestamp"
+        assert uuid_file.read_text(encoding="utf-8") == "keep uuid"
+        assert set(tmp_path.glob("run_report_*.json")) == {timestamp_file, uuid_file}
 
     async def test_serialization_failure_does_not_create_a_file_async(
         self,