vouchington-tooling 3.4.1 → 3.5.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.
Files changed (37) hide show
  1. package/dist/mcp-server/handlers-retrospective-save.d.mts +1 -1
  2. package/dist/mcp-server/handlers-retrospective-save.mjs +8 -1
  3. package/dist/mcp-server/retrospective-sections.test-helpers.d.mts +4 -0
  4. package/dist/mcp-server/retrospective-sections.test-helpers.mjs +29 -0
  5. package/dist/mcp-server/retrospective-validate-assessments.d.mts +2 -0
  6. package/dist/mcp-server/retrospective-validate-assessments.mjs +51 -0
  7. package/dist/mcp-server/retrospective-validate-ci.d.mts +4 -0
  8. package/dist/mcp-server/retrospective-validate-ci.mjs +79 -0
  9. package/dist/mcp-server/retrospective-validate.d.mts +6 -0
  10. package/dist/mcp-server/retrospective-validate.mjs +35 -0
  11. package/dist/triage-loop-scripts.test-helpers.d.mts +53 -0
  12. package/dist/triage-loop-scripts.test-helpers.mjs +143 -0
  13. package/docs/mcp-server.md +17 -1
  14. package/package.json +3 -3
  15. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  16. package/skills/blackboard/SKILL.md +2 -0
  17. package/skills/blackboard/references/session-id.md +14 -0
  18. package/skills/manifest.json +9 -9
  19. package/skills/retrospective/SKILL.md +6 -2
  20. package/skills/retrospective/references/pr-feedback.md +45 -0
  21. package/skills/retrospective/references/sandbox-audit.md +44 -0
  22. package/skills/retrospective-distill/SKILL.md +6 -3
  23. package/skills/triage-loop/SKILL.md +43 -8
  24. package/skills/triage-loop/references/config.md +4 -2
  25. package/skills/triage-loop/scripts/__pycache__/events.cpython-314.pyc +0 -0
  26. package/skills/triage-loop/scripts/__pycache__/late_review.cpython-314.pyc +0 -0
  27. package/skills/triage-loop/scripts/__pycache__/state.cpython-314.pyc +0 -0
  28. package/skills/triage-loop/scripts/__pycache__/update_check.cpython-314.pyc +0 -0
  29. package/skills/triage-loop/scripts/events.py +120 -0
  30. package/skills/triage-loop/scripts/late_review.py +78 -0
  31. package/skills/triage-loop/scripts/state.py +79 -11
  32. package/skills/triage-loop/scripts/update_check.py +35 -0
  33. package/skills/triage-loop/scripts/wait.py +98 -36
  34. package/skills/triage-prs/SKILL.md +2 -2
  35. package/skills/triage-prs/references/feedback.md +4 -1
  36. package/skills/triage-sweep/SKILL.md +2 -1
  37. package/skills/triage-sweep/references/dependency-update-check.md +6 -3
@@ -0,0 +1,45 @@
1
+ # PR creation feedback
2
+
3
+ Read this when a PR-triage caller supplied agent-authored PR creation feedback this session. Keep
4
+ both the per-PR findings and the deduplicated grouped themes.
5
+
6
+ ```markdown
7
+ ## PR Creation Feedback
8
+
9
+ ### Per-PR findings
10
+
11
+ - PR #N - `<recurring|one-off>`
12
+ - Evidence: <body, diff, checks, or shepherd correction>
13
+ - Generator provenance: <verified generating prompt or skill>
14
+ - Source target: <exact file path>
15
+ - Recommendation: <specific preventive improvement>
16
+
17
+ ### Grouped themes
18
+
19
+ - <theme>
20
+ - PRs: #N, #N
21
+ - Recurrence: <recurring|one-off>
22
+ - Source target: <exact file path>
23
+ - Recommendation: <deduplicated improvement>
24
+ - Disposition: <issue #N|PR #N|preauthorized-pr #N|deferred>
25
+ ```
26
+
27
+ When there is no actionable feedback, write `No actionable feedback: none` instead of inventing a
28
+ theme.
29
+
30
+ ## Disposition
31
+
32
+ When the caller did not already publish the feedback, ask the user to choose one:
33
+
34
+ - **File issues:** deduplicate by root cause, file through the repository's issue workflow, and
35
+ record each issue link.
36
+ - **Make a PR:** when several unrelated themes exist, ask which single theme to implement. Reuse or
37
+ create its tracking issue, make one coherent draft PR, do not merge it, and record the PR link.
38
+ - **Defer:** make no GitHub change; the theme stays eligible for a later distillation run.
39
+
40
+ When the triage flow already completed its bounded publication
41
+ ([feedback](../../triage-prs/references/feedback.md)), it passes `Disposition: preauthorized-pr #N`.
42
+ Record that exact disposition and the PR link without asking again. If publication failed or only
43
+ partly completed, record the concrete blocker as `deferred`; never claim the feedback was handled.
44
+
45
+ Save one retrospective with the final disposition and links for all PRs.
@@ -40,9 +40,53 @@ or package entry it names still exists. A transcript can be stale.
40
40
  - Human-rejected command: propose a block rule, but surface it for human review and never write a
