From 13e8f54d605a58918c175e1891915df748680ec2 Mon Sep 17 00:00:00 2001 From: cndgrr <59120057+cndgrr@users.noreply.github.com> Date: Mon, 3 Aug 2026 18:01:58 +0000 Subject: [PATCH] fix(issueflow): a failed read never reaches a decision function MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `gh api` prints a 5xx response body to stdout AND exits non-zero, and GitHub's 5xx body is a JSON object. Inside the per-issue subshell that payload passed `has("pull_request") | not`, emptied `.labels[]`, and `queue_decision` — correct on the input it was handed — wrote `needs-triage` onto a healthy epic. The run then logged `reconciled.` and exited 0 (crew#329, #247). errexit could not have caught it: a command whose status is tested by `||` runs with errexit suppressed, and the suppression extends through the whole subshell body, so the `|| log` handler is what disables the errexit that would have aborted at the failed read. Removing the handler revives errexit and loses #91's resilience, and an inline `set -e` does not re-arm it. Explicit per-read checks are the mechanism. Every read inside that subshell is now checked — the issue read on its status AND on its payload shape (an HTTP 200 whose body is `null` exits 0 and empties the label set just the same), both reads in `last_issue_activity`, and the comments read in `issue_comment_has_marker`. On failure the issue is left exactly as it is, the reason rides its own `#$n:` line, and the subshell exits with a distinguished status the sweep counts, so a deliberate skip is not reported as a crash and a genuine crash is still named byte-identically. `read_failure_reason` moves to lib/read.sh beside a new `guarded_read`, sourced by both reconcilers: labels-reconcile's copy was the only one, and the issue surface needs the identical rule. Refs #247 --- .../issueflow-reconcile.sh | 146 +++++++++++++++--- actions/labels-reconcile/labels-reconcile.sh | 25 +-- changelog.d/247.md | 16 ++ lib/read.sh | 55 +++++++ test/issueflow-reconcile.test.sh | 18 ++- 5 files changed, 215 insertions(+), 45 deletions(-) create mode 100644 changelog.d/247.md create mode 100644 lib/read.sh diff --git a/actions/issueflow-reconcile/issueflow-reconcile.sh b/actions/issueflow-reconcile/issueflow-reconcile.sh index a77df04..209ee3f 100644 --- a/actions/issueflow-reconcile/issueflow-reconcile.sh +++ b/actions/issueflow-reconcile/issueflow-reconcile.sh @@ -27,10 +27,33 @@ TRIAGE_ACTORS=() # The needs-ruling invariants (#52) — one implementation for both surfaces. # shellcheck source=lib/ruling.sh . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../../lib/ruling.sh" +# The guarded read and its reason line (#101, #247) — one implementation for +# both surfaces. +# shellcheck source=lib/read.sh +. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../../lib/read.sh" + +# The status a per-issue subshell exits with when it walked away from an +# unreadable fact (#247 D4). Distinguished from every other non-zero status so +# a deliberate skip is counted rather than reported as a crash — and so the +# existing crash handler still names a genuine one. +ISSUEFLOW_SKIP=3 +# Set by reconcile_issue_pass, read once by main for the D6 tail. +SKIPPED_COUNT=0 +SKIPPED_ISSUES="" log() { printf 'issueflow: %s\n' "$*"; } run() { if [ -n "${DRY_RUN:-}" ]; then log "DRY_RUN: $*"; else "$@"; fi; } +skip_issue() { # $1 = issue, $2 = the whole reason clause — ends this issue's pass + # Leaves the issue exactly as it is: nothing is derived from a read that + # did not answer. Called from wherever the read lives, so no call site can + # forget to check — which is why it exits rather than returns. Every caller + # runs inside the per-issue subshell, so the exit ends that issue's pass and + # nothing else. The reason rides its own `#$n:`-prefixed line (#247 D5). + log "#$1: skipped this pass — $2" + exit "$ISSUEFLOW_SKIP" +} + load_issueflow_config() { # $1 = labels.conf local conf="$1" line seen=false [ -f "$conf" ] || { echo "issueflow: missing config: $conf" >&2; return 1; } @@ -287,6 +310,31 @@ offsite_resolved_decision() { # PR states on stdin -> NUDGE | QUIET fi } +issue_payload_valid() { # $1 = the requested issue; payload on stdin + # The second of D3's two required guards, and neither subsumes the other. + # The status check catches the 504 whose body is GitHub's JSON error object + # — valid JSON that passes every jq guard and empties the label set. THIS + # one catches an HTTP 200 whose body is `null`, which exits 0 and empties it + # just the same. `.number` is checked against the issue asked for, so a + # payload about some other issue can never be reconciled as this one. + jq -e --arg n "$1" ' + type == "object" and (.number | tostring) == $n and (.labels | type) == "array" + ' >/dev/null 2>&1 +} + +skipped_tail() { # $1 = skip count, $2 = the issue numbers → the D6 line, or nothing + # `reconciled.` stays byte-identical when the pass was whole — tests pin that + # exact string, and #101 D1 is the precedent for not folding new text into a + # matched line. A partial pass says so on a line of its own, after it, so a + # consumer reading only the tail of a job log can see it. + [ "$1" -gt 0 ] || return 0 + if [ "$1" -eq 1 ]; then + printf '%s issue skipped this pass on an unreadable fact: %s\n' "$1" "$2" + else + printf '%s issues skipped this pass on unreadable facts: %s\n' "$1" "$2" + fi +} + # API edge. Marker comments make warnings and nudges idempotent across sweeps. ensure_comment() { # $1 issue, $2 marker, $3 message local n="$1" marker="$2" message="$3" @@ -295,9 +343,15 @@ ensure_comment() { # $1 issue, $2 marker, $3 message $message" >/dev/null } -issue_comment_has_marker() { # $1 issue, $2 marker - gh api --paginate "repos/$REPO/issues/$1/comments" --jq '.[].body' \ - | grep -qF "" +issue_comment_has_marker() { # $1 issue, $2 marker → 0 found, 1 genuinely absent + # A failed read used to answer "no marker", which re-posts the comment the + # marker exists to suppress — absence of evidence read as evidence of + # absence (#247 D1). It cannot be a return value: every caller treats + # non-zero as "absent", so the skip is taken here, at the read. + local bodies + guarded_read bodies gh api --paginate "repos/$REPO/issues/$1/comments" --jq '.[].body' \ + || skip_issue "$1" "could not read its comments: $(read_failure_reason "$READ_FAILURE_STDERR")" + grep -qF "" <<<"$bodies" } reference_states() { @@ -324,22 +378,27 @@ offsite_timeline() { # unreadable timelines are deliberately silent gh api --paginate "repos/$REPO/issues/$1/timeline" 2>/dev/null || return 1 } -last_issue_activity() { - local n="$1" created="$2" latest - latest="$({ - printf '%s\n' "$created" - gh api --paginate "repos/$REPO/issues/$n/comments" --jq '.[].created_at' - # Assignment is the claim itself. Ignoring it would let an old issue be - # reclaimed in the seconds between assignment and its required draft PR. - gh api --paginate "repos/$REPO/issues/$n/timeline" \ - --jq '.[] | select(.event == "assigned") | .created_at' - } \ - | sort | tail -n1)" +last_issue_activity() { # $1 issue, $2 created_at → epoch; non-zero if a read failed + # Both reads are checked, and a failure reports rather than answering an age + # (#247 D1). Swallowed, the comments read falls back to `created_at`, and a + # `claimed` issue created months ago but commented on seconds earlier is + # reclaimed — the live builder unassigned, under a comment asserting 48 + # hours of silence. `needs-triage` is cheap to remove; that is not. + # gh's stderr is left to flow to this function's own, where the caller's + # guarded_read captures it for the reason line. + local n="$1" created="$2" comments timeline latest + comments="$(gh api --paginate "repos/$REPO/issues/$n/comments" --jq '.[].created_at')" \ + || return 1 + # Assignment is the claim itself. Ignoring it would let an old issue be + # reclaimed in the seconds between assignment and its required draft PR. + timeline="$(gh api --paginate "repos/$REPO/issues/$n/timeline" \ + --jq '.[] | select(.event == "assigned") | .created_at')" || return 1 + latest="$(printf '%s\n%s\n%s\n' "$created" "$comments" "$timeline" | sort | tail -n1)" date -d "$latest" +%s } reconcile_issue() { - local n="$1" decision refs cross_refs states age assignees open_pr=false label owners + local n="$1" decision refs cross_refs states age created assignees open_pr=false label owners local merged_ref_pr="" transition_marker="" transition_handled=false local unchecked="" remove_claimed=claimed decision="$(queue_decision <<<"$ISSUE_LABELS")" @@ -386,7 +445,9 @@ The merge releases the claim; no builder owes a draft. Triage owes completion in fi log "#$n: merged Refs PR -> post-merge; claim released" else - age="$(last_issue_activity "$n" "$(jq -r '.created_at' <<<"$ISSUE_JSON")")" + created="$(jq -r '.created_at' <<<"$ISSUE_JSON")" + guarded_read age last_issue_activity "$n" "$created" \ + || skip_issue "$n" "could not read its activity history: $(read_failure_reason "$READ_FAILURE_STDERR")" if [ "$(claim_clock_exempt <<<"$ISSUE_LABELS")" = EXEMPT ]; then # Legitimately quiet work does not run the reclaim clock. Only the # clock stops: an unassigned claim is still a repair the decision must @@ -474,8 +535,11 @@ The merge releases the claim; no builder owes a draft. Triage owes completion in run gh issue edit "$n" -R "$REPO" --remove-label stale >/dev/null log "#$n: unstale (a ruling is pending)" fi - [ -n "${age:-}" ] \ - || age="$(last_issue_activity "$n" "$(jq -r '.created_at' <<<"$ISSUE_JSON")")" + if [ -z "${age:-}" ]; then + created="$(jq -r '.created_at' <<<"$ISSUE_JSON")" + guarded_read age last_issue_activity "$n" "$created" \ + || skip_issue "$n" "could not read its activity history: $(read_failure_reason "$READ_FAILURE_STDERR")" + fi reconcile_ruling "$n" "$age" "$NOW" fi } @@ -503,6 +567,34 @@ reconcile_opened_issue() { log "#$n: needs-triage (opened by $author)" } +reconcile_issue_pass() { # $1 = issue — one issue's whole pass, in its own subshell + # The subshell is #91's resilience: one unreadable or broken issue must not + # take the sweep down. What it is NOT is an errexit boundary — a command + # whose status is tested by `||` runs with errexit suppressed, and the + # suppression extends through the whole subshell body, so the handler below + # is what disables the errexit that would have caught a failed read (#247 + # D2). Removing it would revive errexit and lose #91. Explicit per-read + # checks are the mechanism instead, and each one exits with ISSUEFLOW_SKIP. + local n="$1" status=0 + ( + guarded_read ISSUE_JSON gh api "repos/$REPO/issues/$n" \ + || skip_issue "$n" "could not read the issue: $(read_failure_reason "$READ_FAILURE_STDERR")" + issue_payload_valid "$n" <<<"$ISSUE_JSON" \ + || skip_issue "$n" "the issue read answered a payload that is not issue #$n carrying a label array" + jq -e 'has("pull_request") | not' <<<"$ISSUE_JSON" >/dev/null || exit 0 + ISSUE_LABELS="$(jq -r '.labels[].name' <<<"$ISSUE_JSON")" + reconcile_issue "$n" + ) || status=$? + if [ "$status" -eq "$ISSUEFLOW_SKIP" ]; then + SKIPPED_COUNT=$((SKIPPED_COUNT + 1)) + SKIPPED_ISSUES="${SKIPPED_ISSUES:+$SKIPPED_ISSUES }#$n" + elif [ "$status" -ne 0 ]; then + # Byte-identical, and still owed: a skip is deliberate, a crash is not, + # and folding the two together would hide one behind the other (D4). + log "#$n: reconcile failed — continuing with the remaining issues" + fi +} + main() { local owner name REPO="${REPO:?set REPO to owner/name}" @@ -554,17 +646,21 @@ main() { done < <(refs_references <<<"$body") done)" - local n + local n tail_line + SKIPPED_COUNT=0 + SKIPPED_ISSUES="" for n in $(gh api --paginate "repos/$REPO/issues?state=open&per_page=100" \ --jq '.[] | select(has("pull_request") | not) | .number'); do - ( - ISSUE_JSON="$(gh api "repos/$REPO/issues/$n")" - jq -e 'has("pull_request") | not' <<<"$ISSUE_JSON" >/dev/null || exit 0 - ISSUE_LABELS="$(jq -r '.labels[].name' <<<"$ISSUE_JSON")" - reconcile_issue "$n" - ) || log "#$n: reconcile failed — continuing with the remaining issues" + reconcile_issue_pass "$n" done log "reconciled." + # The job stays green (D7): an hourly sweep over a hundred-issue board meets + # transient 504s as a matter of course, and reddening the whole run for one + # skipped issue trains consumers to ignore red — the outcome #95 and #101 + # both steered away from on the PR surface. This line is what buys back the + # auditability that costs. + tail_line="$(skipped_tail "$SKIPPED_COUNT" "$SKIPPED_ISSUES")" + [ -z "$tail_line" ] || log "$tail_line" } if [ "${BASH_SOURCE[0]}" = "$0" ]; then main "$@"; fi diff --git a/actions/labels-reconcile/labels-reconcile.sh b/actions/labels-reconcile/labels-reconcile.sh index 003c92c..97ada8a 100755 --- a/actions/labels-reconcile/labels-reconcile.sh +++ b/actions/labels-reconcile/labels-reconcile.sh @@ -74,6 +74,12 @@ SELF_WORKFLOW="${SELF_WORKFLOW:-${GITHUB_WORKFLOW:-}}" # The needs-ruling invariants (#52) — one implementation for both surfaces. # shellcheck source=lib/ruling.sh . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../../lib/ruling.sh" +# The guarded read and its reason line (#101) — one implementation for both +# surfaces. read_failure_reason lived here until the issue surface needed the +# identical rule (#247); a second copy of it is the failure lib/ruling.sh's +# own header was written to record. +# shellcheck source=lib/read.sh +. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../../lib/read.sh" log() { printf 'labels: %s\n' "$*"; } @@ -98,25 +104,6 @@ blind_sweep_warning() { # $1 = unreadable PRs, $2 = all open PRs, $3 = sampled r fi } -read_failure_reason() { # $1 = captured stderr → one bounded line; pure (#101) - # Verbatim, collapsed, bounded (D3): gh emits multi-line errors and GraphQL - # blobs. Collapsed so the reason is exactly one log line — a raw newline - # inside the captured per-PR output block could collide with a matched - # string — and truncated because an unbounded paste per PR per sweep is - # noise, and annotations are capped anyway. - local reason - reason="$(printf '%s' "${1-}" | tr '\n' ' ')" - if [ -z "$reason" ]; then - # Empty stderr is itself a fact (D4): a read that failed silently is a - # different observation from a denial, and must not read as one. - echo "no error output" - elif [ "${#reason}" -gt 300 ]; then - printf '%s…\n' "${reason:0:300}" - else - printf '%s\n' "$reason" - fi -} - missing_core_labels_warning() { # $1 = declared rows, $2 = repo label names local rows="$1" repo_labels="$2" row name missing="" [ -n "$repo_labels" ] || return 0 diff --git a/changelog.d/247.md b/changelog.d/247.md new file mode 100644 index 0000000..0b0c371 --- /dev/null +++ b/changelog.d/247.md @@ -0,0 +1,16 @@ +### Fixed + +- The issue sweep no longer derives label writes from a read that failed. An + HTTP 504 whose body is GitHub's JSON error object passed every guard and + emptied the label set, so a healthy epic was written `needs-triage` and the + pass reported success (#247). +- A failed comments read no longer reclaims a live claim. Swallowed, it dated + the issue by `created_at` and unassigned the builder under a comment + asserting 48 hours of silence about an issue commented on seconds earlier + (#247). +- A failed comments read no longer reads as "no marker", which re-posted the + comment the marker exists to suppress (#247). +- Every read inside the per-issue subshell is checked explicitly, on its + status and on its payload shape; the issue is left exactly as it is and the + sweep continues. A partial pass names its skipped issues after + `reconciled.` (#247). diff --git a/lib/read.sh b/lib/read.sh new file mode 100644 index 0000000..c391cb2 --- /dev/null +++ b/lib/read.sh @@ -0,0 +1,55 @@ +#!/usr/bin/env bash +# lib/read.sh — the guarded read: an unreadable fact never invents a verdict. +# +# Both reconcilers source this file. The rule is the family's oldest one +# (#101, #95) and it has now been bought twice: the PR surface learned it +# when a permissions denial and a network hiccup left byte-identical +# evidence, and the ISSUE surface learned it when an HTTP 504 whose body is +# GitHub's JSON error object flowed straight into a decision function — +# `gh api` prints that body to stdout *and* exits non-zero, so the payload +# reaching the guards was valid JSON, `.labels[]` came back empty, and the +# sweep wrote `needs-triage` onto a healthy epic and called the pass a +# success (crew#329, #247). +# +# Two helpers, both used on both surfaces: +# - guarded_read — run a read, keep its stderr, report its status +# - read_failure_reason — render that stderr into one bounded log line +# +# What the CALLER does with a failed read is the caller's: labels-reconcile +# leaves the PR alone for the pass, issueflow-reconcile skips the issue. The +# one thing neither may do is carry a degraded value into a decision. + +guarded_read() { # $1 = variable to fill, rest = the read; sets READ_FAILURE_STDERR + # The status check and the captured stderr are one operation on purpose: a + # read whose failure is noticed but whose reason is thrown away is what + # #95 had to infer a cause from a control case for — wrongly, it turned + # out (#101 D2). Captured into a file rather than merged into stdout, so + # an unlucky error line can never be read back as the read's own payload. + local __var="$1" __err __out __rc=0 + shift + __err="$(mktemp)" || return 1 + __out="$("$@" 2>"$__err")" || __rc=$? + READ_FAILURE_STDERR="$(cat "$__err")" + rm -f "$__err" + printf -v "$__var" '%s' "$__out" + return "$__rc" +} + +read_failure_reason() { # $1 = captured stderr → one bounded line; pure (#101) + # Verbatim, collapsed, bounded (D3): gh emits multi-line errors and GraphQL + # blobs. Collapsed so the reason is exactly one log line — a raw newline + # inside the captured per-item output block could collide with a matched + # string — and truncated because an unbounded paste per item per sweep is + # noise, and annotations are capped anyway. + local reason + reason="$(printf '%s' "${1-}" | tr '\n' ' ')" + if [ -z "$reason" ]; then + # Empty stderr is itself a fact (D4): a read that failed silently is a + # different observation from a denial, and must not read as one. + echo "no error output" + elif [ "${#reason}" -gt 300 ]; then + printf '%s…\n' "${reason:0:300}" + else + printf '%s\n' "$reason" + fi +} diff --git a/test/issueflow-reconcile.test.sh b/test/issueflow-reconcile.test.sh index 837194a..678999f 100644 --- a/test/issueflow-reconcile.test.sh +++ b/test/issueflow-reconcile.test.sh @@ -289,6 +289,11 @@ check "claimed plus attention is a healthy issue" 0 "KEEP" \ INOW=2000000000 iso_at() { date -u -d "@$1" +%Y-%m-%dT%H:%M:%SZ; } +# gh's own rendering of a 5xx whose body carries a `message` key — the line +# crew#329's job log carried, verbatim (#247), and the payload beside it. +GH_STUB_STDERR="gh: We couldn't respond to your request in time. (HTTP 504)" +GH_STUB_ERROR_BODY='{"message":"We could not respond to your request in time.","documentation_url":"https://docs.github.com/rest"}' + issue_stub_gh() { if [ "$1" = api ]; then shift @@ -303,7 +308,18 @@ issue_stub_gh() { done file="$TMP/$(printf '%s' "$endpoint" | tr '/' '_').json" printf '%s\n' "$endpoint" >>"$TMP/api-calls" - [ ! -f "$file.error" ] || return 1 + # A `.http-error` sentinel is the real 5xx (#247): `gh api` prints the + # response body — GitHub's JSON error object — to STDOUT, says why on + # stderr, and exits non-zero. The `.error` sentinel models a failure with + # no payload, which is the *safe* path (an empty label set is empty either + # way), and is why this class was never caught. Both now speak on stderr, + # because the real gh always does and the reason line renders it. + if [ -f "$file.http-error" ]; then + cat "$file.http-error" + printf '%s\n' "$GH_STUB_STDERR" >&2 + return 1 + fi + [ ! -f "$file.error" ] || { printf '%s\n' "$GH_STUB_STDERR" >&2; return 1; } [ -f "$file" ] || { printf '[]\n'; return 0; } if [ -n "$jqexpr" ]; then jq -r "$jqexpr" "$file"; else cat "$file"; fi elif [ "$1" = issue ] && [ "$2" = comment ]; then