From 79c27b3798e91fccdc2e8dd7a0b6555d2db1cb05 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Tue, 27 Oct 2026 10:40:05 +0100
Subject: [PATCH] feat: read saved findings in refresh_stale

--findings FILE takes a check_freshness.py --json report written earlier, kept to the --only areas, so one full check can drive a refresh of a few areas.
---
 scripts/refresh_stale.py    | 23 ++++++++++++++++++++++-
 tests/test_refresh_stale.py | 23 +++++++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/scripts/refresh_stale.py b/scripts/refresh_stale.py
index 6d4f35570..2f26305b9 100755
--- a/scripts/refresh_stale.py
+++ b/scripts/refresh_stale.py
@@ -44,6 +44,7 @@ Usage:
     python scripts/refresh_stale.py --dry-run
     python scripts/refresh_stale.py --only platforms,targets
     python scripts/refresh_stale.py --jobs 6
+    python scripts/refresh_stale.py --findings tmp/freshness.json --only data
 """
 
 from __future__ import annotations
@@ -159,6 +160,17 @@ def _run_check_freshness(areas: tuple[str, ...], extra: list[str]) -> list[dict]
         raise RuntimeError(f"check_freshness.py returned unreadable JSON: {exc}") from exc
 
 
+def load_findings(path: Path, areas: tuple[str, ...]) -> list[dict]:
+    """A saved check_freshness.py --json report, kept to the asked areas."""
+    try:
+        findings = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise RuntimeError(f"cannot read findings from {path}: {exc}") from exc
+    if not isinstance(findings, list):
+        raise RuntimeError(f"{path} is not a check_freshness.py --json report")
+    return [f for f in findings if f.get("area") in areas]
+
+
 def _slug(subject: str) -> str:
     """A safe filename stem for a finding's subject."""
     return re.sub(r"[^A-Za-z0-9_.-]+", "_", subject).strip("_") or "job"
@@ -565,6 +577,12 @@ def main() -> int:
         action="store_true",
         help="machine-readable summary (jobs, surfaced, ignored)",
     )
+    parser.add_argument(
+        "--findings",
+        metavar="FILE",
+        help="read the check_freshness.py --json report from FILE instead of "
+        "running it (rows outside --only are left out)",
+    )
     parser.add_argument(
         "--freshness-arg",
         action="append",
@@ -585,7 +603,10 @@ def main() -> int:
         areas = all_areas
 
     try:
-        findings = _run_check_freshness(areas, args.freshness_arg)
+        if args.findings:
+            findings = load_findings(Path(args.findings), areas)
+        else:
+            findings = _run_check_freshness(areas, args.freshness_arg)
     except RuntimeError as exc:
         print(exc, file=sys.stderr)
         return 2
diff --git a/tests/test_refresh_stale.py b/tests/test_refresh_stale.py
index 446bc3b2a..db5a7dacd 100644
--- a/tests/test_refresh_stale.py
+++ b/tests/test_refresh_stale.py
@@ -206,5 +206,28 @@ class Running(unittest.TestCase):
             self.assertFalse(marker.exists())
 
 
+class SavedFindings(unittest.TestCase):
+    """--findings reads the report a full check_freshness run saved, so the
+    nightly job checks every area once and refreshes only some."""
+
+    def test_rows_outside_the_asked_areas_are_left_out(self):
+        with tempfile.TemporaryDirectory(dir=REPO_ROOT / "tmp" / "tests") as directory:
+            path = Path(directory) / "freshness.json"
+            path.write_text(
+                '[{"area": "data", "subject": "dolphin-sys", "status": "STALE"},'
+                ' {"area": "platforms", "subject": "batocera", "status": "STALE"}]',
+                encoding="utf-8",
+            )
+            findings = rs.load_findings(path, ("data", "catalogs"))
+            self.assertEqual([f["subject"] for f in findings], ["dolphin-sys"])
+
+    def test_a_report_that_is_not_a_list_is_refused(self):
+        with tempfile.TemporaryDirectory(dir=REPO_ROOT / "tmp" / "tests") as directory:
+            path = Path(directory) / "freshness.json"
+            path.write_text('{"area": "data"}', encoding="utf-8")
+            with self.assertRaises(RuntimeError):
+                rs.load_findings(path, ("data",))
+
+
 if __name__ == "__main__":
     unittest.main()