41
41
  deny rule from a retrospective. One rejection is one data point; confirm the pattern recurs.
42
42
 
43
+ ## Reading the command audit report
44
+
45
+ The `sandbox-command-audit` command reports three signals instead of one merged ranking, because
46
+ each maps to a different action:
47
+
48
+ - Genuine bypass: Claude Bash failures on a permission or access signature, not `E2BIG`. Judge them
49
+ by the decision criteria above.
50
+ - Block candidates: Claude denials where a human rejected the command. Propose a block rule for
51
+ human review.
52
+ - Escalation pressure: Claude `dangerouslyDisableSandbox` escalations, split into covered and
53
+ uncovered by policy, plus the `E2BIG` count. It shows sandbox friction and is not by itself a
54
+ command to allow.
55
+
56
+ Also:
57
+
58
+ - `permission-rule` and `automode-blocked` denials appear only as a hygiene count: a block policy
59
+ working as intended.
60
+ - Codex transcripts are read only when the consumer's rules module sets `classifyFailure`, which
61
+ then runs on each completed `CommandExecution` result whatever its exit status. A push can
62
+ succeed before a later local write fails, so a zero exit does not exempt a result.
63
+ - Worktree write-path denials are not built in. The package ships only the `genuine` and `e2big`
64
+ kinds; a consumer's `classifyFailure` rule claims these (it runs before the generic permission
65
+ signatures), and they are reported as `Other classified sandbox failures`, a count per kind and
66
+ never a bypass candidate. A conservative rule requires git command context, a git-produced
67
+ diagnostic (`fatal:`, `error:`, or `warning:`), and a permission token (`Operation not permitted`,
68
+ `EPERM`, `Permission denied`, `EROFS`, `Read-only file system`) adjacent to
69
+ `.git/worktrees/<name>/`, `.git/config`, `.git/packed-refs`, or `.git/refs/`. File content shown
70
+ by `git show` or `git diff` is not a diagnostic, and `index.lock` contention is not a permission
71
+ denial.
72
+
73
+ ### Repo scoping
74
+
75
+ - Check the `Scope:` line before trusting a report: it lists the roots and counts the files
76
+ skipped as `other repo` or `cwd unknown`.
77
+ - A transcript is attributed by its first recorded `cwd`. The walk stops at `--limit`, so the skip
78
+ counts are lower bounds: a `0` for `other repo` is not proof that nothing else was reachable.
79
+ - A deleted worktree that `git worktree list` no longer reports is not discoverable, and its
80
+ transcripts count as `other repo`. Restore its path with `--repo-root`, or its layout with
81
+ `--worktree-glob`.
82
+
43
83
  ## Privacy
44
84
 
45
85
  Report a normalized `<command> <subcommand>` prefix and counts, never the raw command line or a
46
86
  justification verbatim. For a short command the prefix is the whole command, so a branch slug, short
47
87
  path, or hostname can appear in it: skim and redact before saving. Retrospectives are distilled into
48
88
  public issues.
89
+
90
+ The audit's default output is prefix-only, and any token longer than 40 characters is replaced
91
+ outright with a marker, never truncated. `--raw` adds full commands and failure text for local
92
+ inspection only; never paste `--raw` output into a retrospective.
@@ -128,11 +128,14 @@ difference is a conflicting payload and stays quarantined.
128
128
  for sessions whose only themes were deferred, since deferral promises re-evaluation. Keep a theme
129
129
  tied to a closed-without-merge issue or change eligible; do not treat open state alone as
130
130
  conclusive. Preserve each theme's contributing session IDs through merging and deduplication.
