ci: harden contributor checks (#254)

* ci: harden contributor checks

* ci: pin setup-uv action release

* ci: split workflow checks

* docs: clarify required checks

scripts/check_docs.py

@@ -0,0 +1,109 @@
+"""Validate contributor-facing Markdown and use-case documentation."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+SKIP_DIRS = {".git", "node_modules", ".venv", ".uv-cache"}
+USE_CASE_TABLES = {
+    Path("README.md"): "## Use Cases",
+    Path("use-cases/README.md"): "## Use Cases",
+}
+PRIMARY_LINK_RE = re.compile(
+    r"^\[(?:Code|Plugin|Live Demo|Learn more)\]\(([^)]+)\)",
+    flags=re.M,
+)
+
+
+def _markdown_files() -> list[Path]:
+    return sorted(
+        path
+        for path in Path(".").rglob("*.md")
+        if not any(part in SKIP_DIRS for part in path.parts)
+    )
+
+
+def _check_active_relative_links() -> list[str]:
+    missing: list[str] = []
+    root = Path.cwd().resolve()
+    for path in _markdown_files():
+        active = re.sub(r"<!--.*?-->", "", path.read_text(), flags=re.S)
+        for raw in re.findall(r"\[[^\]]*\]\(([^)]+)\)", active):
+            link = raw.split("#", 1)[0]
+            if not link or link.startswith(("http://", "https://", "mailto:")):
+                continue
+
+            target = (path.parent / link).resolve()
+            try:
+                target.relative_to(root)
+            except ValueError:
+                missing.append(f"{path}: {raw} -> outside repository")
+                continue
+
+            if not target.exists():
+                missing.append(f"{path}: {raw} -> missing")
+    return missing
+
+
+def _check_use_case_banner_links() -> tuple[list[str], list[str]]:
+    failures: list[str] = []
+    warnings: list[str] = []
+
+    for path, heading in USE_CASE_TABLES.items():
+        text = path.read_text()
+        start = text.find(heading)
+        if start == -1:
+            failures.append(f"{path}: missing {heading}")
+            continue
+
+        table_start = text.find("<table>", start)
+        table_end = text.find("</table>", table_start)
+        if table_start == -1 or table_end == -1:
+            failures.append(f"{path}: missing use-case table")
+            continue
+
+        table = text[table_start:table_end]
+        cells = re.findall(r"<td[^>]*>(.*?)</td>", table, flags=re.S)
+        for index, cell in enumerate(cells, start=1):
+            title_match = re.search(r"####\s+(.+)", cell)
+            title = title_match.group(1).strip() if title_match else f"use case {index}"
+            banner_match = re.search(r"\[!\[[^\]]*\]\([^)]+\)\]\(([^)]+)\)", cell)
+            primary_match = PRIMARY_LINK_RE.search(cell)
+
+            if not banner_match and primary_match:
+                warnings.append(f"{path}: {title}: primary link has no linked banner")
+            elif banner_match and not primary_match:
+                failures.append(f"{path}: {title}: missing primary link")
+            elif (
+                banner_match
+                and primary_match
+                and banner_match.group(1) != primary_match.group(1)
+            ):
+                failures.append(
+                    f"{path}: {title}: banner link {banner_match.group(1)} "
+                    f"does not match primary link {primary_match.group(1)}"
+                )
+
+    return failures, warnings
+
+
+def main() -> int:
+    failures = _check_active_relative_links()
+    use_case_failures, warnings = _check_use_case_banner_links()
+    failures.extend(use_case_failures)
+
+    if warnings:
+        print("\n".join(f"warning: {warning}" for warning in warnings))
+
+    if failures:
+        print("\n".join(failures))
+        return 1
+
+    print("Documentation checks passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())