ticket-runner 0.6.4 → 0.6.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.ko.md +5 -5
  2. package/README.md +4 -4
  3. package/docs/templates/operator-skill.md +81 -16
  4. package/package.json +1 -1
  5. package/src/acceptance-criteria.ts +99 -2
  6. package/src/adapters/claude-agent-runner.ts +5 -5
  7. package/src/adapters/exec.ts +32 -4
  8. package/src/adapters/gh-tracker.ts +276 -60
  9. package/src/adapters/git-workspace.ts +27 -10
  10. package/src/adapters/liveness.ts +77 -0
  11. package/src/adapters/process-tree.ts +4 -7
  12. package/src/adapters/version.ts +5 -5
  13. package/src/branch.ts +1 -1
  14. package/src/cli.ts +2 -2
  15. package/src/config.ts +22 -4
  16. package/src/conventions.ts +22 -19
  17. package/src/credential.ts +14 -13
  18. package/src/criteria.ts +102 -52
  19. package/src/failing-base.ts +7 -7
  20. package/src/failure-message.ts +72 -0
  21. package/src/guards.ts +21 -6
  22. package/src/handoff.ts +2 -2
  23. package/src/init.ts +8 -8
  24. package/src/landing.ts +1 -1
  25. package/src/lifecycle.ts +2 -2
  26. package/src/lock.ts +10 -2
  27. package/src/note-schema.ts +14 -11
  28. package/src/notes.ts +19 -7
  29. package/src/operator-skill.ts +2 -2
  30. package/src/orchestrator.ts +758 -275
  31. package/src/outside-fault.ts +103 -0
  32. package/src/ports/agent-runner.ts +1 -1
  33. package/src/ports/tracker.ts +29 -15
  34. package/src/ports/workspace.ts +52 -24
  35. package/src/progress.ts +42 -7
  36. package/src/prompts.ts +242 -34
  37. package/src/readiness.ts +11 -11
  38. package/src/remove.ts +7 -7
  39. package/src/resume.ts +28 -20
  40. package/src/run-log.ts +5 -5
  41. package/src/run.ts +55 -13
  42. package/src/staleness.ts +14 -14
  43. package/src/start.ts +29 -16
  44. package/src/stranded.ts +19 -19
  45. package/src/templates.ts +398 -149
  46. package/src/title.ts +106 -8
  47. package/src/transcript-home.ts +49 -0
  48. package/src/verdict.ts +132 -27
  49. package/src/version-number.ts +13 -13
  50. package/src/version-pr.ts +12 -12
package/src/title.ts CHANGED
@@ -8,6 +8,10 @@
8
8
  * subject describes its own commit: a fix Stage that did most of a Ticket's
9
9
  * work could not retitle a branch whose first commit was already pushed without
10
10
  * rewriting it.
11
+ *
12
+ * The pull request body and the problem and solution the squash commit opens
13
+ * with are answered beside the title for the same reason, and recorded the
14
+ * same way ({@link BranchProse}).
11
15
  */
12
16
 
13
17
  import { CODE_STAGE_NOTES_LIST_SCHEMA } from "./note-schema.js";
@@ -19,31 +23,71 @@ import { CODE_STAGE_NOTES_LIST_SCHEMA } from "./note-schema.js";
19
23
  export const BRANCH_TITLE =
20
24
  "one line summarising the whole branch as it stands when you finish, the work of any Stage before you included";
21
25
 
22
- /** Any `<type>(<scope>): <summary>`; the repo's own types and scopes are CONTRIBUTING.md's business. */
26
+ /**
27
+ * The shape a commit subject and a title take, as the prompts of the code
28
+ * Stages and the schema state it: one declaration, so they cannot drift apart.
29
+ * The conventions document a Target carries states it to the readers the
30
+ * pipeline does not brief.
31
+ */
32
+ export const SUBJECT_SHAPE = "<type>(<scope>): <summary>";
33
+
34
+ /** Any {@link SUBJECT_SHAPE}; the repo's own types and scopes are CONTRIBUTING.md's business. */
23
35
  const CONVENTIONAL_SUBJECT = /^[a-z]+(\([a-z0-9._-]+\))?: \S/;
24
36
 
25
37
  /** The `(#<n>)` a commit may carry, which the squash commit's `Closes #<n>` replaces. */
