diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index a7a3bb587..20e947480 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -10,6 +10,14 @@ on: permissions: contents: read +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (push to main, a release tag, a manual run) gets a group of its own: it is neither + # cancelled nor replaced while queued, so a main run always finishes and saves the dependency + # cache, and a release run is never cancelled. + group: workspace-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: native: name: Workspace @@ -39,6 +47,7 @@ jobs: printf 'CRAFT_PSD_CORPUS=%s\n' "$GITHUB_WORKSPACE/$corpus_fetcher/corpus" >> "$GITHUB_ENV" printf 'CRAFT_PDF_TEST_FONT_DIR=%s\n' "$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" command: | + python3 scripts/test-workspace-concurrency.py cargo fmt --check cargo clippy --workspace --all-targets --locked -- -D warnings cargo clippy --workspace --all-targets --all-features --locked -- -D warnings diff --git a/scripts/test-workspace-concurrency.py b/scripts/test-workspace-concurrency.py new file mode 100644 index 000000000..96bfae304 --- /dev/null +++ b/scripts/test-workspace-concurrency.py @@ -0,0 +1,162 @@ +#!/usr/bin/env python3 +"""Check the Workspace workflow's pull-request-only cancellation policy. + +The policy is the top-level `concurrency` block of .github/workflows/workspace.yml. This script +reads those fields, requires the documented expression shapes, and checks which group each event +would be given. The rest of the workflow is left to diff review, not frozen here. + +Use --workflow PATH to read a baseline or a deliberately wrong variant without touching this +checkout. +""" + +import argparse +import re +import sys +import unittest +from pathlib import Path + +try: # cross-check only; the reader below is what a plain `python3` run needs + import yaml +except ImportError: + yaml = None + +DEFAULT_WORKFLOW = Path(__file__).resolve().parent.parent / ".github" / "workflows" / "workspace.yml" +PULL_REQUEST, PUSH, DISPATCH = "pull_request", "push", "workflow_dispatch" + +# The two shapes this policy may use. GitHub reads `a && b || c` as "b, or c when a is false"; these +# patterns are the whole of that expression language this script understands, so a reworded policy +# has to be reworded here too, on purpose. github.ref, never github.head_ref or github.sha. +GROUP_SHAPE = re.compile( + r"(?P[A-Za-z0-9._-]+)-\$\{\{\s*github\.event_name\s*==\s*'(?P[a-z_]+)'\s*" + r"&&\s*github\.ref\s*\|\|\s*github\.run_id\s*\}\}" +) +CANCEL_SHAPE = re.compile(r"\$\{\{\s*github\.event_name\s*==\s*'(?P[a-z_]+)'\s*\}\}") + + +def read_concurrency(text): + """The top-level `concurrency` mapping. A deliberately limited reader: two-space fields.""" + lines = text.splitlines() + starts = [index for index, line in enumerate(lines) if line.startswith("concurrency:")] + if len(starts) != 1: + raise AssertionError(f"expected one top-level concurrency block, found {len(starts)}") + header = lines[starts[0]].partition("#")[0].strip() + if header != "concurrency:": + # `concurrency: |` and `concurrency: some-string` are scalars, not a mapping. Reading the + # lines under one as fields would let a workflow that is not this policy pass every check. + raise AssertionError(f"concurrency must be a mapping, not a scalar: {lines[starts[0]]!r}") + fields = {} + for line in lines[starts[0] + 1:]: + stripped = line.strip() + if stripped and not line.startswith(" "): + break # the next top-level key + if not stripped or stripped.startswith("#"): + continue + if not line.startswith(" ") or line.startswith(" "): + raise AssertionError(f"unexpected indentation under concurrency: {line!r}") + key, separator, value = stripped.partition(":") + if not separator: + raise AssertionError(f"not a field of concurrency: {line!r}") + fields[key.strip()] = value.strip() + return fields + + +def pull_request(number, run_id): + # github.ref for a pull request is refs/pull//merge: the PR number, never the branch name. + return (PULL_REQUEST, f"refs/pull/{number}/merge", run_id) + + +def other_run(event_name, ref, run_id): + return (event_name, ref, run_id) + + +MAIN, TAG = ("refs/heads/main", "refs/tags/v1.2.3") +SAME_GROUP = [ + ("a newer commit on the same pull request", pull_request(1316, 43599251877), pull_request(1316, 43600899878)), + ("a rerun of one main run", other_run(PUSH, MAIN, 7001), other_run(PUSH, MAIN, 7001)), +] +DIFFERENT_GROUPS = [ + ("two pull requests", pull_request(1316, 1), pull_request(1317, 1)), + ("the same branch name in two forks", pull_request(1316, 2), pull_request(1400, 2)), + ("two pushes to main", other_run(PUSH, MAIN, 3), other_run(PUSH, MAIN, 4)), + ("two release tag runs", other_run(PUSH, TAG, 5), other_run(PUSH, TAG, 6)), + ("two manual runs", other_run(DISPATCH, MAIN, 7), other_run(DISPATCH, MAIN, 8)), + ("a main push and a pull request", other_run(PUSH, MAIN, 9), pull_request(1316, 9)), + ("a release tag and a pull request", other_run(PUSH, TAG, 10), pull_request(1316, 10)), +] +CANCELLATION = [ + ("a push supersedes the previous run of its pull request", pull_request(1316, 11), True), + ("a push to main is never cancelled", other_run(PUSH, MAIN, 12), False), + ("a release tag run is never cancelled", other_run(PUSH, TAG, 13), False), + ("a manual run is never cancelled", other_run(DISPATCH, MAIN, 14), False), +] + + +class ConcurrencyTests(unittest.TestCase): + workflow = DEFAULT_WORKFLOW + + @classmethod + def setUpClass(cls): + cls.text = cls.workflow.read_text() + cls.fields = read_concurrency(cls.text) + cls.group_shape = GROUP_SHAPE.fullmatch(cls.fields.get("group", "")) + cls.cancel_shape = CANCEL_SHAPE.fullmatch(cls.fields.get("cancel-in-progress", "")) + if not cls.group_shape or not cls.cancel_shape: + raise AssertionError(f"the concurrency fields are not the documented shapes: {cls.fields}") + + def cancels(self, event_name): + return event_name == self.cancel_shape["event"] + + def group(self, event_name, ref, run_id): + return self.group_shape["prefix"] + "-" + (ref if event_name == self.group_shape["event"] else str(run_id)) + + def test_policy_is_the_two_documented_fields(self): + self.assertEqual(sorted(self.fields), ["cancel-in-progress", "group"]) + self.assertEqual(self.group_shape["prefix"], "workspace") + self.assertEqual(self.group_shape["event"], PULL_REQUEST) + self.assertEqual(self.cancel_shape["event"], PULL_REQUEST) + + def test_a_scalar_concurrency_value_is_not_read_as_a_mapping(self): + cases = { + "a block scalar": "concurrency: |\n group: workspace-x\n cancel-in-progress: true\n", + "a plain scalar": "concurrency: workspace-x\njobs: {}\n", + } + for description, text in cases.items(): + with self.subTest(description): + with self.assertRaises(AssertionError): + read_concurrency(text) + + def test_one_group_per_pull_request_and_run(self): + for description, first, second in SAME_GROUP: + with self.subTest(description): + self.assertEqual(self.group(*first), self.group(*second), description) + for description, first, second in DIFFERENT_GROUPS: + with self.subTest(description): + self.assertNotEqual(self.group(*first), self.group(*second), description) + + def test_only_a_pull_request_cancels(self): + for description, context, expected in CANCELLATION: + with self.subTest(description): + self.assertEqual(self.cancels(context[0]), expected, description) + + def test_pyyaml_reads_the_same_fields(self): + if yaml is None: + self.skipTest("PyYAML is not installed; the limited reader above ran alone") + document = yaml.load(self.text, Loader=yaml.BaseLoader) # BaseLoader keeps `on:` a string + self.assertEqual(document["concurrency"], self.fields) + + def test_no_per_job_concurrency_is_added(self): + indented = [line for line in self.text.splitlines() + if line.strip().startswith("concurrency:") and not line.startswith("concurrency:")] + self.assertEqual(indented, [], "the policy belongs to the workflow, not to one job") + + +def main(): + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument("--workflow", type=Path, default=DEFAULT_WORKFLOW, help="workflow to read (default: %(default)s)") + arguments, remaining = parser.parse_known_args() + ConcurrencyTests.workflow = arguments.workflow + unittest.main(argv=[sys.argv[0], *remaining]) + + +if __name__ == "__main__": + main() diff --git a/sonar-project.properties b/sonar-project.properties index f30f3ae5f..c2be7b192 100644 --- a/sonar-project.properties +++ b/sonar-project.properties @@ -7,7 +7,11 @@ sonar.organization=storytold # *_tests.rs), which includes the browser fault-injection fixtures in crates/platform/tests. sonar.sources=. sonar.tests=. -sonar.test.inclusions=**/tests/**,**/tests.rs,**/*_tests.rs +# scripts/test-workspace-concurrency.py is a unit-test module for the Workspace workflow's +# cancellation policy: its unittest cases read a workflow and assert on it, so it is test +# code, analysed as a test and still linted, indexed and reported, not counted as production +# code that needs coverage. Its name is listed exactly, so no other script is classified. +sonar.test.inclusions=**/tests/**,**/tests.rs,**/*_tests.rs,scripts/test-workspace-concurrency.py # Codec constant tables are transcribed from the format specifications; their repeated rows are # data, not copy-pasted logic.