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/config.ts
CHANGED
|
@@ -53,7 +53,7 @@ const configSchema = z
|
|
|
53
53
|
.optional(),
|
|
54
54
|
permissionMode: z.enum(PERMISSION_MODES).optional(),
|
|
55
55
|
ciTimeoutMinutes: z.number().positive().optional(),
|
|
56
|
-
ciGraceMinutes: z.number().
|
|
56
|
+
ciGraceMinutes: z.number().nonnegative().optional(),
|
|
57
57
|
checkTimeoutMinutes: z.number().positive().optional(),
|
|
58
58
|
labels: z
|
|
59
59
|
.object({
|
|
@@ -112,7 +112,8 @@ export interface Config {
|
|
|
112
112
|
/**
|
|
113
113
|
* How long a pull request GitHub has registered no check run for still counts
|
|
114
114
|
* as pending. A Target whose Actions queue slowly raises it; a Target with no
|
|
115
|
-
* CI
|
|
115
|
+
* CI sets it to zero, or else pays it once per Landing, so it is not the CI
|
|
116
|
+
* timeout.
|
|
116
117
|
*/
|
|
117
118
|
ciGraceMinutes: number;
|
|
118
119
|
/**
|
|
@@ -171,7 +172,7 @@ const LABEL_DEFAULTS: Labels = {
|
|
|
171
172
|
* from package.json when the config does not name them.
|
|
172
173
|
*
|
|
173
174
|
* Throws {@link ConfigError} naming the offending field when the file is
|
|
174
|
-
* unusable; a missing file is not an error. `version` is the
|
|
175
|
+
* unusable; a missing file is not an error. `version` is the version doing the
|
|
175
176
|
* refusing, which the message for an unknown key carries.
|
|
176
177
|
*/
|
|
177
178
|
export function loadConfig(repoRoot: string, version: string): Config {
|
|
@@ -207,12 +208,12 @@ export function loadConfig(repoRoot: string, version: string): Config {
|
|
|
207
208
|
}
|
|
208
209
|
|
|
209
210
|
/**
|
|
210
|
-
* Why the file was refused, and — for an unknown key — which
|
|
211
|
+
* Why the file was refused, and — for an unknown key — which version refused it.
|
|
211
212
|
*
|
|
212
213
|
* The schema is strict, so a key this install has never heard of is refused by
|
|
213
214
|
* name. That is the right answer to a typo and a confusing one to a key a newer
|
|
214
|
-
*
|
|
215
|
-
* the same. So the
|
|
215
|
+
* version added, and on a machine running a stale install the two look exactly
|
|
216
|
+
* the same. So the version is said out loud, and the config file itself is left
|
|
216
217
|
* without one to carry (ADR-0007).
|
|
217
218
|
*/
|
|
218
219
|
function refusal(error: z.ZodError, version: string): string {
|
package/src/conventions.ts
CHANGED
|
@@ -11,7 +11,13 @@
|
|
|
11
11
|
* vocabulary, the review rules, the test policy are the Target's business, and a
|
|
12
12
|
* document that took them over would be rewritten out from under it.
|
|
13
13
|
*
|
|
14
|
-
*
|
|
14
|
+
* It is for the readers the pipeline does not brief: humans, attended Claude
|
|
15
|
+
* sessions in a Target, and the Planning skills that write Tickets. It leaves
|
|
16
|
+
* out what the Stage prompts already say, such as how a Stage titles its branch
|
|
17
|
+
* and that it opens no pull request: a Stage hears those from its own prompt,
|
|
18
|
+
* and a second copy here would only drift from it.
|
|
19
|
+
*
|
|
20
|
+
* The one thing it says about versions is the mark it bears: which pipeline
|
|
15
21
|
* wrote the copy a Target carries, hidden on the first line so no reader of the
|
|
16
22
|
* document meets it. That is a direction comparing text never gives — `init`
|
|
17
23
|
* leaves a document a newer pipeline wrote alone, and a Run behind one warns
|
|
@@ -37,7 +43,7 @@ export const CLAUDE_SECTION = `## Pipeline conventions
|
|
|
37
43
|
`;
|
|
38
44
|
|
|
39
45
|
/**
|
|
40
|
-
* The marker carrying the
|
|
46
|
+
* The marker carrying the version, as the first line of the document ends.
|
|
41
47
|
*
|
|
42
48
|
* An HTML comment, like every other marker the pipeline finds its own writing
|
|
43
49
|
* by, so it is on the line a reader sees and in none of the text they read.
|
|
@@ -46,10 +52,10 @@ const MARKER = /<!-- ticket-runner:version ([^\s>]+) -->/;
|
|
|
46
52
|
|
|
47
53
|
/**
|
|
48
54
|
* The document itself, as {@link CONVENTIONS_PATH} must contain it, marked with
|
|
49
|
-
* the
|
|
55
|
+
* the version writing it.
|
|
50
56
|
*
|
|
51
57
|
* The number alone, never the commit a development checkout adds: two checkouts
|
|
52
|
-
* of one
|
|
58
|
+
* of one version write one document, and a Target whose copy was rewritten by
|
|
53
59
|
* every commit would say nothing by having been.
|
|
54
60
|
*
|
|
55
61
|
* A copy with no number to stamp carries no marker rather than a marker saying
|
|
@@ -63,7 +69,7 @@ export function conventionsDoc(version: string): string {
|
|
|
63
69
|
}
|
|
64
70
|
|
|
65
71
|
/**
|
|
66
|
-
* The
|
|
72
|
+
* The version number a Target's copy was written by, and undefined for a copy
|
|
67
73
|
* carrying no mark at all — every copy an older pipeline wrote, which is read
|
|
68
74
|
* as being behind rather than as being wrong.
|
|
69
75
|
*/
|
|
@@ -73,25 +79,22 @@ export function conventionsMark(document: string | undefined): string | undefine
|
|
|
73
79
|
return marked === undefined ? undefined : versionNumber(marked);
|
|
74
80
|
}
|
|
75
81
|
|
|
76
|
-
/** Everything under the marked first line, which no
|
|
82
|
+
/** Everything under the marked first line, which no version changes. */
|
|
77
83
|
const BODY = `
|
|
78
84
|
What \`ticket-runner\` requires of this repository, and nothing else. \`ticket-runner init\` writes this file and rewrites it whenever those requirements change, so an edit made here does not survive the next \`init\`. Everything the pipeline leaves to this repository — which commit types and scopes it uses, how it reviews, what it tests — belongs in the repository's own contributing guide.
|
|
79
85
|
|
|
86
|
+
Besides names such as GitHub and Claude Code, a capitalised word below is one of the pipeline's own terms, said in a few words where it first appears; every other word means what it ordinarily does. To the pipeline this repository is a Target, the repository a Run takes its work from and merges into. A Run is one invocation of the pipeline on a Host, the machine it executes on, and works through Tickets, GitHub issues each sized for one session of work, until it has none left to take or is told to take no more. Each Ticket is worked by Stages, each one Claude Code session with a single purpose: implement, verify, fix, or resolve a rebase conflict. A Stage may answer Notes beside its work: defects it met that belong to another Ticket or to none yet, recorded where a human will find them instead of being fixed there.
|
|
87
|
+
|
|
80
88
|
## Commits
|
|
81
89
|
|
|
82
|
-
- Subject: \`<type>(<scope>): <summary
|
|
83
|
-
- The type and scope vocabulary is this repository's own. The pipeline reads the shape
|
|
84
|
-
-
|
|
90
|
+
- Subject: \`<type>(<scope>): <summary>\`.
|
|
91
|
+
- The type and scope vocabulary is this repository's own. The pipeline reads the shape, never the words.
|
|
92
|
+
- This repository's own commit conventions must fit this shape: the pipeline titles its pull requests in it where it can, and so the squash commits they land as. Where it cannot, a pull request takes the Ticket's title.
|
|
85
93
|
|
|
86
94
|
## Branches
|
|
87
95
|
|
|
88
96
|
- \`agent/<n>-<slug>\` belongs to the pipeline. A Run creates one per Ticket, works in a worktree of it, and pushes it after every Stage that commits. The repository deletes it when the pull request merges, a setting \`ticket-runner init\` switches on. Nothing else branches there.
|
|
89
|
-
- \`ticket-runner/lock\` and \`ticket-runner/state\` belong to the pipeline too. The first says which Run holds this repository, and the second keeps the
|
|
90
|
-
- A Stage commits only to the branch already checked out in the worktree it was started in. It creates no branch and switches to none.
|
|
91
|
-
|
|
92
|
-
## What a Stage does not do
|
|
93
|
-
|
|
94
|
-
- A Stage opens no pull request and closes no issue. The pipeline opens the pull request when the Stage finishes, waits for CI, merges it, and lets the merge close the Ticket.
|
|
97
|
+
- \`ticket-runner/lock\` and \`ticket-runner/state\` belong to the pipeline too. The first says which Run holds this repository, and the second keeps the state file of every Ticket a Run can resume, and the transcripts of the Stages of a handed-off Ticket. A Hand-off gives a Ticket to a human rather than merging it, and leaves its work where they can carry on from it. Nothing else commits to either, except a human, or an Operator a human asked, the Claude session a human opens on a cloud Host from the Claude app to start a Run, watch it and stop it, releasing a lock a vanished Host left behind.
|
|
95
98
|
|
|
96
99
|
## What a Ticket needs
|
|
97
100
|
|
|
@@ -103,17 +106,17 @@ A Ticket is one issue the pipeline can implement in a single session. It is refu
|
|
|
103
106
|
|
|
104
107
|
## Checks
|
|
105
108
|
|
|
106
|
-
- The Checks of different Tickets may run at the same time, each in its own worktree, because a Run has as many Lanes as \`lanes\` says. A Target whose Checks need a port, a database or anything else they would have to share keeps \`lanes\` at one, or makes them independent of each other.
|
|
107
|
-
- A Check that fails on a Ticket's branch, or CI that fails on its pull request, is graded again at what the branch inherited: the pipeline runs the Check commands in a clean worktree at the branch's merge-base with the
|
|
109
|
+
- A Check is a command the pipeline runs itself on a Ticket's code to gate it, such as its tests or its typecheck, and never the CI on a pull request, which the pipeline only waits for. The Checks of different Tickets may run at the same time, each in its own worktree, because a Run has as many Lanes as \`lanes\` says, and each Lane holds one Ticket in progress. A Target whose Checks need a port, a database or anything else they would have to share keeps \`lanes\` at one, or makes them independent of each other.
|
|
110
|
+
- A Check that fails on a Ticket's branch, or CI that fails on its pull request, is graded again at what the branch inherited: the pipeline runs the Check commands in a clean worktree at the branch's merge-base with the base branch. One that fails there too is the base branch's, not the Ticket's, so the Ticket is released, given back to the pipeline for a later Run to take up again, as something outside the Ticket stopped its work. That Release spends none of its fix budget (the fix Stages it is allowed), the Run claims no more Tickets, and the pipeline posts a Note on the standing Notes issue naming the Check. The next Run rebases the Ticket onto the base branch before its Checks, so mending the base branch is what frees it. Nothing is installed in the worktree at the merge-base: its Checks find their dependencies in the main checkout, as a Ticket's worktree does, so Checks that need an install or a build step of their own fail there and release the Ticket, and the Note's output shows it.
|
|
108
111
|
|
|
109
112
|
## The Operator's skill
|
|
110
113
|
|
|
111
|
-
- \`.claude/skills/ticket-runner/\` belongs to the pipeline. It tells an Operator
|
|
114
|
+
- \`.claude/skills/ticket-runner/\` belongs to the pipeline. It tells an Operator how to start a Run, report on it and pass on a Stop, a human's request that the Run finish the Tickets its Lanes hold and take no more. \`ticket-runner init\` writes it and rewrites it like this file, so an edit made there does not survive the next \`init\` either.
|
|
112
115
|
|
|
113
116
|
## Local directories
|
|
114
117
|
|
|
115
118
|
Both are \`ticket-runner\`'s own, both are gitignored by \`ticket-runner init\`, and neither is ever committed.
|
|
116
119
|
|
|
117
|
-
- \`.worktrees/ticket-<n>/\` — one git worktree per claimed Ticket, where its Stages run. Beside them, \`.worktrees/base-<commit>/\` is a clean worktree at a merge-base with the
|
|
118
|
-
- \`.ticket-runner/\` — the Run's logs and Stage transcripts. The Run lock and the
|
|
120
|
+
- \`.worktrees/ticket-<n>/\` — one git worktree per claimed Ticket, where its Stages run. Beside them, \`.worktrees/base-<commit>/\` is a clean worktree at a merge-base with the base branch, made to run a failing Check there once and removed when it has run.
|
|
121
|
+
- \`.ticket-runner/\` — the Run's logs and Stage transcripts. The Run lock and the state file a Ticket keeps while its branch has work worth resuming are not here but on the Target's remote, so that a Run on any Host sees which Run holds the Target, and carries on from where a killed Run, or a handed-off Ticket relabelled \`ready-for-agent\`, stopped.
|
|
119
122
|
`;
|
package/src/credential.ts
CHANGED
|
@@ -16,31 +16,116 @@ export type Credential = "subscription" | "api-key";
|
|
|
16
16
|
*/
|
|
17
17
|
export const API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
|
|
18
18
|
|
|
19
|
-
/**
|
|
19
|
+
/** What the Stages are billed to, as the Run summary's header and the log name it. */
|
|
20
20
|
export const CREDENTIAL_WORDS: Record<Credential, string> = {
|
|
21
21
|
subscription: "subscription",
|
|
22
22
|
"api-key": "API key",
|
|
23
23
|
};
|
|
24
24
|
|
|
25
25
|
/**
|
|
26
|
-
* The `apiKeySource` a Stage's `system/init` event reports when it
|
|
27
|
-
* Run
|
|
28
|
-
* choose: a key an `apiKeyHelper` in the
|
|
29
|
-
* no environment variable removes.
|
|
26
|
+
* The `apiKeySource` a Stage's `system/init` event reports when it was billed
|
|
27
|
+
* to the subscription or API key its Run started with. Any other is a Stage
|
|
28
|
+
* billed somewhere the Run did not choose: a key an `apiKeyHelper` in the
|
|
29
|
+
* Host's settings supplied, say, which no environment variable removes.
|
|
30
30
|
*/
|
|
31
31
|
export function expectedKeySource(credential: Credential): string {
|
|
32
32
|
return credential === "api-key" ? API_KEY_ENV_VAR : "none";
|
|
33
33
|
}
|
|
34
34
|
|
|
35
35
|
/**
|
|
36
|
-
* A Stage that reported another `apiKeySource` than
|
|
37
|
-
*
|
|
36
|
+
* A Stage that reported another `apiKeySource` than the one
|
|
37
|
+
* {@link expectedKeySource} gives its Run, which the Run's log and its
|
|
38
|
+
* summary each name.
|
|
38
39
|
*/
|
|
39
40
|
export interface StrayStage {
|
|
40
41
|
ticket: number;
|
|
41
42
|
stage: string;
|
|
42
43
|
/** What the Stage's `system/init` event said it ran on. */
|
|
43
44
|
apiKeySource: string;
|
|
45
|
+
/** What the CLI priced the Stage at, where it said. */
|
|
46
|
+
costUsd?: number;
|
|
47
|
+
/** Present, and true, where {@link costUsd} is only part of the Stage's. */
|
|
48
|
+
costIncomplete?: true;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* What a Run's Stages were billed, gathered as each comes back and shared by
|
|
53
|
+
* every Ticket, for the Run summary and nothing else: the log and the progress
|
|
54
|
+
* comment carry no amount.
|
|
55
|
+
*/
|
|
56
|
+
export interface Billing {
|
|
57
|
+
/** Every Stage billed to something other than its Run's subscription or API key, in order. */
|
|
58
|
+
strays: StrayStage[];
|
|
59
|
+
/**
|
|
60
|
+
* The spend, in dollars: the CLI's figures for the Stages of an `--api-key`
|
|
61
|
+
* Run that ran on the Run's own key, added up, which is the amount that key's
|
|
62
|
+
* Console can be checked against. Always zero on a subscription Run, whose
|
|
63
|
+
* figure is an estimate at API prices and not money spent.
|
|
64
|
+
*/
|
|
65
|
+
spendUsd: number;
|
|
66
|
+
/**
|
|
67
|
+
* Whether a Stage that ran on the Run's own key reported no figure, or only
|
|
68
|
+
* part of its session's — one the wall-clock limit stopped or that crashed —
|
|
69
|
+
* so the spend is at least {@link spendUsd}.
|
|
70
|
+
*/
|
|
71
|
+
spendUnreported: boolean;
|
|
72
|
+
/** Whether any Stage said it ran on the subscription's extra usage. */
|
|
73
|
+
extraUsage: boolean;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** A Run's billing before any Stage has come back. */
|
|
77
|
+
export function emptyBilling(): Billing {
|
|
78
|
+
return { strays: [], spendUsd: 0, spendUnreported: false, extraUsage: false };
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** What a Stage said about what it was billed to, as far as {@link Billing} needs it. */
|
|
82
|
+
export interface StageBilling {
|
|
83
|
+
/** What the Stage's `system/init` event said it ran on, absent where it printed none. */
|
|
84
|
+
apiKeySource?: string;
|
|
85
|
+
/** What the CLI priced the Stage at, absent where no `result` event gave a figure. */
|
|
86
|
+
costUsd?: number;
|
|
87
|
+
/** Present, and true, where {@link costUsd} is only part of the Stage's. */
|
|
88
|
+
costIncomplete?: true;
|
|
89
|
+
/** Present, and true, where the Stage ran on the subscription's extra usage. */
|
|
90
|
+
extraUsage?: true;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Add one Stage of a Run on `credential` to the Run's billing, and return it as
|
|
95
|
+
* a stray where it ran on something else.
|
|
96
|
+
*
|
|
97
|
+
* A Stage that reported no `apiKeySource` printed no `system/init` event and so
|
|
98
|
+
* made no request: it is no stray, adds no spend and leaves the spend exact. A
|
|
99
|
+
* stray's figure stays on its own row and out of the spend, which is the Run's
|
|
100
|
+
* own key's alone.
|
|
101
|
+
*/
|
|
102
|
+
export function recordStage(
|
|
103
|
+
billing: Billing,
|
|
104
|
+
credential: Credential,
|
|
105
|
+
ticket: number,
|
|
106
|
+
stage: string,
|
|
107
|
+
{ apiKeySource, costUsd, costIncomplete, extraUsage }: StageBilling,
|
|
108
|
+
): StrayStage | undefined {
|
|
109
|
+
if (extraUsage === true) billing.extraUsage = true;
|
|
110
|
+
if (apiKeySource === undefined) return undefined;
|
|
111
|
+
|
|
112
|
+
if (apiKeySource !== expectedKeySource(credential)) {
|
|
113
|
+
const stray: StrayStage = {
|
|
114
|
+
ticket,
|
|
115
|
+
stage,
|
|
116
|
+
apiKeySource,
|
|
117
|
+
...(costUsd === undefined ? {} : { costUsd }),
|
|
118
|
+
...(costUsd !== undefined && costIncomplete === true ? { costIncomplete } : {}),
|
|
119
|
+
};
|
|
120
|
+
billing.strays.push(stray);
|
|
121
|
+
return stray;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
if (credential === "api-key") {
|
|
125
|
+
if (costUsd === undefined || costIncomplete === true) billing.spendUnreported = true;
|
|
126
|
+
billing.spendUsd += costUsd ?? 0;
|
|
127
|
+
}
|
|
128
|
+
return undefined;
|
|
44
129
|
}
|
|
45
130
|
|
|
46
131
|
/**
|
package/src/criteria.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Ticking the Acceptance Criteria a
|
|
2
|
+
* Ticking the Acceptance Criteria a verdict proved.
|
|
3
3
|
*
|
|
4
4
|
* A merged Ticket whose checkboxes are all still empty reads as unfinished
|
|
5
5
|
* work, so the criteria verify marked `met` are ticked where they live — the
|
|
@@ -19,45 +19,134 @@ import type { Verdict } from "./verdict.js";
|
|
|
19
19
|
/** {@link UNCHECKED_BOX}, extended to capture the criterion text after the box. */
|
|
20
20
|
const CHECKBOX_LINE = new RegExp(`${UNCHECKED_BOX}( .*)$`, "gm");
|
|
21
21
|
|
|
22
|
+
/** {@link TICKED_BOX}, likewise: a line whose criterion is written, though not open. */
|
|
23
|
+
const TICKED_CHECKBOX_LINE = new RegExp(`${TICKED_BOX}( .*)$`, "gm");
|
|
24
|
+
|
|
22
25
|
/** {@link TICKED_BOX}, over every line of a text rather than the first. */
|
|
23
26
|
const TICKED_LINE = new RegExp(TICKED_BOX, "gm");
|
|
24
27
|
|
|
28
|
+
/** One parenthetical closing a criterion, with the space before it. */
|
|
29
|
+
const TRAILING_PARENTHETICAL = /\s*\([^()]*\)$/;
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Where the verify Stage cut a passage, with the spaces it set the cut off by:
|
|
33
|
+
* a cut takes a comma or a space beside it as often as not, so `reads ... order`
|
|
34
|
+
* stands for `reads, in order`.
|
|
35
|
+
*/
|
|
36
|
+
const ELLIPSIS = /\s*(?:\.\.\.|…)\s*/;
|
|
37
|
+
|
|
25
38
|
/**
|
|
26
39
|
* The same criterion as the verify Stage reported it.
|
|
27
40
|
*
|
|
28
41
|
* The Stage is asked for the criterion verbatim and mostly obliges, but it
|
|
29
42
|
* reflows and recases often enough that an exact match would leave half a
|
|
30
|
-
* Ticket unticked. Whitespace and case are the differences worth forgiving
|
|
31
|
-
* anything more and the risk is ticking a box nobody graded.
|
|
43
|
+
* Ticket unticked. Whitespace and case are the differences worth forgiving on
|
|
44
|
+
* every criterion; anything more and the risk is ticking a box nobody graded.
|
|
45
|
+
*
|
|
46
|
+
* A criterion that matches no checkbox even so gets {@link secondChancePattern},
|
|
47
|
+
* and the reasons for its two forgivenesses are given there.
|
|
32
48
|
*/
|
|
33
49
|
function normalise(text: string): string {
|
|
34
50
|
return text.trim().replaceAll(/\s+/g, " ").toLowerCase();
|
|
35
51
|
}
|
|
36
52
|
|
|
37
53
|
/**
|
|
38
|
-
*
|
|
54
|
+
* The pattern a {@link normalise}d criterion that matched no line exactly is
|
|
55
|
+
* matched again with: one trailing parenthetical dropped, and each `...` or `…`
|
|
56
|
+
* read as any run of characters.
|
|
57
|
+
*
|
|
58
|
+
* The verify Stage appends a note such as `(table)` to a criterion that ends in
|
|
59
|
+
* a colon and puts its content in a block below it, and cuts passages of a long
|
|
60
|
+
* criterion to an ellipsis. Both are seen in the Stage's own output, and nothing
|
|
61
|
+
* else is forgiven here. Either makes a criterion looser than its whole text,
|
|
62
|
+
* so the pattern ticks a line only when it picks out one.
|
|
63
|
+
*
|
|
64
|
+
* `undefined` when nothing but dots is left, which would match any line.
|
|
65
|
+
*/
|
|
66
|
+
function secondChancePattern(criterion: string): RegExp | undefined {
|
|
67
|
+
const passages = criterion.replace(TRAILING_PARENTHETICAL, "").split(ELLIPSIS);
|
|
68
|
+
if (passages.every((passage) => passage.trim() === "")) return undefined;
|
|
69
|
+
return new RegExp(`^${passages.map(escapeRegExp).join(".*")}$`);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function escapeRegExp(text: string): string {
|
|
73
|
+
return text.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* `texts` with every unticked box whose criterion is in `met` ticked, the texts
|
|
78
|
+
* being every place one Ticket writes its criteria: its body and its comments.
|
|
39
79
|
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
80
|
+
* A criterion ticks every line it matches exactly, after {@link normalise}. One
|
|
81
|
+
* that matches no checkbox line in any of the texts, ticked or not, is then
|
|
82
|
+
* offered its {@link secondChancePattern} against the lines still unticked, all the
|
|
83
|
+
* texts' together, and ticks a line only when exactly one matches. Two lines
|
|
84
|
+
* that fit equally well are a guess, and a wrong tick claims a criterion was
|
|
85
|
+
* graded that never was; an unticked one only says the match failed.
|
|
86
|
+
*
|
|
87
|
+
* Returns each text unchanged when nothing in it matched, which is how the
|
|
88
|
+
* caller knows there is nothing to write back.
|
|
42
89
|
*/
|
|
43
|
-
export function tickCriteria(
|
|
90
|
+
export function tickCriteria(texts: readonly string[], met: readonly string[]): string[] {
|
|
44
91
|
const wanted = new Set(met.map(normalise));
|
|
45
|
-
if (wanted.size === 0) return
|
|
92
|
+
if (wanted.size === 0) return [...texts];
|
|
93
|
+
|
|
94
|
+
const exact = texts.map((text) => tickLines(text, (rest) => wanted.has(normalise(rest))));
|
|
95
|
+
|
|
96
|
+
const written = new Set(
|
|
97
|
+
texts.flatMap((text) =>
|
|
98
|
+
[CHECKBOX_LINE, TICKED_CHECKBOX_LINE].flatMap((pattern) =>
|
|
99
|
+
[...text.matchAll(pattern)].map(([, , rest = ""]) => normalise(rest)),
|
|
100
|
+
),
|
|
101
|
+
),
|
|
102
|
+
);
|
|
103
|
+
const missed = [...wanted].filter((criterion) => !written.has(criterion));
|
|
104
|
+
if (missed.length === 0) return exact;
|
|
105
|
+
|
|
106
|
+
const open = exact.flatMap((text, place) =>
|
|
107
|
+
[...text.matchAll(CHECKBOX_LINE)].map(({ index, 2: rest = "" }) => ({
|
|
108
|
+
key: lineKey(place, index),
|
|
109
|
+
text: normalise(rest),
|
|
110
|
+
})),
|
|
111
|
+
);
|
|
112
|
+
const chosen = new Set<string>();
|
|
113
|
+
for (const criterion of missed) {
|
|
114
|
+
const pattern = secondChancePattern(criterion);
|
|
115
|
+
if (pattern === undefined) continue;
|
|
116
|
+
const matches = open.filter((line) => pattern.test(line.text));
|
|
117
|
+
if (matches.length === 1 && matches[0] !== undefined) chosen.add(matches[0].key);
|
|
118
|
+
}
|
|
119
|
+
if (chosen.size === 0) return exact;
|
|
46
120
|
|
|
47
|
-
return
|
|
48
|
-
|
|
121
|
+
return exact.map((text, place) =>
|
|
122
|
+
tickLines(text, (_rest, index) => chosen.has(lineKey(place, index))),
|
|
49
123
|
);
|
|
50
124
|
}
|
|
51
125
|
|
|
126
|
+
/** `text` with each unticked box ticked whose line `tick` picks, by its criterion or offset. */
|
|
127
|
+
function tickLines(text: string, tick: (rest: string, index: number) => boolean): string {
|
|
128
|
+
return text.replaceAll(CHECKBOX_LINE, (line, bullet: string, rest: string, index: number) =>
|
|
129
|
+
tick(rest, index) ? `${bullet}[x]${rest}` : line,
|
|
130
|
+
);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** One checkbox line on the whole Ticket: which text it is in, and where in it. */
|
|
134
|
+
function lineKey(place: number, index: number): string {
|
|
135
|
+
return `${place}:${index}`;
|
|
136
|
+
}
|
|
137
|
+
|
|
52
138
|
/**
|
|
53
|
-
* Tick every criterion the
|
|
139
|
+
* Tick every criterion the verdict proved, wherever the Ticket writes it.
|
|
54
140
|
*
|
|
55
141
|
* The issue is read again rather than reusing the copy it was claimed with: a
|
|
56
142
|
* whole Run has happened since, and both the body and any comment are written
|
|
57
143
|
* back whole. Triage posts its brief as a comment, and nothing says all the
|
|
58
144
|
* criteria are in one place, so every comment is offered the same edit.
|
|
59
145
|
*
|
|
60
|
-
*
|
|
146
|
+
* The body and the comments are matched together, because a criterion's second
|
|
147
|
+
* chance must pick out one line on the whole Ticket, not one in each place.
|
|
148
|
+
*
|
|
149
|
+
* A criterion the Stage reworded past both chances matches nothing and is
|
|
61
150
|
* left as it was, which is said out loud rather than passed over in silence: a
|
|
62
151
|
* merged Ticket with an unticked criterion is otherwise a mystery.
|
|
63
152
|
*/
|
|
@@ -73,16 +162,19 @@ export async function tickMetCriteria(
|
|
|
73
162
|
if (met.length === 0) return;
|
|
74
163
|
|
|
75
164
|
const issue = await tracker.getIssue(ticket);
|
|
165
|
+
const [body = issue.body, ...comments] = tickCriteria(
|
|
166
|
+
[issue.body, ...issue.comments.map((comment) => comment.body)],
|
|
167
|
+
met,
|
|
168
|
+
);
|
|
76
169
|
let ticked = 0;
|
|
77
170
|
|
|
78
|
-
const body = tickCriteria(issue.body, met);
|
|
79
171
|
if (body !== issue.body) {
|
|
80
172
|
await tracker.updateIssueBody(ticket, body);
|
|
81
173
|
ticked += ticks(issue.body, body);
|
|
82
174
|
}
|
|
83
175
|
|
|
84
|
-
for (const comment of issue.comments) {
|
|
85
|
-
const edited =
|
|
176
|
+
for (const [place, comment] of issue.comments.entries()) {
|
|
177
|
+
const edited = comments[place] ?? comment.body;
|
|
86
178
|
if (edited === comment.body || comment.id === undefined) continue;
|
|
87
179
|
await tracker.updateComment(comment.id, edited);
|
|
88
180
|
ticked += ticks(comment.body, edited);
|
package/src/failing-base.ts
CHANGED
|
@@ -2,20 +2,20 @@
|
|
|
2
2
|
* Whether a Check a Ticket's branch failed is one it inherited.
|
|
3
3
|
*
|
|
4
4
|
* The Checks run on the Ticket's branch, and CI on its pull request, so a
|
|
5
|
-
* failure alone cannot say whether the branch brought it or the
|
|
6
|
-
* did. A test that starts failing on the
|
|
5
|
+
* failure alone cannot say whether the branch brought it or the base branch
|
|
6
|
+
* did. A test that starts failing on the base branch fails on every branch at
|
|
7
7
|
* once, and a fix Stage per Ticket then mends it differently in each pull
|
|
8
|
-
* request, at the cost of every Ticket's
|
|
9
|
-
* once more, at what the branch inherited: its merge-base with the
|
|
8
|
+
* request, at the cost of every Ticket's fix budget. So a failure is graded
|
|
9
|
+
* once more, at what the branch inherited: its merge-base with the base branch,
|
|
10
10
|
* checked out clean in a worktree of its own. One that fails there too is the
|
|
11
|
-
*
|
|
11
|
+
* base branch's, and the Ticket is released rather than charged for it.
|
|
12
12
|
*/
|
|
13
13
|
|
|
14
14
|
import { baseWorktreePath } from "./branch.js";
|
|
15
15
|
import type { RoutedNote } from "./notes.js";
|
|
16
16
|
import type { CheckOutcome, Workspace } from "./ports/workspace.js";
|
|
17
17
|
|
|
18
|
-
/** A Check command the
|
|
18
|
+
/** A Check command the base branch fails, and how. */
|
|
19
19
|
export interface FailingBase {
|
|
20
20
|
/** The merge-base it fails at, in full. */
|
|
21
21
|
commit: string;
|
|
@@ -38,7 +38,7 @@ export interface BaseCheckRun {
|
|
|
38
38
|
* posted about the ones that failed there.
|
|
39
39
|
*
|
|
40
40
|
* A Run has one and every Lane shares it, so the Tickets that fail together
|
|
41
|
-
* over one broken
|
|
41
|
+
* over one broken base branch cost one run of the Check between them, and one
|
|
42
42
|
* Note. Runs at the same commit take turns, because they share its worktree.
|
|
43
43
|
* A run that could not be made — no worktree, no git — is forgotten rather
|
|
44
44
|
* than kept, as a standing Notes lookup that failed is: the Ticket that asked
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An error message as the pipeline shows it.
|
|
3
|
+
*
|
|
4
|
+
* A failure the pipeline did not expect reaches it as an error whose message
|
|
5
|
+
* is a command and how it exited, on its first line, and then whatever the
|
|
6
|
+
* command printed: `throwOnFailure` in `adapters/exec.ts` builds it so, giving
|
|
7
|
+
* an argument with a newline in it by its first line alone. Wherever one line
|
|
8
|
+
* is expected — a hand-off's `Failure:` line, a draft pull request's opening,
|
|
9
|
+
* a Run summary's row, a console log line — the first line goes, and the
|
|
10
|
+
* output goes where the whole of it can be read. No line of the output is
|
|
11
|
+
* picked as the reason: a rule that picked one would name the wrong cause on
|
|
12
|
+
* an output nobody has seen yet, and the output is never dropped.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/** A message's one line, and the output that followed it. */
|
|
16
|
+
export interface SplitMessage {
|
|
17
|
+
/** The first line that says anything: the command and how it exited. */
|
|
18
|
+
line: string;
|
|
19
|
+
/** Everything after it, trimmed; empty when the message is one line. */
|
|
20
|
+
output: string;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export function splitMessage(message: string): SplitMessage {
|
|
24
|
+
const lines = message.split("\n");
|
|
25
|
+
const first = lines.findIndex((line) => line.trim() !== "");
|
|
26
|
+
if (first === -1) return { line: "", output: "" };
|
|
27
|
+
return {
|
|
28
|
+
line: lines[first]!.trim(),
|
|
29
|
+
output: lines
|
|
30
|
+
.slice(first + 1)
|
|
31
|
+
.join("\n")
|
|
32
|
+
.trim(),
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* What a log line whose output was already printed in this Run says in place
|
|
38
|
+
* of printing it again.
|
|
39
|
+
*/
|
|
40
|
+
const SAME_OUTPUT = "the same output as above";
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* The Run's console log, printing each failure's output once.
|
|
44
|
+
*
|
|
45
|
+
* One cause tends to fail several steps of a Ticket in turn — a remote that
|
|
46
|
+
* refuses SSH fails the push, the draft pull request, the transcripts and the
|
|
47
|
+
* pull the rebase starts with — and each event logs the same output. Printed
|
|
48
|
+
* nine times it buries the lines that matter, so a line whose output this log
|
|
49
|
+
* has already printed gives its one line and says the output is the same.
|
|
50
|
+
* A line with no output passes as it is.
|
|
51
|
+
*/
|
|
52
|
+
export function printEachOutputOnce(print: (line: string) => void): (line: string) => void {
|
|
53
|
+
const printed = new Set<string>();
|
|
54
|
+
return (text) => {
|
|
55
|
+
const { line, output } = splitMessage(text);
|
|
56
|
+
if (output === "") return print(text);
|
|
57
|
+
if (printed.has(output)) return print(`${line} · ${SAME_OUTPUT}`);
|
|
58
|
+
printed.add(output);
|
|
59
|
+
print(text);
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* A quoted message ended as a sentence, so that a sentence can follow it.
|
|
65
|
+
*
|
|
66
|
+
* A command's output often ends with its own full stop, and one appended after
|
|
67
|
+
* it reads as a typo: "…and the repository exists.. It still names this Run".
|
|
68
|
+
*/
|
|
69
|
+
export function endSentence(message: string): string {
|
|
70
|
+
const trimmed = message.trimEnd();
|
|
71
|
+
return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
|
|
72
|
+
}
|
package/src/guards.ts
CHANGED
|
@@ -54,8 +54,8 @@ export function skipReason(
|
|
|
54
54
|
/**
|
|
55
55
|
* Whether this is a **Stranded Ticket**: one this checkout already holds, left
|
|
56
56
|
* claimed by a Run that never came back (GLOSSARY.md). Both refusals read the
|
|
57
|
-
*
|
|
58
|
-
* assignee is this very user and `ready-for-agent` came off when the
|
|
57
|
+
* claim as somebody else's work, and a stranded Ticket wears it itself — the
|
|
58
|
+
* assignee is this very user and `ready-for-agent` came off when the claim was
|
|
59
59
|
* made — so it passes them and is resumed rather than refused. The Planning
|
|
60
60
|
* guards below still grade it: they are about the issue, not about who has it.
|
|
61
61
|
*
|
package/src/handoff.ts
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* the Ticket is relabelled and a Run takes it again, the comment still reads as
|
|
6
6
|
* the last word on it — and on a Ticket that then merges it is the last thing
|
|
7
7
|
* on a closed issue, because the progress comment is edited in place above it
|
|
8
|
-
* and the merge writes nothing below. So the
|
|
8
|
+
* and the merge writes nothing below. So the claim marks every hand-off comment
|
|
9
9
|
* on the Ticket as history on its way past.
|
|
10
10
|
*
|
|
11
11
|
* Marked, not removed: the failure, the location and the evidence are worth
|
|
@@ -21,7 +21,7 @@ import { HANDOFF_MARKER, findMarkedComments, handoffTakenComment } from "./templ
|
|
|
21
21
|
* Every hand-off comment the Ticket is still carrying as current, each with the
|
|
22
22
|
* body that would mark it as history.
|
|
23
23
|
*
|
|
24
|
-
* One question, asked twice: it is what the
|
|
24
|
+
* One question, asked twice: it is what the claim edits, and it is also what
|
|
25
25
|
* says a human has been holding the Ticket since the last Run put it down.
|
|
26
26
|
*/
|
|
27
27
|
function unmarkedHandoffs(
|
package/src/init.ts
CHANGED
|
@@ -63,12 +63,12 @@ const FAIL = "✗";
|
|
|
63
63
|
export interface InitOptions {
|
|
64
64
|
repoRoot: string;
|
|
65
65
|
/**
|
|
66
|
-
* The
|
|
66
|
+
* The version doing the setting up, which the report's first line names. A
|
|
67
67
|
* string the CLI resolved, never something read from here (ADR-0007).
|
|
68
68
|
*/
|
|
69
69
|
version: string;
|
|
70
70
|
/**
|
|
71
|
-
* The pipeline's own repository, as `owner/name`, which the newer-
|
|
71
|
+
* The pipeline's own repository, as `owner/name`, which the newer-version
|
|
72
72
|
* notice is looked up against; see {@link import("./staleness.js")}.
|
|
73
73
|
*/
|
|
74
74
|
repository?: string | undefined;
|
|
@@ -170,7 +170,7 @@ function writeTargetFiles(repoRoot: string, version: string): string[] {
|
|
|
170
170
|
}
|
|
171
171
|
|
|
172
172
|
/**
|
|
173
|
-
* The
|
|
173
|
+
* The version that set this Target up, where it is newer than the one setting
|
|
174
174
|
* it up now, and nothing otherwise.
|
|
175
175
|
*
|
|
176
176
|
* Read off the conventions document's mark, which is the only thing in a
|
|
@@ -184,7 +184,7 @@ export function newerSetUp(repoRoot: string, version: string): NewerSetUp | unde
|
|
|
184
184
|
: undefined;
|
|
185
185
|
}
|
|
186
186
|
|
|
187
|
-
/** Which newer
|
|
187
|
+
/** Which newer version set a Target up, and which one found it. */
|
|
188
188
|
export interface NewerSetUp {
|
|
189
189
|
mark: string;
|
|
190
190
|
own: string;
|
|
@@ -229,7 +229,7 @@ function ensureConfigFile(repoRoot: string): string | undefined {
|
|
|
229
229
|
*
|
|
230
230
|
* The mark is read before the text, because it is the only thing that says
|
|
231
231
|
* which way round the two copies are. Nothing is refused either way: a Target
|
|
232
|
-
* is not worse for carrying a document from another
|
|
232
|
+
* is not worse for carrying a document from another version.
|
|
233
233
|
*/
|
|
234
234
|
function ensureConventionsDoc(
|
|
235
235
|
repoRoot: string,
|
|
@@ -254,9 +254,9 @@ function ensureConventionsDoc(
|
|
|
254
254
|
/**
|
|
255
255
|
* Which of the four ways a copy came to be rewritten this one was.
|
|
256
256
|
*
|
|
257
|
-
* A copy marked with this very
|
|
257
|
+
* A copy marked with this very version is the odd one: nothing about the
|
|
258
258
|
* pipeline moved, so the difference is something the Target did to the file,
|
|
259
|
-
* and saying it was left by the
|
|
259
|
+
* and saying it was left by the version now writing it would read as nonsense.
|
|
260
260
|
*/
|
|
261
261
|
function rewritten(
|
|
262
262
|
existing: string | undefined,
|
|
@@ -264,7 +264,7 @@ function rewritten(
|
|
|
264
264
|
own: string | undefined,
|
|
265
265
|
): string {
|
|
266
266
|
if (existing === undefined) return "written";
|
|
267
|
-
if (mark === undefined) return "overwritten, because the copy here carried no
|
|
267
|
+
if (mark === undefined) return "overwritten, because the copy here carried no version";
|
|
268
268
|
if (mark === own) return "overwritten, because the copy here said something else";
|
|
269
269
|
return `overwritten, because the copy here was left by ${mark}`;
|
|
270
270
|
}
|