ticket-runner 0.6.5 → 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.
package/src/criteria.ts CHANGED
@@ -7,127 +7,79 @@
7
7
  * `unverifiable` criterion is one nobody has evidence for, and a tick would
8
8
  * claim otherwise.
9
9
  *
10
+ * The verdict answers each criterion by the number the pipeline listed it
11
+ * under, so a met criterion is found again by the checkbox line it was listed
12
+ * as, never by what the verify Stage wrote about it. A Ticket edited between
13
+ * verify and the merge can leave that line reading otherwise, or twice; then
14
+ * nothing is ticked for it, since a box left unticked only says the line moved,
15
+ * where a wrong one claims a criterion was graded that never was.
16
+ *
10
17
  * Nothing else in the text is touched. The pipeline is editing a human's
11
18
  * writing, so it rewrites three characters of a line it recognises and leaves
12
19
  * the line, and the document around it, as it found them.
13
20
  */
14
21
 
15
- import { TICKED_BOX, UNCHECKED_BOX } from "./acceptance-criteria.js";
22
+ import { UNCHECKED_BOX } from "./acceptance-criteria.js";
16
23
  import type { Tracker } from "./ports/tracker.js";
17
24
  import type { Verdict } from "./verdict.js";
18
25
 
19
- /** {@link UNCHECKED_BOX}, extended to capture the criterion text after the box. */
20
- const CHECKBOX_LINE = new RegExp(`${UNCHECKED_BOX}( .*)$`, "gm");
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
-
25
- /** {@link TICKED_BOX}, over every line of a text rather than the first. */
26
- const TICKED_LINE = new RegExp(TICKED_BOX, "gm");
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
-
38
- /**
39
- * The same criterion as the verify Stage reported it.
40
- *
41
- * The Stage is asked for the criterion verbatim and mostly obliges, but it
42
- * reflows and recases often enough that an exact match would leave half a
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.
48
- */
49
- function normalise(text: string): string {
50
- return text.trim().replaceAll(/\s+/g, " ").toLowerCase();
51
- }
26
+ /** {@link UNCHECKED_BOX}, over every line of a text, capturing the rest of the line. */
27
+ const CHECKBOX_LINE = new RegExp(`${UNCHECKED_BOX}(.*)$`, "gm");
52
28
 
53
- /**
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(".*")}$`);
29
+ /** A met criterion, as ticking needs it: its number, and the line it was listed as. */
30
+ export interface MetCriterion {
31
+ number: number;
32
+ line: string;
70
33
  }
71
34
 
72
- function escapeRegExp(text: string): string {
73
- return text.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
35
+ /** A met criterion nothing was ticked for, and how many unticked lines read as its own. */
36
+ export interface Untickable {
37
+ number: number;
38
+ /** 0 when no line reads so any more, 2 or more when it is no longer one line. */
39
+ matching: number;
74
40
  }
75
41
 
76
42
  /**
77
- * `texts` with every unticked box whose criterion is in `met` ticked, the texts
43
+ * `texts` with the unticked box of each criterion in `met` ticked, the texts
78
44
  * being every place one Ticket writes its criteria: its body and its comments.
79
45
  *
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.
46
+ * A criterion is ticked on the one unticked checkbox line, across all the
47
+ * texts together, that reads as the line it was listed as, trailing spaces
48
+ * aside. None is ticked when no line, or more than one, reads so.
86
49
  *
87
- * Returns each text unchanged when nothing in it matched, which is how the
50
+ * Returns each text unchanged when nothing in it was ticked, which is how the
88
51
  * caller knows there is nothing to write back.
89
52
  */
90
- export function tickCriteria(texts: readonly string[], met: readonly string[]): string[] {
91
- const wanted = new Set(met.map(normalise));
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 = "" }) => ({
53
+ export function tickCriteria(
54
+ texts: readonly string[],
55
+ met: readonly MetCriterion[],
56
+ ): { texts: string[]; untickable: Untickable[] } {
57
+ const open = texts.flatMap((text, place) =>
58
+ [...text.matchAll(CHECKBOX_LINE)].map(({ index, 0: line }) => ({
108
59
  key: lineKey(place, index),
109
- text: normalise(rest),
60
+ line: line.trimEnd(),
110
61
  })),
111
62
  );
63
+
112
64
  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);
65
+ const untickable: Untickable[] = [];
66
+ for (const criterion of met) {
67
+ const wanted = criterion.line.trimEnd();
68
+ const matches = open.filter((line) => line.line === wanted);
69
+ const [only] = matches;
70
+ if (matches.length === 1 && only !== undefined) chosen.add(only.key);
71
+ else untickable.push({ number: criterion.number, matching: matches.length });
118
72
  }
119
- if (chosen.size === 0) return exact;
120
-
121
- return exact.map((text, place) =>
122
- tickLines(text, (_rest, index) => chosen.has(lineKey(place, index))),
123
- );
124
- }
73
+ if (chosen.size === 0) return { texts: [...texts], untickable };
125
74
 
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
- );
75
+ return {
76
+ texts: texts.map((text, place) =>
77
+ text.replaceAll(CHECKBOX_LINE, (line, bullet: string, rest: string, index: number) =>
78
+ chosen.has(lineKey(place, index)) ? `${bullet}[x]${rest}` : line,
79
+ ),
80
+ ),
81
+ untickable,
82
+ };
131
83
  }
