@plot-pm/board 0.18.0 → 0.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/plot-host.sh CHANGED
@@ -66,9 +66,17 @@
66
66
  # EXIT 3 is the question failing, and it is not
67
67
  # the same as an empty answer: a diff that could
68
68
  # not be read is not a diff that was empty.
69
+ # pr-merged-heads <branch> the head commit of every MERGED PR for this
70
+ # branch, one sha per line, or EMPTY (exit 0)
71
+ # where none merged. Reads `mergedAt`, never
72
+ # `state`. EXIT 3 is the question failing,
73
+ # including a CLI that fails without a word: an
74
+ # empty answer sends the reaper to a weaker
75
+ # reading, so only a recognised lookup miss is
76
+ # empty.
69
77
  # pr-create --title T [--body B] [--base BR] [--head BR] [--draft]
70
78
  # create a PR, print its URL
71
- # pr-merge <number> [--squash] [--delete-branch]
79
+ # pr-merge <number> [--squash] [--delete-branch] [--match-head <sha>]
72
80
  # pr-ready <number> take a PR out of draft
73
81
  # merge the PR
74
82
  # pr-list [--state open|merged|closed|all] [--limit N] [--rich|--rich-open]
@@ -448,6 +456,17 @@ die() { echo "plot-host: $*" >&2; exit 1; }
448
456
  # error a person must fix, not a transient the board should retry past.
449
457
  die3() { echo "plot-host: $*" >&2; exit 3; }
450
458
 
459
+ # THE ONE FOLD of a PR's check rollup into a word. `pr-list` and `pr-state` both
460
+ # read it, so what `green` means cannot differ between a listing and a merge.
461
+ # An allow-list: `ck` reads `ok` only for a finished item with an accepted
462
+ # result, `wait` for an unfinished one, and `bad` for every other word.
463
+ CHECKS_OF='def ck: (.conclusion // "") as $k | (.status // "") as $s | (if $s != "" then $s else (.state // "") end) as $w |
464
+ if $k != "" and ($s|IN("","COMPLETED")) then (if ($k|IN("SUCCESS","NEUTRAL","SKIPPED")) then "ok" else "bad" end)
465
+ elif ($w|IN("","QUEUED","IN_PROGRESS","WAITING","REQUESTED","PENDING","EXPECTED")) then "wait"
466
+ elif $s == "" and $w == "SUCCESS" then "ok" else "bad" end;
467
+ def checks_of: if (.statusCheckRollup|length) == 0 then "none" elif any(.statusCheckRollup[]; ck == "bad") then "failing"
468
+ elif any(.statusCheckRollup[]; ck == "wait") then "pending" else "green" end;'
469
+
451
470
  # Exit 5 — the host refused to answer FOR NOW. A rate limit, primary or
452
471
  # secondary: nothing is broken, nothing needs fixing, and the same question
453
472
  # asked later will be answered.
@@ -1657,6 +1676,74 @@ jenkins_job_url_path() { # $1 = job path, $2 = branch or ""
1657
1676
  printf '%s' "$out"
1658
1677
  }
1659
1678
 
