deadgate 0.1.0__py3-none-any.whl

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/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())

deadgate/detectors.py

@@ -0,0 +1,362 @@
+"""Structural detectors for CI checks that cannot fail.
+
+Every detector reports a FINDING only when the defect is STRUCTURAL and decidable from
+the workflow file alone. Anything needing branch-protection state or runtime history is
+out of scope here and belongs to the API tier.
+
+Design rule taken from gate_mutation_sweep.py: a detector must fire on the planted defect
+AND stay quiet on a near miss. A detector that fires on everything gets the whole tool
+switched off, which is worse than not shipping it.
+"""
+from __future__ import annotations
+
+import re
+import os
+from dataclasses import dataclass
+
+# EXPERIMENT AFFORDANCE, not a product feature. With DEADGATE_NAIVE=1 the detectors run
+# WITHOUT the suppressions and narrowings that tracing real repositories forced on them,
+# and D4 is withheld because it did not exist then. It exists so the cost of each
+# suppression can be measured against an identical corpus instead of two samples.
+NAIVE = os.environ.get("DEADGATE_NAIVE") == "1"
+
+FILTERS = {"grep", "jq", "head", "tail", "tee", "awk", "sed", "cut", "sort", "uniq", "wc", "tr"}
+
+
+@dataclass(frozen=True)
+class Finding:
+    detector: str
+    job: str
+    title: str
+    detail: str
+    repro: str
+    severity: str = "HIGH"
+
+
+def _truthy_always(cond) -> bool:
+    """Does this if: condition reduce to always()?"""
+    if cond is None:
+        return False
+    s = str(cond).strip()
+    s = re.sub(r"^\$\{\{\s*|\s*\}\}$", "", s).strip()
+    return s == "always()"
+
+
+# Conditions that are NOT skip-prone. A job guarded by one of these runs in normal
+# operation, so treating it as "might skip" is a false alarm. Found by running against
+# promptfoo main.yml, where package-acceptance carries `if: ${{ !cancelled() }}` and
+# the corpus had nothing like it.
+_NEVER_SKIPS = re.compile(r"^(always\(\)|!\s*cancelled\(\)|success\(\)\s*\|\|\s*failure\(\)|"
+                          r"failure\(\)\s*\|\|\s*success\(\))$")
+
+
+def _skip_prone(cond) -> bool:
+    """A job-level if: that can realistically evaluate false and skip the job."""
+    if cond is None:
+        return False
+    s = re.sub(r"^\$\{\{\s*|\s*\}\}$", "", str(cond).strip()).strip()
+    return not _NEVER_SKIPS.match(s)
+
+
+def _steps_text(job: dict) -> str:
+    """All text a job's steps can reference, so we can look for needs.* reads."""
+    out = []
+    for step in job.get("steps") or []:
+        if isinstance(step, dict):
+            out.append(str(step.get("run", "")))
+            out.append(str(step.get("if", "")))
+            env = step.get("env") or {}
+            if isinstance(env, dict):
+                out.extend(str(v) for v in env.values())
+            with_ = step.get("with") or {}
+            if isinstance(with_, dict):
+                out.extend(str(v) for v in with_.values())
+    out.append(str(job.get("env") or ""))
+    # The job-level if: is a result check too. A job guarded by
+    # `if: always() && needs.x.outputs.y` IS reading its upstream, and missing this
+    # was a LEAKY bug found by running against real workflows, not by the corpus.
+    # Behind NAIVE so the flag reproduces the pre-fix behaviour rather than quietly
+    # keeping the fix in both arms, which made an A/B report a difference of zero.
+    if not NAIVE:
+        out.append(str(job.get("if") or ""))
+    return "\n".join(out)
+
+
+def d2_fanin_without_result_check(jobs: dict) -> list[Finding]:
+    """A fan-in job that runs on always() and never reads needs.*.result.
+
+    It will be GREEN when the jobs it gates FAILED. If it is a required check, the
+    branch protection it provides is decorative.
+    """
+    found = []
+    for name, job in jobs.items():
+        if not isinstance(job, dict):
+            continue
+        needs = job.get("needs")
+        if not needs or not _truthy_always(job.get("if")):
+            continue
+        text = _steps_text(job)
+        if re.search(r"needs\.[A-Za-z0-9_\-]+\.(result|outputs)", text):
+            continue
+        upstream = ", ".join(needs) if isinstance(needs, list) else str(needs)
+        found.append(Finding(
+            detector="D2",
+            job=name,
+            title="fan-in gate cannot fail",
+            detail=(f"job '{name}' needs [{upstream}] and runs on always(), but no step reads "
+                    f"needs.*.result. It reports success even when [{upstream}] fail."),
+            repro=(f"Make any of [{upstream}] exit 1 and re-run. '{name}' still succeeds, "
+                   f"and any branch protection requiring it still passes."),
+        ))
+    return found
+
+
+def d1_skippable_upstream(jobs: dict, doc: dict | None = None) -> list[Finding]:
+    """A conditional job that something depends on, where the dependent never checks the result.
+
+    GitHub documents that a skipped job reports Success and does not prevent a merge even
+    as a required check, and that a skipped conclusion is treated as success for dependent
+    checks. So skipping the real work silently satisfies the gate.
+    """
+    found = []
+    conditional = {n for n, j in jobs.items()
+                   if isinstance(j, dict) and _skip_prone(j.get("if"))}
+    # A dependent whose own if: reads the upstream's outputs is deliberately gated on it:
+    # the change-detection pattern, which is intentional, and whose real failure mode is
+    # D4's. That exclusion happens in _steps_text, which reads the job-level if:. An
+    # explicit second check here was DEAD CODE and is removed; the A/B that was supposed
+    # to prove it worked reported a difference of exactly zero and found it instead.
+    for name, job in jobs.items():
+        if not isinstance(job, dict):
+            continue
+        needs = job.get("needs")
+        if not needs:
+            continue
+        needs_list = needs if isinstance(needs, list) else [needs]
+        skippable = [n for n in needs_list if n in conditional]
+        if not skippable:
+            continue
+        text = _steps_text(job)
+        if re.search(r"needs\.[A-Za-z0-9_\-]+\.(result|outputs)", text):
+            continue
+        sev = _gate_severity(name, job, doc or {})
+        for up in skippable:
+            found.append(Finding(
+                detector="D1",
+                severity=sev,
+                job=name,
+                title="gate satisfied by a skipped job",
+                detail=(f"job '{name}' depends on '{up}', which is conditional. A skipped job "
+                        f"reports Success, and '{name}' never reads needs.{up}.result."),
+                repro=(f"Open a PR where '{up}'s if: condition is false. '{up}' skips, "
+                       f"'{name}' succeeds, and nothing ran."),
+            ))
+    return found
+
+
+_CANNOT_FAIL = re.compile(r"^\s*(echo|printf)\b")
+
+
+def _substitution_bodies(line: str) -> list[str]:
+    """Bodies of $( ... ), innermost first, so a pipe inside one is analysed on its own."""
+    out, stack = [], []
+    i = 0
+    while i < len(line) - 1:
+        if line[i] == "$" and line[i + 1] == "(":
+            stack.append(i + 2); i += 2; continue
+        if line[i] == ")" and stack:
+            out.append(line[stack.pop():i])
+        i += 1
+    return out
+
+
+def _upstream_can_fail(line: str) -> bool:
+    """Can the command BEFORE the final pipe actually fail?
+
+    Two shapes are benign and together they were 10 of 20 sampled findings:
+      echo "literal" | cut                      the head cannot fail
+      echo "X=$(echo literal | cut)" >> file    the pipe lives INSIDE a substitution whose
+                                                own head is echo, and splitting the whole
+                                                line on its last pipe misses that.
+    """
+    for body in _substitution_bodies(line):
+        if "|" in body:
+            head = body.rsplit("|", 1)[0].strip()
+            if _CANNOT_FAIL.match(head) and "$(" not in head and "`" not in head:
+                return False
+    head = line.rsplit("|", 1)[0].strip()
+    if "$(" in head or "`" in head:
+        # the outer head holds a substitution we already judged benign above
+        return True
+    return not _CANNOT_FAIL.match(head)
+
+
+def _result_is_emptiness_checked(var: str, body: str) -> bool:
+    """Did the author guard the empty case themselves, in the same step?
+
+    `X=$(find ... | head -1)` followed by `if [ -z "$X" ]; then exit 1` is a handled
+    case, not a defect. Reporting it anyway is how a tool gets uninstalled.
+    """
+    if not var:
+        return False
+    return bool(re.search(rf"-[zn]\s+\"?\$\{{?{re.escape(var)}\}}?", body))
+
+
+def _d3_severity(step: dict, job_name: str, job: dict, doc: dict, line: str) -> str:
+    """Does the masked exit status actually decide anything?
+
+    A pipeline whose result is exported, or which sits in a step that can fail the build,
+    masks a decision. A pipeline in a cleanup or logging step masks nothing anybody reads.
+    Tracing twenty D3 findings by hand, the ones that mattered all had a consumer and the
+    ones that did not were fire-and-forget.
+    """
+    body = str(step.get("run") or "")
+    if not _on_pull_request(doc):
+        return "LOW"
+    exported = "GITHUB_OUTPUT" in body or "GITHUB_ENV" in body
+    decides = bool(re.search(r"\bexit\s+[1-9]|::error::", body))
+    assigned = re.match(r"\s*([A-Za-z_][A-Za-z0-9_]*)=", line)
+    consumed = bool(assigned and re.search(rf"\$\{{?{re.escape(assigned.group(1))}\b",
+                                           body.replace(line, "", 1)))
+    if decides or exported or consumed:
+        return "HIGH"
+    return "MEDIUM"
+
+
+def d3_pipe_masked_exit(jobs: dict, doc: dict | None = None) -> list[Finding]:
+    """A run: step whose exit status is the LAST command in a pipe, with no pipefail.
+
+    The step's status reports the filter's success, not the real command's. An outage
+    reads as a pass.
+    """
+    found = []
+    for name, job in jobs.items():
+        if not isinstance(job, dict):
+            continue
+        for step in job.get("steps") or []:
+            if not isinstance(step, dict):
+                continue
+            run = step.get("run")
+            if not run or "|" not in str(run):
+                continue
+            body = str(run)
+            if re.search(r"set\s+[-a-z]*o?\s*[-a-z]*pipefail|set\s+-o\s+pipefail", body):
+                continue
+            for line in body.splitlines():
+                line = line.strip()
+                if "|" not in line or line.startswith("#") or "||" in line:
+                    continue
+                tail = line.rsplit("|", 1)[1].strip().split()
+                if not tail:
+                    continue
+                if tail[0] in FILTERS and (NAIVE or _upstream_can_fail(line)):
+                    assigned = (re.match(r"([A-Za-z_][A-Za-z0-9_]*)=", line) or [None, ""])[1]
+                    if not NAIVE and _result_is_emptiness_checked(assigned, body):
+                        continue
+                    label = step.get("name") or line[:40]
+                    found.append(Finding(
+                        detector="D3",
+                        severity=_d3_severity(step, name, job, doc or {}, line),
+                        job=name,
+                        title="exit status masked by a pipe",
+                        detail=(f"step '{label}' in job '{name}' ends a pipeline with "
+                                f"'{tail[0]}' and does not set pipefail. The step's status is "
+                                f"{tail[0]}'s, so a failure upstream of the pipe passes."),
+                        repro=(f"Make the command before '| {tail[0]}' fail. The step still "
+                               f"succeeds. Add 'set -o pipefail' and it fails correctly."),
+                    ))
+                    break
+    return found
+
+
+# Severity for D4 is decided by TWO questions the workflow file can answer:
+#   does this workflow run on pull_request, so the job is a candidate required check, and
+#   is the gated job a VERIFICATION job, so skipping it means nothing was checked.
+# Skipping a deploy because no release was cut is intended. Skipping the tests because the
+# path filter crashed is not. Without the branch-protection API this is the honest ceiling,
+# and the tier says which question it could not answer.
+_CHECK_JOB = re.compile(
+    r"\b(test|tests|lint|check|checks|verify|typecheck|type-check|coverage|audit|"
+    r"security|e2e|unit|integration|spec|validate|ci)\b", re.I)
+_SHIP_JOB = re.compile(
+    r"\b(deploy|publish|release|upload|notify|docs|announce|changelog|tag|sign|"
+    r"docker|image|artifact)\b", re.I)
+
+
+def _on_pull_request(doc: dict) -> bool:
+    on = (doc or {}).get("on") or (doc or {}).get(True)
+    if isinstance(on, str):
+        return on == "pull_request"
+    if isinstance(on, list):
+        return "pull_request" in on
+    if isinstance(on, dict):
+        return "pull_request" in on or "pull_request_target" in on
+    return False
+
+
+def _gate_severity(job_name: str, job: dict, doc: dict) -> str:
+    name = f"{job_name} {job.get('name') or ''}"
+    if _SHIP_JOB.search(name) and not _CHECK_JOB.search(name):
+        return "LOW"          # a release step, where skipping is usually the intent
+    if not _on_pull_request(doc):
+        return "LOW"          # never runs on a PR, so it is not a merge gate
+    if _CHECK_JOB.search(name):
+        return "HIGH"         # a PR verification job that can silently not run
+    return "MEDIUM"
+
+
+def d4_outputs_gate_without_result_check(jobs: dict, doc: dict | None = None) -> list[Finding]:
+    """A job gated on an upstream's OUTPUTS, with nothing checking that upstream SUCCEEDED.
+
+    The common change-detection shape:  if: needs.detect.outputs.rust == 'true'
+
+    That is a deliberate optimisation and is NOT a defect by itself. The defect is what
+    happens when `detect` FAILS rather than decides: a failed job sets no outputs, the
+    comparison is false, the dependent job SKIPS, and a skipped job reports Success. One
+    broken detector silently disables the tests it gates, and the merge is green.
+
+    A job that also reads needs.<up>.result is doing it correctly and is not reported.
+    """
+    found = []
+    for name, job in jobs.items():
+        if not isinstance(job, dict):
+            continue
+        cond = str(job.get("if") or "")
+        if not cond:
+            continue
+        ups = set(re.findall(r"needs\.([A-Za-z0-9_\-]+)\.outputs\.", cond))
+        if not ups:
+            continue
+        checked = set(re.findall(r"needs\.([A-Za-z0-9_\-]+)\.result", cond + _steps_text(job)))
+        sev = _gate_severity(name, job, doc or {})
+        for up in sorted(ups - checked):
+            found.append(Finding(
+                detector="D4",
+                severity=sev,
+                job=name,
+                title="tests silently disabled if the gating job fails",
+                detail=(f"job '{name}' runs only when '{up}' outputs say so, and nothing checks "
+                        f"needs.{up}.result. If '{up}' FAILS, its outputs are unset, the "
+                        f"condition is false, '{name}' skips, and a skipped job reports Success."),
+                repro=(f"Make '{up}' exit 1. '{name}' does not run, reports Success, and any "
+                       f"branch protection requiring it passes with nothing tested."),
+            ))
+    return found
+
+
+DETECTORS = (d1_skippable_upstream, d2_fanin_without_result_check,
+              d3_pipe_masked_exit, d4_outputs_gate_without_result_check)
+
+
+def active_detectors():
+    return DETECTORS[:3] if NAIVE else DETECTORS
+
+
+def scan_workflow(doc: dict) -> list[Finding]:
+    jobs = (doc or {}).get("jobs") or {}
+    if not isinstance(jobs, dict):
+        return []
+    out = []
+    for fn in active_detectors():
+        out.extend(fn(jobs, doc) if fn is not d2_fanin_without_result_check else fn(jobs))
+    return out