deadgate 0.1.0__tar.gz

deadgate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erik Hill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deadgate-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: deadgate
+Version: 0.1.0
+Summary: Find CI checks that cannot fail: gates satisfied by skipped jobs, exit statuses swallowed by pipes, fan-ins that never read whether their upstream passed.
+Author-email: Erik Hill <contact@erikhill.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/egnaro9/deadgate
+Project-URL: Repository, https://github.com/egnaro9/deadgate
+Project-URL: Issues, https://github.com/egnaro9/deadgate/issues
+Project-URL: How it was measured, https://github.com/egnaro9/deadgate/blob/main/MEASUREMENT.md
+Keywords: ci,github-actions,workflow,static-analysis,testing,mutation-testing,branch-protection,continuous-integration,devops
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# deadgate
+
+**Find CI checks that cannot fail.**
+
+Flaky-test tools find checks that fail randomly. This finds the opposite: checks that are
+structurally incapable of going red, so your pipeline is green for reasons unrelated to your code.
+
+GitHub documents the sharpest case itself:
+
+> A job that is skipped will report its status as `Success`. It will not prevent a pull
+> request from merging, even if it is a required check.
+
+```bash
+pip install deadgate
+deadgate .
+```
+
+Exit code is 1 when there are findings, 0 when clean, and **2 when a workflow file could not
+be parsed**. A file it could not read is never counted as a file with no problems.
+
+## What it detects
+
+| id | defect | why it matters |
+|----|--------|----------------|
+| D1 | a job depends on a skip-prone job and never reads `needs.*.result` | the dependency skips, reports Success, and the gate passes with nothing run |
+| D2 | a fan-in job runs on `always()` and never reads `needs.*.result` | it is green when the jobs it gates failed |
+| D3 | a `run:` step ends a pipeline in a filter with no `pipefail` | the step's status is the filter's, so an upstream failure passes |
+
+Every finding carries a reproduction. A finding without one is an opinion, and this tool
+does not emit opinions.
+
+## The calibration corpus is the specification
+
+`corpus/` holds workflows that are **known broken** and workflows that are **known good**, and
+the good ones are deliberate near misses of the broken ones. A detector has to fire on the
+defect *and* stay quiet on its near miss. A detector that fires on everything is as useless as
+one that fires on nothing, and it gets the whole tool switched off.
+
+```bash
+python -m pytest tests/
+```
+
+Fixtures `g6` and `g7` exist because the detectors were **wrong against real repositories while
+the corpus was green**:
+
+- `g6` a job guarding itself with a job-level `if:` that reads `needs.*.outputs` IS checking its
+  upstream. The first version only read step-level conditions and flagged correct jobs.
+- `g7` `if: ${{ !cancelled() }}` is not skip-prone. It runs in normal operation and on failure.
+  Treating every `if:` as a possible skip produced false alarms.
+
+Both were found by running against a real 25k-star repository, not by the suite. That is the
+argument this tool makes about everyone else's checks, so it is held to it too.
+
+## The branch-protection tier
+
+The structural tier reads workflow files and reports the SHAPE of a dead gate. It cannot tell
+you whether anything was relying on the job. That needs the branch's required status checks:
+
+```bash
+deadgate . --repo owner/name            # read-only GitHub API calls via `gh`
+```
+
+Two endpoints answer, and they do not have the same reach:
+
+| endpoint | access needed | what it covers |
+|---|---|---|
+| `GET /repos/{o}/{r}/rules/branches/{b}` | read | rulesets only |
+| `GET /repos/{o}/{r}/branches/{b}/protection` | **admin** | classic protection |
+
+On a repository you do not administer, only the first answers. It says nothing about classic
+protection, so an empty result does not mean the branch is unprotected. That asymmetry decides
+what the tier is allowed to claim:
+
+- a **match proves** the check is required, so a MEDIUM finding escalates to HIGH
+- **no match proves nothing** unless the required set is complete, which needs admin on both
+  endpoints. Without that, the verdict is AMBIGUOUS and the severity does not move
+
+Only MEDIUM moves. MEDIUM is the tier that means "the workflow file does not say", so it is the
+only one this evidence can settle. A structural HIGH keeps its severity even when a check is not
+required, because protection can be added later and may be configured where this API does not
+reach. A structural LOW keeps its severity because a release pipeline that skips on purpose does
+not become a merge gate by appearing in a list.
+
+### Verdicts
+
+| verdict | meaning | severity |
+|---|---|---|
+| `REQUIRED` | a derived check name matches a required context | MEDIUM becomes HIGH |
+| `NOT_REQUIRED` | complete required set, no match | MEDIUM becomes LOW |
+| `UNPROTECTED` | complete, and the branch requires nothing at all | MEDIUM becomes LOW |
+| `AMBIGUOUS` | the name could not be derived, or the set is incomplete | unchanged |
+| `UNREADABLE` | the API did not answer | unchanged |
+
+### Why it reports contexts it could not attribute
+
+A required status check is identified by its **check-run name**, which is not the job key in the
+YAML. If name derivation breaks, no required context matches any job, every MEDIUM resolves to
+"not required", and the tool quietly downgrades real defects. So the run prints how many required
+contexts it attributed to a job in the repository, and warns when none of them matched anything.
+A broken matcher then appears as a number rather than as silence. Some contexts land there
+legitimately, from third-party apps or workflows outside the repository, so it is a signal to
+read and not an assertion.
+
+Two transport facts are enforced rather than trusted, because both were observed:
+
+- `403` is returned for rate limiting **and** for insufficient permissions. These are separated,
+  because one is retryable and the other means this tier cannot help on that repository.
+- `404` from the classic endpoint means "not protected" for a branch you administer and "you
+  cannot see this" otherwise, with the same status code and only the prose differing. So it is
+  gated on `permissions.admin`, never on the message text.
+
+## Measurements
+
+Figures, and the unit each one is in, are in [MEASUREMENT.md](MEASUREMENT.md). Reproduce them
+with `python bench/build_cache.py` then `python bench/ab.py`.
+
+The short version: corpus totals are weighted by workflow size, one monorepo carries 55% of the
+naive D1 count, and the median affected repository sees 2 findings where the pre-narrowing
+detector gave 3. `bench/ab.py` prints the per-repo median, p90 and max alongside every total,
+so the unit cannot be dropped by accident.
+
+## Scope, stated plainly
+
+This reads workflow files. It does **not** read branch-protection settings, so it reports the
+*shape* of a defect, not whether a given check is actually required on your default branch.
+Semantic gate testing, planting the condition a gate claims to catch and asserting it reacts,
+is a separate and harder problem and is not in this release.
+
+## Licence
+MIT

