chore: merge site and docs fixes, third pass

scripts/check_freshness.py

@@ -80,6 +80,9 @@ TOSEC_DOWNLOADS = "https://www.tosecdev.org/downloads"
 MAME_REPO = "https://github.com/mamedev/mame"
 FBNEO_REPO = "https://github.com/libretro/FBNeo"
 PYPI_URL = "https://pypi.org/pypi/{name}/json"
+NPM_URL = "https://registry.npmjs.org/{name}/latest"
+# The site's npm dependencies, pinned to exact versions and built by Deploy Site.
+SITE_PACKAGE = REPO_ROOT / "website" / "package.json"
 INSTALLERS = ("install.sh", "install.ps1")
 
 SHOWN_ITEMS = 4  # items named in a diff summary before ", ..."
@@ -1356,6 +1359,53 @@ def pypi_latest(name: str) -> str | None:
     return str(info.get("version") or "") or None
 
 
+def parse_npm_pins(text: str) -> dict[str, str]:
+    """Package -> the version a package.json names, dependencies of both kinds."""
+    data = json.loads(text)
+    pins: dict[str, str] = {}
+    for key in ("dependencies", "devDependencies"):
+        pins.update({str(k): str(v) for k, v in (data.get(key) or {}).items()})
+    return pins
+
+
+def npm_latest(name: str) -> str | None:
+    payload = upstream._http_json(NPM_URL.format(name=name))  # noqa: SLF001
+    if not isinstance(payload, dict):
+        return None
+    return str(payload.get("version") or "") or None
+
+
+def _npm_findings() -> list[Finding]:
+    """One row per site dependency: an exact pin is stale once npm's latest
+    release is newer, since nothing else asks npm."""
+    findings = []
+    for name, pinned in sorted(parse_npm_pins(SITE_PACKAGE.read_text(encoding="utf-8")).items()):
+        subject = f"npm:{name}"
+        if not re.fullmatch(r"\d+(\.\d+)*", pinned):
+            findings.append(Finding("ci", subject, UNKNOWN, local=pinned, detail="a range, not an exact pin"))
+            continue
+        try:
+            latest = npm_latest(name)
+        except upstream.UpstreamError as exc:
+            findings.append(Finding("ci", subject, UNKNOWN, local=pinned, detail=str(exc)))
+            continue
+        if latest is None:
+            findings.append(Finding("ci", subject, UNKNOWN, local=pinned, detail="not on npm"))
+            continue
+        newer = _version_tuple(latest) > _version_tuple(pinned)
+        findings.append(
+            Finding(
+                "ci",
+                subject,
+                STALE if newer else OK,
+                local=pinned,
+                remote=latest,
+                detail="a newer release is out" if newer else "",
+            )
+        )
+    return findings
+
+
 def check_ci(cache_dir: str, offline: bool) -> list[Finding]:
     findings = [_check_installer_pins()]
     workflows = sorted((REPO_ROOT / ".github" / "workflows").glob("*.yml"))
@@ -1367,8 +1417,9 @@ def check_ci(cache_dir: str, offline: bool) -> list[Finding]:
             pins.setdefault(name, spec)
         actions.update(parse_action_pins(text))
     if offline:
-        findings.append(Finding("ci", "workflow pins", SKIPPED, detail="offline"))
+        findings.append(Finding("ci", "workflow and site pins", SKIPPED, detail="offline"))
         return findings
+    findings.extend(_npm_findings())
     for name, spec in sorted(pins.items()):
         try:
             latest = pypi_latest(name)