Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

fix(ci): give the breaking-change gate the escape hatch it documents (#799)

Beenu Arorac4a4e0bc522a
diff --git a/.github/workflows/openapi-breaking.yml b/.github/workflows/openapi-breaking.yml
index 8f56980c1..aeff3f99b 100644
--- a/.github/workflows/openapi-breaking.yml
+++ b/.github/workflows/openapi-breaking.yml
@@ -5,11 +5,25 @@ name: OpenAPI breaking-change gate
# touches docs/openapi.yaml, diff the PR's spec against the base branch's spec
# and fail on any change that would break an existing generated SDK client
# (removed endpoint/schema/field, type change, tightened request, dropped enum
-# value). Ship a breaking change deliberately by bumping the version and adding
-# a CHANGELOG BREAKING note (then a maintainer re-runs with --allow-breaking).
+# value).
+#
+# Shipping a break deliberately: write a `### BREAKING` note under
+# `## [Unreleased]` in CHANGELOG.md saying what moved and why it could not be
+# preserved, then a maintainer applies the `breaking-change-approved` label to
+# the PR. The label is the authorisation, and GitHub records who applied it and
+# when on the PR timeline — which a workflow_dispatch boolean would not. The job
+# re-runs on `labeled`/`unlabeled` so the label is a live control rather than
+# something that only takes effect on the next push; it still runs the detector,
+# names every break it is permitting in the job summary, and refuses the approval
+# if the CHANGELOG note is missing or was inherited from an earlier PR.
+#
+# The version bump is not checked here: this repository accumulates under
+# `[Unreleased]` and bumps VERSION when a release is cut, so a per-PR version
+# check would demand something no PR can correctly do.
on:
pull_request:
+ types: [opened, synchronize, reopened, labeled, unlabeled]
paths:
- "docs/openapi.yaml"
- "scripts/openapi_diff.py"
@@ -22,6 +36,7 @@ concurrency:
permissions:
contents: read
+ pull-requests: read
jobs:
breaking-change:
@@ -43,7 +58,7 @@ jobs:
- name: Unit-test the detector
run: python -m pytest tests/test_openapi_diff.py -v --tb=short
- - name: Extract base-branch spec
+ - name: Extract base-branch spec and CHANGELOG
run: |
set -euo pipefail
BASE="${{ github.event.pull_request.base.sha }}"
@@ -54,6 +69,47 @@ jobs:
echo "no base spec (new file) — nothing to compare"
cp docs/openapi.yaml /tmp/base-openapi.yaml
fi
+ if git cat-file -e "${BASE}:CHANGELOG.md" 2>/dev/null; then
+ git show "${BASE}:CHANGELOG.md" > /tmp/base-CHANGELOG.md
+ else
+ : > /tmp/base-CHANGELOG.md
+ fi
+ # Not approved: the ordinary path. The detector fails the PR on any break.
- name: Diff for breaking changes
+ if: ${{ !contains(github.event.pull_request.labels.*.name, 'breaking-change-approved') }}
run: python scripts/openapi_diff.py --old /tmp/base-openapi.yaml --new docs/openapi.yaml
+
+ # Approved: name the maintainer who applied the label, from the PR's own
+ # event history, so the audit line does not depend on who pushed last.
+ - name: Resolve the approval record
+ id: approval
+ if: contains(github.event.pull_request.labels.*.name, 'breaking-change-approved')
+ env:
+ GH_TOKEN: ${{ github.token }}
+ REPO: ${{ github.repository }}
+ PR_NUMBER: ${{ github.event.pull_request.number }}
+ run: |
+ set -uo pipefail
+ record=$(gh api --paginate "repos/${REPO}/issues/${PR_NUMBER}/events" \
+ --jq '.[] | select(.event == "labeled" and .label.name == "breaking-change-approved") | "@\(.actor.login) at \(.created_at)"' \
+ 2>/dev/null | tail -n 1 || true)
+ if [ -z "${record}" ]; then
+ record="the 'breaking-change-approved' label on PR #${PR_NUMBER} (actor not resolved — see the PR timeline)"
+ else
+ record="${record}, via the 'breaking-change-approved' label on PR #${PR_NUMBER}"
+ fi
+ echo "record=${record}" >> "$GITHUB_OUTPUT"
+ echo "approval: ${record}"
+
+ - name: Diff for breaking changes (break approved by label)
+ if: contains(github.event.pull_request.labels.*.name, 'breaking-change-approved')
+ env:
+ APPROVED_BY: ${{ steps.approval.outputs.record }}
+ run: |
+ python scripts/openapi_diff.py \
+ --old /tmp/base-openapi.yaml --new docs/openapi.yaml \
+ --allow-breaking \
+ --changelog CHANGELOG.md \
+ --changelog-base /tmp/base-CHANGELOG.md \
+ --approved-by "${APPROVED_BY}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 70e5df64e..f19a75f46 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -95,6 +95,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- **The OpenAPI gate's documented escape hatch did not exist.** The workflow
+ header told a maintainer to "re-run with `--allow-breaking`" and
+ `scripts/openapi_diff.py` claimed the flag was what "the release flow uses" —
+ but the workflow triggered on `pull_request` only, with no dispatch, no input
+ and no label check, and the diff step never passed the flag. `--allow-breaking`
+ had **no caller anywhere in the tree**. A maintainer facing a correct,
+ deliberate break had no action that worked, and the two statements describing
+ the procedure were both false.
+
+ The hatch is now a PR label, `breaking-change-approved`, chosen over a
+ `workflow_dispatch` boolean because applying a label leaves an attributable
+ record of who authorised the break and when on the PR timeline. The job reads
+ that timeline and names the approver in its output. It re-runs on `labeled`
+ and `unlabeled`, so the label is a live control rather than one that waits for
+ the next push.
+
+ Approval is not a skip, and the flag is no longer usable as a silent bypass:
+ `--allow-breaking` now *requires* `--changelog` and `--changelog-base`, so it
+ cannot be wired up without also wiring up the thing that records what was
+ approved. The detector still runs, and the job summary lists every breaking
+ change being permitted next to the CHANGELOG note that justified it. The
+ approval is refused if there is no `### BREAKING` section under
+ `## [Unreleased]`, or if that section is byte-identical to the base branch's —
+ checked in both directions, because "a BREAKING section exists" alone would
+ let the first note in a release cycle excuse every later break in that cycle.
+
+ The version-bump half of the old promise was dropped rather than implemented:
+ this repository accumulates under `[Unreleased]` and bumps `VERSION` at
+ release-cut, so a per-PR version check would demand something no PR can
+ correctly do. The comment now says what the control does.
+
+ Thirteen new tests, all of which fail against the pre-change tree. Four are
+ wiring assertions over the workflow YAML itself — that some step passes
+ `--allow-breaking`, that the step passing it is guarded by the label and
+ presents its evidence, that the unapproved path still blocks, and that
+ `labeled` is in the trigger types. A unit-tested function with no caller is
+ indistinguishable from a working feature until something asserts the call.
+
- **A dry run called the customer's production SIEM.** The live-action dry-run
path works by stripping credentials so the executor falls through to
simulation, and the strip list did not match what the client factory reads:
diff --git a/apps/docs/docs/contributing/guidelines.md b/apps/docs/docs/contributing/guidelines.md
index c462f3f0f..d25ce5d03 100644
--- a/apps/docs/docs/contributing/guidelines.md
+++ b/apps/docs/docs/contributing/guidelines.md
@@ -152,6 +152,52 @@ must include:
> [eval harness page](../benchmark) explains exactly which is which. Update
> that page in the same commit if your PR changes a suite's metric category.
+### 4. OpenAPI breaking-change gate {#openapi-breaking-change-gate}
+
+A PR that touches `docs/openapi.yaml` is diffed against the base branch by
+`scripts/openapi_diff.py`. It fails on any change that would break an existing
+generated SDK client: a removed path, operation, schema or property, a changed
+property type, an optional field becoming required, a new required field on a
+request-shaped schema, a dropped enum value, or a new required parameter.
+
+Run it yourself before pushing:
+
+```bash
+git show origin/main:docs/openapi.yaml > /tmp/base-openapi.yaml
+python scripts/openapi_diff.py --old /tmp/base-openapi.yaml --new docs/openapi.yaml
+```
+
+Additive changes — a new path, a new optional field, a new enum value — are not
+flagged. Most spec changes need nothing further.
+
+#### Shipping a break deliberately
+
+Sometimes the break is the point: a schema described data the platform never
+measured, or a field promised a number with no formula behind it. Removing it is
+correct, and preserving it would keep the lie. Two steps:
+
+1. **Write the record.** Add a `### BREAKING` section under `## [Unreleased]` in
+ `CHANGELOG.md` saying what moved, what replaced it, and why it could not be
+ preserved. Name each field. This is the half that outlives CI logs.
+2. **Get it authorised.** Ask a maintainer to apply the
+ `breaking-change-approved` label to the PR.
+
+The label is the authorisation, and it is deliberately a label rather than a
+workflow input: GitHub records who applied it and when on the PR timeline, so
+the approval is attributable after the fact. The gate re-runs on `labeled` and
+`unlabeled`, so applying or removing it takes effect immediately.
+
+Approval is not a skip. The detector still runs, and the job summary lists
+**every** breaking change being permitted alongside the CHANGELOG note that
+justified it — the record says what was approved, not merely that something was.
+The gate refuses the approval outright if the CHANGELOG note is missing, or if
+the `### BREAKING` section is unchanged from the base branch (a note written for
+an earlier PR does not describe yours).
+
+There is no version-bump requirement here. This repository accumulates under
+`[Unreleased]` and bumps `VERSION` when a release is cut, so no single PR can
+correctly satisfy one.
+
## Commit Messages
Follow [Conventional Commits](https://www.conventionalcommits.org/). The
diff --git a/docs/audit/CLAIM_TO_GATE_MATRIX.md b/docs/audit/CLAIM_TO_GATE_MATRIX.md
index 46514b4ab..9b098d014 100644
--- a/docs/audit/CLAIM_TO_GATE_MATRIX.md
+++ b/docs/audit/CLAIM_TO_GATE_MATRIX.md
@@ -37,7 +37,7 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`
| Container image / IaC / secret scanning (Trivy/checkov/tfsec/gitleaks/Semgrep) | (implied by security) | `security.yml` (claim-matrix ratchet HARD; gitleaks/Semgrep/Trivy/checkov/tfsec observe) | PARTIAL (matrix ratchet enforced; secret + code/IaC/container scanners report-and-ratchet, allowlist at `.security/allowlist.yml` / `.gitleaksignore`; GitHub push-protection is the always-on hard secret gate) | Phase 2 |
| Signed / attested release artifacts | (implied by "run next to crown jewels") | `release.yml` + `publish-images.yml` (cosign keyless signatures, CycloneDX SBOM attestation, BuildKit SLSA provenance + SPDX SBOM per image; SHA-pinned actions), `build-extensions.yml` (extension cosign) | GATED | - |
| Insecure defaults hard-fail in production | (implied by self-host) | `ci.yml` api tests (`test_security_defaults.py::test_enforce_*`; `enforce_secure_defaults` raises at boot in production) | GATED | - |
-| OpenAPI stability for 3 SDKs + MCP | (implied by SDKs) | `check-openapi.yml` (drift) + `openapi-breaking.yml` (`scripts/openapi_diff.py` — PR spec vs base fails on removed endpoint/schema/field, type change, tightened request, or dropped enum value) | GATED | - |
+| OpenAPI stability for 3 SDKs + MCP | (implied by SDKs) | `check-openapi.yml` (drift) + `openapi-breaking.yml` (`scripts/openapi_diff.py` — PR spec vs base fails on removed endpoint/schema/field, type change, tightened request, or dropped enum value). A deliberate break goes through the `breaking-change-approved` PR label, which still runs the detector and records every break it permits plus the CHANGELOG `### BREAKING` note that justified it; `--allow-breaking` requires that note as an argument, so the bypass cannot be wired up without the record. Four of the tests assert the *workflow* reaches the flag — it previously had no caller at all | GATED | - |
| Ingested events land in the queryable ClickHouse lake | README (SIEM / lake) | `integration.yml :: spine` (Phase A1 — after the spine ingests, asserts `SELECT count() FROM aisoc.raw_events > 0` against the live ClickHouse container; `services/fusion` `LakeWriter` archives every normalized event) | GATED | - |
| Detection rules fire on the live event stream (not just CI fixtures) | README L170 (detection engine) | `integration.yml :: spine` (Phase A2 — posts an event matching the native `aws-root-account-login` rule, asserts the fusion `DetectionEngine` produces the alert) + `validate-detections.yml` (exported-ruleset drift `--check`) + fusion `test_detection_engine.py` / `test_detection_matcher_parity.py` | GATED | - |
| Three-model AI: behavioral (UEBA) model feeds alert scoring in production | README (multi-model) | `ci.yml` fusion job (`test_ueba_signal.py` — the `ueba.anomalies` stream warms a per-entity cache that boosts fuse-time confidence + anomaly score; wired in `fusion_engine.process`) | GATED | - |
diff --git a/scripts/openapi_diff.py b/scripts/openapi_diff.py
index 92b2eba66..db5f87d12 100644
--- a/scripts/openapi_diff.py
+++ b/scripts/openapi_diff.py
@@ -20,15 +20,23 @@ of an existing generated client. Breaking classes:
* an enum value was removed (a client with exhaustive handling breaks),
* a new required parameter was added to an existing operation.
-`--old`/`--new` take spec files; exit 1 if any breaking change is found (unless
-`--allow-breaking`, which the release flow uses when it deliberately ships a
-major bump). The CI job (`openapi-breaking.yml`) diffs the PR spec against the
-base branch's spec, so a breaking change blocks the PR until it's intentional.
+`--old`/`--new` take spec files; exit 1 if any breaking change is found. The CI
+job (`openapi-breaking.yml`) diffs the PR spec against the base branch's spec,
+so a breaking change blocks the PR until it is deliberate.
+
+Shipping one deliberately goes through `--allow-breaking`, which the gate passes
+only when a maintainer has applied the `breaking-change-approved` label to the
+pull request. The flag is not a silent bypass: it *requires* `--changelog` and
+`--changelog-base`, refuses the approval unless this change added a `### BREAKING`
+note under `## [Unreleased]`, and prints every break it is permitting — so the
+record says what was approved rather than merely that something was.
"""
from __future__ import annotations
import argparse
+import os
+import re
import sys
from dataclasses import dataclass
from pathlib import Path
@@ -156,12 +164,104 @@ def load_spec(path: Path) -> dict[str, Any]:
return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
-def main() -> int:
+# ── CHANGELOG evidence for an approved break ────────────────────────────────
+#
+# The approval label says a maintainer authorised the break. The CHANGELOG note
+# is what says *what* was broken, and it is the half that outlives CI logs.
+
+_H2 = re.compile(r"^##\s+")
+_H3 = re.compile(r"^###\s+")
+_UNRELEASED = re.compile(r"^##\s+\[Unreleased\]", re.IGNORECASE)
+_BREAKING_HEADING = re.compile(r"^###\s+BREAKING\b", re.IGNORECASE)
+
+
+def changelog_breaking_notes(text: str) -> list[str]:
+ """Non-blank lines under `### BREAKING` inside the `## [Unreleased]` section.
+
+ Scoped to Unreleased on purpose: a BREAKING heading in an already-shipped
+ release section describes a past break and must not stand in for this one.
+ """
+ lines = text.splitlines()
+ start = next((n for n, line in enumerate(lines) if _UNRELEASED.match(line)), None)
+ if start is None:
+ return []
+ notes: list[str] = []
+ in_breaking = False
+ for line in lines[start + 1 :]:
+ if _H2.match(line): # the next release section — Unreleased has ended
+ break
+ if _H3.match(line):
+ in_breaking = bool(_BREAKING_HEADING.match(line))
+ continue
+ if in_breaking and line.strip():
+ notes.append(line.strip())
+ return notes
+
+
+def changelog_evidence(old_text: str, new_text: str) -> tuple[list[str], str | None]:
+ """Notes this change added, or a reason the approval cannot be honoured.
+
+ Checked in both directions. "A BREAKING section exists" alone would let the
+ first such note in a release cycle excuse every later break in that cycle,
+ so the note must also differ from the base branch's.
+ """
+ new_notes = changelog_breaking_notes(new_text)
+ if not new_notes:
+ return [], "the CHANGELOG has no '### BREAKING' section with content under '## [Unreleased]'"
+ old_notes = set(changelog_breaking_notes(old_text))
+ added = [note for note in new_notes if note not in old_notes]
+ if not added:
+ return [], (
+ "the '### BREAKING' section under '## [Unreleased]' is byte-identical to the "
+ "base branch's, so it documents an earlier break and not this one"
+ )
+ return added, None
+
+
+def approval_record(breaking: list[Change], notes: list[str], approved_by: str) -> str:
+ """The audit line: who permitted it, and exactly what they permitted."""
+ lines = [
+ "## Breaking OpenAPI changes PERMITTED",
+ "",
+ f"Authorised by: {approved_by or 'not resolved — see the pull request timeline'}",
+ "",
+ f"The detector ran and found {len(breaking)} breaking change(s). All are permitted:",
+ "",
+ ]
+ lines += [f"- `{c.kind}` — {c.detail}" for c in breaking]
+ lines += ["", "CHANGELOG `### BREAKING` note added by this change:", ""]
+ lines += [f"> {note}" for note in notes]
+ return "\n".join(lines)
+
+
+def _write_step_summary(record: str) -> None:
+ """Mirror the record onto the check-run page, not just into the job log."""
+ path = os.environ.get("GITHUB_STEP_SUMMARY")
+ if not path:
+ return
+ with open(path, "a", encoding="utf-8") as handle:
+ handle.write(record + "\n")
+
+
+def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--old", required=True, type=Path, help="baseline spec (e.g. base branch / last release)")
parser.add_argument("--new", required=True, type=Path, help="candidate spec (e.g. this PR)")
- parser.add_argument("--allow-breaking", action="store_true", help="permit breaking changes (deliberate major bump)")
- args = parser.parse_args()
+ parser.add_argument(
+ "--allow-breaking",
+ action="store_true",
+ help="permit breaking changes; requires --changelog/--changelog-base as evidence",
+ )
+ parser.add_argument("--changelog", type=Path, help="candidate CHANGELOG.md (required with --allow-breaking)")
+ parser.add_argument("--changelog-base", type=Path, help="baseline CHANGELOG.md (required with --allow-breaking)")
+ parser.add_argument("--approved-by", default="", help="who authorised the break; recorded in the audit line")
+ args = parser.parse_args(argv)
+
+ # A bypass that can be taken on trust is not auditable. Requiring the
+ # evidence as arguments means --allow-breaking cannot be wired up later
+ # without also wiring up the thing that records what was approved.
+ if args.allow_breaking and not (args.changelog and args.changelog_base):
+ parser.error("--allow-breaking requires --changelog and --changelog-base (the CHANGELOG BREAKING note is the evidence)")
old = load_spec(args.old)
new = load_spec(args.new)
@@ -172,20 +272,38 @@ def main() -> int:
print(f"OK: no breaking OpenAPI changes ({len(changes)} total change(s))")
return 0
+ # The detector runs and names every break whether or not it is approved.
print(f"Found {len(breaking)} BREAKING OpenAPI change(s):", file=sys.stderr)
for c in breaking:
print(f" - [{c.kind}] {c.detail}", file=sys.stderr)
- if args.allow_breaking:
- print("--allow-breaking set: not failing (deliberate breaking release).", file=sys.stderr)
- return 0
- print(
- "\nBreaking API changes break every generated SDK client. Either avoid the "
- "break, or ship it deliberately with a version bump + CHANGELOG BREAKING note "
- "and re-run with --allow-breaking.",
- file=sys.stderr,
+ if not args.allow_breaking:
+ print(
+ "\nBreaking API changes break every generated SDK client. Either avoid the "
+ "break, or ship it deliberately: add a '### BREAKING' note under "
+ "'## [Unreleased]' in CHANGELOG.md saying what moved and why it could not "
+ "be preserved, then have a maintainer apply the 'breaking-change-approved' "
+ "label to the pull request.",
+ file=sys.stderr,
+ )
+ return 1
+
+ notes, problem = changelog_evidence(
+ args.changelog_base.read_text(encoding="utf-8"),
+ args.changelog.read_text(encoding="utf-8"),
)
- return 1
+ if problem:
+ print(
+ f"\nApproval REFUSED: {problem}. The label authorises a break; the CHANGELOG "
+ "note is what records which break, and it has to outlive this job log.",
+ file=sys.stderr,
+ )
+ return 1
+
+ record = approval_record(breaking, notes, args.approved_by)
+ print(record)
+ _write_step_summary(record)
+ return 0
if __name__ == "__main__":
diff --git a/tests/test_openapi_diff.py b/tests/test_openapi_diff.py
index db274c236..12f8c7d21 100644
--- a/tests/test_openapi_diff.py
+++ b/tests/test_openapi_diff.py
@@ -10,10 +10,17 @@ from __future__ import annotations
import sys
from pathlib import Path
+import pytest
+import yaml
+
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
import openapi_diff as od # noqa: E402
+_REPO = Path(__file__).resolve().parents[1]
+_WORKFLOW = _REPO / ".github" / "workflows" / "openapi-breaking.yml"
+_LABEL = "breaking-change-approved"
+
def _spec(paths=None, schemas=None):
return {
@@ -126,3 +133,220 @@ def test_ref_type_signature_change_is_breaking():
def test_identical_specs_have_no_changes():
s = _spec(paths={"/a": {"get": {}}}, schemas={"User": {"properties": {"id": {"type": "string"}}}})
assert od.diff(s, s) == []
+
+
+# ── The deliberate-break escape hatch ────────────────────────────────────────
+#
+# `--allow-breaking` shipped with no caller: the workflow triggered on
+# pull_request only and never passed the flag, so the documented way to ship a
+# deliberate break did not exist. These cover both halves — that the flag does
+# what it claims, and that the workflow actually reaches it.
+
+_CHANGELOG_BASE = """# Changelog
+
+## [Unreleased]
+
+### Security
+
+- something unrelated
+
+## [1.0.0]
+
+### BREAKING
+
+- an old break, already shipped
+"""
+
+_CHANGELOG_WITH_NOTE = """# Changelog
+
+## [Unreleased]
+
+### BREAKING
+
+- `Thing.health_score` is removed; it was an undefined composite.
+
+### Security
+
+- something unrelated
+
+## [1.0.0]
+
+### BREAKING
+
+- an old break, already shipped
+"""
+
+
+def _write_pair(tmp_path, old_spec, new_spec):
+ old = tmp_path / "old.yaml"
+ new = tmp_path / "new.yaml"
+ old.write_text(yaml.safe_dump(old_spec), encoding="utf-8")
+ new.write_text(yaml.safe_dump(new_spec), encoding="utf-8")
+ return old, new
+
+
+def _breaking_pair(tmp_path):
+ return _write_pair(
+ tmp_path,
+ _spec(schemas={"Thing": {"properties": {"id": {"type": "string"}, "health_score": {"type": "number"}}}}),
+ _spec(schemas={"Thing": {"properties": {"id": {"type": "string"}}}}),
+ )
+
+
+def _changelogs(tmp_path, new_text):
+ base = tmp_path / "base-CHANGELOG.md"
+ head = tmp_path / "CHANGELOG.md"
+ base.write_text(_CHANGELOG_BASE, encoding="utf-8")
+ head.write_text(new_text, encoding="utf-8")
+ return base, head
+
+
+def test_a_break_without_approval_still_fails(tmp_path):
+ old, new = _breaking_pair(tmp_path)
+ assert od.main(["--old", str(old), "--new", str(new)]) == 1
+
+
+def test_allow_breaking_without_changelog_evidence_is_an_argument_error(tmp_path):
+ """The bypass cannot be taken on trust: the evidence is mandatory.
+
+ Before this change `--allow-breaking` alone silently returned 0, which is
+ what made it usable as an invisible bypass had anything ever called it.
+ """
+ old, new = _breaking_pair(tmp_path)
+ with pytest.raises(SystemExit) as excinfo:
+ od.main(["--old", str(old), "--new", str(new), "--allow-breaking"])
+ assert excinfo.value.code == 2
+
+
+def test_approved_break_passes_when_the_changelog_records_it(tmp_path):
+ old, new = _breaking_pair(tmp_path)
+ base_cl, head_cl = _changelogs(tmp_path, _CHANGELOG_WITH_NOTE)
+ rc = od.main(
+ ["--old", str(old), "--new", str(new), "--allow-breaking", "--changelog", str(head_cl), "--changelog-base", str(base_cl)]
+ )
+ assert rc == 0
+
+
+def test_approved_break_is_refused_when_the_changelog_says_nothing(tmp_path):
+ old, new = _breaking_pair(tmp_path)
+ base_cl, head_cl = _changelogs(tmp_path, _CHANGELOG_BASE)
+ rc = od.main(
+ ["--old", str(old), "--new", str(new), "--allow-breaking", "--changelog", str(head_cl), "--changelog-base", str(base_cl)]
+ )
+ assert rc == 1
+
+
+def test_an_inherited_note_does_not_excuse_a_later_break(tmp_path):
+ """Both directions. "A BREAKING section exists" would let the first note in
+ a release cycle excuse every later break in that cycle."""
+ old, new = _breaking_pair(tmp_path)
+ base_cl = tmp_path / "base-CHANGELOG.md"
+ head_cl = tmp_path / "CHANGELOG.md"
+ base_cl.write_text(_CHANGELOG_WITH_NOTE, encoding="utf-8")
+ head_cl.write_text(_CHANGELOG_WITH_NOTE, encoding="utf-8")
+ rc = od.main(
+ ["--old", str(old), "--new", str(new), "--allow-breaking", "--changelog", str(head_cl), "--changelog-base", str(base_cl)]
+ )
+ assert rc == 1
+
+
+def test_a_note_in_a_shipped_release_section_is_not_evidence():
+ notes = od.changelog_breaking_notes(_CHANGELOG_BASE)
+ assert notes == [], "a BREAKING heading under [1.0.0] describes a past break"
+
+
+def test_the_approval_names_every_break_it_permits(tmp_path, capsys):
+ """"Approved" must record *what* was approved, not merely that something was."""
+ old, new = _write_pair(
+ tmp_path,
+ _spec(paths={"/gone": {"get": {}}}, schemas={"Thing": {"properties": {"id": {"type": "string"}, "score": {"type": "number"}}}}),
+ _spec(paths={}, schemas={"Thing": {"properties": {"id": {"type": "string"}}}}),
+ )
+ base_cl, head_cl = _changelogs(tmp_path, _CHANGELOG_WITH_NOTE)
+ rc = od.main(
+ [
+ "--old", str(old), "--new", str(new), "--allow-breaking",
+ "--changelog", str(head_cl), "--changelog-base", str(base_cl),
+ "--approved-by", "@maintainer at 2026-01-01T00:00:00Z",
+ ]
+ )
+ out = capsys.readouterr().out
+ assert rc == 0
+ assert "@maintainer at 2026-01-01T00:00:00Z" in out
+ assert "path '/gone' was removed" in out
+ assert "Thing.score was removed" in out
+ assert "health_score" in out, "the CHANGELOG note that justified it is part of the record"
+
+
+def test_the_approval_record_reaches_the_check_run_page(tmp_path, monkeypatch):
+ """A record only in the job log is one click further from a reviewer than
+ the summary, and job logs age out."""
+ summary = tmp_path / "summary.md"
+ monkeypatch.setenv("GITHUB_STEP_SUMMARY", str(summary))
+ old, new = _breaking_pair(tmp_path)
+ base_cl, head_cl = _changelogs(tmp_path, _CHANGELOG_WITH_NOTE)
+ od.main(
+ ["--old", str(old), "--new", str(new), "--allow-breaking", "--changelog", str(head_cl), "--changelog-base", str(base_cl)]
+ )
+ assert "Thing.health_score was removed" in summary.read_text(encoding="utf-8")
+
+
+# ── The workflow must actually reach the flag ────────────────────────────────
+
+
+def _workflow():
+ doc = yaml.safe_load(_WORKFLOW.read_text(encoding="utf-8"))
+ # PyYAML resolves a bare `on:` key to the boolean True (YAML 1.1).
+ triggers = doc.get("on", doc.get(True))
+ steps = doc["jobs"]["breaking-change"]["steps"]
+ return triggers, steps
+
+
+def _diff_steps():
+ _, steps = _workflow()
+ return [s for s in steps if "openapi_diff.py" in (s.get("run") or "")]
+
+
+def test_the_workflow_passes_allow_breaking_somewhere():
+ """The defect this closes: the flag existed, was tested, and had no caller."""
+ assert any("--allow-breaking" in s["run"] for s in _diff_steps()), (
+ "no step invokes --allow-breaking, so the documented escape hatch does not exist"
+ )
+
+
+def test_the_approved_path_is_guarded_by_the_label_and_presents_its_evidence():
+ approved = [s for s in _diff_steps() if "--allow-breaking" in s["run"]]
+ assert len(approved) == 1, "exactly one step may permit breaks"
+ step = approved[0]
+ assert _LABEL in str(step.get("if", "")), "the bypass must be guarded by the approval label"
+ assert "--changelog " in step["run"] and "--changelog-base" in step["run"]
+
+
+def test_the_unapproved_path_never_permits_a_break():
+ unapproved = [s for s in _diff_steps() if "--allow-breaking" not in s["run"]]
+ assert unapproved, "the ordinary blocking path must still exist"
+ for step in unapproved:
+ assert "--allow-breaking" not in step["run"]
+
+
+def test_the_approved_path_still_runs_the_detector():
+ """Approval must not short-circuit detection — otherwise the record cannot
+ say what was permitted."""
+ approved = [s for s in _diff_steps() if "--allow-breaking" in s["run"]][0]
+ assert "--old" in approved["run"] and "--new" in approved["run"]
+
+
+def test_applying_the_label_re_runs_the_gate():
+ """Without `labeled`, the label would only take effect on the next push —
+ a control that appears to do something and does not."""
+ triggers, _ = _workflow()
+ types = triggers["pull_request"]["types"]
+ assert "labeled" in types and "unlabeled" in types
+
+
+def test_the_label_name_the_script_tells_contributors_matches_the_workflow():
+ """One-directional drift: renaming the label in CI while the instructions
+ still name the old one leaves contributors following a dead procedure."""
+ script = (_REPO / "scripts" / "openapi_diff.py").read_text(encoding="utf-8")
+ assert _LABEL in script
+ assert _LABEL in _WORKFLOW.read_text(encoding="utf-8")