Skip to content

Commit 1ba9f60

Browse files
authored
Merge pull request #358 from PhysShell/claude/p022-merge-gate-ci
ci(step7): the merge gate becomes a check, not a script in a drawer
2 parents 40c7efa + 715bbe7 commit 1ba9f60

3 files changed

Lines changed: 508 additions & 0 deletions

File tree

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: P-022 merge gate
2+
3+
# The merge order for the #263 preregistration, as a check rather than an
4+
# agreement. `mergegate.py` is run against the commit a merge would PRODUCE —
5+
# for a pull_request event that is `github.sha`, the merge ref, not the branch
6+
# head — because a PR number proves someone pressed a button and says nothing
7+
# about what the merged tree contains.
8+
#
9+
# Two jobs, and the gate needs the controls: a gate whose own controls are
10+
# failing must not be the thing that says a merge is safe. A failed controls job
11+
# leaves the gate job unreported, which a required check reads as unsatisfied.
12+
#
13+
# This workflow is one half of the wiring. The other half is a ruleset requiring
14+
# these two checks; without it the job reports and nothing is prevented. The
15+
# names below are the contexts that ruleset must name:
16+
#
17+
# P-022 merge gate controls
18+
# P-022 merge gate
19+
#
20+
# Least privilege as elsewhere in this repository: read-only, and every
21+
# third-party `uses:` pinned to a commit SHA with its version in a comment.
22+
23+
permissions:
24+
contents: read
25+
26+
on:
27+
pull_request:
28+
workflow_dispatch:
29+
30+
jobs:
31+
controls:
32+
name: P-022 merge gate controls
33+
runs-on: ubuntu-latest
34+
steps:
35+
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
36+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
37+
with:
38+
python-version: "3.11"
39+
- name: the gate's own controls (fixtures ship the real tools and mutate them)
40+
run: python tests/test_step7_mergegate.py
41+
- name: the wiring's controls (applicability and co-change)
42+
run: python tests/test_step7_mergegate_ci.py
43+
44+
gate:
45+
name: P-022 merge gate
46+
needs: controls
47+
runs-on: ubuntu-latest
48+
steps:
49+
# Full history: the co-change rule compares the gate's own files against
50+
# the base commit, which a shallow clone would not carry.
51+
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
52+
with:
53+
fetch-depth: 0
54+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
55+
with:
56+
python-version: "3.11"
57+
- name: the gate, against the commit this merge would produce
58+
env:
59+
# Read through the environment rather than interpolated into the
60+
# script body, so nothing from the event can be read as shell.
61+
MERGE_COMMIT: ${{ github.sha }}
62+
BASE_COMMIT: ${{ github.event.pull_request.base.sha }}
63+
run: |
64+
set -euo pipefail
65+
if [ -n "${BASE_COMMIT}" ]; then
66+
python scripts/step7/mergegate_ci.py --repo . \
67+
--commit "${MERGE_COMMIT}" --base "${BASE_COMMIT}"
68+
else
69+
python scripts/step7/mergegate_ci.py --repo . --commit "${MERGE_COMMIT}"
70+
fi

