@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/drain-prs/scripts/triage-prs.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# Enumerates open remote GitHub PRs and classifies each into one of seven drain
+# tiers (ready-green, ready-unarmed, needs-lockfile-fix, needs-conflict-resolution,
+# needs-review, drafts, broken), emitting a tier-grouped report.
+#
+# Usage:
+#   triage-prs.sh [--format text|json] [--fixture <path>]
+#
+# --fixture is test-only: reads the PR-list JSON from a file instead of `gh`.
+#   The fixture must be the exact shape of
+#   `gh pr list --state open --json number,title,headRefName,isDraft,mergeable,reviewDecision,labels,author,createdAt,statusCheckRollup`.
+#
+# Classification is first-match-wins in this priority order:
+#   1. drafts                     isDraft == true            (author-owned WIP)
+#   2. broken                     CONFLICTING AND >=3 failing checks
+#   3. needs-conflict-resolution  CONFLICTING
+#   4. needs-lockfile-fix         has `dependencies` label AND >0 failing checks
+#   5. ready-unarmed              ready (non-draft) PR whose head verdict is no-run or
+#                                 stalled and nothing else is failing: it was readied but
+#                                 no full CI run exists (ADR-276 S3, #9728). Recovery:
+#                                 `gh pr ready --undo <N>` then `gh pr ready <N>` (user token)
+#   6. needs-review               has `bot-fix/review-required` label
+#                                 OR reviewDecision == REVIEW_REQUIRED
+#   7. ready-green                MERGEABLE AND 0 failing checks (not awaiting-approval)
+#   8. needs-review               (fallback: UNKNOWN-mergeable / un-reviewed)
+#
+# Failing checks are counted from the NEWEST row per check name (a ready PR carries the
+# draft run's rows AND the ready run's rows; counting both reads a decided PR as red). For a
+# ready PR whose newest `test` row is red, plugins/soleur/scripts/ci-head-verdict.sh decides
+# whether that row is the draft-era one: pending-full, no-run, stalled and awaiting-approval
+# never count it failing; full-decided and n/a keep today's reading. A resolver that errors
+# keeps today's reading too. Live mode calls the resolver for each non-draft PR with a failing
+# `test` row; --fixture mode never does unless CI_HEAD_VERDICT_BIN is set (a test seam). A resolver that cannot read prints
+# state=error (exit 3), outside the six whitelisted states, so it is ignored: a real red `test` is never softened by an outage.
+# `no-run` goes to ready-unarmed too, with a recovery that first asks whether another session is still inside wait-ready-run.
+
+set -euo pipefail
+
+FORMAT="text"
+FIXTURE=""
+
+usage() {
+  cat <<'EOF'
+Usage: triage-prs.sh [--format text|json] [--fixture <path>]
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --format)   FORMAT="$2";  shift 2 ;;
+    --fixture)  FIXTURE="$2"; shift 2 ;;
+    -h|--help)  usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+command -v jq >/dev/null 2>&1 || { echo "ERROR: jq not found on PATH." >&2; exit 1; }
+
+# --- Acquire the PR-list JSON ------------------------------------------------
+if [[ -n "$FIXTURE" ]]; then
+  [[ -f "$FIXTURE" ]] || { echo "ERROR: fixture not found: $FIXTURE" >&2; exit 1; }
+  PR_JSON="$(cat "$FIXTURE")"
+else
+  command -v gh >/dev/null 2>&1 || { echo "ERROR: gh not found on PATH." >&2; exit 1; }
+  gh auth status >/dev/null 2>&1 || { echo "ERROR: gh is not authenticated (run 'gh auth login')." >&2; exit 1; }
+  # Two-stage gh --json | jq (never `gh --jq` with --arg — learning
+  # 2026-04-15-gh-jq-does-not-forward-arg-to-jq).
+  #
+  # `--limit 200` is a LOAD-BEARING BOUND (#6736), not just a paging preference. It is
+  # the only cap on $PR_JSON, and $PR_JSON is by far the largest payload in this script:
+  # `statusCheckRollup` alone carries one object per check run per PR. Measured on this
+  # repo: 392,170 B at 20 open PRs, i.e. ~19.6 KB per PR.
+  PR_JSON="$(gh pr list --state open --limit 200 \
+    --json number,title,headRefName,isDraft,mergeable,reviewDecision,labels,author,createdAt,statusCheckRollup)"
+fi
+
+# --- Head verdicts (ADR-276 S3) ------------------------------------------------
+# Candidates: non-draft PRs whose newest `test` row is failing. One resolver call each.
+VERDICT_BIN="${CI_HEAD_VERDICT_BIN:-}"
+if [[ -z "$VERDICT_BIN" && -z "$FIXTURE" ]]; then
+  VERDICT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../scripts" 2>/dev/null && pwd -P)" || VERDICT_DIR=""
+  [[ -z "$VERDICT_DIR" ]] || VERDICT_BIN="$VERDICT_DIR/ci-head-verdict.sh"
+fi
+VERDICTS='{}'
+if [[ -n "$VERDICT_BIN" && -r "$VERDICT_BIN" ]]; then
+  CANDIDATES="$(jq -r '
+    [ .[] | select(.isDraft != true) | . as $pr
+      | ([ .statusCheckRollup[]? | select((.name // .context) == "test") ]
+         | sort_by(.startedAt // "9999") | last // null) as $t
+      | select($t != null and (($t.conclusion // $t.state) as $c
+               | $c == "FAILURE" or $c == "ERROR" or $c == "CANCELLED" or $c == "TIMED_OUT"))
+      | $pr.number ] | .[]' <<<"$PR_JSON")"
+  for n in $CANDIDATES; do
+    marker="$(bash "$VERDICT_BIN" verdict "$n" 2>/dev/null)" || true
+    marker="$(grep -m1 '^SOLEUR_CI_HEAD_VERDICT ' <<<"$marker")" || continue
+    st="${marker#*state=}"; st="${st%% *}"
+    case "$st" in n/a|full-decided|pending-full|no-run|stalled|awaiting-approval) VERDICTS="$(jq -c --arg n "$n" --arg s "$st" '. + {($n): $s}' <<<"$VERDICTS")" ;; esac
+  done
+fi
+
+# --- Classify ---------------------------------------------------------------
+# Emits a flat array of {number,title,author,mergeable,tier}. Failing/pending
+# check counts are derived from statusCheckRollup (conclusion for check-runs,
+# state for legacy statuses).
+#
+# ══ THE `<<<"$PR_JSON"` HERESTRING IS A LOAD-BEARING INVARIANT (#6736) ══
+#
+# $PR_JSON MUST reach jq via this herestring (or a pipe / file), and MUST NEVER be
+# bound as `--argjson pr_json "$PR_JSON"`. A herestring is delivered on jq's STDIN
+# through a pipe/tempfile and has no size limit; an --argjson binding makes it ONE argv
+# argument, and the kernel caps a SINGLE argv argument at MAX_ARG_STRLEN = 131,072 B —
+# verified by bisect on this host: 131,071 B passes, 131,072 B fails E2BIG. That is NOT
+# `getconf ARG_MAX` (2,097,152 B here); a payload at 6% of ARG_MAX still dies.
+#
+# This is NOT a bound that is eroding toward a future failure — it is ALREADY 3× over.
+# Measured on this repo: $PR_JSON is 392,170 B at 20 open PRs, 2.99 × MAX_ARG_STRLEN.
+# Converting this herestring to --argjson does not degrade drain-prs at some later PR
+# count; it breaks it on the next run, today, with `Argument list too long`. Even a
+# single mid-size PR would exceed the ceiling on its own at ~19.6 KB/PR by PR #7.
+#
+# The `--argjson prs "$CLASSIFIED"` binding further down is SAFE and deliberately left
+# alone: the projection above discards statusCheckRollup and keeps ~174 B/PR, measured
+# 3,484 B at 20 PRs (2.7% of the ceiling). $CLASSIFIED is the collapse; $PR_JSON is the
+# raw fan-out. Do not generalize from one to the other.
+#
+# Guarded by the argv-ceiling regression test in ../test/ — it drives this script with a
+# synthesized >MAX_ARG_STRLEN fixture and asserts the fixture really exceeds the ceiling,
+# so the test cannot silently degrade to vacuous.
+CLASSIFIED="$(jq --argjson verdicts "$VERDICTS" '
+  # The NEWEST row per check name: a ready PR lists the draft run rows and the ready run rows.
+  # A queued re-run has no startedAt yet, so a null sorts as the newest.
+  # Keyed on workflow AND name: two workflows may each carry a check called `detect` or `build`, and a newer green in one
+  # must not hide an older red in the other.
+  def newest: [ .statusCheckRollup[]? ] | group_by([.workflowName // "", .name // .context // ""]) | map(sort_by(.startedAt // "9999") | last);
+  # The draft-era `test` row is not a failure while the head verdict says a ready run is coming or missing.
+  def softened($v): ($v == "pending-full" or $v == "no-run" or $v == "stalled" or $v == "awaiting-approval");
+  def counted($v): [ newest[] | select(((.name // .context) == "test" and softened($v)) | not) ];
+  def fails($v): [ counted($v)[] | (.conclusion // .state)
+               | select(. == "FAILURE" or . == "ERROR" or . == "CANCELLED" or . == "TIMED_OUT") ] | length;
+  def pending($v): [ counted($v)[] | (.status // .state)
+               | select(. == "IN_PROGRESS" or . == "QUEUED" or . == "PENDING" or . == "WAITING") ] | length;
+  def haslabel($n): any(.labels[]?; .name == $n);
+  [ .[] | . as $pr | ($verdicts[(.number | tostring)] // "") as $v
+    | ($pr | fails($v)) as $f | ($pr | pending($v)) as $p |
+    {
+      number: .number,
+      title: .title,
+      author: (.author.login // "unknown"),
+      mergeable: (.mergeable // "UNKNOWN"),
+      failing: $f,
+      pending: $p,
+      ci: $v,
+      tier: (
+        if .isDraft == true then "drafts"
+        elif .mergeable == "CONFLICTING" and $f >= 3 then "broken"
+        elif .mergeable == "CONFLICTING" then "needs-conflict-resolution"
+        elif ($pr | haslabel("dependencies")) and $f > 0 then "needs-lockfile-fix"
+        elif ($v == "no-run" or $v == "stalled") and $f == 0 then "ready-unarmed"
+        elif ($pr | haslabel("bot-fix/review-required")) or .reviewDecision == "REVIEW_REQUIRED" then "needs-review"
+        elif .mergeable == "MERGEABLE" and $f == 0 and $v != "awaiting-approval" then "ready-green"
+        else "needs-review"
+        end
+      )
+    }
+    | if .tier == "ready-unarmed" then . + { recovery: "if no session is still inside wait-ready-run for it: gh pr ready --undo \(.number) && gh pr ready \(.number)  (user token, never GITHUB_TOKEN), then re-run the whole ship step 6 block (read ready-count first, arm only after wait-ready-run exits 0)" } else . end
+  ]' <<<"$PR_JSON")"
+
+# --- Emit -------------------------------------------------------------------
+# Stable tier order for the grouped output.
+TIER_ORDER='["ready-green","ready-unarmed","needs-lockfile-fix","needs-conflict-resolution","needs-review","broken","drafts"]'
+
+if [[ "$FORMAT" == "json" ]]; then
+  jq -n --argjson prs "$CLASSIFIED" --argjson order "$TIER_ORDER" '
+    reduce $order[] as $t ({}; . + { ($t): [ $prs[] | select(.tier == $t) ] })
+  '
+  exit 0
+fi
+
+# text format
+echo "=== Open PR triage ==="
+total="$(jq 'length' <<<"$CLASSIFIED")"
+echo "Open PRs: $total"
+echo ""
+jq -r --argjson order "$TIER_ORDER" '
+  . as $prs
+  | $order[] as $t
+  | ([ $prs[] | select(.tier == $t) ]) as $g
+  | "## \($t) (\($g | length))",
+    ( $g[] | "  #\(.number)  \(.title)  [@\(.author), mergeable=\(.mergeable), fail=\(.failing), pending=\(.pending)\(if .ci != "" then ", ci=\(.ci)" else "" end)]",
+             (if .recovery then "      recovery: \(.recovery)" else empty end) ),
+    ""
+' <<<"$CLASSIFIED"

package/skills/drain-prs/test/argv-ceiling.test.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# Argv-ceiling regression for plugins/soleur/skills/drain-prs/scripts/triage-prs.sh (#6736).
+#
+# WHAT THIS GUARDS. $PR_JSON reaches jq via a `<<<"$PR_JSON"` herestring. A herestring is
+# delivered on stdin through a pipe/tempfile and has no size limit. If it is ever converted
+# to `--argjson pr_json "$PR_JSON"` the payload becomes ONE argv argument, and the kernel
+# caps a SINGLE argv argument at MAX_ARG_STRLEN = 131,072 B -- bisected on this host:
+# 131,071 B passes, 131,072 B fails E2BIG. That is NOT `getconf ARG_MAX` (2,097,152 B here);
+# a payload at 6% of ARG_MAX still dies.
+#
+# WHY THIS SITE GETS THE ONLY PHASE-2.3 ASSERTION. Every other bounded site in this sweep is
+# comment-only: proving a bound nobody proposed removing means synthesizing ~30x the real
+# fixture to fire for one imagined mutation. This site is different -- it is not an eroding
+# bound, it is ALREADY over. Measured on this repo: $PR_JSON is 392,170 B at 20 open PRs,
+# 2.99 x MAX_ARG_STRLEN, today. The herestring is the only reason drain-prs runs at all.
+#
+# FIXTURE ADEQUACY. The fixture is SYNTHESIZED (cq-test-fixtures-synthesized-only) and
+# PRODUCTION-SHAPED: each PR carries a statusCheckRollup of realistic check-run objects,
+# which is where the real bytes live. Row count is NOT the load-bearing parameter, BYTES PER
+# ROW is -- 200 *minimal* PRs would measure well under the ceiling and would therefore pass
+# against an --argjson mutation, i.e. vacuously. The suite asserts the fixture's byte size
+# exceeds MAX_ARG_STRLEN in-suite so it cannot silently degrade as jq's encoding or the
+# script's --json field list changes.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGET="$SCRIPT_DIR/../scripts/triage-prs.sh"
+
+# Named at every use, never bare (the whole point of the sweep is that this is a per-argument
+# kernel constant, not ARG_MAX and not a byte count anyone should re-derive from memory).
+MAX_ARG_STRLEN=131072
+
+PASS=0
+FAIL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+command -v jq >/dev/null 2>&1 || { echo "SKIP: jq missing"; exit 0; }
+[[ -f "$TARGET" ]] || { echo "ERROR: target not found: $TARGET" >&2; exit 1; }
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+# --- Synthesized, production-shaped fixture ---------------------------------------------
+# 40 PRs x ~25 check runs. Nothing here is copied from a real PR: numbers, titles, branch
+# names, authors and check names are all generated.
+FIXTURE="$WORK/prs.json"
+PR_ROWS=40
+CHECKS_PER_PR=25
+
+jq -nc --argjson prs "$PR_ROWS" --argjson checks "$CHECKS_PER_PR" '
+  [ range(0; $prs) as $i
+    | { number: (4000 + $i),
+        title: ("synthesized fixture pull request for argv ceiling coverage number \($i) with a realistically long subject line"),
+        headRefName: ("synth/argv-ceiling-fixture-branch-with-a-long-name-\($i)"),
+        isDraft: (($i % 7) == 0),
+        mergeable: (if ($i % 5) == 0 then "CONFLICTING" else "MERGEABLE" end),
+        reviewDecision: (if ($i % 3) == 0 then "REVIEW_REQUIRED" else "APPROVED" end),
+        labels: [ {name: "synthesized-fixture"}, {name: "dependencies"} ],
+        author: { login: ("synth-author-\($i % 4)") },
+        createdAt: "2026-07-01T00:00:00Z",
+        statusCheckRollup:
+          [ range(0; $checks) as $c
+            | { __typename: "CheckRun",
+                name: ("synthesized-workflow-job-with-a-long-descriptive-name / matrix-shard-\($c)"),
+                status: "COMPLETED",
+                conclusion: (if ($c % 11) == 0 then "FAILURE" else "SUCCESS" end),
+                detailsUrl: ("https://example.invalid/synth/checks/\($i)/\($c)/a-long-details-path-segment"),
+                startedAt: "2026-07-01T00:00:00Z",
+                completedAt: "2026-07-01T00:05:00Z" } ] } ]' > "$FIXTURE"
+
+echo "TEST: triage-prs argv ceiling (#6736)"
+
+# --- Generator cardinality: an under-filled generator makes everything below vacuous -----
+gen_rows="$(jq 'length' "$FIXTURE")"
+if [[ "$gen_rows" -eq "$PR_ROWS" ]]; then
+  pass "fixture generator emitted $gen_rows PR rows (want $PR_ROWS)"
+else
+  fail "fixture generator emitted $gen_rows PR rows (want $PR_ROWS) -- asserts below would be vacuous"
+fi
+
+gen_checks="$(jq '[.[].statusCheckRollup | length] | unique | .[0]' "$FIXTURE")"
+if [[ "$gen_checks" -eq "$CHECKS_PER_PR" ]]; then
+  pass "every PR row carries $gen_checks check runs (want $CHECKS_PER_PR)"
+else
+  fail "check-run cardinality is $gen_checks (want $CHECKS_PER_PR) -- fixture is not production-shaped"
+fi
+
+# --- FIXTURE ADEQUACY: the payload must actually exceed the ceiling ----------------------
+# Asserted IN-SUITE, not demonstrated in a PR body: a PR-body demonstration is unrunnable
+# after merge, because there is no pre-fix code left to run it against.
+fixture_bytes="$(wc -c < "$FIXTURE")"
+if [[ "$fixture_bytes" -gt "$MAX_ARG_STRLEN" ]]; then
+  pass "fixture is ${fixture_bytes} B > MAX_ARG_STRLEN (${MAX_ARG_STRLEN})"
+else
+  fail "fixture is only ${fixture_bytes} B -- below MAX_ARG_STRLEN (${MAX_ARG_STRLEN}), this test proves nothing"
+fi
+
+# The collapse must stay FAR under the ceiling: this is what makes `--argjson prs
+# "$CLASSIFIED"` safe, and it is the reason that binding is deliberately NOT converted.
+# If the projection ever starts carrying statusCheckRollup through, this catches it.
+#
+# TWO-SIDED on purpose. `-lt MAX_ARG_STRLEN` alone passes when the collapse is 0 B --
+# which is exactly what a crashed script produces, so a one-sided bound would report
+# PASS on the very mutation this suite exists to catch. The lower bound makes "the
+# script produced nothing" a FAILURE rather than a suspiciously good result.
+classified_bytes="$(bash "$TARGET" --fixture "$FIXTURE" --format json 2>/dev/null | jq -c '[.[][]]' | wc -c)"
+if [[ "$classified_bytes" -gt 1000 && "$classified_bytes" -lt "$MAX_ARG_STRLEN" ]]; then
+  pass "\$CLASSIFIED collapse is ${classified_bytes} B (>1000, < MAX_ARG_STRLEN ${MAX_ARG_STRLEN})"
+elif [[ "$classified_bytes" -le 1000 ]]; then
+  fail "\$CLASSIFIED is only ${classified_bytes} B for $PR_ROWS PRs -- the script produced (almost) nothing; this bound is vacuous"
+else
+  fail "\$CLASSIFIED is ${classified_bytes} B -- the projection no longer collapses; --argjson prs is now unsafe"
+fi
+
+# --- Behavioural: the script survives a >ceiling PR_JSON --------------------------------
+# This is the assertion that goes RED when the herestring becomes --argjson: jq dies with
+# E2BIG ("Argument list too long") and the command substitution yields a non-zero exit.
+out="$(bash "$TARGET" --fixture "$FIXTURE" --format json 2>"$WORK/err.txt")"
+rc=$?
+if [[ "$rc" -eq 0 ]]; then
+  pass ">MAX_ARG_STRLEN fixture exits 0 (pre-fix this dies 'Argument list too long')"
+else
+  fail ">MAX_ARG_STRLEN fixture exit=$rc -- stderr: $(head -c 200 "$WORK/err.txt")"
+fi
+
+# E2BIG must not be reachable even as a swallowed diagnostic.
+if grep -qiE 'argument list too long' "$WORK/err.txt"; then
+  fail "stderr carries an E2BIG diagnostic -- argv ceiling was hit"
+else
+  pass "no 'Argument list too long' diagnostic on stderr"
+fi
+
+# --- Completeness: every synthesized PR must survive classification ----------------------
+# Guards the silent-truncation failure mode, which an exit-code-only assertion misses: a
+# partial read that classified 12 of 40 PRs would still exit 0.
+classified_count="$(printf '%s' "$out" | jq '[.[][]] | length')"
+if [[ "$classified_count" -eq "$gen_rows" ]]; then
+  pass "all $classified_count PRs classified (== $gen_rows source rows, no truncation)"
+else
+  fail "classified $classified_count PRs but fixture had $gen_rows -- truncation/undercount"
+fi
+
+# The tier field must be really populated, not empty shells at >ceiling size.
+tiered="$(printf '%s' "$out" | jq '[.[][] | select(.tier != null and .number != null)] | length')"
+if [[ "$tiered" -eq "$gen_rows" ]]; then
+  pass "all $tiered rows carry a tier + number at >ceiling size"
+else
+  fail "only $tiered of $gen_rows rows carry tier+number"
+fi
+
+# --- Structural: the herestring must not have become an --argjson binding ----------------
+# Anchored on the ASSIGNMENT LINE, not a bare token. `--argjson` legitimately appears in
+# this script (`--argjson prs`, `--argjson order`) and `PR_JSON` now appears in the
+# load-bearing comment block, so a bare grep for either would false-pass on prose.
+if grep -qE '^CLASSIFIED="\$\(jq ' "$TARGET"; then
+  pass "CLASSIFIED is still assigned from a jq invocation"
+else
+  fail "CLASSIFIED assignment shape changed -- re-verify the herestring invariant by hand"
+fi
+
+# Comments start with '#', so a match on a line that both ENDS the jq program and applies
+# the herestring cannot be produced by the comment block above it.
+if grep -qE "^[[:space:]]*\]'[[:space:]]*<<<\"\\\$PR_JSON\"\\)\"$" "$TARGET"; then
+  pass "PR_JSON is applied via a <<< herestring (no argv binding)"
+else
+  fail "the <<<\"\$PR_JSON\" herestring is gone -- if it became --argjson, PR_JSON (392,170 B at 20 PRs) now exceeds MAX_ARG_STRLEN ($MAX_ARG_STRLEN)"
+fi
+
+# Directly forbid the mutation this suite exists to catch, on a CODE line only.
+# `grep -c` (not `producer | grep -q`): under `set -o pipefail` an early match closes the
+# pipe, the producer takes SIGPIPE (141) and the pipeline fails even though grep MATCHED.
+argjson_prjson="$(grep -cE '^[^#]*--argjson[[:space:]]+[a-z_]+[[:space:]]+"\$PR_JSON"' "$TARGET")"
+if [[ "$argjson_prjson" -eq 0 ]]; then
+  pass "no --argjson binding of \$PR_JSON on any code line"
+else
+  fail "\$PR_JSON is bound via --argjson on $argjson_prjson code line(s) -- exceeds MAX_ARG_STRLEN ($MAX_ARG_STRLEN) on every real run"
+fi
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[[ "$FAIL" -eq 0 ]]