deadgate-0.1.0/README.md

@@ -0,0 +1,130 @@
+# deadgate
+
+**Find CI checks that cannot fail.**
+
+Flaky-test tools find checks that fail randomly. This finds the opposite: checks that are
+structurally incapable of going red, so your pipeline is green for reasons unrelated to your code.
+
+GitHub documents the sharpest case itself:
+
+> A job that is skipped will report its status as `Success`. It will not prevent a pull
+> request from merging, even if it is a required check.
+
+```bash
+pip install deadgate
+deadgate .
+```
+
+Exit code is 1 when there are findings, 0 when clean, and **2 when a workflow file could not
+be parsed**. A file it could not read is never counted as a file with no problems.
+
+## What it detects
+
+| id | defect | why it matters |
+|----|--------|----------------|
+| D1 | a job depends on a skip-prone job and never reads `needs.*.result` | the dependency skips, reports Success, and the gate passes with nothing run |
+| D2 | a fan-in job runs on `always()` and never reads `needs.*.result` | it is green when the jobs it gates failed |
+| D3 | a `run:` step ends a pipeline in a filter with no `pipefail` | the step's status is the filter's, so an upstream failure passes |
+
+Every finding carries a reproduction. A finding without one is an opinion, and this tool
+does not emit opinions.
+
+## The calibration corpus is the specification
+
+`corpus/` holds workflows that are **known broken** and workflows that are **known good**, and
+the good ones are deliberate near misses of the broken ones. A detector has to fire on the
+defect *and* stay quiet on its near miss. A detector that fires on everything is as useless as
+one that fires on nothing, and it gets the whole tool switched off.
+
+```bash
+python -m pytest tests/
+```
+
+Fixtures `g6` and `g7` exist because the detectors were **wrong against real repositories while
+the corpus was green**:
+
+- `g6` a job guarding itself with a job-level `if:` that reads `needs.*.outputs` IS checking its
+  upstream. The first version only read step-level conditions and flagged correct jobs.
+- `g7` `if: ${{ !cancelled() }}` is not skip-prone. It runs in normal operation and on failure.
+  Treating every `if:` as a possible skip produced false alarms.
+
+Both were found by running against a real 25k-star repository, not by the suite. That is the
+argument this tool makes about everyone else's checks, so it is held to it too.
+
+## The branch-protection tier
+
+The structural tier reads workflow files and reports the SHAPE of a dead gate. It cannot tell
+you whether anything was relying on the job. That needs the branch's required status checks:
+
+```bash
+deadgate . --repo owner/name            # read-only GitHub API calls via `gh`
+```
+
+Two endpoints answer, and they do not have the same reach:
+
+| endpoint | access needed | what it covers |
+|---|---|---|
+| `GET /repos/{o}/{r}/rules/branches/{b}` | read | rulesets only |
+| `GET /repos/{o}/{r}/branches/{b}/protection` | **admin** | classic protection |
+
+On a repository you do not administer, only the first answers. It says nothing about classic
+protection, so an empty result does not mean the branch is unprotected. That asymmetry decides
+what the tier is allowed to claim:
+
+- a **match proves** the check is required, so a MEDIUM finding escalates to HIGH
+- **no match proves nothing** unless the required set is complete, which needs admin on both
+  endpoints. Without that, the verdict is AMBIGUOUS and the severity does not move
+
+Only MEDIUM moves. MEDIUM is the tier that means "the workflow file does not say", so it is the
+only one this evidence can settle. A structural HIGH keeps its severity even when a check is not
+required, because protection can be added later and may be configured where this API does not
+reach. A structural LOW keeps its severity because a release pipeline that skips on purpose does
+not become a merge gate by appearing in a list.
+
+### Verdicts
+
+| verdict | meaning | severity |
+|---|---|---|
+| `REQUIRED` | a derived check name matches a required context | MEDIUM becomes HIGH |
+| `NOT_REQUIRED` | complete required set, no match | MEDIUM becomes LOW |
+| `UNPROTECTED` | complete, and the branch requires nothing at all | MEDIUM becomes LOW |
+| `AMBIGUOUS` | the name could not be derived, or the set is incomplete | unchanged |
+| `UNREADABLE` | the API did not answer | unchanged |
+
+### Why it reports contexts it could not attribute
+
+A required status check is identified by its **check-run name**, which is not the job key in the
+YAML. If name derivation breaks, no required context matches any job, every MEDIUM resolves to
+"not required", and the tool quietly downgrades real defects. So the run prints how many required
+contexts it attributed to a job in the repository, and warns when none of them matched anything.
+A broken matcher then appears as a number rather than as silence. Some contexts land there
+legitimately, from third-party apps or workflows outside the repository, so it is a signal to
+read and not an assertion.
+
+Two transport facts are enforced rather than trusted, because both were observed:
+
+- `403` is returned for rate limiting **and** for insufficient permissions. These are separated,
+  because one is retryable and the other means this tier cannot help on that repository.
+- `404` from the classic endpoint means "not protected" for a branch you administer and "you
+  cannot see this" otherwise, with the same status code and only the prose differing. So it is
+  gated on `permissions.admin`, never on the message text.
+
+## Measurements
+
+Figures, and the unit each one is in, are in [MEASUREMENT.md](MEASUREMENT.md). Reproduce them
+with `python bench/build_cache.py` then `python bench/ab.py`.
+
+The short version: corpus totals are weighted by workflow size, one monorepo carries 55% of the
+naive D1 count, and the median affected repository sees 2 findings where the pre-narrowing
+detector gave 3. `bench/ab.py` prints the per-repo median, p90 and max alongside every total,
+so the unit cannot be dropped by accident.
+
+## Scope, stated plainly
+
+This reads workflow files. It does **not** read branch-protection settings, so it reports the
+*shape* of a defect, not whether a given check is actually required on your default branch.
+Semantic gate testing, planting the condition a gate claims to catch and asserting it reacts,
+is a separate and harder problem and is not in this release.
+
+## Licence
+MIT