1679
+ # Every Jenkins build of one job that built ONE sha, as a JSON array (newest
1680
+ # first), or exit 3 (no instance) / exit 4 (cannot be asked). Shared by
1681
+ # `run-for-sha` and `runs-for-sha`, so the instance, the credential and the
1682
+ # multibranch-then-plain URL fallback are written once.
1683
+ #
1684
+ # $1 = the op's name, $2 = branch, $3 = how many builds to list, $4 = the sha.
1685
+ # Run it in `$(...)` and read the exit code with `|| exit $?`: it exits rather
1686
+ # than returns, and a subshell's exit is the code the caller sees.
1687
+ #
1688
+ # THE SHA IS IN JENKINS AND `jen` IS NOT THE TRANSPORT. Measured 2026-09-10: a
1689
+ # `jen build list --json` entry carries no sha, so Jenkins' REST API answers it
1690
+ # at `actions[].lastBuiltRevision.SHA1`. One `tree=` query returns a whole
1691
+ # history, so this costs one round trip like the GitHub arm.
1692
+ #
1693
+ # A BRANCH IS A JOB SEGMENT ON A MULTIBRANCH JOB AND NOT ON A PLAIN ONE, and no
1694
+ # reading of the configured path says which this is. The multibranch URL is
1695
+ # tried first and the plain one is the fallback (measured 2026-09-11: asking
1696
+ # the plain job for a branch segment answers 404). THE PLAIN JOB REPORTS ITS
1697
+ # OWN BUILDS whatever branch was asked about; the `sha` says which it built.
1698
+ #
1699
+ # NO CREDENTIAL IS *CANNOT BE ASKED*, never *no run*: the keychain is macOS-only
1700
+ # and a Linux agent legitimately has none. AN UNREACHABLE INSTANCE IS NOT AN
1701
+ # EMPTY HISTORY: a refused or redirected request answers HTML, which fails the
1702
+ # `builds` test.
1703
+ #
1704
+ # ONLY THE ASKED-FOR SHA, never another build's. `result` is null while a build
1705
+ # runs, Jenkins' own word for *in flight*, mapped to the `status`/`conclusion`
1706
+ # split the contract already uses so the shape does not fork per connector.
1707
+ jenkins_sha_runs() {
1708
+ local op="$1" branch="$2" limit="$3" sha="$4" instance host job cred tree body try path
1709
+ instance="$(jenkins_instance)"
1710
+ [ -n "$instance" ] || jenkins_no_instance
1711
+ host="${instance%%/*}"
1712
+ job="${instance#*/}"
1713
+ [ "$job" = "$instance" ] && job=""
1714
+ [ -n "${PLOT_JENKINS_JOB:-}" ] && job="$PLOT_JENKINS_JOB"
1715
+ if [ -z "$job" ]; then
1716
+ echo "plot-host: $op — the Jenkins instance names no job path; a sha lives in a job's builds, so it must be <slug>/<job/path>, not a bare host" >&2
1717
+ exit 4
1718
+ fi
1719
+ cred="$(jenkins_rest_credential "$host")" || {
1720
+ echo "plot-host: $op — no Jenkins API credential for '$host'" >&2
1721
+ echo " Jenkins' REST API takes basic auth with an API token, which \`jen auth login\` stores in the login keychain. The Keycloak bearer from \`jen auth token\` is NOT it." >&2
1722
+ exit 4
1723
+ }
1724
+ tree="tree=builds%5Bnumber,result,building,timestamp,url,actions%5BlastBuiltRevision%5BSHA1%5D%5D%5D%7B0,$limit%7D"
1725
+ body=""
1726
+ for path in "$(jenkins_job_url_path "$job" "$branch")" "$(jenkins_job_url_path "$job" "")"; do
1727
+ host_slot_take jenkins ''
1728
+ try=$(curl -sg --max-time 30 -u "$cred" "https://$host$path/api/json?$tree" 2>/dev/null) || true
1729
+ host_slot_give; budget_record_call jenkins ''
1730
+ if printf '%s' "$try" | jq -e 'has("builds")' >/dev/null 2>&1; then body="$try"; break; fi
1731
+ done
1732
+ cred=""
1733
+ if [ -z "$body" ]; then
1734
+ echo "plot-host: $op — Jenkins did not answer for '$host'" >&2
1735
+ exit 4
1736
+ fi
1737
+ printf '%s' "$body" | jq -c --arg sha "$sha" '
1738
+ [ .builds[]
1739
+ | { sha: ([ .actions[]? | select(.lastBuiltRevision) | .lastBuiltRevision.SHA1 ] | first // ""),
1740
+ status: (if .building then "in_progress" else "completed" end),
1741
+ conclusion: (if .building then null else (.result // null) end),
1742
+ url: (.url // ""),
1743
+ startedAt: (if .timestamp then (.timestamp / 1000 | todate) else "" end) } ]
1744
+ | map(select(.sha == $sha))' || exit 4
1745
+ }
1746
+
1660
1747
  ci_unaskable() { # $1 = the op's name, $2 = the CI word (may be empty)
1661
1748
  local ci_word="${2:-}"
1662
1749
  if [ -z "$ci_word" ] || [ "$ci_word" = none ]; then
@@ -1993,7 +2080,7 @@ rest_pr_to_state() {
1993
2080
  state: $state,
1994
2081
  draft: (.draft // false),
1995
2082
  url: (.html_url // ""),
1996
- mergeCommit: (.merge_commit_sha // "") }
2083
+ mergeCommit: (.merge_commit_sha // ""), headSha: (.head.sha // ""), checks: "unknown" }
1997
2084
  '
1998
2085
  }
1999
2086
 
@@ -3485,9 +3572,9 @@ case "$op" in
3485
3572
  # mergeCommit is what lets a caller ask "which release contains this?" —
3486
3573
  # `git tag --contains <sha>` answers exactly, where dates cannot. It is ""
3487
3574
  # for anything unmerged, which is the honest answer rather than a guess.
3488
- elif out="$(gh ${repo_args[@]+"${repo_args[@]}"} pr view "$ref" --json number,state,isDraft,url,mergeCommit 2>"$HOST_ERR")"; then
3575
+ elif out="$(gh ${repo_args[@]+"${repo_args[@]}"} pr view "$ref" --json number,state,isDraft,url,mergeCommit,headRefOid,statusCheckRollup 2>"$HOST_ERR")"; then
3489
3576
  rm -f "$HOST_ERR"
3490
- jq -c '{number:.number,state:.state,draft:.isDraft,url:.url,mergeCommit:(.mergeCommit.oid // "")}' <<<"$out"
3577
+ jq -c "$CHECKS_OF"'{number:.number,state:.state,draft:.isDraft,url:.url,mergeCommit:(.mergeCommit.oid // ""),headSha:(.headRefOid // ""),checks:checks_of,checksSha:(.headRefOid // "")}' <<<"$out"
3491
3578
  else
3492
3579
  err="$(cat "$HOST_ERR" 2>/dev/null)"; rm -f "$HOST_ERR"
3493
3580
  # REFUSED FOR RATE IS NOT ANSWERED. The budget gate above could not see
@@ -3723,6 +3810,56 @@ case "$op" in
3723
3810
  fi
3724
3811
  ;;
3725
3812
 
3813
+ pr-merged-heads)
3814
+ # THE HEAD COMMIT OF EVERY MERGED PR FOR A BRANCH, one sha per line.
3815
+ # `plot-reap.mjs` asks it only for a branch already known merged, to tell a
3816
+ # pushed commit from one made after the merge once the remote ref is gone.
3817
+ #
3818
+ # `--state all` and `--limit 100` for `pr-merged`'s own two reasons: a
3819
+ # merged PR reports CLOSED, and the newest PR is not the merge.
3820
+ #
3821
+ # A FAILURE WITH NO MESSAGE IS A FAILURE HERE, unlike `pr-state`: an empty
3822
+ # answer makes the caller fall back to a patch-id reading, so silence must
3823
+ # not stand in for *no merged head*. Only a recognised lookup miss is empty.
3824
+ ref="${1:?pr-merged-heads needs a branch}"; shift || true
3825
+ repo_args=()
3826
+ while [ $# -gt 0 ]; do
3827
+ case "$1" in
3828
+ --repo) repo_args=(-R "${2:?}"); shift 2 ;;
3829
+ *) die "pr-merged-heads: unknown arg $1" ;;
3830
+ esac
3831
+ done
3832
+ if [ "$be" = "github" ]; then
3833
+ if out="$(gh ${repo_args[@]+"${repo_args[@]}"} pr list --head "$ref" --state all --limit 100 --json mergedAt,headRefOid 2>"$HOST_ERR")"; then
3834
+ rm -f "$HOST_ERR"
3835
+ jq -r '.[] | select(.mergedAt != null and .headRefOid != null) | .headRefOid' <<<"$out" || exit 3
3836
+ else
3837
+ err="$(cat "$HOST_ERR" 2>/dev/null)"; rm -f "$HOST_ERR"
3838
+ if [ -n "$err" ] && is_lookup_miss "$err"; then
3839
+ :
3840
+ else
3841
+ echo "plot-host: ${err:-gh pr list failed}" >&2
3842
+ exit 3
3843
+ fi
3844
+ fi
3845
+ else
3846
+ bb_require_json
3847
+ # Bitbucket names the merged head `source.commit.hash`.
3848
+ if out="$(bb ${repo_args[@]+"${repo_args[@]}"} pr list --state merged --json 2>"$HOST_ERR")"; then
3849
+ rm -f "$HOST_ERR"
3850
+ jq -r --arg b "$ref" '.[] | select(.source.branch.name==$b) | (.source.commit.hash // empty)' <<<"$out" || exit 3
3851
+ else
3852
+ err="$(cat "$HOST_ERR" 2>/dev/null)"; rm -f "$HOST_ERR"
3853
+ if [ -n "$err" ] && is_lookup_miss "$err"; then
3854
+ :
3855
+ else
3856
+ echo "plot-host: ${err:-bb pr list failed}" >&2
3857
+ exit 3
3858
+ fi
3859
+ fi
3860
+ fi
3861
+ ;;
3862
+
3726
3863
  pr-create)
3727
3864
  title=""; body=""; base=""; head=""; draft=0
3728
3865
  while [ $# -gt 0 ]; do
@@ -3753,11 +3890,12 @@ case "$op" in
3753
3890
 
3754
3891
  pr-merge)
3755
3892
  num="${1:?pr-merge needs a PR number}"; shift
3756
- squash=0; delbranch=0
3893
+ squash=0; delbranch=0; pin=""
3757
3894
  while [ $# -gt 0 ]; do
3758
3895
  case "$1" in
3759
3896
  --squash) squash=1; shift ;;
3760
3897
  --delete-branch) delbranch=1; shift ;;
3898
+ --match-head) pin="${2:?pr-merge --match-head needs a commit}"; shift 2 ;;
3761
3899
  *) die "pr-merge: unknown arg $1" ;;
3762
3900
  esac
3763
3901
  done
@@ -3765,7 +3903,9 @@ case "$op" in
3765
3903
  args=(pr merge "$num")
3766
3904
  [ "$squash" = 1 ] && args+=(--squash) || args+=(--merge)
3767
3905
  [ "$delbranch" = 1 ] && args+=(--delete-branch)
3906
+ [ -n "$pin" ] && args+=(--match-head-commit "$pin")
3768
3907
  gh "${args[@]}"
3908
+ elif [ -n "$pin" ]; then echo "plot-host: pr-merge --match-head: bitbucket cannot pin a merge to a commit; nothing was merged" >&2; exit 4
3769
3909
  else
3770
3910
  args=(pr merge "$num")
3771
3911
  [ "$squash" = 1 ] && args+=(--squash)
@@ -4035,6 +4175,11 @@ case "$op" in
4035
4175
  # GitHub's statusCheckRollup. Done-when 3 verifies this is orthogonal:
4036
4176
  # a GitHub repo without Jenkins still reads its own rollup exactly as
4037
4177
  # before.
4178
+ # COMMIT FIELDS PER ARM. `headSha` is `headRefOid` on all three GitHub
4179
+ # arms. `checksSha` is emitted ONLY by the rollup arm: `statusCheckRollup`
4180
+ # belongs to the head commit, so it equals `headSha`. The Jenkins colours
4181
+ # are per branch and carry no commit, and the plain arm reads no checks,
4182
+ # so neither emits `checksSha`. `mergedAt` is the host's, `""` on an open PR.
4038
4183
  if [ "$ci" = "jenkins" ]; then
4039
4184
  # GitHub PR list, but `checks` comes from Jenkins, joined on branch
4040
4185
  # name. `statusCheckRollup` is NOT even requested — the GitHub rollup
@@ -4044,7 +4189,7 @@ case "$op" in
4044
4189
  # $jentry == null → the branch has no Jenkins job; `none`.
4045
4190
  # otherwise → the joined colour's `checks`, job named on fail.
4046
4191
  _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} \
4047
- --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author)" || exit $?
4192
+ --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4048
4193
  pr_list_report_truncation github "$limit" "$state" \
4049
4194
  "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4050
4195
  printf '%s' "$_gh_raw" \
@@ -4064,7 +4209,7 @@ case "$op" in
4064
4209
  else "unknown" end),