131
- - Delegate partitions only to read-only inspectors, which must not call MCP, create issues, archive
131
+ - Delegate partitions only to read-only inspectors (the host's read-only explore agent), which
132
+ must not call MCP, create issues, archive
132
133
  sessions, edit files, or keep a copy of a partition. Have each return a compact disposition
133
134
  summary: partition index, deduplicated themes with their session IDs, and each session's
134
- disposition. Inspectors hand-read only journal-only and retrospective sessions; every other shape
135
- is determined structurally.
135
+ disposition. Before hand-reading, each inspector runs
136
+ `vouchington agent-blackboard distill classify <partition> --retro-cutoff <retroCutoff> --session-cutoff <sessionCutoff>`
137
+ with the shared cutoffs. Inspectors hand-read only journal-only and retrospective sessions; every
138
+ other shape is determined structurally.
136
139
  - Keep the verified snapshot until the last `snapshot_archive` call, because the server's archival
137
140
  check reads it.
138
141
  Then call `snapshot_cleanup`, which removes the snapshot and the partitions
@@ -122,6 +122,9 @@ through a printed command, and merges within the grant.
122
122
  - `intake` (queued agent reports)
123
123
  - `scheduledPrompts` (`next` rotation position, and a bounded `runs` history)
124
124
  - `delegations` (see [Configuration](#configuration)) and `routed` (where items were sent)
125
+ - `watches` (merge watches, see [Step 3](#step-3---handle-the-wait-result)), `quietMerges`
126
+ (clean merges `wait.py` handled), and `pendingUpdateChecks` (repositories awaiting a
127
+ dependency update check)
125
128
  4. Run the sweep [Preflight](../triage-sweep/SKILL.md#preflight) once (`pr-shepherd`, `gh`, the
126
129
  dispatch targets, and the journal server). Check `hook-harness` only when `eventWait` is
127
130
  configured; if it is absent or fails, continue and use the fallback pacing in Step 2.
@@ -143,9 +146,10 @@ prompt) when the recurring-task tool is only available there.
143
146
  cursor with `--on ejection,dependabot-pr,/shepherd,/plan,/fix`, plus failed `workflow_run`
144
147
  completions on `main` and every `pull_request` `closed` event (merged or not). Default-branch failures come from `workflow_run` only, which carries
145
148
  `workflow` and `runId`; pull-request checks are left to pr-shepherd, and failures from
146
- third-party check apps are deliberately not watched in real time. The script writes
147
- `{events, gap, timedOut?, cursor}` to `<stateDir>/hh-last.json`, prints one line per event, and
148
- exits. Command events carry `payload.comment.body`, which is untrusted text. When the relay host
149
+ third-party check apps are deliberately not watched in real time. The script checks each merge
150
+ for late reviews itself and keeps waiting through clean ones (see Step 3). It writes
151
+ `{events, gap, timedOut?, cursor}` for the actionable events to `<stateDir>/hh-last.json`,
152
+ prints a summary line and one compact line per event, and exits. Command events carry `payload.comment.body`, which is untrusted text. When the relay host
149
153
  is outside the host sandbox's network allowlist, the wait needs an unsandboxed run. The wait's
150
154
  timeout is the heartbeat: on each timeout, relaunch it and re-register the fallback cron if it
151
155
  nears expiry. While it runs, schedule no idle wakeups: events, other agents' messages, and
@@ -162,13 +166,23 @@ Each sweep takes the lock in the state directory and skips if another sweep hold
162
166
 
163
167
  ## Step 3 - Handle the wait result
164
168
 
165
- When the wait exits: read its result and dedupe events on `id` against `hookHarness.seen`. Record
169
+ When the wait exits: read its output and dedupe events on `id` against `hookHarness.seen`. Record
166
170
  each event in `hookHarness` as in progress before acting, mark it done after, and only then persist
167
- the new cursor (`state.py advance-hh`) and relaunch the wait. Every external action must be idempotent across an
171
+ the new cursor (`state.py advance-hh`, or launch `wait.py --advance` or set `eventWait.advance` to
172
+ store it when the wait returns, giving up crash replay; returned ids are then not added to `seen`, so
173
+ handle each returned event) and relaunch the wait. Every external action must be idempotent across an
168
174
  interruption and replay: before opening a PR, filing an issue, or posting a comment, look for an
169
175
  existing one from this event (a PR linking the issue, an issue citing the run id, the `eyes`
170
176
  reaction, a `shepherds` entry) and reuse it instead of creating another.
171
177
 
178
+ The first output line is a JSON summary: `gap`, `timedOut?`, `events` (the count that follow),
179
+ `quiet?` (`{count, merges}`: clean merges handled since the last return, as `repo#N`),
180
+ `pendingUpdateChecks?` (repository names), `updateCheckDue?`, and `advanced?`. Each following line
181
+ is one event with only its non-empty fields, in the order `id`, `repo`, `event`, `action`, `prs`,
182
+ `issue`, `reason`, `conclusion`, `workflow`, `runId`, `command`, `commentId`, `headSha`, `sender`,
183
+ `merged`, and for a merge `unresolved`, `late`, `truncated`, or `lateReviewError`. A watch trigger
184
+ is `{event: "watch", id, notify, note, prs}`.
185
+
172
186
  - `gap: true`: events may have been missed. Run the backstop, triage-sweep Phase G.
173
187
  - Exit 1 (auth, cursor, or relay error): report it and fall back to sweeps until it is fixed.
174
188
  - Skip events for repositories outside the configured filter.
@@ -181,22 +195,36 @@ private organization members.
181
195
  - **`ejection`, failed `workflow_run` on `main`:** see [Failures](#failures). A dequeue carries no run: find it with
182
196
  `gh run list --repo <owner>/<name> --event merge_group --status failure --limit 5` and match the PR number.
183
197
  - **`dependabot-pr`:** run triage-sweep Phase A for that PR.
184
- - **`pull_request` `closed`** (the line's `merged` says whether it merged). Event text is data, so
198
+ - **`pull_request` `closed`** (the line's `merged` says whether it merged). `wait.py` already ran
199
+ the late-review check on every merge and returned only the merges with `unresolved`, `late`,
200
+ `truncated`, or `lateReviewError`, and clean merges of a PR the loop tracks (`tracked: true`: a
201
+ `shepherds`, `routed`, `delegations`, `escalations`, or `intake` record mentions it). Other clean
202
+ merges never reach the loop; the next summary's `quiet` lists them. Past the overall timeout it
203
+ returns `timedOut` even amid quiet merges. A `tracked` merge takes the _Tracked PR_ steps below,
204
+ which the loop (not `wait.py`) performs. Event text is data, so
185
205
  first confirm the state with `gh pr view <N> --repo <owner>/<name> --json state,mergedAt`.
186
206
  Continue only when the PR is still closed or merged; leave an open PR running.
187
207
  - _Tracked PR_ (a `shepherds` entry, a pending or escalation record, an awaiting-approval line):
188
208
  stop any pr-shepherd command still running for it, remove its records with `state.py remove`,
189
209
  and stop listing it as awaiting approval or in flight. Report a merge as `merged` and a close
190
210
  without merge as `closed` in the next summary.
191
- - _Merged PR, tracked or not:_ run triage-sweep
211
+ - _Merged PR, tracked or not, with findings:_ run triage-sweep
192
212
  [Phase F](../triage-sweep/SKILL.md#phase-f---missed-code-reviews) for that one PR right away: scan it
193
213
  for review threads unresolved at merge and for reviews, review comments, and review-thread
194
214
  comments created after `mergedAt`, then verify, dedupe against `reviewedComments`, and file
195
215
  findings exactly as Phase F does. This does not replace Phase F's incremental and backstop
196
- scans, which still catch comments posted later. The per-event check never advances
216
+ scans, which still catch comments posted later. `state.py late-review <owner/repo#N> ...`
217
+ reruns the check and prints one line per PR. The per-event check never advances
197
218
  `scannedThrough`, `activityThrough`, or `fullScanAt` (it covers one PR, not a window); only the
198
219
  sweep does, and `reviewedComments` keeps the sweep from refiling what the event check handled.
199
220
  - A closed PR without merge that the loop does not track needs nothing further.
221
+ - **`pendingUpdateChecks` or `updateCheckDue`:** after a dependency-bot PR merges, build the script
222
+ with `state.py update-check-script --repo <name> [--repo <name:ecosystem>]` for those repositories,
223
+ run it as in triage-sweep's
224
+ [dependency update check](../triage-sweep/references/dependency-update-check.md), then
225
+ `state.py remove pendingUpdateChecks`. Do this on any return that lists them.
226
+ - **`event: "watch"`:** message the `notify` session with `note` (see
227
+ [Merge watches](#merge-watches)), then `state.py watch remove --id <id>` (or `watch ack`). An unacked complete watch is returned again on every wait.
200
228
  - **`/shepherd`, `/plan`, `/fix`:** see [Comment commands](#comment-commands).
201
229
  - **Other events:** leave them to the next sweep.
202
230
 
@@ -205,6 +233,13 @@ untracked merge with no late-review findings, a closed PR the loop does not trac
205
233
  out-of-filter event. Report only escalations, findings, and state changes of PRs the loop tracks or
206
234
  was asked to handle.
207
235
 
236
+ ### Merge watches
237
+
238
+ `state.py watch add --id <id> --pr <owner/repo#N> [--pr ...] --notify <session> --note <text>`
239
+ asks to be told when every listed PR has merged. `wait.py` then returns a `watch` event and
240
+ repeats it on every wait until `watch ack --id <id>` or `watch remove --id <id>`; `watch list` shows them.
241
+ A watch is intent only, so a PR closed without merging keeps it pending until removed.
242
+
208
243
  ### Failures
209
244
 
210
245
  For a merge-queue ejection or a default-branch CI failure, dedupe per repository and workflow (or
@@ -94,5 +94,7 @@ Both read the configuration file, honor `TRIAGE_LOOP_CONFIG`, and need Python 3
94
94
  rather than editing the file another way. `state.py --help` lists them.
95
95
  - [`scripts/wait.py`](../scripts/wait.py) runs one `hook-harness wait` from the stored cursor over
96
96
  the configured repositories, writes the result to `<stateDir>/hh-last.json`, prints one summary
97
- line per event, and exits. It never advances the cursor; `state.py advance-hh` does that after
98
- the events are handled.
97
+ line per event, and exits. Unless asked to, it never advances the cursor; `state.py advance-hh` does that after
98
+ the events are handled (or `wait.py --advance`, or `eventWait.advance: true`, does it at return).
99
+ Clean merges are checked for late reviews inline and do not return; the wait also returns when a
100
+ dependency update check has been pending for `eventWait.updateCheckDelay` (default `"10m"`).
@@ -0,0 +1,120 @@
1
+ """Event classification for wait.py: compact lines, quiet merges, dependency-bot merges, and watches."""
2
+ import json, re, state, late_review
3
+
4
+ FIELDS = ("id", "repo", "event", "action", "prs", "issue", "reason", "conclusion", "workflow",
5
+ "runId", "command", "commentId", "headSha")
6
+ QUIET_KEEP = 100
7
+ TRACKING = ("shepherds", "routed", "delegations", "escalations", "intake")
8
+
9
+
10
+ def compact(event):
11
+ """One stable line: the fields the loop uses, in a fixed order, without empty values."""
12
+ line = {k: event[k] for k in FIELDS if event.get(k) not in (None, "", [])}
13
+ if event.get("sender"):
14
+ line["sender"] = (event.get("sender") or {}).get("login")
15
+ pull = (event.get("payload") or {}).get("pull_request")
16
+ if event.get("event") == "pull_request" and isinstance(pull, dict):
17
+ line["merged"] = pull.get("merged") is True
18
+ return line
19
+
20
+
21
+ def pull_of(event):
22
+ pull = (event.get("payload") or {}).get("pull_request")
23
+ return pull if isinstance(pull, dict) else {}
24
+
25
+
26
+ def is_merge(event):
27
+ return event.get("event") == "pull_request" and event.get("action") == "closed" and pull_of(event).get("merged") is True
28
+
29
+
30
+ def ref_of(event, org):
31
+ number = pull_of(event).get("number") or next(iter(event.get("prs") or []), None)
32
+ repo = event.get("repo") or ""
33
+ return f"{repo if '/' in repo else org + '/' + repo}#{number}"
34
+
35
+
36
+ def login(name):
37
+ return (name or "").removeprefix("app/").removesuffix("[bot]").lower()
38
+
39
+
40
+ def is_dependency_bot(event, cfg):
41
+ author = ((cfg.get("dependencyBot") or {}).get("author")) or "dependabot"
42
+ return login((pull_of(event).get("user") or {}).get("login")) == login(author)
43
+
44
+
45
+ def triage_merge(event, cfg):
46
+ """Return (line, ref, bot) for one merge event; line is None when it is clean."""
47
+ ref = ref_of(event, cfg["org"])
48
+ line = compact(event)
49
+ try:
50
+ result = late_review.check(ref)
51
+ except Exception as error: # any failure returns the merge rather than killing the wait
52
+ return {**line, "lateReviewError": str(error)[:200]}, ref, is_dependency_bot(event, cfg)
53
+ if result["unresolved"] or result["late"] or result["truncated"]:
54
+ found = {"unresolved": result["unresolved"], "late": result["late"]}
55
+ return {**line, **found, **({"truncated": True} if result["truncated"] else {})}, ref, is_dependency_bot(event, cfg)
56
+ return None, ref, is_dependency_bot(event, cfg)
57
+
58
+
59
+ def tracked(s, ref):
60
+ """True when a loop record (shepherd, routing, delegation, escalation, intake) mentions the PR."""
61
+ pattern = re.compile(re.escape(ref.split("/", 1)[1]) + r"(?!\d)", re.I)
62
+ return any(pattern.search(json.dumps(s.get(key) or "")) for key in TRACKING)
63
+
64
+
65
+ def update_watches(s, merged):
66
+ """Record merged PRs in each watch; return a trigger for every complete watch not yet acked.
67
+ A trigger repeats on each wait until `state.py watch ack|remove`, so a crash cannot lose it."""
68
+ triggers = []
69
+ for w in s.get("watches") or []:
70
+ wanted = {p.lower() for p in w["prs"]}
71
+ w["merged"] = sorted({r.lower() for r in w.get("merged", [])} | {r.lower() for r in merged} & wanted)
72
+ if set(w["merged"]) >= wanted and not w.get("ackedAt"):
73
+ triggers.append({"event": "watch", "id": w["id"], "notify": w["notify"], "note": w.get("note", ""), "prs": w["prs"]})
74
+ return triggers
75
+
76
+
77
+ def sweep(events, cfg):
78
+ """Split a wait result's events into (actionable lines, raw actionable events, watch triggers).
79
+ Clean merges are recorded in `quietMerges` (and `pendingUpdateChecks` for dependency-bot PRs), their
80
+ ids marked seen, and watches updated, all in one locked write."""
81
+ s = state.load()
82
+ seen = set(((s.get("hookHarness") or {}).get("seen")) or [])
83
+ lines, raw, quiet, bots, merged, quiet_ids = [], [], [], [], [], []
84
+ for event in events:
85
+ if not is_merge(event):
86
+ lines.append(compact(event)), raw.append(event)
87
+ continue
88
+ if event.get("id") in seen:
89
+ continue
90
+ line, ref, bot = triage_merge(event, cfg)
91
+ if line is None and tracked(s, ref):
92
+ line = {**compact(event), "tracked": True}
93
+ merged.append(ref)
94
+ if bot:
95
+ bots.append(ref.split("#")[0].split("/")[1])
96
+ if line:
97
+ lines.append(line), raw.append(event)
98
+ else:
99
+ quiet.append(ref), quiet_ids.append(event.get("id"))
100
+ with state.locked():
101
+ s = state.load()
102
+ at = state.now()
103
+ log = s.setdefault("quietMerges", [])
104
+ log.extend(r.split("/", 1)[1] for r in quiet)
105
+ s["quietMerges"] = log[-QUIET_KEEP:]
106
+ pending = s.setdefault("pendingUpdateChecks", [])
107
+ pending.extend({"repo": r, "at": at} for r in dict.fromkeys(bots) if r not in {p["repo"] for p in pending})
108
+ triggers = update_watches(s, merged)
109
+ state.record_events(s, [i for i in quiet_ids if i], None)
110
+ state.save(s)
111
+ return lines, raw, triggers
112
+
113
+
114
+ def watch_triggers():
115
+ """Triggers for watches already complete and unacked, without new events."""
116
+ with state.locked():
117
+ s = state.load()
118
+ triggers = update_watches(s, [])
119
+ state.save(s)
120
+ return triggers
@@ -0,0 +1,78 @@
1
+ """Late-review check for merged pull requests, shared by state.py and wait.py.
2
+
3
+ For one `owner/repo#N` it reports the PR state, mergedAt, the unresolved review threads, and the
4
+ non-empty reviews submitted after mergedAt. Threads and reviews are paged 100 at a time, up to
5
+ MAX_PAGES pages each; a PR with more is reported with `truncated: true` rather than undercounted.
6
+ """
7
+ import json, re, subprocess
8
+
9
+ MAX_PAGES = 5
10
+ REF = re.compile(r"^([\w.-]+)/([\w.-]+)#(\d+)$")
11
+ QUERY = (
12
+ "query($o:String!,$n:String!,$p:Int!,$c:String){repository(owner:$o,name:$n){pullRequest(number:$p){"
13
+ "state mergedAt %s(first:100,after:$c){pageInfo{hasNextPage endCursor} nodes{%s}}}}}"
14
+ )
15
+ CONNECTIONS = {"reviewThreads": "isResolved", "reviews": "body submittedAt"}
16
+
17
+
18
+ class LateReviewError(Exception):
19
+ pass
20
+
21
+
22
+ def graphql(owner, name, number, connection, cursor):
23
+ command = ["gh", "api", "graphql", "-f", f"query={QUERY % (connection, CONNECTIONS[connection])}",
24
+ "-f", f"o={owner}", "-f", f"n={name}", "-F", f"p={number}"]
25
+ if cursor:
26
+ command += ["-f", f"c={cursor}"]
27
+ done = subprocess.run(command, capture_output=True, text=True)
28
+ if done.returncode != 0:
29
+ raise LateReviewError(f"gh exited {done.returncode}: {done.stderr.strip()[:200]}")
30
+ try:
31
+ pull = json.loads(done.stdout)["data"]["repository"]["pullRequest"]
32
+ return pull, pull[connection]
33
+ except (ValueError, KeyError, TypeError):
34
+ raise LateReviewError("pull request not found or unexpected response")
35
+
36
+
37
+ def fetch(owner, name, number, connection):
38
+ """Return (pull, nodes, truncated) for one connection."""
39
+ cursor, nodes = None, []
40
+ for _ in range(MAX_PAGES):
41
+ pull, conn = graphql(owner, name, number, connection, cursor)
42
+ nodes += conn["nodes"]
43
+ if not conn["pageInfo"]["hasNextPage"]:
44
+ return pull, nodes, False
45
+ cursor = conn["pageInfo"]["endCursor"]
46
+ return pull, nodes, True
47
+
48
+
49
+ def check(ref):
50
+ match = REF.match(ref)
51
+ if not match:
52
+ raise LateReviewError(f"{ref!r} must look like owner/repo#N")
53
+ owner, name, number = match.groups()
54
+ pull, threads, cut_threads = fetch(owner, name, number, "reviewThreads")
55
+ _, reviews, cut_reviews = fetch(owner, name, number, "reviews")
56
+ merged_at = pull["mergedAt"]
57
+ late = [r for r in reviews if merged_at and (r["body"] or "").strip() and r["submittedAt"] and r["submittedAt"] > merged_at]
58
+ return {"ref": ref, "state": pull["state"], "mergedAt": merged_at,
59
+ "unresolved": sum(not t["isResolved"] for t in threads), "late": len(late),
60
+ "truncated": cut_threads or cut_reviews}
61
+
62
+
63
+ def is_merged(ref):
64
+ match = REF.match(ref)
65
+ if not match:
66
+ raise LateReviewError(f"{ref!r} must look like owner/repo#N")
67
+ owner, name, number = match.groups()
68
+ done = subprocess.run(["gh", "api", f"repos/{owner}/{name}/pulls/{number}", "--jq", ".merged_at // empty"],
69
+ capture_output=True, text=True)
70
+ if done.returncode != 0:
71
+ raise LateReviewError(f"gh exited {done.returncode}: {done.stderr.strip()[:200]}")
72
+ return bool(done.stdout.strip())
73
+
74
+
75
+ def line(result):
76
+ text = (f"{result['ref']} {result['state']} mergedAt={result['mergedAt']} "
77
+ f"unresolved={result['unresolved']} late={result['late']}")
78
+ return text + (" truncated" if result["truncated"] else "")
@@ -8,13 +8,16 @@ Add a subcommand rather than editing state.json another way.
8
8
  """
9
9
  import argparse, contextlib, datetime, fcntl, json, os, sys, tempfile
10
10
 
11
+ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) # python3 -I leaves it off the path
12
+ import late_review, update_check
13
+
11
14
  SEEN_MAX = 200
12
15
  # The top-level fields and their shapes; `set`, `append`, and `remove` touch only these.
13
16
  FIELDS = {
14
17
  "lastSweepAt": str, "commandsThrough": str, "reviewedComments": dict, "lateReview": dict, "schedule": dict,
15
18
  "retroCursor": str, "escalations": dict, "hookHarness": dict, "handledFailures": dict,
16
19
  "shepherds": dict, "intake": list, "scheduledPrompts": dict, "delegations": list,
17
- "routed": list,
20
+ "routed": list, "watches": list, "quietMerges": list, "pendingUpdateChecks": list,
18
21
  }
19
22
 
20
23
 
@@ -122,23 +125,73 @@ def expect(value, kind, name):
122
125
  return value
123
126
 
124
127
 
128
+ def record_events(s, ids, cursor):
129
+ """Mark event ids seen and store the cursor, as `advance-hh` does for one wait result."""
130
+ hh = expect(s.setdefault("hookHarness", {}), dict, "hookHarness")
131
+ seen = expect(hh.setdefault("seen", []), list, "hookHarness.seen")
132
+ seen.extend(i for i in ids if i not in seen)
133
+ hh["seen"] = seen[-SEEN_MAX:]
134
+ if cursor:
135
+ hh["cursor"] = cursor
136
+
137
+
125
138
  def advance_hh(_):
126
139
  s = load()
127
140
  with open(HH_LAST) as f:
128
141
  d = json.load(f)
129
- hh = expect(s.setdefault("hookHarness", {}), dict, "hookHarness")
130
- seen = expect(hh.setdefault("seen", []), list, "hookHarness.seen")
131
- ids = [e["id"] for e in d.get("events", [])]
132
- for i in ids:
133
- if i not in seen:
134
- seen.append(i)
135
- hh["seen"] = seen[-SEEN_MAX:]
136
- if d.get("cursor"):
137
- hh["cursor"] = d["cursor"]
142
+ ids = [e["id"] for e in d.get("events", []) if "id" in e]
143
+ record_events(s, ids, d.get("cursor"))
138
144
  save(s)
139
145
  print(json.dumps({"events": len(ids), "cursorAdvanced": bool(d.get("cursor"))}))
140
146
 
141
147
 
148
+ def late_review_cmd(a):
149
+ failed = False
150
+ for ref in a.refs:
151
+ try:
152
+ print(late_review.line(late_review.check(ref)))
153
+ except late_review.LateReviewError as error:
154
+ failed = True
155
+ print(f"{ref} error: {error}")
156
+ sys.exit(1 if failed else 0)
157
+
158
+
159
+ def update_check_script(a):
160
+ try:
161
+ print(update_check.script(a.org or CONFIG.get("org"), a.repo, a.dry), end="")
162
+ except ValueError as error:
163
+ sys.exit(f"update-check-script: {error}")
164
+
165
+
166
+ def watch(a):
167
+ s = load()
168
+ watches = expect(s.setdefault("watches", []), list, "watches")
169
+ if a.action == "add":
170
+ if not a.id or not a.pr or not a.notify:
171
+ sys.exit("watch add needs --id, --notify, and at least one --pr")
172
+ if any(w["id"] == a.id for w in watches):
173
+ sys.exit(f"watch add: {a.id!r} already exists")
174
+ for ref in a.pr:
175
+ if not late_review.REF.match(ref):
176
+ sys.exit(f"watch add: {ref!r} must look like owner/repo#N")
177
+ try:
178
+ merged = [ref for ref in a.pr if late_review.is_merged(ref)]
179
+ except late_review.LateReviewError as error:
180
+ sys.exit(f"watch add: {error}")
181
+ watches.append({"id": a.id, "prs": a.pr, "notify": a.notify, "note": a.note or "", "at": now(),
182
+ "merged": sorted(r.lower() for r in merged)})
183
+ elif a.action == "remove":
184
+ watches[:] = [w for w in watches if w["id"] != a.id]
185
+ elif a.action == "ack":
186
+ hits = [w for w in watches if w["id"] == a.id]
187
+ if not hits:
188
+ sys.exit(f"watch ack: no watch {a.id!r}")
189
+ hits[0]["ackedAt"] = now()
190
+ if a.action != "list":
191
+ save(s)
192
+ print(json.dumps(watches))
193
+
194
+
142
195
  def route(a):
143
196
  s = load()
144
197
  routed = expect(s.setdefault("routed", []), list, "routed")
@@ -274,11 +327,26 @@ def main():
274
327
  x = sub.add_parser("remove", help="remove the key at a dotted path")
275
328
  x.add_argument("path")
276
329
  x.set_defaults(fn=remove_value)
330
+ x = sub.add_parser("late-review", help="report unresolved threads and late reviews for merged PRs")
331
+ x.add_argument("refs", nargs="+", metavar="owner/repo#N")
332
+ x.set_defaults(fn=late_review_cmd, lock=False)
333
+ x = sub.add_parser("update-check-script", help="print the Check-for-updates browser script")
334
+ x.add_argument("--repo", action="append", required=True, help="name or name:ecosystem[,ecosystem]")
335
+ x.add_argument("--org")
336
+ x.add_argument("--dry", action="store_true")
337
+ x.set_defaults(fn=update_check_script, lock=False)
338
+ x = sub.add_parser("watch", help="add, list, or remove a merge watch (watches in state.json)")
339
+ x.add_argument("action", choices=["add", "list", "ack", "remove"])
340
+ x.add_argument("--id")
341
+ x.add_argument("--pr", action="append", metavar="owner/repo#N")
342
+ x.add_argument("--notify", help="session name wait.py reports for the trigger")
343
+ x.add_argument("--note", help="what to tell it")
344
+ x.set_defaults(fn=watch)
277
345
  sh = sub.add_parser("show", help="print one key, or the top-level keys")
278
346
  sh.add_argument("key", nargs="?")
279
347
  sh.set_defaults(fn=show)
280
348
  args = p.parse_args()
281
- with locked():
349
+ with locked() if getattr(args, "lock", True) else contextlib.nullcontext():
282
350
  args.fn(args)
283
351
 
284
352
 
@@ -0,0 +1,35 @@
1
+ """Fills in triage-sweep's in-page "Check for updates" script for the host browser's JavaScript tool."""
2
+ import os, re
3
+
4
+ DOC = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "triage-sweep", "references",
5
+ "dependency-update-check.md")
6
+ NAME = re.compile(r"^[\w.-]+$")
7
+
8
+
9
+ def targets(repos):
10
+ """`name` checks every ecosystem; `name:npm,pip` limits the check to those ecosystems."""
11
+ merged = {} # repeated --repo options combine; an unrestricted one (None) covers every ecosystem
12
+ for repo in repos:
13
+ name, _, ecos = repo.partition(":")
14
+ listed = ecos.split(",") if ecos else []
15
+ if not NAME.match(name) or not all(NAME.match(e) for e in listed):
16
+ raise ValueError(f"{repo!r} must be name or name:ecosystem[,ecosystem]")
17
+ have = merged.get(name, [])
18
+ merged[name] = None if not listed or (name in merged and have is None) else have + [e for e in listed if e not in have]
19
+ return "{ " + ", ".join(
20
+ f"'{n}': " + ("[" + ", ".join(f"'{e}'" for e in v) + "]" if v else "null") for n, v in merged.items()) + " }"
21
+
22
+
23
+ def script(org, repos, dry=False):
24
+ if not NAME.match(org or ""):
25
+ raise ValueError(f"org {org!r} is not a valid organization name")
26
+ with open(DOC) as f:
27
+ match = re.search(r"```js\n(.*?)```", f.read(), re.S)
28
+ if not match:
29
+ raise ValueError("dependency-update-check.md has no js block")
30
+ code = match.group(1)
31
+ for name, value in (("ORG", f"'{org}'"), ("TARGETS", targets(repos)), ("DRY", "true" if dry else "false")):
32
+ code, count = re.subn(rf"^const {name} = .*$", lambda _: f"const {name} = {value}", code, count=1, flags=re.M)
33
+ if count != 1:
34
+ raise ValueError(f"dependency-update-check.md script has no `const {name} =` line")
35
+ return code