deadgate-0.1.0/deadgate/checknames.py

@@ -0,0 +1,180 @@
+"""Derive the check-run names a workflow job produces.
+
+A required status check is identified by its CHECK-RUN NAME, which is not the job key in
+the YAML. Getting this wrong is the way this tier lies: if derivation silently fails, no
+required context matches any job, every finding resolves to "not required", and the tool
+quietly downgrades real defects. So derivation reports its own confidence, and anything it
+cannot work out is AMBIGUOUS rather than "no match".
+
+The naming rules GitHub actually applies:
+
+  no `name:`                     the job key
+  no `name:` + a matrix          `<job key> (<values, in matrix key order>)`
+  `name:` + a matrix             that string, ALSO suffixed `(<values>)`
+  `name:` already naming matrix  the string per leg, with expressions substituted, no suffix
+  `uses:` (reusable workflow)    `<caller name> / <callee job name>`
+
+The rule for a static `name:` with a matrix is append-the-leg-values, not use-it-once. Verified
+against the authoritative surface: promptfoo's `main` branch requires the context
+`Check Python (3.9)` while its workflow declares a static `name: Check Python` over a
+`python-version` matrix, and its `Build on Node ${{ matrix.node }}` job, whose name already
+references the matrix, is required as the unsuffixed `Build on Node 24.x`. Encoding the
+opposite made every leg of a statically named matrix job match nothing.
+
+Matrix legs and reusable callees are matched by PREFIX rather than enumerated, because the
+prefix is decidable from the caller alone while the values often are not. That keeps a
+`matrix: ${{ fromJson(needs.x.outputs.y) }}` job decidable instead of ambiguous.
+"""
+from __future__ import annotations
+
+import itertools
+import re
+from dataclasses import dataclass
+
+EXACT = "EXACT"
+AMBIGUOUS = "AMBIGUOUS"
+
+_EXPR = re.compile(r"\$\{\{(.+?)\}\}", re.S)
+_MATRIX_REF = re.compile(r"^\s*matrix\.([A-Za-z_][\w-]*)\s*$")
+MAX_COMBINATIONS = 256
+
+
+@dataclass(frozen=True)
+class Derived:
+    """Check-run names a job produces, plus how sure we are."""
+    names: frozenset[str]
+    prefixes: frozenset[str]
+    confidence: str
+    reason: str = ""
+
+    def matches(self, context: str) -> bool:
+        if self.confidence != EXACT:
+            raise ValueError("refusing to match on an AMBIGUOUS derivation")
+        return context in self.names or any(context.startswith(p) for p in self.prefixes)
+
+
+def _render(value) -> str:
+    """A matrix value as GitHub interpolates it, which is not Python's str().
+
+    A YAML boolean renders `true`, not `True`, and null renders as the empty string. Getting
+    this wrong produces a name that matches nothing, and a name that matches nothing clears
+    the finding.
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _literal_matrix(strategy) -> dict | None:
+    """The matrix as literal lists, or None when any part of it is computed.
+
+    `include` and `exclude` add and remove legs by rules not worth guessing at: an
+    under-enumerated name set silently fails to match a context that IS required, which clears
+    the finding. Both are lists of mappings, so they make the matrix non-literal here.
+    """
+    if not isinstance(strategy, dict):
+        return None
+    matrix = strategy.get("matrix")
+    if not isinstance(matrix, dict):
+        return None
+    axes = {}
+    for key, val in matrix.items():
+        # `include` and `exclude` land here too, and that is deliberate: both are lists of
+        # mappings, so the check below already makes the matrix non-literal and the caller
+        # falls through to AMBIGUOUS. An explicit guard for them was written first and was
+        # unreachable, which is the defect this tool is named after.
+        if not isinstance(val, list) or any(isinstance(v, (dict, list)) for v in val):
+            return None
+        if any("${{" in str(v) for v in val):
+            return None
+        axes[key] = [_render(v) for v in val]
+    return axes or None
+
+
+def _substitute(template: str, axes: dict) -> frozenset[str] | None:
+    """Expand a `name:` template over a literal matrix, or None if it cannot be expanded."""
+    refs = []
+    for raw in _EXPR.findall(template):
+        m = _MATRIX_REF.match(raw)
+        if not m or m.group(1) not in axes:
+            return None          # an expression we cannot evaluate: not our business to guess
+        refs.append(m.group(1))
+    if not refs:
+        return frozenset({template})
+    used = {r: axes[r] for r in dict.fromkeys(refs)}
+    combos = list(itertools.product(*used.values()))
+    if len(combos) > MAX_COMBINATIONS:
+        return None
+    out = set()
+    for combo in combos:
+        values = dict(zip(used.keys(), combo))
+        # GitHub trims the rendered name, which matters when a leg's value is empty.
+        out.add(_EXPR.sub(lambda m: values[_MATRIX_REF.match(m.group(1)).group(1)],
+                          template).strip())
+    # A job SKIPPED by its job-level if: emits one check run carrying the RAW template, with
+    # the expressions left literal and no matrix expansion. Skipped jobs are precisely this
+    # tool's target population, so the unexpanded form is a legitimate candidate name.
+    out.add(template.strip())
+    return frozenset(out)
+
+
+def derive(job_key: str, job: dict, workflow_callable: bool = False) -> Derived:
+    """The check-run names job `job_key` produces.
+
+    `workflow_callable` says this job's own workflow declares `on: workflow_call`. When another
+    workflow in the repository `uses:` it, GitHub names the check `<caller job> / <this job>`,
+    and which caller, if any, is not decidable from this file. Guessing the unprefixed name
+    clears a finding on a job that IS a required gate, so this is AMBIGUOUS instead.
+    """
+    job = job if isinstance(job, dict) else {}
+    if workflow_callable:
+        return Derived(frozenset(), frozenset(), AMBIGUOUS,
+                       "workflow is `uses:`-callable, so its checks may be named "
+                       "`<caller> / <job>` and the caller is not knowable from this file")
+    template = job.get("name")
+    axes = _literal_matrix(job.get("strategy"))
+    has_matrix = isinstance(job.get("strategy"), dict) and job["strategy"].get("matrix") is not None
+
+    if template is None:
+        base = job_key
+        if "${{" in base:
+            return Derived(frozenset(), frozenset(), AMBIGUOUS, "job key contains an expression")
+        if job.get("uses"):
+            # A reusable call produces `caller / callee`, and a MATRIXED one produces
+            # `caller (values) / callee`. Checking uses: before the matrix emitted only the
+            # first prefix, so every matrixed reusable call matched nothing.
+            prefixes = {f"{base} / "}
+            if has_matrix:
+                prefixes.add(f"{base} (")
+            # A skipped reusable call emits the bare caller name with no callee suffix.
+            return Derived(frozenset({base}), frozenset(prefixes), EXACT,
+                           "reusable workflow" + (" with matrix legs" if has_matrix else ""))
+        prefixes = frozenset({f"{base} ("}) if has_matrix else frozenset()
+        return Derived(frozenset({base}), prefixes, EXACT,
+                       "job key" + (" with matrix legs" if has_matrix else ""))
+
+    template = str(template)
+    if "${{" not in template:
+        # A static name is SUFFIXED with the leg values when the job has a matrix. Encoding
+        # the opposite, that it is used once verbatim, made every leg match nothing.
+        prefixes = {f"{template} ("} if has_matrix else set()
+        if job.get("uses"):
+            prefixes.add(f"{template} / ")
+            return Derived(frozenset({template}), frozenset(prefixes), EXACT,
+                           "reusable workflow" + (" with matrix legs" if has_matrix else ""))
+        return Derived(frozenset({template}), frozenset(prefixes), EXACT,
+                       "explicit name" + (" with matrix legs" if has_matrix else ""))
+
+    if axes is None:
+        return Derived(frozenset(), frozenset(), AMBIGUOUS,
+                       "name: has an expression and the matrix is not literal")
+    names = _substitute(template, axes)
+    if names is None:
+        return Derived(frozenset(), frozenset(), AMBIGUOUS,
+                       "name: has an expression that does not resolve from the matrix")
+    if job.get("uses"):
+        return Derived(names, frozenset(f"{n} / " for n in names), EXACT,
+                       "reusable workflow, name expanded over the matrix")
+    return Derived(names, frozenset(), EXACT, "name expanded over the matrix")

deadgate-0.1.0/deadgate/cli.py

@@ -0,0 +1,124 @@
+"""deadgate: find CI checks that cannot fail."""
+from __future__ import annotations
+
+import argparse
+import pathlib
+from dataclasses import replace
+import sys
+
+import yaml
+
+from .detectors import scan_workflow
+from .protection import fetch, gh_api, repo_meta, selftest
+from .resolve import attribute, resolve, workflow_is_callable
+
+
+def workflows(root: pathlib.Path):
+    for pat in ("*.yml", "*.yaml"):
+        yield from sorted(root.rglob(f".github/workflows/{pat}"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="deadgate", description=__doc__)
+    ap.add_argument("path", nargs="?", default=".", help="repository root")
+    ap.add_argument("--quiet", action="store_true", help="only print the summary")
+    ap.add_argument("--repo", metavar="OWNER/NAME",
+                    help="resolve MEDIUM findings against what the branch actually requires. "
+                         "Read-only GitHub API calls via `gh`. On a repository you do not "
+                         "administer the required set is incomplete, so findings can only be "
+                         "escalated, never cleared.")
+    ap.add_argument("--branch", help="branch to read protection from (default: the repo's default)")
+    ap.add_argument("--all", action="store_true",
+                    help="include LOW findings (release and deploy pipelines, where a skip "
+                         "is usually the intent). Hidden by default so the output stays actionable.")
+    args = ap.parse_args(argv)
+
+    root = pathlib.Path(args.path)
+    files = list(workflows(root))
+    if not files:
+        print(f"no workflow files under {root}/.github/workflows", file=sys.stderr)
+        return 0
+
+    prot = None
+    jobs_by_file: dict[str, dict] = {}
+    callable_files: set[str] = set()
+    if args.repo:
+        api = gh_api()
+        ok, why = selftest(api)
+        if not ok:
+            # Refuse rather than report every finding UNREADABLE, which would look like a
+            # result about the repository instead of a broken transport.
+            print(f"GitHub API transport self-test failed: {why}", file=sys.stderr)
+            return 2
+        default_branch, admin = repo_meta(args.repo, api)
+        branch = args.branch or default_branch
+        if not branch:
+            print(f"could not read {args.repo} from the GitHub API; is `gh` authenticated?",
+                  file=sys.stderr)
+            return 2
+        prot = fetch(args.repo, branch, api, admin=admin)
+        print(f"branch {branch}: {prot.state}"
+              f"{f', {len(prot.required)} required check(s)' if prot.required else ''}"
+              f"{'' if prot.complete else ', required set INCOMPLETE (no admin)'}"
+              f"{f' [{prot.detail}]' if prot.detail else ''}\n")
+
+    findings = []
+    suppressed = 0
+    for f in files:
+        try:
+            doc = yaml.safe_load(f.read_text())
+        except yaml.YAMLError as exc:
+            # Refuse to report a clean result for a file we could not read. A parse
+            # failure counted as "no findings" is the exact defect this tool exists to find.
+            print(f"UNREADABLE {f}: {exc.__class__.__name__}", file=sys.stderr)
+            return 2
+        jobs_by_file[str(f)] = (doc or {}).get("jobs") or {}
+        if workflow_is_callable(doc):
+            callable_files.add(str(f))
+        for x in scan_workflow(doc):
+            why = ""
+            if prot is not None:
+                job = ((doc or {}).get("jobs") or {}).get(x.job)
+                r = resolve(x.severity, x.job, job if isinstance(job, dict) else {}, prot,
+                            str(f) in callable_files)
+                why = f"{r.verdict}: {r.why}"
+                if r.moved:
+                    why = f"{r.structural} -> {r.severity}  {why}"
+                x = replace(x, severity=r.severity)
+            if x.severity == "LOW" and not args.all:
+                suppressed += 1
+                continue
+            findings.append((f, x, why))
+
+    if not args.quiet:
+        for f, x, why in findings:
+            rel = f.relative_to(root) if f.is_relative_to(root) else f
+            print(f"[{x.detector}/{x.severity}] {rel}::{x.job}  {x.title}")
+            print(f"        {x.detail}")
+            if why:
+                print(f"        branch:  {why}")
+            print(f"        repro: {x.repro}\n")
+
+    tail = f", {suppressed} LOW hidden (use --all)" if suppressed else ""
+    print(f"{len(files)} workflow file(s), {len(findings)} finding(s){tail}")
+
+    if prot is not None and prot.required:
+        att = attribute(prot, jobs_by_file, frozenset(callable_files))
+        print(f"required checks: {len(att.attributed)}/{len(att.required)} attributed to a job "
+              f"in this repository")
+        if att.unattributed:
+            # Printed because a broken name derivation shows up here as a number instead of
+            # as silently cleared findings. Third-party checks land here legitimately.
+            print(f"  unattributed: {', '.join(att.unattributed[:8])}"
+                  f"{' ...' if len(att.unattributed) > 8 else ''}")
+        if att.undecidable_jobs:
+            print(f"  jobs whose check name could not be derived: {len(att.undecidable_jobs)}")
+        if att.suspicious:
+            print("  WARNING: no required check matched any job here. Either every gate is "
+                  "external, or the name derivation is broken. Do not read the severities "
+                  "above as resolved.")
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())