from __future__ import annotations
import re
import unittest
from pathlib import Path
WORKFLOW = Path(__file__).resolve().parent.parent / ".github" / "workflows" / "release.yml"
STATUS_FUNCTIONS = ("success(", "failure(", "cancelled(", "always(")
IMPLICIT_SUCCESS_ALLOWED = {
"resolve-release-ref": "root job, no needs",
"verify-release-ref": "implicit success() over resolve-release-ref is what we want",
"feature-020-v11-gate": "implicit success() plus the phase check; must not run if verification failed",
"gate-release-ref": "always() by design; its result checks live in the step body",
}
STEP_BODY_RESULT_CHECKS = {
"gate-release-ref": "checks VERIFY_RESULT/FEATURE_GATE_RESULT in the step body",
}
JOB_RE = re.compile(r"^ ([A-Za-z0-9_-]+):\s*$")
NEEDS_ITEM_RE = re.compile(r"^ - ([A-Za-z0-9_-]+)\s*$")
IF_RE = re.compile(r"^ if:\s*(.+?)\s*$")
def parse_jobs(text: str) -> dict[str, dict[str, object]]:
jobs: dict[str, dict[str, object]] = {}
current: str | None = None
in_needs = False
in_jobs = False
for line in text.splitlines():
if line.startswith("jobs:"):
in_jobs = True
continue
if not in_jobs:
continue
if line and not line.startswith(" ") and not line.startswith("#"):
break
job = JOB_RE.match(line)
if job:
current = job.group(1)
jobs[current] = {"needs": [], "if": None}
in_needs = False
continue
if current is None:
continue
if line.strip() == "needs:":
in_needs = True
continue
if in_needs:
item = NEEDS_ITEM_RE.match(line)
if item:
jobs[current]["needs"].append(item.group(1)) continue
in_needs = False
single = re.match(r"^ needs:\s*([A-Za-z0-9_-]+)\s*$", line)
if single:
jobs[current]["needs"] = [single.group(1)]
continue
condition = IF_RE.match(line)
if condition:
jobs[current]["if"] = condition.group(1)
return jobs
class ReleaseWorkflowConditions(unittest.TestCase):
def setUp(self) -> None:
self.assertTrue(WORKFLOW.is_file(), f"missing {WORKFLOW}")
self.jobs = parse_jobs(WORKFLOW.read_text(encoding="utf-8"))
def test_parse_found_the_workflow_shape(self) -> None:
self.assertGreaterEqual(len(self.jobs), 10, f"parsed only {sorted(self.jobs)}")
for required in ("resolve-release-ref", "gate-release-ref", "prepare-release", "cargo-publish"):
self.assertIn(required, self.jobs)
self.assertEqual(self.jobs["verify-release-ref"]["needs"], ["resolve-release-ref"])
self.assertGreaterEqual(len(self.jobs["cargo-publish"]["needs"]), 5)
@staticmethod
def _requires_success(condition: str, dependency: str) -> bool:
return any(
term in condition
for term in (
f"needs.{dependency}.result == 'success'",
f"needs['{dependency}'].result == 'success'",
)
)
def test_status_function_jobs_assert_every_dependency_succeeded(self) -> None:
checked = 0
for name, job in sorted(self.jobs.items()):
condition = job["if"]
if not isinstance(condition, str) or not any(f in condition for f in STATUS_FUNCTIONS):
continue
checked += 1
if name in STEP_BODY_RESULT_CHECKS:
continue
for dependency in job["needs"]: self.assertTrue(
self._requires_success(condition, dependency),
f"job {name!r} names a status function, which discards the implicit "
f"success(), but never requires needs.{dependency}.result == 'success' "
f"-- it will run when {dependency!r} fails",
)
self.assertGreaterEqual(
checked, 6, "expected the six post-gate jobs to name a status function"
)
def test_conditions_never_reference_a_job_they_do_not_need(self) -> None:
for name, job in sorted(self.jobs.items()):
condition = job["if"]
if not isinstance(condition, str):
continue
referenced = set(re.findall(r"needs\.([A-Za-z0-9_-]+)\.", condition))
referenced |= set(re.findall(r"needs\['([A-Za-z0-9_-]+)'\]", condition))
declared = set(job["needs"]) stray = sorted(referenced - declared)
self.assertEqual(
stray,
[],
f"job {name!r} references {stray} which are not in its needs; those "
f"expressions evaluate to null and silently block the job forever",
)
def test_jobs_without_a_status_function_are_deliberate(self) -> None:
for name, job in sorted(self.jobs.items()):
condition = job["if"]
if isinstance(condition, str) and any(f in condition for f in STATUS_FUNCTIONS):
continue
self.assertIn(
name,
IMPLICIT_SUCCESS_ALLOWED,
f"job {name!r} relies on the implicit success() wrap; if anything it needs "
f"is skipped it silently skips too. Add a status function plus explicit "
f"result checks, or record why here.",
)
if __name__ == "__main__":
unittest.main()