fix(622): bind H10 merge consent to the reviewed sha via a required commit status #630
@@ -7,6 +7,14 @@
|
||||
# (c) a review-verdict comment on the PR references the CURRENT head sha (H10) — proving the
|
||||
# LATEST commit was reviewed, not a stale earlier diff (the ersatztv#242 failure mode:
|
||||
# "re-review the fix commit, not just the initial PR diff").
|
||||
#
|
||||
# EVERY ONE OF THOSE IS A SNAPSHOT, taken when the merge tool is called. That is sound for an
|
||||
# immediate merge and UNSOUND for a scheduled one: with merge_when_checks_succeed, Gitea merges
|
||||
# later, against whatever head is green then (ersatztv#622). So the sha-bound half of H10 is
|
||||
# enforced by the SERVER, not here — `review-verdict/h10` is a required status check on `main`,
|
||||
# written per-sha by scripts/post-review-verdict.sh, and a new commit cannot inherit it. This hook
|
||||
# additionally refuses to SCHEDULE an auto-merge unless that status is already green on head, so the
|
||||
# two mechanisms agree at the only moment they can both observe the same commit.
|
||||
# The "## Done-when" issue-body checklist is the convention (docs/decisions.md, CLAUDE.md Task
|
||||
# Completion Protocol). One box is "adversarial review passed"; the others are per-issue.
|
||||
# The H10 review-verdict convention: after reviewing a PR (or its latest fix commit), post a PR
|
||||
@@ -77,8 +85,41 @@ sha=$(printf '%s' "$prjson" | jq -r '.head.sha // ""' 2>/dev/null || true)
|
||||
body=$(printf '%s' "$prjson" | jq -r '.body // ""' 2>/dev/null || true)
|
||||
|
||||
# --- Docs-only exemption: if every changed file is docs/process, skip the gate. ---
|
||||
files=$(gq "repos/$owner/$repo/pulls/$pr/files?limit=100" | jq -r '.[].filename // empty' 2>/dev/null || true)
|
||||
if [ -n "$files" ] && ! printf '%s\n' "$files" | grep -qvE '^(docs/|\.claude/|\.husky/|\.gitea/|.*\.md$)'; then
|
||||
# The file list must be enumerated EXHAUSTIVELY or the exemption is unsafe. Gitea caps this
|
||||
# endpoint at 50 rows per page and silently ignores a larger `limit` (verified: PR #619 has 194
|
||||
# changed files and `?limit=100` returns exactly 50), so the previous single-page read could see 50
|
||||
# docs files, miss the code in positions 51+, and exempt a PR that is not remotely docs-only.
|
||||
# Page until a short page proves the end; anything else leaves `files_complete=no`, which withholds
|
||||
# the exemption and falls through to the full gate (ersatztv#622).
|
||||
files=""; files_complete=no; page=1
|
||||
while [ "$page" -le 40 ]; do
|
||||
raw=$(gq "repos/$owner/$repo/pulls/$pr/files?limit=50&page=$page")
|
||||
# A transport/parse failure must not look like a legitimate short final page: `gq` returns empty
|
||||
# on any error, which counts as zero rows and would set files_complete=yes over a PARTIAL list —
|
||||
# failing OPEN into the exemption.
|
||||
#
|
||||
# Checking only the top-level type leaves the same hole one level down: `[{}]` is a valid array
|
||||
# whose rows carry no `filename`, so it yields no paths, looks like a short page, and completes
|
||||
# the enumeration from a partial list. Require every row to carry a non-empty string `filename`
|
||||
# (an empty array is still valid — that is a genuine end-of-pagination). This also rejects arrays
|
||||
# of scalars, which would otherwise make the `.filename` extraction below fail under `set -e`.
|
||||
if ! printf '%s' "$raw" \
|
||||
| jq -e 'type == "array" and all(.[]; (.filename | type == "string" and length > 0) and (if .status == "renamed" then (.previous_filename | type == "string" and length > 0) else true end))' \
|
||||
>/dev/null 2>&1; then
|
||||
files_complete=no; break
|
||||
fi
|
||||
# BOTH sides of a rename: Gitea reports a `git mv` as ONE row whose `filename` is the DESTINATION,
|
||||
# with the source in `previous_filename`. Reading only `filename` would let a PR move code into
|
||||
# docs/ and claim the docs-only exemption. Page size is measured in ROWS, not paths — one renamed
|
||||
# row is one row but two paths.
|
||||
n=$(printf '%s' "$raw" | jq -r 'length')
|
||||
chunk=$(printf '%s' "$raw" | jq -r '.[] | (.filename // empty), (.previous_filename // empty)')
|
||||
[ -n "$chunk" ] && files=$(printf '%s\n%s' "$files" "$chunk")
|
||||
if [ "$n" -lt 50 ]; then files_complete=yes; break; fi
|
||||
page=$((page + 1))
|
||||
done
|
||||
files=$(printf '%s\n' "$files" | grep -v '^$' || true)
|
||||
if [ "$files_complete" = yes ] && [ -n "$files" ] && ! printf '%s\n' "$files" | grep -qvE '^(docs/|\.claude/|\.husky/|\.gitea/|.*\.md$)'; then
|
||||
# Docs/process-only PR: the Done-when + review-verdict gate doesn't apply — but this exemption is a
|
||||
# file-TYPE bypass, NOT the a+b+c "provably reviewed & ready" proof, so it does NOT auto-grant. It
|
||||
# passes through to normal permissioning (one prompt). This deliberately keeps a human in the loop for
|
||||
@@ -113,11 +154,71 @@ done
|
||||
# --- (a) CI combined status must be green (unless deferring to Gitea's own check-gate). ---
|
||||
if [ "$mwcs" != "true" ]; then
|
||||
[ -n "$sha" ] || decide ask "H6 merge gate: could not resolve PR #$pr head sha to check CI. Verify CI is green before merging."
|
||||
state=$(gq "repos/$owner/$repo/commits/$sha/status" | jq -r '.state // ""' 2>/dev/null || true)
|
||||
cistatus=$(gq "repos/$owner/$repo/commits/$sha/status?limit=100")
|
||||
state=$(printf '%s' "$cistatus" | jq -r '.state // ""' 2>/dev/null || true)
|
||||
case "$state" in
|
||||
success) : ;;
|
||||
"") decide ask "H6 merge gate: could not read CI status for PR #$pr ($sha). Verify CI is green before merging." ;;
|
||||
*) decide deny "H6 merge gate: BLOCKED — PR #$pr CI status is '$state', not 'success'. Wait for a green build (or pass merge_when_checks_succeed to let Gitea gate it) before merging." ;;
|
||||
*)
|
||||
# `review-verdict/h10` is itself one of the contexts folded into the COMBINED state, so a PR
|
||||
# awaiting its verdict reports combined 'pending' and would otherwise be reported as a CI
|
||||
# problem — sending the reader to build logs when the missing thing is the review. Name the
|
||||
# real blocker when the verdict is the only thing outstanding.
|
||||
#
|
||||
# "Not green" is anything that is not `success`, NOT just pending/failure: Gitea also has
|
||||
# `error` (and `warning`), and omitting those would let an errored build hide behind the
|
||||
# verdict and produce the flatly false claim "every CI check is green". `skipped` IS treated
|
||||
# as green — the image-push job skips on every PR (ersatztv#593: a skipped context is not red).
|
||||
nongreen=$(printf '%s' "$cistatus" \
|
||||
| jq -r '[.statuses[]? | select(.status != "success" and .status != "skipped")]
|
||||
| map("\(.context)=\(.status)") | join(", ")' 2>/dev/null || true)
|
||||
# The verdict's OWN state decides the wording: absent/pending means nobody has reviewed this
|
||||
# head, while failure/error means someone reviewed it and said no. Telling a reviewer to "post
|
||||
# a verdict" when they already posted a BLOCKED one would be actively misleading.
|
||||
vonly=$(printf '%s' "$cistatus" \
|
||||
| jq -r '[.statuses[]? | select(.status != "success" and .status != "skipped")]
|
||||
| if (length == 1 and .[0].context == "review-verdict/h10") then .[0].status else "" end' 2>/dev/null || true)
|
||||
case "$vonly" in
|
||||
pending)
|
||||
decide deny "H6/H10 merge gate: BLOCKED — every CI check on PR #$pr is green; the only outstanding context is 'review-verdict/h10' on head ${sha:0:7}, i.e. this head has no review verdict yet. Review it and run: scripts/post-review-verdict.sh $pr MERGEABLE" ;;
|
||||
failure|error)
|
||||
decide deny "H6/H10 merge gate: BLOCKED — every CI check on PR #$pr is green, but 'review-verdict/h10' is '$vonly' on head ${sha:0:7}: this head was reviewed and REJECTED. Resolve the findings, then run: scripts/post-review-verdict.sh $pr MERGEABLE" ;;
|
||||
esac
|
||||
decide deny "H6 merge gate: BLOCKED — PR #$pr CI status is '$state', not 'success' (not green: ${nongreen:-unknown}). Wait for a green build (or pass merge_when_checks_succeed to let Gitea gate it) before merging."
|
||||
;;
|
||||
esac
|
||||
else
|
||||
# --- SCHEDULED auto-merge: everything this hook proves is a SNAPSHOT (ersatztv#622). ----------
|
||||
# With merge_when_checks_succeed, Gitea performs the merge later, against whatever head is green
|
||||
# at THAT moment — but (b) and (c) below are evaluated against the head that exists right now.
|
||||
# Any commit pushed in between would merge with no verdict covering it. Demonstrated as a
|
||||
# controlled A/B (#622): with a slow CI check pending so Gitea waits, an unreviewed commit pushed
|
||||
# after scheduling MERGED without the required verdict context and was REFUSED with it.
|
||||
#
|
||||
# The durable fix is server-side and lives outside this hook: `review-verdict/h10` is a REQUIRED
|
||||
# status check on `main`, and a commit status belongs to exactly ONE sha, so a later commit cannot
|
||||
# inherit it and Gitea's own gate refuses to merge until that head is re-reviewed.
|
||||
#
|
||||
# What we add HERE is the matching precondition at SCHEDULING time: refuse to arm an auto-merge
|
||||
# unless the sha-bound status already exists on this head. Checking the comment alone (condition
|
||||
# (c) below) is not enough for this path — the comment is what a human reads, the status is what
|
||||
# the server enforces, and only the latter survives a new push. Deny rather than ask: the remedy
|
||||
# is a single documented command, so there is nothing here for a human to adjudicate.
|
||||
[ -n "$sha" ] || decide ask "H6 merge gate: could not resolve PR #$pr head sha to check the review-verdict status. Verify the review covered the latest commit before scheduling an auto-merge."
|
||||
# Read the COMBINED endpoint, not `/statuses/{sha}`: the latter returns one row per status POST
|
||||
# rather than per context and pages at 50, so a head with a few CI reruns can push the verdict off
|
||||
# the first page and read as absent — a confusing false deny. The combined endpoint returns
|
||||
# latest-per-context, which is exactly the question being asked.
|
||||
vjson=$(gq "repos/$owner/$repo/commits/$sha/status?limit=100")
|
||||
if ! printf '%s' "$vjson" | jq -e '.statuses | type == "array"' >/dev/null 2>&1; then
|
||||
decide ask "H6/H10 merge gate: could not read the 'review-verdict/h10' status for PR #$pr head ${sha:0:7} (Gitea unreachable or an unexpected response). Confirm the current head is reviewed before scheduling an auto-merge."
|
||||
fi
|
||||
vstate=$(printf '%s' "$vjson" | jq -r '[.statuses[] | select(.context == "review-verdict/h10")] | first | .status // ""')
|
||||
case "$vstate" in
|
||||
success) : ;;
|
||||
"") decide deny "H6/H10 merge gate: BLOCKED — PR #$pr has no 'review-verdict/h10' commit status on head ${sha:0:7}, so scheduling an auto-merge would freeze consent at a head Gitea may not be the one to merge (ersatztv#622). Review the current head and run: scripts/post-review-verdict.sh $pr MERGEABLE" ;;
|
||||
pending) decide deny "H6/H10 merge gate: BLOCKED — 'review-verdict/h10' is still pending on PR #$pr head ${sha:0:7} (no verdict posted for this commit yet). Review the current head and run: scripts/post-review-verdict.sh $pr MERGEABLE" ;;
|
||||
*) decide deny "H6/H10 merge gate: BLOCKED — 'review-verdict/h10' is '$vstate' on PR #$pr head ${sha:0:7}. Resolve the findings, then run: scripts/post-review-verdict.sh $pr MERGEABLE" ;;
|
||||
esac
|
||||
fi
|
||||
|
||||
@@ -170,7 +271,13 @@ if [ "$head_neg" = 1 ]; then
|
||||
decide deny "H10 merge gate: BLOCKED — a review verdict for the current head ($short) is negative (BLOCKED/NOT-MERGEABLE). Resolve the findings and post a fresh 'Review-verdict: MERGEABLE @ $short' before merging PR #$pr."
|
||||
fi
|
||||
if [ "$head_pos" = 1 ]; then
|
||||
# (a) CI green + (b) all Done-when ticked + (c) positive verdict @ current head -> SATISFIED. Auto-grant.
|
||||
# (a) CI + (b) all Done-when ticked + (c) positive verdict @ current head -> SATISFIED. Auto-grant.
|
||||
# The reason string must not claim more than was actually checked: on the merge_when_checks_succeed
|
||||
# path this hook never read the CI status at all (it is delegated to Gitea), so saying "CI green"
|
||||
# there was a plain falsehood in the one message a human reads to decide whether to trust the gate.
|
||||
if [ "$mwcs" = "true" ]; then
|
||||
decide grant "H6/H10 merge gate: satisfied — all Done-when boxes ticked, and both a positive Review-verdict comment and the 'review-verdict/h10' status cover the current head ($short). CI is gated by Gitea (merge_when_checks_succeed), and because the verdict status is bound to this sha, a commit pushed before Gitea merges will clear it and block the merge (ersatztv#622). Auto-granted."
|
||||
fi
|
||||
decide grant "H6/H10 merge gate: satisfied — CI green, all Done-when boxes ticked, and a positive Review-verdict references the current head ($short). Auto-granted (no separate confirmation needed)."
|
||||
fi
|
||||
if [ "$stale" = 1 ]; then
|
||||
|
||||
@@ -0,0 +1,193 @@
|
||||
name: Review verdict
|
||||
|
||||
# ersatztv#622 — server-side H10 enforcement.
|
||||
#
|
||||
# THE INVARIANT. `review-verdict/h10` is a REQUIRED status check on `main`, and a Gitea commit
|
||||
# status belongs to exactly ONE sha. So a commit that did not exist when a verdict was written can
|
||||
# never inherit that verdict: push a new head and the required context is simply absent, which
|
||||
# Gitea's merge-requirement check treats as not-passing. `merge_when_checks_succeed` therefore
|
||||
# refuses to fire until someone re-reviews THAT head. This is what closes the ersatztv#622 hole,
|
||||
# where the PreToolUse hook proved conditions (b) and (c) against the head at SCHEDULING time and
|
||||
# Gitea then merged whatever head happened to be green minutes later.
|
||||
#
|
||||
# WHAT THIS WORKFLOW DOES — and, importantly, does NOT do. It does NOT decide whether code was
|
||||
# reviewed; only a human/agent review does that, via `scripts/post-review-verdict.sh`, which writes
|
||||
# the `review-verdict/h10` status directly. This workflow only handles the two EXEMPT classes that
|
||||
# would otherwise deadlock, and marks everything else `pending` so the PR shows an explicit,
|
||||
# actionable blocking reason instead of a silently-missing check:
|
||||
#
|
||||
# 1. Bot-authored PRs (Renovate). Renovate uses `platformAutomerge: true` — i.e. Gitea's OWN
|
||||
# auto-merge — to land patch bumps unattended. A required verdict context with no exemption
|
||||
# would stall every dependency PR forever waiting on a human verdict.
|
||||
# 2. Docs-only PRs, mirroring the merge-consent hook's existing docs-only carve-out.
|
||||
#
|
||||
# BOTH exemptions are void when the PR touches a PROTECTED path (see PROTECTED below): the gate,
|
||||
# the CI definition, the git hooks, the scripts they call, and the CI toolchain image. A PR that
|
||||
# weakens the merge gate must never be able to exempt itself from the merge gate — that is the one
|
||||
# self-referential failure worth spending an explicit rule on. Note this also (deliberately) means
|
||||
# Renovate's `docker/ci/Dockerfile` base bumps need a real verdict; those already require the
|
||||
# manual publish-then-pin two-step (docs/ci-cd.md -> "CI toolchain image"), so unattended merge was
|
||||
# never correct for them anyway.
|
||||
#
|
||||
# WHY ITS OWN FILE, not a job in pr-checks.yml: that workflow sets `cancel-in-progress: true`, so a
|
||||
# superseding push cancels its runs. A cancelled run here would leave an EXEMPT PR with no success
|
||||
# status and no further pushes to re-trigger it — Renovate would stall silently. This workflow
|
||||
# therefore takes no cancelling concurrency group.
|
||||
#
|
||||
# This job's OWN status context ("Review verdict / Set review-verdict status (pull_request)") is
|
||||
# NOT the required check and is not what gates merges — `review-verdict/h10`, the status it POSTS,
|
||||
# is. Keeping them distinct is deliberate: a workflow cannot be allowed to satisfy the gate merely
|
||||
# by running successfully.
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, reopened, synchronize, ready_for_review]
|
||||
|
||||
defaults:
|
||||
run:
|
||||
shell: bash
|
||||
|
||||
jobs:
|
||||
set-verdict-status:
|
||||
name: Set review-verdict status
|
||||
runs-on: small # a few API calls; keep it off the build runners
|
||||
steps:
|
||||
- name: Classify the PR and post the review-verdict status
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
BASE_URL: ${{ github.server_url }}/api/v1
|
||||
REPO: ${{ github.repository }}
|
||||
PR: ${{ github.event.pull_request.number }}
|
||||
SHA: ${{ github.event.pull_request.head.sha }}
|
||||
AUTHOR: ${{ github.event.pull_request.user.login }}
|
||||
PR_URL: ${{ github.event.pull_request.html_url }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
CONTEXT="review-verdict/h10"
|
||||
# Accounts whose PRs may merge without a human verdict. Renovate only — keep this list
|
||||
# minimal and explicit; every entry is an account that can land code unreviewed.
|
||||
BOTS="renovate"
|
||||
# Paths where NEITHER exemption applies, because a change here can alter the gate itself,
|
||||
# what CI runs, or what the hooks enforce.
|
||||
PROTECTED='^(\.claude/|\.gitea/|\.husky/|scripts/|docker/ci/)'
|
||||
# Docs-only: prose and decision records. Deliberately narrower than the hook's pattern,
|
||||
# which also lets .claude/.gitea/.husky through — that carve-out is safe there only
|
||||
# because it falls through to a HUMAN PROMPT, whereas here it would post a green status
|
||||
# with nobody in the loop.
|
||||
DOCS_ONLY='^(docs/|[^/]*\.md$)'
|
||||
|
||||
if [ -z "${GITEA_TOKEN:-}" ]; then
|
||||
echo "::error::No GITEA_TOKEN available, so the ${CONTEXT} status cannot be written. An exempt (bot/docs-only) PR will stall until this is fixed; a normal PR is unaffected — post its verdict with scripts/post-review-verdict.sh."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
gh() { curl -sf -H "Authorization: token $GITEA_TOKEN" "$@"; }
|
||||
|
||||
# --- Already decided for THIS sha? Never overwrite a real verdict. -------------------
|
||||
# A human/agent verdict for this exact head may already exist (the reviewer ran the
|
||||
# script before this workflow finished, or a rerun). Re-posting `pending` over it would
|
||||
# un-approve a reviewed head and stall the PR.
|
||||
#
|
||||
# Read the COMBINED endpoint, not `/statuses/{sha}`: the latter returns one row per
|
||||
# status POST (not per context) and pages at 50, so a head with a few CI reruns can push
|
||||
# an earlier verdict off the first page. Missing it here is NOT harmless — we would post
|
||||
# `pending` (or worse, an exemption `success`) over a real human verdict. The combined
|
||||
# endpoint returns latest-per-context, which is both what we mean and ~11 rows.
|
||||
#
|
||||
# An unreadable/unparseable response must NOT be read as "no verdict exists": fail the
|
||||
# job WITHOUT posting anything, so a transient API error can never overwrite a verdict.
|
||||
statusjson=$(gh "$BASE_URL/repos/$REPO/commits/$SHA/status?limit=100") || statusjson=""
|
||||
if ! printf '%s' "$statusjson" | jq -e '.statuses | type == "array"' >/dev/null 2>&1; then
|
||||
echo "::error::Could not read existing commit statuses for ${SHA:0:7}. Refusing to post anything rather than risk overwriting an existing verdict."
|
||||
exit 1
|
||||
fi
|
||||
existing=$(printf '%s' "$statusjson" \
|
||||
| jq -r --arg c "$CONTEXT" '[.statuses[] | select(.context == $c)] | first | .status // ""')
|
||||
if [ "$existing" = "success" ] || [ "$existing" = "failure" ]; then
|
||||
echo "${CONTEXT} is already '${existing}' on ${SHA:0:7} — leaving the existing verdict alone."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# --- Changed files: PAGE to exhaustion, and fail CLOSED if we cannot. ----------------
|
||||
# Gitea caps this endpoint at 50 rows per page and SILENTLY IGNORES a larger `limit`
|
||||
# (verified: PR #619 has 194 changed files and `?limit=100` returns exactly 50). A
|
||||
# single-page read is therefore a silent false negative: a protected path sitting at
|
||||
# position 51+ would simply not be seen, and a bot-authored PR that edits the gate could
|
||||
# exempt itself from the gate. Page until a short page proves the end.
|
||||
PAGE_SIZE=50
|
||||
MAX_PAGES=40 # 2000 files; beyond this we refuse rather than guess
|
||||
files=""
|
||||
page=1
|
||||
complete=no
|
||||
while [ "$page" -le "$MAX_PAGES" ]; do
|
||||
raw=$(gh "$BASE_URL/repos/$REPO/pulls/$PR/files?limit=${PAGE_SIZE}&page=${page}") || raw=""
|
||||
# A transport/parse failure must NOT masquerade as a legitimate short final page.
|
||||
# Empty output counts as zero rows, which would otherwise read as "end of list" and set
|
||||
# complete=yes over a PARTIAL enumeration — failing OPEN at the exact point this guard
|
||||
# exists to fail closed.
|
||||
#
|
||||
# Validating only the TOP-LEVEL type is not enough: a page like `[{}]` is a well-formed
|
||||
# array whose rows carry no `filename`, so it contributes no paths, counts as a short
|
||||
# page, and completes the enumeration from a partial list — the same failure one level
|
||||
# down. Require every row to carry a non-empty string `filename`; an empty array stays
|
||||
# valid, since that is what a genuine end-of-pagination looks like.
|
||||
if ! printf '%s' "$raw" \
|
||||
| jq -e 'type == "array" and all(.[]; (.filename | type == "string" and length > 0) and (if .status == "renamed" then (.previous_filename | type == "string" and length > 0) else true end))' \
|
||||
>/dev/null 2>&1; then
|
||||
complete=no; break
|
||||
fi
|
||||
# Page-size termination is measured in ROWS; the path set collects BOTH sides of a
|
||||
# rename. Gitea reports a `git mv` as ONE row whose `filename` is the DESTINATION, with
|
||||
# the source only in `previous_filename` — so reading `filename` alone lets a PR move a
|
||||
# protected file INTO docs/ and pass as docs-only (verified live:
|
||||
# `.gitea/workflows/renovate.yml` -> `docs/innocuous-note.md` showed no protected path).
|
||||
# One renamed row thus contributes ONE to `n` and TWO to the path set, which is why
|
||||
# these two counts are deliberately computed differently.
|
||||
n=$(printf '%s' "$raw" | jq -r 'length')
|
||||
chunk=$(printf '%s' "$raw" | jq -r '.[] | (.filename // empty), (.previous_filename // empty)')
|
||||
[ -n "$chunk" ] && files=$(printf '%s\n%s' "$files" "$chunk")
|
||||
if [ "$n" -lt "$PAGE_SIZE" ]; then complete=yes; break; fi
|
||||
page=$((page + 1))
|
||||
done
|
||||
files=$(printf '%s\n' "$files" | grep -v '^$' || true)
|
||||
count=$(printf '%s\n' "$files" | grep -c . || true)
|
||||
echo "Changed files (${count}, complete=${complete}, pages=${page}):"
|
||||
printf '%s\n' "$files" | sed 's/^/ /'
|
||||
|
||||
exempt=no
|
||||
reason=""
|
||||
if [ "$complete" != yes ]; then
|
||||
reason="could not enumerate the changed files exhaustively (stopped at ${count}) — no exemption"
|
||||
elif [ "${count:-0}" -eq 0 ]; then
|
||||
reason="no changed files could be read from the API — no exemption"
|
||||
elif printf '%s\n' "$files" | grep -qE "$PROTECTED"; then
|
||||
reason="touches a protected path (gate/CI/hooks/scripts/ci-image) — exemptions do not apply"
|
||||
elif printf '%s\n' "$BOTS" | tr ' ' '\n' | grep -qxF "$AUTHOR"; then
|
||||
exempt=yes
|
||||
reason="authored by the '$AUTHOR' bot account and touches no protected path"
|
||||
elif ! printf '%s\n' "$files" | grep -qvE "$DOCS_ONLY"; then
|
||||
exempt=yes
|
||||
reason="docs-only change (no code, no protected path)"
|
||||
else
|
||||
reason="awaiting an H10 review verdict for head ${SHA:0:7}"
|
||||
fi
|
||||
|
||||
if [ "$exempt" = yes ]; then
|
||||
state=success
|
||||
desc="Exempt: $reason"
|
||||
else
|
||||
state=pending
|
||||
desc="Awaiting review verdict for ${SHA:0:7}"
|
||||
fi
|
||||
echo "Decision: state=${state} — ${reason}"
|
||||
|
||||
payload=$(jq -n --arg s "$state" --arg c "$CONTEXT" --arg d "$desc" --arg u "$PR_URL" \
|
||||
'{state:$s, context:$c, description:$d, target_url:$u}')
|
||||
gh -X POST -H 'Content-Type: application/json' -d "$payload" \
|
||||
"$BASE_URL/repos/$REPO/statuses/$SHA" >/dev/null
|
||||
echo "Posted ${CONTEXT}=${state} on ${SHA:0:7}."
|
||||
|
||||
if [ "$state" = "pending" ]; then
|
||||
echo "::notice::This PR needs an H10 review verdict for head ${SHA:0:7} before it can merge. After reviewing, run: scripts/post-review-verdict.sh ${PR} MERGEABLE"
|
||||
fi
|
||||
@@ -52,7 +52,7 @@ docker build -f docker/Dockerfile -t ersatztv:dev .
|
||||
- Test with **NUnit** + Shouldly + NSubstitute (the existing `*.Tests` projects); xUnit is **not** used here
|
||||
- **Dependencies use Central Package Management**: versions live in the repo-root `Directory.Packages.props`; csproj reference packages by name only. Add/upgrade by editing the central `<PackageVersion>` — never put `Version=` back on a `<PackageReference>` (trips `NU1008`). See `docs/ci-cd.md` → Dependency management.
|
||||
- **DB migrations target BOTH providers**: a `TvContext` model change needs a migration in `ErsatzTV.Infrastructure.Sqlite` **and** `ErsatzTV.Infrastructure.MySql` — run `scripts/add-migration.sh <Name>` (does both). CI's `migrations` job enforces model-drift + apply-to-fresh-DB per provider. See `docs/ci-cd.md` → Migration integrity.
|
||||
- **Renovate** is live (`.gitea/workflows/renovate.yml`, weekly + `workflow_dispatch`): opens dependency-update + OSV vuln-fix PRs and a Dependency Dashboard issue; patch bumps to test/dev-only packages auto-merge once `Build & test` passes, the rest are manual. Cross-repo rollout: server-management#484. See `docs/ci-cd.md` → Dependency management.
|
||||
- **Renovate** is live (`.gitea/workflows/renovate.yml`, weekly + `workflow_dispatch`): opens dependency-update + OSV vuln-fix PRs and a Dependency Dashboard issue; patch bumps to test/dev-only packages auto-merge once `Build & test` passes (their `review-verdict/h10` required check is auto-passed as a bot PR — unless they touch `.claude/`/`.gitea/`/`.husky/`/`scripts/`/`docker/ci/`, which need a real verdict), the rest are manual. Cross-repo rollout: server-management#484. See `docs/ci-cd.md` → Dependency management.
|
||||
- **Versioning**: release tags are `vYY.<release-seq>.<patch>` (year · sequential release-within-year · patch) — inherited from upstream, **not** year.month. `v26.3.1` = our infra rebuild of upstream 26.3.0 (no app changes); `v26.4.0` is reserved for the first release with app changes. Never `[skip ci]` a commit you'll tag (it suppresses the release build). Full policy: `docs/ci-cd.md` → Versioning & releases.
|
||||
- Backlog tracked via [Gitea Issues](http://192.168.1.95:3000/timothy/ersatztv/issues)
|
||||
|
||||
@@ -61,7 +61,8 @@ docker build -f docker/Dockerfile -t ersatztv:dev .
|
||||
Every task that closes a Gitea issue MUST complete ALL of these before it is considered done. Use `/done <issue>` to run through this automatically.
|
||||
|
||||
**Merge-consent is derived from state, not asserted (`## Done-when` convention — ersatztv#303 H6 + H10).** Any issue whose PR will merge to `main` should carry a `## Done-when` section in its **issue body** — a checklist of completion criteria (always include an "adversarial review passed" box; add per-issue criteria like tests-green, docs-updated, live-E2E). Two hooks derive merge-consent from it so a premature merge is blocked *by construction*, not by memory:
|
||||
- `pretooluse-merge-consent.sh` (Claude PreToolUse on the Gitea merge tool) — **auto-grants** a merge (emits `permissionDecision: allow`, so **no** redundant mechanical prompt fires) only when the PR's CI is green **and** every `## Done-when` box on the linked issue (`fixes #N`) is ticked **and** a `Review-verdict:` comment references the PR's *current head sha* (**H10**); **denies** on an unticked box, red CI, or a stale/negative review verdict; **asks** (falls back to a human prompt) when it can't derive state (no linked issue, no `## Done-when` section, no `Review-verdict:` comment yet, no creds, Gitea down). On the auto-grant (satisfied) path the derived state **is** the consent — do not also ask conversationally to merge; a separate human confirmation is warranted only when the gate **asks** (ersatztv#314). **The H10 review-verdict convention**: after an adversarial/Codex review of a PR (or its latest fix commit), post a PR comment with a line `Review-verdict: <MERGEABLE|APPROVED|BLOCKED> @ <head-sha>` — this proves the *latest* commit was reviewed, not a stale earlier diff (ersatztv#242).
|
||||
- `pretooluse-merge-consent.sh` (Claude PreToolUse on the Gitea merge tool) — **auto-grants** a merge (emits `permissionDecision: allow`, so **no** redundant mechanical prompt fires) only when the PR's CI is green **and** every `## Done-when` box on the linked issue (`fixes #N`) is ticked **and** a `Review-verdict:` comment references the PR's *current head sha* (**H10**); **denies** on an unticked box, red CI, or a stale/negative review verdict; **asks** (falls back to a human prompt) when it can't derive state (no linked issue, no `## Done-when` section, no `Review-verdict:` comment yet, no creds, Gitea down). On the auto-grant (satisfied) path the derived state **is** the consent — do not also ask conversationally to merge; a separate human confirmation is warranted only when the gate **asks** (ersatztv#314). **The H10 review-verdict convention**: after an adversarial/Codex review of a PR (or its latest fix commit), run **`scripts/post-review-verdict.sh <pr> <MERGEABLE|APPROVED|BLOCKED|NOT-MERGEABLE> [note]`** — it posts both the `Review-verdict: … @ <head-sha>` comment and the sha-bound `review-verdict/h10` commit status, proving the *latest* commit was reviewed rather than a stale earlier diff (ersatztv#242). Do not hand-write the comment: the **status** is the required check branch protection enforces, and a comment alone leaves it absent.
|
||||
- **The gate is enforced server-side, per sha (ersatztv#622).** `review-verdict/h10` is a required status check on `main`. Because a commit status belongs to one sha, a commit pushed *after* an auto-merge is scheduled clears it and blocks the merge — closing the hole where `merge_when_checks_succeed` froze consent at scheduling time and Gitea later merged an unreviewed head. Renovate-authored and docs-only PRs are auto-passed by `.gitea/workflows/review-verdict.yml`, **except** when they touch `.claude/`, `.gitea/`, `.husky/`, `scripts/` or `docker/ci/`. See `docs/ci-cd.md` → Review-verdict gate.
|
||||
- `.husky/pre-push` → `prepush-donewhen.sh` — a fail-open backstop that blocks a direct `git push origin main` whose commits `fix #N` an issue with unticked boxes.
|
||||
|
||||
Both need Gitea read creds in the env to enforce (**`ETV_GITEA_BASICAUTH=user:pass`** or `ETV_GITEA_TOKEN`; `ETV_GITEA_URL` overrides the base). Without them the merge hook asks and the push backstop is a no-op — the gate degrades to today's manual confirmation, never a silent pass. Docs-only PRs/pushes are exempt.
|
||||
|
||||
+59
-4
@@ -620,10 +620,65 @@ grep of `docker-build.yml` still validates the five pin-bearing jobs
|
||||
(`test`/`migrations`/`functional-e2e`/`api-docs`/`format`) that remain there. `api-docs` and
|
||||
`format` stay in `docker-build.yml` because they carry the shared-image `container:` + pin and run
|
||||
on the healthy `ubuntu-latest` lane (where they skipped correctly). None of the three moved jobs is
|
||||
a **required** check — branch protection requires only `Build & test (.NET)` and `EF migration
|
||||
integrity` — so relocating them (their status-context prefix changes from `Build ErsatzTV Image /
|
||||
…` to `PR Gates / …`) does not affect merges. The file declares `defaults: run: shell: bash`
|
||||
because `ci-image-pin` uses `mapfile`/`set -o pipefail`.
|
||||
a **required** check — branch protection requires `Build & test (.NET)`, `EF migration integrity`
|
||||
and `review-verdict/h10` (next section) — so relocating them (their status-context prefix changes
|
||||
from `Build ErsatzTV Image / …` to `PR Gates / …`) does not affect merges. The file declares
|
||||
`defaults: run: shell: bash` because `ci-image-pin` uses `mapfile`/`set -o pipefail`.
|
||||
|
||||
## Review-verdict gate (`review-verdict/h10`, required — `.gitea/workflows/review-verdict.yml`)
|
||||
|
||||
**A required status check named `review-verdict/h10`, written per-sha, is what actually stops an
|
||||
unreviewed commit from merging** (ersatztv#622). It is not produced by a job's success/failure; it
|
||||
is a commit status that `scripts/post-review-verdict.sh` POSTs onto one specific sha.
|
||||
|
||||
**The hole it closes.** `pretooluse-merge-consent.sh` proves its three consent conditions at the
|
||||
moment the merge tool is called. Pass `merge_when_checks_succeed=true` and Gitea performs the merge
|
||||
*later*, against whatever head is green then — while the Done-when and review-verdict checks were
|
||||
proven against the head at **scheduling** time. Every commit pushed in between merges unreviewed.
|
||||
|
||||
This was demonstrated as a controlled A/B rather than inferred (`ci/fake` stands in for a slow CI
|
||||
check so Gitea waits, as it really does): review head A → post its verdict → schedule auto-merge →
|
||||
push an unreviewed commit B → CI greens on B. **Without** the required verdict context, B merged.
|
||||
**With** it, the same sequence was refused, and merged only once B itself was reviewed.
|
||||
|
||||
Note the motivating anecdote in ersatztv#622 — "PR #619 merged 263 insertions with no verdict" —
|
||||
is **wrong**: #619 does carry `Review-verdict: MERGEABLE @ 02c82b35`, posted six seconds before the
|
||||
merge, explicitly re-reviewing the follow-up commits. It was filed from an API read that lagged.
|
||||
The gap is real anyway, and structural: nothing *forced* that re-review inside the 45-minute window
|
||||
where Gitea would have merged whatever went green. This turns diligence into construction.
|
||||
|
||||
**Why a commit status fixes it and a smarter hook cannot.** A status belongs to exactly one sha, so
|
||||
a new commit *cannot inherit it*: the required context is simply absent on the new head, Gitea's
|
||||
merge-requirement check reads that as not-passing, and the scheduled auto-merge refuses to fire.
|
||||
The invariant self-invalidates — nothing has to notice the push. It also covers merge paths the
|
||||
hook never sees (Gitea UI, raw API, another agent's session).
|
||||
|
||||
**Posting a verdict.** After reviewing a PR's *current* head:
|
||||
|
||||
```bash
|
||||
ETV_GITEA_BASICAUTH=user:pass scripts/post-review-verdict.sh <pr> MERGEABLE [note...]
|
||||
```
|
||||
|
||||
That posts both the `Review-verdict: … @ <sha>` comment (the human-readable artifact, and the
|
||||
hook's condition (c)) and the `review-verdict/h10` status on the same sha. `BLOCKED` /
|
||||
`NOT-MERGEABLE` post a `failure` status instead. The script re-reads the head after commenting: if
|
||||
a commit landed mid-flight it writes **no** status and exits non-zero rather than retargeting your
|
||||
verdict at a commit you never read.
|
||||
|
||||
**Exemptions** are handled by `review-verdict.yml` on every `pull_request` event, which posts the
|
||||
status as `success` for **Renovate-authored** PRs (it uses `platformAutomerge: true`, so a required
|
||||
verdict with no exemption would stall every dependency bump) and for **docs-only** PRs, and as
|
||||
`pending` for everything else so the block has a visible reason. Both exemptions are **void when the
|
||||
PR touches `.claude/`, `.gitea/`, `.husky/`, `scripts/` or `docker/ci/`** — a PR that can weaken the
|
||||
gate must not be able to exempt itself from the gate. That includes Renovate's `docker/ci` base
|
||||
bumps, which already need the manual publish-then-pin two-step anyway.
|
||||
|
||||
It lives in its **own workflow file** on purpose: `pr-checks.yml` sets `cancel-in-progress: true`,
|
||||
and a cancelled run there would leave an exempt PR with no status and no further push to
|
||||
re-trigger it. Its own job context (`Review verdict / Set review-verdict status`) is **not** the
|
||||
required check — a workflow must not satisfy the gate merely by running successfully.
|
||||
|
||||
Full rationale: `docs/decisions/records/release/verdict-status-check.md`.
|
||||
|
||||
## CI toolchain image (`docker/ci/Dockerfile`, `.gitea/workflows/ci-image.yml`)
|
||||
|
||||
|
||||
@@ -111,6 +111,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera
|
||||
| `release.prepush-clean-worktree-guard` | A fail-open pre-push hook blocks a push when any file in the branch's diff vs `origin/main` also has uncommitted working-tree or index changes, since a stale-index commit (e.g. `git reset --soft` + `git add` over an edited-but-unstaged fix) can silently push, CI-test, and get reviewed a different tree than the one on disk. Scope is precise to pushed-diff files; escape hatch `ETV_ALLOW_DIRTY_PUSH=1`. | 2026-07-17 | [link](records/release/prepush-clean-worktree-guard.md) |
|
||||
| `release.promotion-floating-prod` | Prod tracks the floating `:prod` image reference; a tag build's immutable `:<version>` image is scanned first, then promotion happens via a separate manual `DeployStack`, with daily auto-update only as a fallback — tag with enough runway before 03:00 to avoid an unscanned promotion. | 2026-07-13 | [link](records/release/promotion-floating-prod.md) |
|
||||
| `release.review-verdict-gate` | A PR may not merge until a `Review-verdict: <MERGEABLE\|APPROVED\|BLOCKED\|NOT-MERGEABLE> @ <head-sha>` comment references the PR's current head sha (short-sha prefix match, line-start marker only, negative wins over positive on the same head); folds into the H6 merge-consent hook as condition (c). | 2026-07-12 | [link](records/release/review-verdict-gate.md) |
|
||||
| `release.verdict-status-check` | The H10 review verdict is written as a `review-verdict/h10` Gitea **commit status** on the exact reviewed sha by `scripts/post-review-verdict.sh`, and that context is a REQUIRED status check on `main`. Because a status belongs to one sha, a later commit cannot inherit it, so Gitea's own `merge_when_checks_succeed` refuses to merge a head no one reviewed. The PreToolUse hook additionally refuses to SCHEDULE an auto-merge unless that status is already green on head. A `pull_request` workflow auto-passes the two exempt classes (Renovate-authored, docs-only) unless the PR touches a protected path (`.claude/`, `.gitea/`, `.husky/`, `scripts/`, `docker/ci/`). This extends — does not supersede — `release.review-verdict-gate` (#303 H10), whose comment convention remains the human-readable artifact and the hook's condition (c). | 2026-07-25 | [link](records/release/verdict-status-check.md) |
|
||||
| `rulebuilder.relative-date-macros` | The visual rule builder's `inLast`/`notInLast` date operators compile to/parse from the pre-existing `CustomMultiFieldQueryParser` macros `released_inthelast`/`released_notinthelast` and `added_inthelast`/`added_notinthelast`, value form `"<n> day\|week\|month\|year"`; there is no backend change. | 2026-07-23 | [link](records/rulebuilder/relative-date-macros.md) |
|
||||
| `scan.collections-scan-status` | `GET /api/v1/media-sources/collections-scan-status` reports a family-global (not per-source), boolean-only active-scan set read from `IEntityLocker`; the SPA reconciles authoritatively against it (with a grace-tick helper) instead of a fixed client-side timeout. | 2026-07-12 | [link](records/scan/collections-scan-status.md) |
|
||||
| `scan.getoraddfolder-db-lookup` | `ILibraryRepository.GetOrAddFolder` resolves the existing folder via a DB query on `(LibraryPathId, Path)`, not the caller's `LibraryPath.LibraryFolders` in-memory navigation, since that navigation is only eager-loaded on the local scan path and is null on remote (Jellyfin) callers. | 2026-07-20 | [link](records/scan/getoraddfolder-db-lookup.md) |
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
---
|
||||
key: release.verdict-status-check
|
||||
title: '2026-07-25 — H10 is enforced server-side as a per-sha required status check, not only by the PreToolUse hook (#622)'
|
||||
status: active
|
||||
since: '2026-07-25'
|
||||
supersedes: none
|
||||
superseded-by: none
|
||||
rule: 'The H10 review verdict is written as a `review-verdict/h10` Gitea **commit status** on the exact reviewed sha by `scripts/post-review-verdict.sh`, and that context is a REQUIRED status check on `main`. Because a status belongs to one sha, a later commit cannot inherit it, so Gitea''s own `merge_when_checks_succeed` refuses to merge a head no one reviewed. The PreToolUse hook additionally refuses to SCHEDULE an auto-merge unless that status is already green on head. A `pull_request` workflow auto-passes the two exempt classes (Renovate-authored, docs-only) unless the PR touches a protected path (`.claude/`, `.gitea/`, `.husky/`, `scripts/`, `docker/ci/`). This extends — does not supersede — `release.review-verdict-gate` (#303 H10), whose comment convention remains the human-readable artifact and the hook''s condition (c).'
|
||||
signals: 'merge_when_checks_succeed freezes consent, auto-merge merges an unreviewed head, verdict bound to sha, review-verdict/h10 required check, post-review-verdict.sh, Renovate platformAutomerge exemption · paths: `scripts/post-review-verdict.sh`, `.gitea/workflows/review-verdict.yml`, `.claude/hooks/pretooluse-merge-consent.sh` · issues: #622, #303 (H6/H10), #242, #619'
|
||||
mechanics: '`scripts/tests/test_post_review_verdict.py` (incl. a TOCTOU head-moved case and cross-checks against the hook''s own condition-(c) regexes); branch protection `status_check_contexts` on `main`'
|
||||
---
|
||||
|
||||
`pretooluse-merge-consent.sh` evaluates all three consent conditions **at the moment the merge tool is
|
||||
called**. That is sound for an immediate merge and unsound for a scheduled one. When the call passes
|
||||
`merge_when_checks_succeed=true`, condition (a) is deliberately delegated to Gitea — but Gitea then
|
||||
merges whatever head is green at *its* merge time, while (b) Done-when and (c) the head-referencing
|
||||
verdict were proven against the head that existed at **scheduling** time. Any commit pushed in between
|
||||
merges with no verdict covering it. The gate is not bypassed; it is **satisfied against a snapshot that
|
||||
stops being true**.
|
||||
|
||||
This is the same shape as the failure H10 was created to fix (#242, "re-review the fix commit, not just
|
||||
the initial diff"), reintroduced through the scheduling path rather than through forgetfulness. It also
|
||||
interacted badly with a convention we actively encouraged: append-only files hit the conflict treadmill,
|
||||
and the documented remedy was "rebase, then schedule `merge_when_checks_succeed`" — steering exactly the
|
||||
high-churn PRs, the ones most likely to grow follow-up commits, onto the one path where H10 stopped
|
||||
applying.
|
||||
|
||||
**Correction on the motivating anecdote.** #622 was filed claiming PR #619 merged 263 insertions with no
|
||||
covering verdict. That is **false**, and the record is corrected here rather than repeated: #619 carries a
|
||||
*second* verdict comment, `Review-verdict: MERGEABLE @ 02c82b35`, posted at 20:36:02 — six seconds before
|
||||
the 20:36:08 merge — which explicitly re-reviewed the two follow-up commits ("the verdict on record was
|
||||
stale … so they got their own scoped review"). The original claim came from reading the comment list while
|
||||
the Gitea API lagged. So the incident is evidence of the convention *working under diligence*, not of it
|
||||
failing.
|
||||
|
||||
The hole is nevertheless real, and is structural rather than anecdotal: **nothing forced that re-review**.
|
||||
It happened because a human chose to, inside a 45-minute window in which Gitea would have merged whatever
|
||||
was green. That is exactly the distinction this record exists to close — turning a property that held by
|
||||
diligence into one that holds by construction. The justification below therefore rests on a controlled
|
||||
experiment, not on the anecdote (`ci/fake` stands in for a slow CI check, so Gitea waits, as it really
|
||||
does):
|
||||
|
||||
| arm | required contexts | unreviewed commit pushed after scheduling |
|
||||
| --- | --- | --- |
|
||||
| without this change | `ci/fake` | **merged** |
|
||||
| with this change | `ci/fake`, `review-verdict/h10` | **refused** |
|
||||
| then review the new head and post its verdict | | merges — blocked, not deadlocked |
|
||||
|
||||
The negative-control arm is what makes this meaningful: the fix *changes the outcome*, rather than the
|
||||
observation passing for an unrelated reason.
|
||||
|
||||
**The fix is the sha, not a smarter check.** A Gitea commit status is attached to exactly one commit, so
|
||||
a status written for a parent cannot be inherited by a child that did not exist yet. Making
|
||||
`review-verdict/h10` a required status check on `main` therefore makes the invariant self-invalidating
|
||||
by construction: push a new head and the required context is simply absent, which Gitea's
|
||||
merge-requirement check treats as not-passing, and the scheduled auto-merge refuses to fire until that
|
||||
head is re-reviewed. No re-evaluation hook, no polling, no second snapshot to go stale. Three properties
|
||||
follow that no hook-side fix could deliver:
|
||||
|
||||
- it covers **every** merge path — Gitea UI, raw API, auto-merge, another agent's session — not only
|
||||
calls that happen to route through the Claude PreToolUse hook;
|
||||
- it needs no event to re-fire, because absence-of-status *is* the block;
|
||||
- it cannot be satisfied by a workflow merely running successfully, since the required context is the
|
||||
status the workflow *posts*, never the workflow's own job status.
|
||||
|
||||
The comment convention of `release.review-verdict-gate` is unchanged and still load-bearing: it is what a
|
||||
human reads, and it remains the hook's condition (c). `post-review-verdict.sh` writes both from one
|
||||
command so they cannot drift, and re-reads the head after posting the comment — if a commit landed in
|
||||
between it writes **no** status and exits non-zero rather than retargeting the verdict at a commit nobody
|
||||
reviewed (#622 in miniature). Where the two ever disagree, the status wins, because it is the one a merge
|
||||
is actually gated on.
|
||||
|
||||
**Exemptions, and why they are narrow.** A required check applies to every PR, including Renovate's,
|
||||
which uses `platformAutomerge: true` — Gitea's own auto-merge — to land patch bumps unattended. So
|
||||
`.gitea/workflows/review-verdict.yml` posts the status as `success` for Renovate-authored PRs and for
|
||||
docs-only PRs, and `pending` for everything else (an explicit blocking reason beats a silently-missing
|
||||
check). Both exemptions are void when the PR touches a **protected path** — `.claude/`, `.gitea/`,
|
||||
`.husky/`, `scripts/`, `docker/ci/` — because a PR that weakens the merge gate must never be able to
|
||||
exempt itself from the merge gate. This deliberately also means Renovate's `docker/ci/Dockerfile` base
|
||||
bumps need a real verdict; those already require the manual publish-then-pin two-step
|
||||
(`docs/ci-cd.md` → "CI toolchain image"), so unattended merge was never correct for them.
|
||||
|
||||
Two deliberate non-choices. The workflow lives in **its own file** rather than joining `pr-checks.yml`,
|
||||
whose `cancel-in-progress: true` would let a superseding push cancel the run that grants an exemption,
|
||||
stranding a Renovate PR with no status and no further push to re-trigger it. And the workflow's
|
||||
docs-only pattern is **narrower** than the merge-consent hook's: the hook also lets `.claude/`/`.gitea/`/
|
||||
`.husky/` through, which is safe there only because that path falls through to a human prompt, whereas
|
||||
here it would post a green status with nobody in the loop.
|
||||
|
||||
Option (2) from #622 — "refuse to schedule when the branch can still move" — was rejected as close to a
|
||||
no-op on its own, since it cannot stop a later push. It survives only as the hook-side precondition
|
||||
described above, which is now meaningful precisely *because* the server-side status exists to check.
|
||||
|
||||
**Known limits, stated rather than papered over.** This raises the floor against *accident*, which is the
|
||||
failure mode we actually have; it is not a control against a determined author of a PR, and should not be
|
||||
described as one:
|
||||
|
||||
1. **A rename hides a path unless both sides are read.** Gitea reports a `git mv` as ONE row whose
|
||||
`filename` is the destination, with the source only in `previous_filename` — so reading `filename`
|
||||
alone lets a PR move a protected file into `docs/` and look docs-only. Verified live
|
||||
(`.gitea/workflows/renovate.yml` → `docs/innocuous-note.md` showed no protected path). Both the
|
||||
workflow and the hook now read **both** sides. Noting the near-miss: an initial check against #619
|
||||
suggested Gitea exposed no rename data at all, which was a false negative — that PR simply contained
|
||||
no renames. A constructed positive case settled it; an arbitrary sample did not.
|
||||
2. **The file list must be paged, and the paging must fail closed.** The endpoint caps at 50 rows and
|
||||
silently ignores a larger `limit` (PR #619: 194 changed files, `?limit=100` returns 50). A
|
||||
single-page read is a silent false negative — on #619 it saw **zero** protected paths where the full
|
||||
enumeration finds ten. Both call sites now page to exhaustion. Critically, each page is validated
|
||||
*before* its rows are counted, and validated **per row**, not just at the top level: every row must
|
||||
carry a non-empty string `filename`. An errored page, a non-array body, an array of scalars, and an
|
||||
array of `filename`-less objects all yield zero usable paths, and any of them would otherwise read as
|
||||
"end of list" and complete the enumeration from a **partial** list — failing open at precisely the
|
||||
point the guard exists to fail closed. An empty array stays valid, because that is what a genuine
|
||||
end-of-pagination looks like.
|
||||
|
||||
Rename rows carry one extra requirement: a row whose `status` is `renamed` must also carry a
|
||||
non-empty `previous_filename`, or the row validates while its SOURCE silently vanishes — which is
|
||||
exactly the path-hiding that collecting both sides exists to prevent. It is required *only* for
|
||||
rename rows; demanding it globally would reject every ordinary modified/added row and make the gate
|
||||
refuse all exemptions, a failure the "withholds the exemption" tests could not distinguish from
|
||||
working, so there is a positive control for that too.
|
||||
|
||||
This whole class lives only on the *failure* path, so every happy-path run looked correct and the
|
||||
first test suite was green throughout. It took two rounds to close: the first fix validated only the
|
||||
top-level type, which left `[{}]` as a working bypass. The tests therefore error and malform pages
|
||||
mid-pagination rather than only returning data, and include positive controls (an empty final page
|
||||
must still exempt; an ordinary row without `previous_filename` must still be valid) so that an
|
||||
over-strict guard — which would make every "withholds the exemption" test pass for the wrong
|
||||
reason — is also caught.
|
||||
|
||||
**Where this hardening stops.** Three review rounds closed: single-page truncation, renames,
|
||||
failure-path pages, top-level-only validation, and malformed rename rows. Real Gitea populates
|
||||
`previous_filename` on renames and returns well-formed pages; everything past this point defends
|
||||
against response shapes with no evidence of existing. The guard's contract is now "any page we
|
||||
cannot fully classify withholds the exemption", and it is worth keeping that claim narrow and true
|
||||
rather than extending it to shapes nobody has observed.
|
||||
|
||||
2b. **Status reads use the combined endpoint.** `GET /statuses/{sha}` returns one row per status *post*
|
||||
(not per context) and pages at 50, so a head with a few CI reruns can push an earlier verdict off the
|
||||
first page. In the hook that would be a confusing false deny; in the workflow it would be worse — it
|
||||
would post `pending` (or an exemption `success`) **over** a real human verdict. Both now read
|
||||
`GET /commits/{sha}/status`, which returns latest-per-context, and the workflow refuses to post
|
||||
anything at all when that read fails or is unparseable, rather than treating it as "no verdict yet".
|
||||
3. **Changing a PR's base does not change its head sha**, so a verdict status keeps applying to a diff
|
||||
that has materially changed. Not currently handled; low exposure here because base changes are rare
|
||||
and manual.
|
||||
4. **A PR that edits `review-verdict.yml` is judged by its own edited copy.** Gitea runs
|
||||
`pull_request` workflows from the PR **head**, not the base — confirmed on the very PR that
|
||||
introduced this workflow (#630): `review-verdict.yml` does not exist on `main`, yet its job ran
|
||||
and posted a status. So `PROTECTED` is a guardrail against *accidental* self-exemption, **not** a
|
||||
tamper-proof control: a PR that rewrote the workflow would be classified by the rewritten rules.
|
||||
Acceptable for a two-account repo (`timothy`, `renovate`) where the threat is a careless change
|
||||
rather than a hostile one; it would not be for an untrusted-contributor repo, which would need
|
||||
the classification moved somewhere the PR cannot edit (a base-branch-pinned workflow, or
|
||||
server-side policy).
|
||||
|
||||
The same head-execution behaviour is what makes the rollout self-hosting in the good case: #630's
|
||||
own run correctly identified it as touching `.claude/` and `scripts/`, refused both exemptions,
|
||||
and posted `review-verdict/h10=pending` with an actionable description.
|
||||
@@ -296,6 +296,11 @@ HARD CONSTRAINTS:
|
||||
- **Merge consent is DERIVED, not asked.** The H6/H10 gate auto-grants when the `## Done-when` boxes are
|
||||
ticked, a fresh `Review-verdict` references the current head, and CI is green; confirm in conversation
|
||||
only when the gate ASKS. Prior pre-approvals never carry over. → `release.merge-consent-autogrant`
|
||||
- **Post every review verdict with `scripts/post-review-verdict.sh <pr> <VERDICT>`** — never hand-write the
|
||||
comment. It also writes the `review-verdict/h10` commit status, which is the REQUIRED check that actually
|
||||
gates the merge; a comment alone leaves it absent. Being sha-bound is the point: a commit pushed after an
|
||||
auto-merge is scheduled clears it, so scheduled merges can no longer land unreviewed code.
|
||||
→ `release.verdict-status-check`
|
||||
- **After the push, fixes are follow-up commits** — never amend or force-push a pushed branch.
|
||||
→ `process.pr-routine-sequence`
|
||||
|
||||
|
||||
Executable
+128
@@ -0,0 +1,128 @@
|
||||
#!/usr/bin/env bash
|
||||
# post-review-verdict.sh — post an H10 review verdict as BOTH a PR comment and a per-sha commit
|
||||
# status, so merge consent is bound to the exact commit that was reviewed (ersatztv#622).
|
||||
#
|
||||
# WHY THIS EXISTS. `pretooluse-merge-consent.sh` evaluates all three consent conditions at the
|
||||
# moment the merge tool is called. When that call passes `merge_when_checks_succeed=true`, condition
|
||||
# (a) is deliberately delegated to Gitea — but Gitea then merges whatever head is green at ITS merge
|
||||
# time, which may be several commits past the head that conditions (b) and (c) were proven against.
|
||||
# The gate reports satisfied and the newest code merges with no review verdict covering it. That is
|
||||
# not a bypass: the gate is *satisfied against a snapshot that stops being true* (ersatztv#622).
|
||||
# Shown by a controlled A/B: with a slow CI check still pending so Gitea waits, a commit pushed after
|
||||
# scheduling MERGED unreviewed without the required verdict context, and was REFUSED with it.
|
||||
#
|
||||
# THE FIX IS THE SHA, NOT THE SCRIPT. A Gitea commit status is attached to ONE sha. Making
|
||||
# `review-verdict/h10` a REQUIRED status check on `main` therefore makes the H10 invariant
|
||||
# self-invalidating by construction: push a new commit and the new head simply has no such status,
|
||||
# so Gitea's own auto-merge refuses to fire until someone re-reviews THAT head and posts a fresh
|
||||
# verdict. No re-evaluation hook, no polling, no snapshot to go stale — a status cannot be inherited
|
||||
# by a commit that did not exist when it was written. This closes the hole for every merge path
|
||||
# (Gitea UI, API, auto-merge, another agent's session), not just the one that goes through the
|
||||
# Claude PreToolUse hook.
|
||||
#
|
||||
# The comment is still posted because it is the human-readable artifact and the hook's condition (c)
|
||||
# parser reads it; the status is what the SERVER enforces. Both name the same sha on purpose — if
|
||||
# they ever disagree, the status wins, because it is the one a merge is actually gated on.
|
||||
#
|
||||
# Usage:
|
||||
# scripts/post-review-verdict.sh <pr-number> <verdict> [note ...]
|
||||
#
|
||||
# <verdict> MERGEABLE | APPROVED | LGTM -> commit status `success` (merge may proceed)
|
||||
# BLOCKED | NOT-MERGEABLE -> commit status `failure` (merge stays blocked)
|
||||
# [note] optional free text appended to the comment under the verdict line.
|
||||
#
|
||||
# Env: ETV_GITEA_TOKEN (token) or ETV_GITEA_BASICAUTH (user:pass) — required.
|
||||
# ETV_GITEA_URL overrides the base (default: the LAN instance; a LAN address, not a secret).
|
||||
# ETV_GITEA_REPO overrides owner/repo (default: timothy/ersatztv).
|
||||
set -euo pipefail
|
||||
|
||||
STATUS_CONTEXT="review-verdict/h10"
|
||||
|
||||
die() { printf 'post-review-verdict: %s\n' "$*" >&2; exit 1; }
|
||||
|
||||
usage() {
|
||||
sed -n '/^# Usage:/,/^# ETV_GITEA_REPO/p' "$0" | sed 's/^# \{0,1\}//'
|
||||
exit 2
|
||||
}
|
||||
|
||||
[ $# -ge 2 ] || usage
|
||||
pr="$1"; verdict_raw="$2"; shift 2
|
||||
note="$*"
|
||||
|
||||
printf '%s' "$pr" | grep -qE '^[0-9]+$' || die "pull-request number must be numeric, got '$pr'"
|
||||
|
||||
# Normalize to upper-case and classify. The positive set MUST stay in sync with the hook's
|
||||
# condition-(c) regex in .claude/hooks/pretooluse-merge-consent.sh (mergeable|approved|lgtm) —
|
||||
# a word this script treats as positive but the hook does not would let the server-side status go
|
||||
# green while the hook still denies, which reads as an unexplained deny.
|
||||
verdict=$(printf '%s' "$verdict_raw" | tr '[:lower:]' '[:upper:]')
|
||||
case "$verdict" in
|
||||
MERGEABLE|APPROVED|LGTM) state="success" ;;
|
||||
BLOCKED|NOT-MERGEABLE) state="failure" ;;
|
||||
*) die "unknown verdict '$verdict_raw' — use MERGEABLE, APPROVED, LGTM, BLOCKED or NOT-MERGEABLE" ;;
|
||||
esac
|
||||
|
||||
base_url="${ETV_GITEA_URL:-http://192.168.1.95:3000}/api/v1"
|
||||
repo_slug="${ETV_GITEA_REPO:-timothy/ersatztv}"
|
||||
owner="${repo_slug%%/*}"
|
||||
repo="${repo_slug##*/}"
|
||||
[ -n "$owner" ] && [ -n "$repo" ] && [ "$owner" != "$repo_slug" ] \
|
||||
|| die "ETV_GITEA_REPO must be owner/repo, got '$repo_slug'"
|
||||
|
||||
if [ -n "${ETV_GITEA_TOKEN:-}" ]; then
|
||||
auth=(-H "Authorization: token $ETV_GITEA_TOKEN")
|
||||
elif [ -n "${ETV_GITEA_BASICAUTH:-}" ]; then
|
||||
auth=(-u "$ETV_GITEA_BASICAUTH")
|
||||
else
|
||||
die "no Gitea credentials in env — set ETV_GITEA_TOKEN or ETV_GITEA_BASICAUTH"
|
||||
fi
|
||||
|
||||
api_get() { curl -sf "${auth[@]}" "$base_url/$1"; }
|
||||
api_post() { curl -sf "${auth[@]}" -X POST -H 'Content-Type: application/json' -d "$2" "$base_url/$1"; }
|
||||
|
||||
# --- Resolve the head sha from the SERVER, never from a local checkout. -------------------------
|
||||
# A local `git rev-parse HEAD` can be ahead of (unpushed work) or behind (stale fetch) what the PR
|
||||
# actually points at, and the status must land on the sha Gitea will merge.
|
||||
prjson=$(api_get "repos/$owner/$repo/pulls/$pr") \
|
||||
|| die "could not fetch PR #$pr from $base_url (unreachable, missing, or auth rejected)"
|
||||
sha=$(printf '%s' "$prjson" | jq -r '.head.sha // ""')
|
||||
pr_state=$(printf '%s' "$prjson" | jq -r '.state // ""')
|
||||
pr_url=$(printf '%s' "$prjson" | jq -r '.html_url // ""')
|
||||
[ -n "$sha" ] || die "PR #$pr has no resolvable head sha"
|
||||
[ "$pr_state" = "open" ] || die "PR #$pr is '$pr_state', not open — refusing to post a verdict"
|
||||
short=${sha:0:7}
|
||||
|
||||
# --- The comment (human-readable artifact + the hook's condition-(c) input). --------------------
|
||||
# The verdict line MUST start the line: the hook anchors its parser to line-start precisely so a
|
||||
# comment that merely QUOTES the template mid-sentence cannot self-approve a merge.
|
||||
body="Review-verdict: $verdict @ $short"
|
||||
[ -n "$note" ] && body="$body"$'\n\n'"$note"
|
||||
comment_payload=$(jq -n --arg b "$body" '{body:$b}')
|
||||
api_post "repos/$owner/$repo/issues/$pr/comments" "$comment_payload" >/dev/null \
|
||||
|| die "failed to post the verdict comment on PR #$pr"
|
||||
printf 'posted comment: Review-verdict: %s @ %s\n' "$verdict" "$short"
|
||||
|
||||
# --- TOCTOU guard: refuse to green a head that stopped being head while we were posting. --------
|
||||
# Without this, a commit pushed between the head read above and the status write below would inherit
|
||||
# a verdict written for its parent — reintroducing ersatztv#622 at a smaller time scale. We do NOT
|
||||
# retry against the new head: the new commit is genuinely unreviewed, and silently re-targeting the
|
||||
# verdict at it is exactly the failure this script exists to prevent.
|
||||
sha_now=$(api_get "repos/$owner/$repo/pulls/$pr" | jq -r '.head.sha // ""')
|
||||
if [ -n "$sha_now" ] && [ "$sha_now" != "$sha" ]; then
|
||||
die "head moved from $short to ${sha_now:0:7} while posting — that commit is UNREVIEWED, so no status was written. Re-review the new head and run this again."
|
||||
fi
|
||||
|
||||
status_payload=$(jq -n \
|
||||
--arg s "$state" --arg c "$STATUS_CONTEXT" --arg u "$pr_url" \
|
||||
--arg d "Review-verdict: $verdict @ $short" \
|
||||
'{state:$s, context:$c, description:$d, target_url:$u}')
|
||||
api_post "repos/$owner/$repo/statuses/$sha" "$status_payload" >/dev/null \
|
||||
|| die "failed to post the '$STATUS_CONTEXT' commit status on $short"
|
||||
printf 'posted status: %s = %s on %s\n' "$STATUS_CONTEXT" "$state" "$short"
|
||||
|
||||
if [ "$state" = "failure" ]; then
|
||||
printf '\nPR #%s stays BLOCKED: %s is failing on head %s.\n' "$pr" "$STATUS_CONTEXT" "$short"
|
||||
else
|
||||
printf '\nPR #%s may merge on this head. Any NEW commit clears this status by construction —\n' "$pr"
|
||||
printf 'a fresh review + verdict is required for each head (ersatztv#622).\n'
|
||||
fi
|
||||
@@ -0,0 +1,232 @@
|
||||
"""Tests for the docs-only exemption path in `.claude/hooks/pretooluse-merge-consent.sh` (#622).
|
||||
|
||||
This covers the *file-enumeration* half of the gate, which decides whether a PR skips the
|
||||
Done-when/verdict checks entirely. Three defects lived here, all silent false negatives that
|
||||
widened the exemption rather than narrowing it:
|
||||
|
||||
1. the list was read from a single `?limit=100` page, which Gitea caps at 50 — on PR #619 that
|
||||
showed zero protected paths where the full enumeration finds ten;
|
||||
2. only `.filename` was read, so a `git mv` of a protected file INTO `docs/` looked docs-only;
|
||||
3. a mid-pagination transport failure produced an empty page, which counted as zero rows and
|
||||
read as "end of list" — completing the enumeration from a PARTIAL list.
|
||||
|
||||
(3) is the one worth restating: it is a defect on the FAILURE path, so every happy-path run looked
|
||||
correct. These tests therefore assert what happens when a page *errors*, not only when it returns.
|
||||
|
||||
Observable contract: the hook exits 0 with EMPTY stdout when the PR is exempt (it passes through to
|
||||
normal permissioning), and emits a JSON `permissionDecision` when it is not. So "did the exemption
|
||||
apply" is directly observable without stubbing the rest of the gate.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[2]
|
||||
HOOK = REPO_ROOT / ".claude" / "hooks" / "pretooluse-merge-consent.sh"
|
||||
|
||||
SHA = "a9e3e23abf337980ca4c05854f5b1e210099d08b"
|
||||
|
||||
# Serves paged `pulls/N/files`, plus the minimal PR object the hook reads first.
|
||||
CURL_SHIM = r'''#!/usr/bin/env python3
|
||||
import json, os, sys, pathlib, urllib.parse
|
||||
|
||||
state = pathlib.Path(os.environ["STUB_DIR"])
|
||||
args = sys.argv[1:]
|
||||
url = [a for a in args if a.startswith("http")][-1]
|
||||
|
||||
if "/pulls/" in url and "/files" in url:
|
||||
q = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)
|
||||
page = int(q.get("page", ["1"])[0])
|
||||
pages = json.loads((state / "pages.json").read_text())
|
||||
if page > len(pages):
|
||||
print("[]"); sys.exit(0)
|
||||
entry = pages[page - 1]
|
||||
if entry == "ERROR": # transport failure on this page
|
||||
sys.exit(22)
|
||||
if entry == "GARBAGE": # 200 with a non-array body (proxy/error page)
|
||||
print('{"message":"internal error"}'); sys.exit(0)
|
||||
# anything else is served verbatim as the page body (rows, [], malformed rows, scalars)
|
||||
print(json.dumps(entry)); sys.exit(0)
|
||||
|
||||
if "/pulls/" in url:
|
||||
print(json.dumps({"head": {"sha": os.environ["STUB_SHA"]}, "body": "no linked issue here"}))
|
||||
sys.exit(0)
|
||||
|
||||
print("{}")
|
||||
'''
|
||||
|
||||
|
||||
def _rows(paths):
|
||||
return [{"filename": p, "status": "modified"} for p in paths]
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def hook(tmp_path):
|
||||
bindir = tmp_path / "bin"; bindir.mkdir()
|
||||
shim = bindir / "curl"; shim.write_text(CURL_SHIM); shim.chmod(0o755)
|
||||
state = tmp_path / "state"; state.mkdir()
|
||||
|
||||
env = dict(os.environ)
|
||||
env["PATH"] = f"{bindir}{os.pathsep}{env['PATH']}"
|
||||
env["STUB_DIR"] = str(state)
|
||||
env["STUB_SHA"] = SHA
|
||||
env["ETV_GITEA_TOKEN"] = "stub"
|
||||
env["ETV_GITEA_URL"] = "http://gitea.example"
|
||||
env.pop("ETV_GITEA_BASICAUTH", None)
|
||||
|
||||
class Handle:
|
||||
def set_pages(self, *pages):
|
||||
(state / "pages.json").write_text(json.dumps(list(pages)))
|
||||
|
||||
def run(self):
|
||||
payload = {"tool_input": {"method": "merge", "owner": "timothy",
|
||||
"repo": "ersatztv", "pull_number": 42}}
|
||||
return subprocess.run(["bash", str(HOOK)], input=json.dumps(payload),
|
||||
env=env, capture_output=True, text=True)
|
||||
|
||||
def exempted(self):
|
||||
"""Exempt == passthrough == exit 0 with no decision JSON."""
|
||||
r = self.run()
|
||||
assert r.returncode == 0, r.stderr
|
||||
return r.stdout.strip() == ""
|
||||
|
||||
return Handle()
|
||||
|
||||
|
||||
def test_docs_only_pr_is_exempt(hook):
|
||||
hook.set_pages(_rows(["docs/a.md", "docs/b.md", "README.md"]))
|
||||
assert hook.exempted() is True
|
||||
|
||||
|
||||
def test_code_pr_is_not_exempt(hook):
|
||||
hook.set_pages(_rows(["docs/a.md", "ErsatzTV/Program.cs"]))
|
||||
assert hook.exempted() is False
|
||||
|
||||
|
||||
def test_protected_path_on_a_LATER_page_is_still_seen(hook):
|
||||
"""The #619 shape: 50 docs files on page 1, code hiding on page 2."""
|
||||
hook.set_pages(_rows([f"docs/f{i}.md" for i in range(50)]),
|
||||
_rows(["scripts/decisions_lib.py"]))
|
||||
assert hook.exempted() is False
|
||||
|
||||
|
||||
def test_full_first_page_alone_does_not_end_enumeration(hook):
|
||||
"""A full 50-row page must trigger a second fetch, not terminate the loop."""
|
||||
hook.set_pages(_rows([f"docs/f{i}.md" for i in range(50)]),
|
||||
_rows(["docs/tail.md"]))
|
||||
assert hook.exempted() is True # genuinely all docs, but only provable by reading page 2
|
||||
|
||||
|
||||
def test_rename_of_code_into_docs_is_not_exempt(hook):
|
||||
"""`git mv ErsatzTV/Program.cs docs/note.md` — the code path lives only in previous_filename.
|
||||
|
||||
NOTE the source must be a path the hook does not already exempt. Its docs-only pattern
|
||||
deliberately also covers `.claude/`/`.gitea/`/`.husky/` (process files exempt to a HUMAN
|
||||
PROMPT, never to an auto-grant), so a rename between two exempt paths is correctly still
|
||||
exempt. That is the hook's contract and differs from `review-verdict.yml`'s stricter
|
||||
PROTECTED list, which must never auto-post a green status for those paths.
|
||||
"""
|
||||
hook.set_pages([{"filename": "docs/innocuous-note.md", "status": "renamed",
|
||||
"previous_filename": "ErsatzTV/Program.cs"}])
|
||||
assert hook.exempted() is False
|
||||
|
||||
|
||||
def test_rename_between_two_exempt_paths_stays_exempt(hook):
|
||||
"""Guards the above: reading previous_filename must not over-trigger on legitimate moves."""
|
||||
hook.set_pages([{"filename": "docs/b.md", "status": "renamed",
|
||||
"previous_filename": "docs/a.md"}])
|
||||
assert hook.exempted() is True
|
||||
|
||||
|
||||
def test_transport_failure_mid_pagination_withholds_the_exemption(hook):
|
||||
"""The failure-path defect: an errored page must not read as 'end of list'."""
|
||||
hook.set_pages(_rows([f"docs/f{i}.md" for i in range(50)]), "ERROR")
|
||||
assert hook.exempted() is False
|
||||
|
||||
|
||||
def test_non_array_body_mid_pagination_withholds_the_exemption(hook):
|
||||
"""A 200 carrying an error object must not be treated as an empty final page."""
|
||||
hook.set_pages(_rows([f"docs/f{i}.md" for i in range(50)]), "GARBAGE")
|
||||
assert hook.exempted() is False
|
||||
|
||||
|
||||
def test_first_page_failure_withholds_the_exemption(hook):
|
||||
"""NOTE this one is deliberately weak on its own — see the test below.
|
||||
|
||||
With page 1 failing, the path list is empty, and the hook independently withholds the
|
||||
exemption on an empty list. So this passes even with the validation guard removed. It is
|
||||
kept as a smoke case, but it does NOT pin the guard; `test_malformed_rows_*` does.
|
||||
"""
|
||||
hook.set_pages("ERROR")
|
||||
assert hook.exempted() is False
|
||||
|
||||
|
||||
def test_malformed_rows_mid_pagination_withhold_the_exemption(hook):
|
||||
"""Isolates the row-schema hole: `[{}]` is a valid ARRAY whose rows carry no filename.
|
||||
|
||||
Validating only the top-level type lets this through — it contributes no paths, so it looks
|
||||
like a short final page and completes the enumeration from a PARTIAL list. The 50 docs rows on
|
||||
page 1 are what make this non-vacuous: the path list is non-empty, so the exemption would
|
||||
genuinely fire if `complete` were wrongly set.
|
||||
"""
|
||||
hook.set_pages(_rows([f"docs/f{i}.md" for i in range(50)]), [{}])
|
||||
assert hook.exempted() is False
|
||||
|
||||
|
||||
def test_scalar_rows_mid_pagination_withhold_the_exemption(hook):
|
||||
"""An array of scalars must be rejected, not crash the extraction under `set -e`."""
|
||||
hook.set_pages(_rows([f"docs/f{i}.md" for i in range(50)]), ["unexpected"])
|
||||
assert hook.exempted() is False
|
||||
|
||||
|
||||
def test_empty_final_page_is_a_legitimate_end_of_pagination(hook):
|
||||
"""Positive control for the guard above: `[]` must still count as a clean end, not a failure.
|
||||
|
||||
Without this, a stricter guard could withhold every exemption and the tests above would still
|
||||
pass — the suite would be asserting 'never exempt', which is not the contract.
|
||||
"""
|
||||
hook.set_pages(_rows([f"docs/f{i}.md" for i in range(50)]), [])
|
||||
assert hook.exempted() is True
|
||||
|
||||
|
||||
def test_malformed_rename_row_withholds_the_exemption(hook):
|
||||
"""A row marked `renamed` with NO `previous_filename` hides its source path.
|
||||
|
||||
The destination alone is `docs/...`, so validating only `filename` would accept the row and
|
||||
silently drop whatever it was renamed FROM — defeating the reason both sides are collected.
|
||||
Real Gitea always populates it (verified by constructing a rename), so this is the
|
||||
malformed-2xx class the guard claims to fail closed on; the claim should match the behaviour.
|
||||
"""
|
||||
hook.set_pages(_rows([f"docs/f{i}.md" for i in range(50)]),
|
||||
[{"filename": "docs/moved.md", "status": "renamed"}])
|
||||
assert hook.exempted() is False
|
||||
|
||||
|
||||
def test_rename_row_with_empty_previous_filename_withholds_the_exemption(hook):
|
||||
hook.set_pages(_rows([f"docs/f{i}.md" for i in range(50)]),
|
||||
[{"filename": "docs/moved.md", "status": "renamed", "previous_filename": ""}])
|
||||
assert hook.exempted() is False
|
||||
|
||||
|
||||
def test_ordinary_row_without_previous_filename_is_still_valid(hook):
|
||||
"""Positive control: `previous_filename` must be required ONLY for rename rows.
|
||||
|
||||
Requiring it globally would reject every normal modified/added row and make the gate refuse
|
||||
all exemptions — which the 'withholds' tests above could not distinguish from working.
|
||||
"""
|
||||
hook.set_pages([{"filename": "docs/a.md", "status": "modified"},
|
||||
{"filename": "docs/b.md", "status": "added"},
|
||||
{"filename": "docs/c.md"}])
|
||||
assert hook.exempted() is True
|
||||
|
||||
|
||||
def test_exceeding_max_pages_withholds_the_exemption(hook):
|
||||
"""41 full pages: enumeration cannot be proven exhaustive, so no exemption."""
|
||||
hook.set_pages(*[_rows([f"docs/p{p}f{i}.md" for i in range(50)]) for p in range(41)])
|
||||
assert hook.exempted() is False
|
||||
@@ -0,0 +1,254 @@
|
||||
"""Tests for `scripts/post-review-verdict.sh` (ersatztv#622).
|
||||
|
||||
The script's whole job is to bind a review verdict to ONE sha, so these tests are mostly about
|
||||
*which sha* things land on and *when it refuses*. Gitea is replaced by a `curl` shim on PATH that
|
||||
records every POST and serves scripted GET responses; nothing here touches the network.
|
||||
|
||||
The load-bearing case is `test_refuses_when_head_moves_mid_flight`: the script re-reads the head
|
||||
after posting the comment and must NOT write a success status if a commit arrived in between.
|
||||
Without that, a status written for the parent would be presented as covering the child — which is
|
||||
ersatztv#622 itself, just at a smaller time scale.
|
||||
|
||||
`test_comment_line_matches_the_hook_parser` is a cross-check rather than a unit test: it runs the
|
||||
comment body this script produces through the *same* regexes `.claude/hooks/pretooluse-merge-consent.sh`
|
||||
uses for condition (c). The two are separate implementations of one convention, and a drift between
|
||||
them would be invisible until a merge mysteriously stalled.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[2]
|
||||
SCRIPT = REPO_ROOT / "scripts" / "post-review-verdict.sh"
|
||||
HOOK = REPO_ROOT / ".claude" / "hooks" / "pretooluse-merge-consent.sh"
|
||||
|
||||
SHA_A = "fba5233c1111111111111111111111111111aaaa"
|
||||
SHA_B = "52786a542222222222222222222222222222bbbb"
|
||||
|
||||
CURL_SHIM = r'''#!/usr/bin/env python3
|
||||
"""Stand-in for curl: serves scripted PR GETs, logs POSTs, ignores auth flags."""
|
||||
import json, os, sys, pathlib
|
||||
|
||||
state = pathlib.Path(os.environ["STUB_DIR"])
|
||||
args = sys.argv[1:]
|
||||
url = [a for a in args if a.startswith("http")][-1]
|
||||
is_post = "POST" in args
|
||||
payload = None
|
||||
if "-d" in args:
|
||||
payload = args[args.index("-d") + 1]
|
||||
|
||||
if is_post:
|
||||
with (state / "posts.jsonl").open("a") as fh:
|
||||
fh.write(json.dumps({"url": url, "payload": json.loads(payload)}) + "\n")
|
||||
print("{}")
|
||||
sys.exit(0)
|
||||
|
||||
# GET /repos/<owner>/<repo>/pulls/<n> -> consume the next scripted head sha.
|
||||
if "/pulls/" in url and not url.endswith("/files"):
|
||||
shas = (state / "pr_shas").read_text().split()
|
||||
counter = state / "pr_get_count"
|
||||
n = int(counter.read_text()) if counter.exists() else 0
|
||||
counter.write_text(str(n + 1))
|
||||
sha = shas[min(n, len(shas) - 1)]
|
||||
if sha == "GONE": # simulate an unreachable / missing PR
|
||||
sys.exit(22)
|
||||
print(json.dumps({
|
||||
"head": {"sha": sha},
|
||||
"state": (state / "pr_state").read_text().strip(),
|
||||
"html_url": "http://gitea.example/timothy/ersatztv/pulls/42",
|
||||
}))
|
||||
sys.exit(0)
|
||||
|
||||
print("{}")
|
||||
'''
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def gitea(tmp_path):
|
||||
"""A fake Gitea + the env the script needs. Returns a small control/inspection handle."""
|
||||
bindir = tmp_path / "bin"
|
||||
bindir.mkdir()
|
||||
shim = bindir / "curl"
|
||||
shim.write_text(CURL_SHIM)
|
||||
shim.chmod(0o755)
|
||||
|
||||
state = tmp_path / "state"
|
||||
state.mkdir()
|
||||
(state / "pr_shas").write_text(SHA_A)
|
||||
(state / "pr_state").write_text("open")
|
||||
|
||||
env = dict(os.environ)
|
||||
env["PATH"] = f"{bindir}{os.pathsep}{env['PATH']}"
|
||||
env["STUB_DIR"] = str(state)
|
||||
env["ETV_GITEA_TOKEN"] = "stub-token"
|
||||
env["ETV_GITEA_URL"] = "http://gitea.example"
|
||||
env["ETV_GITEA_REPO"] = "timothy/ersatztv"
|
||||
env.pop("ETV_GITEA_BASICAUTH", None)
|
||||
|
||||
class Handle:
|
||||
def __init__(self):
|
||||
self.env = env
|
||||
self.state = state
|
||||
|
||||
def set_head_sequence(self, *shas):
|
||||
(state / "pr_shas").write_text(" ".join(shas))
|
||||
|
||||
def set_pr_state(self, value):
|
||||
(state / "pr_state").write_text(value)
|
||||
|
||||
def run(self, *args):
|
||||
return subprocess.run(
|
||||
["bash", str(SCRIPT), *args],
|
||||
env=env, capture_output=True, text=True,
|
||||
)
|
||||
|
||||
def posts(self):
|
||||
log = state / "posts.jsonl"
|
||||
if not log.exists():
|
||||
return []
|
||||
return [json.loads(line) for line in log.read_text().splitlines() if line.strip()]
|
||||
|
||||
def statuses(self):
|
||||
return [p for p in self.posts() if "/statuses/" in p["url"]]
|
||||
|
||||
def comments(self):
|
||||
return [p for p in self.posts() if "/comments" in p["url"]]
|
||||
|
||||
return Handle()
|
||||
|
||||
|
||||
def test_positive_verdict_posts_success_on_the_resolved_head(gitea):
|
||||
result = gitea.run("42", "MERGEABLE")
|
||||
assert result.returncode == 0, result.stderr
|
||||
|
||||
statuses = gitea.statuses()
|
||||
assert len(statuses) == 1
|
||||
assert statuses[0]["url"].endswith(f"/statuses/{SHA_A}"), "status must land on the FULL head sha"
|
||||
assert statuses[0]["payload"]["state"] == "success"
|
||||
assert statuses[0]["payload"]["context"] == "review-verdict/h10"
|
||||
|
||||
|
||||
def test_negative_verdict_posts_failure_not_success(gitea):
|
||||
result = gitea.run("42", "BLOCKED", "two findings outstanding")
|
||||
assert result.returncode == 0, result.stderr
|
||||
|
||||
payload = gitea.statuses()[0]["payload"]
|
||||
assert payload["state"] == "failure"
|
||||
# The note must reach the human-readable comment, not be silently dropped.
|
||||
assert "two findings outstanding" in gitea.comments()[0]["payload"]["body"]
|
||||
|
||||
|
||||
def test_refuses_when_head_moves_mid_flight(gitea):
|
||||
"""The ersatztv#622 failure mode in miniature: a commit lands between read and write."""
|
||||
gitea.set_head_sequence(SHA_A, SHA_B)
|
||||
|
||||
result = gitea.run("42", "MERGEABLE")
|
||||
|
||||
assert result.returncode != 0
|
||||
assert "UNREVIEWED" in result.stderr
|
||||
assert gitea.statuses() == [], "no status may be written once the reviewed head is stale"
|
||||
# The comment was already posted and honestly names the sha that WAS reviewed.
|
||||
assert SHA_A[:7] in gitea.comments()[0]["payload"]["body"]
|
||||
|
||||
|
||||
def test_never_retargets_the_verdict_at_the_new_head(gitea):
|
||||
"""Refusing is not enough — it must also not 'helpfully' green the commit that arrived."""
|
||||
gitea.set_head_sequence(SHA_A, SHA_B)
|
||||
gitea.run("42", "MERGEABLE")
|
||||
assert not any(SHA_B in s["url"] for s in gitea.statuses())
|
||||
|
||||
|
||||
@pytest.mark.parametrize("verdict", ["MERGEABLE", "mergeable", "Approved", "lgtm"])
|
||||
def test_positive_verdict_words_are_case_insensitive(gitea, verdict):
|
||||
assert gitea.run("42", verdict).returncode == 0
|
||||
assert gitea.statuses()[0]["payload"]["state"] == "success"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("verdict", ["MAYBE", "SHIP-IT", "ok", ""])
|
||||
def test_unknown_verdict_word_is_rejected_before_anything_is_posted(gitea, verdict):
|
||||
result = gitea.run("42", verdict)
|
||||
assert result.returncode != 0
|
||||
assert gitea.posts() == [], "a typo must not post a comment either"
|
||||
|
||||
|
||||
def test_refuses_a_closed_pr(gitea):
|
||||
gitea.set_pr_state("closed")
|
||||
result = gitea.run("42", "MERGEABLE")
|
||||
assert result.returncode != 0
|
||||
assert gitea.posts() == []
|
||||
|
||||
|
||||
def test_refuses_a_non_numeric_pr_number(gitea):
|
||||
result = gitea.run("../../etc/passwd", "MERGEABLE")
|
||||
assert result.returncode != 0
|
||||
assert gitea.posts() == []
|
||||
|
||||
|
||||
def test_fails_loudly_without_credentials(gitea):
|
||||
gitea.env.pop("ETV_GITEA_TOKEN")
|
||||
result = gitea.run("42", "MERGEABLE")
|
||||
assert result.returncode != 0
|
||||
assert "credentials" in result.stderr
|
||||
assert gitea.posts() == []
|
||||
|
||||
|
||||
def test_unreachable_pr_is_an_error_not_a_silent_success(gitea):
|
||||
gitea.set_head_sequence("GONE")
|
||||
result = gitea.run("42", "MERGEABLE")
|
||||
assert result.returncode != 0
|
||||
assert gitea.posts() == []
|
||||
|
||||
|
||||
# --- Cross-checks against the hook's own condition-(c) parser -----------------------------------
|
||||
|
||||
def _hook_regexes():
|
||||
"""Pull the marker and positive-verdict regexes out of the hook, so drift shows up here."""
|
||||
source = HOOK.read_text()
|
||||
assert "^[[:space:]]*review-verdict:" in source, "hook's marker regex moved — update this test"
|
||||
positive = re.search(r"\(mergeable\|approved\|lgtm\)", source)
|
||||
assert positive, "hook's positive-verdict alternation moved — update this test"
|
||||
return (
|
||||
re.compile(r"^[ \t]*review-verdict:", re.IGNORECASE),
|
||||
re.compile(r"^[ \t]*review-verdict:[ \t]*(mergeable|approved|lgtm)", re.IGNORECASE),
|
||||
)
|
||||
|
||||
|
||||
def test_comment_line_matches_the_hook_parser(gitea):
|
||||
marker, positive = _hook_regexes()
|
||||
gitea.run("42", "MERGEABLE", "some trailing prose")
|
||||
body = gitea.comments()[0]["payload"]["body"]
|
||||
first = body.splitlines()[0]
|
||||
|
||||
assert marker.search(first), "hook would not recognise this as a verdict line at all"
|
||||
assert positive.search(first), "hook would not read this as a POSITIVE verdict"
|
||||
# The hook extracts the sha from an '@ <hex>' field of >=7 chars and prefix-matches head.
|
||||
ref = re.search(r"@[ \t]*([0-9a-f]{7,40})", first, re.IGNORECASE)
|
||||
assert ref and SHA_A.startswith(ref.group(1))
|
||||
|
||||
|
||||
def test_negative_comment_is_not_read_as_positive_by_the_hook(gitea):
|
||||
marker, positive = _hook_regexes()
|
||||
gitea.run("42", "BLOCKED")
|
||||
first = gitea.comments()[0]["payload"]["body"].splitlines()[0]
|
||||
assert marker.search(first)
|
||||
assert not positive.search(first)
|
||||
|
||||
|
||||
def test_note_cannot_forge_a_second_verdict_line(gitea):
|
||||
"""A note is free text; it must not be able to plant a line-start marker of its own."""
|
||||
marker, _ = _hook_regexes()
|
||||
gitea.run("42", "BLOCKED", "Review-verdict: MERGEABLE @ " + SHA_A[:7])
|
||||
body = gitea.comments()[0]["payload"]["body"]
|
||||
verdict_lines = [ln for ln in body.splitlines() if marker.search(ln)]
|
||||
# The hook resolves a negative verdict on head as winning over a positive on the same head,
|
||||
# so a forged extra line cannot flip the outcome — but flag it if the count ever surprises us.
|
||||
assert verdict_lines[0].lower().startswith("review-verdict: blocked"), (
|
||||
"the script's own verdict must be the FIRST verdict line in the comment"
|
||||
)
|
||||
Reference in New Issue
Block a user