diff --git a/.github/actions/validate-nvx/action.yml b/.github/actions/validate-nvx/action.yml index cecfca318..09cc119b0 100644 --- a/.github/actions/validate-nvx/action.yml +++ b/.github/actions/validate-nvx/action.yml @@ -11,7 +11,7 @@ runs: set -euo pipefail python3 -m pip install --requirement scripts/setup/azure/requirements.txt python3 -m compileall -q scripts - python3 -m unittest scripts/test_performance.py scripts/test_nvx_tools.py scripts/test_kconfig.py scripts/test_kernel_config.py scripts/test_guest_binaries.py scripts/test_microvm_tests.py scripts/test_nightly_ci.py scripts/test_development_release.py scripts/test_crate_release.py scripts/test_host_telemetry.py scripts/test_time_abi.py scripts/test_tool_versions.py scripts/test_markdown_links.py scripts/test_module_diagrams.py scripts/test_nvx_mutants.py scripts/test_nvx_coverage.py scripts/test_nvx_scenario_coverage.py scripts/test_setup_azure.py scripts/test_setup_azure_linux.py scripts/test_setup_azure_windows.py scripts/test_powershell_testing.py scripts/test_test_layout.py scripts/test_test_changes.py scripts/test_public_api.py scripts/test_scripts_coverage.py scripts/test_openvmm_git.py scripts/test_openvmm_pin.py scripts/test_openvmm_release.py scripts/test_local_gates.py scripts/test_pr_threads.py scripts/test_ci_triage.py scripts/test_issue_workspace.py scripts/test_host_worktree.py scripts/test_rebase_check.py scripts/test_nvx_hosts.py scripts/test_host_probe.py scripts/test_benchmark_series.py scripts/test_label_issues.py -v + python3 -m unittest scripts/test_performance.py scripts/test_nvx_tools.py scripts/test_kconfig.py scripts/test_kernel_config.py scripts/test_guest_binaries.py scripts/test_microvm_tests.py scripts/test_nightly_ci.py scripts/test_development_release.py scripts/test_crate_release.py scripts/test_host_telemetry.py scripts/test_time_abi.py scripts/test_tool_versions.py scripts/test_markdown_links.py scripts/test_module_diagrams.py scripts/test_nvx_mutants.py scripts/test_nvx_coverage.py scripts/test_nvx_scenario_coverage.py scripts/test_setup_azure.py scripts/test_setup_azure_linux.py scripts/test_setup_azure_windows.py scripts/test_powershell_testing.py scripts/test_test_layout.py scripts/test_test_changes.py scripts/test_public_api.py scripts/test_scripts_coverage.py scripts/test_openvmm_git.py scripts/test_openvmm_pin.py scripts/test_openvmm_release.py scripts/test_local_gates.py scripts/test_pr_threads.py scripts/test_ci_triage.py scripts/test_issue_workspace.py scripts/test_host_worktree.py scripts/test_rebase_check.py scripts/test_nvx_hosts.py scripts/test_host_probe.py scripts/test_benchmark_series.py scripts/test_label_issues.py scripts/test_issue_link.py -v python3 scripts/test_adversarial.py -v python3 scripts/nvx.py --help python3 scripts/nvx.py test-openvmm-unit --help @@ -30,7 +30,7 @@ runs: if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } python -m compileall -q scripts if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - python -m unittest scripts/test_performance.py scripts/test_nvx_tools.py scripts/test_kconfig.py scripts/test_kernel_config.py scripts/test_guest_binaries.py scripts/test_microvm_tests.py scripts/test_nightly_ci.py scripts/test_development_release.py scripts/test_crate_release.py scripts/test_host_telemetry.py scripts/test_time_abi.py scripts/test_tool_versions.py scripts/test_markdown_links.py scripts/test_module_diagrams.py scripts/test_nvx_mutants.py scripts/test_nvx_coverage.py scripts/test_nvx_scenario_coverage.py scripts/test_setup_azure.py scripts/test_setup_azure_linux.py scripts/test_setup_azure_windows.py scripts/test_powershell_testing.py scripts/test_test_layout.py scripts/test_test_changes.py scripts/test_public_api.py scripts/test_scripts_coverage.py scripts/test_openvmm_git.py scripts/test_openvmm_pin.py scripts/test_openvmm_release.py scripts/test_local_gates.py scripts/test_pr_threads.py scripts/test_ci_triage.py scripts/test_issue_workspace.py scripts/test_host_worktree.py scripts/test_rebase_check.py scripts/test_nvx_hosts.py scripts/test_host_probe.py scripts/test_benchmark_series.py scripts/test_label_issues.py -v + python -m unittest scripts/test_performance.py scripts/test_nvx_tools.py scripts/test_kconfig.py scripts/test_kernel_config.py scripts/test_guest_binaries.py scripts/test_microvm_tests.py scripts/test_nightly_ci.py scripts/test_development_release.py scripts/test_crate_release.py scripts/test_host_telemetry.py scripts/test_time_abi.py scripts/test_tool_versions.py scripts/test_markdown_links.py scripts/test_module_diagrams.py scripts/test_nvx_mutants.py scripts/test_nvx_coverage.py scripts/test_nvx_scenario_coverage.py scripts/test_setup_azure.py scripts/test_setup_azure_linux.py scripts/test_setup_azure_windows.py scripts/test_powershell_testing.py scripts/test_test_layout.py scripts/test_test_changes.py scripts/test_public_api.py scripts/test_scripts_coverage.py scripts/test_openvmm_git.py scripts/test_openvmm_pin.py scripts/test_openvmm_release.py scripts/test_local_gates.py scripts/test_pr_threads.py scripts/test_ci_triage.py scripts/test_issue_workspace.py scripts/test_host_worktree.py scripts/test_rebase_check.py scripts/test_nvx_hosts.py scripts/test_host_probe.py scripts/test_benchmark_series.py scripts/test_label_issues.py scripts/test_issue_link.py -v if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } python scripts\test_adversarial.py -v if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } diff --git a/.github/skills/nvx-rebase-openvmm-chain/SKILL.md b/.github/skills/nvx-rebase-openvmm-chain/SKILL.md index a764e27b2..d528f8188 100644 --- a/.github/skills/nvx-rebase-openvmm-chain/SKILL.md +++ b/.github/skills/nvx-rebase-openvmm-chain/SKILL.md @@ -176,6 +176,13 @@ absence of an OpenVMM pull request, and the signatures), what changed in OpenVMM and in NVX, the equivalence evidence, and the landing order of section 7. Ask whether it is Draft or Ready. +A release completes no issue, so the +[Issue link](../../../doc/ci.md#issue-link) check flags its pull request and +creates the `no-issue` label when the repository lacks it. Then label the pull +request `no-issue`, which exempts it, with +`gh pr edit P --repo microsoft/nvx --add-label no-issue`. A pin that promotes +an OpenVMM fix is not a release: it references the fix's issue instead. + ## 7. Land The Release Once OpenVMM CI passed NVX's required jobs on the new head, and only when the diff --git a/.github/workflows/issue-link.yml b/.github/workflows/issue-link.yml new file mode 100644 index 000000000..9594e403f --- /dev/null +++ b/.github/workflows/issue-link.yml @@ -0,0 +1,64 @@ +name: Issue link + +# Checks that a pull request references an issue of the repository: GitHub +# links it to one, or its description holds Fixes, Closes, Part of, or Refs +# and the issue (doc/ci.md#issue-link). An unlinked pull request gets the +# needs-issue label and one comment that says how to fix it, and the check +# fails; a linked or exempt one loses them. pull_request_target runs the +# workflow as the default branch holds it, with a token that may label and +# comment, for pull requests from forks too. So the job runs the default +# branch's script, which reads the pull request through the API and never +# runs its code. +on: + pull_request_target: + types: + - opened + - reopened + - synchronize + # An edit of the description, or of the base, changes the verdict + # without a push. + - edited + - labeled + - unlabeled + +permissions: {} + +jobs: + check: + name: Check that the pull request references an issue + # No condition: a run whose job a condition skips would replace the result + # of the run before it, so every event checks the pull request again. + runs-on: ubuntu-latest + timeout-minutes: 5 + # Runs of one pull request go one at a time, so that each reads what the + # run before it wrote: canceling a run would not cancel a write that + # GitHub had already received. A newer waiting run replaces an older one, + # so the newest event's run comes last. + concurrency: + group: issue-link-${{ github.event.pull_request.number }} + cancel-in-progress: false + # Labelling and commenting on a pull request need pull-requests: write. + # Reading an issue of a public repository needs no issues permission. + permissions: + contents: read + pull-requests: write + steps: + # The default branch's script runs, whatever the pull request's base, + # so that no other branch's script runs with the token. + - name: Checkout + uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + with: + ref: ${{ github.event.repository.default_branch }} + persist-credentials: false + + # Only the pull request's number reaches the job; the script reads the + # rest through the API and never prints the description. + - name: Check that the pull request references an issue + env: + GH_TOKEN: ${{ github.token }} + NUMBER: ${{ github.event.pull_request.number }} + run: >- + python3 scripts/check_issue_link.py + --repository "${GITHUB_REPOSITORY}" + --summary "${GITHUB_STEP_SUMMARY}" + "${NUMBER}" diff --git a/doc/ci.md b/doc/ci.md index d59bd9b82..86da5adc7 100644 --- a/doc/ci.md +++ b/doc/ci.md @@ -2055,8 +2055,9 @@ started it. The job checks out the default branch, never the run's code. Its token can read the repository, the run's jobs and logs, and their check annotations, and write issues, and no other workflow can write issues; the -[Test changes](#test-changes) workflow labels and comments on pull requests -with a token that writes pull requests instead. The job runs one +[Test changes](#test-changes) and [Issue link](#issue-link) workflows label +and comment on pull requests with tokens that write pull requests instead. The +job runs one report at a time; a newer reporter can replace one that waits for its turn, but it reports the latest nightly result anyway. Its job summary repeats the report. @@ -2215,6 +2216,77 @@ The `quality` job checks the [test layout](contribute.md#test-layout) with where tests live, which test hooks a production file may hold, and which the flagging script shares to read Rust. +## Issue link + +The [`issue-link.yml`](../.github/workflows/issue-link.yml) workflow checks +that a pull request references an issue of this repository, as +[Commits and pull requests](contribute.md#commits-and-pull-requests) asks. A +pull request is linked when GitHub links it to an issue of the repository, as +a closing keyword in the description of a pull request to the default branch, +or the Development sidebar, does, or when its description holds a keyword and +an issue: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, +`resolves`, `resolved`, `Part of`, or `Refs`, in any case and with an +optional colon, then `#N`, `microsoft/nvx#N`, or the issue's URL, where `N` is +an issue, open or closed. The description counts whatever the base, so a +stacked pull request, to which a closing keyword links no issue, counts too, +and so do `Part of` and `Refs`, which never link one. A pull request's number, +a missing number, a bare `#N`, and another repository's issue do not count. +The script reads the description as GitHub renders it on the pull request's +page, through GitHub's +[Markdown API](https://docs.github.com/en/rest/markdown/markdown#render-a-markdown-document), +and only the text that GitHub shows counts: not a reference in an HTML +comment, such as the template's, in an attribute, such as a link's title, or +in code, inline, fenced, indented, or in `
`, nor a keyword that code or
+the end of a block, such as a paragraph, a list item, a heading, or a table
+cell, separates from its number. A link counts by where it goes, and of its
+text only a keyword that starts it: a link to an issue or a pull request on
+GitHub, such as the link that GitHub makes of `#N`, as that keyword and
+`OWNER/REPO#N`, so `[Part of #N]` linked to the issue counts and `[#N]`
+linked to another repository's issue does not, and any other link as code
+does. Such a link is `https://github.com/OWNER/REPO/issues/N` or
+`.../pull/N`, whose scheme and host may take any case or be left out; a link
+relative to the page counts as code does. In such a link, as in an issue's URL
+that GitHub shows as text, nothing may follow `N` but a slash, a query, or a
+fragment, and in text the punctuation that ends a sentence, so that no `..`
+takes it elsewhere, and the text after a link does not extend `N`. It looks up
+only the first 10 numbers that the description references, so a description
+cannot make it call the API without bound, which is one more reason to
+reference the issue on the first line.
+
+It runs when a pull request to any branch, drafts included, is opened,
+reopened, pushed to, edited, labelled, or unlabelled. The runs of one pull
+request go one at a time, so that each reads what the run before it wrote,
+since canceling a run would not cancel a write that GitHub had already
+received; a newer waiting run replaces an older one, so the newest event's run
+comes last. Its job has no condition, since a run whose job
+a condition skipped would replace the result of the run before it. An
+unlinked pull request gets the `needs-issue` label and one comment, which a
+hidden marker at its start identifies, that says how to reference an issue,
+and the check fails. Editing the description runs it again: a linked pull
+request loses the label, and the comment, if there is one, says that it
+passes. Pull requests by `dependabot[bot]` or `github-actions[bot]`, and those
+labelled `no-issue`, which a maintainer applies to a pull request that needs
+no issue, such as a release pin of the OpenVMM chain, are exempt; closed and
+merged ones are left alone. The workflow creates either label when the
+repository lacks it. `Required status check` does not wait for the workflow. A
+GitHub API error fails the check. The script reads everything before its first
+change, so an error while reading changes nothing, and the next run completes
+the changes of a run that fails while writing. The job summary gives the
+verdict and the numbers that the description references, never the
+description.
+
+As with [Test changes](#test-changes), `pull_request_target` gives the job a
+token that can label and comment, for pull requests from forks too, so the
+job runs the workflow and [`check_issue_link.py`](../scripts/check_issue_link.py)
+of the default branch, whose checkout keeps no credentials, and never a pull
+request's code. Only the pull request's number reaches the job; the script
+reads the pull request, has GitHub render its description, and reads the
+issues that GitHub links to it, the issues that its description names, and
+its comments through the API. The token can read the
+repository's contents and write pull requests, but not issues: reading an
+issue of a public repository needs no permission. A change to the workflow or
+to the script takes effect once it merges into `dev`.
+
 ## crates.io releases
 
 A scheduled or manually dispatched full run of `dev` publishes the
diff --git a/doc/contribute.md b/doc/contribute.md
index cc484f4f0..0d1cafb9c 100644
--- a/doc/contribute.md
+++ b/doc/contribute.md
@@ -52,7 +52,7 @@ with the deploy key and on the hypervisor runners before it merges; see
 | Commit body | What changed and why, when the subject does not say enough. |
 | Pull request title | The commit subject of a single-commit pull request; otherwise a summary in the same form. |
 | Pull request body | The sections of the [pull request template](../.github/pull_request_template.md): **What does this pull request change?**, **Why is this change needed?**, **How was this change validated?**, with the checks that you ran and the gates that you leave to CI, such as backends that you could not test, and **Checklist**. Add **Changes to existing tests** when `check_test_changes.py` lists any, and **OpenVMM pin** when the `openvmm` gitlink moves. |
-| Issue references | `Closes #N` or `Fixes #N` first when the pull request completes the issue; `Part of #N` or `Refs #N` otherwise. |
+| Issue references | Every pull request references an issue of this repository on the first line of its description: `Closes #N` or `Fixes #N` when it completes the issue, and `Part of #N` or `Refs #N` otherwise. When no issue covers the change, open one first. The [Issue link](ci.md#issue-link) workflow labels a pull request that references none `needs-issue`; a maintainer labels one that needs none, such as a release pin of the OpenVMM chain, `no-issue`. |
 | Review threads | Reply with the commit that addresses the comment, or with the evidence that no change is needed, then resolve the thread once the pull request's head holds that outcome. `scripts/pr_threads.py` lists the threads, and checks each reply and resolution. |
 
 Leave the performance histories in `data/*.csv` to CI: successful `dev`
diff --git a/doc/project-structure.md b/doc/project-structure.md
index 3d2523a3b..60518d678 100644
--- a/doc/project-structure.md
+++ b/doc/project-structure.md
@@ -45,6 +45,7 @@ nvx/
 |   |   |-- ci.yml               Main build, test, benchmark, and release workflow
 |   |   |-- copilot-code-review.yml Copilot code review environment
 |   |   |-- copilot-setup-steps.yml Copilot cloud agent environment
+|   |   |-- issue-link.yml       Check that every pull request references an issue
 |   |   |-- module-diagrams.yml  Module diagrams of the nvx crate, drawn every night
 |   |   |-- nightly-ci-report.yml Report of failed nightly CI runs
 |   |   |-- nvx-coverage.yml     Coverage of nvx's own tests, for dev and pull requests
@@ -182,6 +183,7 @@ nvx/
 |   |   |-- setup-windows-whp.ps1 Windows/WHP development-host and Actions runner bootstrap
 |   |   `-- tool-versions.conf    Shared tool release and checksum pins
 |   |-- benchmark_series.py      Benchmark series with CI's validation, for local and remote hosts
+|   |-- check_issue_link.py      Checks that a pull request references an issue
 |   |-- check_markdown_links.py  Markdown link, anchor, and doc/ path check run by CI
 |   |-- check_test_changes.py    Flags the changes of a pull request to existing tests
 |   |-- check_test_layout.py     Check that tests live apart from the code that they test
@@ -242,7 +244,7 @@ reusable workflows: `build-openvmm-binary.yml` builds OpenVMM for one target,
 `run-platform.yml` benchmarks one platform. The full runs of `ci.yml` on `dev`
 also publish the `nvx` crate to
 crates.io. The other workflows report failed nightly CI runs, flag the pull
-requests that change existing tests, draw the module
+requests that change existing tests or reference no issue, draw the module
 diagrams of the `nvx` crate every night, run adversarial campaigns, measure
 the coverage of the `nvx` crate's tests and of the Python tooling's unit tests
 as `dev` changes, measure every week which host code of the `nvx` crate the
@@ -393,6 +395,8 @@ hooks that `test-layout-allowlist.json` allows them, and
 `check_test_changes.py` flags the pull requests that change existing tests; see
 [Test layout](contribute.md#test-layout) and
 [Changes to existing tests](contribute.md#changes-to-existing-tests).
+`check_issue_link.py` flags the pull requests that reference no issue; see
+[Issue link](ci.md#issue-link).
 `public_api.py` checks the public API of `nvx` against its snapshots in
 `nvx/public-api/`, and rewrites them; see [Rust crates](ci.md#rust-crates).
 
diff --git a/scripts/check_issue_link.py b/scripts/check_issue_link.py
new file mode 100644
index 000000000..ff278b0fa
--- /dev/null
+++ b/scripts/check_issue_link.py
@@ -0,0 +1,766 @@
+#!/usr/bin/env python3
+"""Check that a pull request references an issue of its repository.
+
+A pull request is linked when GitHub links it to an issue of the repository,
+as a closing keyword in the description of a pull request to the default
+branch, or the Development sidebar, does, or when its description holds
+`KEYWORD TARGET`:
+
+- KEYWORD is close, closes, closed, fix, fixes, fixed, resolve, resolves,
+  resolved, Part of, or Refs, in any case, with an optional colon;
+- TARGET is #N, OWNER/REPO#N, or https://github.com/OWNER/REPO/issues/N, where
+  OWNER/REPO is the repository and N one of its issues, open or closed. A pull
+  request's number, a missing number, and a bare #N do not count.
+
+The script reads the description as GitHub renders it, through GitHub's
+Markdown API, and only the text that GitHub shows counts: not an HTML comment,
+an attribute such as a link's title, or code, inline, fenced, indented, or in
+
, nor a keyword that code or the end of a block, such as a paragraph, a
+list item, a heading, or a table cell, separates from its target. A link
+counts by where it goes, and of its text only a keyword that starts it: a link
+to an issue or a pull request, https://github.com/OWNER/REPO/issues/N or
+.../pull/N, such as the link that GitHub makes of #N, as that keyword and
+OWNER/REPO#N, and any other link as code does. Its scheme and host may take
+any case or be left out, and the text after it does not extend N. Nothing may
+follow N, in such a link or in an issue's URL that GitHub shows as text, other
+than a slash, a query, or a fragment, or, in text, the punctuation that ends a
+sentence. It looks up at most the first LOOKUPS numbers of the description. A
+pull request by dependabot[bot] or github-actions[bot], or labelled no-issue,
+is exempt, and a closed or merged one is left alone.
+
+The script reads the pull request through the API, never from an event, and
+never runs its code or prints its description, so a workflow that
+pull_request_target triggers can run it, from the default branch, on any pull
+request. A linked or exempt pull request loses the needs-issue label, the
+marker comment, if there is one, says so, and the script exits 0. An unlinked
+one gets the label and one marker comment, and the script exits 1. A GitHub
+API error before the first change changes nothing, and the script exits 2.
+"""
+
+from __future__ import annotations
+
+import argparse
+import html.parser
+import json
+import re
+import subprocess
+import sys
+import urllib.parse
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+NEEDS_ISSUE = "needs-issue"
+NO_ISSUE = "no-issue"
+# The labels that a flagged pull request needs, with their colors and
+# descriptions, created when the repository lacks them.
+LABELS = {
+    NEEDS_ISSUE: ("d93f0b", "The description references no issue; see Issue link"),
+    NO_ISSUE: ("c2e0c6", "Needs no issue reference; applied by a maintainer"),
+}
+COMMENT_MARKER = ""
+COMMENTER = "github-actions[bot]"
+EXEMPT_AUTHORS = frozenset({"dependabot[bot]", "github-actions[bot]"})
+GUIDE = "doc/contribute.md#commits-and-pull-requests"
+
+# Exit codes.
+PASSED = 0
+FLAGGED = 1
+FAILED = 2
+
+_KEYWORD = r"(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|part\s+of|refs)"
+_NAME = r"[A-Za-z0-9_.-]+"
+# GitHub's numbers fit in 32 bits, so a longer number, which int() might not
+# even convert, matches nothing.
+_NUMBER = r"[1-9][0-9]{0,9}"
+_REFERENCE = re.compile(
+    rf"(?{_NUMBER})"
+    rf"|(?P{_NAME})/(?P{_NAME})#(?P{_NUMBER})"
+    rf"|https://github\.com/(?P{_NAME})/(?P{_NAME})"
+    rf"/issues/(?P{_NUMBER})"
+    # As in a link, nothing but a slash, a query, or a fragment may follow the
+    # number of a URL, but for the punctuation that ends a sentence.
+    r"(?=/?(?:[?#][^\s\x00]*)?[.,;:!)\]]*(?![^\s\x00])))"
+    r"(?![\w-])",
+    re.IGNORECASE,
+)
+# The most numbers of a description that the check looks up, so that a
+# description cannot make it call the API without bound.
+LOOKUPS = 10
+
+# A link to an issue or a pull request on GitHub, such as the link that GitHub
+# makes of #N, which stands for OWNER/REPO#N whatever its text. Its scheme and
+# host may take any case, as a browser reads them, or be left out, but nothing
+# may follow the number other than a slash, a query, or a fragment, so that it
+# goes where it names.
+_ISSUE_LINK = re.compile(
+    rf"(?:(?i:https?:)?//(?i:github\.com))?/(?P{_NAME})/(?P{_NAME})"
+    rf"/(?:issues|pull)/(?P{_NUMBER})/?(?:[?#].*)?",
+    re.DOTALL,
+)
+# A keyword that starts the text of a link to an issue, which the link keeps.
+_LEADING_KEYWORD = re.compile(rf"\s*{_KEYWORD}:?(?=\s|\Z)", re.IGNORECASE)
+# A NUL stands for code, for a link elsewhere, and for the start and the end of
+# each block, which \s does not match, so that no reference spans them, and
+# follows the reference that a link to an issue stands for, so that no text
+# after the link extends its number.
+_BOUNDARY = "\0"
+# The elements whose text GitHub links no reference in.
+_CODE = frozenset({"code", "pre"})
+# The elements that GitHub renders within a line of text. Any other element,
+# a block or a ruby annotation (rt, rp) alike, separates its text from the
+# text around it.
+_INLINE = frozenset(
+    {
+        "a",
+        "abbr",
+        "b",
+        "bdi",
+        "bdo",
+        "br",
+        "cite",
+        "del",
+        "dfn",
+        "em",
+        "g-emoji",
+        "i",
+        "img",
+        "ins",
+        "kbd",
+        "mark",
+        "picture",
+        "q",
+        "ruby",
+        "s",
+        "samp",
+        "small",
+        "source",
+        "span",
+        "strike",
+        "strong",
+        "sub",
+        "sup",
+        "themed-picture",
+        "tt",
+        "u",
+        "var",
+        "wbr",
+    }
+)
+
+
+class _Text(html.parser.HTMLParser):
+    """Collects the text of GitHub's HTML but for code, with a boundary at
+    code and at the start and the end of each block. Attributes, such as a
+    link's title, are not text, and a link stands for where it goes: a link
+    to an issue or a pull request for the keyword that starts its text, if
+    any, and OWNER/REPO#N, and any other link for a boundary."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.code = 0
+        # Whether each open link hides its text, and how many do.
+        self.links: list[bool] = []
+        self.hidden = 0
+        self.parts: list[str] = []
+        # The reference that the open link to an issue stands for, and its text.
+        self.target: str | None = None
+        self.label: list[str] = []
+
+    def _add(self, part: str) -> None:
+        (self.parts if self.target is None else self.label).append(part)
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag == "a":
+            href = dict(attrs).get("href")
+            if href is not None and not self.code and not self.hidden:
+                target = _ISSUE_LINK.fullmatch(href)
+                if target:
+                    self.target = (
+                        f"{target['owner']}/{target['name']}#{target['number']}"
+                    )
+                    self.label = []
+                else:
+                    self.parts.append(_BOUNDARY)
+            self.links.append(href is not None)
+            self.hidden += href is not None
+        elif tag == "br":
+            self._add("\n")
+        elif tag not in _INLINE:
+            self._add(_BOUNDARY)
+        if tag in _CODE:
+            self.code += 1
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "a" and self.links:
+            self.hidden -= self.links.pop()
+            if not self.hidden and self.target is not None:
+                keyword = _LEADING_KEYWORD.match("".join(self.label))
+                if keyword:
+                    self.parts.append(f"{keyword[0]} ")
+                self.parts += (self.target, _BOUNDARY)
+                self.target = None
+        if tag in _CODE:
+            self.code = max(0, self.code - 1)
+        if tag not in _INLINE:
+            self._add(_BOUNDARY)
+
+    def handle_data(self, data: str) -> None:
+        if self.code:
+            return
+        if self.target is not None:
+            self.label.append(data)
+        elif not self.hidden:
+            self.parts.append(data)
+
+
+def visible_text(rendered: str) -> str:
+    """Returns the text of the HTML that GitHub renders for a description,
+    with a boundary for code, for a link elsewhere than an issue or a pull
+    request, and at the start and the end of each block, and a link to an
+    issue or a pull request as the keyword that starts its text, if any, and
+    OWNER/REPO#N, then a boundary."""
+    text = _Text()
+    text.feed(rendered)
+    text.close()
+    return "".join(text.parts)
+
+
+def referenced_numbers(rendered: str, repository: str) -> list[int]:
+    """Returns the numbers that a description references with a keyword in
+    the repository, in order and once each, from the HTML that GitHub renders
+    for it."""
+    numbers: list[int] = []
+    for match in _REFERENCE.finditer(visible_text(rendered)):
+        if match["local"]:
+            number = match["local"]
+        elif match["qualified"]:
+            if f"{match['owner']}/{match['name']}".casefold() != repository.casefold():
+                continue
+            number = match["qualified"]
+        else:
+            if (
+                f"{match['url_owner']}/{match['url_name']}".casefold()
+                != repository.casefold()
+            ):
+                continue
+            number = match["url"]
+        if int(number) not in numbers:
+            numbers.append(int(number))
+    return numbers
+
+
+# GitHub.
+
+
+class LinkError(RuntimeError):
+    """A call to GitHub failed, or its answer was not what the API documents."""
+
+
+Runner = Callable[[Sequence[str], str | None], subprocess.CompletedProcess[str]]
+
+
+def _run(
+    arguments: Sequence[str], stdin: str | None
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        list(arguments),
+        input=stdin,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        check=False,
+    )
+
+
+def _object(value: object, what: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise LinkError(f"GitHub returned no object for {what}")
+    return cast(dict[str, object], value)
+
+
+def _list(value: object, what: str) -> list[object]:
+    if not isinstance(value, list):
+        raise LinkError(f"GitHub returned no list for {what}")
+    return cast(list[object], value)
+
+
+def _string(value: object, what: str) -> str:
+    if not isinstance(value, str):
+        raise LinkError(f"GitHub returned no string for {what}")
+    return value
+
+
+def _number(value: object, what: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise LinkError(f"GitHub returned no number for {what}")
+    return value
+
+
+def _json(text: str | None, what: str) -> object:
+    try:
+        return json.loads(text or "")
+    except ValueError as error:
+        raise LinkError(f"GitHub returned no JSON for {what}: {error}") from error
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    number: int
+    open: bool
+    author: str
+    body: str
+    labels: tuple[str, ...]
+    default_branch: str
+
+    def labelled(self, label: str) -> bool:
+        # GitHub compares label names without case.
+        return label.casefold() in (name.casefold() for name in self.labels)
+
+
+@dataclass(frozen=True)
+class Comment:
+    id: int
+    body: str
+
+
+class GitHub:
+    """The calls to GitHub that check a pull request, through the gh CLI."""
+
+    GRAPHQL_LINKS = """
+query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      closingIssuesReferences(first: 100) {
+        nodes { number repository { nameWithOwner } }
+      }
+    }
+  }
+}
+"""
+
+    def __init__(self, repository: str, run: Runner = _run) -> None:
+        self.repository = repository
+        self.run = run
+
+    def api(
+        self,
+        endpoint: str,
+        *,
+        method: str = "GET",
+        body: Mapping[str, object] | None = None,
+        options: Sequence[str] = (),
+        tolerate: Sequence[int] = (),
+    ) -> str | None:
+        """Calls the API; returns None for an HTTP status that tolerate lists,
+        and raises LinkError for any other failure."""
+        arguments = ["gh", "api", "--method", method, *options, endpoint]
+        stdin = None
+        if body is not None:
+            arguments += ["--input", "-"]
+            stdin = json.dumps(body)
+        try:
+            result = self.run(arguments, stdin)
+        except OSError as error:
+            raise LinkError(f"gh api {method} {endpoint} failed: {error}") from error
+        if result.returncode != 0:
+            if any(f"HTTP {status}" in result.stderr for status in tolerate):
+                return None
+            raise LinkError(
+                f"gh api {method} {endpoint} failed: {result.stderr.strip()}"
+            )
+        return result.stdout
+
+    def pull_request(self, number: int) -> PullRequest:
+        what = f"pull request #{number}"
+        fields = _object(
+            _json(self.api(f"repos/{self.repository}/pulls/{number}"), what), what
+        )
+        base = _object(fields.get("base"), f"{what}'s base")
+        repository = _object(base.get("repo"), f"{what}'s repository")
+        body = fields.get("body")
+        return PullRequest(
+            number=_number(fields.get("number"), what),
+            open=_string(fields.get("state"), f"{what}'s state") == "open",
+            author=_string(
+                _object(fields.get("user"), f"{what}'s author").get("login"),
+                f"{what}'s author",
+            ),
+            body=_string(body, f"{what}'s description") if body is not None else "",
+            labels=tuple(
+                _string(_object(label, f"{what}'s label").get("name"), "a label")
+                for label in _list(fields.get("labels"), f"{what}'s labels")
+            ),
+            default_branch=_string(
+                repository.get("default_branch"), "the default branch"
+            ),
+        )
+
+    def render(self, text: str) -> str:
+        """Returns the HTML that GitHub renders for Markdown text of the
+        repository, as a pull request's page shows it."""
+        return (
+            self.api(
+                "markdown",
+                method="POST",
+                body={"text": text, "mode": "gfm", "context": self.repository},
+            )
+            or ""
+        )
+
+    def linked_issues(self, number: int) -> list[int]:
+        """Returns the issues of the repository that GitHub links to the pull
+        request: those that a closing keyword links, for a pull request to the
+        default branch, and those linked from the Development sidebar."""
+        owner, name = self.repository.split("/")
+        what = f"the issues linked to #{number}"
+        answer = _object(
+            _json(
+                self.api(
+                    "graphql",
+                    method="POST",
+                    options=(
+                        "-f",
+                        f"query={self.GRAPHQL_LINKS}",
+                        "-f",
+                        f"owner={owner}",
+                        "-f",
+                        f"name={name}",
+                        "-F",
+                        f"number={number}",
+                    ),
+                ),
+                what,
+            ),
+            what,
+        )
+        if answer.get("errors"):
+            raise LinkError(f"GitHub could not list {what}: {answer['errors']}")
+        node: object = answer
+        for key in ("data", "repository", "pullRequest", "closingIssuesReferences"):
+            node = _object(node, what).get(key)
+        issues: list[int] = []
+        for item in _list(_object(node, what).get("nodes"), what):
+            issue = _object(item, what)
+            source = _object(issue.get("repository"), what).get("nameWithOwner")
+            if _string(source, what).casefold() == self.repository.casefold():
+                issues.append(_number(issue.get("number"), what))
+        return issues
+
+    def kind(self, number: int) -> str:
+        """Returns what #number of the repository is: an issue, a pull
+        request, missing, or an issue that moved to another repository."""
+        what = f"#{number}"
+        text = self.api(f"repos/{self.repository}/issues/{number}", tolerate=(404, 410))
+        if text is None:
+            return "missing"
+        fields = _object(_json(text, what), what)
+        if "pull_request" in fields:
+            return "pull request"
+        source = _string(fields.get("repository_url"), f"{what}'s repository")
+        if not source.casefold().endswith(f"/repos/{self.repository}".casefold()):
+            return "another repository"
+        return "issue"
+
+    def label_exists(self, label: str) -> bool:
+        name = urllib.parse.quote(label, safe="")
+        return (
+            self.api(f"repos/{self.repository}/labels/{name}", tolerate=(404,))
+            is not None
+        )
+
+    def comments(self, number: int) -> list[Comment]:
+        """Returns COMMENTER's comments on #number."""
+        what = f"the comments of #{number}"
+        listing = self.api(
+            f"repos/{self.repository}/issues/{number}/comments",
+            options=(
+                "--paginate",
+                "--jq",
+                ".[] | {id, author: .user.login, body} | @json",
+            ),
+        )
+        comments: list[Comment] = []
+        for line in (listing or "").splitlines():
+            if line.strip():
+                fields = _object(_json(line, what), what)
+                # Anyone else's comments do not matter, and a deleted account's
+                # have no author.
+                if fields.get("author") != COMMENTER:
+                    continue
+                comments.append(
+                    Comment(
+                        _number(fields.get("id"), what),
+                        _string(fields.get("body"), what),
+                    )
+                )
+        return comments
+
+    def create_label(self, label: str) -> bool:
+        """Creates the label, and returns False when another run created it
+        first."""
+        color, description = LABELS[label]
+        endpoint = f"repos/{self.repository}/labels"
+        body = {"name": label, "color": color, "description": description}
+        if self.api(endpoint, method="POST", body=body, tolerate=(422,)) is not None:
+            return True
+        # GitHub answers 422 both when the label exists and when it rejects it.
+        if not self.label_exists(label):
+            raise LinkError(f"GitHub rejected the `{label}` label (HTTP 422)")
+        return False
+
+    def add_label(self, number: int, label: str) -> None:
+        self.api(
+            f"repos/{self.repository}/issues/{number}/labels",
+            method="POST",
+            body={"labels": [label]},
+        )
+
+    def remove_label(self, number: int, label: str) -> None:
+        name = urllib.parse.quote(label, safe="")
+        self.api(
+            f"repos/{self.repository}/issues/{number}/labels/{name}",
+            method="DELETE",
+            tolerate=(404,),
+        )
+
+    def create_comment(self, number: int, body: str) -> None:
+        self.api(
+            f"repos/{self.repository}/issues/{number}/comments",
+            method="POST",
+            body={"body": body},
+        )
+
+    def update_comment(self, comment: int, body: str) -> None:
+        self.api(
+            f"repos/{self.repository}/issues/comments/{comment}",
+            method="PATCH",
+            body={"body": body},
+        )
+
+
+# The verdict.
+
+
+@dataclass(frozen=True)
+class Verdict:
+    state: str  # closed, exempt, linked, or unlinked
+    reason: str
+    linked: tuple[int, ...] = ()
+    # The numbers of the description, with what each is, in order; None for
+    # one that the check did not need to look up.
+    referenced: tuple[tuple[int, str | None], ...] = ()
+
+    @property
+    def code(self) -> int:
+        return FLAGGED if self.state == "unlinked" else PASSED
+
+
+def evaluate(github: GitHub, pull: PullRequest) -> Verdict:
+    """Reads what the verdict needs and changes nothing."""
+    if not pull.open:
+        return Verdict("closed", "the pull request is closed")
+    if pull.author in EXEMPT_AUTHORS:
+        return Verdict("exempt", f"its author is `{pull.author}`")
+    if pull.labelled(NO_ISSUE):
+        return Verdict("exempt", f"it is labelled `{NO_ISSUE}`")
+    numbers = (
+        referenced_numbers(github.render(pull.body), github.repository)
+        if pull.body.strip()
+        else []
+    )
+    linked = tuple(github.linked_issues(pull.number))
+    if linked:
+        return Verdict(
+            "linked",
+            f"GitHub links it to #{linked[0]}",
+            linked,
+            tuple((number, None) for number in numbers),
+        )
+    referenced: list[tuple[int, str | None]] = []
+    found: int | None = None
+    for index, number in enumerate(numbers):
+        if found is not None or index >= LOOKUPS:
+            referenced.append((number, None))
+            continue
+        kind = github.kind(number)
+        referenced.append((number, kind))
+        if kind == "issue":
+            found = number
+    if found is not None:
+        return Verdict(
+            "linked", f"its description references #{found}", (), tuple(referenced)
+        )
+    reason = "its description references no issue"
+    if len(numbers) > LOOKUPS:
+        reason = f"none of the first {LOOKUPS} numbers of its description is an issue"
+    return Verdict("unlinked", reason, (), tuple(referenced))
+
+
+def comment_body(verdict: Verdict, repository: str, default_branch: str) -> str:
+    guide = f"https://github.com/{repository}/blob/{default_branch}/{GUIDE}"
+    if verdict.state != "unlinked":
+        return "\n".join(
+            [
+                COMMENT_MARKER,
+                f"**This pull request passes the issue link check**: {verdict.reason}.",
+                "",
+            ]
+        )
+    headline = "**This pull request references no issue.**"
+    if len(verdict.referenced) > LOOKUPS:
+        headline = (
+            f"**None of the first {LOOKUPS} numbers that this pull request's "
+            "description references is an issue**, and the check looks up no "
+            "more."
+        )
+    return "\n".join(
+        [
+            COMMENT_MARKER,
+            f"{headline} Reference an issue of "
+            "this repository on the first line of the description, as "
+            f"[Commits and pull requests]({guide}) asks:",
+            "",
+            "- `Fixes #N` or `Closes #N` when the pull request completes the issue;",
+            "- `Part of #N` or `Refs #N` otherwise.",
+            "",
+            f"`#N` may also be `{repository}#N` or the issue's URL. When no issue "
+            "covers the change, open one first. Editing the description runs "
+            f"this check again, which then removes the `{NEEDS_ISSUE}` label.",
+            "",
+            f"A maintainer can label a pull request that completes no issue, such "
+            f"as a release pin of the OpenVMM chain, `{NO_ISSUE}`.",
+            "",
+        ]
+    )
+
+
+def publish(github: GitHub, pull: PullRequest, verdict: Verdict) -> list[str]:
+    """Labels and comments as the verdict says, and returns what changed. It
+    reads everything first, so that an error changes nothing."""
+    flagged = verdict.state == "unlinked"
+    body = comment_body(verdict, github.repository, pull.default_branch)
+    comments = [
+        comment
+        for comment in github.comments(pull.number)
+        # Other workflows comment as COMMENTER too.
+        if comment.body.startswith(COMMENT_MARKER)
+    ]
+    add = flagged and not pull.labelled(NEEDS_ISSUE)
+    # A label that the pull request holds exists; no-issue, which a flagged
+    # pull request cannot hold, has to exist for a maintainer to apply it.
+    missing = [
+        label
+        for label in LABELS
+        if flagged and not pull.labelled(label) and not github.label_exists(label)
+    ]
+    changes: list[str] = []
+    for label in missing:
+        if github.create_label(label):
+            changes.append(f"created the `{label}` label")
+    if add:
+        github.add_label(pull.number, NEEDS_ISSUE)
+        changes.append(f"added `{NEEDS_ISSUE}`")
+    elif not flagged and pull.labelled(NEEDS_ISSUE):
+        github.remove_label(pull.number, NEEDS_ISSUE)
+        changes.append(f"removed `{NEEDS_ISSUE}`")
+    if comments:
+        if comments[0].body != body:
+            github.update_comment(comments[0].id, body)
+            changes.append("updated the comment")
+    elif flagged:
+        github.create_comment(pull.number, body)
+        changes.append("added the comment")
+    return changes
+
+
+def summary(number: int, verdict: Verdict, changes: Sequence[str] | None) -> str:
+    """Renders the verdict and the numbers found, never the description."""
+
+    def numbers(found: Sequence[tuple[int, str | None]]) -> str:
+        return (
+            ", ".join(
+                f"#{number} ({kind or 'not looked up'})" for number, kind in found
+            )
+            or "none"
+        )
+
+    lines = [
+        f"### Issue link: {verdict.state}",
+        "",
+        f"Pull request #{number}: {verdict.reason}.",
+        "",
+    ]
+    if verdict.state in ("linked", "unlinked"):
+        lines += [
+            f"- GitHub's links: "
+            f"{', '.join(f'#{issue}' for issue in verdict.linked) or 'none'}",
+            f"- The description's references: {numbers(verdict.referenced)}",
+        ]
+    if changes is None:
+        lines.append("- Changes: none, a dry run")
+    else:
+        lines.append(f"- Changes: {'; '.join(changes) or 'none'}")
+    return "\n".join(lines) + "\n"
+
+
+def _repository(value: str) -> str:
+    if not re.fullmatch(rf"{_NAME}/{_NAME}", value):
+        raise argparse.ArgumentTypeError("must have the form OWNER/REPO")
+    return value
+
+
+def _pull_request(value: str) -> int:
+    if not re.fullmatch(_NUMBER, value):
+        raise argparse.ArgumentTypeError("must be a pull request's number")
+    return int(value)
+
+
+def main(argv: Sequence[str] | None = None, run: Runner = _run) -> int:
+    parser = argparse.ArgumentParser(
+        description="Check that a pull request references an issue."
+    )
+    parser.add_argument("number", type=_pull_request, help="the pull request")
+    parser.add_argument(
+        "--repository", type=_repository, required=True, help="OWNER/REPO"
+    )
+    parser.add_argument("--summary", type=Path, help="append the verdict here")
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="report the verdict without labelling or commenting",
+    )
+    args = parser.parse_args(argv)
+    github = GitHub(args.repository, run)
+    try:
+        pull = github.pull_request(args.number)
+        verdict = evaluate(github, pull)
+        changes = (
+            None
+            if args.dry_run
+            else []
+            if verdict.state == "closed"
+            else publish(github, pull, verdict)
+        )
+        report = summary(args.number, verdict, changes)
+    except LinkError as error:
+        report = f"### Issue link: error\n\n{error}\n"
+        print(f"error: {error}", file=sys.stderr)
+        code = FAILED
+    else:
+        print(report, end="")
+        code = verdict.code
+    if args.summary is not None:
+        try:
+            with args.summary.open("a", encoding="utf-8") as output:
+                output.write(report)
+        except OSError as error:
+            print(f"error: {error}", file=sys.stderr)
+            return FAILED
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/test_issue_link.py b/scripts/test_issue_link.py
new file mode 100644
index 000000000..45c0abbcc
--- /dev/null
+++ b/scripts/test_issue_link.py
@@ -0,0 +1,874 @@
+# pyright: reportPrivateUsage=false
+"""Tests of check_issue_link.py, which checks that a pull request references an
+issue."""
+
+from __future__ import annotations
+
+import contextlib
+import html
+import io
+import json
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from collections.abc import Sequence
+from pathlib import Path
+from typing import cast
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import check_issue_link as link  # noqa: E402
+
+REPOSITORY = "microsoft/nvx"
+WORKFLOWS = Path(__file__).resolve().parents[1] / ".github" / "workflows"
+
+
+def numbers(rendered: str) -> list[int]:
+    return link.referenced_numbers(rendered, REPOSITORY)
+
+
+def paragraph(text: str) -> str:
+    return f'