132
84
 
133
85
  /** One checkbox line on the whole Ticket: which text it is in, and where in it. */
@@ -143,12 +95,8 @@ function lineKey(place: number, index: number): string {
143
95
  * back whole. Triage posts its brief as a comment, and nothing says all the
144
96
  * criteria are in one place, so every comment is offered the same edit.
145
97
  *
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
150
- * left as it was, which is said out loud rather than passed over in silence: a
151
- * merged Ticket with an unticked criterion is otherwise a mystery.
98
+ * A met criterion left unticked is said out loud rather than passed over in
99
+ * silence: a merged Ticket with an unticked criterion is otherwise a mystery.
152
100
  */
153
101
  export async function tickMetCriteria(
154
102
  tracker: Tracker,
@@ -156,43 +104,53 @@ export async function tickMetCriteria(
156
104
  verdict: Verdict,
157
105
  log?: (line: string) => void,
158
106
  ): Promise<void> {
159
- const met = verdict.criteria
160
- .filter((criterion) => criterion.status === "met")
161
- .map((criterion) => criterion.text);
107
+ const met = verdict.criteria.filter((criterion) => criterion.status === "met");
162
108
  if (met.length === 0) return;
163
109
 
164
110
  const issue = await tracker.getIssue(ticket);
165
- const [body = issue.body, ...comments] = tickCriteria(
111
+ const { texts, untickable } = tickCriteria(
166
112
  [issue.body, ...issue.comments.map((comment) => comment.body)],
167
113
  met,
168
114
  );
169
- let ticked = 0;
115
+ const [body = issue.body, ...comments] = texts;
116
+ const unwritten: number[] = [];
170
117
 
171
- if (body !== issue.body) {
172
- await tracker.updateIssueBody(ticket, body);
173
- ticked += ticks(issue.body, body);
174
- }
118
+ if (body !== issue.body) await tracker.updateIssueBody(ticket, body);
175
119
 
176
120
  for (const [place, comment] of issue.comments.entries()) {
177
121
  const edited = comments[place] ?? comment.body;
178
- if (edited === comment.body || comment.id === undefined) continue;
122
+ if (edited === comment.body) continue;
123
+ if (comment.id === undefined) {
124
+ unwritten.push(...ticksIn(comment.body, edited, met));
125
+ continue;
126
+ }
179
127
  await tracker.updateComment(comment.id, edited);
180
- ticked += ticks(comment.body, edited);
181
128
  }
182
129
 
183
- if (ticked < met.length) {
130
+ const missed = [
131
+ ...untickable.map(({ number, matching }) =>
132
+ matching === 0
133
+ ? `criterion ${number}, which no unticked line reads as any more`
134
+ : `criterion ${number}, which ${matching} unticked lines read as`,
135
+ ),
136
+ ...unwritten.map((number) => `criterion ${number}, in a comment it cannot edit`),
137
+ ];
138
+ if (missed.length > 0) {
184
139
  log?.(
185
- `#${ticket} ticked ${ticked} of ${met.length} met criteria; ` +
186
- "the rest match no checkbox on the Ticket",
140
+ `#${ticket} ticked ${met.length - missed.length} of ${met.length} met criteria; ` +
141
+ `left unticked: ${missed.join("; ")}`,
187
142
  );
188
143
  }
189
144
  }
190
145
 
191
- /** How many boxes an edit ticked, so a criterion that matched nothing shows up. */
192
- function ticks(before: string, after: string): number {
193
- return countTicked(after) - countTicked(before);
194
- }
195
-
196
- function countTicked(text: string): number {
197
- return [...text.matchAll(TICKED_LINE)].length;
146
+ /** The numbers of the criteria in `met` whose line an edit ticked, which leaves the line count as it was. */
147
+ function ticksIn(before: string, after: string, met: readonly MetCriterion[]): number[] {
148
+ const now = after.split("\n");
149
+ const changed = before
150
+ .split("\n")
151
+ .filter((line, index) => line !== now[index])
152
+ .map((line) => line.trimEnd());
153
+ return met
154
+ .filter((criterion) => changed.includes(criterion.line.trimEnd()))
155
+ .map((criterion) => criterion.number);
198
156
  }
package/src/guards.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { UNCHECKED_BOX } from "./acceptance-criteria.js";
1
+ import { TICKED_BOX, UNCHECKED_BOX } from "./acceptance-criteria.js";
2
2
  import type { Issue } from "./ports/tracker.js";
3
3
 
4
4
  /**
@@ -79,9 +79,24 @@ const CRITERION_LINE = new RegExp(UNCHECKED_BOX, "m");
79
79
 
80
80
  /** Triage posts its brief as a comment, so criteria are not always in the body. */
81
81
  function hasCriteria(issue: Issue): boolean {
82
- return [issue.body, ...issue.comments.map((comment) => comment.body)].some((text) =>
83
- CRITERION_LINE.test(text),
84
- );
82
+ return texts(issue).some((text) => CRITERION_LINE.test(text));
83
+ }
84
+
85
+ /** {@link TICKED_BOX}, over every line of a text, whichever case its `x` is in. */
86
+ const TICKED_LINE = new RegExp(TICKED_BOX, "gmi");
87
+
88
+ /**
89
+ * How many ticked checkboxes the Ticket carries, which is what the
90
+ * `no-criteria` guard says of one that has no unticked box: written with every
91
+ * box already ticked, it reads as having no criteria at all unless told so.
92
+ */
93
+ export function tickedBoxes(issue: Issue): number {
94
+ return texts(issue).reduce((count, text) => count + [...text.matchAll(TICKED_LINE)].length, 0);
95
+ }
96
+
97
+ /** Every place a Ticket writes its criteria: its body, then its comments. */
98
+ function texts(issue: Issue): string[] {
99
+ return [issue.body, ...issue.comments.map((comment) => comment.body)];
85
100
  }
86
101
 
87
102
  /**
@@ -21,8 +21,9 @@
21
21
  * only needs a Ticket by its `next`. `next` alone is optional, because a Stage
22
22
  * that knows neither a fix nor the decision in the way has nothing to put there.
23
23
  *
24
- * This is the list as the verify Stage reads it. The Stages that write code read
25
- * {@link CODE_STAGE_NOTES_LIST_SCHEMA}, the same list with one more sentence.
24
+ * Each Stage reads it with one more sentence in its description, saying where a
25
+ * defect of its own branch goes instead: the Stages that write code read
26
+ * {@link CODE_STAGE_NOTES_LIST_SCHEMA}, and verify reads the verdict's copy.
26
27
  */
27
28
  export const NOTES_LIST_SCHEMA = {
28
29
  type: "array",
@@ -61,17 +62,19 @@ export const NOTES_LIST_SCHEMA = {
61
62
  } as const;
62
63
 
63
64
  /**
64
- * Whose a defect the branch itself introduced is, in the words both the code
65
- * Stages' schema and their prompts use: one declaration, so the two cannot drift.
65
+ * What a defect the branch itself made is, in the words every Stage is told it
66
+ * in: one declaration, so the code Stages and verify cannot drift apart on it.
66
67
  */
67
- export const OWN_DEFECT =
68
- "A defect this branch introduced, one that behaves correctly on the base branch and wrongly here, or one in code this branch added, belongs to this Ticket";
68
+ export const BRANCH_DEFECT =
69
+ "A defect this branch introduced, one that behaves correctly on the base branch and wrongly here, or one in code this branch added";
70
+
71
+ /** Whose such a defect is, in the words the code Stages' schema and prompts use. */
72
+ export const OWN_DEFECT = `${BRANCH_DEFECT}, belongs to this Ticket`;
69
73
 
70
74
  /**
71
75
  * The list as the implement and fix Stages read it: a defect their own branch
72
- * introduced is theirs to fix, not to list. verify keeps the list without it,
73
- * because it fixes nothing and grades the Acceptance Criteria alone, so a
74
- * regression it demonstrates beside them still has only a Note to go in.
76
+ * introduced is theirs to fix, not to list. verify reads the list with a
77
+ * description of its own, which sends such a defect to its verdict instead.
75
78
  */
76
79
  export const CODE_STAGE_NOTES_LIST_SCHEMA = {
77
80
  ...NOTES_LIST_SCHEMA,
package/src/notes.ts CHANGED
@@ -55,6 +55,16 @@ export interface Note extends NoteText {
55
55
  ticket?: number;
56
56
  }
57
57
 
58
+ /**
59
+ * A Note one of this Ticket's code Stages wrote, as the verify Stage behind it
60
+ * is shown it: what it says and which Stage said it, so a defect of the branch
61
+ * among them is graded rather than left to the Note.
62
+ */
63
+ export interface WrittenNote {
64
+ stage: Exclude<NotingStage, "verify">;
65
+ note: Note;
66
+ }
67
+
58
68
  /** A Note that reached GitHub, which is what a Run summary reports. */
59
69
  export interface RoutedNote {
60
70
  /** The Ticket whose Stage made the finding, or whose Release did. */
@@ -97,7 +107,7 @@ const noteSchema = z.object({
97
107
  });
98
108
 
99
109
  /** The parts of a Note beside its summary. */
100
- const NOTE_PARTS = ["evidence", "impact", "next"] as const;
110
+ export const NOTE_PARTS = ["evidence", "impact", "next"] as const;
101
111
 
102
112
  /**
103
113
  * The Notes in a Stage's structured output, and nothing else from it.