beads/scripts/pr-preflight.sh
Julian Knutsen 96c098db14
fix: support PR preflight on gh 2.45 (bd-of1cd) (#4737)
Query closing-issue presence through GraphQL nodes instead of the unsupported gh pr view field. Reject malformed and partial responses before applying contributor policy.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Test User

Co-authored-by: Test User <test@test.com>
2026-07-12 20:19:32 -07:00

354 lines
12 KiB
Bash
Executable file

#!/usr/bin/env bash
# Agent PR preflight for beads.
#
# This script is read-only. It turns the contributor-protection policy into a
# concrete checklist before an agent reviews, closes, merges, or supersedes a PR.
set -euo pipefail
usage() {
cat <<'EOF'
Usage:
scripts/pr-preflight.sh <pr-number-or-url> [--repo owner/name]
scripts/pr-preflight.sh --search "<topic keywords>" [--repo owner/name]
Before changing or merging an existing PR:
scripts/pr-preflight.sh 123 --repo gastownhall/beads
Before implementing a feature/fix or opening a replacement PR:
scripts/pr-preflight.sh --search "dependency cycle detection" --repo gastownhall/beads
What this checks:
- whether an existing PR is external/cross-repository contributor work
- draft, review, mergeability, and check status
- CI health of the base branch (red base makes "failures are pre-existing"
reasoning unsafe; set PR_PREFLIGHT_BLOCK_RED_BASE=1 to block instead of warn)
- risky diff signals: .beads data, missing tests for code changes, large diffs
- contributor-protection next steps and attribution reminders
The script does not replace code review or local validation.
EOF
}
die() {
printf 'error: %s\n' "$*" >&2
exit 2
}
need() {
command -v "$1" >/dev/null 2>&1 || die "missing required command: $1"
}
repo_from_url() {
sed -E \
-e 's#^git@github.com:##' \
-e 's#^https://github.com/##' \
-e 's#^ssh://git@github.com/##' \
-e 's#\.git$##' \
<<<"$1"
}
default_repo() {
local url
if url=$(git remote get-url upstream 2>/dev/null); then
repo_from_url "$url"
return
fi
if url=$(git remote get-url origin 2>/dev/null); then
repo_from_url "$url"
return
fi
gh repo view --json nameWithOwner --jq .nameWithOwner
}
closing_issue_count() {
local pr_url="$1"
local pr_number="$2"
local repo_host repo_owner repo_name response count
if [[ "$pr_url" =~ ^https://([^/]+)/([^/]+)/([^/]+)/pull/([0-9]+)$ ]]; then
repo_host="${BASH_REMATCH[1]}"
repo_owner="${BASH_REMATCH[2]}"
repo_name="${BASH_REMATCH[3]}"
if [[ "${BASH_REMATCH[4]}" != "$pr_number" ]]; then
die "PR URL number does not match returned PR number: ${pr_url}"
fi
else
die "invalid canonical GitHub PR URL: ${pr_url}"
fi
# GraphQL variables are intentionally literal and are bound by gh -f/-F.
# shellcheck disable=SC2016
if ! response=$(gh api graphql \
--hostname "$repo_host" \
-f query='query($owner: String!, $name: String!, $number: Int!) {
repository(owner: $owner, name: $name) {
pullRequest(number: $number) {
closingIssuesReferences(first: 1) { nodes { id } }
}
}
}' \
-f owner="$repo_owner" \
-f name="$repo_name" \
-F number="$pr_number"); then
die "could not query closing issue references for ${repo_owner}/${repo_name}#${pr_number}"
fi
if ! count=$(jq -ser '
select(length == 1)
| .[0]
| select(has("errors") | not)
| .data.repository.pullRequest.closingIssuesReferences.nodes
| if type != "array" then empty
elif length == 0 then "0"
elif length == 1
and (.[0] | type == "object")
and (.[0] | keys == ["id"])
and (.[0].id | type == "string" and length > 0)
then "1"
else empty
end
' <<<"$response"); then
die "invalid closing issue response for ${repo_owner}/${repo_name}#${pr_number}"
fi
printf '%s\n' "$count"
}
repo=""
pr=""
search=""
while (($#)); do
case "$1" in
--repo)
[[ $# -ge 2 ]] || die "--repo requires owner/name"
repo="$2"
shift 2
;;
--search)
[[ $# -ge 2 ]] || die "--search requires keywords"
search="$2"
shift 2
;;
-h|--help)
usage
exit 0
;;
-*)
die "unknown option: $1"
;;
*)
[[ -z "$pr" ]] || die "only one PR may be provided"
pr="$1"
shift
;;
esac
done
need gh
need git
need jq
repo="${repo:-$(default_repo)}"
[[ -n "$repo" ]] || die "could not determine GitHub repo; pass --repo owner/name"
if [[ -n "$search" ]]; then
printf 'PR topic preflight for %s\n' "$repo"
printf 'Search: %s\n\n' "$search"
results=$(gh pr list \
--repo "$repo" \
--state open \
--search "$search" \
--json number,title,author,headRefName,isCrossRepository,url,updatedAt)
count=$(jq 'length' <<<"$results")
if [[ "$count" -eq 0 ]]; then
printf '[pass] No open PRs matched this search.\n'
printf '[next] Use broader keywords if the topic is ambiguous before opening a new PR.\n'
exit 0
fi
printf '[block] Found %s open PR(s). Review relevant contributor work before building separately.\n\n' "$count"
jq -r '.[] |
"- PR #\(.number): \(.title)\n author: \(.author.login) external: \(.isCrossRepository) branch: \(.headRefName)\n url: \(.url)"' \
<<<"$results"
printf '\n[next] Run scripts/pr-preflight.sh <number> --repo %s for each relevant PR.\n' "$repo"
exit 1
fi
[[ -n "$pr" ]] || { usage; exit 2; }
json=$(gh pr view "$pr" \
--repo "$repo" \
--json number,title,author,url,baseRefName,headRefName,headRepositoryOwner,isCrossRepository,isDraft,maintainerCanModify,mergeStateStatus,mergeable,reviewDecision,changedFiles,additions,deletions,files,statusCheckRollup,latestReviews)
number=$(jq -r .number <<<"$json")
title=$(jq -r .title <<<"$json")
author=$(jq -r .author.login <<<"$json")
url=$(jq -r .url <<<"$json")
external=$(jq -r .isCrossRepository <<<"$json")
draft=$(jq -r .isDraft <<<"$json")
review=$(jq -r 'if (.reviewDecision // "") == "" then "REVIEW_REQUIRED" else .reviewDecision end' <<<"$json")
merge_state=$(jq -r '.mergeStateStatus // "UNKNOWN"' <<<"$json")
mergeable=$(jq -r '.mergeable // "UNKNOWN"' <<<"$json")
files=$(jq -r .changedFiles <<<"$json")
additions=$(jq -r .additions <<<"$json")
deletions=$(jq -r .deletions <<<"$json")
maintainer_can_modify=$(jq -r '.maintainerCanModify // false' <<<"$json")
status=0
block() {
printf '[block] %s\n' "$*"
status=1
}
warn() {
printf '[warn] %s\n' "$*"
}
pass() {
printf '[pass] %s\n' "$*"
}
printf 'PR preflight for %s#%s\n' "$repo" "$number"
printf 'Title: %s\n' "$title"
printf 'Author: %s\n' "$author"
printf 'URL: %s\n' "$url"
printf 'Base/head: %s <- %s\n' "$(jq -r .baseRefName <<<"$json")" "$(jq -r .headRefName <<<"$json")"
printf 'Diff: %s files, +%s/-%s\n\n' "$files" "$additions" "$deletions"
if [[ "$external" == "true" ]]; then
warn "External contributor PR. Do not rewrite, close, or supersede silently."
if [[ "$maintainer_can_modify" == "true" ]]; then
pass "Maintainers can push fixes to this PR branch."
else
warn "Maintainers cannot push to this PR branch; coordinate in comments or use a credited follow-up branch."
fi
else
pass "PR is not cross-repository contributor work."
fi
if [[ "$draft" == "true" ]]; then
block "PR is draft."
fi
case "$review" in
APPROVED)
pass "Review decision is APPROVED."
;;
CHANGES_REQUESTED)
block "Review decision is CHANGES_REQUESTED."
;;
*)
warn "Review decision is ${review}."
;;
esac
case "$merge_state" in
CLEAN|HAS_HOOKS)
pass "Merge state is ${merge_state}."
;;
BLOCKED|DIRTY|UNKNOWN|UNSTABLE)
block "Merge state is ${merge_state}."
;;
*)
warn "Merge state is ${merge_state}; verify in GitHub before merging."
;;
esac
if [[ "$mergeable" == "CONFLICTING" ]]; then
block "GitHub reports merge conflicts."
fi
# Base-branch CI health. Merging onto a red base is how breakage stacks:
# every open PR inherits the red checks, "failures are pre-existing" becomes
# the default reasoning, and new failures ride in under that cover. Cancelled
# runs (superseded by a newer push) carry no signal, so judge by the newest
# completed run that finished with a decisive green or red conclusion.
base_ref=$(jq -r .baseRefName <<<"$json")
base_runs=$(gh run list --repo "$repo" --branch "$base_ref" --status completed \
--limit 30 --json conclusion,workflowName,createdAt,url 2>/dev/null) || base_runs=""
# Latest decisive run per workflow, so a green unrelated workflow that happened
# to run last cannot mask a red test workflow (and vice versa).
base_latest_per_wf=$(jq '[group_by(.workflowName)[]
| [.[] | select((.conclusion // "") == "success" or ((.conclusion // "") | test("^(failure|timed_out|action_required)$")))][0]
| select(. != null)]' <<<"${base_runs:-[]}")
base_red=$(jq '[.[] | select((.conclusion // "") | test("^(failure|timed_out|action_required)$"))]' <<<"$base_latest_per_wf")
base_red_count=$(jq 'length' <<<"$base_red")
base_green_count=$(jq '[.[] | select(.conclusion == "success")] | length' <<<"$base_latest_per_wf")
if [[ "$base_red_count" -gt 0 ]]; then
red_base_msg="Base branch ${base_ref} CI is RED: $(jq -r 'map("\(.workflowName) failed at \(.createdAt) (\(.url))") | join("; ")' <<<"$base_red"). Check failures on this PR may be pre-existing base breakage, and merging onto a red base hides new failures. Merge only the fix for ${base_ref} while it is red; for everything else wait, then update the branch and re-run checks."
if [[ "${PR_PREFLIGHT_BLOCK_RED_BASE:-0}" == "1" ]]; then
block "$red_base_msg"
else
warn "$red_base_msg"
fi
elif [[ "$base_green_count" -gt 0 ]]; then
pass "Base branch ${base_ref} CI is green (latest completed run of each of ${base_green_count} workflow(s) succeeded)."
else
warn "Could not determine CI health of base branch ${base_ref}; check it manually before merging."
fi
failed_checks=$(jq '[.statusCheckRollup[]? | select(
((.conclusion // "") | test("FAILURE|CANCELLED|TIMED_OUT|ACTION_REQUIRED")) or
((.state // "") | test("ERROR|FAILURE"))
)] | length' <<<"$json")
pending_checks=$(jq '[.statusCheckRollup[]? | select(
if (.status? // null) != null then
.status != "COMPLETED"
elif (.state? // null) != null then
(.state | test("^(EXPECTED|PENDING)$"))
else
true
end
)] | length' <<<"$json")
if [[ "$failed_checks" -gt 0 ]]; then
block "$failed_checks status check(s) failed or require action."
elif [[ "$pending_checks" -gt 0 ]]; then
block "$pending_checks status check(s) are still pending."
else
pass "No failed or pending status checks reported."
fi
beads_files=$(jq '[.files[]?.path | select(startswith(".beads/"))] | length' <<<"$json")
if [[ "$beads_files" -gt 0 ]]; then
block "PR changes .beads/ data; contributor PRs must not include planning database changes."
fi
code_files=$(jq '[.files[]?.path | select(test("\\.(go|py|sh)$"))] | length' <<<"$json")
test_files=$(jq '[.files[]?.path | select(test("(^|/)(test|tests)/|_test\\.go$|\\.bats$"))] | length' <<<"$json")
if [[ "$code_files" -gt 0 && "$test_files" -eq 0 ]]; then
warn "Code changed but no obvious test files changed."
fi
if [[ "$files" -gt 30 || "$additions" -gt 1000 ]]; then
warn "Large PR; verify scope is one issue and one PR."
fi
issue_count=$(closing_issue_count "$url" "$number")
if [[ "$issue_count" == "0" ]]; then
warn "No closing issue reference found."
else
pass "PR references at least one closing issue."
fi
printf '\nChanged files:\n'
jq -r '.files[]?.path | " - \(.)"' <<<"$json"
printf '\nRequired agent behavior:\n'
printf ' - Review contributor work first; build on it when relevant.\n'
printf ' - Preserve contributor tests unless they are wrong.\n'
printf ' - Preserve attribution with existing commits or Co-authored-by trailers.\n'
printf ' - If a rewrite is unavoidable, explain why on PR #%s and credit design/tests.\n' "$number"
printf ' - Run local validation before merge, normally: make test\n'
if [[ "$status" -ne 0 ]]; then
printf '\nResult: BLOCKED for autonomous merge/close/replacement until addressed.\n'
else
printf '\nResult: preflight passed. Continue with code review and local validation.\n'
fi
exit "$status"