{text}

' + + +def issue_link(number: int, text: str = "") -> str: + """Returns GitHub's link for a reference to #number of the repository.""" + return ( + '' + f"{text or f'#{number}'}" + ) + + +class TextTests(unittest.TestCase): + """The numbers of descriptions as GitHub renders them: the HTML here is + what gh api markdown returns in the repository's context, but for the data + attributes of its links.""" + + KEYWORDS = ( + "close", + "closes", + "closed", + "fix", + "fixes", + "fixed", + "resolve", + "resolves", + "resolved", + "part of", + "refs", + ) + + def test_each_keyword_counts_in_any_case_with_an_optional_colon(self) -> None: + for keyword in self.KEYWORDS: + for spelling in (keyword, keyword.upper(), keyword.title()): + for colon in ("", ":"): + with self.subTest(keyword=spelling, colon=colon): + rendered = paragraph(f"{spelling}{colon} {issue_link(12)}") + self.assertEqual(numbers(rendered), [12]) + self.assertEqual(numbers(paragraph(f"Part of\t{issue_link(12)}")), [12]) + + def test_each_target_form_of_the_repository_counts(self) -> None: + # GitHub shows #N, OWNER/REPO#N, and the URL of an issue of the + # repository as #N, and a URL that it does not resolve as it is. + for target in ( + issue_link(12), + issue_link(12, "#12 (comment)"), + "microsoft/nvx#12", + "Microsoft/NVX#12", + '' + "https://github.com/microsoft/nvx/issues/12", + ): + with self.subTest(target=target): + self.assertEqual(numbers(paragraph(f"Fixes {target}.")), [12]) + + def test_other_repositories_and_pull_request_urls_do_not_count(self) -> None: + for target in ( + '' + "microsoft/openvmm#12", + "https://github.com/microsoft/openvmm/issues/12", + # GitHub shows the URL of a pull request that it resolves as #N, + # which the check looks up. + "https://github.com/microsoft/nvx/pull/12", + ): + with self.subTest(target=target): + self.assertEqual(numbers(paragraph(f"Fixes {target}")), []) + + def test_a_bare_or_missing_number_does_not_count(self) -> None: + for text in ( + issue_link(12), + f"Stacked on {issue_link(12)}.", + "Fixes #", + "Fixes #N", + "Fixes 12", + "Fixes #0", + "Fixes #12abc", + f"Prefixes {issue_link(12)}", + ): + with self.subTest(text=text): + self.assertEqual(numbers(paragraph(text)), []) + + def test_a_number_too_long_to_be_an_issue_does_not_count(self) -> None: + # Python converts no number of more than 4300 digits. + long = "9" * 5000 + for target in ( + f"#{long}", + f"https://github.com/microsoft/nvx/issues/{long}", + "#12345678901", + ): + with self.subTest(target=target[:20]): + rendered = paragraph(f"Refs {target}, fixes {issue_link(12)}") + self.assertEqual(numbers(rendered), [12]) + + def test_code_does_not_count(self) -> None: + for rendered in ( + paragraph('Fixes #12'), + '
Fixes #12\n'
+            "
", + # GitHub links no reference in raw
 either.
