ticket-runner 0.6.3 → 0.6.5
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/README.ko.md +4 -4
- package/README.md +3 -3
- package/docs/templates/operator-skill.md +7 -7
- package/package.json +1 -1
- package/src/acceptance-criteria.ts +2 -2
- package/src/adapters/claude-agent-runner.ts +49 -5
- package/src/adapters/exec.ts +19 -4
- package/src/adapters/gh-tracker.ts +17 -17
- package/src/adapters/git-workspace.ts +12 -8
- package/src/adapters/liveness.ts +77 -0
- package/src/adapters/process-tree.ts +4 -7
- package/src/adapters/version.ts +5 -5
- package/src/branch.ts +1 -1
- package/src/cli.ts +2 -2
- package/src/config.ts +7 -6
- package/src/conventions.ts +23 -20
- package/src/credential.ts +92 -7
- package/src/criteria.ts +107 -15
- package/src/failing-base.ts +7 -7
- package/src/failure-message.ts +72 -0
- package/src/guards.ts +2 -2
- package/src/handoff.ts +2 -2
- package/src/init.ts +8 -8
- package/src/landing.ts +1 -1
- package/src/lifecycle.ts +2 -2
- package/src/lock.ts +10 -2
- package/src/note-schema.ts +3 -3
- package/src/notes.ts +8 -6
- package/src/operator-skill.ts +2 -2
- package/src/orchestrator.ts +194 -144
- package/src/ports/agent-runner.ts +21 -1
- package/src/ports/tracker.ts +14 -13
- package/src/ports/workspace.ts +23 -22
- package/src/progress.ts +2 -2
- package/src/prompts.ts +74 -25
- package/src/readiness.ts +11 -11
- package/src/remove.ts +7 -7
- package/src/resume.ts +12 -12
- package/src/run-log.ts +5 -5
- package/src/run.ts +72 -10
- package/src/staleness.ts +14 -14
- package/src/start.ts +20 -15
- package/src/stranded.ts +19 -19
- package/src/templates.ts +191 -73
- package/src/timer.ts +25 -0
- package/src/title.ts +45 -9
- package/src/verdict.ts +7 -7
- package/src/version-number.ts +13 -13
- package/src/version-pr.ts +12 -12
package/src/templates.ts
CHANGED
|
@@ -4,9 +4,16 @@
|
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
6
|
import { UNCHECKED_BOX } from "./acceptance-criteria.js";
|
|
7
|
-
import {
|
|
7
|
+
import {
|
|
8
|
+
type Billing,
|
|
9
|
+
CREDENTIAL_WORDS,
|
|
10
|
+
type Credential,
|
|
11
|
+
type StrayStage,
|
|
12
|
+
emptyBilling,
|
|
13
|
+
} from "./credential.js";
|
|
8
14
|
import type { GuardReason } from "./guards.js";
|
|
9
15
|
import type { HostKind } from "./host.js";
|
|
16
|
+
import { splitMessage } from "./failure-message.js";
|
|
10
17
|
import type { FailurePoint } from "./lifecycle.js";
|
|
11
18
|
import { logTail } from "./log-tail.js";
|
|
12
19
|
import type { NoteText, NotingStage, RoutedNote } from "./notes.js";
|
|
@@ -110,7 +117,7 @@ export function guardComment(reason: GuardReason): string {
|
|
|
110
117
|
].join("\n");
|
|
111
118
|
}
|
|
112
119
|
|
|
113
|
-
/** The
|
|
120
|
+
/** The verdict summary both the pull request body and the squash commit carry. */
|
|
114
121
|
function verdictCounts(verdict: Verdict): string {
|
|
115
122
|
const counts = countStatuses(verdict);
|
|
116
123
|
return `${counts.met} met · ${counts.unmet} unmet · ${counts.unverifiable} unverifiable`;
|
|
@@ -160,6 +167,10 @@ export function pullRequestBody({ ticket, verdict, runId, host }: PullRequestBod
|
|
|
160
167
|
export interface DraftPullRequestBody {
|
|
161
168
|
ticket: number;
|
|
162
169
|
stage: FailurePoint;
|
|
170
|
+
/**
|
|
171
|
+
* As the hand-off comment's: one line, or an unexpected error's whole
|
|
172
|
+
* message, whose output the body shows as evidence the way the comment does.
|
|
173
|
+
*/
|
|
163
174
|
failure: string;
|
|
164
175
|
runId: string;
|
|
165
176
|
/** Where the hand-off kept the Stages' transcripts on the remote, when it kept any. */
|
|
@@ -167,9 +178,9 @@ export interface DraftPullRequestBody {
|
|
|
167
178
|
}
|
|
168
179
|
|
|
169
180
|
/**
|
|
170
|
-
* The body of the draft
|
|
171
|
-
* or made an open one a draft: what a human needs from
|
|
172
|
-
* a
|
|
181
|
+
* The body of the draft pull request a hand-off leaves behind, whether it
|
|
182
|
+
* opened the pull request or made an open one a draft: what a human needs from
|
|
183
|
+
* it is the hand-off, not a verdict.
|
|
173
184
|
*/
|
|
174
185
|
export function draftPullRequestBody({
|
|
175
186
|
ticket,
|
|
@@ -178,11 +189,13 @@ export function draftPullRequestBody({
|
|
|
178
189
|
runId,
|
|
179
190
|
transcripts,
|
|
180
191
|
}: DraftPullRequestBody): string {
|
|
192
|
+
const shown = failureShown(failure, "");
|
|
181
193
|
return [
|
|
182
194
|
`Closes #${ticket}`,
|
|
183
195
|
"",
|
|
184
|
-
`**Handed off at ${stage}.** ${
|
|
196
|
+
`**Handed off at ${stage}.** ${shown.line}`,
|
|
185
197
|
"",
|
|
198
|
+
...evidenceBlock(shown.evidence),
|
|
186
199
|
`See the hand-off comment on #${ticket} for the branch, worktree and evidence.`,
|
|
187
200
|
"",
|
|
188
201
|
runLine(runId, transcripts === undefined ? undefined : keptPlace(transcripts)),
|
|
@@ -190,6 +203,31 @@ export function draftPullRequestBody({
|
|
|
190
203
|
].join("\n");
|
|
191
204
|
}
|
|
192
205
|
|
|
206
|
+
/**
|
|
207
|
+
* A hand-off's failure as one line, and the evidence that goes with it.
|
|
208
|
+
*
|
|
209
|
+
* The failures the pipeline expects already come as one line and their output
|
|
210
|
+
* as evidence. An unexpected error comes as its message whole — the command,
|
|
211
|
+
* how it exited, and everything it printed — so its first line is the failure
|
|
212
|
+
* and the rest is evidence, ahead of any the hand-off carried already.
|
|
213
|
+
*/
|
|
214
|
+
function failureShown(failure: string, evidence: string): { line: string; evidence: string } {
|
|
215
|
+
const { line, output } = splitMessage(failure);
|
|
216
|
+
return {
|
|
217
|
+
line,
|
|
218
|
+
evidence: [output, evidence.trim()].filter((part) => part !== "").join("\n\n"),
|
|
219
|
+
};
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Evidence folded away and fenced, because it is raw output that would
|
|
224
|
+
* otherwise be read as Markdown; nothing at all when there is none.
|
|
225
|
+
*/
|
|
226
|
+
function evidenceBlock(evidence: string): string[] {
|
|
227
|
+
if (evidence === "") return [];
|
|
228
|
+
return ["<details><summary>Evidence</summary>", "", "```", evidence, "```", "", "</details>", ""];
|
|
229
|
+
}
|
|
230
|
+
|
|
193
231
|
/**
|
|
194
232
|
* The line both pull request bodies end with: the Run, and where its
|
|
195
233
|
* transcripts are when there is somewhere that outlives the Host to point at.
|
|
@@ -221,7 +259,7 @@ export interface SquashCommitMessage {
|
|
|
221
259
|
* The commit a merged Ticket leaves on the base branch.
|
|
222
260
|
*
|
|
223
261
|
* `git log` renders no HTML, so this is the one template with nothing folded
|
|
224
|
-
* away: the
|
|
262
|
+
* away: the verdict is counts only, and the per-criterion evidence stays in the
|
|
225
263
|
* pull request body where a browser can collapse it.
|
|
226
264
|
*/
|
|
227
265
|
export function squashCommit({
|
|
@@ -250,7 +288,10 @@ export function squashCommit({
|
|
|
250
288
|
|
|
251
289
|
export interface HandoffComment {
|
|
252
290
|
stage: FailurePoint;
|
|
253
|
-
/**
|
|
291
|
+
/**
|
|
292
|
+
* One line a human can read in a notification, or an unexpected error's
|
|
293
|
+
* whole message, whose first line is shown here and the rest as evidence.
|
|
294
|
+
*/
|
|
254
295
|
failure: string;
|
|
255
296
|
branch: string;
|
|
256
297
|
/**
|
|
@@ -271,6 +312,12 @@ export interface HandoffComment {
|
|
|
271
312
|
fixUsed?: boolean;
|
|
272
313
|
/** Where the Stages' transcripts were kept on the remote, when any were. */
|
|
273
314
|
transcripts?: KeptTranscripts;
|
|
315
|
+
/**
|
|
316
|
+
* Why the Stage this hand-off is for committed nothing, as it answered it in
|
|
317
|
+
* `noCommitReason`. Set only for an implement or fix Stage that finished and
|
|
318
|
+
* left no new commit, which is the one hand-off the reason explains.
|
|
319
|
+
*/
|
|
320
|
+
reason?: string;
|
|
274
321
|
}
|
|
275
322
|
|
|
276
323
|
export function handoffComment(handoff: HandoffComment): string {
|
|
@@ -284,33 +331,33 @@ export function handoffComment(handoff: HandoffComment): string {
|
|
|
284
331
|
// pipeline already had a second go at, which is what a human needs to know.
|
|
285
332
|
const budget = handoff.fixUsed ? ", after the fix budget was used" : "";
|
|
286
333
|
|
|
287
|
-
const
|
|
334
|
+
const shown = failureShown(handoff.failure, handoff.evidence);
|
|
335
|
+
return [
|
|
288
336
|
HANDOFF_MARKER,
|
|
289
337
|
`**Handed off.** Failed at **${handoff.stage}**${budget}.`,
|
|
290
338
|
"",
|
|
291
|
-
`- Failure: ${
|
|
339
|
+
`- Failure: ${shown.line}`,
|
|
292
340
|
`- ${location}`,
|
|
293
341
|
...(handoff.transcripts === undefined
|
|
294
342
|
? []
|
|
295
343
|
: [`- Transcripts: ${keptPlace(handoff.transcripts)}`]),
|
|
296
344
|
"",
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
lines.push(
|
|
302
|
-
"<details><summary>Evidence</summary>",
|
|
303
|
-
"",
|
|
304
|
-
"```",
|
|
305
|
-
evidence,
|
|
306
|
-
"```",
|
|
307
|
-
"",
|
|
308
|
-
"</details>",
|
|
309
|
-
"",
|
|
310
|
-
);
|
|
311
|
-
}
|
|
345
|
+
...stageSaid(handoff.stage, handoff.reason),
|
|
346
|
+
...evidenceBlock(shown.evidence),
|
|
347
|
+
].join("\n");
|
|
348
|
+
}
|
|
312
349
|
|
|
313
|
-
|
|
350
|
+
/**
|
|
351
|
+
* The reason a Stage gave for committing nothing, as a paragraph of its own
|
|
352
|
+
* between the hand-off's lines and its folded evidence, so a human reads it
|
|
353
|
+
* without unfolding anything; nothing when it gave none.
|
|
354
|
+
*
|
|
355
|
+
* The Stage's prose is posted on the Ticket, whose comments are read for
|
|
356
|
+
* Acceptance Criteria, so its checkboxes are defused as a Note's are.
|
|
357
|
+
*/
|
|
358
|
+
function stageSaid(stage: FailurePoint, reason: string | undefined): string[] {
|
|
359
|
+
if (reason === undefined || reason.trim() === "") return [];
|
|
360
|
+
return [`**The ${stage} Stage said:** ${escapeCheckboxes(reason.trim())}`, ""];
|
|
314
361
|
}
|
|
315
362
|
|
|
316
363
|
/**
|
|
@@ -362,21 +409,22 @@ export interface NoteSubject {
|
|
|
362
409
|
because?: string;
|
|
363
410
|
}
|
|
364
411
|
|
|
365
|
-
/** {@link UNCHECKED_BOX}, over every line of a
|
|
366
|
-
const
|
|
412
|
+
/** {@link UNCHECKED_BOX}, over every line of a Stage's prose rather than the first. */
|
|
413
|
+
const PROSE_CHECKBOX = new RegExp(UNCHECKED_BOX, "gm");
|
|
367
414
|
|
|
368
415
|
/**
|
|
369
|
-
*
|
|
416
|
+
* A Stage's prose — one part of a Note, or the reason it gave for committing
|
|
417
|
+
* nothing — with every checkbox defused.
|
|
370
418
|
*
|
|
371
419
|
* `- [ ]` is Acceptance Criteria to everything that reads a Ticket: the
|
|
372
420
|
* `no-criteria` guard counts one as a usable Ticket, verify grades it, and the
|
|
373
|
-
* merge ticks it. A
|
|
421
|
+
* merge ticks it. A Stage's prose is for a human to read, not work anyone
|
|
374
422
|
* promised, so its boxes are escaped into the text they were meant to be.
|
|
375
423
|
* Brackets anywhere but at the head of a list item are left alone, because that
|
|
376
424
|
* is the only shape those readers recognise.
|
|
377
425
|
*/
|
|
378
|
-
function escapeCheckboxes(
|
|
379
|
-
return
|
|
426
|
+
function escapeCheckboxes(prose: string): string {
|
|
427
|
+
return prose.replaceAll(PROSE_CHECKBOX, (_, bullet: string) => `${bullet}\\[ \\]`);
|
|
380
428
|
}
|
|
381
429
|
|
|
382
430
|
/**
|
|
@@ -420,14 +468,28 @@ export function noteComment(subject: NoteSubject): string {
|
|
|
420
468
|
return [NOTE_MARKER, noteProvenance(subject), "", paragraphs.join("\n\n"), ""].join("\n");
|
|
421
469
|
}
|
|
422
470
|
|
|
423
|
-
/**
|
|
471
|
+
/**
|
|
472
|
+
* How the Ticket's own branch failed, before the merge-base was graded: a Check
|
|
473
|
+
* in its worktree, or CI on its pull request.
|
|
474
|
+
*/
|
|
475
|
+
export type BranchFailure =
|
|
476
|
+
| { point: "checks"; command: string; output: string; timedOut: boolean }
|
|
477
|
+
| {
|
|
478
|
+
point: "ci";
|
|
479
|
+
/** Which checks went red, as CI reported them. */
|
|
480
|
+
summary: string;
|
|
481
|
+
/** The tail of the failing jobs' logs, which a fix Stage would be handed; empty when none had one. */
|
|
482
|
+
excerpt: string;
|
|
483
|
+
};
|
|
484
|
+
|
|
485
|
+
/** A Check the base branch fails, as the pipeline's own Note reports it. */
|
|
424
486
|
export interface FailingBaseNote {
|
|
425
487
|
/** The Ticket the failure released. */
|
|
426
488
|
origin: number;
|
|
427
|
-
/**
|
|
428
|
-
|
|
489
|
+
/** How the Ticket's branch failed, which the Note quotes beside the merge-base's output. */
|
|
490
|
+
onBranch: BranchFailure;
|
|
429
491
|
baseBranch: string;
|
|
430
|
-
/** The Ticket's branch, whose merge-base with the
|
|
492
|
+
/** The Ticket's branch, whose merge-base with the base branch `commit` is. */
|
|
431
493
|
branch: string;
|
|
432
494
|
/** The merge-base, in full, so it can be checked out as it is. */
|
|
433
495
|
commit: string;
|
|
@@ -438,43 +500,72 @@ export interface FailingBaseNote {
|
|
|
438
500
|
|
|
439
501
|
/** The pipeline's Note's summary, which is also the Run summary's `noted` row. */
|
|
440
502
|
export function failingBaseSummary(baseBranch: string, command: string): string {
|
|
441
|
-
return `The
|
|
503
|
+
return `The base branch \`${baseBranch}\` fails \`${command}\`.`;
|
|
442
504
|
}
|
|
443
505
|
|
|
444
506
|
/**
|
|
445
|
-
* The one Note no Stage writes: a Ticket was released because the
|
|
446
|
-
* fails the Check its branch failed, so the defect is the
|
|
507
|
+
* The one Note no Stage writes: a Ticket was released because the base branch
|
|
508
|
+
* fails the Check its branch failed, so the defect is the base branch's and a
|
|
447
509
|
* human has to mend it there.
|
|
448
510
|
*
|
|
449
511
|
* Signed and laid out as a Stage's Note is, so triage reads it the same way,
|
|
450
512
|
* with the provenance naming the pipeline rather than a Stage. The tail of the
|
|
451
513
|
* output is the one a CI log excerpt keeps, so long lines cannot push the Note
|
|
452
|
-
* past what GitHub takes in a comment.
|
|
453
|
-
*
|
|
514
|
+
* past what GitHub takes in a comment.
|
|
515
|
+
*
|
|
516
|
+
* The branch's own failure is quoted beside it, because only the command is
|
|
517
|
+
* compared: a branch that fails the command differently is released all the
|
|
518
|
+
* same, and its failure would otherwise be nowhere a human can read it. For CI
|
|
519
|
+
* that is the failing jobs' logs as a fix Stage would be handed them, which are
|
|
520
|
+
* tails already.
|
|
454
521
|
*/
|
|
455
522
|
export function failingBaseNote(note: FailingBaseNote): string {
|
|
456
|
-
const { baseBranch, branch, commit, command } = note;
|
|
457
|
-
const tail = logTail(note.output);
|
|
523
|
+
const { baseBranch, branch, commit, command, onBranch } = note;
|
|
458
524
|
const where = `\`${command}\` ${note.timedOut ? "timed out" : "failed"} in a clean worktree at ${commit}, the merge-base of \`${branch}\` with \`${baseBranch}\`.`;
|
|
459
|
-
const
|
|
460
|
-
const
|
|
461
|
-
|
|
462
|
-
?
|
|
463
|
-
|
|
525
|
+
const opening = "The branch's own failure, which need not be the same:";
|
|
526
|
+
const branchPart =
|
|
527
|
+
onBranch.point === "checks"
|
|
528
|
+
? quoted(
|
|
529
|
+
`${opening} \`${onBranch.command}\` ${onBranch.timedOut ? "timed out" : "failed"} on \`${branch}\`.`,
|
|
530
|
+
"The tail of the branch's output:",
|
|
531
|
+
logTail(onBranch.output),
|
|
532
|
+
"It printed nothing.",
|
|
533
|
+
)
|
|
534
|
+
: quoted(
|
|
535
|
+
`${opening} CI on the pull request from \`${branch}\` reported ${onBranch.summary}.`,
|
|
536
|
+
"The tail of the failing jobs' logs:",
|
|
537
|
+
onBranch.excerpt.trim(),
|
|
538
|
+
"No failing job had a log to quote.",
|
|
539
|
+
);
|
|
464
540
|
return [
|
|
465
541
|
NOTE_MARKER,
|
|
466
|
-
`From the pipeline, releasing #${note.origin} at ${
|
|
542
|
+
`From the pipeline, releasing #${note.origin} at ${onBranch.point}`,
|
|
467
543
|
"",
|
|
468
544
|
[
|
|
469
545
|
`**${failingBaseSummary(baseBranch, command)}**`,
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
`**
|
|
546
|
+
`**Evidence**: ${quoted(where, "The tail of its output:", logTail(note.output), "It printed nothing.")}`,
|
|
547
|
+
branchPart,
|
|
548
|
+
`**Impact**: every Ticket whose branch inherits ${commit} fails the same Check. #${note.origin} was released with its fix budget as it was, and the Run claimed no more Tickets.`,
|
|
549
|
+
`**Next**: mend \`${command}\` on \`${baseBranch}\`. The next Run takes the released Tickets up again from their state files, rebased onto \`${baseBranch}\` before their Checks.`,
|
|
473
550
|
].join("\n\n"),
|
|
474
551
|
"",
|
|
475
552
|
].join("\n");
|
|
476
553
|
}
|
|
477
554
|
|
|
555
|
+
/**
|
|
556
|
+
* A sentence of the pipeline's own and the output it introduces, or `ifEmpty`
|
|
557
|
+
* in place of the introduction when there was no output.
|
|
558
|
+
*
|
|
559
|
+
* The output is fenced with more backticks than any run of them inside it, so a
|
|
560
|
+
* fence the output prints cannot close it early, and only the output has its
|
|
561
|
+
* checkboxes escaped, since the words around it are the pipeline's.
|
|
562
|
+
*/
|
|
563
|
+
function quoted(sentence: string, introduction: string, output: string, ifEmpty: string): string {
|
|
564
|
+
if (output === "") return `${sentence} ${ifEmpty}`;
|
|
565
|
+
const fence = "`".repeat(Math.max(3, ...[...output.matchAll(/`+/g)].map(([run]) => run.length + 1)));
|
|
566
|
+
return `${sentence} ${introduction}\n\n${fence}\n${escapeCheckboxes(output)}\n${fence}`;
|
|
567
|
+
}
|
|
568
|
+
|
|
478
569
|
/** Whether an issue's body says it is the standing Notes issue. */
|
|
479
570
|
export function isNotesIssue(body: string): boolean {
|
|
480
571
|
return carriesMarker(body, NOTES_ISSUE_MARKER);
|
|
@@ -497,7 +588,7 @@ export function notesIssue(): { title: string; body: string } {
|
|
|
497
588
|
"**Notes from the pipeline.** Every finding a Stage could not post on a " +
|
|
498
589
|
"Ticket arrives here as a comment: one that named no Ticket, one whose " +
|
|
499
590
|
"Ticket would have buried it, and one whose Ticket refused the comment. " +
|
|
500
|
-
"So does the pipeline's own Note about a
|
|
591
|
+
"So does the pipeline's own Note about a base branch that fails a Check. " +
|
|
501
592
|
"Each comment says which Ticket and Stage, or the pipeline, found it.",
|
|
502
593
|
"",
|
|
503
594
|
"Triage empties this issue by hand: promote what deserves a Ticket, record " +
|
|
@@ -510,7 +601,7 @@ export function notesIssue(): { title: string; body: string } {
|
|
|
510
601
|
}
|
|
511
602
|
|
|
512
603
|
export interface RunSummary {
|
|
513
|
-
/** The
|
|
604
|
+
/** The version the Run ran, which is what its transcripts are stamped with. */
|
|
514
605
|
version: string;
|
|
515
606
|
runId: string;
|
|
516
607
|
durationMs: number;
|
|
@@ -518,12 +609,13 @@ export interface RunSummary {
|
|
|
518
609
|
credential: Credential;
|
|
519
610
|
outcomes: TicketOutcome[];
|
|
520
611
|
/**
|
|
521
|
-
*
|
|
522
|
-
*
|
|
612
|
+
* What the Run's Stages said they were billed: the spend or extra usage its
|
|
613
|
+
* header gives, and every Stage that said it ran on something else, each
|
|
614
|
+
* named in a row after its own Ticket's.
|
|
523
615
|
*/
|
|
524
|
-
|
|
616
|
+
billing?: Billing;
|
|
525
617
|
/**
|
|
526
|
-
* The line saying a newer
|
|
618
|
+
* The line saying a newer version is out, where one is. Above the header
|
|
527
619
|
* rather than below it: the Run already said this hours ago, at the top of a
|
|
528
620
|
* log this summary is the bottom of (ADR-0007).
|
|
529
621
|
*/
|
|
@@ -535,14 +627,14 @@ export interface RunSummary {
|
|
|
535
627
|
/**
|
|
536
628
|
* What a Release is put down to, in the words the Run summary and the log
|
|
537
629
|
* share: the rate limit, a transient API failure, an API key out of credit or
|
|
538
|
-
* past its spend limit, or a
|
|
630
|
+
* past its spend limit, or a base branch that fails the Check the Ticket's
|
|
539
631
|
* branch failed.
|
|
540
632
|
*/
|
|
541
633
|
export const RELEASE_WORDS: Record<ReleaseCause, string> = {
|
|
542
634
|
"rate-limited": "rate limit",
|
|
543
635
|
"api-error": "API failure",
|
|
544
636
|
"out-of-budget": "out of API budget",
|
|
545
|
-
"failing-base": "failing
|
|
637
|
+
"failing-base": "failing base branch",
|
|
546
638
|
};
|
|
547
639
|
|
|
548
640
|
/**
|
|
@@ -562,7 +654,7 @@ const VERB_WIDTH = 9;
|
|
|
562
654
|
/**
|
|
563
655
|
* What a Run prints when it ends. One line per Ticket, then why the Run
|
|
564
656
|
* stopped — the Frontier is empty, everything left on it is blocked, the rate
|
|
565
|
-
* limit, a transient API failure, the API key's budget or a failing
|
|
657
|
+
* limit, a transient API failure, the API key's budget or a failing base branch
|
|
566
658
|
* released a Ticket and the Run went no further, or a human stopped it.
|
|
567
659
|
*/
|
|
568
660
|
export function runSummary({
|
|
@@ -571,16 +663,14 @@ export function runSummary({
|
|
|
571
663
|
durationMs,
|
|
572
664
|
credential,
|
|
573
665
|
outcomes,
|
|
574
|
-
|
|
666
|
+
billing = emptyBilling(),
|
|
575
667
|
newer,
|
|
576
668
|
stop,
|
|
577
669
|
}: RunSummary): string {
|
|
578
670
|
const rows = [
|
|
579
671
|
...outcomes.flatMap((outcome) => [
|
|
580
672
|
...ticketRows(outcome, credential),
|
|
581
|
-
...
|
|
582
|
-
.filter((stray) => stray.ticket === outcome.ticket)
|
|
583
|
-
.map((stray) => row("billed", stray.ticket, `${stray.stage} · apiKeySource ${stray.apiKeySource}`)),
|
|
673
|
+
...billing.strays.filter((stray) => stray.ticket === outcome.ticket).map(billedRow),
|
|
584
674
|
]),
|
|
585
675
|
// Only a Run that reached the end of the Frontier can name what was held
|
|
586
676
|
// back all Run, so only that stop carries candidates to skip.
|
|
@@ -591,7 +681,7 @@ export function runSummary({
|
|
|
591
681
|
|
|
592
682
|
return [
|
|
593
683
|
...(newer === undefined ? [] : [newer]),
|
|
594
|
-
`ticket-runner ${version} run ${runId} · ${Math.round(durationMs / 60_000)}m · ${
|
|
684
|
+
`ticket-runner ${version} run ${runId} · ${Math.round(durationMs / 60_000)}m · ${billedTo(credential, billing)}`,
|
|
595
685
|
"",
|
|
596
686
|
...(rows.length === 0 ? [" nothing to do"] : rows),
|
|
597
687
|
"",
|
|
@@ -600,6 +690,38 @@ export function runSummary({
|
|
|
600
690
|
].join("\n");
|
|
601
691
|
}
|
|
602
692
|
|
|
693
|
+
/**
|
|
694
|
+
* What the header says the Run's Stages were billed to. An `--api-key` Run
|
|
695
|
+
* adds its spend, ending `+` where a Stage on the key reported no figure, so it
|
|
696
|
+
* is at least that much. A subscription Run adds no amount, since its figure
|
|
697
|
+
* is an estimate at API prices and not money spent, only whether a Stage ran
|
|
698
|
+
* on the plan's extra usage.
|
|
699
|
+
*/
|
|
700
|
+
function billedTo(credential: Credential, billing: Billing): string {
|
|
701
|
+
const words = CREDENTIAL_WORDS[credential];
|
|
702
|
+
if (credential === "api-key") {
|
|
703
|
+
return `${words} · ${dollars(billing.spendUsd)}${billing.spendUnreported ? "+" : ""}`;
|
|
704
|
+
}
|
|
705
|
+
return billing.extraUsage ? `${words} · extra usage` : words;
|
|
706
|
+
}
|
|
707
|
+
|
|
708
|
+
/**
|
|
709
|
+
* A Stage billed somewhere the Run did not choose, with its own figure where it
|
|
710
|
+
* gave one, ending `+` where that is only part of its session's.
|
|
711
|
+
*/
|
|
712
|
+
function billedRow(stray: StrayStage): string {
|
|
713
|
+
const cost =
|
|
714
|
+
stray.costUsd === undefined
|
|
715
|
+
? ""
|
|
716
|
+
: ` · ${dollars(stray.costUsd)}${stray.costIncomplete === true ? "+" : ""}`;
|
|
717
|
+
return row("billed", stray.ticket, `${stray.stage} · apiKeySource ${stray.apiKeySource}${cost}`);
|
|
718
|
+
}
|
|
719
|
+
|
|
720
|
+
/** An amount of dollars as the Run summary prints one: `$12.34`. */
|
|
721
|
+
function dollars(usd: number): string {
|
|
722
|
+
return `$${usd.toFixed(2)}`;
|
|
723
|
+
}
|
|
724
|
+
|
|
603
725
|
/** The one line that says why the Run stopped. */
|
|
604
726
|
function lastLine(stop: RunStop, credential: Credential): string {
|
|
605
727
|
switch (stop.reason) {
|
|
@@ -657,11 +779,6 @@ function ticketRows(outcome: TicketOutcome, credential: Credential): string[] {
|
|
|
657
779
|
];
|
|
658
780
|
}
|
|
659
781
|
|
|
660
|
-
/** A Note summary's opening line, which is as much of it as a Run summary has room for. */
|
|
661
|
-
function firstLine(text: string): string {
|
|
662
|
-
return (text.split("\n").find((line) => line.trim() !== "") ?? "").trim();
|
|
663
|
-
}
|
|
664
|
-
|
|
665
782
|
/** `text`, or as much of it as fits with an ellipsis standing in for the rest. */
|
|
666
783
|
function truncate(text: string, limit: number): string {
|
|
667
784
|
return text.length <= limit ? text : `${text.slice(0, limit - 1).trimEnd()}\u2026`;
|
|
@@ -680,7 +797,7 @@ function noteRow({ origin, stage, issue, opened, summary }: RoutedNote): string
|
|
|
680
797
|
return row(
|
|
681
798
|
"noted",
|
|
682
799
|
issue,
|
|
683
|
-
`${destination} · from #${origin} ${stage} · ${truncate(
|
|
800
|
+
`${destination} · from #${origin} ${stage} · ${truncate(splitMessage(summary).line, NOTE_WIDTH)}`,
|
|
684
801
|
);
|
|
685
802
|
}
|
|
686
803
|
|
|
@@ -693,7 +810,8 @@ function ticketRow(outcome: TicketOutcome, credential: Credential): string {
|
|
|
693
810
|
return row(
|
|
694
811
|
"handed",
|
|
695
812
|
outcome.ticket,
|
|
696
|
-
|
|
813
|
+
// The one line of an unexpected error; its output is the hand-off's.
|
|
814
|
+
`${outcome.title} · ${outcome.stage} · ${splitMessage(outcome.failure).line}`,
|
|
697
815
|
);
|
|
698
816
|
case "released":
|
|
699
817
|
// Nothing for a human to do, so the row says only what stopped the Stage
|
package/src/timer.ts
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A wait the caller can call off before it elapses.
|
|
3
|
+
*
|
|
4
|
+
* Called off rather than left to run out, because a pending timer keeps Node's
|
|
5
|
+
* process alive: a Run that ended while one was still counting down would
|
|
6
|
+
* hold the terminal until it did.
|
|
7
|
+
*/
|
|
8
|
+
export interface Timer {
|
|
9
|
+
/** Resolves once the wait has elapsed, and never if it was called off first. */
|
|
10
|
+
elapsed: Promise<void>;
|
|
11
|
+
/** Call the wait off. Calling it off again, or after it elapsed, does nothing. */
|
|
12
|
+
cancel(): void;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** Start a wait of `ms` milliseconds. */
|
|
16
|
+
export type StartTimer = (ms: number) => Timer;
|
|
17
|
+
|
|
18
|
+
/** A wait on the real clock. */
|
|
19
|
+
export const startTimer: StartTimer = (ms) => {
|
|
20
|
+
let handle: ReturnType<typeof setTimeout> | undefined;
|
|
21
|
+
const elapsed = new Promise<void>((resolve) => {
|
|
22
|
+
handle = setTimeout(resolve, ms);
|
|
23
|
+
});
|
|
24
|
+
return { elapsed, cancel: () => clearTimeout(handle) };
|
|
25
|
+
};
|
package/src/title.ts
CHANGED
|
@@ -19,31 +19,51 @@ import { CODE_STAGE_NOTES_LIST_SCHEMA } from "./note-schema.js";
|
|
|
19
19
|
export const BRANCH_TITLE =
|
|
20
20
|
"one line summarising the whole branch as it stands when you finish, the work of any Stage before you included";
|
|
21
21
|
|
|
22
|
-
/**
|
|
22
|
+
/**
|
|
23
|
+
* The shape a commit subject and a title take, as the prompts of the code
|
|
24
|
+
* Stages and the schema state it: one declaration, so they cannot drift apart.
|
|
25
|
+
* The conventions document a Target carries states it to the readers the
|
|
26
|
+
* pipeline does not brief.
|
|
27
|
+
*/
|
|
28
|
+
export const SUBJECT_SHAPE = "<type>(<scope>): <summary>";
|
|
29
|
+
|
|
30
|
+
/** Any {@link SUBJECT_SHAPE}; the repo's own types and scopes are CONTRIBUTING.md's business. */
|
|
23
31
|
const CONVENTIONAL_SUBJECT = /^[a-z]+(\([a-z0-9._-]+\))?: \S/;
|
|
24
32
|
|
|
25
|
-
/** The `(#<n>)` a
|
|
33
|
+
/** The `(#<n>)` a commit may carry, which the squash commit's `Closes #<n>` replaces. */
|
|
26
34
|
const TICKET_REFERENCE = /\s*\(#\d+\)$/;
|
|
27
35
|
|
|
28
36
|
/**
|
|
29
37
|
* The `--json-schema` the implement and fix Stages are invoked with: the title
|
|
30
|
-
* of the whole branch,
|
|
38
|
+
* of the whole branch, the Notes channel beside it, and why the Stage ended
|
|
39
|
+
* with no new commit when it did.
|
|
31
40
|
*
|
|
32
|
-
*
|
|
33
|
-
* Notes list when it found nothing,
|
|
34
|
-
* parsers forgive
|
|
35
|
-
*
|
|
41
|
+
* All three are required, so a Stage always says something about each: an
|
|
42
|
+
* empty Notes list when it found nothing, a title however little it did, and an
|
|
43
|
+
* empty reason when it committed. The parsers forgive each one on its own
|
|
44
|
+
* ({@link parseTitle}, `parseNotes` and {@link parseNoCommitReason}), so a bad
|
|
45
|
+
* answer to one never costs the others.
|
|
46
|
+
*
|
|
47
|
+
* The reason is asked for in its own field because, under `--json-schema`, the
|
|
48
|
+
* answer is all of the session the pipeline reads: a last message in prose is
|
|
49
|
+
* only an earlier turn of the transcript. A Stage that ends with no new commit
|
|
50
|
+
* hands the Ticket to a human, and the hand-off quotes the reason (#306).
|
|
36
51
|
*/
|
|
37
52
|
export const CODE_STAGE_JSON_SCHEMA = {
|
|
38
53
|
type: "object",
|
|
39
54
|
properties: {
|
|
40
55
|
title: {
|
|
41
56
|
type: "string",
|
|
42
|
-
description: `Write ${BRANCH_TITLE}:
|
|
57
|
+
description: `Write ${BRANCH_TITLE}: \`${SUBJECT_SHAPE}\`, without the \`(#<n>)\`. It titles the pull request and the squash commit that lands.`,
|
|
43
58
|
},
|
|
44
59
|
notes: CODE_STAGE_NOTES_LIST_SCHEMA,
|
|
60
|
+
noCommitReason: {
|
|
61
|
+
type: "string",
|
|
62
|
+
description:
|
|
63
|
+
"When you end with no new commit on the branch, say why in a few sentences: ending so hands the Ticket to a human, and the hand-off comment quotes this. Otherwise an empty string.",
|
|
64
|
+
},
|
|
45
65
|
},
|
|
46
|
-
required: ["title", "notes"],
|
|
66
|
+
required: ["title", "notes", "noCommitReason"],
|
|
47
67
|
additionalProperties: false,
|
|
48
68
|
} as const;
|
|
49
69
|
|
|
@@ -73,6 +93,22 @@ export function parseTitle(result: unknown): string | undefined {
|
|
|
73
93
|
return typeof raw === "string" ? asTitle(raw) : undefined;
|
|
74
94
|
}
|
|
75
95
|
|
|
96
|
+
/**
|
|
97
|
+
* Why a code Stage ended with no new commit, as it answered it, or nothing
|
|
98
|
+
* when it gave no reason.
|
|
99
|
+
*
|
|
100
|
+
* Forgiving, as the title and the Notes beside it are: output that is not an
|
|
101
|
+
* object and a missing, blank or non-string reason each cost the reason alone.
|
|
102
|
+
* The lines are kept as the Stage wrote them; only the ends are trimmed.
|
|
103
|
+
*/
|
|
104
|
+
export function parseNoCommitReason(result: unknown): string | undefined {
|
|
105
|
+
if (typeof result !== "object" || result === null) return undefined;
|
|
106
|
+
const raw = (result as { noCommitReason?: unknown }).noCommitReason;
|
|
107
|
+
if (typeof raw !== "string") return undefined;
|
|
108
|
+
const reason = raw.trim();
|
|
109
|
+
return reason === "" ? undefined : reason;
|
|
110
|
+
}
|
|
111
|
+
|
|
76
112
|
/**
|
|
77
113
|
* The pull request title, in this order of preference: the latest title a
|
|
78
114
|
* Stage answered, whether in this Run or recorded by the one before it; the
|
package/src/verdict.ts
CHANGED
|
@@ -22,7 +22,7 @@ export type Verdict = z.infer<typeof verdictSchema>;
|
|
|
22
22
|
export type CriterionStatus = Criterion["status"];
|
|
23
23
|
|
|
24
24
|
/**
|
|
25
|
-
* The `--json-schema` the verify Stage is invoked with: the
|
|
25
|
+
* The `--json-schema` the verify Stage is invoked with: the verdict, and the
|
|
26
26
|
* Notes channel beside it.
|
|
27
27
|
*
|
|
28
28
|
* The `notes` list has to be declared here even though {@link parseVerdict}
|
|
@@ -31,11 +31,11 @@ export type CriterionStatus = Criterion["status"];
|
|
|
31
31
|
* parsing, is what would otherwise leave the most adversarial reader in the
|
|
32
32
|
* pipeline with nowhere to put a finding outside the criteria.
|
|
33
33
|
*
|
|
34
|
-
* It is not required, where the criteria and the flag are. The
|
|
34
|
+
* It is not required, where the criteria and the flag are. The verdict is the
|
|
35
35
|
* Stage's product and a session that graded nothing has done none of its job,
|
|
36
|
-
* so every required key here is a way for a Ticket to lose its
|
|
37
|
-
* side channel may never cost one. A
|
|
38
|
-
*
|
|
36
|
+
* so every required key here is a way for a Ticket to lose its verdict — and a
|
|
37
|
+
* side channel may never cost one. A verdict that leaves the list out is a
|
|
38
|
+
* verdict from a session that found nothing beside the criteria.
|
|
39
39
|
*/
|
|
40
40
|
export const VERDICT_JSON_SCHEMA = {
|
|
41
41
|
type: "object",
|
|
@@ -49,7 +49,7 @@ export const VERDICT_JSON_SCHEMA = {
|
|
|
49
49
|
status: { type: "string", enum: ["met", "unmet", "unverifiable"] },
|
|
50
50
|
evidence: {
|
|
51
51
|
type: "string",
|
|
52
|
-
description: "What you ran or read, and what it showed",
|
|
52
|
+
description: "What you ran or read, and what it showed. It proposes no fix",
|
|
53
53
|
},
|
|
54
54
|
},
|
|
55
55
|
required: ["text", "status", "evidence"],
|
|
@@ -70,7 +70,7 @@ export function parseVerdict(result: unknown): Verdict {
|
|
|
70
70
|
|
|
71
71
|
/**
|
|
72
72
|
* The pipeline's own pass decision: no criterion is unmet and at least one is
|
|
73
|
-
* met. A
|
|
73
|
+
* met. A verdict of nothing but `unverifiable` is zero evidence, so it fails.
|
|
74
74
|
*/
|
|
75
75
|
export function passes(verdict: Verdict): boolean {
|
|
76
76
|
const counts = countStatuses(verdict);
|