From 8cbd7204807ff29ebfb8d8239311c533193df489 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Thu, 5 Nov 2026 19:32:51 +0100
Subject: [PATCH] docs: say what a SHA1 lookup leaves out

The Data page said a SHA1 lookup was enough because MD5 and CRC32 declarations are filed under the collection file's SHA1 too. That holds only for a file the collection holds: 702 platform MD5s and 18 CRC32s are filed under their own value alone.
---
 scripts/generate_site.py     |  8 +++++---
 tests/test_site_reference.py | 17 +++++++++++++++++
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/scripts/generate_site.py b/scripts/generate_site.py
index f595f438b..eef11d4f8 100644
--- a/scripts/generate_site.py
+++ b/scripts/generate_site.py
@@ -2191,9 +2191,11 @@ def generate_data_page(exports: list[dict], measurements_sqlite: Path | None = N
         "when one is known, the `system_name` the site gives its system. "
         "[Find or check a file](files/index.md) reads it.",
         "",
-        "In a browser, the SHA1 of a file the reader picks finds its records. Web "
-        "Crypto has no MD5, and none is needed: a setup that lists a file by MD5 "
-        "or CRC32 is filed under the SHA1 of the collection file it names too.",
+        "In a browser, the SHA1 of a file the reader picks finds its records when "
+        "the collection holds that file. A list naming a file the collection lacks "
+        "is filed under its MD5 or CRC32 alone, and Web Crypto has no MD5: "
+        "that page computes MD5 and CRC32 in script and looks "
+        "up all four.",
         "",
         "```js",
         "// The records of the file a reader picked, by its SHA1.",
diff --git a/tests/test_site_reference.py b/tests/test_site_reference.py
index e32f4610d..de6080114 100644
--- a/tests/test_site_reference.py
+++ b/tests/test_site_reference.py
@@ -696,6 +696,23 @@ class ManifestsArePublished(unittest.TestCase):
         self.assertLess(page.index("## Stable JSON endpoints"), page.index("The DAT is Logiqx XML"))
 
 
+class TheLookupRecipeSaysWhatASha1Misses(unittest.TestCase):
+    """The page said a SHA1 lookup was enough, "a setup that lists a file
+    by MD5 or CRC32 is filed under the SHA1 of the collection file it names
+    too". A record whose value no collection file answers has no SHA1: 702
+    platform MD5s were out of the recipe's reach."""
+
+    def test_the_page_and_the_records_agree(self):
+        record = {"layer": "platform", "algorithm": "md5", "value": "0" * 32,
+                  "name": "dmg_boot.bin", "owner": "recalbox"}
+        self.assertEqual(generate_site._held_under_every_hash([record], {}, {}), [])
+        self.assertNotIn("sha1", record)
+        page = " ".join(generate_site.generate_data_page([]).split())
+        self.assertNotIn("none is needed", page)
+        self.assertIn("A list naming a file the collection lacks is filed under its MD5 "
+                      "or CRC32 alone", page)
+
+
 class AnIdLeadsToItsData(unittest.TestCase):
     """8.6: a system by its id, a core by the name the buildbot gives it."""