+            '
Fixes #12
', + # Backticks pair across what a table's cells would be. + paragraph('| x | Refs #12 |'), + # Nor does a link in code. + paragraph( + 'Fixes ' + f'#12' + ), + ): + with self.subTest(rendered=rendered): + self.assertEqual(numbers(rendered), []) + + def test_text_after_code_counts(self) -> None: + for rendered in ( + '
Fixes #1\n'
+            f"
\n{paragraph(f'Refs {issue_link(12)}')}", + paragraph( + f'Fixes #1 and refs {issue_link(12)}' + ), + ): + with self.subTest(rendered=rendered): + self.assertEqual(numbers(rendered), [12]) + + def test_attributes_do_not_count(self) -> None: + # A link's title, an element's title, and an image's text. + rendered = paragraph( + 't ' + 'x ' + 'Fixes #14' + ) + self.assertEqual(numbers(rendered), []) + # Nor do they open a comment or code. + rendered = paragraph( + f'Refs {issue_link(12)} ' + 'x -->' + ) + self.assertEqual(numbers(rendered), [12]) + + def test_a_link_counts_by_where_it_goes(self) -> None: + # Whatever its text, but for a keyword that starts it: a link to an + # issue or a pull request as OWNER/REPO#N, which the check looks up, + # and any other link as code. + issues = f"https://github.com/{REPOSITORY}/issues/12" + for rendered, expected in ( + (paragraph(f'Part of the issue'), [12]), + ( + paragraph( + f'Fixes #12' + ), + [12], + ), + (paragraph(f'Fixes t'), [12]), + ( + paragraph( + f'Refs #12' + ), + [12], + ), + ( + paragraph( + 'Refs #12' + ), + [], + ), + ( + paragraph('Fixes #12'), + [], + ), + ( + paragraph( + 'Fixes ' + f"{issue_link(12)}" + ), + [], + ), + ): + with self.subTest(rendered=rendered): + self.assertEqual(numbers(rendered), expected) + + def test_a_link_to_an_issue_goes_where_its_href_names(self) -> None: + # GitHub keeps a link's href as written. The browser reads the scheme + # and the host in any case, and resolves the rest against the page. + for href, expected in ( + (f"HTTPS://GitHub.com/{REPOSITORY}/issues/12", [12]), + (f"http://github.com/{REPOSITORY}/issues/12/?q=1#x", [12]), + (f"//github.com/{REPOSITORY}/issues/12", [12]), + (f"/{REPOSITORY}/issues/12", [12]), + ( + f"https://github.com/{REPOSITORY}/issues/12/../../../openvmm/issues/12", + [], + ), + (f"https://github.com/{REPOSITORY}/issues/12/x", []), + (f"https://github.com.example.com/{REPOSITORY}/issues/12", []), + # The browser takes microsoft for the host of this one, and resolves + # the next two against the page. + (f"///{REPOSITORY}/issues/12", []), + (f"{REPOSITORY}/issues/12", []), + ("../issues/12", []), + ): + with self.subTest(href=href): + rendered = paragraph(f'Refs #12') + self.assertEqual(numbers(rendered), expected) + + def test_a_link_to_an_issue_keeps_the_keyword_that_starts_its_text( + self, + ) -> None: + issues = f"https://github.com/{REPOSITORY}/issues/12" + for text, expected in ( + ("Part of #12", [12]), + ("fixes: the crash", [12]), + (" Refs", [12]), + ("Fixes #12", [12]), + ("See part of #12", []), + ("Fixes#12", []), + ('Fixes #12', []), + ): + with self.subTest(text=text): + self.assertEqual( + numbers(paragraph(f'{text}')), expected + ) + # The href, not the text, names the issue. + rendered = paragraph( + 'Part of #12' + ) + self.assertEqual(numbers(rendered), []) + + def test_text_after_a_link_to_an_issue_does_not_extend_its_number( + self, + ) -> None: + # GitHub links #12 in "Refs #12-related", and shows the 3 after a link + # to #12 apart from it. + pulls = f"https://github.com/{REPOSITORY}/pull/12" + for rendered in ( + paragraph(f"Refs {issue_link(12)}-related"), + paragraph(f'Refs #123'), + paragraph(f'Fixes #123'), + ): + with self.subTest(rendered=rendered): + self.assertEqual(numbers(rendered), [12]) + + def test_an_issues_url_shown_as_text_goes_where_its_path_names(self) -> None: + # As in a link, nothing but a slash, a query, or a fragment may follow + # the number, but for the punctuation that ends a sentence. + url = f"https://github.com/{REPOSITORY}/issues/12" + for suffix, expected in ( + ("", [12]), + ("/", [12]), + ("/?q=1#x", [12]), + ("#x).", [12]), + ("),", [12]), + ("/../../../openvmm/issues/123", []), + ("/x", []), + ("./../../openvmm/issues/123", []), + ("\\..\\..\\..\\openvmm\\issues\\123", []), + ): + for after in ("", " and more"): + with self.subTest(suffix=suffix, after=after): + rendered = paragraph(f"Refs {url}{suffix}{after}") + self.assertEqual(numbers(rendered), expected) + + def test_no_reference_spans_code_or_blocks(self) -> None: + for rendered in ( + paragraph(f'Fixes #8 {issue_link(12)}'), + f'

