From 2aa39eb831290e7ac44a3c9a09b8ffa8ffd2af48 Mon Sep 17 00:00:00 2001 From: "richmond-avenal[bot]" <323733923+richmond-avenal[bot]@users.noreply.github.com> Date: Wed, 9 Sep 2026 06:14:13 +0000 Subject: [PATCH 1/6] feat: filter pattern matcher pinned to GitHub's cheat sheet GitHub's ? and + are regex quantifiers on the preceding character, not glob wildcards, so fnmatch is the wrong tool: *.jsx? must not match page.jsz. Every row of both cheat sheet tables is a test. --- src/deadtrigger/pattern.py | 172 +++++++++++++++++++++++++++++++++ tests/test_pattern.py | 190 +++++++++++++++++++++++++++++++++++++ 2 files changed, 362 insertions(+) create mode 100644 src/deadtrigger/pattern.py create mode 100644 tests/test_pattern.py diff --git a/src/deadtrigger/pattern.py b/src/deadtrigger/pattern.py new file mode 100644 index 0000000..41b40fe --- /dev/null +++ b/src/deadtrigger/pattern.py @@ -0,0 +1,172 @@ +"""GitHub Actions filter patterns, translated to regular expressions. + +These are the patterns in ``branches``, ``tags``, ``paths`` and their +``-ignore`` variants. They look like shell globs and they are not. From +GitHub's own filter pattern cheat sheet: + + ``?`` Matches zero or one of the **preceding character**. + ``+`` Matches one or more of the **preceding character**. + +That is regex, not glob. In a shell, ``*.jsx?`` means "any character in place +of the ``?``"; to GitHub it means "the ``x`` is optional", which is why the +documented matches for ``*.jsx?`` are ``page.js`` and ``page.jsx`` and not +``page.jsz``. Any implementation that reaches for ``fnmatch`` gets this wrong, +so this module builds the regex by hand. + +The rest: + + ``*`` zero or more characters, but never ``/`` + ``**`` zero or more of any character, ``/`` included + ``[]`` one alphanumeric character from the listed set or ranges + ``!`` at the *start of a pattern only*, negates earlier positives + ``\\`` escapes the next character + +One special case that does not fall out of the rules as written: ``**/README.md`` +is documented as matching ``README.md`` at the repository root. Read literally, +``**`` matching zero characters would leave ``/README.md``, which has a leading +slash and matches nothing. So the ``**/`` sequence has to be able to swallow +its own slash, and is translated as an optional group. +""" + +from __future__ import annotations + +import re +from dataclasses import dataclass + + +class PatternError(ValueError): + """A filter pattern that cannot be translated at all.""" + + +# Ranges in a character class are documented as a-z, A-Z and 0-9 only. +_CLASS_BODY = re.compile(r"\A(?:[0-9A-Za-z]|[0-9]-[0-9]|[a-z]-[a-z]|[A-Z]-[A-Z])+\Z") + + +@dataclass(frozen=True) +class Pattern: + """One filter pattern, compiled and ready to test paths or ref names.""" + + text: str + negated: bool + regex: re.Pattern[str] + + def matches(self, candidate: str) -> bool: + return self.regex.match(candidate) is not None + + @property + def has_wildcard(self) -> bool: + """Whether this pattern can match anything but its own literal text. + + Used to tell a branch filter that names one branch from one that + describes a family of them. An escaped ``\\*`` is a literal star, so + this walks the pattern rather than searching it for characters. + """ + i = 0 + while i < len(self.text): + char = self.text[i] + if char == "\\": + i += 2 + continue + if char in "*?+[": + return True + i += 1 + return False + + +def compile_pattern(text: str) -> Pattern: + """Translate one filter pattern into a Pattern. + + Raises PatternError if the pattern cannot be understood. The caller is + expected to treat that as "this check could not run", not as a pass -- + a matcher that silently ignores the pattern it could not read would + report every filter using it as healthy. + """ + if not isinstance(text, str): + raise PatternError(f"not a string: {text!r}") + + negated = text.startswith("!") + body = text[1:] if negated else text + if not body: + raise PatternError("empty pattern") + + # `parts` holds finished regex atoms. Quantifiers (`?`, `+`) attach to the + # last one, which is why the pieces are kept separate rather than + # concatenated as they are produced. + parts: list[str] = [] + i = 0 + length = len(body) + + while i < length: + char = body[i] + + if char == "\\": + if i + 1 >= length: + raise PatternError(f"trailing backslash: {text!r}") + parts.append(re.escape(body[i + 1])) + i += 2 + continue + + if char == "*": + if body.startswith("**", i): + # `**/` swallows its own slash so that `**/README.md` matches + # a root-level README.md, as documented. + if body.startswith("**/", i): + parts.append("(?:.*/)?") + i += 3 + else: + parts.append(".*") + i += 2 + else: + parts.append("[^/]*") + i += 1 + continue + + if char in "?+": + if not parts: + raise PatternError( + f"{char!r} has nothing before it to repeat: {text!r}" + ) + # `.*?` would be a lazy quantifier rather than "an optional `.*`", + # so the previous atom is wrapped before the quantifier goes on. + parts[-1] = f"(?:{parts[-1]}){'?' if char == '?' else '+'}" + i += 1 + continue + + if char == "[": + end = body.find("]", i + 1) + if end == -1: + raise PatternError(f"unclosed '[': {text!r}") + inner = body[i + 1 : end] + if not _CLASS_BODY.match(inner): + raise PatternError( + f"character class [{inner}] is not alphanumeric characters " + f"or a-z / A-Z / 0-9 ranges: {text!r}" + ) + parts.append(f"[{inner}]") + i = end + 1 + continue + + parts.append(re.escape(char)) + i += 1 + + return Pattern(text=text, negated=negated, regex=re.compile("".join(parts) + r"\Z")) + + +def compile_all(texts: list[str]) -> list[Pattern]: + return [compile_pattern(text) for text in texts] + + +def included(patterns: list[Pattern], candidate: str) -> bool: + """Whether an ordered filter list includes ``candidate``. + + Last match wins, per the docs: "a matching negative pattern after a + positive match will exclude the ref, and a matching positive pattern + after a negative match will include it again". With no match at all, the + ref is not included -- a list of nothing but negations includes nothing, + because there was never anything positive for them to subtract from. + """ + verdict = False + for pattern in patterns: + if pattern.matches(candidate): + verdict = not pattern.negated + return verdict diff --git a/tests/test_pattern.py b/tests/test_pattern.py new file mode 100644 index 0000000..b174921 --- /dev/null +++ b/tests/test_pattern.py @@ -0,0 +1,190 @@ +"""The filter pattern matcher, pinned to GitHub's own cheat sheet. + +CHEAT_SHEET below is transcribed from the "Filter pattern cheat sheet" +section of GitHub's workflow syntax reference: every pattern in the two +tables, with every example match they publish for it. If the matcher stops +agreeing with the documentation, these fail by name. + +The non-matches are mine, not GitHub's, and they are the cases where a +glob-shaped implementation would go wrong. +""" + +from __future__ import annotations + +import pytest + +from deadtrigger.pattern import PatternError, compile_all, compile_pattern, included + +# (pattern, [documented matches], [things it must not match]) +CHEAT_SHEET = [ + # --- Patterns to match branches and tags --- + ("feature/*", ["feature/my-branch", "feature/your-branch"], ["feature/a/b", "feature"]), + ( + "feature/**", + ["feature/beta-a/my-branch", "feature/your-branch", "feature/mona/the/octocat"], + ["features/x", "feature"], + ), + ("main", ["main"], ["mainline", "release/main", "mai"]), + ("releases/mona-the-octocat", ["releases/mona-the-octocat"], ["releases/mona"]), + ("*", ["main", "releases"], ["all/the/branches", "releases/v1"]), + ("**", ["all/the/branches", "every/tag", "main"], []), + ("*feature", ["mona-feature", "feature", "ver-10-feature"], ["feature-x", "a/feature"]), + ("v2*", ["v2", "v2.0", "v2.9"], ["v3", "v", "av2"]), + ( + "v[12].[0-9]+.[0-9]+", + ["v1.10.1", "v2.0.0"], + # v3 is out of the class; the trailing `+` means at least one digit, + # so an empty patch component must not match. + ["v3.0.0", "v1.10.", "v1.a.1"], + ), + # --- Patterns to match file paths --- + ("*", ["README.md", "server.rb"], ["docs/README.md"]), + # The `?` case: `x` is optional, so page.js and page.jsx match. A glob + # implementation reads `?` as "any one character" and lets page.jsz + # through, which is the bug this whole module exists to avoid. + ("*.jsx?", ["page.js", "page.jsx"], ["page.jsz", "page.jsxx", "a/page.js"]), + ("**", ["all/the/files.md"], []), + ("*.js", ["app.js", "index.js"], ["js/index.js", "src/js/app.js"]), + ("**.js", ["index.js", "js/index.js", "src/js/app.js"], ["index.jsx", "index.j"]), + ("docs/*", ["docs/README.md", "docs/file.txt"], ["docs/mona/octocat.txt", "a/docs/x.md"]), + ("docs/**", ["docs/README.md", "docs/mona/octocat.txt"], ["a/docs/x.md", "documents/x"]), + ( + "docs/**/*.md", + ["docs/README.md", "docs/mona/hello-world.md", "docs/a/markdown/file.md"], + ["docs/README.txt", "a/docs/README.md"], + ), + ( + "**/docs/**", + ["docs/hello.md", "dir/docs/my-file.txt", "space/docs/plan/space.doc"], + ["dir/documents/x.md", "docs"], + ), + ("**/README.md", ["README.md", "js/README.md"], ["README.markdown", "a/READMEx.md"]), + ("**/*src/**", ["a/src/app.js", "my-src/code/js/app.js"], ["src", "a/source"]), + ("**/*-post.md", ["my-post.md", "path/their-post.md"], ["post.md", "my-post.markdown"]), + ( + "**/migrate-*.sql", + ["migrate-10909.sql", "db/migrate-v1.0.sql", "db/sept/migrate-v1.sql"], + ["migrate.sql", "db/migrate-v1.sqlx"], + ), +] + + +@pytest.mark.parametrize("text,hits,misses", CHEAT_SHEET, ids=[row[0] for row in CHEAT_SHEET]) +def test_cheat_sheet(text, hits, misses): + pattern = compile_pattern(text) + for candidate in hits: + assert pattern.matches(candidate), f"{text!r} should match {candidate!r}" + for candidate in misses: + assert not pattern.matches(candidate), f"{text!r} should not match {candidate!r}" + + +def test_patterns_are_anchored_at_both_ends(): + """"Path patterns must match the whole path", per the docs.""" + pattern = compile_pattern("docs/file.txt") + assert pattern.matches("docs/file.txt") + assert not pattern.matches("x/docs/file.txt") + assert not pattern.matches("docs/file.txt.bak") + + +def test_dot_is_literal(): + """`.` is an ordinary character here, not regex's any-character.""" + assert not compile_pattern("v1.0").matches("v1x0") + + +def test_plus_needs_at_least_one(): + assert compile_pattern("a+b").matches("ab") + assert compile_pattern("a+b").matches("aaab") + assert not compile_pattern("a+b").matches("b") + + +def test_question_mark_applies_to_a_group_not_a_lazy_quantifier(): + """`**?` must mean "an optional `**`", not a lazily-matched one. + + Translating `?` by appending it to the previous atom would turn `.*` into + `.*?`, which still matches everything and would hide the bug. + """ + pattern = compile_pattern("a**?b") + assert pattern.matches("ab") + assert pattern.matches("a/x/y/b") + + +def test_escaping_makes_a_special_character_literal(): + pattern = compile_pattern(r"release\*") + assert pattern.matches("release*") + assert not pattern.matches("release-1") + assert not pattern.has_wildcard + + +def test_has_wildcard(): + assert not compile_pattern("main").has_wildcard + assert not compile_pattern("releases/mona-the-octocat").has_wildcard + for text in ["v2*", "feature/**", "*.jsx?", "a+b", "v[12].0"]: + assert compile_pattern(text).has_wildcard, text + + +def test_negation_is_recorded_and_stripped(): + pattern = compile_pattern("!feature/*") + assert pattern.negated + assert pattern.matches("feature/x") + + +def test_bang_is_only_special_at_the_start(): + pattern = compile_pattern("wip!") + assert not pattern.negated + assert pattern.matches("wip!") + + +class TestIncluded: + """Ordering rules for a whole filter list.""" + + def test_last_match_wins_negative_after_positive(self): + patterns = compile_all(["releases/**", "!releases/**-alpha"]) + assert included(patterns, "releases/v1") + assert not included(patterns, "releases/v1-alpha") + + def test_last_match_wins_positive_after_negative(self): + patterns = compile_all(["releases/**", "!releases/**-alpha", "releases/v9-alpha"]) + assert included(patterns, "releases/v9-alpha") + + def test_order_matters(self): + """The same two patterns the other way round include everything.""" + patterns = compile_all(["!releases/**-alpha", "releases/**"]) + assert included(patterns, "releases/v1-alpha") + + def test_negations_alone_include_nothing(self): + assert not included(compile_all(["!main"]), "topic") + + def test_no_match_is_not_included(self): + assert not included(compile_all(["main", "release/**"]), "topic") + + +class TestPatternError: + def test_unclosed_class(self): + with pytest.raises(PatternError): + compile_pattern("v[12.0") + + def test_non_alphanumeric_class(self): + """Ranges are documented as a-z / A-Z / 0-9 only.""" + with pytest.raises(PatternError): + compile_pattern("v[!0-9]") + + def test_trailing_backslash(self): + with pytest.raises(PatternError): + compile_pattern("main\\") + + def test_quantifier_with_nothing_to_repeat(self): + with pytest.raises(PatternError): + compile_pattern("?main") + + def test_empty(self): + with pytest.raises(PatternError): + compile_pattern("") + + def test_bare_bang(self): + with pytest.raises(PatternError): + compile_pattern("!") + + def test_non_string(self): + """YAML will hand us an int for `branches: [2]`.""" + with pytest.raises(PatternError): + compile_pattern(2) From b7657e3e51e1aa9da79e5f09024af70f6e75403e Mon Sep 17 00:00:00 2001 From: "richmond-avenal[bot]" <323733923+richmond-avenal[bot]@users.noreply.github.com> Date: Wed, 9 Sep 2026 06:21:42 +0000 Subject: [PATCH 2/6] feat: the checks, the git layer and the CLI Six checks, each one comparing a workflow against the repository it is in rather than against itself: workflow_run names that match no workflow, schedule/workflow_dispatch/workflow_run stranded off the default branch, crons that never come round, literal branch and tag filters naming refs that do not exist, path filters no file can satisfy, and job conditions no declared event can make true. A shallow clone declines the branch checks by name rather than reporting every branch filter in the repository as dead. --- pyproject.toml | 37 +++ src/deadtrigger/__init__.py | 3 + src/deadtrigger/cli.py | 216 +++++++++++++++ src/deadtrigger/core.py | 303 +++++++++++++++++++++ src/deadtrigger/cron.py | 165 ++++++++++++ src/deadtrigger/gitcmd.py | 128 +++++++++ src/deadtrigger/ifexpr.py | 208 +++++++++++++++ src/deadtrigger/workflows.py | 137 ++++++++++ tests/conftest.py | 57 ++++ tests/test_cli.py | 497 +++++++++++++++++++++++++++++++++++ tests/test_cron.py | 111 ++++++++ tests/test_ifexpr.py | 128 +++++++++ tests/test_workflows.py | 130 +++++++++ 13 files changed, 2120 insertions(+) create mode 100644 pyproject.toml create mode 100644 src/deadtrigger/__init__.py create mode 100644 src/deadtrigger/cli.py create mode 100644 src/deadtrigger/core.py create mode 100644 src/deadtrigger/cron.py create mode 100644 src/deadtrigger/gitcmd.py create mode 100644 src/deadtrigger/ifexpr.py create mode 100644 src/deadtrigger/workflows.py create mode 100644 tests/conftest.py create mode 100644 tests/test_cli.py create mode 100644 tests/test_cron.py create mode 100644 tests/test_ifexpr.py create mode 100644 tests/test_workflows.py diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..bf457fc --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,37 @@ +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[project] +name = "deadtrigger" +version = "0.1.0" +description = "Find the GitHub Actions workflows that can never run: dead branch and path filters, workflow_run names that match nothing, crons that never fire." +readme = "README.md" +license = { file = "LICENSE" } +requires-python = ">=3.10" +keywords = ["github-actions", "workflows", "ci", "linter", "devops"] +classifiers = [ + "Development Status :: 4 - Beta", + "Environment :: Console", + "Intended Audience :: Developers", + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3", + "Topic :: Software Development :: Build Tools", +] +dependencies = ["PyYAML>=5.1"] + +[project.optional-dependencies] +dev = ["pytest>=7.0"] + +[project.scripts] +deadtrigger = "deadtrigger.cli:main" + +[project.urls] +Source = "https://github.com/committed-nightly/deadtrigger" + +[tool.hatch.build.targets.wheel] +packages = ["src/deadtrigger"] + +[tool.pytest.ini_options] +testpaths = ["tests"] +addopts = "-q" diff --git a/src/deadtrigger/__init__.py b/src/deadtrigger/__init__.py new file mode 100644 index 0000000..83f144b --- /dev/null +++ b/src/deadtrigger/__init__.py @@ -0,0 +1,3 @@ +"""Find the GitHub Actions workflows that can never run.""" + +__version__ = "0.1.0" diff --git a/src/deadtrigger/cli.py b/src/deadtrigger/cli.py new file mode 100644 index 0000000..fb8ec59 --- /dev/null +++ b/src/deadtrigger/cli.py @@ -0,0 +1,216 @@ +"""Command line entry point. + +Exit codes, because the main use for this is a CI gate: + + 0 every trigger, filter and condition can fire + 1 at least one of them cannot + 2 the check could not run at all + +2 is deliberately not 1 and very deliberately not 0. No repository, a --ref +that doesn't resolve, a filter pattern that cannot be parsed: those all mean +nobody looked, and "nobody looked" reported as a green tick is worse than no +check at all. + +A repository with no workflow files is a 2 for the same reason. You have +pointed a workflow checker at a repository that has no workflows, and the +likeliest explanation is that you are running it somewhere unexpected. +""" + +from __future__ import annotations + +import argparse +import json +import os +import sys + +from . import gitcmd, workflows +from .core import ( + DEAD_CRON, + DEAD_PATH_FILTER, + IMPOSSIBLE_IF, + NO_SUCH_WORKFLOW, + OFF_DEFAULT_BRANCH, + UNMATCHED_PATH, + UNMATCHED_REF, + Repo, + check, +) +from .gitcmd import GitError +from .pattern import PatternError +from .workflows import WORKFLOW_DIR, WorkflowError + +EXIT_OK = 0 +EXIT_DEAD = 1 +EXIT_ERROR = 2 + +HEADLINE = { + NO_SUCH_WORKFLOW: "names a workflow that does not exist", + OFF_DEFAULT_BRANCH: "is on the wrong branch to ever fire", + DEAD_CRON: "is a schedule that never comes round", + UNMATCHED_REF: "names a branch or tag that does not exist", + DEAD_PATH_FILTER: "cannot be satisfied by any file in the repository", + UNMATCHED_PATH: "matches no file in the repository", + IMPOSSIBLE_IF: "is a condition that is never true", +} + +ORDER = [ + OFF_DEFAULT_BRANCH, + NO_SUCH_WORKFLOW, + DEAD_PATH_FILTER, + DEAD_CRON, + IMPOSSIBLE_IF, + UNMATCHED_REF, + UNMATCHED_PATH, +] + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + prog="deadtrigger", + description=( + "Find the GitHub Actions workflows that can never run, by checking " + "their triggers against the repository they are actually in." + ), + ) + parser.add_argument( + "path", nargs="?", default=".", + help="a path inside the repository to check (default: the current directory)", + ) + parser.add_argument( + "--ref", default="HEAD", + help="check the workflows as they are at this revision (default: HEAD)", + ) + parser.add_argument( + "--default-branch", default=None, metavar="NAME", + help=( + "the repository's default branch. Only needed when the clone does " + "not record one, which is the usual case under actions/checkout." + ), + ) + parser.add_argument("--json", action="store_true", help="machine-readable output") + return parser + + +def _load(repo_root: str, ref: str) -> list: + """Every workflow file at ``ref``, parsed.""" + paths = sorted( + path + for path in gitcmd.tracked_files(repo_root, ref) + if workflows.is_workflow_path(path) + ) + sheet = [] + for path in paths: + text = gitcmd.show(ref, path, repo_root) + if text is None: # pragma: no cover - ls-tree just said it is there + continue + sheet.append(workflows.parse(text, path)) + return sheet + + +def _plural(count: int, word: str) -> str: + return f"{count} {word}" if count == 1 else f"{count} {word}s" + + +def _print_human(report, out) -> None: + by_kind: dict[str, list] = {} + for finding in report.findings: + by_kind.setdefault(finding.kind, []).append(finding) + + for kind in ORDER: + for finding in by_kind.get(kind, []): + print(f" {finding.workflow}", file=out) + print(f" {finding.where}: {finding.subject}", file=out) + print(f" {HEADLINE[kind]} -- {finding.detail}", file=out) + print(file=out) + + checked = _plural(report.workflows_checked, "workflow") + if report.findings: + print(f"{checked} checked, {_plural(len(report.findings), 'finding')}", file=out) + else: + print(f"{checked} checked, clean", file=out) + + # Printed last and printed always. A skipped check is the one thing a + # green run must not hide. + for name, reason in report.skipped: + print(f"not checked: {name} -- {reason}", file=out) + + +def main(argv: list[str] | None = None, out=None, err=None) -> int: + args = build_parser().parse_args(argv) + out = out or sys.stdout + err = err or sys.stderr + + if not os.path.isdir(args.path): + print(f"deadtrigger: not a directory: {args.path}", file=err) + return EXIT_ERROR + + try: + root = gitcmd.repo_root(args.path) + gitcmd.resolve(args.ref, root) + sheet = _load(root, args.ref) + except (GitError, WorkflowError) as exc: + print(f"deadtrigger: {exc}", file=err) + return EXIT_ERROR + + if not sheet: + print( + f"deadtrigger: no workflow files in {WORKFLOW_DIR}/ at {args.ref}", + file=err, + ) + return EXIT_ERROR + + try: + repo = _describe(root, args) + report = check(sheet, repo) + except (GitError, PatternError) as exc: + print(f"deadtrigger: {exc}", file=err) + return EXIT_ERROR + + if args.json: + print( + json.dumps( + { + "workflows_checked": report.workflows_checked, + "findings": [f.as_dict() for f in report.findings], + "skipped": [ + {"check": name, "reason": reason} + for name, reason in report.skipped + ], + }, + indent=2, + ), + file=out, + ) + else: + _print_human(report, out) + + return EXIT_OK if report.ok else EXIT_DEAD + + +def _describe(root: str, args) -> Repo: + default_branch = args.default_branch or gitcmd.default_branch(root) + + default_workflows = None + if default_branch is not None and gitcmd.ref_exists(default_branch, root): + default_workflows = { + path + for path in gitcmd.tracked_files(root, default_branch) + if workflows.is_workflow_path(path) + } + elif default_branch is not None: + # Named a default branch this clone does not have. Better to check + # nothing than to report every workflow as stranded off it. + default_branch = None + + return Repo( + files=gitcmd.tracked_files(root, args.ref), + branches=gitcmd.branches(root), + tags=gitcmd.tags(root), + default_branch=default_branch, + refs_are_complete=not gitcmd.is_shallow(root), + default_branch_workflows=default_workflows, + ) + + +if __name__ == "__main__": # pragma: no cover + sys.exit(main()) diff --git a/src/deadtrigger/core.py b/src/deadtrigger/core.py new file mode 100644 index 0000000..a0a41ed --- /dev/null +++ b/src/deadtrigger/core.py @@ -0,0 +1,303 @@ +"""The checks themselves. + +Each one answers the same question in a different place: *given this +repository as it actually is, can this thing ever fire?* That is the line +between this tool and a workflow linter. A linter reads the file; these +checks read the file against the branch list, the tag list, the file tree +and the other workflows sitting next to it. + +Where a check cannot be answered -- a shallow clone with one branch in it, +a job condition built out of things only the run knows -- it is recorded as +skipped and named in the output. A check that did not run must never be +indistinguishable from a check that passed. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field + +from . import cron as croncheck +from . import ifexpr, workflows +from .pattern import PatternError, Pattern, compile_all, included +from .workflows import DEFAULT_BRANCH_ONLY, Workflow, as_list + +NO_SUCH_WORKFLOW = "no-such-workflow" +OFF_DEFAULT_BRANCH = "off-default-branch" +DEAD_CRON = "dead-cron" +UNMATCHED_REF = "unmatched-ref" +DEAD_PATH_FILTER = "dead-path-filter" +UNMATCHED_PATH = "unmatched-path" +IMPOSSIBLE_IF = "impossible-if" + +REF_KEYS = {"branches": "branch", "branches-ignore": "branch", + "tags": "tag", "tags-ignore": "tag"} +PATH_KEYS = ("paths", "paths-ignore") + + +@dataclass +class Finding: + kind: str + workflow: str + where: str + subject: str + detail: str + + def as_dict(self) -> dict: + return { + "kind": self.kind, + "workflow": self.workflow, + "where": self.where, + "subject": self.subject, + "detail": self.detail, + } + + +@dataclass +class Report: + findings: list[Finding] = field(default_factory=list) + skipped: list[tuple[str, str]] = field(default_factory=list) + workflows_checked: int = 0 + + @property + def ok(self) -> bool: + return not self.findings + + def add(self, *args) -> None: + self.findings.append(Finding(*args)) + + def skip(self, check: str, reason: str) -> None: + self.skipped.append((check, reason)) + + +@dataclass +class Repo: + """Everything the checks are allowed to know about the repository.""" + + files: list[str] + branches: set[str] + tags: set[str] + default_branch: str | None + refs_are_complete: bool + # Workflow paths present on the default branch, or None if we cannot see it. + default_branch_workflows: set[str] | None = None + + +def check(sheet: list[Workflow], repo: Repo) -> Report: + report = Report(workflows_checked=len(sheet)) + + if not repo.refs_are_complete: + report.skip( + "branch and tag filters", + "this clone is shallow, so its branch and tag lists are the ones " + "fetched rather than the ones that exist " + "(actions/checkout needs fetch-depth: 0)", + ) + if repo.default_branch is None: + report.skip( + "default-branch-only triggers", + "cannot tell which branch is the default one " + "(no refs/remotes/origin/HEAD; pass --default-branch)", + ) + + known_names = {flow.display_name for flow in sheet} + known_names.update(flow.path for flow in sheet) + + for flow in sheet: + _check_workflow_run(flow, known_names, report) + _check_default_branch(flow, repo, report) + _check_schedule(flow, report) + _check_filters(flow, repo, report) + _check_jobs(flow, report) + + return report + + +def _check_workflow_run(flow: Workflow, known_names: set[str], report: Report) -> None: + """`workflow_run` matches the *name* of another workflow, and says nothing + when that name matches nothing.""" + config = flow.triggers.get("workflow_run") + if not isinstance(config, dict) or not config: + return + + named = [name for name in as_list(config.get("workflows")) if isinstance(name, str)] + if not named: + return + + missing = [name for name in named if name not in known_names] + if len(missing) == len(named): + report.add( + NO_SUCH_WORKFLOW, + flow.path, + "on.workflow_run.workflows", + ", ".join(repr(name) for name in missing), + "no workflow in .github/workflows has this name, so nothing can " + "ever trigger this one", + ) + elif missing: + report.add( + NO_SUCH_WORKFLOW, + flow.path, + "on.workflow_run.workflows", + ", ".join(repr(name) for name in missing), + "no workflow has this name; the other entries in the list still " + "trigger this one, so it fires less often than it reads", + ) + + +def _check_default_branch(flow: Workflow, repo: Repo, report: Report) -> None: + if repo.default_branch is None or repo.default_branch_workflows is None: + return + if flow.path in repo.default_branch_workflows: + return + + stranded = [event for event in DEFAULT_BRANCH_ONLY if event in flow.triggers] + if stranded: + report.add( + OFF_DEFAULT_BRANCH, + flow.path, + "on", + ", ".join(stranded), + f"GitHub only delivers {'this event' if len(stranded) == 1 else 'these events'} " + f"to the copy of a workflow on the default branch ({repo.default_branch}), " + "and this file is not there", + ) + + +def _check_schedule(flow: Workflow, report: Report) -> None: + raw = flow.triggers.get("schedule") + if raw is None: + return + + entries = raw if isinstance(raw, list) else as_list(raw) + crons = [ + entry.get("cron") if isinstance(entry, dict) else entry + for entry in entries + if not (isinstance(entry, dict) and "cron" not in entry) + ] + if not crons: + report.add( + DEAD_CRON, flow.path, "on.schedule", "(no cron)", + "the schedule trigger is declared with no cron entry, so nothing " + "is ever scheduled", + ) + return + + for expression in crons: + try: + parsed = croncheck.parse(expression) + except croncheck.CronError as exc: + report.add( + DEAD_CRON, flow.path, "on.schedule", repr(expression), + f"GitHub will not schedule this: {exc}", + ) + continue + + reason = croncheck.impossible_reason(parsed) + if reason: + report.add( + DEAD_CRON, flow.path, "on.schedule", repr(expression), + f"valid cron for a date that never happens: {reason}", + ) + + +def _unmatched(patterns: list[Pattern], candidates: set[str] | list[str]) -> list[Pattern]: + return [p for p in patterns if not any(p.matches(c) for c in candidates)] + + +def _check_filters(flow: Workflow, repo: Repo, report: Report) -> None: + for event, config in flow.triggers.items(): + if not isinstance(config, dict): + continue + + if repo.refs_are_complete: + for key, noun in REF_KEYS.items(): + if key in config: + _check_ref_filter(flow, event, key, noun, config[key], repo, report) + + for key in PATH_KEYS: + if key in config: + _check_path_filter(flow, event, key, config[key], repo, report) + + +def _compile(texts: list, flow: Workflow, where: str) -> list[Pattern]: + try: + return compile_all([t for t in texts]) + except PatternError as exc: + raise PatternError(f"{flow.path}: {where}: {exc}") from exc + + +def _check_ref_filter(flow, event, key, noun, raw, repo: Repo, report: Report) -> None: + """Branch and tag filters. + + Only patterns with no wildcard in them are reported. `release/**` in a + repository with no release branches is a filter waiting for a branch, + which is a normal thing to write and none of this tool's business. + `master` in a repository whose branch is called `main` is a typo, and + the workflow has never run once. + """ + where = f"on.{event}.{key}" + patterns = _compile(as_list(raw), flow, where) + candidates = repo.branches if noun == "branch" else repo.tags + + for pattern in _unmatched(patterns, candidates): + if pattern.has_wildcard: + continue + report.add( + UNMATCHED_REF, flow.path, where, pattern.text, + f"no {noun} in this repository is called that", + ) + + +def _check_path_filter(flow, event, key, raw, repo: Repo, report: Report) -> None: + where = f"on.{event}.{key}" + patterns = _compile(as_list(raw), flow, where) + + # A `paths:` list that matches nothing is reported once, for the whole + # filter, rather than once per pattern: the interesting fact is that the + # event cannot fire, not that each line individually missed. + if key == "paths" and patterns: + if not any(included(patterns, path) for path in repo.files): + report.add( + DEAD_PATH_FILTER, flow.path, where, + ", ".join(p.text for p in patterns), + f"no file in the repository is matched by this filter, so " + f"{event} can never start this workflow", + ) + return + + for pattern in _unmatched(patterns, repo.files): + if pattern.negated: + # An exclusion that currently excludes nothing is a guard against + # files that do not exist yet. That is what a guard is for. + continue + report.add( + UNMATCHED_PATH, flow.path, where, pattern.text, + "matches no file in the repository", + ) + + +def _check_jobs(flow: Workflow, report: Report) -> None: + """Job conditions that no event this workflow receives can satisfy. + + Skipped entirely for reusable workflows: under `workflow_call`, + `github.event_name` is the *caller's* event, which is not in this file + and not knowable from it. + """ + events = flow.events + if not events or "workflow_call" in flow.triggers: + return + + for job_id, job in flow.jobs.items(): + if not isinstance(job, dict) or "if" not in job: + continue + try: + live = ifexpr.satisfiable_events(job["if"], events) + except ifexpr.Unsupported: + continue + if not live: + report.add( + IMPOSSIBLE_IF, flow.path, f"jobs.{job_id}.if", + ifexpr.strip_expression(job["if"]), + "no event this workflow is triggered by can make this true, " + f"so the job never runs (triggers: {', '.join(events)})", + ) diff --git a/src/deadtrigger/cron.py b/src/deadtrigger/cron.py new file mode 100644 index 0000000..0f6d667 --- /dev/null +++ b/src/deadtrigger/cron.py @@ -0,0 +1,165 @@ +"""Cron expressions, and whether a date exists that satisfies them. + +Two things can go wrong with a `schedule:` entry, and neither of them shows +up anywhere in the Actions UI: + +* the expression is not valid cron, so nothing is ever scheduled; +* the expression is perfectly valid and describes a date that does not + happen. ``0 0 30 2 *`` is February the 30th. + +The second one is the reason this module computes rather than validates. +The trap is the day-of-month / day-of-week rule: when both fields are +restricted, cron fires if **either** matches, not both. So ``0 0 30 2 1`` +does fire -- every Monday in February -- and calling it impossible because +the 30th does not exist would be wrong. Only a schedule whose day-of-week +is unrestricted can be ruled out on its dates alone. + +Anything this module does not recognise is reported as unparseable rather +than guessed at, and the caller must not turn that into a pass. +""" + +from __future__ import annotations + +import calendar +from dataclasses import dataclass + +MONTH_NAMES = { + name: index + for index, name in enumerate( + ["JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"], + start=1, + ) +} +DAY_NAMES = { + name: index + for index, name in enumerate(["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"]) +} + +# (name, low, high, aliases) +FIELDS = [ + ("minute", 0, 59, {}), + ("hour", 0, 23, {}), + ("day of month", 1, 31, {}), + ("month", 1, 12, MONTH_NAMES), + # 7 is Sunday as well as 0. Vixie cron allows it and rejecting it would + # be a false "invalid" on a schedule that runs perfectly well. + ("day of week", 0, 7, DAY_NAMES), +] + + +class CronError(ValueError): + """An expression this module will not pretend to understand.""" + + +@dataclass(frozen=True) +class Cron: + text: str + minutes: frozenset[int] + hours: frozenset[int] + days_of_month: frozenset[int] + months: frozenset[int] + days_of_week: frozenset[int] + dom_restricted: bool + dow_restricted: bool + + +def _parse_field(text: str, name: str, low: int, high: int, aliases: dict) -> set[int]: + values: set[int] = set() + + for item in text.split(","): + if not item: + raise CronError(f"empty value in the {name} field") + + step = 1 + if "/" in item: + item, _, step_text = item.partition("/") + if not step_text.isdigit() or int(step_text) == 0: + raise CronError(f"bad step {step_text!r} in the {name} field") + step = int(step_text) + + if item == "*": + start, end = low, high + elif "-" in item: + start_text, _, end_text = item.partition("-") + start = _value(start_text, name, low, high, aliases) + end = _value(end_text, name, low, high, aliases) + if start > end: + # Vixie cron rejects a reversed range rather than wrapping it. + raise CronError(f"reversed range {item!r} in the {name} field") + else: + start = _value(item, name, low, high, aliases) + # `5/10` is "from 5 to the top of the field, every 10". Bare `5` + # with no step is just the one value. + end = high if step > 1 else start + + values.update(range(start, end + 1, step)) + + if not values: + raise CronError(f"the {name} field matches nothing") + return values + + +def _value(text: str, name: str, low: int, high: int, aliases: dict) -> int: + key = text.strip().upper() + if key in aliases: + return aliases[key] + if not key.isdigit(): + raise CronError(f"{text!r} is not a number in the {name} field") + number = int(key) + if not low <= number <= high: + raise CronError(f"{number} is outside {low}-{high} in the {name} field") + return number + + +def parse(text: str) -> Cron: + """Parse a five-field cron expression, or raise CronError.""" + if not isinstance(text, str): + raise CronError(f"not a string: {text!r}") + + fields = text.split() + if len(fields) != 5: + raise CronError( + f"{len(fields)} field{'' if len(fields) == 1 else 's'}, expected 5 " + "(minute hour day-of-month month day-of-week)" + ) + + parsed = [ + _parse_field(field, name, low, high, aliases) + for field, (name, low, high, aliases) in zip(fields, FIELDS) + ] + minutes, hours, doms, months, dows = parsed + + if 7 in dows: + dows = (dows - {7}) | {0} + + return Cron( + text=text, + minutes=frozenset(minutes), + hours=frozenset(hours), + days_of_month=frozenset(doms), + months=frozenset(months), + days_of_week=frozenset(dows), + dom_restricted=fields[2] != "*", + dow_restricted=fields[4] != "*", + ) + + +def impossible_reason(cron: Cron) -> str | None: + """Why no date can ever satisfy this cron, or None if one can. + + Only day-of-month against month can make a schedule impossible, and only + when day-of-week is unrestricted -- otherwise the day-of-week half of + cron's OR still fires. + """ + if not cron.dom_restricted or cron.dow_restricted: + return None + + # 2024 is a leap year, so February 29 counts as a day that exists. + for month in sorted(cron.months): + longest = calendar.monthrange(2024, month)[1] + if any(day <= longest for day in cron.days_of_month): + return None + + days = ", ".join(str(day) for day in sorted(cron.days_of_month)) + names = ", ".join(calendar.month_name[month] for month in sorted(cron.months)) + return f"day {days} does not occur in {names}" diff --git a/src/deadtrigger/gitcmd.py b/src/deadtrigger/gitcmd.py new file mode 100644 index 0000000..46f433b --- /dev/null +++ b/src/deadtrigger/gitcmd.py @@ -0,0 +1,128 @@ +"""Thin wrappers over the ``git`` binary. + +Everything this tool compares workflows against -- the file tree, the branch +names, the tag names, the default branch -- comes from git rather than from +the filesystem or the API. No network, no token, no rate limit. + +The one thing to be careful about is that a checkout can be a partial view of +the repository. ``actions/checkout`` at its default ``fetch-depth: 1`` leaves +a shallow clone holding exactly one branch, so ``for-each-ref`` there reports +one branch for a repository that has forty. ``is_shallow`` exists so the +branch checks can decline to run rather than accuse every branch filter in +the repository of naming something that does not exist. +""" + +from __future__ import annotations + +import subprocess + + +class GitError(RuntimeError): + """git was missing, unhappy, or pointed at something that isn't a repo.""" + + +def run_git(args: list[str], cwd: str) -> str: + try: + proc = subprocess.run(["git", *args], cwd=cwd, capture_output=True, check=False) + except FileNotFoundError as exc: # pragma: no cover - depends on the box + raise GitError("git is not on PATH") from exc + if proc.returncode != 0: + stderr = proc.stderr.decode("utf-8", "replace").strip() + raise GitError(stderr or f"git {' '.join(args)} failed") + return proc.stdout.decode("utf-8", "replace") + + +def repo_root(cwd: str) -> str: + return run_git(["rev-parse", "--show-toplevel"], cwd).strip() + + +def resolve(rev: str, cwd: str) -> str: + """Resolve a revision to a commit sha, or raise with the name the user typed.""" + try: + out = run_git(["rev-parse", "--verify", "--quiet", rev + "^{commit}"], cwd).strip() + except GitError as exc: + if str(exc).startswith("git "): + raise GitError(f"no such revision: {rev}") from exc + raise + if not out: + raise GitError(f"no such revision: {rev}") + return out + + +def is_shallow(cwd: str) -> bool: + return run_git(["rev-parse", "--is-shallow-repository"], cwd).strip() == "true" + + +def tracked_files(cwd: str, ref: str) -> list[str]: + """Every file at ``ref``, as repo-root-relative paths. + + ``-z`` because a newline in a path is legal in git, rare, and exactly the + sort of thing that would make a checker quietly miscount. + """ + out = run_git(["ls-tree", "-r", "-z", "--name-only", ref], cwd) + return [path for path in out.split("\0") if path] + + +def show(ref: str, relpath: str, cwd: str) -> str | None: + """Contents of a file at a revision, or None if it isn't there.""" + try: + return run_git(["show", f"{ref}:{relpath}"], cwd) + except GitError: + return None + + +def _strip_remote(refname: str) -> str | None: + """``refs/remotes/origin/feature/x`` -> ``feature/x``. + + ``origin/HEAD`` is a symbolic pointer at the default branch, not a branch + in its own right, and counting it would invent a branch called HEAD. + """ + rest = refname[len("refs/remotes/") :] + _, _, name = rest.partition("/") + if not name or name == "HEAD": + return None + return name + + +def branches(cwd: str) -> set[str]: + """Branch names, local and remote-tracking, with the remote prefix removed.""" + out = run_git( + ["for-each-ref", "--format=%(refname)", "refs/heads", "refs/remotes"], cwd + ) + names: set[str] = set() + for line in out.splitlines(): + line = line.strip() + if line.startswith("refs/heads/"): + names.add(line[len("refs/heads/") :]) + elif line.startswith("refs/remotes/"): + name = _strip_remote(line) + if name: + names.add(name) + return names + + +def tags(cwd: str) -> set[str]: + out = run_git(["for-each-ref", "--format=%(refname)", "refs/tags"], cwd) + return {line[len("refs/tags/") :] for line in out.splitlines() if line.strip()} + + +def default_branch(cwd: str) -> str | None: + """The default branch, if this clone records one. + + ``refs/remotes/origin/HEAD`` is set by a normal ``git clone`` and is not + set by ``actions/checkout``, so this returns None often enough that the + caller has to handle it rather than assume "main". + """ + try: + out = run_git(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], cwd).strip() + except GitError: + return None + return _strip_remote(out) if out.startswith("refs/remotes/") else None + + +def ref_exists(rev: str, cwd: str) -> bool: + try: + resolve(rev, cwd) + return True + except GitError: + return False diff --git a/src/deadtrigger/ifexpr.py b/src/deadtrigger/ifexpr.py new file mode 100644 index 0000000..ea49739 --- /dev/null +++ b/src/deadtrigger/ifexpr.py @@ -0,0 +1,208 @@ +"""Deciding whether a job's ``if:`` can ever be true. + +This only answers the question for conditions built entirely out of +``github.event_name``, string literals and booleans. That is a small corner +of the expression language, and deliberately so: the whole value of this +check is that when it fires it is *right*, and there is no way to be right +about ``needs.build.result`` or ``github.event.pull_request.draft`` without +knowing what happened at run time. + +So the parser refuses anything it does not fully recognise. A refusal means +the job is not reported, which is the correct failure direction -- a missed +dead job costs nothing, a false accusation costs the tool its credibility. + +Why evaluation and not pattern-matching: the condition is evaluated once per +event the workflow actually declares, with ``github.event_name`` bound to +that event. If every one of them comes out false, no event this workflow can +receive will ever start the job. That handles ``||`` chains, negation and +parentheses without special-casing any of them. + +Not handled on purpose: ``github.event.pull_request`` on a workflow with no +pull request trigger. It looks like the same kind of check and it is a trap. +The value is ``null``, and in GitHub's expression language ``null == false`` +compares 0 to 0 and is **true**, so the obvious reading of a draft check +gets the answer backwards. A tool that guessed here would be confidently +wrong about a job that runs perfectly well. +""" + +from __future__ import annotations + +import re + +EVENT_NAME = "github.event_name" + +_TOKENS = re.compile( + r""" + \s*(?: + (?P==|!=|\|\||&&|!|\(|\)) + | (?P'(?:[^']|'')*') + | (?P[A-Za-z_][A-Za-z_0-9.\-]*) + ) + """, + re.VERBOSE, +) + + +class Unsupported(Exception): + """The condition uses something this module will not guess about.""" + + +def _tokenise(text: str) -> list[tuple[str, str]]: + tokens: list[tuple[str, str]] = [] + position = 0 + while position < len(text): + if text[position].isspace(): + position += 1 + continue + match = _TOKENS.match(text, position) + if not match: + raise Unsupported(f"cannot read {text[position:position + 12]!r}") + kind = match.lastgroup + tokens.append((kind, match.group(kind))) + position = match.end() + return tokens + + +class _Parser: + """Recursive descent over the fragment of the language we accept. + + ``event`` is the value bound to github.event_name for this evaluation. + """ + + def __init__(self, tokens: list[tuple[str, str]], event: str) -> None: + self.tokens = tokens + self.index = 0 + self.event = event + + def peek(self) -> tuple[str, str] | None: + return self.tokens[self.index] if self.index < len(self.tokens) else None + + def take(self) -> tuple[str, str]: + token = self.peek() + if token is None: + raise Unsupported("expression ends early") + self.index += 1 + return token + + def parse(self) -> bool: + value = self.or_expr() + if self.peek() is not None: + raise Unsupported(f"trailing {self.peek()[1]!r}") + return _truthy(value) + + def or_expr(self): + value = self.and_expr() + while self.peek() == ("op", "||"): + self.take() + right = self.and_expr() + # GitHub's || returns the first truthy operand, but every caller + # here immediately asks whether the result is truthy, so folding + # to a bool loses nothing. + value = _truthy(value) or _truthy(right) + return value + + def and_expr(self): + value = self.unary() + while self.peek() == ("op", "&&"): + self.take() + right = self.unary() + value = _truthy(value) and _truthy(right) + return value + + def unary(self): + if self.peek() == ("op", "!"): + self.take() + return not _truthy(self.unary()) + return self.comparison() + + def comparison(self): + left = self.primary() + token = self.peek() + if token is not None and token[0] == "op" and token[1] in ("==", "!="): + self.take() + right = self.primary() + equal = _equal(left, right) + return equal if token[1] == "==" else not equal + return left + + def primary(self): + kind, text = self.take() + if (kind, text) == ("op", "("): + value = self.or_expr() + if self.take() != ("op", ")"): + raise Unsupported("unbalanced parentheses") + return value + if (kind, text) == ("op", "!"): + return not _truthy(self.unary()) + if kind == "string": + return text[1:-1].replace("''", "'") + if kind == "word": + if text == EVENT_NAME: + return self.event + if text == "true": + return True + if text == "false": + return False + raise Unsupported(f"{text} is not github.event_name") + raise Unsupported(f"unexpected {text!r}") + + +def _equal(left, right) -> bool: + if isinstance(left, bool) or isinstance(right, bool): + # Mixed-type comparison in GitHub's language coerces to numbers, and + # guessing at that is exactly what this module refuses to do. + if not (isinstance(left, bool) and isinstance(right, bool)): + raise Unsupported("comparison mixes a boolean with a string") + return left == right + + +def _truthy(value) -> bool: + if isinstance(value, bool): + return value + if isinstance(value, str): + return value != "" + raise Unsupported(f"cannot take the truth of {value!r}") + + +def strip_expression(condition) -> str: + """The condition with a single wrapping ``${{ }}`` removed. + + A job `if:` may be written with or without the braces. Anything with + braces *around part of it* is a template with literal text in it, which + this module does not handle. + """ + if isinstance(condition, bool): + return "true" if condition else "false" + if not isinstance(condition, str): + raise Unsupported(f"not a condition: {condition!r}") + + text = condition.strip() + if text.startswith("${{"): + if not text.endswith("}}") or "${{" in text[3:]: + raise Unsupported("condition is a template, not a single expression") + text = text[3:-2].strip() + elif "${{" in text: + raise Unsupported("condition is a template, not a single expression") + if not text: + raise Unsupported("empty condition") + return text + + +def satisfiable_events(condition, events: list[str]) -> list[str]: + """Which of ``events`` could make ``condition`` true. + + Raises Unsupported if the condition is not one we can decide, which the + caller must treat as "no opinion" rather than as a pass or a failure. + """ + text = strip_expression(condition) + tokens = _tokenise(text) + if not tokens: + raise Unsupported("empty condition") + + mentions_event = ("word", EVENT_NAME) in tokens + if not mentions_event and text not in ("true", "false"): + # A condition that never looks at the event cannot be decided from + # the trigger list, and this module has nothing else to go on. + raise Unsupported("condition does not depend on github.event_name") + + return [event for event in events if _Parser(tokens, event).parse()] diff --git a/src/deadtrigger/workflows.py b/src/deadtrigger/workflows.py new file mode 100644 index 0000000..f160767 --- /dev/null +++ b/src/deadtrigger/workflows.py @@ -0,0 +1,137 @@ +"""Finding and reading the workflow files in a repository. + +The one thing worth knowing here: in YAML 1.1, which is what PyYAML +implements, the bare word ``on`` is a **boolean**. So the key of the block +every workflow file in the world starts with does not come back as the +string ``"on"``; it comes back as ``True``. Look it up by name and every +workflow in the repository appears to have no triggers at all, which for a +tool about triggers is a quiet and total failure. ``trigger_block`` below is +the whole fix and it is three lines long. +""" + +from __future__ import annotations + +import posixpath +from dataclasses import dataclass, field +from typing import Any + +import yaml + +WORKFLOW_DIR = ".github/workflows" +WORKFLOW_SUFFIXES = (".yml", ".yaml") + +# Triggers GitHub only ever delivers to the copy of a workflow that is on the +# repository's default branch, however many other branches it appears on. +DEFAULT_BRANCH_ONLY = ("schedule", "workflow_dispatch", "workflow_run") + +# Events that carry a pull request. Used to decide whether a job condition +# that reads github.event.pull_request can ever see one. +PULL_REQUEST_EVENTS = ("pull_request", "pull_request_target", "pull_request_review", + "pull_request_review_comment", "merge_group") + + +class WorkflowError(ValueError): + """A workflow file that could not be read as a workflow.""" + + +@dataclass +class Workflow: + path: str + declared_name: str | None + triggers: dict[str, Any] + jobs: dict[str, Any] + raw: dict[str, Any] = field(repr=False, default_factory=dict) + + @property + def display_name(self) -> str: + """What GitHub calls this workflow in the UI and in the API. + + With no `name:`, GitHub falls back to the workflow's path. That + fallback is also what a `workflow_run` reference has to be matched + against, since there is no name for it to use. + """ + return self.declared_name if self.declared_name else self.path + + @property + def events(self) -> list[str]: + return list(self.triggers) + + +def is_workflow_path(path: str) -> bool: + """Whether a repo-relative path is a file GitHub will read as a workflow. + + GitHub only looks in .github/workflows itself, not in subdirectories of + it -- a file one level down is silently not a workflow at all. + """ + if not path.endswith(WORKFLOW_SUFFIXES): + return False + return posixpath.dirname(path) == WORKFLOW_DIR + + +def trigger_block(document: dict[str, Any]) -> Any: + """The value of the `on:` key, whatever YAML decided that key was.""" + if "on" in document: + return document["on"] + return document.get(True) + + +def normalise_triggers(raw: Any) -> dict[str, Any]: + """The `on:` value as {event: config}, for all three spellings. + + ``on: push``, ``on: [push, pull_request]`` and the mapping form all mean + the same thing to GitHub, and only the mapping form carries filters. An + event with no configuration gets an empty dict rather than None so that + callers can index it without checking. Anything else is passed through + untouched -- ``schedule:`` is a *list* of cron entries, and coercing + every non-mapping config to {} would throw every schedule in the + repository away without saying so. + """ + if raw is None: + return {} + if isinstance(raw, str): + return {raw: {}} + if isinstance(raw, list): + return {event: {} for event in raw if isinstance(event, str)} + if isinstance(raw, dict): + return { + event: ({} if config is None else config) + for event, config in raw.items() + if isinstance(event, str) + } + return {} + + +def parse(text: str, path: str) -> Workflow: + """Parse one workflow file. Raises WorkflowError if it is not one.""" + try: + document = yaml.safe_load(text) + except yaml.YAMLError as exc: + raise WorkflowError(f"{path}: not valid YAML: {exc}") from exc + + if document is None: + raise WorkflowError(f"{path}: file is empty") + if not isinstance(document, dict): + raise WorkflowError(f"{path}: top level is not a mapping") + + declared = document.get("name") + jobs = document.get("jobs") + + return Workflow( + path=path, + declared_name=declared if isinstance(declared, str) and declared else None, + triggers=normalise_triggers(trigger_block(document)), + jobs=jobs if isinstance(jobs, dict) else {}, + raw=document, + ) + + +def as_list(value: Any) -> list[Any]: + """A YAML field that may be written as a scalar or a sequence. + + `branches: main` and `branches: [main]` are both legal. + """ + if value is None: + return [] + if isinstance(value, list): + return value + return [value] diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..fa53e31 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,57 @@ +"""A real git repository per test. + +The checks are about a repository, so the tests build one: real commits, +real branches, real tags, real `git ls-tree`. Faking the git layer would +leave the part most likely to be wrong -- what a checkout can actually see +-- untested. +""" + +from __future__ import annotations + +import subprocess +import textwrap + +import pytest + + +class Repo: + def __init__(self, path): + self.path = str(path) + self.git("init", "-q", "-b", "main") + self.git("config", "user.name", "test") + self.git("config", "user.email", "test@example.invalid") + + def git(self, *args) -> str: + proc = subprocess.run( + ["git", *args], cwd=self.path, capture_output=True, check=True + ) + return proc.stdout.decode() + + def write(self, relpath: str, content: str = "x\n") -> None: + import os + + full = os.path.join(self.path, relpath) + os.makedirs(os.path.dirname(full), exist_ok=True) if os.path.dirname( + relpath + ) else None + with open(full, "w", encoding="utf-8") as handle: + handle.write(textwrap.dedent(content)) + self.git("add", relpath) + + def workflow(self, name: str, content: str) -> None: + self.write(f".github/workflows/{name}", content) + + def commit(self, message: str = "commit") -> str: + self.git("commit", "-q", "-m", message) + return self.git("rev-parse", "HEAD").strip() + + def branch(self, name: str) -> None: + self.git("branch", name) + + def tag(self, name: str) -> None: + self.git("tag", name) + + +@pytest.fixture +def repo(tmp_path): + return Repo(tmp_path) diff --git a/tests/test_cli.py b/tests/test_cli.py new file mode 100644 index 0000000..96f86a7 --- /dev/null +++ b/tests/test_cli.py @@ -0,0 +1,497 @@ +"""End to end, against real repositories built by the `repo` fixture.""" + +from __future__ import annotations + +import io +import json + +import pytest + +from deadtrigger.cli import EXIT_DEAD, EXIT_ERROR, EXIT_OK, main + +HEALTHY = """ + name: CI + on: + push: + branches: [main] + paths: ['src/**'] + jobs: + build: + runs-on: ubuntu-latest + steps: [{run: 'true'}] +""" + + +def run(repo, *args): + out, err = io.StringIO(), io.StringIO() + code = main([repo.path, *args], out=out, err=err) + return code, out.getvalue(), err.getvalue() + + +def run_json(repo, *args): + code, out, err = run(repo, "--json", *args) + return code, json.loads(out), err + + +@pytest.fixture +def healthy(repo): + repo.write("src/app.py") + repo.workflow("ci.yml", HEALTHY) + repo.commit() + return repo + + +class TestHealthy: + def test_clean_repository_exits_zero(self, healthy): + code, out, _ = run(healthy) + assert code == EXIT_OK + assert "1 workflow checked, clean" in out + + def test_nothing_is_skipped_in_a_full_clone_with_a_default_branch(self, healthy): + code, out, _ = run(healthy, "--default-branch", "main") + assert code == EXIT_OK + assert "not checked:" not in out + + +class TestWorkflowRun: + def test_name_that_matches_nothing(self, repo): + repo.workflow("ci.yml", "name: CI\non: push\njobs: {}\n") + repo.workflow( + "after.yml", + """ + name: After + on: + workflow_run: + workflows: [Build] + types: [completed] + jobs: {} + """, + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + finding = next(f for f in data["findings"] if f["kind"] == "no-such-workflow") + assert finding["subject"] == "'Build'" + assert "nothing can ever trigger" in finding["detail"] + + def test_name_that_matches_is_clean(self, repo): + repo.workflow("ci.yml", "name: CI\non: push\njobs: {}\n") + repo.workflow( + "after.yml", + "name: After\non:\n workflow_run:\n workflows: [CI]\njobs: {}\n", + ) + repo.commit() + assert run(repo)[0] == EXIT_OK + + def test_unnamed_workflow_is_matched_by_its_path(self, repo): + """A workflow with no name: is shown by GitHub as its path, so a + workflow_run naming that path is not dead.""" + repo.workflow("ci.yml", "on: push\njobs: {}\n") + repo.workflow( + "after.yml", + "name: After\non:\n workflow_run:\n" + " workflows: ['.github/workflows/ci.yml']\njobs: {}\n", + ) + repo.commit() + assert run(repo)[0] == EXIT_OK + + def test_one_bad_name_among_good_ones_is_still_reported(self, repo): + repo.workflow("ci.yml", "name: CI\non: push\njobs: {}\n") + repo.workflow( + "after.yml", + "name: After\non:\n workflow_run:\n workflows: [CI, Buidl]\njobs: {}\n", + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + finding = data["findings"][0] + assert finding["subject"] == "'Buidl'" + assert "fires less often than it reads" in finding["detail"] + + +class TestSchedule: + def test_impossible_date(self, repo): + repo.workflow( + "nightly.yml", + "name: N\non:\n schedule:\n - cron: '0 0 30 2 *'\njobs: {}\n", + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert data["findings"][0]["kind"] == "dead-cron" + assert "February" in data["findings"][0]["detail"] + + def test_invalid_cron(self, repo): + repo.workflow( + "nightly.yml", "name: N\non:\n schedule:\n - cron: '0 0 * *'\njobs: {}\n" + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert "expected 5" in data["findings"][0]["detail"] + + def test_schedule_declared_with_no_cron(self, repo): + """`on: [push, schedule]` reads like a nightly build and schedules + nothing at all.""" + repo.workflow("nightly.yml", "name: N\non: [push, schedule]\njobs: {}\n") + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert "no cron entry" in data["findings"][0]["detail"] + + def test_ordinary_schedule_is_clean(self, repo): + repo.workflow( + "nightly.yml", + "name: N\non:\n schedule:\n - cron: '17 22 * * *'\njobs: {}\n", + ) + repo.commit() + assert run(repo)[0] == EXIT_OK + + +class TestRefFilters: + def test_literal_branch_that_does_not_exist(self, repo): + repo.workflow( + "ci.yml", "name: CI\non:\n push:\n branches: [master]\njobs: {}\n" + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert data["findings"][0]["kind"] == "unmatched-ref" + assert data["findings"][0]["subject"] == "master" + + def test_literal_branch_that_exists_only_as_a_remote_is_fine(self, repo): + repo.workflow( + "ci.yml", "name: CI\non:\n push:\n branches: [release]\njobs: {}\n" + ) + repo.commit() + repo.git("update-ref", "refs/remotes/origin/release", "HEAD") + assert run(repo)[0] == EXIT_OK + + def test_wildcard_branch_pattern_is_left_alone(self, repo): + """`release/**` with no release branches yet is a filter waiting for + a branch, not a mistake. Nagging about it would make the tool useless + in every repository that plans ahead.""" + repo.workflow( + "ci.yml", + "name: CI\non:\n push:\n branches: [main, 'release/**']\njobs: {}\n", + ) + repo.commit() + assert run(repo)[0] == EXIT_OK + + def test_literal_tag(self, repo): + repo.workflow( + "rel.yml", "name: R\non:\n push:\n tags: [v1.0.0]\njobs: {}\n" + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert "no tag in this repository" in data["findings"][0]["detail"] + + def test_existing_tag_is_clean(self, repo): + repo.workflow( + "rel.yml", "name: R\non:\n push:\n tags: [v1.0.0]\njobs: {}\n" + ) + repo.commit() + repo.tag("v1.0.0") + assert run(repo)[0] == EXIT_OK + + def test_branches_ignore_is_checked_too(self, repo): + repo.workflow( + "ci.yml", + "name: CI\non:\n push:\n branches-ignore: [gh-pages]\njobs: {}\n", + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert data["findings"][0]["subject"] == "gh-pages" + + def test_scalar_form_of_a_filter(self, repo): + """`branches: master` without the brackets is legal YAML and legal + Actions.""" + repo.workflow( + "ci.yml", "name: CI\non:\n push:\n branches: master\njobs: {}\n" + ) + repo.commit() + assert run(repo)[0] == EXIT_DEAD + + +class TestPathFilters: + def test_whole_filter_dead(self, repo): + repo.write("app/main.py") + repo.workflow( + "ci.yml", "name: CI\non:\n push:\n paths: ['src/**']\njobs: {}\n" + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert data["findings"][0]["kind"] == "dead-path-filter" + assert "push can never start this workflow" in data["findings"][0]["detail"] + + def test_one_dead_pattern_among_live_ones(self, repo): + repo.write("src/main.py") + repo.workflow( + "ci.yml", + "name: CI\non:\n push:\n paths: ['src/**', 'lib/**']\njobs: {}\n", + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert [f["kind"] for f in data["findings"]] == ["unmatched-path"] + assert data["findings"][0]["subject"] == "lib/**" + + def test_dead_filter_is_reported_once_not_per_pattern(self, repo): + repo.write("app/main.py") + repo.workflow( + "ci.yml", + "name: CI\non:\n push:\n paths: ['src/**', 'lib/**']\njobs: {}\n", + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert len(data["findings"]) == 1 + + def test_negated_pattern_that_excludes_nothing_is_left_alone(self, repo): + """An exclusion guarding against files that do not exist yet is what + an exclusion is for.""" + repo.write("src/main.py") + repo.workflow( + "ci.yml", + "name: CI\non:\n push:\n paths: ['src/**', '!src/vendor/**']\njobs: {}\n", + ) + repo.commit() + assert run(repo)[0] == EXIT_OK + + def test_paths_ignore_that_matches_nothing(self, repo): + repo.write("src/main.py") + repo.workflow( + "ci.yml", + "name: CI\non:\n push:\n paths-ignore: ['docs/**']\njobs: {}\n", + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert data["findings"][0]["kind"] == "unmatched-path" + + def test_the_regex_quantifier_really_is_used(self, repo): + """`*.jsx?` must not be satisfied by a file called page.jsz. If the + matcher ever falls back to fnmatch, this goes green and stops + catching anything.""" + repo.write("page.jsz") + repo.workflow( + "ci.yml", "name: CI\non:\n push:\n paths: ['*.jsx?']\njobs: {}\n" + ) + repo.commit() + assert run(repo)[0] == EXIT_DEAD + + +class TestJobConditions: + def test_condition_naming_an_event_the_workflow_lacks(self, repo): + repo.workflow( + "ci.yml", + """ + name: CI + on: push + jobs: + nightly: + if: github.event_name == 'schedule' + runs-on: ubuntu-latest + steps: [{run: 'true'}] + """, + ) + repo.commit() + code, data, _ = run_json(repo) + assert code == EXIT_DEAD + assert data["findings"][0]["kind"] == "impossible-if" + assert "triggers: push" in data["findings"][0]["detail"] + + def test_condition_that_can_fire_is_clean(self, repo): + repo.workflow( + "ci.yml", + """ + name: CI + on: + push: + schedule: + - cron: '0 3 * * *' + jobs: + nightly: + if: github.event_name == 'schedule' + steps: [] + """, + ) + repo.commit() + assert run(repo)[0] == EXIT_OK + + def test_undecidable_condition_is_not_reported(self, repo): + repo.workflow( + "ci.yml", + """ + name: CI + on: push + jobs: + deploy: + if: github.ref == 'refs/heads/main' + steps: [] + """, + ) + repo.commit() + assert run(repo)[0] == EXIT_OK + + def test_reusable_workflows_are_left_alone(self, repo): + """Under workflow_call, github.event_name is the caller's event and + is not knowable from this file.""" + repo.workflow( + "reusable.yml", + """ + name: Reusable + on: workflow_call + jobs: + only-on-push: + if: github.event_name == 'push' + steps: [] + """, + ) + repo.commit() + assert run(repo)[0] == EXIT_OK + + +class TestDefaultBranch: + def test_schedule_on_a_branch_that_is_not_the_default(self, repo): + repo.write("README.md") + repo.commit() + repo.git("checkout", "-q", "-b", "topic") + repo.workflow( + "nightly.yml", + "name: N\non:\n schedule:\n - cron: '0 3 * * *'\njobs: {}\n", + ) + repo.commit() + code, data, _ = run_json(repo, "--default-branch", "main") + assert code == EXIT_DEAD + finding = data["findings"][0] + assert finding["kind"] == "off-default-branch" + assert finding["subject"] == "schedule" + + def test_same_workflow_on_the_default_branch_is_clean(self, repo): + repo.workflow( + "nightly.yml", + "name: N\non:\n schedule:\n - cron: '0 3 * * *'\njobs: {}\n", + ) + repo.commit() + assert run(repo, "--default-branch", "main")[0] == EXIT_OK + + def test_push_only_workflow_off_the_default_branch_is_fine(self, repo): + """push is delivered to whatever branch the workflow is on. Only + schedule, workflow_dispatch and workflow_run are stranded.""" + repo.write("README.md") + repo.commit() + repo.git("checkout", "-q", "-b", "topic") + repo.workflow("ci.yml", "name: CI\non: push\njobs: {}\n") + repo.commit() + assert run(repo, "--default-branch", "main")[0] == EXIT_OK + + def test_check_is_named_as_skipped_when_the_default_branch_is_unknown(self, repo): + repo.workflow("ci.yml", "name: CI\non: push\njobs: {}\n") + repo.commit() + _, out, _ = run(repo) + assert "not checked: default-branch-only triggers" in out + + def test_a_default_branch_that_does_not_exist_skips_rather_than_accuses(self, repo): + repo.workflow( + "nightly.yml", + "name: N\non:\n schedule:\n - cron: '0 3 * * *'\njobs: {}\n", + ) + repo.commit() + code, out, _ = run(repo, "--default-branch", "trunk") + assert code == EXIT_OK + assert "not checked: default-branch-only triggers" in out + + +class TestSkippedChecks: + def test_shallow_clone_declines_the_branch_check(self, repo, tmp_path): + """A shallow clone holds the branches it fetched, not the ones that + exist, so `master` there proves nothing.""" + repo.workflow( + "ci.yml", "name: CI\non:\n push:\n branches: [master]\njobs: {}\n" + ) + repo.commit() + + clone = tmp_path / "shallow" + import subprocess + + subprocess.run( + ["git", "clone", "-q", "--depth", "1", "file://" + repo.path, str(clone)], + check=True, + capture_output=True, + ) + + out = io.StringIO() + code = main([str(clone)], out=out, err=io.StringIO()) + assert code == EXIT_OK + assert "not checked: branch and tag filters" in out.getvalue() + + def test_skips_are_listed_in_json_too(self, repo): + repo.workflow("ci.yml", "name: CI\non: push\njobs: {}\n") + repo.commit() + _, data, _ = run_json(repo) + assert [s["check"] for s in data["skipped"]] == ["default-branch-only triggers"] + + +class TestErrors: + def test_not_a_repository(self, tmp_path): + out, err = io.StringIO(), io.StringIO() + assert main([str(tmp_path)], out=out, err=err) == EXIT_ERROR + assert "not a git repository" in err.getvalue() + + def test_not_a_directory(self, tmp_path): + err = io.StringIO() + assert main([str(tmp_path / "nope")], out=io.StringIO(), err=err) == EXIT_ERROR + assert "not a directory" in err.getvalue() + + def test_no_workflows_is_an_error_not_a_pass(self, repo): + """The whole point of this tool is that a check which did not run + must not look like a check that passed.""" + repo.write("README.md") + repo.commit() + err = io.StringIO() + assert main([repo.path], out=io.StringIO(), err=err) == EXIT_ERROR + assert ".github/workflows" in err.getvalue() + + def test_bad_ref(self, healthy): + code, _, err = run(healthy, "--ref", "nope") + assert code == EXIT_ERROR + assert "no such revision: nope" in err + + def test_unreadable_workflow(self, repo): + repo.workflow("ci.yml", "name: [\n") + repo.commit() + code, _, err = run(repo) + assert code == EXIT_ERROR + assert "not valid YAML" in err + + def test_unparseable_pattern_is_an_error_not_a_pass(self, repo): + """A pattern we cannot read means we cannot say whether the filter is + dead. Exit 2, not a green tick.""" + repo.write("src/main.py") + repo.workflow( + "ci.yml", "name: CI\non:\n push:\n paths: ['src/[!x]/**']\njobs: {}\n" + ) + repo.commit() + code, _, err = run(repo) + assert code == EXIT_ERROR + assert "on.push.paths" in err + + +class TestRef: + def test_ref_reads_the_workflows_at_that_revision(self, repo): + repo.write("src/main.py") + repo.workflow( + "ci.yml", "name: CI\non:\n push:\n paths: ['src/**']\njobs: {}\n" + ) + first = repo.commit() + repo.workflow( + "ci.yml", "name: CI\non:\n push:\n paths: ['lib/**']\njobs: {}\n" + ) + repo.commit() + + assert run(repo)[0] == EXIT_DEAD + assert run(repo, "--ref", first)[0] == EXIT_OK diff --git a/tests/test_cron.py b/tests/test_cron.py new file mode 100644 index 0000000..2263c02 --- /dev/null +++ b/tests/test_cron.py @@ -0,0 +1,111 @@ +"""Cron parsing, and the day-of-month / day-of-week OR rule.""" + +from __future__ import annotations + +import pytest + +from deadtrigger.cron import CronError, impossible_reason, parse + + +def impossible(text: str) -> str | None: + return impossible_reason(parse(text)) + + +class TestParse: + def test_every_minute(self): + cron = parse("* * * * *") + assert len(cron.minutes) == 60 + assert len(cron.hours) == 24 + assert not cron.dom_restricted + assert not cron.dow_restricted + + def test_a_real_schedule(self): + cron = parse("30 5,17 * * *") + assert cron.minutes == {30} + assert cron.hours == {5, 17} + + def test_step(self): + assert parse("*/15 * * * *").minutes == {0, 15, 30, 45} + + def test_range_with_step(self): + assert parse("0 9-17/4 * * *").hours == {9, 13, 17} + + def test_range(self): + assert parse("0 0 * * 1-5").days_of_week == {1, 2, 3, 4, 5} + + def test_names(self): + assert parse("0 0 1 JAN,DEC *").months == {1, 12} + assert parse("0 0 * * MON-FRI").days_of_week == {1, 2, 3, 4, 5} + + def test_names_are_case_insensitive(self): + assert parse("0 0 * * sun").days_of_week == {0} + + def test_seven_is_sunday(self): + """Vixie cron accepts 7 for Sunday; calling it invalid would be a + false report on a schedule that runs fine.""" + assert parse("0 0 * * 7").days_of_week == {0} + assert parse("0 0 * * 0,7").days_of_week == {0} + + def test_value_with_step_runs_to_the_top_of_the_field(self): + assert parse("5/20 * * * *").minutes == {5, 25, 45} + + +class TestParseErrors: + @pytest.mark.parametrize( + "text", + [ + "* * * *", # four fields + "* * * * * *", # six -- seconds, which cron does not have + "", + "60 * * * *", # minute 60 + "* 24 * * *", # hour 24 + "0 0 0 * *", # day of month 0 + "0 0 * 13 *", # month 13 + "0 0 * * 8", # day of week 8 + "0 0 * * MOO", + "0 0 * * 5-1", # reversed range + "*/0 * * * *", # zero step + "0,, * * * *", + "@daily", # GitHub does not take the nicknames + ], + ) + def test_rejected(self, text): + with pytest.raises(CronError): + parse(text) + + def test_not_a_string(self): + """`- cron: 5` in YAML arrives here as an int.""" + with pytest.raises(CronError): + parse(5) + + +class TestImpossible: + def test_ordinary_schedules_are_possible(self): + assert impossible("0 3 * * *") is None + assert impossible("30 5 1 * *") is None + assert impossible("0 0 * * 1") is None + + def test_february_30th(self): + assert impossible("0 0 30 2 *") == "day 30 does not occur in February" + + def test_april_31st(self): + assert impossible("0 0 31 4 *") is not None + + def test_february_29th_is_possible(self): + """Leap years happen. A schedule can legitimately want one.""" + assert impossible("0 0 29 2 *") is None + + def test_one_reachable_month_is_enough(self): + """31 is impossible in April but fine in May.""" + assert impossible("0 0 31 4,5 *") is None + + def test_one_reachable_day_is_enough(self): + assert impossible("0 0 28,31 2 *") is None + + def test_day_of_week_rescues_an_impossible_day_of_month(self): + """cron ORs the two day fields when both are restricted, so this + fires every Monday in February and is not dead.""" + assert impossible("0 0 30 2 1") is None + + def test_all_impossible_days_across_all_short_months(self): + assert impossible("0 0 31 2,4,6,9,11 *") is not None diff --git a/tests/test_ifexpr.py b/tests/test_ifexpr.py new file mode 100644 index 0000000..9454571 --- /dev/null +++ b/tests/test_ifexpr.py @@ -0,0 +1,128 @@ +"""Job conditions: decided when they can be, refused when they cannot.""" + +from __future__ import annotations + +import pytest + +from deadtrigger.ifexpr import Unsupported, satisfiable_events, strip_expression + +PUSH_ONLY = ["push"] +PUSH_AND_PR = ["push", "pull_request"] + + +class TestDecided: + def test_matching_event(self): + assert satisfiable_events("github.event_name == 'push'", PUSH_AND_PR) == ["push"] + + def test_event_the_workflow_never_receives(self): + assert satisfiable_events("github.event_name == 'schedule'", PUSH_AND_PR) == [] + + def test_braces_are_optional(self): + condition = "${{ github.event_name == 'schedule' }}" + assert satisfiable_events(condition, PUSH_AND_PR) == [] + + def test_or_chain(self): + condition = "github.event_name == 'push' || github.event_name == 'schedule'" + assert satisfiable_events(condition, PUSH_AND_PR) == ["push"] + + def test_or_chain_with_no_live_branch(self): + condition = "github.event_name == 'schedule' || github.event_name == 'release'" + assert satisfiable_events(condition, PUSH_AND_PR) == [] + + def test_and_of_two_events_is_never_true(self): + """A single run has one event name, so this is always false -- + a real mistake, usually meant as ||.""" + condition = "github.event_name == 'push' && github.event_name == 'pull_request'" + assert satisfiable_events(condition, PUSH_AND_PR) == [] + + def test_negation(self): + condition = "github.event_name != 'push'" + assert satisfiable_events(condition, PUSH_ONLY) == [] + assert satisfiable_events(condition, PUSH_AND_PR) == ["pull_request"] + + def test_bang_operator(self): + condition = "!(github.event_name == 'push')" + assert satisfiable_events(condition, PUSH_ONLY) == [] + + def test_parentheses(self): + condition = ( + "(github.event_name == 'push' || github.event_name == 'schedule') " + "&& github.event_name != 'schedule'" + ) + assert satisfiable_events(condition, PUSH_AND_PR) == ["push"] + + def test_literal_false(self): + assert satisfiable_events("false", PUSH_AND_PR) == [] + + def test_yaml_boolean_false(self): + """`if: false` with no quotes arrives from YAML as a bool.""" + assert satisfiable_events(False, PUSH_AND_PR) == [] + + def test_literal_true(self): + assert satisfiable_events("true", PUSH_AND_PR) == PUSH_AND_PR + + def test_bare_event_name_is_truthy(self): + """A non-empty string is true in GitHub's expression language.""" + assert satisfiable_events("github.event_name", PUSH_AND_PR) == PUSH_AND_PR + + def test_quoted_string_with_escaped_quote(self): + condition = "github.event_name == 'it''s'" + assert satisfiable_events(condition, PUSH_AND_PR) == [] + + +class TestRefused: + """Everything here must raise rather than guess. A wrong accusation is + worse than a missed finding.""" + + @pytest.mark.parametrize( + "condition", + [ + "github.ref == 'refs/heads/main'", + "needs.build.result == 'success'", + "success()", + "github.event.pull_request.draft == false", + "github.event_name == 'push' && github.ref == 'refs/heads/main'", + "contains(github.event_name, 'push')", + "matrix.os == 'ubuntu-latest'", + "env.DEPLOY == 'yes'", + ], + ) + def test_unsupported_conditions(self, condition): + with pytest.raises(Unsupported): + satisfiable_events(condition, PUSH_AND_PR) + + def test_boolean_against_string_is_refused(self): + """GitHub coerces mixed types to numbers. Not guessing at that.""" + with pytest.raises(Unsupported): + satisfiable_events("github.event_name == true", PUSH_AND_PR) + + def test_template_with_literal_text_is_refused(self): + with pytest.raises(Unsupported): + satisfiable_events("run-${{ github.event_name }}", PUSH_AND_PR) + + def test_unbalanced_parentheses(self): + with pytest.raises(Unsupported): + satisfiable_events("(github.event_name == 'push'", PUSH_AND_PR) + + def test_trailing_junk(self): + with pytest.raises(Unsupported): + satisfiable_events("github.event_name == 'push' 'x'", PUSH_AND_PR) + + def test_empty(self): + with pytest.raises(Unsupported): + satisfiable_events("", PUSH_AND_PR) + + def test_none(self): + with pytest.raises(Unsupported): + satisfiable_events(None, PUSH_AND_PR) + + +class TestStripExpression: + def test_plain(self): + assert strip_expression(" a == 'b' ") == "a == 'b'" + + def test_braces(self): + assert strip_expression("${{ a == 'b' }}") == "a == 'b'" + + def test_yaml_true(self): + assert strip_expression(True) == "true" diff --git a/tests/test_workflows.py b/tests/test_workflows.py new file mode 100644 index 0000000..cb8971b --- /dev/null +++ b/tests/test_workflows.py @@ -0,0 +1,130 @@ +"""Reading workflow files, including the `on:` key that isn't called "on".""" + +from __future__ import annotations + +import pytest +import yaml + +from deadtrigger.workflows import ( + WorkflowError, + as_list, + is_workflow_path, + normalise_triggers, + parse, + trigger_block, +) + + +def test_yaml_really_does_parse_on_as_a_boolean(): + """The premise of trigger_block, asserted against PyYAML rather than + against our own code. If a future YAML 1.2 loader changes this, the + special case becomes dead weight and this test says so.""" + document = yaml.safe_load("on:\n push:\n") + assert "on" not in document + assert True in document + + +def test_trigger_block_finds_the_boolean_key(): + assert trigger_block(yaml.safe_load("on:\n push:\n")) == {"push": None} + + +def test_trigger_block_finds_a_quoted_on(): + assert trigger_block(yaml.safe_load('"on":\n push:\n')) == {"push": None} + + +def test_trigger_block_absent(): + assert trigger_block({"name": "x"}) is None + + +class TestNormaliseTriggers: + def test_scalar(self): + assert normalise_triggers("push") == {"push": {}} + + def test_sequence(self): + assert normalise_triggers(["push", "pull_request"]) == { + "push": {}, + "pull_request": {}, + } + + def test_mapping_with_empty_event(self): + assert normalise_triggers({"push": None}) == {"push": {}} + + def test_mapping_with_filters(self): + raw = {"push": {"branches": ["main"]}} + assert normalise_triggers(raw)["push"]["branches"] == ["main"] + + def test_schedule_stays_a_list(self): + """schedule is a sequence, not a mapping. Flattening it to {} would + throw away every cron in the repository.""" + raw = {"schedule": [{"cron": "0 0 * * *"}]} + assert normalise_triggers(raw)["schedule"] == [{"cron": "0 0 * * *"}] + + def test_none(self): + assert normalise_triggers(None) == {} + + +class TestIsWorkflowPath: + @pytest.mark.parametrize( + "path", [".github/workflows/ci.yml", ".github/workflows/release.yaml"] + ) + def test_yes(self, path): + assert is_workflow_path(path) + + @pytest.mark.parametrize( + "path", + [ + ".github/workflows/shared/ci.yml", # GitHub does not recurse + ".github/workflow/ci.yml", + "workflows/ci.yml", + ".github/workflows/README.md", + ".github/workflows/ci.yml.bak", + ], + ) + def test_no(self, path): + assert not is_workflow_path(path) + + +class TestParse: + def test_name_and_triggers(self): + flow = parse("name: CI\non:\n push:\njobs:\n a:\n steps: []\n", "p.yml") + assert flow.declared_name == "CI" + assert flow.display_name == "CI" + assert flow.events == ["push"] + assert list(flow.jobs) == ["a"] + + def test_unnamed_workflow_displays_as_its_path(self): + """GitHub falls back to the file path when there is no name:, and + that fallback is what workflow_run has to match against.""" + flow = parse("on:\n push:\n", ".github/workflows/ci.yml") + assert flow.declared_name is None + assert flow.display_name == ".github/workflows/ci.yml" + + def test_empty_name_is_no_name(self): + assert parse("name: ''\non: push\n", "p.yml").declared_name is None + + def test_no_jobs(self): + assert parse("on: push\n", "p.yml").jobs == {} + + @pytest.mark.parametrize( + "text,fragment", + [ + ("", "empty"), + ("- a\n- b\n", "not a mapping"), + ("name: [\n", "not valid YAML"), + ], + ) + def test_rejected(self, text, fragment): + with pytest.raises(WorkflowError) as caught: + parse(text, "p.yml") + assert fragment in str(caught.value) + + +class TestAsList: + def test_scalar(self): + assert as_list("main") == ["main"] + + def test_list(self): + assert as_list(["a", "b"]) == ["a", "b"] + + def test_none(self): + assert as_list(None) == [] From 715338d9d033fc398b5aadf8546153cfc407751e Mon Sep 17 00:00:00 2001 From: "richmond-avenal[bot]" <323733923+richmond-avenal[bot]@users.noreply.github.com> Date: Wed, 9 Sep 2026 06:25:31 +0000 Subject: [PATCH 3/6] feat: check the working tree by default, and name the directory mistake --ref now means "at that revision instead"; with no --ref the tool reads the workflow files as they are on disk, which is the moment the answer can still save you a push. Candidate files still come from git, so an untracked build directory cannot make a dead path filter look alive. An unmatched path pattern that names a real directory now says so: crates/ruff_db matches no changed file, crates/ruff_db/** does. --- src/deadtrigger/cli.py | 53 +++++++++++++++++++++++++-------------- src/deadtrigger/core.py | 30 +++++++++++++++++++--- src/deadtrigger/gitcmd.py | 26 +++++++++++++++++-- tests/test_cli.py | 39 ++++++++++++++++++++++++++++ 4 files changed, 123 insertions(+), 25 deletions(-) diff --git a/src/deadtrigger/cli.py b/src/deadtrigger/cli.py index fb8ec59..ca9c99d 100644 --- a/src/deadtrigger/cli.py +++ b/src/deadtrigger/cli.py @@ -22,6 +22,7 @@ import json import os import sys +import textwrap from . import gitcmd, workflows from .core import ( @@ -43,16 +44,6 @@ EXIT_DEAD = 1 EXIT_ERROR = 2 -HEADLINE = { - NO_SUCH_WORKFLOW: "names a workflow that does not exist", - OFF_DEFAULT_BRANCH: "is on the wrong branch to ever fire", - DEAD_CRON: "is a schedule that never comes round", - UNMATCHED_REF: "names a branch or tag that does not exist", - DEAD_PATH_FILTER: "cannot be satisfied by any file in the repository", - UNMATCHED_PATH: "matches no file in the repository", - IMPOSSIBLE_IF: "is a condition that is never true", -} - ORDER = [ OFF_DEFAULT_BRANCH, NO_SUCH_WORKFLOW, @@ -77,8 +68,11 @@ def build_parser() -> argparse.ArgumentParser: help="a path inside the repository to check (default: the current directory)", ) parser.add_argument( - "--ref", default="HEAD", - help="check the workflows as they are at this revision (default: HEAD)", + "--ref", default=None, + help=( + "check the workflows as they were at this revision, instead of as " + "they are on disk now" + ), ) parser.add_argument( "--default-branch", default=None, metavar="NAME", @@ -91,8 +85,13 @@ def build_parser() -> argparse.ArgumentParser: return parser -def _load(repo_root: str, ref: str) -> list: - """Every workflow file at ``ref``, parsed.""" +def _load(repo_root: str, ref: str | None) -> list: + """Every workflow file, parsed. + + With no --ref this reads the files as they are on disk, so that you can + edit a filter and find out whether it is dead before committing it -- + which is the moment the answer is worth anything. + """ paths = sorted( path for path in gitcmd.tracked_files(repo_root, ref) @@ -100,8 +99,12 @@ def _load(repo_root: str, ref: str) -> list: ) sheet = [] for path in paths: - text = gitcmd.show(ref, path, repo_root) - if text is None: # pragma: no cover - ls-tree just said it is there + text = ( + gitcmd.read_worktree(repo_root, path) + if ref is None + else gitcmd.show(ref, path, repo_root) + ) + if text is None: # pragma: no cover - git just said it is there continue sheet.append(workflows.parse(text, path)) return sheet @@ -120,7 +123,17 @@ def _print_human(report, out) -> None: for finding in by_kind.get(kind, []): print(f" {finding.workflow}", file=out) print(f" {finding.where}: {finding.subject}", file=out) - print(f" {HEADLINE[kind]} -- {finding.detail}", file=out) + # The kind is printed rather than a prose headline so that what + # you grep for in the terminal is the same string --json gives. + print( + textwrap.fill( + f"{kind}: {finding.detail}", + width=80, + initial_indent=" " * 6, + subsequent_indent=" " * 6, + ), + file=out, + ) print(file=out) checked = _plural(report.workflows_checked, "workflow") @@ -146,15 +159,17 @@ def main(argv: list[str] | None = None, out=None, err=None) -> int: try: root = gitcmd.repo_root(args.path) - gitcmd.resolve(args.ref, root) + if args.ref is not None: + gitcmd.resolve(args.ref, root) sheet = _load(root, args.ref) except (GitError, WorkflowError) as exc: print(f"deadtrigger: {exc}", file=err) return EXIT_ERROR if not sheet: + where = f" at {args.ref}" if args.ref else "" print( - f"deadtrigger: no workflow files in {WORKFLOW_DIR}/ at {args.ref}", + f"deadtrigger: no workflow files in {WORKFLOW_DIR}/{where}", file=err, ) return EXIT_ERROR diff --git a/src/deadtrigger/core.py b/src/deadtrigger/core.py index a0a41ed..c85c5a6 100644 --- a/src/deadtrigger/core.py +++ b/src/deadtrigger/core.py @@ -15,6 +15,7 @@ from __future__ import annotations from dataclasses import dataclass, field +from functools import cached_property from . import cron as croncheck from . import ifexpr, workflows @@ -81,6 +82,21 @@ class Repo: # Workflow paths present on the default branch, or None if we cannot see it. default_branch_workflows: set[str] | None = None + @cached_property + def directories(self) -> set[str]: + """Every directory in the tree, as a path with no trailing slash. + + Only used to tell one kind of dead path filter from another: a + pattern naming a real directory is the `docs` / `docs/**` mistake, + and saying so is more use than "matches nothing". + """ + found: set[str] = set() + for path in self.files: + parts = path.split("/")[:-1] + for index in range(1, len(parts) + 1): + found.add("/".join(parts[:index])) + return found + def check(sheet: list[Workflow], repo: Repo) -> Report: report = Report(workflows_checked=len(sheet)) @@ -270,10 +286,16 @@ def _check_path_filter(flow, event, key, raw, repo: Repo, report: Report) -> Non # An exclusion that currently excludes nothing is a guard against # files that do not exist yet. That is what a guard is for. continue - report.add( - UNMATCHED_PATH, flow.path, where, pattern.text, - "matches no file in the repository", - ) + + if pattern.text in repo.directories: + detail = ( + f"{pattern.text} is a directory, and a path filter is matched " + f"against the paths of changed *files*. Editing anything under " + f"it does not trigger this workflow -- {pattern.text}/** does" + ) + else: + detail = "no file in the repository is matched by it" + report.add(UNMATCHED_PATH, flow.path, where, pattern.text, detail) def _check_jobs(flow: Workflow, report: Report) -> None: diff --git a/src/deadtrigger/gitcmd.py b/src/deadtrigger/gitcmd.py index 46f433b..8858c19 100644 --- a/src/deadtrigger/gitcmd.py +++ b/src/deadtrigger/gitcmd.py @@ -14,6 +14,7 @@ from __future__ import annotations +import os import subprocess @@ -53,13 +54,19 @@ def is_shallow(cwd: str) -> bool: return run_git(["rev-parse", "--is-shallow-repository"], cwd).strip() == "true" -def tracked_files(cwd: str, ref: str) -> list[str]: +def tracked_files(cwd: str, ref: str | None = None) -> list[str]: """Every file at ``ref``, as repo-root-relative paths. + With no ref this is the index rather than a commit, so that editing a + workflow and running the tool tells you something before you commit it. + ``-z`` because a newline in a path is legal in git, rare, and exactly the sort of thing that would make a checker quietly miscount. """ - out = run_git(["ls-tree", "-r", "-z", "--name-only", ref], cwd) + if ref is None: + out = run_git(["ls-files", "-z", "--cached"], cwd) + else: + out = run_git(["ls-tree", "-r", "-z", "--name-only", ref], cwd) return [path for path in out.split("\0") if path] @@ -71,6 +78,21 @@ def show(ref: str, relpath: str, cwd: str) -> str | None: return None +def read_worktree(root: str, relpath: str) -> str | None: + """Contents of a tracked file as it is right now. + + Falls back to the index for a file that is tracked but not on disk -- + staged deletions and sparse checkouts both produce that, and neither is + a reason to stop checking. + """ + full = os.path.join(root, relpath) + try: + with open(full, encoding="utf-8", errors="replace") as handle: + return handle.read() + except OSError: + return show("", relpath, root) + + def _strip_remote(refname: str) -> str | None: """``refs/remotes/origin/feature/x`` -> ``feature/x``. diff --git a/tests/test_cli.py b/tests/test_cli.py index 96f86a7..49f9754 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -481,6 +481,45 @@ def test_unparseable_pattern_is_an_error_not_a_pass(self, repo): assert "on.push.paths" in err +class TestUncommittedWork: + """With no --ref the answer is about the files as they are now, which is + the only moment at which it can still save you a push.""" + + def test_a_staged_workflow_is_checked(self, repo): + repo.write("src/main.py") + repo.workflow("ci.yml", "name: CI\non:\n push:\n paths: ['nope/**']\njobs: {}\n") + assert run(repo)[0] == EXIT_DEAD + + def test_an_uncommitted_edit_is_checked(self, repo): + repo.write("src/main.py") + repo.workflow("ci.yml", "name: CI\non:\n push:\n paths: ['src/**']\njobs: {}\n") + repo.commit() + assert run(repo)[0] == EXIT_OK + + # Edited on disk, not staged, not committed. + import os + + with open( + os.path.join(repo.path, ".github/workflows/ci.yml"), "w", encoding="utf-8" + ) as handle: + handle.write("name: CI\non:\n push:\n paths: ['lib/**']\njobs: {}\n") + assert run(repo)[0] == EXIT_DEAD + + def test_untracked_files_are_not_counted_as_matches(self, repo): + """git decides what is in the repository, not the filesystem: a build + directory nobody committed must not make a path filter look alive.""" + repo.write("src/main.py") + repo.workflow("ci.yml", "name: CI\non:\n push:\n paths: ['build/**']\njobs: {}\n") + repo.commit() + + import os + + os.makedirs(os.path.join(repo.path, "build")) + with open(os.path.join(repo.path, "build/out.o"), "w") as handle: + handle.write("x") + assert run(repo)[0] == EXIT_DEAD + + class TestRef: def test_ref_reads_the_workflows_at_that_revision(self, repo): repo.write("src/main.py") From 2962cd542e87369da289521d28299507ec19c254 Mon Sep 17 00:00:00 2001 From: "richmond-avenal[bot]" <323733923+richmond-avenal[bot]@users.noreply.github.com> Date: Wed, 9 Sep 2026 06:27:00 +0000 Subject: [PATCH 4/6] feat: CI, and a default branch that resolves the way CI leaves it On a pull request actions/checkout leaves the default branch existing only as refs/remotes/origin/main, where `git rev-parse main` fails. The first version took that at face value, so --default-branch would have quietly checked nothing on every CI run -- the one place it is needed. The dogfood job uses fetch-depth: 0 because that is the advice the tool prints when it declines the branch checks, so the job is also the test that the advice works. --- .github/workflows/ci.yml | 80 +++++++++++++++++++++++++++++++++++++++ src/deadtrigger/cli.py | 22 ++++++----- src/deadtrigger/gitcmd.py | 28 +++++++++++--- tests/test_cli.py | 38 +++++++++++++++++++ 4 files changed, 152 insertions(+), 16 deletions(-) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..1f1de68 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,80 @@ +name: test + +on: + push: + branches: [main] + pull_request: + +jobs: + test: + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + python-version: ["3.10", "3.12"] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + # The tests build real repositories and make real commits in them. + # Each one sets a local identity, so this is only a backstop against a + # runner with no global one at all. + - run: | + git config --global user.name "ci" + git config --global user.email "ci@example.invalid" + - run: pip install -e ".[dev]" + - run: python -m pytest + + dogfood: + # Run the tool on this repository, for real. + # + # fetch-depth: 0 is not incidental -- it is the advice the tool gives + # when it declines the branch checks, so this job is also the test that + # the advice works. If a future change stops the branch checks running + # under a full clone, the last step here goes red. + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: pip install -e . + + - name: our own workflows are alive + run: deadtrigger --default-branch main + + # `code=0; cmd || code=$?` rather than `cmd; code=$?`, because these + # steps run under `bash -e` and the whole point is to run a command + # that exits non-zero. + - name: a dead path filter is caught + run: | + cat > .github/workflows/scratch.yml <<'YAML' + name: Scratch + on: + push: + paths: ['no/such/directory/**'] + jobs: + a: + runs-on: ubuntu-latest + steps: [{run: 'true'}] + YAML + code=0; deadtrigger --default-branch main || code=$? + rm .github/workflows/scratch.yml + test "$code" -eq 1 || { echo "expected exit 1, got $code"; exit 1; } + + - name: a revision that does not exist is an error, not a pass + run: | + code=0; deadtrigger --ref no-such-revision || code=$? + test "$code" -eq 2 || { echo "expected exit 2, got $code"; exit 1; } + + - name: nothing is left unchecked in a full clone + run: | + deadtrigger --default-branch main > report.txt + if grep -q '^not checked:' report.txt; then + cat report.txt + echo "a check declined to run in a full clone" + exit 1 + fi diff --git a/src/deadtrigger/cli.py b/src/deadtrigger/cli.py index ca9c99d..5002eb1 100644 --- a/src/deadtrigger/cli.py +++ b/src/deadtrigger/cli.py @@ -206,16 +206,18 @@ def _describe(root: str, args) -> Repo: default_branch = args.default_branch or gitcmd.default_branch(root) default_workflows = None - if default_branch is not None and gitcmd.ref_exists(default_branch, root): - default_workflows = { - path - for path in gitcmd.tracked_files(root, default_branch) - if workflows.is_workflow_path(path) - } - elif default_branch is not None: - # Named a default branch this clone does not have. Better to check - # nothing than to report every workflow as stranded off it. - default_branch = None + if default_branch is not None: + rev = gitcmd.resolve_branch(default_branch, root) + if rev is None: + # Named a default branch this clone does not have. Better to + # check nothing than to report every workflow as stranded off it. + default_branch = None + else: + default_workflows = { + path + for path in gitcmd.tracked_files(root, rev) + if workflows.is_workflow_path(path) + } return Repo( files=gitcmd.tracked_files(root, args.ref), diff --git a/src/deadtrigger/gitcmd.py b/src/deadtrigger/gitcmd.py index 8858c19..ac70aba 100644 --- a/src/deadtrigger/gitcmd.py +++ b/src/deadtrigger/gitcmd.py @@ -142,9 +142,25 @@ def default_branch(cwd: str) -> str | None: return _strip_remote(out) if out.startswith("refs/remotes/") else None -def ref_exists(rev: str, cwd: str) -> bool: - try: - resolve(rev, cwd) - return True - except GitError: - return False +def resolve_branch(name: str, cwd: str) -> str | None: + """A branch name as something git can actually resolve, or None. + + Worth the trouble because of the case this tool most needs to get right: + on a pull request, ``actions/checkout`` leaves ``main`` existing only as + ``refs/remotes/origin/main``, and plain ``git rev-parse main`` fails + there. Taking that failure at face value would make --default-branch + silently do nothing on every CI run -- the one place it is needed. + """ + for candidate in (f"refs/heads/{name}", f"refs/remotes/origin/{name}", name): + try: + resolve(candidate, cwd) + return candidate + except GitError: + continue + + out = run_git(["for-each-ref", "--format=%(refname)", "refs/remotes"], cwd) + for line in out.splitlines(): + line = line.strip() + if _strip_remote(line) == name: + return line + return None diff --git a/tests/test_cli.py b/tests/test_cli.py index 49f9754..c80c043 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -389,6 +389,44 @@ def test_push_only_workflow_off_the_default_branch_is_fine(self, repo): repo.commit() assert run(repo, "--default-branch", "main")[0] == EXIT_OK + def test_default_branch_that_only_exists_as_a_remote_ref(self, repo, tmp_path): + """The shape actions/checkout leaves behind on a pull request: the + default branch is refs/remotes/origin/main and nothing else, where + plain `git rev-parse main` fails. If --default-branch quietly did + nothing here it would do nothing on every CI run.""" + repo.write("README.md") + repo.commit() + repo.git("checkout", "-q", "-b", "topic") + repo.workflow( + "nightly.yml", + "name: N\non:\n schedule:\n - cron: '0 3 * * *'\njobs: {}\n", + ) + repo.commit() + + import subprocess + + clone = tmp_path / "pr" + subprocess.run( + ["git", "clone", "-q", "--no-checkout", "file://" + repo.path, str(clone)], + check=True, capture_output=True, + ) + # --no-checkout never creates a local `main`, so after this the only + # trace of the default branch is refs/remotes/origin/main. + subprocess.run( + ["git", "checkout", "-q", "-b", "pr-merge", "origin/topic"], + cwd=clone, check=True, capture_output=True, + ) + assert subprocess.run( + ["git", "rev-parse", "--verify", "--quiet", "main^{commit}"], + cwd=clone, capture_output=True, + ).returncode != 0 + + out = io.StringIO() + code = main([str(clone), "--default-branch", "main"], out=out, err=io.StringIO()) + assert "not checked: default-branch-only triggers" not in out.getvalue() + assert code == EXIT_DEAD + assert "off-default-branch" in out.getvalue() + def test_check_is_named_as_skipped_when_the_default_branch_is_unknown(self, repo): repo.workflow("ci.yml", "name: CI\non: push\njobs: {}\n") repo.commit() From cc514b75b47548dd71f0a9093c19810154dccccd Mon Sep 17 00:00:00 2001 From: "richmond-avenal[bot]" <323733923+richmond-avenal[bot]@users.noreply.github.com> Date: Wed, 9 Sep 2026 06:28:58 +0000 Subject: [PATCH 5/6] docs: README, with the example run verbatim and the limits stated --- README.md | 250 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 249 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7cedc9c..e87afe3 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,251 @@ # deadtrigger -Find the GitHub Actions workflows that can never run. +Finds GitHub Actions workflows that can never run, by checking their triggers +against the repository they are actually in. It is for anyone who has ever +pushed a change, waited for a workflow, and slowly worked out that it was +never going to start. + +A workflow that fails is loud. A workflow that is never triggered at all looks +exactly like a workflow with nothing to do: no run, no annotation, no red tick, +nothing in the Actions tab to click on. `deadtrigger` is the thing that +notices. + +## Install + +``` +pip install git+https://github.com/committed-nightly/deadtrigger +``` + +Python 3.10 or newer. One dependency, PyYAML. + +## Use + +``` +cd your-repo +deadtrigger +``` + +It reads the workflow files as they are on disk, so you can check a filter +before you commit it. `--ref` checks a revision instead, `--json` gives you +the same findings in a form you can pipe somewhere. + +## A real example + +Four workflows, none of which is obviously wrong: + +```bash +mkdir demo && cd demo && git init -b main +mkdir -p src docs .github/workflows +echo "print('hi')" > src/app.py +echo "# docs" > docs/index.md + +cat > .github/workflows/ci.yml <<'YAML' +name: CI +on: + push: + branches: [master] +jobs: + test: + runs-on: ubuntu-latest + steps: [{run: pytest}] +YAML + +cat > .github/workflows/docs.yml <<'YAML' +name: Docs +on: + pull_request: + paths: + - src/** + - docs +jobs: + build: + runs-on: ubuntu-latest + steps: [{run: make html}] +YAML + +cat > .github/workflows/nightly.yml <<'YAML' +name: Nightly +on: + schedule: + - cron: '0 0 30 2 *' +jobs: + soak: + runs-on: ubuntu-latest + steps: [{run: make soak}] +YAML + +cat > .github/workflows/publish.yml <<'YAML' +name: Publish +on: + workflow_run: + workflows: [Build] + types: [completed] +jobs: + upload: + runs-on: ubuntu-latest + steps: [{run: make upload}] +YAML + +git add -A && git commit -qm "a plausible looking set of workflows" +deadtrigger --default-branch main +``` + +``` + .github/workflows/publish.yml + on.workflow_run.workflows: 'Build' + no-such-workflow: no workflow in .github/workflows has this name, so + nothing can ever trigger this one + + .github/workflows/nightly.yml + on.schedule: '0 0 30 2 *' + dead-cron: valid cron for a date that never happens: day 30 does not occur + in February + + .github/workflows/ci.yml + on.push.branches: master + unmatched-ref: no branch in this repository is called that + + .github/workflows/docs.yml + on.pull_request.paths: docs + unmatched-path: docs is a directory, and a path filter is matched against + the paths of changed *files*. Editing anything under it does not trigger + this workflow -- docs/** does + +4 workflows checked, 4 findings +``` + +Four workflows, four ways of never running, and not one of them would show up +as a failure anywhere. The `docs` one is the meanest: `src/**` is right there +next to it and works, so the workflow does run — just never for a +documentation change, which is the only thing it was for. + +## What it checks + +| kind | what it means | +| --- | --- | +| `no-such-workflow` | `on.workflow_run.workflows` names a workflow no file in `.github/workflows` is called | +| `off-default-branch` | `schedule`, `workflow_dispatch` or `workflow_run` on a workflow that is not on the default branch, where GitHub never delivers them | +| `dead-cron` | a cron GitHub will not accept, or one describing a date that does not happen | +| `unmatched-ref` | a branch or tag filter naming a ref that does not exist | +| `dead-path-filter` | a `paths:` list that no file in the repository satisfies, so the event can never start the workflow | +| `unmatched-path` | one pattern in a path filter that matches no file | +| `impossible-if` | a job `if:` that no event this workflow receives can make true | + +Exit codes, because this is meant to sit in CI: **0** everything can fire, +**1** something cannot, **2** the check could not run — no repository, no +workflows, a revision that does not resolve, a filter pattern that cannot be +parsed. 2 is deliberately not 0. A checker that passes when it did not run is +the failure this whole tool exists to catch. + +## In CI + +```yaml +- uses: actions/checkout@v4 + with: + fetch-depth: 0 +- run: pip install git+https://github.com/committed-nightly/deadtrigger +- run: deadtrigger --default-branch ${{ github.event.repository.default_branch }} +``` + +`fetch-depth: 0` matters. At the default depth `actions/checkout` leaves a +shallow clone holding one branch, and a tool that read that as "this +repository has one branch" would report every branch filter you own as dead. +Instead the branch and tag checks decline to run, and say so: + +``` +not checked: branch and tag filters -- this clone is shallow, so its branch +and tag lists are the ones fetched rather than the ones that exist +``` + +Every check that does not run is named in the output, on green runs too. + +## What it is not + +It is not a workflow linter, and if you are not already running one, run +[actionlint](https://github.com/rhysd/actionlint) first — it type-checks +expressions, shellchecks your `run:` blocks and catches far more than this +does. + +The difference is the input. actionlint reads a workflow file; `deadtrigger` +reads it *against the repository*. `branches: [master]` is valid YAML, valid +Actions and a perfectly good filter — the only thing wrong with it is that +this repository's branch is called `main`, which is not a fact any linter has. +Same for a `workflow_run` naming a workflow that was renamed last year, and +for a `paths` filter pointing at a directory that has moved. + +## Known limits + +**Filters can be legitimately forward-looking.** A `paths` filter can name a +directory you are about to add. That is reported anyway, because "nothing in +this repository can trigger this workflow today" is still true and still worth +knowing, but it is the false-positive case and the first thing to check. +Branch and tag filters get more slack: only patterns with *no wildcard in +them* are reported, because `release/**` in a repository with no release +branches is a filter waiting for a branch, which is a normal thing to write +and none of this tool's business. + +**`impossible-if` is the weakest check here.** It refuses any condition it +cannot decide with certainty, which in practice is most of them: across the +168 job conditions in the validation set below it reached a verdict on 6. +When it does fire it is right, and a job gated on an event its workflow no +longer has is genuinely invisible — but do not expect it to earn its keep on +your repository. + +**It does not guess at GitHub's expression evaluator.** Checking +`github.event.pull_request` on a workflow with no pull request trigger looks +like it belongs here, and it is a trap: the value is `null`, and `null == +false` compares 0 to 0 and is **true**, so the obvious reading of a draft +check comes out backwards. Refusing to answer beat guessing. + +**Not checked:** step-level `if:`, the five-minute floor on cron intervals +(GitHub runs those less often rather than never), and whether a +`workflow_call` workflow has any caller — a reusable workflow can be called +from another repository, and this only ever looks at one. + +## Where the matcher came from + +GitHub's filter patterns look like shell globs and are not: + +> `?` Matches zero or one of the **preceding character**. +> `+` Matches one or more of the **preceding character**. + +Those are regex quantifiers, which is why GitHub's own documented matches for +`*.jsx?` are `page.js` and `page.jsx` and not `page.jsz`. Anything built on +`fnmatch` gets this wrong. Every row of both tables in GitHub's [filter +pattern cheat sheet](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet) +is a case in `tests/test_pattern.py` with the documented example matches kept +verbatim, so if the matcher ever stops agreeing with the documentation it +fails by name. + +## Validation + +Run against 148 workflows in 18 repositories — `cli/cli`, `astral-sh/ruff`, +`tiangolo/fastapi`, `pydantic/pydantic`, `psf/black`, `pallets/flask`, +`actions/checkout`, `scrapy/scrapy` and others — covering 163 path patterns, +89 branch and tag patterns, 39 schedules and 5 `workflow_run` references. + +Three findings, all in one repository, all real: `astral-sh/ruff`'s typing +conformance workflow lists `crates/ruff_db`, `crates/ruff_python_ast` and +`crates/ruff_python_parser` in its `paths` filter, on the lines immediately +around `crates/ruff_python_edits/**`. Those three are directories, path +filters only ever match the paths of changed files, and so a change to any of +those three crates does not run that workflow. + +Seventeen of the eighteen came out clean. The honest reading is that +well-maintained repositories mostly do not have this problem, and that this is +a tool for the day you go looking for why something never ran. + +## Development + +``` +pip install -e ".[dev]" +python -m pytest +``` + +176 tests. The end-to-end ones build real git repositories and make real +commits in them, because the question this tool answers is about a repository, +and faking that away would leave the interesting part untested. + +## Licence + +MIT. From 13d03261cad03ad7827a8a1465887252ef43693e Mon Sep 17 00:00:00 2001 From: "richmond-avenal[bot]" <323733923+richmond-avenal[bot]@users.noreply.github.com> Date: Wed, 9 Sep 2026 06:31:58 +0000 Subject: [PATCH 6/6] fix: check workflow files that are not in git yet The dogfood job caught this: it wrote a workflow with a dead path filter, ran the tool, and got "1 workflow checked, clean". Candidate workflows were coming from the index, so a file nobody had `git add`ed was not examined at all -- and produced no findings and no warning, which is indistinguishable from a clean one. That is the exact failure this tool exists to catch, in the tool. Workflow files now come from the directory when no --ref is given. What they are checked against still comes from git: path filters match the paths of changed files, and an untracked build directory is not something anyone can change in a commit. --- README.md | 13 +++++++++---- src/deadtrigger/cli.py | 39 ++++++++++++++++++++++++++++++++++----- tests/test_cli.py | 19 +++++++++++++++++++ 3 files changed, 62 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index e87afe3..5e439d6 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,14 @@ cd your-repo deadtrigger ``` -It reads the workflow files as they are on disk, so you can check a filter -before you commit it. `--ref` checks a revision instead, `--json` gives you -the same findings in a form you can pipe somewhere. +It reads the workflow files as they are on disk — including one you have +written but not yet `git add`ed — so you can check a filter before you commit +it. What they are checked *against* still comes from git: an untracked build +directory is not something anyone can change in a commit, so it can't make a +dead path filter look alive. + +`--ref` checks a revision instead, `--json` gives you the same findings in a +form you can pipe somewhere. ## A real example @@ -242,7 +247,7 @@ pip install -e ".[dev]" python -m pytest ``` -176 tests. The end-to-end ones build real git repositories and make real +177 tests. The end-to-end ones build real git repositories and make real commits in them, because the question this tool answers is about a repository, and faking that away would leave the interesting part untested. diff --git a/src/deadtrigger/cli.py b/src/deadtrigger/cli.py index 5002eb1..ebc287e 100644 --- a/src/deadtrigger/cli.py +++ b/src/deadtrigger/cli.py @@ -85,6 +85,39 @@ def build_parser() -> argparse.ArgumentParser: return parser +def _workflow_paths(repo_root: str, ref: str | None) -> list[str]: + """The workflow files to check. + + With no --ref these come from the directory rather than from git, so a + workflow you have written but not yet added is checked. Taking them from + the index instead would mean a brand new workflow file produced no + findings and no warning -- indistinguishable from a clean one, which is + the exact failure this tool exists to catch. + + The repository *contents* still come from git either way. Path filters + are matched against the paths of changed files, and an untracked build + directory is not something anyone can change in a commit. + """ + if ref is not None: + return sorted( + path + for path in gitcmd.tracked_files(repo_root, ref) + if workflows.is_workflow_path(path) + ) + + directory = os.path.join(repo_root, WORKFLOW_DIR) + try: + names = os.listdir(directory) + except OSError: + return [] + return sorted( + f"{WORKFLOW_DIR}/{name}" + for name in names + if workflows.is_workflow_path(f"{WORKFLOW_DIR}/{name}") + and os.path.isfile(os.path.join(directory, name)) + ) + + def _load(repo_root: str, ref: str | None) -> list: """Every workflow file, parsed. @@ -92,11 +125,7 @@ def _load(repo_root: str, ref: str | None) -> list: edit a filter and find out whether it is dead before committing it -- which is the moment the answer is worth anything. """ - paths = sorted( - path - for path in gitcmd.tracked_files(repo_root, ref) - if workflows.is_workflow_path(path) - ) + paths = _workflow_paths(repo_root, ref) sheet = [] for path in paths: text = ( diff --git a/tests/test_cli.py b/tests/test_cli.py index c80c043..acf2f19 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -543,6 +543,25 @@ def test_an_uncommitted_edit_is_checked(self, repo): handle.write("name: CI\non:\n push:\n paths: ['lib/**']\njobs: {}\n") assert run(repo)[0] == EXIT_DEAD + def test_a_workflow_file_that_is_not_in_git_yet_is_still_checked(self, repo): + """A brand new workflow producing no findings and no warning would be + indistinguishable from a clean one. Workflow files come from the + directory; only the repository contents they are checked against come + from git.""" + repo.write("src/main.py") + repo.commit() + + import os + + os.makedirs(os.path.join(repo.path, ".github/workflows"), exist_ok=True) + with open( + os.path.join(repo.path, ".github/workflows/new.yml"), "w", encoding="utf-8" + ) as handle: + handle.write("name: New\non:\n push:\n paths: ['nope/**']\njobs: {}\n") + + assert repo.git("status", "--short", ".github").strip().startswith("??") + assert run(repo)[0] == EXIT_DEAD + def test_untracked_files_are_not_counted_as_matches(self, repo): """git decides what is in the repository, not the filesystem: a build directory nobody committed must not make a path filter look alive."""