4065
4210
  review:(.reviewDecision // ""),
4066
4211
  url:.url,
4067
- updatedAt:(.updatedAt // ""),
4212
+ updatedAt:(.updatedAt // ""),headSha:(.headRefOid // ""),mergedAt:(.mergedAt // ""),
4068
4213
  author:(.author.login // ""),
4069
4214
  failing_checks:(
4070
4215
  if $jentry != null and $jentry.checks == "failing"
@@ -4075,35 +4220,24 @@ case "$op" in
4075
4220
  else
4076
4221
  # GitHub without Jenkins (or Jenkins not configured): use GitHub rollup
4077
4222
  _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} \
4078
- --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author)" || exit $?
4223
+ --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4079
4224
  pr_list_report_truncation github "$limit" "$state" \
4080
4225
  "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4081
4226
  printf '%s' "$_gh_raw" \
4082
- | jq -c '.[] | {
4227
+ | jq -c "$CHECKS_OF"'.[] | {
4083
4228
  number:.number, title:.title, state:.state, head:.headRefName,
4084
4229
  draft:.isDraft,
4085
- checks:(
4086
- if (.statusCheckRollup|length) == 0 then "none"
4087
- elif any(.statusCheckRollup[]; (if (.conclusion // "") != "" then .conclusion else (.status // .state) end) as $c
4088
- | $c=="FAILURE" or $c=="ERROR" or $c=="CANCELLED"
4089
- or $c=="TIMED_OUT" or $c=="ACTION_REQUIRED") then "failing"
4090
- elif any(.statusCheckRollup[]; (if (.conclusion // "") != "" then .conclusion else (.status // .state) end) as $c
4091
- | $c=="PENDING" or $c=="IN_PROGRESS" or $c=="QUEUED"
4092
- or $c=="WAITING" or $c==null) then "pending"
4093
- else "green" end),
4230
+ checks:checks_of,
4094
4231
  mergeable:(
4095
4232
  if .mergeable=="CONFLICTING" or .mergeStateStatus=="DIRTY" then "conflicting"
4096
4233
  elif .mergeable=="MERGEABLE" then "mergeable"
4097
4234
  else "unknown" end),
4098
4235
  review:(.reviewDecision // ""),
4099
4236
  url:.url,
4100
- updatedAt:(.updatedAt // ""),
4237
+ updatedAt:(.updatedAt // ""),headSha:(.headRefOid // ""),checksSha:(.headRefOid // ""),mergedAt:(.mergedAt // ""),
4101
4238
  author:(.author.login // ""),
4102
4239
  failing_checks:[
4103
- .statusCheckRollup[]? | select((if (.conclusion // "") != "" then .conclusion else (.status // .state) end) as $c
4104
- | $c=="FAILURE" or $c=="ERROR" or $c=="CANCELLED"
4105
- or $c=="TIMED_OUT" or $c=="ACTION_REQUIRED")
4106
- | (.name // .context // "")] | map(select(. != ""))
4240
+ .statusCheckRollup[]? | select(ck == "bad") | (.name // .context // "")] | map(select(. != ""))
4107
4241
  }'
4108
4242
  fi
4109
4243
  else
@@ -4121,13 +4255,17 @@ case "$op" in
4121
4255
  # the store unable to narrow and the daily full read would never fall
4122
4256
  # due against anything but a cold window.
4123
4257
  _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} \
4124
- --json number,title,state,headRefName,isDraft,url,updatedAt,author)" || exit $?
4258
+ --json number,title,state,headRefName,isDraft,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4125
4259
  pr_list_report_truncation github "$limit" "$state" \
4126
4260
  "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4127
4261
  printf '%s' "$_gh_raw" \
4128
- | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,draft:.isDraft,url:.url,updatedAt:(.updatedAt // ""),author:(.author.login // "")}'
4262
+ | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,draft:.isDraft,url:.url,updatedAt:(.updatedAt // ""),headSha:(.headRefOid // ""),mergedAt:(.mergedAt // ""),author:(.author.login // "")}'
4129
4263
  fi
4130
4264
  else
4265
+ # `headSha` IS `.source.commit.hash`, which the pullrequests endpoint
4266
+ # carries. The endpoint has no `merged_on`, so `mergedAt` is `.updated_on`
4267
+ # of a MERGED PR only; `checksSha` is absent, as `bb` reads no checks.
4268
+ #
4131
4269
  # `author` IS THE `nickname`, the one handle field a Bitbucket user
4132
4270
  # object carries. Measured 2026-09-25 against bb 1.9.0: `author` holds
4133
4271
  # `display_name`, `nickname`, `account_id` and `uuid` and no username,
@@ -4220,7 +4358,7 @@ case "$op" in
4220
4358
  mergeable:"unknown",
4221
4359
  review:"",
4222
4360
  url:(.links.html.href // ""),
4223
- updatedAt:(.updated_on // ""),
4361
+ updatedAt:(.updated_on // ""),headSha:(.source.commit.hash // ""),mergedAt:(if .state=="MERGED" then (.updated_on // "") else "" end),
4224
4362
  author:(.author.nickname // ""),
4225
4363
  failing_checks:(
4226
4364
  if $jentry != null and $jentry.checks == "failing"
@@ -4232,7 +4370,7 @@ case "$op" in
4232
4370
  # Bitbucket without Jenkins: checks remain unknown
4233
4371
  PR_LIST_JQ_ARGS=()
4234
4372
  pr_list_states bitbucket "$limit" "$bb_states" \
4235
- '.[] | {number:.id,title:.title,state:(if .state=="DECLINED" then "CLOSED" else .state end),head:.source.branch.name,draft:(.draft // false),checks:"unknown",mergeable:"unknown",review:"",url:(.links.html.href // ""),updatedAt:(.updated_on // ""),author:(.author.nickname // ""),failing_checks:[]}' \
4373
+ '.[] | {number:.id,title:.title,state:(if .state=="DECLINED" then "CLOSED" else .state end),head:.source.branch.name,draft:(.draft // false),checks:"unknown",mergeable:"unknown",review:"",url:(.links.html.href // ""),updatedAt:(.updated_on // ""),headSha:(.source.commit.hash // ""),mergedAt:(if .state=="MERGED" then (.updated_on // "") else "" end),author:(.author.nickname // ""),failing_checks:[]}' \
4236
4374
  "${bb_cmd[@]}" || exit $?
4237
4375
  fi
4238
4376
  else
@@ -4335,8 +4473,16 @@ case "$op" in
4335
4473
  esac
4336
4474
  ;;
4337
4475
 
4338
- run-for-sha)
4339
- # The run for ONE sha, or nothing — the BuildMonitor's only host question.
4476
+ run-for-sha|runs-for-sha)
4477
+ # `runs-for-sha` is this op's plural: EVERY run for the sha as a JSON array
4478
+ # (`[]` is an answer, exit 4 is *cannot be asked*), from ONE listing call and
4479
+ # no per-run `gh run view`. The default branch needs it because `main` runs
4480
+ # several workflows per commit and the first match alone would let a green
4481
+ # first run hide a red second one. Facts only: `status` and `conclusion` as
4482
+ # the host gives them, Jenkins' words included.
4483
+ #
4484
+ # The singular, below, is the BuildMonitor's only host question.
4485
+ #
4340
4486
  #
4341
4487
  # WHY THIS IS NOT `runs`. `runs` is branch-scoped and reports no sha at all,
4342
4488
  # so a caller cannot tell which commit an answer is about. `gh run list
@@ -4366,8 +4512,8 @@ case "$op" in
4366
4512
  # A Bitbucket remote exits 4 (`bb` has no run listing), as does a failing
4367
4513
  # `gh` or Jenkins that cannot be asked: exit 4 reads as unavailable, never
4368
4514
  # as "this sha has no build".
4369
- branch="${1:?run-for-sha needs a branch}"; shift
4370
- sha="${1:?run-for-sha needs a sha}"; shift
4515
+ branch="${1:?$op needs a branch}"; shift
4516
+ sha="${1:?$op needs a sha}"; shift
4371
4517
  # Enough runs to find the sha among its neighbours. A branch accumulates
4372
4518
  # runs per push and per workflow, so the sha being asked about can sit
4373
4519
  # several entries down even when it is the current head.
@@ -4375,7 +4521,7 @@ case "$op" in
4375
4521
  while [ $# -gt 0 ]; do
4376
4522
  case "$1" in
4377
4523
  --limit) limit="${2:?}"; shift 2 ;;
4378
- *) die "run-for-sha: unknown arg $1" ;;
4524
+ *) die "$op: unknown arg $1" ;;
4379
4525
  esac
4380
4526
  done
4381
4527
  # DISPATCHED ON THE CI SYSTEM, for the reason `runs` above states: the git
@@ -4396,80 +4542,11 @@ case "$op" in
4396
4542
  #
4397
4543
  # THIS ARM EXITED 4 UNTIL 2026-09-11, and the refusal was honest for
4398
4544
  # the transport it had. What changed is the transport, not the rule.
4399
- _jen_instance="$(jenkins_instance)"
4400
- [ -n "$_jen_instance" ] || jenkins_no_instance
4401
- _jen_host="${_jen_instance%%/*}"
4402
- _jen_job="${_jen_instance#*/}"
4403
- [ "$_jen_job" = "$_jen_instance" ] && _jen_job=""
4404
- [ -n "${PLOT_JENKINS_JOB:-}" ] && _jen_job="$PLOT_JENKINS_JOB"
4405
- if [ -z "$_jen_job" ]; then
4406
- # A bare-host instance names no job, and a sha lives in a job's
4407
- # builds. `runs` degrades to an empty map here; this op has no row to
4408
- # carry that, so the only way to say *cannot be asked* is exit 4.
4409
- echo "plot-host: run-for-sha — the Jenkins instance names no job path" >&2
4410
- echo " A sha is a fact about a job's builds, so the instance must be" >&2
4411
- echo " <slug>/<job/path> rather than a bare host." >&2
4412
- exit 4
4413
- fi
4414
- _jen_cred="$(jenkins_rest_credential "$_jen_host")" || {
4415
- # NO CREDENTIAL IS *CANNOT BE ASKED*, never *no run*. The keychain is
4416
- # macOS-only and a Linux agent legitimately has none; saying nothing
4417
- # at exit 0 would read as a branch that never built.
4418
- echo "plot-host: run-for-sha — no Jenkins API credential for '$_jen_host'" >&2
4419
- echo " Jenkins' REST API takes basic auth with an API token, which" >&2
4420
- echo " \`jen auth login\` stores in the login keychain. The Keycloak" >&2
4421
- echo " bearer from \`jen auth token\` is NOT it — Jenkins answers that" >&2
4422
- echo " with a login redirect." >&2
4423
- exit 4
4424
- }
4425
- # A BRANCH IS A JOB SEGMENT ON A MULTIBRANCH JOB AND NOT ON A PLAIN
4426
- # ONE, and no reading of the configured path says which this is. So the
4427
- # multibranch URL is tried first and the plain one is the fallback:
4428
- # `job/quaweb/job/continuous-build/job/content%2Fctas` against
4429
- # `job/quaweb/job/release`. Measured 2026-09-11 — asking the plain job
4430
- # for a branch segment answers 404, which is why guessing one shape
4431
- # cost a run.
4432
- #
4433
- # THE PLAIN JOB REPORTS ITS OWN BUILDS whatever branch was asked about,
4434
- # and that is honest rather than wrong: a pipeline job builds one
4435
- # thing, and the `sha` in the answer says which commit it built.
4436
- _jen_tree="tree=builds%5Bnumber,result,building,timestamp,url,actions%5BlastBuiltRevision%5BSHA1%5D%5D%5D%7B0,$limit%7D"
4437
- _jen_body=""
4438
- for _jen_path in \
4439
- "$(jenkins_job_url_path "$_jen_job" "$branch")" \
4440
- "$(jenkins_job_url_path "$_jen_job" "")"; do
4441
- host_slot_take jenkins ''
4442
- _jen_try=$(curl -sg --max-time 30 -u "$_jen_cred" \
4443
- "https://$_jen_host$_jen_path/api/json?$_jen_tree" 2>/dev/null) || true
4444
- host_slot_give
4445
- budget_record_call jenkins ''
4446
- if printf '%s' "$_jen_try" | jq -e 'has("builds")' >/dev/null 2>&1; then
4447
- _jen_body="$_jen_try"; break
4448
- fi
4449
- done
4450
- _jen_cred=""
4451
- if [ -z "$_jen_body" ] || ! printf '%s' "$_jen_body" | jq -e 'has("builds")' >/dev/null 2>&1; then
4452
- # AN UNREACHABLE INSTANCE IS NOT AN EMPTY HISTORY. A refused or
4453
- # redirected request answers HTML, which fails the `builds` test.
4454
- echo "plot-host: run-for-sha — Jenkins did not answer for '$_jen_host'" >&2
4455
- exit 4
4456
- fi
4457
- # THE SAME MATCH RULE AS THE GITHUB ARM: only the asked-for sha, never
4458
- # another build's. A build for any other commit is not evidence about
4459
- # this one, so no match means no output.
4460
- #
4461
- # `result` is null while a build runs, which is Jenkins' own word for
4462
- # *in flight* — mapped to the `status`/`conclusion` split the contract
4463
- # already uses, so the shape does not fork per connector.
4464
- printf '%s' "$_jen_body" | jq -c --arg sha "$sha" '
4465
- [ .builds[]
4466
- | { sha: ([ .actions[]? | select(.lastBuiltRevision) | .lastBuiltRevision.SHA1 ] | first // ""),
4467
- status: (if .building then "in_progress" else "completed" end),
4468
- conclusion: (if .building then null else (.result // null) end),
4469
- url: (.url // ""),
4470
- startedAt: (if .timestamp then (.timestamp / 1000 | todate) else "" end) } ]
4471
- | (map(select(.sha == $sha)) | .[0])
4472
- | select(. != null)' 2>/dev/null || true
4545
+ # The fetch, credential and match rule live in `jenkins_sha_runs`, which
4546
+ # `runs-for-sha` shares. `|| exit $?` keeps exit 3 (no instance) apart
4547
+ # from exit 4 (cannot be asked).
4548
+ _jen_all=$(jenkins_sha_runs "$op" "$branch" "$limit" "$sha") || exit $?
4549
+ if [ "$op" = runs-for-sha ]; then printf '%s' "$_jen_all"; else printf '%s' "$_jen_all" | jq -c '.[0] // empty' 2>/dev/null || true; fi
4473
4550
  # THIS ARM ANSWERS AND THE OP IS OVER. Everything below the `esac` is
4474
4551
  # the GitHub path — the old jenkins arm reached it only because it
4475
4552
  # ended in `exit 4`. Measured 2026-09-11: without this the answer was
@@ -4478,13 +4555,13 @@ case "$op" in
4478
4555
  exit 0
4479
4556
  ;;
4480
4557
  github-actions) : ;;
4481
- *) ci_unaskable run-for-sha "$_ci" ;;
4558
+ *) ci_unaskable "$op" "$_ci" ;;
4482
4559
  esac
4483
4560
  if [ "$be" != "github" ]; then
4484
4561
  # SAME SECOND CONDITION AS `runs`: `gh run list` reads the repository its
4485
4562
  # remote names, so `CI: github-actions` on a non-GitHub remote names runs
4486
4563
  # that cannot be reached from here.
4487
- echo "plot-host: run-for-sha — CI is github-actions but the git host is '$be'" >&2
4564
+ echo "plot-host: $op — CI is github-actions but the git host is '$be'" >&2
4488
4565
  echo " \`gh run list\` reads the runs of the repository its remote names," >&2
4489
4566
  echo " so there is no GitHub repository here to ask about." >&2
4490
4567
  exit 4
@@ -4509,8 +4586,15 @@ case "$op" in
4509
4586
  # a network failure exits 4 here, the way the Jenkins arm does, so the
4510
4587
  # monitor reads *could not ask* and not *no run yet*.
4511
4588
  _gh_runs=$(gh run list --branch "$branch" --limit "$limit" \
4512
- --json headSha,conclusion,status,startedAt,url,databaseId 2>/dev/null) \
4513
- || { echo "plot-host: run-for-sha — gh run list failed for '$branch'" >&2; exit 4; }
4589
+ --json headSha,conclusion,status,startedAt,url,databaseId,workflowName 2>/dev/null) \
4590
+ || { echo "plot-host: $op — gh run list failed for '$branch'" >&2; exit 4; }
4591
+ if [ "$op" = runs-for-sha ]; then
4592
+ printf '%s' "$_gh_runs" | jq -c --arg sha "$sha" '[.[] | select(.headSha == $sha)
4593
+ | {sha:.headSha, workflow:(.workflowName // ""), status:.status,
4594
+ conclusion:(if (.conclusion // "") == "" then null else .conclusion end),
4595
+ url:.url, startedAt:.startedAt}]' || exit 4
4596
+ exit 0
4597
+ fi
4514
4598
  _gh_match=$(printf '%s' "$_gh_runs" | jq -c --arg sha "$sha" \
4515
4599
  '(map(select(.headSha == $sha)) | .[0]) | select(. != null)
4516
4600
  | {sha:.headSha, status:.status,
package/plot-plan-meta.sh CHANGED
@@ -173,6 +173,10 @@
173
173
  # are a plan's evidence, and plot-host.sh resolves where each
174
174
  # one lives. An absent PR contributes nothing — not "", not 0 —
175
175
  # the same rule `Issue:` follows.
176
+ # deferred_prs PR numbers read from a branch line or slice heading that
177
+ # carries a `deferred:`/`moved:` annotation, in document order.
178
+ # Every one is also in `prs`. The release record reads the last
179
+ # PR of `prs` that is not here. [] when no deferred line names one.
176
180
  # malformed_prs near-miss annotations, verbatim — currently `→#NNN` with no
177
181
  # space. Reported rather than dropped: "no annotation" is a
178
182
  # claim the sweep acts on, so a typo that reads as absence
@@ -307,7 +311,7 @@ if [ ${#files[@]} -eq 0 ] && [ ${#missing[@]} -eq 0 ]; then
307
311
  fi
308
312
 
309
313
  for f in ${missing[@]+"${missing[@]}"}; do
310
- printf '{"file":"%s","format":"none","error":"file not found","phase_raw":"","phase":"NONE","phase_alt_raw":"","phase_alt":"NONE","type":"","title":"","sprint":"","story":"","assignee":"","branches":[],"prs":[],"issues":[],"malformed_prs":[],"changelog":[],"long_wave_names":[],"unread_branch_headings":[],"unread_waits":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
314
+ printf '{"file":"%s","format":"none","error":"file not found","phase_raw":"","phase":"NONE","phase_alt_raw":"","phase_alt":"NONE","type":"","title":"","sprint":"","story":"","assignee":"","branches":[],"prs":[],"deferred_prs":[],"issues":[],"malformed_prs":[],"changelog":[],"long_wave_names":[],"unread_branch_headings":[],"unread_waits":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
311
315
  "$(printf '%s' "$f" | sed 's/\\/\\\\/g; s/"/\\"/g')"
312
316
  done
313
317
 
@@ -495,7 +499,7 @@ function reset_state() {
495
499
  block_rounds = ""
496
500
  in_fm = 0; section = ""; in_comment = 0; in_challenge = 0; in_fence = 0; slices_seen = 0; slice_shape = ""
497
501
  delete branches; n_branches = 0
498
- delete prs; n_prs = 0
502
+ delete prs; n_prs = 0; delete dprs; n_dprs = 0
499
503
  delete malformed_prs; n_malformed_prs = 0
500
504
  fm_issue = ""; canon_issue = ""
501
505
  delete issues; n_issues = 0
@@ -645,7 +649,7 @@ function emit_record( fmt, praw, palt_raw, traw, title, sprint, story, assigne
645
649
  for (i = 1; i <= nb; i++) out = out (i > 1 ? "," : "") "\"" jesc(sorted_b[i]) "\""
646
650
  out = out "],\"prs\":["
647
651
  for (i = 1; i <= np; i++) out = out (i > 1 ? "," : "") sorted_p[i]
648
- out = out "],\"issues\":["
652
+ out = out "],\"deferred_prs\":["; for (i = 1; i <= n_dprs; i++) out = out (i > 1 ? "," : "") (dprs[i] + 0); out = out "],\"issues\":["
649
653
  for (i = 1; i <= ni; i++) {
650
654
  # Numeric issues output as JSON numbers; string issues (Jira keys) as quoted.
651
655
  if (sorted_i[i] in issue_is_str)
@@ -1245,7 +1249,7 @@ section == "slices" && slice_shape != "heading" {
1245
1249
  while (match(line, /→ ([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+)?#[0-9]+/)) {
1246
1250
  p = substr(line, RSTART, RLENGTH)
1247
1251
  sub(/^.*#/, "", p)
1248
- prs[++n_prs] = p
1252
+ prs[++n_prs] = p; if ($0 ~ /<!--[ \t]*(deferred|moved)[ \t]*(:|-->)/) dprs[++n_dprs] = p
1249
1253
  line = substr(line, RSTART + RLENGTH)
1250
1254
  }
1251
1255
  # A near-miss is REPORTED, never silently dropped. `→#44` (no space) is the
@@ -1382,7 +1386,7 @@ section == "slices" && slice_shape == "heading" {
1382
1386
  if (match($0, /PR:[ \t]*#[0-9]+/)) {
1383
1387
  p = substr($0, RSTART, RLENGTH)
1384
1388
  sub(/^.*#/, "", p)
1385
- prs[++n_prs] = p
1389
+ prs[++n_prs] = p; if ($0 ~ /<!--[ \t]*(deferred|moved)[ \t]*(:|-->)/) dprs[++n_dprs] = p
1386
1390
  }
1387
1391
  next
1388
1392
  }
package/plot-pr-merged.sh CHANGED
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env bash
2
2
  # Plot helper: the ONE answer to "did the host merge ANY PR for this branch?"
3
3
  #
4
- # SOURCED, NOT RUN. `. "$script_dir/plot-pr-merged.sh"` defines `pr_merged`,
5
- # `pr_open` and `pr_merged_heads`; the file does nothing else on load. That is what makes sourcing it
4
+ # SOURCED, NOT RUN. `. "$script_dir/plot-pr-merged.sh"` defines `pr_merged` and
5
+ # `pr_open`; the file does nothing else on load. That is what makes sourcing it
6
6
  # safe, and it is the same shape — and the same reason — as
7
7
  # `plot-worker-state.sh`: the logic could not simply stay in `plot-reap.sh`,
8
8
  # because that file parses `$@` and `exit 2`s on an unknown argument at load
@@ -72,9 +72,8 @@
72
72
  #
73
73
  # AN EMPTY BRANCH IS NOT ASKED ABOUT. `gh pr list --head ""` applies no filter,
74
74
  # so every PR in the repository matches: measured 2026-10-01 on `origin/main`
75
- # (`56a978ea`), `_plot_merged_lookup ""` answered `found`, `pr_merged ""` exited
76
- # 0 — merged — and `pr_merged_heads ""` printed 98 lines, the head of every
77
- # merged PR here. So each of the three lookups refuses an empty branch BEFORE
75
+ # (`56a978ea`), `_plot_merged_lookup ""` answered `found` and `pr_merged ""`
76
+ # exited 0 — merged. So each of the two lookups refuses an empty branch BEFORE
78
77
  # `command -v gh`, answering `unaskable` rather than `none` because a lookup that
79
78
  # did not run is silence and `none` would claim the host spoke; `pr_open ""` then
80
79
  # casts no veto, which is safe only because `pr_merged ""` refuses on the same
@@ -193,31 +192,3 @@ pr_open() {
193
192
  answer=$(_plot_landed none "$(_plot_open_lookup "$1")") || return 1
194
193
  case "$answer" in *" open-pr") return 0 ;; *) return 1 ;; esac
195
194
  }
196
-
197
- # Which commits did the host merge for this branch? One `headRefOid` per merged
198
- # PR, one per line.
199
- #
200
- # A THIRD QUESTION, asked by `plot-reap.sh` only. After a squash merge the
201
- # host deletes the branch (`delete_branch_on_merge`), `git fetch --prune`
202
- # drops the remote-tracking ref, and the branch's own commits are then on no
203
- # remote ref at all. So "which commits did no remote ever hold?" needs the
204
- # head the host merged: a commit reachable from it was pushed; a commit beyond
205
- # it exists only on the desk.
206
- #
207
- # Returns 1 when the host cannot be asked. The caller reads that as
208
- # `unknown`, which keeps the desk: here a failure to observe is the case that
209
- # loses work. It prints nothing and returns 0 when the host answered and no PR
210
- # merged.
211
- pr_merged_heads() {
212
- local br="$1" out
213
- [ -n "$br" ] || return 1
214
- command -v gh >/dev/null 2>&1 || return 1
215
- out=$(gh pr list --head "$br" --state all --limit 100 --json mergedAt,headRefOid 2>/dev/null) \
216
- || return 1
217
- printf '%s' "$out" | node -e '
218
- let s = "";
219
- process.stdin.on("data", (d) => { s += d; }).on("end", () => {
220
- const rows = JSON.parse(s);
221
- for (const r of rows) if (r.mergedAt && r.headRefOid) console.log(r.headRefOid);
222
- });' 2>/dev/null || return 1
223
- }