26
38
  const TICKET_REFERENCE = /\s*\(#\d+\)$/;
27
39
 
40
+ /**
41
+ * How the schema tells a Stage to keep an answer: an empty one is how a fix
42
+ * Stage leaves the body, problem or solution before it standing.
43
+ */
44
+ const KEEP_EARLIER = "An empty string keeps the one an earlier Stage answered.";
45
+
28
46
  /**
29
47
  * The `--json-schema` the implement and fix Stages are invoked with: the title
30
- * of the whole branch, and the Notes channel beside it.
48
+ * of the whole branch, the pull request body, the problem and the solution the
49
+ * squash commit opens with, the Notes channel beside them, and why the Stage
50
+ * ended with no new commit when it did.
31
51
  *
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.
52
+ * All are required, so a Stage always says something about each: an empty
53
+ * Notes list when it found nothing, a title however little it did, an empty
54
+ * string for a body, problem or solution it leaves as it was, and an empty
55
+ * reason when it committed. The parsers forgive each one on its own
56
+ * ({@link parseTitle}, {@link parseBranchProse}, `parseNotes` and
57
+ * {@link parseNoCommitReason}), so a bad answer to one never costs the others.
58
+ *
59
+ * The reason is asked for in its own field because, under `--json-schema`, the
60
+ * answer is all of the session the pipeline reads: a last message in prose is
61
+ * only an earlier turn of the transcript. A Stage that ends with no new commit
62
+ * hands the Ticket to a human, and the hand-off quotes the reason (#306).
36
63
  */
37
64
  export const CODE_STAGE_JSON_SCHEMA = {
38
65
  type: "object",
39
66
  properties: {
40
67
  title: {
41
68
  type: "string",
42
- description: `Write ${BRANCH_TITLE}: \`<type>(<scope>): <summary>\`, without the \`(#<n>)\`. It titles the pull request and the squash commit that lands.`,
69
+ description: `Write ${BRANCH_TITLE}: \`${SUBJECT_SHAPE}\`, without the \`(#<n>)\`. It titles the pull request and the squash commit that lands.`,
70
+ },
71
+ body: {
72
+ type: "string",
73
+ description: `The pull request body for the whole branch, without a title and without the \`Closes #<n>\` line the pipeline writes above it. ${KEEP_EARLIER}`,
74
+ },
75
+ problem: {
76
+ type: "string",
77
+ description: `The problem the branch solves, for the squash commit's body, in the shape your prompt gives. ${KEEP_EARLIER}`,
78
+ },
79
+ solution: {
80
+ type: "string",
81
+ description: `The solution, for the squash commit's body after the problem, in the shape your prompt gives. ${KEEP_EARLIER}`,
43
82
  },
44
83
  notes: CODE_STAGE_NOTES_LIST_SCHEMA,
84
+ noCommitReason: {
85
+ type: "string",
86
+ description:
87
+ "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.",
88
+ },
45
89
  },
46
- required: ["title", "notes"],
90
+ required: ["title", "body", "problem", "solution", "notes", "noCommitReason"],
47
91
  additionalProperties: false,
48
92
  } as const;
49
93
 
@@ -73,6 +117,60 @@ export function parseTitle(result: unknown): string | undefined {
73
117
  return typeof raw === "string" ? asTitle(raw) : undefined;
74
118
  }
75
119
 
120
+ /**
121
+ * The prose a code Stage answers about the whole branch beside its title: the
122
+ * pull request body, and the problem and the solution the squash commit opens
123
+ * with. Each is absent where no Stage has answered one, and the latest one
124
+ * answered stands until a later Stage answers it again.
125
+ */
126
+ export interface BranchProse {
127
+ body?: string;
128
+ problem?: string;
129
+ solution?: string;
130
+ }
131
+
132
+ /** The fields of {@link BranchProse}, in the order the squash commit and the prompts give them. */
133
+ export const BRANCH_PROSE_FIELDS = ["body", "problem", "solution"] as const;
134
+
135
+ /**
136
+ * The body, the problem and the solution in a Stage's structured output, each
137
+ * one it answered with something in it.
138
+ *
139
+ * Forgiving, as the title is: output that is not an object and a missing,
140
+ * blank or non-string answer each cost that answer alone, and a blank one is
141
+ * also how a fix Stage leaves the earlier answer standing. The lines are kept as
142
+ * the Stage wrote them, so a list stays a list; only the ends are trimmed.
143
+ */
144
+ export function parseBranchProse(result: unknown): BranchProse {
145
+ const prose: BranchProse = {};
146
+ for (const field of BRANCH_PROSE_FIELDS) {
147
+ const answer = answeredText(result, field);
148
+ if (answer !== undefined) prose[field] = answer;
149
+ }
150
+ return prose;
151
+ }
152
+
153
+ /**
154
+ * Why a code Stage ended with no new commit, as it answered it, or nothing
155
+ * when it gave no reason.
156
+ *
157
+ * Forgiving, as the title and the Notes beside it are: output that is not an
158
+ * object and a missing, blank or non-string reason each cost the reason alone.
159
+ * The lines are kept as the Stage wrote them; only the ends are trimmed.
160
+ */
161
+ export function parseNoCommitReason(result: unknown): string | undefined {
162
+ return answeredText(result, "noCommitReason");
163
+ }
164
+
165
+ /** A string field of a Stage's output, trimmed, or nothing where it holds none. */
166
+ function answeredText(result: unknown, field: string): string | undefined {
167
+ if (typeof result !== "object" || result === null) return undefined;
168
+ const raw = (result as Record<string, unknown>)[field];
169
+ if (typeof raw !== "string") return undefined;
170
+ const text = raw.trim();
171
+ return text === "" ? undefined : text;
172
+ }
173
+
76
174
  /**
77
175
  * The pull request title, in this order of preference: the latest title a
78
176
  * Stage answered, whether in this Run or recorded by the one before it; the
@@ -0,0 +1,49 @@
1
+ import type { Config } from "./config.js";
2
+ import type { HostKind } from "./host.js";
3
+ import type { Tracker } from "./ports/tracker.js";
4
+
5
+ /**
6
+ * Where a Run keeps a handed-off Ticket's transcripts: on the Target's remote,
7
+ * beside the Ticket's state (ADR-0004), or on the Host the Run executes on,
8
+ * which a workstation outlives and a cloud Host's VM does not.
9
+ */
10
+ export type TranscriptHome = "remote" | HostKind;
11
+
12
+ export interface ResolvedTranscriptHome {
13
+ home: TranscriptHome;
14
+ /** The one line the Run says when the Target's visibility could not be read. */
15
+ said?: string;
16
+ }
17
+
18
+ /**
19
+ * Where this Run keeps a handed-off Ticket's transcripts, decided once before
20
+ * the first Ticket.
21
+ *
22
+ * The config's `keepTranscripts` wins where it is set. Unset, the Target's
23
+ * visibility answers: a transcript holds whatever the Host could see, and on
24
+ * a public Target the state branch is public and a pushed commit stays
25
+ * reachable by its SHA, so it stays off the remote there (ADR-0004). A Target
26
+ * whose visibility cannot be read counts as public, and the Run says so.
27
+ */
28
+ export async function resolveTranscriptHome({
29
+ config,
30
+ tracker,
31
+ host,
32
+ }: {
33
+ config: Pick<Config, "keepTranscripts">;
34
+ tracker: Pick<Tracker, "visibility">;
35
+ host: HostKind;
36
+ }): Promise<ResolvedTranscriptHome> {
37
+ if (config.keepTranscripts !== undefined) {
38
+ return { home: config.keepTranscripts ? "remote" : host };
39
+ }
40
+ const visibility = await tracker.visibility();
41
+ if (visibility === "private") return { home: "remote" };
42
+ if (visibility === "public") return { home: host };
43
+ return {
44
+ home: host,
45
+ said:
46
+ "could not read whether the Target is public, so it counts as public: " +
47
+ "a handed-off Ticket's transcripts stay on this Host",
48
+ };
49
+ }
package/src/verdict.ts CHANGED
@@ -1,41 +1,102 @@
1
+ import type { ListedCriterion } from "./acceptance-criteria.js";
1
2
  import { NOTES_LIST_SCHEMA } from "./note-schema.js";
2
3
  import { z } from "zod";
3
4
 
4
5
  /**
5
6
  * The structured result of the verify Stage: one status per Acceptance
6
- * Criterion, with the evidence the session gathered for it.
7
+ * Criterion, answered by the number the pipeline listed it under, with the
8
+ * evidence the session gathered for it, and the defects of the branch it found
9
+ * beside them.
7
10
  */
8
- const criterionSchema = z.object({
9
- text: z.string(),
11
+ const answerSchema = z.object({
12
+ number: z.number().int(),
10
13
  status: z.enum(["met", "unmet", "unverifiable"]),
11
14
  evidence: z.string(),
12
15
  });
13
16
 
14
- const verdictSchema = z.object({
15
- criteria: z.array(criterionSchema).min(1),
17
+ const defectSchema = z.object({
18
+ summary: z.string(),
19
+ evidence: z.string(),
20
+ });
21
+
22
+ const answeredSchema = z.object({
23
+ criteria: z.array(answerSchema).min(1),
24
+ defects: z.array(defectSchema).default([]),
16
25
  /** The agent's own opinion. The pipeline recomputes it; see {@link passes}. */
17
26
  pass: z.boolean(),
18
27
  });
19
28
 
20
- export type Criterion = z.infer<typeof criterionSchema>;
21
- export type Verdict = z.infer<typeof verdictSchema>;
22
- export type CriterionStatus = Criterion["status"];
29
+ /** The verdict as the Stage answered it, before its numbers are checked against the list. */
30
+ export type AnsweredVerdict = z.infer<typeof answeredSchema>;
31
+ export type CriterionStatus = z.infer<typeof answerSchema>["status"];
32
+
33
+ /**
34
+ * A defect this branch introduced, or one in code it added, which the verify
35
+ * Stage reports beside the criteria rather than as a Note. It fails the
36
+ * verdict as an `unmet` criterion does.
37
+ */
38
+ export type Defect = z.infer<typeof defectSchema>;
39
+
40
+ /** One listed criterion and what the verdict made of it. */
41
+ export interface GradedCriterion extends ListedCriterion {
42
+ status: CriterionStatus;
43
+ evidence: string;
44
+ }
23
45
 
24
46
  /**
25
- * The `--json-schema` the verify Stage is invoked with: the Verdict, and the
47
+ * A verdict whose numbers are exactly the listed ones: every criterion carries
48
+ * the line the pipeline listed it as, so whatever shows a criterion shows the
49
+ * Ticket's words and never the Stage's copy of them.
50
+ */
51
+ export interface Verdict {
52
+ criteria: GradedCriterion[];
53
+ defects: Defect[];
54
+ }
55
+
56
+ /**
57
+ * How a verdict's numbers missed the list, which means it has not graded the
58
+ * Ticket: a number listed and not answered, one answered and not listed, one
59
+ * answered more than once.
60
+ */
61
+ export interface Misnumbered {
62
+ missing: number[];
63
+ unlisted: number[];
64
+ repeated: number[];
65
+ }
66
+
67
+ /** The `defects` list as the verify Stage reads it. */
68
+ const DEFECTS_LIST_SCHEMA = {
69
+ type: "array",
70
+ description:
71
+ "Defects this branch introduced, or in code it added, beside the criteria. Empty when you found none.",
72
+ items: {
73
+ type: "object",
74
+ properties: {
75
+ summary: { type: "string", description: "One short sentence naming the defect." },
76
+ evidence: {
77
+ type: "string",
78
+ description:
79
+ "Where it sits, what you ran or read, what you expected, what came back, and the counterexample. It proposes no fix",
80
+ },
81
+ },
82
+ required: ["summary", "evidence"],
83
+ additionalProperties: false,
84
+ },
85
+ } as const;
86
+
87
+ /**
88
+ * The `--json-schema` the verify Stage is invoked with: the verdict, and the
26
89
  * Notes channel beside it.
27
90
  *
28
91
  * The `notes` list has to be declared here even though {@link parseVerdict}
29
92
  * strips it and the Notes parser reads it off any object at all, because this
30
- * schema closes its top level to additional properties. That closure, not the
31
- * parsing, is what would otherwise leave the most adversarial reader in the
32
- * pipeline with nowhere to put a finding outside the criteria.
93
+ * schema closes its top level to additional properties.
33
94
  *
34
- * It is not required, where the criteria and the flag are. The Verdict is the
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 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.
95
+ * Neither `notes` nor `defects` is required, where the criteria and the flag
96
+ * are. The verdict is the Stage's product and a session that graded nothing has
97
+ * done none of its job, so every required key here is a way for a Ticket to
98
+ * lose its verdict. A verdict that leaves a list out is one from a session that
99
+ * found nothing to put in it.
39
100
  */
40
101
  export const VERDICT_JSON_SCHEMA = {
41
102
  type: "object",
@@ -45,36 +106,80 @@ export const VERDICT_JSON_SCHEMA = {
45
106
  items: {
46
107
  type: "object",
47
108
  properties: {
48
- text: { type: "string", description: "The Acceptance Criterion verbatim" },
109
+ number: {
110
+ type: "integer",
111
+ description: "The criterion's number in the list the prompt gives",
112
+ },
49
113
  status: { type: "string", enum: ["met", "unmet", "unverifiable"] },
50
114
  evidence: {
51
115
  type: "string",
52
- description: "What you ran or read, and what it showed",
116
+ description: "What you ran or read, and what it showed. It proposes no fix",
53
117
  },
54
118
  },
55
- required: ["text", "status", "evidence"],
119
+ required: ["number", "status", "evidence"],
56
120
  additionalProperties: false,
57
121
  },
58
122
  },
123
+ defects: DEFECTS_LIST_SCHEMA,
59
124
  pass: { type: "boolean" },
60
- notes: NOTES_LIST_SCHEMA,
125
+ notes: {
126
+ ...NOTES_LIST_SCHEMA,
127
+ description:
128
+ "Defects that belong to another Ticket, or to no Ticket yet. A defect this branch made goes in `defects`, not here. Empty when you found none, which is the ordinary case.",
129
+ },
61
130
  },
62
131
  required: ["criteria", "pass"],
63
132
  additionalProperties: false,
64
133
  } as const;
65
134
 
66
135
  /** Parse the verify Stage's structured output. Throws when it is unusable. */
67
- export function parseVerdict(result: unknown): Verdict {
68
- return verdictSchema.parse(result);
136
+ export function parseVerdict(result: unknown): AnsweredVerdict {
137
+ return answeredSchema.parse(result);
138
+ }
139
+
140
+ /**
141
+ * The answered verdict with each answer joined to the criterion its number
142
+ * names, in the list's order; or how its numbers missed the list, when they do.
143
+ */
144
+ export function gradeVerdict(
145
+ answered: AnsweredVerdict,
146
+ listed: readonly ListedCriterion[],
147
+ ): Verdict | Misnumbered {
148
+ const byNumber = new Map(listed.map((criterion) => [criterion.number, criterion]));
149
+ const answers = new Map<number, AnsweredVerdict["criteria"][number]>();
150
+ const repeated = new Set<number>();
151
+ const unlisted = new Set<number>();
152
+ for (const answer of answered.criteria) {
153
+ if (!byNumber.has(answer.number)) unlisted.add(answer.number);
154
+ else if (answers.has(answer.number)) repeated.add(answer.number);
155
+ else answers.set(answer.number, answer);
156
+ }
157
+ const missing = listed.map(({ number }) => number).filter((number) => !answers.has(number));
158
+ if (missing.length > 0 || unlisted.size > 0 || repeated.size > 0) {
159
+ return { missing, unlisted: [...unlisted], repeated: [...repeated] };
160
+ }
161
+ return {
162
+ criteria: listed.map((criterion) => {
163
+ const { status, evidence } = answers.get(criterion.number) as AnsweredVerdict["criteria"][number];
164
+ return { ...criterion, status, evidence };
165
+ }),
166
+ defects: answered.defects,
167
+ };
168
+ }
169
+
170
+ /** Whether {@link gradeVerdict} found the numbers off. */
171
+ export function isMisnumbered(graded: Verdict | Misnumbered): graded is Misnumbered {
172
+ return "missing" in graded;
69
173
  }
70
174
 
71
175
  /**
72
- * The pipeline's own pass decision: no criterion is unmet and at least one is
73
- * met. A Verdict of nothing but `unverifiable` is zero evidence, so it fails.
176
+ * The pipeline's own pass decision: no criterion is unmet, the branch made no
177
+ * defect, and at least one criterion is met. A verdict of nothing but
178
+ * `unverifiable` is zero evidence, so it fails.
74
179
  */
75
180
  export function passes(verdict: Verdict): boolean {
76
181
  const counts = countStatuses(verdict);
77
- return counts.unmet === 0 && counts.met > 0;
182
+ return counts.unmet === 0 && verdict.defects.length === 0 && counts.met > 0;
78
183
  }
79
184
 
80
185
  export function countStatuses(verdict: Verdict): Record<CriterionStatus, number> {
@@ -83,6 +188,6 @@ export function countStatuses(verdict: Verdict): Record<CriterionStatus, number>
83
188
  return counts;
84
189
  }
85
190
 
86
- export function unmetCriteria(verdict: Verdict): Criterion[] {
191
+ export function unmetCriteria(verdict: Verdict): GradedCriterion[] {
87
192
  return verdict.criteria.filter((criterion) => criterion.status === "unmet");
88
193
  }
@@ -1,49 +1,49 @@
1
1
  /**
2
- * Arithmetic on Version numbers: which of two is higher, and which number a tag
3
- * or a Version string carries.
2
+ * Arithmetic on version numbers: which of two is higher, and which number a tag
3
+ * or a version string carries.
4
4
  *
5
5
  * Three readers share it and would otherwise each have a comparison of their
6
- * own: the check on a Version PR, the notice a Run prints when a newer Version
6
+ * own: the check on a release PR, the notice a Run prints when a newer version
7
7
  * has been published, and the mark a Target's conventions document bears
8
8
  * (ADR-0007). Nothing here reads a file or asks GitHub — a number against a
9
- * number — so the one thing every Version question turns on is proved once.
9
+ * number — so the one thing every version question turns on is proved once.
10
10
  */
11
11
 
12
- /** A number on its own: the three parts every Version tag is cut at. */
12
+ /** A number on its own: the three parts every version tag is cut at. */
13
13
  const NUMBER = /^\d+\.\d+\.\d+$/;
14
14
 
15
15
  /**
16
- * The number a Version string reports, without the commit a development
16
+ * The number a version string reports, without the commit a development
17
17
  * checkout adds: `0.4.0+331d79c.dirty` is `0.4.0`.
18
18
  *
19
19
  * Undefined where the string carries no number at all, which is what a copy
20
20
  * with no package to read calls itself. Comparing by number is what lets a
21
- * checkout running a commit past the latest Version count as current rather
22
- * than as stale: between two Versions the commit says nothing either way.
21
+ * checkout running a commit past the latest version count as current rather
22
+ * than as stale: between two versions the commit says nothing either way.
23
23
  */
24
24
  export function versionNumber(version: string): string | undefined {
25
25
  const [number = ""] = version.split("+");
26
26
  return NUMBER.test(number) ? number : undefined;
27
27
  }
28
28
 
29
- /** The number a Version tag names: `v0.4.0` is `0.4.0`, and nothing else is one. */
29
+ /** The number a version tag names: `v0.4.0` is `0.4.0`, and nothing else is one. */
30
30
  export function tagNumber(tag: string): string | undefined {
31
31
  return tag.startsWith("v") ? versionNumber(tag.slice(1)) : undefined;
32
32
  }
33
33
 
34
- /** A Version tag, in both halves its readers want: `v0.4.0` and `0.4.0`. */
34
+ /** A version tag, in both halves its readers want: `v0.4.0` and `0.4.0`. */
35
35
  export interface VersionTag {
36
36
  tag: string;
37
37
  number: string;
38
38
  }
39
39
 
40
40
  /**
41
- * The highest Version among tags shaped `v<x.y.z>`, and undefined where there
42
- * is no Version tag at all — the first Version, which nothing can be measured
41
+ * The highest version among tags shaped `v<x.y.z>`, and undefined where there
42
+ * is no version tag at all — the first version, which nothing can be measured
43
43
  * against.
44
44
  *
45
45
  * Every other tag is ignored rather than refused: a repository is free to tag
46
- * whatever else it likes, and only the Versions say what has been cut. The tag
46
+ * whatever else it likes, and only the versions say what has been cut. The tag
47
47
  * comes back beside its number because a message names the tag as it was cut
48
48
  * and the comparison is on the number.
49
49
  */
package/src/version-pr.ts CHANGED
@@ -1,12 +1,12 @@
1
1
  /**
2
- * What a Version PR has to get right, and what its merge publishes.
2
+ * What a release PR has to get right, and what its merge publishes.
3
3
  *
4
- * A Version is cut by merging a Version PR: the number in `package.json` goes
5
- * up, `CHANGELOG.md` gains that Version's section, and the push to `main`
4
+ * A version is cut by merging a release PR: the number in `package.json` goes
5
+ * up, `CHANGELOG.md` gains that version's section, and the push to `main`
6
6
  * creates the tag and a GitHub Release whose body is that section (ADR-0007).
7
7
  * The check on the pull request and the workflow that publishes read the same
8
8
  * changelog, so they are written together here: a check that found a section
9
- * the extraction then missed would tag a Version and publish nothing, which is
9
+ * the extraction then missed would tag a version and publish nothing, which is
10
10
  * the one failure neither half can see on its own.
11
11
  *
12
12
  * Both functions are pure. Everything they judge — the two numbers, the tags,
@@ -17,13 +17,13 @@
17
17
  import { highestVersion, isHigher } from "./version-number.js";
18
18
 
19
19
  /**
20
- * The one heading every Version's notes carry, whatever they group the rest by.
20
+ * The one heading every version's notes carry, whatever they group the rest by.
21
21
  * What a Target or its human has to do after upgrading is the thing a reader of
22
22
  * this tool cannot get anywhere else, so its absence is a refusal.
23
23
  */
24
24
  const AFTER_UPGRADING = "### After upgrading";
25
25
 
26
- /** A pull request, in the five things a Version PR is judged by. */
26
+ /** A pull request, in the five things a release PR is judged by. */
27
27
  export interface VersionPr {
28
28
  /** The number in `package.json` on the head. */
29
29
  number: string;
@@ -31,7 +31,7 @@ export interface VersionPr {
31
31
  baseNumber: string;
32
32
  /** The number in the lock file on the head. */
33
33
  lockNumber: string;
34
- /** Every tag the repository has, Version tags and anything else. */
34
+ /** Every tag the repository has, version tags and anything else. */
35
35
  tags: string[];
36
36
  /** `CHANGELOG.md` on the head, empty where the head has none. */
37
37
  changelog: string;
@@ -41,11 +41,11 @@ export interface VersionPr {
41
41
  * Every reason this pull request may not merge, in the order a reader meets
42
42
  * them, and empty where it may.
43
43
  *
44
- * All of them at once rather than the first: the human fixing a Version PR is
44
+ * All of them at once rather than the first: the human fixing a release PR is
45
45
  * running the check through a pull request, and one refusal per push would cost
46
46
  * a round trip each.
47
47
  *
48
- * A number equal to the base branch's is not a Version PR at all, so nothing
48
+ * A number equal to the base branch's is not a release PR at all, so nothing
49
49
  * else is looked at. That is every Ticket's pull request, which passes this
50
50
  * check without being written for it.
51
51
  */
@@ -56,7 +56,7 @@ export function versionPrRefusals(pr: VersionPr): string[] {
56
56
  const highest = highestVersion(pr.tags);
57
57
  if (highest !== undefined && !isHigher(pr.number, highest.number)) {
58
58
  refusals.push(
59
- `\`${pr.number}\` is not higher than every Version tag; \`${highest.tag}\` exists.`,
59
+ `\`${pr.number}\` is not higher than every version tag; \`${highest.tag}\` exists.`,
60
60
  );
61
61
  }
62
62
  if (pr.lockNumber !== pr.number) {
@@ -75,12 +75,12 @@ export function versionPrRefusals(pr: VersionPr): string[] {
75
75
  }
76
76
 
77
77
  /**
78
- * The Version notes for `number`: its section of the changelog, without the
78
+ * The release notes for `number`: its section of the changelog, without the
79
79
  * `## ` heading the number is written in, and undefined where the changelog has
80
80
  * no section for it.
81
81
  *
82
82
  * Undefined is not a failure. The tag workflow falls back to GitHub's generated
83
- * notes, because a Version that reached `main` is cut either way.
83
+ * notes, because a version that reached `main` is cut either way.
84
84
  */
85
85
  export function versionNotes(changelog: string, number: string): string | undefined {
86
86
  return sections(changelog).get(number)?.trim();