‎scripts/step7/mergegate_ci.py‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
#!/usr/bin/env python3
2+
"""P-022 — the merge gate as a status check.
3+
4+
`mergegate.py` answers one question: may the frozen contract become reachable
5+
from this tree? It answers it about a tree that *has* a frozen contract. A
6+
required status check runs on every pull request in the repository, including
7+
the ones that have nothing to do with P-022, so two rules have to be settled
8+
before that gate can be wired to a branch protection rule.
9+
10+
**Applicability.** If the frozen T0 does not exist at the merge commit, no merge
11+
can make it reachable and there is nothing to protect. The check passes and says
12+
so. This is not a way around the gate: the moment a tree carries T0, every
13+
predicate applies in full.
14+
15+
**Co-change.** A required check that a pull request can rewrite is decoration.
16+
The workflow that runs on a pull request is the one *on that pull request*, so a
17+
branch may carry both the freeze and a weakened gate and be judged by the gate
18+
it brought with it. So: **the gate's own files may not change in the same merge
19+
that introduces or changes the frozen contract.** Repairing the gate is still
20+
ordinary work; doing it in the same breath as the freeze is not.
21+
22+
Neither rule is enforcement isolation. A repository administrator can turn the
23+
protection off, and this script cannot see that. What it removes is the quiet
24+
path — a weakened gate arriving as part of the change it was meant to judge.
25+
26+
Exit codes: 0 the merge may proceed (or the gate does not apply), 1 it is
27+
refused, 2 the question could not be asked.
28+
29+
python scripts/step7/mergegate_ci.py --repo . --commit <merge sha> \
30+
--base <base sha>
31+
32+
`--base` is what the co-change rule compares against. Without it the rule cannot
33+
run, and the output says that rather than implying it passed.
34+
"""
35+
36+
from __future__ import annotations
37+
38+
import argparse
39+
import subprocess
40+
import sys
41+
from pathlib import Path
42+
43+
sys.path.insert(0, str(Path(__file__).resolve().parent))
44+
45+
import mergegate as mg
46+
47+
# The gate's own surface: the predicates, this wrapper, and the workflow that
48+
# runs them. A change to any of these changes what "the gate passed" means.
49+
GATE_FILES = ("scripts/step7/mergegate.py",
50+
"scripts/step7/mergegate_ci.py",
51+
".github/workflows/p022-merge-gate.yml")
52+
53+
54+
def blob_sha(repo: Path, commit: str, path: str) -> str | None:
55+
"""The blob a path resolves to, or None when the path is not there."""
56+
proc = subprocess.run(["git", "-C", str(repo), "rev-parse", f"{commit}:{path}"],
57+
capture_output=True, text=True, check=False)
58+
return proc.stdout.strip() if proc.returncode == 0 else None
59+
60+
61+
def applies(repo: Path, commit: str) -> bool:
62+
return blob_sha(repo, commit, mg.T0_PATH) is not None
63+
64+
65+
def is_commit(repo: Path, rev: str) -> bool:
66+
return subprocess.run(["git", "-C", str(repo), "rev-parse", f"{rev}^{{commit}}"],
67+
capture_output=True, check=False).returncode == 0
68+
69+
70+
def co_change(repo: Path, commit: str, base: str) -> list[str]:
71+
"""Which gate files this merge changes, if it also touches the contract.
72+
73+
Empty when the contract is untouched: repairing the gate is ordinary work.
74+
"""
75+
t0_now, t0_base = blob_sha(repo, commit, mg.T0_PATH), blob_sha(repo, base, mg.T0_PATH)
76+
if t0_now == t0_base:
77+
return []
78+
return [path for path in GATE_FILES
79+
if blob_sha(repo, commit, path) != blob_sha(repo, base, path)]
80+
81+
82+
def main(argv: list[str] | None = None) -> int:
83+
parser = argparse.ArgumentParser(description=__doc__)
84+
parser.add_argument("--repo", type=Path, default=Path("."))
85+
parser.add_argument("--commit", required=True,
86+
help="the commit a merge would produce, not the branch head")
87+
parser.add_argument("--base", help="the base commit the co-change rule compares against")
88+
args = parser.parse_args(argv)
89+
90+
if not is_commit(args.repo, args.commit):
91+
print(f"merge gate: MISUSE — {args.commit} is not a commit in {args.repo}")
92+
return 2
93+
# A base that is not in the clone would make every gate file look changed,
94+
# and the co-change rule would refuse for a reason that is about the checkout
95+
# rather than about the merge. A question that cannot be asked is not a no.
96+
if args.base is not None and not is_commit(args.repo, args.base):
97+
print(f"merge gate: MISUSE — the base {args.base} is not a commit in {args.repo}; "
98+
"the co-change rule cannot be evaluated, and a shallow checkout must not be "
99+
"reported as a rewritten gate")
100+
return 2
101+
102+
if not applies(args.repo, args.commit):
103+
print(f"merge gate: not applicable — {mg.T0_PATH} does not exist at {args.commit[:12]}, "
104+
"so no merge here can make the frozen contract reachable. Every predicate "
105+
"applies the moment a tree carries it.")
106+
return 0
107+
108+
if args.base is None:
109+
print("merge gate: the co-change rule did not run — no --base was given, so this pass "
110+
"cannot say whether the gate itself changed alongside the contract")
111+
else:
112+
changed = co_change(args.repo, args.commit, args.base)
113+
if changed:
114+
print("merge gate: REFUSED — this merge changes the frozen contract and the gate "
115+
f"that judges it in one act: {', '.join(changed)}. Repair the gate in its own "
116+
"merge; a guard that arrives with what it guards is not a guard.")
117+
return 1
118+
print("ok [gate_unchanged] the contract moves and the gate does not; this merge is "
119+
"judged by the gate already on the base")
120+
121+
results = mg.gate(args.repo, args.commit)
122+
for row in results:
123+
mark = "ok " if row["result"] == "pass" else "FAIL"
124+
print(f"{mark} [{row['check']}] {row['detail']}")
125+
bad = [r for r in results if r["result"] != "pass"]
126+
print()
127+
if bad:
128+
print(f"merge gate: REFUSED, {len(bad)} predicate(s) unsatisfied — the frozen contract "
129+
"must not become reachable from this tree")
130+
return 1
131+
print("merge gate: allowed")
132+
return 0
133+
134+
135+
if __name__ == "__main__":
136+
sys.exit(main())

0 commit comments

Comments
 (0)