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/README.md b/README.md index 7cedc9c..5e439d6 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,256 @@ # 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 — 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 + +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 +``` + +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. + +## Licence + +MIT. 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..ebc287e --- /dev/null +++ b/src/deadtrigger/cli.py @@ -0,0 +1,262 @@ +"""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 +import textwrap + +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 + +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=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", + 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 _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. + + 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 = _workflow_paths(repo_root, ref) + sheet = [] + for path in paths: + 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 + + +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) + # 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") + 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) + 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}/{where}", + 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: + 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), + 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..c85c5a6 --- /dev/null +++ b/src/deadtrigger/core.py @@ -0,0 +1,325 @@ +"""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 functools import cached_property + +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 + + @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)) + + 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 + + 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: + """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..ac70aba --- /dev/null +++ b/src/deadtrigger/gitcmd.py @@ -0,0 +1,166 @@ +"""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 os +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 | 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. + """ + 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] + + +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 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``. + + ``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 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/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/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/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..acf2f19 --- /dev/null +++ b/tests/test_cli.py @@ -0,0 +1,593 @@ +"""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_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() + _, 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 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_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.""" + 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") + 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_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) 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) == []