From 00aac8dc72d2c867c77ba04bed2593056b7e3f32 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Fri, 6 Nov 2026 03:48:37 +0100
Subject: [PATCH] docs: say what catalog.json lists

index.json called the catalog every published file, while the one-item
documents of emulators/, platforms/, systems/ and lookup/ are in none of
its items. The description and the data page now say so.
---
 scripts/generate_site.py     |  7 ++++++-
 tests/test_site_reference.py | 18 ++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/scripts/generate_site.py b/scripts/generate_site.py
index e996cb6b0..5fbadd18f 100644
--- a/scripts/generate_site.py
+++ b/scripts/generate_site.py
@@ -1804,7 +1804,9 @@ def generate_data_exports(
     # entry point is a document of its own, naming where to start.
     entry_points = [
         {"title": "Catalog", "url": "catalog.json",
-         "description": "Every published file with its size, SHA256 and schema."},
+         "description": "Each dataset, manifest, export and download with its size, "
+                        "SHA256 and schema. The one-item documents of emulators/, "
+                        "platforms/, systems/ and lookup/ are not listed."},
         {"title": "System ids", "url": "systems.json",
          "description": "Each system id with its name and the section holding its files."},
         {"title": "Core names", "url": "cores.json",
@@ -2204,6 +2206,9 @@ 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.",
         "",
+        "`catalog.json` lists the datasets, manifests, exports and downloads. It "
+        "does not list these one-item documents, which hold no SHA256 of their own.",
+        "",
         "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: "
diff --git a/tests/test_site_reference.py b/tests/test_site_reference.py
index 5375a7972..408327c99 100644
--- a/tests/test_site_reference.py
+++ b/tests/test_site_reference.py
@@ -649,6 +649,24 @@ class TheContractsValidate(unittest.TestCase):
                     [e.message for e in envelope.iter_errors(json.loads((API / name).read_text()))], [])
 
 
+class TheIndexSaysWhatTheCatalogLists(unittest.TestCase):
+    """index.json called catalog.json every published file, while the 990
+    one-item documents of emulators/, platforms/, systems/ and lookup/ are
+    in none of its 80 items."""
+
+    def test_the_description_matches_the_items(self):
+        index = json.loads(_built(API / "index.json").read_text())
+        catalog = json.loads(_built(API / "catalog.json").read_text())
+        described = next(i["description"] for i in index["items"] if i["url"] == "catalog.json")
+        self.assertNotIn("Every published file", described)
+        listed = {item["url"].split("/", 1)[0] for item in catalog["items"]}
+        for folder in ("emulators", "platforms", "systems", "lookup"):
+            with self.subTest(folder=folder):
+                self.assertIn(f"{folder}/", described)
+                self.assertNotIn(folder, listed)
+                self.assertTrue(any((API / folder).glob("*.json")))
+
+
 class EveryEnvelopeCarriesTheCommit(unittest.TestCase):
     """8.5: emulators/ and systems/ lacked `commit` (716 documents)."""