feat: link the version to the file or tag

The Version cell printed the file a version is read from, or its tag, as bare text beside a pinned Revision link. The file now links at the pin where the recorded tree holds it, and the tag links to its tree. cited_paths records the version files so the record can confirm them.

scripts/generate_site.py

@@ -8469,8 +8469,9 @@ def emulator_romset(profile: dict) -> str:
     return ""
 
 
-def _version_said(value: object, basis: dict) -> str:
-    """One build's version and where the profile reads it."""
+def _version_said(value: object, basis: dict, profile: dict, mode: str = "") -> str:
+    """One build's version and where the profile reads it, linked to the
+    file or the tag where the source allows."""
     kind = basis.get("kind")
     if kind == "none":
         return "none stated in the source"
@@ -8479,13 +8480,18 @@ def _version_said(value: object, basis: dict) -> str:
             return f"unknown: {_UNVERIFIED.get(str(basis.get('why')), 'unread')}"
         return "none published"
     value = str(value)
+    url = version_basis_url(profile, basis, mode) if kind in ("file", "tag") else ""
+
+    def shown(text: object) -> str:
+        return f"[{_code(str(text))}]({url})" if url else _code(str(text))
+
     if kind == "file":
-        return f"{value}, stated in `{basis.get('path')}`"
+        return f"{value}, stated in {shown(basis.get('path'))}"
     if kind == "tag":
         distance = int(basis.get("distance") or 0)
         if not distance:
             return f"{value}, the tag at this revision"
-        return f"{value}, {distance} commit{'s' if distance != 1 else ''} after tag `{basis.get('tag')}`"
+        return f"{value}, {distance} commit{'s' if distance != 1 else ''} after tag {shown(basis.get('tag'))}"
     if kind == "package":
         return f"{value}, read from {basis.get('artifact')}"
     if kind == "unverified":
@@ -8520,10 +8526,10 @@ def version_markdown(profile: dict) -> str:
         values = value if isinstance(value, dict) else {}
         modes = list(dict.fromkeys([*values, *basis]))
         return ", ".join(
-            f"{_version_said(values.get(mode), basis.get(mode) or {})} ({mode})"
+            f"{_version_said(values.get(mode), basis.get(mode) or {}, profile, mode)} ({mode})"
             for mode in modes
         )
-    return _version_said(value, basis)
+    return _version_said(value, basis, profile)
 
 
 ROMSET_FAQ_PAGE = Path(WIKI_SRC_DIR) / "technical-faq.md"
@@ -12463,6 +12469,7 @@ from sitesources import (  # noqa: E402,F401
     _forge_sources,
     _source_permalink,
     _source_ref_markdown,
+    version_basis_url,
 )
 from siterender import (  # noqa: E402,F401
     _by_mode,

scripts/sitesources.py

@@ -240,8 +240,15 @@ def _walk(value: object) -> Iterator[tuple[str, object]]:
 
 def cited_paths(profile: dict) -> set[str]:
     """Every path a page of the profile could link: the parts of each
-    source_ref and the file:line citations of its prose."""
-    paths: set[str] = set()
+    source_ref, the file:line citations of its prose and the file its
+    version is read from."""
+    basis = profile.get("version_basis")
+    bases = ([basis] if isinstance(basis, dict) and "kind" in basis
+             else list(basis.values()) if isinstance(basis, dict) else [])
+    paths: set[str] = {
+        str(b["path"]) for b in bases
+        if isinstance(b, dict) and b.get("kind") == "file" and b.get("path")
+    }
     for key, value in _walk(profile):
         if key == "source_ref" and isinstance(value, (str, dict)):
             for _label, refs in source_ref_values(value):
@@ -355,6 +362,30 @@ def _commit_url(repo: upstream.Repo, pin: str) -> str:
     return f"{base}/commit/{pin}"
 
 
+def version_basis_url(profile: dict, basis: dict, mode: str = "") -> str:
+    """Where a reader checks a version: the file stating it at the pin, or
+    the tag it counts from. "" when neither can be linked.
+
+    The Version cell printed `libretro/handy.h` as bare text beside a
+    pinned Revision link, so the #define it reads was one search away.
+    """
+    field = "upstream" if basis.get("repo") == "upstream" else "source"
+    declared = next(iter(_repo_pins(profile, field, mode)), None)
+    repo = _browse_repo(declared[0]) if declared else None
+    if repo is None:
+        return ""
+    kind, path, tag = basis.get("kind"), str(basis.get("path") or ""), str(basis.get("tag") or "")
+    if kind == "file" and path:
+        pin = next((p for r, p in _forge_sources(profile, mode)
+                    if (r.host, r.slug) == (repo.host, repo.slug)), "")
+        return _source_permalink(repo, pin, path, None, None) if pin and tree_holds(
+            repo, pin, path) else ""
+    if kind == "tag" and tag and repo.family in ("github", "gitlab"):
+        tree = "/-/tree/" if repo.family == "gitlab" else "/tree/"
+        return f"https://{repo.host}/{repo.owner}/{repo.name}{tree}{urllib.parse.quote(tag)}"
+    return ""
+
+
 def revision_markdown(profile: dict) -> str:
     """Each repository the profile reads, linked at the commit it was read at.
 

tests/test_site_emulator_page.py

@@ -68,6 +68,27 @@ class WhoShipsTheBuildAndWhy(unittest.TestCase):
                       "(https://example.org/news) (version 13.0 announced there, "
                       "found only as rebuilt copies) |", page)
 
+    def test_the_version_links_its_proof(self):
+        """`0.97, stated in libretro/handy.h` was bare text beside a pinned
+        Revision link: the #define it reads was one search away."""
+        import generate_site as gs
+        import sitesources
+        import yaml
+
+        handy = yaml.safe_load((REPO_ROOT / "emulators" / "handy.yml").read_text(encoding="utf-8"))
+        path = handy["version_basis"]["path"]
+        self.assertIn(path, sitesources.cited_paths(handy))
+        self.assertIn(f"stated in [`{path}`](https://github.com/libretro/libretro-handy/blob/"
+                      f"{handy['source_commit']}/{path})", gs.version_markdown(handy))
+        tagged = {"source": "https://github.com/owner/emu", "source_commit": "a" * 40,
+                  "core_version": "1.2-3-gaaaaaaa",
+                  "version_basis": {"kind": "tag", "tag": "1.2", "distance": 3}}
+        self.assertEqual(gs.version_markdown(tagged), "1.2-3-gaaaaaaa, 3 commits after tag "
+                         "[`1.2`](https://github.com/owner/emu/tree/1.2)")
+        # A file no recorded tree confirms stays plain: no link beats a 404.
+        unread = {**tagged, "version_basis": {"kind": "file", "path": "src/none.h"}}
+        self.assertEqual(gs.version_markdown(unread), "1.2-3-gaaaaaaa, stated in `src/none.h`")
+
     def test_the_upstream_pin_says_why_it_is_held(self):
         """mupen64plus showed its core revision and not that AmberELEC
         builds that one: read as a profile behind HEAD."""