Fixes

\n{paragraph(issue_link(12))}', + f'
    \n
  1. Refs
  2. \n
  3. {issue_link(12)}
  4. \n
', + f"
\n{paragraph('Part of')}\n
\n" + f"
\n{paragraph(issue_link(12))}\n
", + '\n\n\n' + f"\n\n\n\n" + "
Fixes{issue_link(12)}
", + f"
Fixes\n{paragraph(issue_link(12))}\n" + "
", + ): + with self.subTest(rendered=rendered): + self.assertEqual(numbers(rendered), []) + + def test_a_reference_within_a_line_of_text_counts(self) -> None: + # Emphasis, line breaks, pictures, ruby, and a task's checkbox end no + # line, and GitHub drops comments. + for rendered in ( + paragraph(f"Refs {issue_link(12)}"), + paragraph(f"Fixes
{issue_link(12)}"), + paragraph( + 'Fixes ' + '' + f" {issue_link(12)}" + ), + paragraph(f"Part of {issue_link(12)}x"), + '
    \n
  • ' + ' ' + f"Fixes {issue_link(12)}
  • \n
", + paragraph(f"Fixes {issue_link(12)}"), + ): + with self.subTest(rendered=rendered): + self.assertEqual(numbers(rendered), [12]) + + def test_numbers_come_in_order_once_each(self) -> None: + rendered = paragraph( + f"Part of {issue_link(3)}
\n" + f"Refs {issue_link(2)}, and fixes {issue_link(3)}." + ) + self.assertEqual(numbers(rendered), [3, 2]) + + +Call = tuple[str, str] + + +class FakeGitHub: + """A repository as gh api reports it, which the calls change.""" + + def __init__(self) -> None: + self.pulls: dict[int, dict[str, object]] = {} + self.issues: set[int] = set() + self.links: dict[int, list[tuple[int, str]]] = {} + self.labels: set[str] = set() + self.comments: list[dict[str, object]] = [] + self.failures: dict[Call, str] = {} + # GitHub's HTML for a description; any other renders as one paragraph. + self.rendered: dict[str, str] = {} + self.renders: list[object] = [] + # Labels that another run creates just before this one tries to. + self.racing: set[str] = set() + self.calls: list[Call] = [] + + def pull( + self, + number: int = 7, + *, + body: str | None = "", + author: str = "someone", + state: str = "open", + labels: Sequence[str] = (), + ) -> None: + self.pulls[number] = { + "number": number, + "state": state, + "user": {"login": author}, + "body": body, + "labels": [{"name": label} for label in labels], + "base": {"ref": "feature", "repo": {"default_branch": "dev"}}, + } + + def comment(self, author: str | None, body: str) -> int: + identifier = 100 + len(self.comments) + self.comments.append({"id": identifier, "author": author, "body": body}) + return identifier + + def writes(self) -> list[Call]: + return [ + (method, endpoint) + for method, endpoint in self.calls + if method != "GET" and endpoint not in ("graphql", "markdown") + ] + + def labelled(self, number: int = 7) -> list[str]: + labels = cast(list[dict[str, str]], self.pulls[number]["labels"]) + return [label["name"] for label in labels] + + def __call__( + self, arguments: Sequence[str], stdin: str | None + ) -> subprocess.CompletedProcess[str]: + method = arguments[arguments.index("--method") + 1] + endpoint = next( + argument + for argument in arguments[2:] + if argument.startswith("repos/") or argument in ("graphql", "markdown") + ) + self.calls.append((method, endpoint)) + if (method, endpoint) in self.failures: + return self.answer(arguments, 1, "", self.failures[(method, endpoint)]) + if endpoint == "markdown": + request = cast(dict[str, str], json.loads(stdin or "{}")) + self.renders.append(request) + text = request["text"] + rendered = self.rendered.get(text, paragraph(html.escape(text))) + return self.answer(arguments, 0, rendered) + if endpoint == "graphql": + [field] = [ + argument for argument in arguments if argument.startswith("number=") + ] + nodes = [ + {"number": issue, "repository": {"nameWithOwner": source}} + for issue, source in self.links.get(int(field.split("=")[1]), []) + ] + data = {"pullRequest": {"closingIssuesReferences": {"nodes": nodes}}} + return self.answer(arguments, 0, json.dumps({"data": {"repository": data}})) + path = endpoint.removeprefix(f"repos/{REPOSITORY}/").split("/") + payload = cast(dict[str, object], json.loads(stdin or "{}")) + match method, path: + case "GET", ["pulls", number]: + return self.answer(arguments, 0, json.dumps(self.pulls[int(number)])) + case "GET", ["issues", number] if int(number) in self.issues: + source = f"https://api.github.com/repos/{REPOSITORY}" + issue = {"number": int(number), "repository_url": source} + return self.answer(arguments, 0, json.dumps(issue)) + case "GET", ["issues", number] if int(number) in self.pulls: + pull: dict[str, object] = {"number": int(number), "pull_request": {}} + return self.answer(arguments, 0, json.dumps(pull)) + case "GET", ["labels", name] if name in self.labels: + return self.answer(arguments, 0, json.dumps({"name": name})) + case "POST", ["labels"]: + if payload["name"] in self.labels | self.racing: + self.labels.add(cast(str, payload["name"])) + return self.answer(arguments, 1, "", "HTTP 422: already_exists") + self.labels.add(cast(str, payload["name"])) + case "POST", ["issues", number, "labels"]: + for name in cast(list[str], payload["labels"]): + if name not in self.labelled(int(number)): + labels = self.pulls[int(number)]["labels"] + cast(list[object], labels).append({"name": name}) + case "DELETE", ["issues", number, "labels", name]: + if name not in self.labelled(int(number)): + return self.answer(arguments, 1, "", "gh: Not Found (HTTP 404)") + self.pulls[int(number)]["labels"] = [ + {"name": label} + for label in self.labelled(int(number)) + if label != name + ] + case "GET", ["issues", _, "comments"]: + # What the --jq filter prints: one JSON object a line. + listing = "".join(f"{json.dumps(item)}\n" for item in self.comments) + return self.answer(arguments, 0, listing) + case "POST", ["issues", _, "comments"]: + self.comment(link.COMMENTER, cast(str, payload["body"])) + case "PATCH", ["issues", "comments", identifier]: + for item in self.comments: + if item["id"] == int(identifier): + item["body"] = payload["body"] + case _: + return self.answer(arguments, 1, "", "gh: Not Found (HTTP 404)") + return self.answer(arguments, 0, "{}") + + @staticmethod + def answer( + arguments: Sequence[str], status: int, stdout: str, stderr: str = "" + ) -> subprocess.CompletedProcess[str]: + return subprocess.CompletedProcess(list(arguments), status, stdout, stderr) + + +class CheckTests(unittest.TestCase): + def setUp(self) -> None: + self.github = FakeGitHub() + self.github.issues.add(12) + self.github.pull(8) + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.summary = Path(directory.name) / "summary.md" + self.output = "" + + def check(self, *options: str) -> int: + self.github.calls.clear() + self.summary.write_text("", encoding="utf-8") + stdout = io.StringIO() + with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stdout): + code = link.main( + [ + "--repository", + REPOSITORY, + "--summary", + str(self.summary), + *options, + "7", + ], + run=self.github, + ) + self.output = stdout.getvalue() + return code + + def ours(self) -> list[str]: + return [ + cast(str, item["body"]) + for item in self.github.comments + if item["author"] == link.COMMENTER + ] + + def test_githubs_link_alone_passes(self) -> None: + self.github.pull(body=None) + self.github.links[7] = [(12, REPOSITORY)] + self.assertEqual(self.check(), link.PASSED) + self.assertNotIn(("GET", f"repos/{REPOSITORY}/issues/12"), self.github.calls) + self.assertEqual(self.github.renders, []) + self.assertEqual(self.github.writes(), []) + self.assertIn("GitHub links it to #12", self.summary.read_text("utf-8")) + + def test_the_description_counts_as_github_renders_it(self) -> None: + # The Markdown references #8 too, which GitHub shows as code. + body = "`Fixes #8` and refs #12" + self.github.rendered[body] = paragraph( + f'Fixes #8 and refs {issue_link(12)}' + ) + self.github.pull(body=body) + self.assertEqual(self.check(), link.PASSED) + self.assertEqual( + self.github.renders, [{"text": body, "mode": "gfm", "context": REPOSITORY}] + ) + self.assertNotIn(("GET", f"repos/{REPOSITORY}/issues/8"), self.github.calls) + self.assertIn("references: #12 (issue)", self.summary.read_text("utf-8")) + + def test_a_link_to_another_repositorys_issue_does_not_count(self) -> None: + self.github.pull() + self.github.links[7] = [(12, "microsoft/openvmm")] + self.assertEqual(self.check(), link.FLAGGED) + + def test_the_description_alone_passes_whatever_the_base(self) -> None: + # GitHub links no issue to a pull request whose base is not the + # default branch, nor for Part of or Refs. + self.github.pull(body="Fixes #12") + self.assertEqual(self.check(), link.PASSED) + self.assertIn(("GET", f"repos/{REPOSITORY}/issues/12"), self.github.calls) + self.assertEqual(self.github.writes(), []) + + def test_a_pull_request_or_a_missing_number_does_not_count(self) -> None: + for body in ("Refs #8", "Fixes #99"): + with self.subTest(body=body): + self.github.pull(body=body) + self.assertEqual(self.check("--dry-run"), link.FLAGGED) + self.assertIn("#99 (missing)", self.summary.read_text("utf-8")) + + def test_an_issue_after_a_pull_request_counts(self) -> None: + self.github.pull(body="Stacked on #8.\nRefs #8\nPart of #12") + self.assertEqual(self.check(), link.PASSED) + self.assertIn("#8 (pull request), #12 (issue)", self.summary.read_text("utf-8")) + + def test_a_description_makes_a_bounded_number_of_lookups(self) -> None: + missing = range(100, 100 + link.LOOKUPS + 2) + self.github.pull( + body="".join(f"Refs #{number}\n" for number in missing) + "Part of #12" + ) + self.assertEqual(self.check(), link.FLAGGED) + lookups = [ + endpoint + for method, endpoint in self.github.calls + if method == "GET" and re.fullmatch(r".*/issues/[0-9]+", endpoint) + ] + self.assertEqual(len(lookups), link.LOOKUPS) + report = self.summary.read_text("utf-8") + self.assertIn(f"none of the first {link.LOOKUPS} numbers", report) + self.assertIn("#12 (not looked up)", report) + [comment] = self.ours() + self.assertIn(f"None of the first {link.LOOKUPS} numbers", comment) + + def test_exempt_pull_requests_pass_without_a_label_or_a_comment(self) -> None: + for author, labels in ( + ("dependabot[bot]", ()), + ("github-actions[bot]", ()), + ("someone", ("No-Issue",)), + ): + with self.subTest(author=author, labels=labels): + self.github.pull(author=author, labels=labels) + self.assertEqual(self.check(), link.PASSED) + self.assertNotIn(("POST", "graphql"), self.github.calls) + self.assertEqual(self.github.writes(), []) + + def test_a_closed_pull_request_is_left_alone(self) -> None: + self.github.pull(state="closed", labels=[link.NEEDS_ISSUE]) + self.github.comment(link.COMMENTER, f"{link.COMMENT_MARKER}\nold") + self.assertEqual(self.check(), link.PASSED) + self.assertEqual(self.github.calls, [("GET", f"repos/{REPOSITORY}/pulls/7")]) + + def test_a_flagged_pull_request_passes_once_its_description_is_fixed( + self, + ) -> None: + self.github.pull(body="Stacked on #8.") + self.assertEqual(self.check(), link.FLAGGED) + self.assertEqual(self.github.labels, {link.NEEDS_ISSUE, link.NO_ISSUE}) + self.assertEqual(self.github.labelled(), [link.NEEDS_ISSUE]) + [flagged] = self.ours() + self.assertTrue(flagged.startswith(link.COMMENT_MARKER)) + # Another run of the same description changes nothing. + self.assertEqual(self.check(), link.FLAGGED) + self.assertEqual(self.github.writes(), []) + # An edit of the description passes, with no push. + self.github.pull( + body="Part of #12\n\nStacked on #8.", labels=[link.NEEDS_ISSUE] + ) + self.assertEqual(self.check(), link.PASSED) + self.assertEqual(self.github.labelled(), []) + [passed] = self.ours() + self.assertTrue(passed.startswith(link.COMMENT_MARKER)) + self.assertIn("references #12", passed) + # So does an exemption. + self.github.pull(labels=[link.NEEDS_ISSUE, link.NO_ISSUE]) + self.assertEqual(self.check(), link.PASSED) + self.assertEqual(self.github.labelled(), [link.NO_ISSUE]) + self.assertIn("labelled `no-issue`", self.ours()[0]) + self.assertEqual(len(self.github.comments), 1) + + def test_a_flagged_pull_request_recreates_a_deleted_label(self) -> None: + self.github.labels = {link.NEEDS_ISSUE} + self.github.pull(labels=[link.NEEDS_ISSUE]) + self.github.comment( + link.COMMENTER, + link.comment_body( + link.Verdict("unlinked", "its description references no issue"), + REPOSITORY, + "dev", + ), + ) + self.assertEqual(self.check(), link.FLAGGED) + self.assertEqual(self.github.labels, {link.NEEDS_ISSUE, link.NO_ISSUE}) + self.assertEqual(self.github.writes(), [("POST", f"repos/{REPOSITORY}/labels")]) + + def test_a_label_that_another_run_creates_first_is_no_error(self) -> None: + self.github.pull() + self.github.racing = {link.NO_ISSUE} + self.assertEqual(self.check(), link.FLAGGED) + self.assertEqual(self.github.labels, {link.NEEDS_ISSUE, link.NO_ISSUE}) + self.assertIn(link.NEEDS_ISSUE, self.github.labelled()) + report = self.summary.read_text("utf-8") + self.assertIn("created the `needs-issue` label", report) + self.assertNotIn("created the `no-issue` label", report) + + def test_a_label_that_github_rejects_fails_the_check(self) -> None: + self.github.labels = {link.NEEDS_ISSUE} + self.github.pull() + self.github.failures = { + ("POST", f"repos/{REPOSITORY}/labels"): "gh: Validation Failed (HTTP 422)" + } + self.assertEqual(self.check(), link.FAILED) + self.assertEqual(self.github.writes(), [("POST", f"repos/{REPOSITORY}/labels")]) + self.assertIn("rejected the `no-issue` label", self.summary.read_text("utf-8")) + + def test_the_comment_tells_the_author_what_to_do(self) -> None: + self.github.pull() + self.check() + [comment] = self.ours() + for text in ( + "`Fixes #N`", + "`Closes #N`", + "`Part of #N`", + "`Refs #N`", + "first line of the description", + "open one first", + "Editing the description runs this check again", + "`no-issue`", + "https://github.com/microsoft/nvx/blob/dev/doc/contribute.md" + "#commits-and-pull-requests", + ): + self.assertIn(text, comment) + + def test_a_comment_that_quotes_the_marker_is_never_edited(self) -> None: + quote = f"{link.COMMENT_MARKER} quoted by someone" + self.github.comment("someone", quote) + self.github.comment(link.COMMENTER, "a comment of another workflow") + self.github.pull() + self.assertEqual(self.check(), link.FLAGGED) + self.assertEqual(self.github.comments[0]["body"], quote) + self.assertEqual(len(self.ours()), 2) + self.github.pull(body="Fixes #12") + self.assertEqual(self.check(), link.PASSED) + self.assertEqual(self.github.comments[0]["body"], quote) + self.assertEqual(self.ours()[0], "a comment of another workflow") + self.assertIn("references #12", self.ours()[1]) + + def test_a_comment_without_an_author_is_no_error(self) -> None: + # GitHub reports no author for the comments of a deleted account. + ghost = f"{link.COMMENT_MARKER} from a deleted account" + self.github.comment(None, ghost) + self.github.pull() + self.assertEqual(self.check(), link.FLAGGED) + self.assertEqual(len(self.ours()), 1) + self.github.pull(body="Fixes #12") + self.assertEqual(self.check(), link.PASSED) + self.assertEqual(self.github.comments[0]["body"], ghost) + self.assertIn("references #12", self.ours()[0]) + + def test_an_api_error_changes_nothing(self) -> None: + self.github.pull(body="Refs #12", labels=[link.NEEDS_ISSUE]) + self.github.comment(link.COMMENTER, f"{link.COMMENT_MARKER}\nold") + reads = [ + ("GET", f"repos/{REPOSITORY}/pulls/7"), + ("POST", "markdown"), + ("POST", "graphql"), + ("GET", f"repos/{REPOSITORY}/issues/12"), + ("GET", f"repos/{REPOSITORY}/issues/7/comments"), + ] + for read in reads: + with self.subTest(read=read): + self.github.failures = {read: "gh: Bad Gateway (HTTP 502)"} + self.assertEqual(self.check(), link.FAILED) + self.assertIn(read, self.github.calls) + self.assertEqual(self.github.writes(), []) + self.assertIn("HTTP 502", self.summary.read_text("utf-8")) + self.github.pull() + self.github.failures = { + ("GET", f"repos/{REPOSITORY}/labels/needs-issue"): "HTTP 403" + } + self.assertEqual(self.check(), link.FAILED) + self.assertEqual(self.github.writes(), []) + + def test_the_report_never_echoes_the_description(self) -> None: + self.github.pull(body="A SENTINEL description. Refs #8") + self.assertEqual(self.check(), link.FLAGGED) + report = self.summary.read_text("utf-8") + self.assertIn("Issue link: unlinked", report) + self.assertIn("#8 (pull request)", report) + for text in (report, self.output, *self.ours()): + self.assertNotIn("SENTINEL", text) + + def test_a_dry_run_changes_nothing(self) -> None: + self.github.pull() + self.assertEqual(self.check("--dry-run"), link.FLAGGED) + self.assertEqual(self.github.writes(), []) + self.assertNotIn( + ("GET", f"repos/{REPOSITORY}/issues/7/comments"), self.github.calls + ) + + def test_gh_reads_and_writes_utf_8_whatever_the_locale(self) -> None: + sent = link._run( + [sys.executable, "-c", "import sys; print(sys.stdin.buffer.read().hex())"], + "\u00e9", + ) + self.assertEqual(sent.stdout.strip(), "c3a9") + received = link._run( + [ + sys.executable, + "-c", + "import sys; sys.stdout.buffer.write(b'\\xc3\\xa9')", + ], + None, + ) + self.assertEqual(received.stdout, "\u00e9") + + +class WorkflowTests(unittest.TestCase): + def setUp(self) -> None: + self.text = (WORKFLOWS / "issue-link.yml").read_text(encoding="utf-8") + self.workflow = cast(dict[object, object], yaml.safe_load(self.text)) + jobs = cast(dict[str, dict[str, object]], self.workflow["jobs"]) + self.assertEqual(list(jobs), ["check"]) + self.job = jobs["check"] + self.steps = cast(list[dict[str, object]], self.job["steps"]) + + def test_every_event_that_can_change_the_verdict_checks_again(self) -> None: + self.assertEqual(self.workflow["name"], "Issue link") + self.assertEqual( + self.job["name"], "Check that the pull request references an issue" + ) + # YAML 1.1 reads the `on` key as True. + self.assertEqual( + self.workflow[True], + { + "pull_request_target": { + "types": [ + "opened", + "reopened", + "synchronize", + "edited", + "labeled", + "unlabeled", + ] + } + }, + ) + # A run whose job is skipped replaces the result of the run before it. + self.assertNotIn("if", self.job) + self.assertTrue(all("if" not in step for step in self.steps)) + + def test_the_default_branchs_script_runs_with_a_token_that_writes_no_issue( + self, + ) -> None: + self.assertEqual(self.workflow["permissions"], {}) + self.assertEqual( + self.job["permissions"], {"contents": "read", "pull-requests": "write"} + ) + checkout, check = self.steps + test_changes = yaml.safe_load( + (WORKFLOWS / "test-changes.yml").read_text(encoding="utf-8") + ) + [pinned] = [ + step["uses"] + for step in test_changes["jobs"]["flag"]["steps"] + if str(step.get("uses", "")).startswith("actions/checkout@") + ] + self.assertEqual(checkout["uses"], pinned) + self.assertEqual( + checkout["with"], + { + "ref": "${{ github.event.repository.default_branch }}", + "persist-credentials": False, + }, + ) + self.assertEqual( + str(check["run"]).split(), + [ + "python3", + "scripts/check_issue_link.py", + "--repository", + '"${GITHUB_REPOSITORY}"', + "--summary", + '"${GITHUB_STEP_SUMMARY}"', + '"${NUMBER}"', + ], + ) + + def test_only_the_pull_requests_number_reaches_the_job(self) -> None: + check = self.steps[1] + self.assertEqual( + check["env"], + { + "GH_TOKEN": "${{ github.token }}", + "NUMBER": "${{ github.event.pull_request.number }}", + }, + ) + for step in self.steps: + self.assertNotIn("${{", str(step.get("run", ""))) + self.assertEqual( + sorted(set(self._event_fields())), ["github.event.pull_request.number"] + ) + + def test_runs_of_one_pull_request_go_one_at_a_time(self) -> None: + self.assertNotIn("concurrency", self.workflow) + self.assertEqual( + self.job["concurrency"], + { + "group": "issue-link-${{ github.event.pull_request.number }}", + "cancel-in-progress": False, + }, + ) + self.assertEqual(self.job["timeout-minutes"], 5) + + def _event_fields(self) -> list[str]: + """The fields of the pull request that the workflow reads.""" + fields: list[str] = [] + for line in self.text.splitlines(): + if not line.lstrip().startswith("#"): + start = line.find("github.event.pull_request.") + while start != -1: + end = start + while end < len(line) and ( + line[end].isalnum() or line[end] in "._" + ): + end += 1 + fields.append(line[start:end]) + start = line.find("github.event.pull_request.", end) + return fields + + +if __name__ == "__main__": + unittest.main()