ticket-runner 0.6.0
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/LICENSE +21 -0
- package/README.ko.md +97 -0
- package/README.md +98 -0
- package/bin/ticket-runner.js +6 -0
- package/docs/templates/operator-skill.md +87 -0
- package/package.json +42 -0
- package/src/acceptance-criteria.ts +44 -0
- package/src/adapters/claude-agent-runner.ts +389 -0
- package/src/adapters/exec.ts +169 -0
- package/src/adapters/gh-tracker.ts +955 -0
- package/src/adapters/git-workspace.ts +951 -0
- package/src/adapters/repo-root.ts +20 -0
- package/src/adapters/version.ts +118 -0
- package/src/base-branch.ts +21 -0
- package/src/branch.ts +33 -0
- package/src/cli.ts +135 -0
- package/src/command-line.ts +190 -0
- package/src/config.ts +277 -0
- package/src/conventions.ts +118 -0
- package/src/criteria.ts +106 -0
- package/src/frontier.ts +36 -0
- package/src/guards.ts +143 -0
- package/src/handoff.ts +82 -0
- package/src/host.ts +116 -0
- package/src/init.ts +405 -0
- package/src/labels.ts +42 -0
- package/src/landing.ts +75 -0
- package/src/lifecycle.ts +34 -0
- package/src/lock.ts +215 -0
- package/src/note-schema.ts +58 -0
- package/src/notes.ts +433 -0
- package/src/operator-skill.ts +24 -0
- package/src/orchestrator.ts +1816 -0
- package/src/ports/agent-runner.ts +105 -0
- package/src/ports/tracker.ts +334 -0
- package/src/ports/workspace.ts +422 -0
- package/src/progress.ts +231 -0
- package/src/prompts.ts +288 -0
- package/src/readiness.ts +256 -0
- package/src/remove.ts +732 -0
- package/src/resume.ts +145 -0
- package/src/run-log.ts +85 -0
- package/src/run.ts +331 -0
- package/src/self-hosting.ts +33 -0
- package/src/stage-guard.ts +32 -0
- package/src/staleness.ts +101 -0
- package/src/start.ts +284 -0
- package/src/startup.ts +34 -0
- package/src/stop.ts +178 -0
- package/src/stranded.ts +136 -0
- package/src/templates.ts +596 -0
- package/src/title.ts +97 -0
- package/src/verdict.ts +88 -0
- package/src/version-number.ts +67 -0
- package/src/version-pr.ts +103 -0
package/src/templates.ts
ADDED
|
@@ -0,0 +1,596 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The exact shapes the pipeline writes to GitHub. `docs/templates/` is the
|
|
3
|
+
* source of truth for these; change it there first.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { UNCHECKED_BOX } from "./acceptance-criteria.js";
|
|
7
|
+
import type { GuardReason } from "./guards.js";
|
|
8
|
+
import type { HostKind } from "./host.js";
|
|
9
|
+
import type { FailurePoint } from "./lifecycle.js";
|
|
10
|
+
import type { NoteText, NotingStage, RoutedNote } from "./notes.js";
|
|
11
|
+
import type { TicketOutcome } from "./orchestrator.js";
|
|
12
|
+
import type { IssueComment, SquashCommit } from "./ports/tracker.js";
|
|
13
|
+
import type { KeptTranscripts } from "./ports/workspace.js";
|
|
14
|
+
import type { RunStop } from "./run.js";
|
|
15
|
+
import { type Criterion, type Verdict, countStatuses } from "./verdict.js";
|
|
16
|
+
|
|
17
|
+
/** How the pipeline finds its own hand-off comment again. */
|
|
18
|
+
export const HANDOFF_MARKER = "<!-- ticket-runner:handoff -->";
|
|
19
|
+
|
|
20
|
+
/** What a Note comment is signed with. Nothing looks it up; a human reads it. */
|
|
21
|
+
export const NOTE_MARKER = "<!-- ticket-runner:note -->";
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* How the pipeline finds the standing Notes issue again.
|
|
25
|
+
*
|
|
26
|
+
* Distinct from {@link NOTE_MARKER}, which signs the Note comments this issue
|
|
27
|
+
* collects: one marks the container, the other marks what is in it, and a
|
|
28
|
+
* lookup that confused them would write Notes into a Note.
|
|
29
|
+
*
|
|
30
|
+
* It sits in the issue's body rather than in a comment, which is the one place
|
|
31
|
+
* a marker survives a human tidying the thread, and it is the only thing the
|
|
32
|
+
* lookup trusts. The title is a fast path and nothing more.
|
|
33
|
+
*/
|
|
34
|
+
export const NOTES_ISSUE_MARKER = "<!-- ticket-runner:notes-issue -->";
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* The title the standing Notes issue is opened with.
|
|
38
|
+
*
|
|
39
|
+
* Written once, at the moment it is opened, and never rewritten: a human who
|
|
40
|
+
* renames it has said something about this issue, and the marker still finds
|
|
41
|
+
* it.
|
|
42
|
+
*/
|
|
43
|
+
export const NOTES_ISSUE_TITLE = "Notes from the pipeline";
|
|
44
|
+
|
|
45
|
+
/** How the pipeline finds a warning it has already posted: one marker per reason. */
|
|
46
|
+
export function guardMarker(reason: GuardReason): string {
|
|
47
|
+
return `<!-- ticket-runner:guard:${reason} -->`;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** What each guard tells the human: what was wrong, and what to do about it. */
|
|
51
|
+
const GUARD_SENTENCES: Record<GuardReason, string> = {
|
|
52
|
+
spec:
|
|
53
|
+
"This issue has sub-issues, so it is a Spec, not a Ticket; `ready-for-agent` " +
|
|
54
|
+
"was removed. Its Tickets are picked up individually.",
|
|
55
|
+
"no-criteria":
|
|
56
|
+
"No `- [ ]` acceptance criteria found in the body or comments. Add criteria " +
|
|
57
|
+
"the verify Stage can grade, then re-run.",
|
|
58
|
+
"body-only-blockers":
|
|
59
|
+
"The body lists blockers that have no native `blocked by` edge. Add the edges " +
|
|
60
|
+
"with `gh issue edit <n> --add-blocked-by <m>`, then re-run.",
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Every comment carrying `marker`, oldest first.
|
|
65
|
+
*
|
|
66
|
+
* The marker is the first line of every pipeline comment and never changes,
|
|
67
|
+
* which is the whole point of it: this is how the pipeline finds what it has
|
|
68
|
+
* already written rather than writing it again. Most markers are on one comment
|
|
69
|
+
* per Ticket, but a hand-off is a comment of its own every time a Ticket is
|
|
70
|
+
* handed off, so the marker alone does not promise there is only one.
|
|
71
|
+
*/
|
|
72
|
+
export function findMarkedComments(comments: IssueComment[], marker: string): IssueComment[] {
|
|
73
|
+
return comments.filter((comment) => carriesMarker(comment.body, marker));
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** Whether a body opens with `marker`, which is the whole of how one is read. */
|
|
77
|
+
function carriesMarker(body: string, marker: string): boolean {
|
|
78
|
+
return body.trimStart().startsWith(marker);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* The newest comment carrying `marker`, for the markers one comment wears at a
|
|
83
|
+
* time.
|
|
84
|
+
*
|
|
85
|
+
* The newest rather than the first, because "one at a time" is not "one ever": a
|
|
86
|
+
* Ticket taken back from a human starts a progress comment of its own beside the
|
|
87
|
+
* table the human read, and the Run writing now must edit the one it just
|
|
88
|
+
* posted rather than the one it deliberately left alone.
|
|
89
|
+
*/
|
|
90
|
+
export function findMarkedComment(
|
|
91
|
+
comments: IssueComment[],
|
|
92
|
+
marker: string,
|
|
93
|
+
): IssueComment | undefined {
|
|
94
|
+
return findMarkedComments(comments, marker).at(-1);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** Whether a candidate has already been warned about this. */
|
|
98
|
+
export function hasGuardWarning(comments: IssueComment[], reason: GuardReason): boolean {
|
|
99
|
+
return findMarkedComment(comments, guardMarker(reason)) !== undefined;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** The one warning a skipped candidate gets. Two sentences: the reason, the fix. */
|
|
103
|
+
export function guardComment(reason: GuardReason): string {
|
|
104
|
+
return [
|
|
105
|
+
guardMarker(reason),
|
|
106
|
+
`**Skipped by ticket-runner.** ${GUARD_SENTENCES[reason]}`,
|
|
107
|
+
"",
|
|
108
|
+
].join("\n");
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** The Verdict summary both the pull request body and the squash commit carry. */
|
|
112
|
+
function verdictCounts(verdict: Verdict): string {
|
|
113
|
+
const counts = countStatuses(verdict);
|
|
114
|
+
return `${counts.met} met · ${counts.unmet} unmet · ${counts.unverifiable} unverifiable`;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
const STATUS_ICON: Record<Criterion["status"], string> = {
|
|
118
|
+
met: "✅",
|
|
119
|
+
unmet: "❌",
|
|
120
|
+
unverifiable: "❓",
|
|
121
|
+
};
|
|
122
|
+
|
|
123
|
+
export interface PullRequestBody {
|
|
124
|
+
ticket: number;
|
|
125
|
+
verdict: Verdict;
|
|
126
|
+
runId: string;
|
|
127
|
+
/** The Host the Run is on, which decides whether its run directory is worth naming. */
|
|
128
|
+
host: HostKind;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
export function pullRequestBody({ ticket, verdict, runId, host }: PullRequestBody): string {
|
|
132
|
+
const criteria = verdict.criteria.map((criterion) => {
|
|
133
|
+
const line = `- ${STATUS_ICON[criterion.status]} ${criterion.text}`;
|
|
134
|
+
return criterion.status === "met" ? line : `${line} — ${criterion.evidence}`;
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
// A merged Ticket keeps no transcripts on the remote, so the run directory is
|
|
138
|
+
// the only place they are, and a cloud Host's goes with its session.
|
|
139
|
+
const where =
|
|
140
|
+
host === "workstation" ? `\`.ticket-runner/runs/${runId}/${ticket}/\`` : undefined;
|
|
141
|
+
|
|
142
|
+
return [
|
|
143
|
+
`Closes #${ticket}`,
|
|
144
|
+
"",
|
|
145
|
+
`**Verdict:** ${verdictCounts(verdict)}`,
|
|
146
|
+
"",
|
|
147
|
+
"<details><summary>Criteria</summary>",
|
|
148
|
+
"",
|
|
149
|
+
...criteria,
|
|
150
|
+
"",
|
|
151
|
+
"</details>",
|
|
152
|
+
"",
|
|
153
|
+
runLine(runId, where),
|
|
154
|
+
"",
|
|
155
|
+
].join("\n");
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
export interface DraftPullRequestBody {
|
|
159
|
+
ticket: number;
|
|
160
|
+
stage: FailurePoint;
|
|
161
|
+
failure: string;
|
|
162
|
+
runId: string;
|
|
163
|
+
/** Where the hand-off kept the Stages' transcripts on the remote, when it kept any. */
|
|
164
|
+
transcripts?: KeptTranscripts;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* The body of the draft PR a hand-off leaves behind, whether it opened the PR
|
|
169
|
+
* or made an open one a draft: what a human needs from it is the hand-off, not
|
|
170
|
+
* a Verdict.
|
|
171
|
+
*/
|
|
172
|
+
export function draftPullRequestBody({
|
|
173
|
+
ticket,
|
|
174
|
+
stage,
|
|
175
|
+
failure,
|
|
176
|
+
runId,
|
|
177
|
+
transcripts,
|
|
178
|
+
}: DraftPullRequestBody): string {
|
|
179
|
+
return [
|
|
180
|
+
`Closes #${ticket}`,
|
|
181
|
+
"",
|
|
182
|
+
`**Handed off at ${stage}.** ${failure}`,
|
|
183
|
+
"",
|
|
184
|
+
`See the hand-off comment on #${ticket} for the branch, worktree and evidence.`,
|
|
185
|
+
"",
|
|
186
|
+
runLine(runId, transcripts === undefined ? undefined : keptPlace(transcripts)),
|
|
187
|
+
"",
|
|
188
|
+
].join("\n");
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* The line both pull request bodies end with: the Run, and where its
|
|
193
|
+
* transcripts are when there is somewhere that outlives the Host to point at.
|
|
194
|
+
*/
|
|
195
|
+
function runLine(runId: string, where: string | undefined): string {
|
|
196
|
+
const run = `Run \`${runId}\``;
|
|
197
|
+
return where === undefined ? run : `${run} · transcripts in ${where}`;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/** Where a hand-off kept the transcripts, as every shape that names it spells it. */
|
|
201
|
+
function keptPlace(transcripts: KeptTranscripts): string {
|
|
202
|
+
return `\`${transcripts.path}\` on the \`${transcripts.branch}\` branch`;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
export interface SquashCommitMessage {
|
|
206
|
+
ticket: number;
|
|
207
|
+
/** The pull request number, appended to the subject as GitHub would. */
|
|
208
|
+
pullRequest: number;
|
|
209
|
+
/** The pull request title, which is the subject that lands on the base branch. */
|
|
210
|
+
title: string;
|
|
211
|
+
verdict: Verdict;
|
|
212
|
+
/** The branch's commit subjects, oldest first. */
|
|
213
|
+
commits: string[];
|
|
214
|
+
/** Unique `Co-authored-by` values from the branch, carried as trailers. */
|
|
215
|
+
coAuthors: string[];
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* The commit a merged Ticket leaves on the base branch.
|
|
220
|
+
*
|
|
221
|
+
* `git log` renders no HTML, so this is the one template with nothing folded
|
|
222
|
+
* away: the Verdict is counts only, and the per-criterion evidence stays in the
|
|
223
|
+
* pull request body where a browser can collapse it.
|
|
224
|
+
*/
|
|
225
|
+
export function squashCommit({
|
|
226
|
+
ticket,
|
|
227
|
+
pullRequest,
|
|
228
|
+
title,
|
|
229
|
+
verdict,
|
|
230
|
+
commits,
|
|
231
|
+
coAuthors,
|
|
232
|
+
}: SquashCommitMessage): SquashCommit {
|
|
233
|
+
// What GitHub's default message would have carried, now carried by hand.
|
|
234
|
+
const trailers = coAuthors.map((author) => `Co-authored-by: ${author}`);
|
|
235
|
+
return {
|
|
236
|
+
subject: `${title} (#${pullRequest})`,
|
|
237
|
+
body: [
|
|
238
|
+
`Closes #${ticket}`,
|
|
239
|
+
"",
|
|
240
|
+
`Verdict: ${verdictCounts(verdict)}`,
|
|
241
|
+
"",
|
|
242
|
+
...commits.map((subject) => `- ${subject}`),
|
|
243
|
+
"",
|
|
244
|
+
...(trailers.length === 0 ? [] : [...trailers, ""]),
|
|
245
|
+
].join("\n"),
|
|
246
|
+
};
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
export interface HandoffComment {
|
|
250
|
+
stage: FailurePoint;
|
|
251
|
+
/** One line a human can read in a notification. */
|
|
252
|
+
failure: string;
|
|
253
|
+
branch: string;
|
|
254
|
+
/**
|
|
255
|
+
* Whether the remote has the branch, which is where the work still is once
|
|
256
|
+
* the Host that did it is gone. Said only when it is so.
|
|
257
|
+
*/
|
|
258
|
+
onRemote?: boolean;
|
|
259
|
+
/**
|
|
260
|
+
* Where the work is, left out when there is no worktree to send anyone to:
|
|
261
|
+
* a Ticket that failed at setup never had one created, and a path that is not
|
|
262
|
+
* on disk reads as if something else had gone wrong.
|
|
263
|
+
*/
|
|
264
|
+
worktree?: string;
|
|
265
|
+
pullRequest?: number;
|
|
266
|
+
/** Failing Check output, unmet criteria, or a CI log excerpt. */
|
|
267
|
+
evidence: string;
|
|
268
|
+
/** Whether the Ticket's fix budget had already been spent when this failure came. */
|
|
269
|
+
fixUsed?: boolean;
|
|
270
|
+
/** Where the Stages' transcripts were kept on the remote, when any were. */
|
|
271
|
+
transcripts?: KeptTranscripts;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
export function handoffComment(handoff: HandoffComment): string {
|
|
275
|
+
const location = [
|
|
276
|
+
`Branch \`${handoff.branch}\`${handoff.onRemote === true ? " on the remote" : ""}`,
|
|
277
|
+
...(handoff.worktree === undefined ? [] : [`worktree \`${handoff.worktree}\``]),
|
|
278
|
+
...(handoff.pullRequest === undefined ? [] : [`PR #${handoff.pullRequest} (draft)`]),
|
|
279
|
+
].join(" · ");
|
|
280
|
+
|
|
281
|
+
// The budget clause is the difference between one bad Stage and a Ticket the
|
|
282
|
+
// pipeline already had a second go at, which is what a human needs to know.
|
|
283
|
+
const budget = handoff.fixUsed ? ", after the fix budget was used" : "";
|
|
284
|
+
|
|
285
|
+
const lines = [
|
|
286
|
+
HANDOFF_MARKER,
|
|
287
|
+
`**Handed off.** Failed at **${handoff.stage}**${budget}.`,
|
|
288
|
+
"",
|
|
289
|
+
`- Failure: ${handoff.failure}`,
|
|
290
|
+
`- ${location}`,
|
|
291
|
+
...(handoff.transcripts === undefined
|
|
292
|
+
? []
|
|
293
|
+
: [`- Transcripts: ${keptPlace(handoff.transcripts)}`]),
|
|
294
|
+
"",
|
|
295
|
+
];
|
|
296
|
+
|
|
297
|
+
const evidence = handoff.evidence.trim();
|
|
298
|
+
if (evidence !== "") {
|
|
299
|
+
lines.push(
|
|
300
|
+
"<details><summary>Evidence</summary>",
|
|
301
|
+
"",
|
|
302
|
+
"```",
|
|
303
|
+
evidence,
|
|
304
|
+
"```",
|
|
305
|
+
"",
|
|
306
|
+
"</details>",
|
|
307
|
+
"",
|
|
308
|
+
);
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
return lines.join("\n");
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
/**
|
|
315
|
+
* What a hand-off comment gains when the pipeline takes the Ticket on again.
|
|
316
|
+
*
|
|
317
|
+
* Under the marker rather than at the end, so a reader meets it before the
|
|
318
|
+
* failure it qualifies, and italic so it reads as the pipeline talking about
|
|
319
|
+
* the comment rather than as another line of the hand-off.
|
|
320
|
+
*/
|
|
321
|
+
export const HANDOFF_TAKEN_LINE = "_Taken again by a later Run; this hand-off is history._";
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* A hand-off comment with {@link HANDOFF_TAKEN_LINE} under its marker, or
|
|
325
|
+
* nothing when the comment already carries the line.
|
|
326
|
+
*
|
|
327
|
+
* Nothing else about the comment is touched: the failure, the location and the
|
|
328
|
+
* evidence are why the hand-off is worth keeping, and only their currency has
|
|
329
|
+
* changed. Nothing when there is nothing to add is how the caller knows to
|
|
330
|
+
* spend no tracker call on it, which is also what stops a Ticket claimed twice
|
|
331
|
+
* stacking the line.
|
|
332
|
+
*
|
|
333
|
+
* The line is looked for directly under the marker rather than anywhere in the
|
|
334
|
+
* comment, so evidence that happens to quote it is not read as a mark.
|
|
335
|
+
*/
|
|
336
|
+
export function handoffTakenComment(body: string): string | undefined {
|
|
337
|
+
const marked = `${HANDOFF_MARKER}\n${HANDOFF_TAKEN_LINE}`;
|
|
338
|
+
if (body.includes(marked)) return undefined;
|
|
339
|
+
return body.replace(HANDOFF_MARKER, `${marked}\n`);
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/** A Note, and where it came from, as the comment it becomes announces it. */
|
|
343
|
+
export interface NoteSubject {
|
|
344
|
+
/** The Ticket whose Stage made the finding. */
|
|
345
|
+
origin: number;
|
|
346
|
+
stage: NotingStage;
|
|
347
|
+
note: NoteText;
|
|
348
|
+
/**
|
|
349
|
+
* The Ticket this was meant to be a comment on, when that Ticket would not
|
|
350
|
+
* take it or nobody would read it there. Set only on a Note that fell back to
|
|
351
|
+
* the standing Notes issue, so triage can see the link the Note was reaching
|
|
352
|
+
* for.
|
|
353
|
+
*/
|
|
354
|
+
intended?: number;
|
|
355
|
+
/**
|
|
356
|
+
* Why `intended` did not get the comment, as the words after `which`: `is
|
|
357
|
+
* closed`, `is claimed`, `is a Spec`. Absent when the tracker refused the
|
|
358
|
+
* write, which is the one reason the pipeline cannot name.
|
|
359
|
+
*/
|
|
360
|
+
because?: string;
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
/** {@link UNCHECKED_BOX}, over every line of a Note rather than the first. */
|
|
364
|
+
const NOTE_CHECKBOX = new RegExp(UNCHECKED_BOX, "gm");
|
|
365
|
+
|
|
366
|
+
/**
|
|
367
|
+
* One part of a Note's prose, with every checkbox defused.
|
|
368
|
+
*
|
|
369
|
+
* `- [ ]` is Acceptance Criteria to everything that reads a Ticket: the
|
|
370
|
+
* `no-criteria` guard counts one as a usable Ticket, verify grades it, and the
|
|
371
|
+
* merge ticks it. A Note is prose a human should read, not work anyone
|
|
372
|
+
* promised, so its boxes are escaped into the text they were meant to be.
|
|
373
|
+
* Brackets anywhere but at the head of a list item are left alone, because that
|
|
374
|
+
* is the only shape those readers recognise.
|
|
375
|
+
*/
|
|
376
|
+
function escapeCheckboxes(note: string): string {
|
|
377
|
+
return note.replaceAll(NOTE_CHECKBOX, (_, bullet: string) => `${bullet}\\[ \\]`);
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/**
|
|
381
|
+
* Where the Note came from, in the one line every Note comment opens with.
|
|
382
|
+
*
|
|
383
|
+
* A Note that reached the standing Notes issue carries the Ticket it was
|
|
384
|
+
* reaching for and why that Ticket did not get it, because the comment is all
|
|
385
|
+
* triage has to go on: without the number, a finding about #7 read on the
|
|
386
|
+
* standing issue has lost the only thing that placed it.
|
|
387
|
+
*/
|
|
388
|
+
function noteProvenance({ origin, stage, intended, because }: NoteSubject): string {
|
|
389
|
+
const from = `From #${origin} ${stage}`;
|
|
390
|
+
if (intended === undefined) return from;
|
|
391
|
+
return `${from}, meant for #${intended}, which ${because ?? "would not take the comment"}`;
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
/**
|
|
395
|
+
* The labelled paragraph one part of a Note becomes, or nothing when the Stage
|
|
396
|
+
* left that part out or blank.
|
|
397
|
+
*/
|
|
398
|
+
function labelledPart(label: string, text: string | undefined): string[] {
|
|
399
|
+
if (text === undefined || text.trim() === "") return [];
|
|
400
|
+
return [`**${label}**: ${escapeCheckboxes(text.trim())}`];
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
/**
|
|
404
|
+
* One Note, as a comment on the Ticket it names or on the standing Notes issue:
|
|
405
|
+
* the summary in bold, then each part the Stage wrote under a label of its own.
|
|
406
|
+
*
|
|
407
|
+
* The summary is folded onto one line so the bold around it holds: a blank
|
|
408
|
+
* line inside it would end the paragraph and leave the asterisks showing.
|
|
409
|
+
*/
|
|
410
|
+
export function noteComment(subject: NoteSubject): string {
|
|
411
|
+
const { summary, evidence, impact, next } = subject.note;
|
|
412
|
+
const paragraphs = [
|
|
413
|
+
`**${escapeCheckboxes(summary.trim().replaceAll(/\s+/g, " "))}**`,
|
|
414
|
+
...labelledPart("Evidence", evidence),
|
|
415
|
+
...labelledPart("Impact", impact),
|
|
416
|
+
...labelledPart("Next", next),
|
|
417
|
+
];
|
|
418
|
+
return [NOTE_MARKER, noteProvenance(subject), "", paragraphs.join("\n\n"), ""].join("\n");
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
/** Whether an issue's body says it is the standing Notes issue. */
|
|
422
|
+
export function isNotesIssue(body: string): boolean {
|
|
423
|
+
return carriesMarker(body, NOTES_ISSUE_MARKER);
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/**
|
|
427
|
+
* The standing Notes issue, as the Note that needed one opens it. The label is
|
|
428
|
+
* the caller's.
|
|
429
|
+
*
|
|
430
|
+
* Fixed text: the Notes themselves are comments under it, and nothing the
|
|
431
|
+
* pipeline writes afterwards touches this body. What is written here is for
|
|
432
|
+
* triage — what the issue is, and what emptying it means — because a human
|
|
433
|
+
* meeting an issue the pipeline opened by itself is owed both.
|
|
434
|
+
*/
|
|
435
|
+
export function notesIssue(): { title: string; body: string } {
|
|
436
|
+
return {
|
|
437
|
+
title: NOTES_ISSUE_TITLE,
|
|
438
|
+
body: [
|
|
439
|
+
NOTES_ISSUE_MARKER,
|
|
440
|
+
"**Notes from the pipeline.** Every finding a Stage could not post on a " +
|
|
441
|
+
"Ticket arrives here as a comment: one that named no Ticket, one whose " +
|
|
442
|
+
"Ticket would have buried it, and one whose Ticket refused the comment. " +
|
|
443
|
+
"Each comment says which Ticket and Stage found it.",
|
|
444
|
+
"",
|
|
445
|
+
"Triage empties this issue by hand: promote what deserves a Ticket, record " +
|
|
446
|
+
"the promotion in this body, and close the issue once the body accounts " +
|
|
447
|
+
"for every comment. The next Note after that opens a fresh one, so only " +
|
|
448
|
+
"ever one of these is open.",
|
|
449
|
+
"",
|
|
450
|
+
].join("\n"),
|
|
451
|
+
};
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
export interface RunSummary {
|
|
455
|
+
/** The Version the Run ran, which is what its transcripts are stamped with. */
|
|
456
|
+
version: string;
|
|
457
|
+
runId: string;
|
|
458
|
+
durationMs: number;
|
|
459
|
+
outcomes: TicketOutcome[];
|
|
460
|
+
/**
|
|
461
|
+
* The line saying a newer Version is out, where one is. Above the header
|
|
462
|
+
* rather than below it: the Run already said this hours ago, at the top of a
|
|
463
|
+
* log this summary is the bottom of (ADR-0007).
|
|
464
|
+
*/
|
|
465
|
+
newer?: string;
|
|
466
|
+
/** Why the Run stopped, and with it whatever it can still say about the Frontier. */
|
|
467
|
+
stop: RunStop;
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
/** Every summary row is `<verb> #<n> <detail>`, so the numbers line up. */
|
|
471
|
+
const VERB_WIDTH = 9;
|
|
472
|
+
|
|
473
|
+
/**
|
|
474
|
+
* What a Run prints when it ends. One line per Ticket, then why the Run
|
|
475
|
+
* stopped — the Frontier is empty, everything left on it is blocked, the rate
|
|
476
|
+
* limit released a Ticket and the Run went no further, or a human stopped it.
|
|
477
|
+
*/
|
|
478
|
+
export function runSummary({
|
|
479
|
+
version,
|
|
480
|
+
runId,
|
|
481
|
+
durationMs,
|
|
482
|
+
outcomes,
|
|
483
|
+
newer,
|
|
484
|
+
stop,
|
|
485
|
+
}: RunSummary): string {
|
|
486
|
+
const rows = [
|
|
487
|
+
...outcomes.flatMap(ticketRows),
|
|
488
|
+
// Only a Run that reached the end of the Frontier can name what was held
|
|
489
|
+
// back all Run, so only that stop carries candidates to skip.
|
|
490
|
+
...(stop.reason === "frontier"
|
|
491
|
+
? stop.blocked.map((ticket) => row("skipped", ticket, "blocked"))
|
|
492
|
+
: []),
|
|
493
|
+
];
|
|
494
|
+
|
|
495
|
+
return [
|
|
496
|
+
...(newer === undefined ? [] : [newer]),
|
|
497
|
+
`ticket-runner ${version} run ${runId} · ${Math.round(durationMs / 60_000)}m`,
|
|
498
|
+
"",
|
|
499
|
+
...(rows.length === 0 ? [" nothing to do"] : rows),
|
|
500
|
+
"",
|
|
501
|
+
lastLine(stop),
|
|
502
|
+
"",
|
|
503
|
+
].join("\n");
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
/** The one line that says why the Run stopped. */
|
|
507
|
+
function lastLine(stop: RunStop): string {
|
|
508
|
+
switch (stop.reason) {
|
|
509
|
+
case "rate-limited":
|
|
510
|
+
return "Rate limited.";
|
|
511
|
+
case "stopped":
|
|
512
|
+
return `Stopped at ${clockTime(stop.at)} · ${holding(stop.busy)}.`;
|
|
513
|
+
case "frontier":
|
|
514
|
+
return stop.blocked.length === 0 ? "Frontier empty." : "Frontier blocked.";
|
|
515
|
+
}
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
/**
|
|
519
|
+
* The minute a Stop arrived, in UTC — the clock the run id on the first line of
|
|
520
|
+
* the summary is already written in, so the two can be read against each other.
|
|
521
|
+
*/
|
|
522
|
+
function clockTime(at: string): string {
|
|
523
|
+
return at.slice(11, 16);
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
/** What the Lanes were holding when the Stop arrived, and what to call none. */
|
|
527
|
+
function holding(busy: number[]): string {
|
|
528
|
+
if (busy.length === 0) return "nothing to finish";
|
|
529
|
+
return `finishing ${busy.map((ticket) => `#${ticket}`).join(" ")}`;
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
/**
|
|
533
|
+
* One Ticket's lines: what happened to it, then every Note its Stages made.
|
|
534
|
+
*
|
|
535
|
+
* The Notes follow their own Ticket rather than being gathered at the end, so a
|
|
536
|
+
* Run that took six Tickets still says which one noticed what.
|
|
537
|
+
*/
|
|
538
|
+
function ticketRows(outcome: TicketOutcome): string[] {
|
|
539
|
+
return [
|
|
540
|
+
ticketRow(outcome),
|
|
541
|
+
...(outcome.outcome === "skipped" ? [] : outcome.notes.map(noteRow)),
|
|
542
|
+
];
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
/** A Note summary's opening line, which is as much of it as a Run summary has room for. */
|
|
546
|
+
function firstLine(text: string): string {
|
|
547
|
+
return (text.split("\n").find((line) => line.trim() !== "") ?? "").trim();
|
|
548
|
+
}
|
|
549
|
+
|
|
550
|
+
/** `text`, or as much of it as fits with an ellipsis standing in for the rest. */
|
|
551
|
+
function truncate(text: string, limit: number): string {
|
|
552
|
+
return text.length <= limit ? text : `${text.slice(0, limit - 1).trimEnd()}\u2026`;
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
/**
|
|
556
|
+
* How much of a Note a summary line shows before pointing at GitHub for the
|
|
557
|
+
* rest. Chosen so a `noted` row is no longer than the Ticket rows it sits
|
|
558
|
+
* among, which is what makes the column of numbers worth lining up.
|
|
559
|
+
*/
|
|
560
|
+
const NOTE_WIDTH = 40;
|
|
561
|
+
|
|
562
|
+
/** One Note's line: where it went, where it came from, and the gist of it. */
|
|
563
|
+
function noteRow({ origin, stage, issue, opened, summary }: RoutedNote): string {
|
|
564
|
+
const destination = opened ? "new" : "comment";
|
|
565
|
+
return row(
|
|
566
|
+
"noted",
|
|
567
|
+
issue,
|
|
568
|
+
`${destination} · from #${origin} ${stage} · ${truncate(firstLine(summary), NOTE_WIDTH)}`,
|
|
569
|
+
);
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
/** One Ticket's line in a summary: what happened to it, and where to look. */
|
|
573
|
+
function ticketRow(outcome: TicketOutcome): string {
|
|
574
|
+
switch (outcome.outcome) {
|
|
575
|
+
case "merged":
|
|
576
|
+
return row("merged", outcome.ticket, `${outcome.title} (PR #${outcome.pullRequest})`);
|
|
577
|
+
case "handed-off":
|
|
578
|
+
return row(
|
|
579
|
+
"handed",
|
|
580
|
+
outcome.ticket,
|
|
581
|
+
`${outcome.title} · ${outcome.stage} · ${outcome.failure}`,
|
|
582
|
+
);
|
|
583
|
+
case "released":
|
|
584
|
+
// Nothing for a human to do, so the row says only where the limit landed
|
|
585
|
+
// and leaves the rest to the Run that resumes the Ticket.
|
|
586
|
+
return row("released", outcome.ticket, `${outcome.title} · rate limit at ${outcome.stage}`);
|
|
587
|
+
case "skipped":
|
|
588
|
+
// The reason is the guard's own word for it, which is also the marker on
|
|
589
|
+
// the warning comment the human is being pointed at.
|
|
590
|
+
return row("skipped", outcome.ticket, outcome.reason);
|
|
591
|
+
}
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
function row(verb: string, ticket: number, detail: string): string {
|
|
595
|
+
return ` ${verb.padEnd(VERB_WIDTH)}#${ticket} ${detail}`;
|
|
596
|
+
}
|
package/src/title.ts
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a pipeline pull request is titled, which is also the subject of the
|
|
3
|
+
* squash commit that lands on the base branch.
|
|
4
|
+
*
|
|
5
|
+
* The two Stages that write code each answer a `title` for the whole branch as
|
|
6
|
+
* it stands when they finish, and the latest one that counts is the title. It
|
|
7
|
+
* is asked for as an answer rather than read off a commit because a commit
|
|
8
|
+
* subject describes its own commit: a fix Stage that did most of a Ticket's
|
|
9
|
+
* work could not retitle a branch whose first commit was already pushed without
|
|
10
|
+
* rewriting it.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { NOTES_LIST_SCHEMA } from "./note-schema.js";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* What a title is asked to be, in the words both the schema and the prompts of
|
|
17
|
+
* the code Stages use: one declaration, so the two cannot drift apart.
|
|
18
|
+
*/
|
|
19
|
+
export const BRANCH_TITLE =
|
|
20
|
+
"one line summarising the whole branch as it stands when you finish, the work of any Stage before you included";
|
|
21
|
+
|
|
22
|
+
/** Any `<type>(<scope>): <summary>`; the repo's own types and scopes are CONTRIBUTING.md's business. */
|
|
23
|
+
const CONVENTIONAL_SUBJECT = /^[a-z]+(\([a-z0-9._-]+\))?: \S/;
|
|
24
|
+
|
|
25
|
+
/** The `(#<n>)` a branch commit carries, which the squash commit's `Closes #<n>` replaces. */
|
|
26
|
+
const TICKET_REFERENCE = /\s*\(#\d+\)$/;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* The `--json-schema` the implement and fix Stages are invoked with: the title
|
|
30
|
+
* of the whole branch, and the Notes channel beside it.
|
|
31
|
+
*
|
|
32
|
+
* Both are required, so a Stage always says something about each: an empty
|
|
33
|
+
* Notes list when it found nothing, and a title however little it did. The
|
|
34
|
+
* parsers forgive either one on its own ({@link parseTitle} and `parseNotes`),
|
|
35
|
+
* so a bad title never costs the Notes and bad Notes never cost the title.
|
|
36
|
+
*/
|
|
37
|
+
export const CODE_STAGE_JSON_SCHEMA = {
|
|
38
|
+
type: "object",
|
|
39
|
+
properties: {
|
|
40
|
+
title: {
|
|
41
|
+
type: "string",
|
|
42
|
+
description: `Write ${BRANCH_TITLE}: \`<type>(<scope>): <summary>\`, without the \`(#<n>)\`. It titles the pull request and the squash commit that lands.`,
|
|
43
|
+
},
|
|
44
|
+
notes: NOTES_LIST_SCHEMA,
|
|
45
|
+
},
|
|
46
|
+
required: ["title", "notes"],
|
|
47
|
+
additionalProperties: false,
|
|
48
|
+
} as const;
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* A title as it would land, or nothing when it does not count: one line in the
|
|
52
|
+
* commit convention's shape.
|
|
53
|
+
*
|
|
54
|
+
* A trailing `(#<n>)` is taken off rather than held against it, as it is off a
|
|
55
|
+
* commit subject, since the squash commit appends the pull request's own.
|
|
56
|
+
*/
|
|
57
|
+
function asTitle(candidate: string): string | undefined {
|
|
58
|
+
const title = candidate.trim().replace(TICKET_REFERENCE, "");
|
|
59
|
+
if (title.includes("\n")) return undefined;
|
|
60
|
+
return CONVENTIONAL_SUBJECT.test(title) ? title : undefined;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* The title in a Stage's structured output, when it answered one that counts.
|
|
65
|
+
*
|
|
66
|
+
* Forgiving, as the Notes beside it are: output that is not an object, a
|
|
67
|
+
* missing or blank title and one outside the convention each cost the title
|
|
68
|
+
* alone, and the next candidate {@link pullRequestTitle} knows of is used.
|
|
69
|
+
*/
|
|
70
|
+
export function parseTitle(result: unknown): string | undefined {
|
|
71
|
+
if (typeof result !== "object" || result === null) return undefined;
|
|
72
|
+
const raw = (result as { title?: unknown }).title;
|
|
73
|
+
return typeof raw === "string" ? asTitle(raw) : undefined;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* The pull request title, in this order of preference: the latest title a
|
|
78
|
+
* Stage answered, whether in this Run or recorded by the one before it; the
|
|
79
|
+
* branch's first commit subject, which is what a Stage from before titles were
|
|
80
|
+
* asked for summarised the branch in; and the Ticket title.
|
|
81
|
+
*
|
|
82
|
+
* Each candidate counts only in the commit convention's shape. The Ticket title
|
|
83
|
+
* is the one subject on the base branch allowed not to be: a branch nothing
|
|
84
|
+
* wrote one conventional line about is not trusted to have one invented for it,
|
|
85
|
+
* and the Ticket title at least says what the work was.
|
|
86
|
+
*/
|
|
87
|
+
export function pullRequestTitle(
|
|
88
|
+
stageTitle: string | undefined,
|
|
89
|
+
commits: string[],
|
|
90
|
+
ticketTitle: string,
|
|
91
|
+
): string {
|
|
92
|
+
for (const candidate of [stageTitle, commits[0]]) {
|
|
93
|
+
const title = candidate === undefined ? undefined : asTitle(candidate);
|
|
94
|
+
if (title !== undefined) return title;
|
|
95
|
+
}
|
|
96
|
+
return ticketTitle;
|
|
97
|
+
}
|