From 642896346f4d1878b7389c164a2d806ce7cf1f02 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Mon, 19 Oct 2026 04:18:55 +0200
Subject: [PATCH] docs: say what verify --strict fails on

---
 scripts/verify.py               | 11 ++++++++---
 tests/test_audit_regressions.py | 14 ++++++++++++++
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/scripts/verify.py b/scripts/verify.py
index 7f47241e..19580291 100644
--- a/scripts/verify.py
+++ b/scripts/verify.py
@@ -112,7 +112,7 @@ DEFAULT_EMULATORS_DIR = "emulators"
 
 class Status:
     OK = "ok"
-    UNTESTED = "untested"  # file present, hash not confirmed
+    UNTESTED = "untested"  # file present, hash not confirmed: a warning, never --strict
     MISSING = "missing"
 
 
@@ -2226,7 +2226,8 @@ def _main(held: contextlib.ExitStack) -> None:
         "--strict",
         action="store_true",
         help="Exit 1 on a required file missing: where the frontend checks "
-        "hashes for a platform, without HLE for --emulator and --system",
+        "hashes for a platform, without HLE for --emulator and --system. A file "
+        "present with an unconfirmed hash is a warning, not a failure",
     )
     args = parser.parse_args()
     if args.platform:
@@ -2374,7 +2375,11 @@ def _json_details(details: list[dict], verbose: bool) -> list[dict]:
 
 def _exit_if_strict(strict: bool, results: list[dict]) -> None:
     """Exit 1 under --strict when a platform result counts a critical file:
-    a required file missing or rejected where the frontend reads hashes."""
+    a required file missing where the frontend reads hashes.
+
+    A file present whose hash the frontend does not confirm is UNTESTED, a
+    warning (Batocera's BiosStatus calls it so): reported, not failed.
+    """
     critical = sum(r["severity_counts"].get(Severity.CRITICAL, 0) for r in results)
     if strict and critical:
         print(f"ERROR: {critical} required file(s) missing where the frontend "
diff --git a/tests/test_audit_regressions.py b/tests/test_audit_regressions.py
index 429d0de0..eab09149 100644
--- a/tests/test_audit_regressions.py
+++ b/tests/test_audit_regressions.py
@@ -5118,5 +5118,19 @@ class ThePipelineSummaryTimesEachStep(unittest.TestCase):
                                          "verify": True})
 
 
+class StrictFailsOnMissingOnly(unittest.TestCase):
+    """The docstring promised exit 1 on a required file missing or rejected;
+    a rejected file is UNTESTED, a warning, and --strict never saw it."""
+
+    def test_the_contract(self):
+        from scripts import verify as verify_mod
+        from scripts.verify import Severity
+
+        verify_mod._exit_if_strict(True, [{"severity_counts": {Severity.WARNING: 2}}])
+        with self.assertRaises(SystemExit), contextlib.redirect_stderr(io.StringIO()):
+            verify_mod._exit_if_strict(True, [{"severity_counts": {Severity.CRITICAL: 1}}])
+        self.assertNotIn("or rejected", verify_mod._exit_if_strict.__doc__)
+
+
 if __name__ == "__main__":
     unittest.main()