Tidy up the specification annotator a bit.

Author: Julian

.github/workflows/show_specification_annotations.yml

@@ -18,6 +18,4 @@ jobs:
           python-version: '3.x'
 
       - name: Run Python script
-        run: |
-          pip install uritemplate
-          python bin/annotation_workflow.py
+        run: pip install uritemplate && bin/annotate-specification-links

bin/annotate-specification-links

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Annotate pull requests to the GitHub repository with links to specifications.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+import json
+import re
+import sys
+
+from uritemplate import URITemplate
+
+
+BIN_DIR = Path(__file__).parent
+TESTS = BIN_DIR.parent / "tests"
+URLS = json.loads(BIN_DIR.joinpath("specification_urls.json").read_text())
+
+
+def urls(version: str) -> dict[str, URITemplate]:
+    """
+    Retrieve the version-specific URLs for specifications.
+    """
+    for_version = {**URLS["json-schema"][version], **URLS["external"]}
+    return {k: URITemplate(v) for k, v in for_version.items()}
+
+
+def annotation(
+    path: Path,
+    message: str,
+    line: int = 1,
+    level: str = "notice",
+    **kwargs: Any,
+) -> str:
+    """
+    Format a GitHub annotation.
+
+    See https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+    for full syntax.
+    """
+
+    if kwargs:
+        additional = "," + ",".join(f"{k}={v}" for k, v in kwargs.items())
+    else:
+        additional = ""
+
+    relative = path.relative_to(TESTS.parent)
+    return f"::{level} file={relative},line={line}{additional}::{message}\n"
+
+
+def line_number_of(path: Path, case: dict[str, Any]) -> int:
+    """
+    Crudely find the line number of a test case.
+    """
+    with path.open() as file:
+        description = case["description"]
+        return next(
+            (i for i, line in enumerate(file, 1) if description in line),
+            1,
+        )
+
+
+def main():
+    # Clear annotations which may have been emitted by a previous run.
+    sys.stdout.write("::remove-matcher owner=me::\n")
+
+    for version in TESTS.iterdir():
+        if version.name in {"draft-next", "latest"}:
+            continue
+
+        version_urls = urls(version.name)
+
+        for path in version.rglob("*.json"):
+            try:
+                contents = json.loads(path.read_text())
+            except json.JSONDecodeError as error:
+                error = annotation(
+                    level="error",
+                    path=path,
+                    line=error.lineno,
+                    col=error.pos + 1,
+                    title=str(error),
+                )
+                sys.stdout.write(error)
+
+            for test_case in contents:
+                specifications = test_case.get("specification")
+                if specifications is not None:
+                    for each in specifications:
+                        (kind, section), = (
+                            (k, v) for k, v in each.items() if k != "quote"
+                        )
+
+                        number = re.search(r"\d+", kind)
+                        spec = "" if number is None else number.group(0)
+
+                        url = version_urls[kind].expand(
+                            spec=spec,
+                            section=section,
+                        )
+                        sys.stdout.write(
+                            annotation(
+                                path=path,
+                                line=line_number_of(path, test_case),
+                                title="Specification Link",
+                                message=f"See [{section}]({url})",
+                            ),
+                        )
+
+
+if __name__ == "__main__":
+    main()