rungate 0.8.17 → 0.8.20
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/gates/.gate-salt +1 -1
- package/lib/board-intake-move.ts +280 -0
- package/lib/board-mirror.ts +11 -4
- package/lib/cli-commands.ts +25 -0
- package/lib/criterion-issue-census.ts +62 -0
- package/lib/generators/agents-md.ts +2 -3
- package/lib/issue-closure-audit.ts +96 -0
- package/lib/project-state-shape.ts +18 -0
- package/lib/scaffold/board-intake-workflow.ts +469 -0
- package/lib/scaffold/board-ready-workflow.ts +248 -0
- package/lib/scaffold/human-steps.ts +98 -22
- package/lib/scaffold/owned-files.ts +21 -1
- package/lib/scaffold/steps.ts +27 -1
- package/lib/unaccounted-work.ts +314 -0
- package/package.json +4 -1
- package/scripts/board-id.ts +58 -0
- package/scripts/board-intake-move.ts +80 -0
- package/scripts/unaccounted-work.ts +122 -0
package/gates/.gate-salt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
b387c07fdac25bd795e3bf46bc2a7dbe1b8f1f394d3d14380e9ef253451767f6
|
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The board-intake move step as code (#2193, part 1 of #2183).
|
|
3
|
+
*
|
|
4
|
+
* `board-intake.yml`'s move step carried this logic as about 260 lines of
|
|
5
|
+
* shell, and its invariants were enforced only by regexes over the rendered
|
|
6
|
+
* YAML, so an edit could drop one with no test exercising what runs. Here
|
|
7
|
+
* each one is a branch a stub client drives (`test/board-intake-move.test.ts`):
|
|
8
|
+
*
|
|
9
|
+
* - **Every call is retried** (three tries, waits of 2 s and 4 s), and the
|
|
10
|
+
* third failure is API_FAILED, which says the board's state is UNKNOWN.
|
|
11
|
+
* A thrown error is never read as an answer.
|
|
12
|
+
* - **A null `node(id:)` is an id that did not resolve** (stale, invisible to
|
|
13
|
+
* this token, or a wrong project), refused by naming the id, never read as
|
|
14
|
+
* an empty list.
|
|
15
|
+
* - **A full page is not an absence.** Each connection asks `hasNextPage`, and
|
|
16
|
+
* "not found, and the page was full" is its own UNMEASURED refusal.
|
|
17
|
+
* - **The field and option are resolved by NAME**, so a renamed column is a
|
|
18
|
+
* refusal rather than a stale id writing the wrong column.
|
|
19
|
+
* - **A write is not a reading.** Each write is read back from the item AND
|
|
20
|
+
* from the project's search index, which is what the board draws, and only
|
|
21
|
+
* both agreeing is success. GitHub's built-in "Item added" automation fires
|
|
22
|
+
* on the same event and can land after this write, so there are three
|
|
23
|
+
* verified attempts, then a refusal naming which reading disagreed.
|
|
24
|
+
*
|
|
25
|
+
* It owns only the opened -> In review edge; merged and closed stay with
|
|
26
|
+
* GitHub's built-in workflows, so each transition has one decider.
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
/** A GraphQL call: resolves to the response's `data`, throws on failure, as the client does. */
|
|
30
|
+
export type GraphqlCall = (query: string, variables: Record<string, string>) => Promise<unknown>;
|
|
31
|
+
|
|
32
|
+
export interface MoveDeps {
|
|
33
|
+
graphql: GraphqlCall;
|
|
34
|
+
sleep: (ms: number) => Promise<void>;
|
|
35
|
+
/** Progress lines (one per attempt that did not settle). */
|
|
36
|
+
log: (line: string) => void;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export interface MoveInput {
|
|
40
|
+
projectId: string;
|
|
41
|
+
itemId: string;
|
|
42
|
+
column: string;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export type MoveRefusal =
|
|
46
|
+
| "NO_ITEM"
|
|
47
|
+
| "COLUMN_UNSEARCHABLE"
|
|
48
|
+
| "API_FAILED"
|
|
49
|
+
| "NULL_NODE"
|
|
50
|
+
| "FIELDS_TRUNCATED"
|
|
51
|
+
| "NOT_RESOLVED"
|
|
52
|
+
| "VALUES_TRUNCATED"
|
|
53
|
+
| "INDEX_TRUNCATED"
|
|
54
|
+
| "INDEX_LAGGING"
|
|
55
|
+
| "OVERWRITTEN"
|
|
56
|
+
| "UNEXPECTED";
|
|
57
|
+
|
|
58
|
+
export type MoveResult = { ok: true; attempt: number; message: string } | { ok: false; reason: MoveRefusal; message: string };
|
|
59
|
+
|
|
60
|
+
/** How long to let a concurrent built-in write land before reading back. */
|
|
61
|
+
export const SETTLE_MS = 3000;
|
|
62
|
+
|
|
63
|
+
const FIELDS_QUERY = `query($project: ID!) {
|
|
64
|
+
node(id: $project) {
|
|
65
|
+
... on ProjectV2 {
|
|
66
|
+
fields(first: 50) {
|
|
67
|
+
pageInfo { hasNextPage }
|
|
68
|
+
nodes { ... on ProjectV2SingleSelectField { id name options { id name } } }
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}`;
|
|
73
|
+
|
|
74
|
+
const WRITE_MUTATION = `mutation($project: ID!, $item: ID!, $field: ID!, $option: String!) {
|
|
75
|
+
updateProjectV2ItemFieldValue(input: {
|
|
76
|
+
projectId: $project, itemId: $item, fieldId: $field,
|
|
77
|
+
value: { singleSelectOptionId: $option }
|
|
78
|
+
}) { projectV2Item { id } }
|
|
79
|
+
}`;
|
|
80
|
+
|
|
81
|
+
const VALUES_QUERY = `query($item: ID!) {
|
|
82
|
+
node(id: $item) {
|
|
83
|
+
... on ProjectV2Item {
|
|
84
|
+
fieldValues(first: 50) {
|
|
85
|
+
pageInfo { hasNextPage }
|
|
86
|
+
nodes {
|
|
87
|
+
... on ProjectV2ItemFieldSingleSelectValue {
|
|
88
|
+
name field { ... on ProjectV2FieldCommon { name } }
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}`;
|
|
95
|
+
|
|
96
|
+
const INDEX_QUERY = `query($project: ID!, $q: String!) {
|
|
97
|
+
node(id: $project) {
|
|
98
|
+
... on ProjectV2 {
|
|
99
|
+
items(first: 100, query: $q) {
|
|
100
|
+
pageInfo { hasNextPage }
|
|
101
|
+
nodes { id }
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}`;
|
|
106
|
+
|
|
107
|
+
interface Page<T> {
|
|
108
|
+
pageInfo?: { hasNextPage?: boolean } | null;
|
|
109
|
+
nodes?: Array<T | null> | null;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
class Refused extends Error {
|
|
113
|
+
constructor(
|
|
114
|
+
readonly reason: MoveRefusal,
|
|
115
|
+
message: string,
|
|
116
|
+
) {
|
|
117
|
+
super(message);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** One call, three tries. The third failure refuses; a thrown error is never an answer. */
|
|
122
|
+
async function call(deps: MoveDeps, query: string, variables: Record<string, string>): Promise<unknown> {
|
|
123
|
+
let last: unknown;
|
|
124
|
+
for (let attempt = 1; attempt <= 3; attempt++) {
|
|
125
|
+
try {
|
|
126
|
+
return await deps.graphql(query, variables);
|
|
127
|
+
} catch (e) {
|
|
128
|
+
last = e;
|
|
129
|
+
if (attempt < 3) await deps.sleep(attempt * 2000);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
throw new Refused(
|
|
133
|
+
"API_FAILED",
|
|
134
|
+
`GitHub's GraphQL API failed three times. The item may or may not be on the board and its Status is UNKNOWN — this run measured nothing. Last error: ${(last as Error)?.message ?? String(last)}`,
|
|
135
|
+
);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** Which id a read asked `node(id:)` about, and whether a write had been sent before it. */
|
|
139
|
+
interface ReadSite {
|
|
140
|
+
what: string;
|
|
141
|
+
id: string;
|
|
142
|
+
/** What the id names, and the input it came from, so the refusal blames the right one. */
|
|
143
|
+
names: "the project" | "the item";
|
|
144
|
+
input: "PROJECT_ID" | "ITEM_ID";
|
|
145
|
+
wrote: boolean;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* The connection under `node`, or a refusal naming the id that did not
|
|
150
|
+
* resolve. Every clause of the message is drawn from `site`, never written
|
|
151
|
+
* for one call site, so it is true at all three (review of PR #2194, which
|
|
152
|
+
* found a fixed clause wrong at a different site in rounds 2 and 4).
|
|
153
|
+
*/
|
|
154
|
+
function requireNode<T>(data: unknown, key: "fields" | "fieldValues" | "items", site: ReadSite): Page<T> {
|
|
155
|
+
const node = (data as { node?: Record<string, unknown> | null } | null | undefined)?.node;
|
|
156
|
+
const page = node?.[key] as Page<T> | null | undefined;
|
|
157
|
+
if (!page) {
|
|
158
|
+
throw new Refused(
|
|
159
|
+
"NULL_NODE",
|
|
160
|
+
`${site.what} is UNMEASURED and ${site.wrote ? "a write WAS sent before this read, so the board may already hold the new value" : "nothing was written"}: node(id: ${site.id}) came back null, so ${site.names} did not resolve — the id is stale, names an object this token cannot see, or ${site.input} is wrong. This is NOT a missing field, NOT an unset column and NOT an empty board.`,
|
|
161
|
+
);
|
|
162
|
+
}
|
|
163
|
+
return page;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
const truncated = (page: Page<unknown>) => page.pageInfo?.hasNextPage === true;
|
|
167
|
+
const present = <T>(page: Page<T>): T[] => (page.nodes ?? []).filter((n): n is T => n !== null && n !== undefined);
|
|
168
|
+
|
|
169
|
+
/** Move `itemId` to `column` on `projectId`, verified in both readings, or say why not. */
|
|
170
|
+
export async function moveToColumn(input: MoveInput, deps: MoveDeps): Promise<MoveResult> {
|
|
171
|
+
const { projectId, itemId, column } = input;
|
|
172
|
+
try {
|
|
173
|
+
if (!itemId) {
|
|
174
|
+
throw new Refused(
|
|
175
|
+
"NO_ITEM",
|
|
176
|
+
"The add step produced no itemId, so there is nothing to move. The item was NOT added and its Status is UNSET — this is not a board that merely missed a transition.",
|
|
177
|
+
);
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
// The index is read with `status:"<column>"`, and a double quote cannot be
|
|
181
|
+
// carried inside that phrase, so a column holding one could never be seen
|
|
182
|
+
// in the index and every write would be misreported as lagging or
|
|
183
|
+
// overwritten. Refused before anything is written (review of PR #2194).
|
|
184
|
+
if (/["\\]/.test(column)) {
|
|
185
|
+
throw new Refused(
|
|
186
|
+
"COLUMN_UNSEARCHABLE",
|
|
187
|
+
`The column name ${JSON.stringify(column)} contains a double quote or a backslash, which the project search query status:"<column>" cannot carry, so whether the card renders could never be read. Nothing was written. Rename the column, or pass one without either character.`,
|
|
188
|
+
);
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
const fields = requireNode<{ id?: string; name?: string; options?: Array<{ id: string; name: string }> }>(
|
|
192
|
+
await call(deps, FIELDS_QUERY, { project: projectId }),
|
|
193
|
+
"fields",
|
|
194
|
+
{ what: "the project's field list", id: projectId, names: "the project", input: "PROJECT_ID", wrote: false },
|
|
195
|
+
);
|
|
196
|
+
const status = present(fields).find(f => f.name === "Status");
|
|
197
|
+
const fieldId = status?.id ?? "";
|
|
198
|
+
const optionId = status?.options?.find(o => o.name === column)?.id ?? "";
|
|
199
|
+
if (!fieldId && truncated(fields)) {
|
|
200
|
+
throw new Refused(
|
|
201
|
+
"FIELDS_TRUNCATED",
|
|
202
|
+
"The first 50 fields on this project do not include one named 'Status', AND there are more fields beyond that page — so this read is UNMEASURED, not a missing field. Nothing was written. Do not rename anything on the strength of this message; page the fields query instead.",
|
|
203
|
+
);
|
|
204
|
+
}
|
|
205
|
+
if (!fieldId || !optionId) {
|
|
206
|
+
throw new Refused(
|
|
207
|
+
"NOT_RESOLVED",
|
|
208
|
+
`Could not resolve the Status field or its '${column}' option on this project. ${fieldId ? "The Status field was found and its options are returned in full, so this is not a truncated page" : "The whole field list was read, so this is not a truncated page"}. The item WAS added; only the transition failed. Someone renamed the field or the column — update COLUMN in this workflow to match the board.`,
|
|
209
|
+
);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
let current = "";
|
|
213
|
+
for (let attempt = 1; attempt <= 3; attempt++) {
|
|
214
|
+
await call(deps, WRITE_MUTATION, { project: projectId, item: itemId, field: fieldId, option: optionId });
|
|
215
|
+
// Let a concurrent built-in write land, so the read-back sees the settled value.
|
|
216
|
+
await deps.sleep(SETTLE_MS);
|
|
217
|
+
|
|
218
|
+
const values = requireNode<{ name?: string; field?: { name?: string } }>(
|
|
219
|
+
await call(deps, VALUES_QUERY, { item: itemId }),
|
|
220
|
+
"fieldValues",
|
|
221
|
+
{ what: "the item's field values, read back after the write", id: itemId, names: "the item", input: "ITEM_ID", wrote: true },
|
|
222
|
+
);
|
|
223
|
+
current = present(values).find(v => v.field?.name === "Status")?.name ?? "";
|
|
224
|
+
if (!current && truncated(values)) {
|
|
225
|
+
throw new Refused(
|
|
226
|
+
"VALUES_TRUNCATED",
|
|
227
|
+
"Status was not among this item's first 50 field values and there are more beyond that page, so the read-back is UNMEASURED — the write may well have worked. This is NOT a competing writer and NOT an unset column. Page the fieldValues query.",
|
|
228
|
+
);
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
// The field value is not what the board draws: the board renders from a
|
|
232
|
+
// search index that can disagree with the item data.
|
|
233
|
+
const index = requireNode<{ id?: string }>(
|
|
234
|
+
await call(deps, INDEX_QUERY, { project: projectId, q: `status:"${column}"` }),
|
|
235
|
+
"items",
|
|
236
|
+
{ what: `the search index for the '${column}' column`, id: projectId, names: "the project", input: "PROJECT_ID", wrote: true },
|
|
237
|
+
);
|
|
238
|
+
const indexed = present(index).some(n => n.id === itemId);
|
|
239
|
+
if (!indexed && truncated(index)) {
|
|
240
|
+
throw new Refused(
|
|
241
|
+
"INDEX_TRUNCATED",
|
|
242
|
+
`More than 100 items match '${column}' in the project's search index and this item was not in the first page, so its membership is UNMEASURED — it may well be indexed and rendering. Do not read this as a missing card. Page the index query.`,
|
|
243
|
+
);
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
if (current === column && indexed) {
|
|
247
|
+
return {
|
|
248
|
+
ok: true,
|
|
249
|
+
attempt,
|
|
250
|
+
message: `Moved to '${column}' on attempt ${attempt}, confirmed in BOTH the item's field value and the project's search index — so the card will actually render. This workflow owns only the opened->In review edge; merged->Done and closed->Done remain GitHub's built-in project workflows, so exactly one decider writes each transition.`,
|
|
251
|
+
};
|
|
252
|
+
}
|
|
253
|
+
deps.log(
|
|
254
|
+
current === column
|
|
255
|
+
? `Attempt ${attempt}: the field value reads '${column}' but the search index does not carry this item yet, so the board would not draw it. Re-writing to prompt a re-index.`
|
|
256
|
+
: `Attempt ${attempt}: wrote '${column}', read back '${current || "(nothing)"}' — a concurrent write won. Retrying.`,
|
|
257
|
+
);
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
if (current === column) {
|
|
261
|
+
throw new Refused(
|
|
262
|
+
"INDEX_LAGGING",
|
|
263
|
+
`The Status field reads '${column}' but after three attempts the project's SEARCH INDEX still does not list this item under it, and the board draws from the index. The data is right and the card is invisible — do not 'fix' the Status, it is already correct. Re-writing the same value is what repairs the index entry; if three did not take, the index is lagging and this needs a human to re-check later.`,
|
|
264
|
+
);
|
|
265
|
+
}
|
|
266
|
+
throw new Refused(
|
|
267
|
+
"OVERWRITTEN",
|
|
268
|
+
`Wrote '${column}' three times and the board still reads '${current || "(nothing)"}'. Something else is writing this item's Status and winning: check the project's built-in workflows for a rule that also fires on a pull request being added. The item IS on the board; only its column is wrong.`,
|
|
269
|
+
);
|
|
270
|
+
} catch (e) {
|
|
271
|
+
if (e instanceof Refused) return { ok: false, reason: e.reason, message: e.message };
|
|
272
|
+
// Anything else is a response this module did not expect, or a fault in it:
|
|
273
|
+
// named, never a stack trace and never an answer (review of PR #2194).
|
|
274
|
+
return {
|
|
275
|
+
ok: false,
|
|
276
|
+
reason: "UNEXPECTED",
|
|
277
|
+
message: `An unexpected response or fault stopped the move, so the item's Status is UNKNOWN — a write may or may not have been sent. ${(e as Error)?.message ?? String(e)}`,
|
|
278
|
+
};
|
|
279
|
+
}
|
|
280
|
+
}
|
package/lib/board-mirror.ts
CHANGED
|
@@ -389,10 +389,17 @@ export function criteriaNamedBy(
|
|
|
389
389
|
issue: { readonly title: string; readonly body?: string | null },
|
|
390
390
|
criterionIds: readonly string[],
|
|
391
391
|
): string[] {
|
|
392
|
-
const
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
392
|
+
const lines = `${issue.title}\n${issue.body ?? ""}`.split("\n");
|
|
393
|
+
// Scored per mention, not per text (#1683): one checkbox stating an id must
|
|
394
|
+
// not suppress a mention elsewhere that serves it. A declaring checkbox
|
|
395
|
+
// accounts for the one mention it opens with and no other, so a second
|
|
396
|
+
// mention on the same line still counts (review of PR #2190). The id is
|
|
397
|
+
// named when ANY mention is not the one a checkbox states.
|
|
398
|
+
return criterionIds.filter(id => {
|
|
399
|
+
const one = oneScMentionPattern(id);
|
|
400
|
+
const every = new RegExp(one.source, one.flags.includes("g") ? one.flags : `${one.flags}g`);
|
|
401
|
+
return lines.some(line => (line.match(every)?.length ?? 0) > (declaresOwnCriterion(line, id) ? 1 : 0));
|
|
402
|
+
});
|
|
396
403
|
}
|
|
397
404
|
|
|
398
405
|
/**
|
package/lib/cli-commands.ts
CHANGED
|
@@ -274,6 +274,31 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
|
|
|
274
274
|
"[--top-up] [--moving-issue <n>] [--actor <login>] [--write] (at least one of --closed-issue, --top-up; " +
|
|
275
275
|
"--project defaults to board.id in the rungate config)",
|
|
276
276
|
},
|
|
277
|
+
// #2173. For a generated workflow that works in shell (`board-intake.yml`,
|
|
278
|
+
// #2166) and so cannot read the config through the loader itself. No
|
|
279
|
+
// `projectRootFlag`: it reads `process.cwd()`, which the child inherits.
|
|
280
|
+
"board-id": {
|
|
281
|
+
script: "scripts/board-id.ts",
|
|
282
|
+
summary: "Print the board's node id from config",
|
|
283
|
+
usage: "rungate board-id [--project-root <dir>] (UNMEASURED and exit 2 when the config names no board)",
|
|
284
|
+
},
|
|
285
|
+
// #2193 (part 1 of #2183): the board-intake move step as a tested command.
|
|
286
|
+
// `board-intake.yml` switches to it in #2183, once a release carries it.
|
|
287
|
+
"board-intake-move": {
|
|
288
|
+
script: "scripts/board-intake-move.ts",
|
|
289
|
+
summary: "Move a board item to a column, verified in the item and in the board's search index",
|
|
290
|
+
usage: "rungate board-intake-move --project <node-id> --item <item-id> --column <name> (exit 1 naming the cause on every refusal)",
|
|
291
|
+
},
|
|
292
|
+
// #2100. The prose half of declared work: `board-conformance`'s
|
|
293
|
+
// `declared-work` reading covers criteria and stage items. No
|
|
294
|
+
// `projectRootFlag`: it reads `process.cwd()`, which the child inherits.
|
|
295
|
+
"unaccounted-work": {
|
|
296
|
+
script: "scripts/unaccounted-work.ts",
|
|
297
|
+
summary: "Report undone work declared in a repository's prose that no open issue covers",
|
|
298
|
+
usage:
|
|
299
|
+
"rungate unaccounted-work [--project-root <dir>] [--repo <owner/name>] [--issues-fixture <file.json>] [--json] " +
|
|
300
|
+
"(exit 1 when work is unaccounted, 2 when a source could not be read)",
|
|
301
|
+
},
|
|
277
302
|
// Reads a `gh pr view`-shaped payload on stdin, which the dispatcher passes
|
|
278
303
|
// through (`stdio: "inherit"`), or `--fixture` offline.
|
|
279
304
|
"audit-closing-references": {
|
|
@@ -233,6 +233,67 @@ export function assertOneJudgementPerPair(adjudications: readonly Adjudication[]
|
|
|
233
233
|
}
|
|
234
234
|
}
|
|
235
235
|
|
|
236
|
+
/**
|
|
237
|
+
* Refuse a record naming a criterion no spec states (#1643).
|
|
238
|
+
*
|
|
239
|
+
* The lookup in {@link censusRows} is a strict `===`, so a typo (`SC-9110`
|
|
240
|
+
* for `SC-9101`) matches nothing and the row reads UNADJUDICATED while a
|
|
241
|
+
* judgement sits in the file. Shape and duplicates are checked per record and
|
|
242
|
+
* per store; this needs the spec set, so it runs where the specs are in hand.
|
|
243
|
+
* It asks whether a criterion EXISTS, not whether it is ticked: a judgement
|
|
244
|
+
* survives an untick and still applies when the tick returns.
|
|
245
|
+
*
|
|
246
|
+
* The ISSUE half is {@link orphanedAdjudications}, and it reports rather than
|
|
247
|
+
* refuses: the census reads open issues only, so a judged issue closing is the
|
|
248
|
+
* ordinary lifecycle, and a refusal there would stop the whole census on it
|
|
249
|
+
* (review of PR #2192).
|
|
250
|
+
*/
|
|
251
|
+
export function assertAdjudicationsResolve(adjudications: readonly Adjudication[], specs: readonly SpecRef[]): void {
|
|
252
|
+
const stated = new Set<string>();
|
|
253
|
+
for (const spec of specs) {
|
|
254
|
+
if (isTemplateSpec(spec.file)) continue;
|
|
255
|
+
for (const c of parseCriteria(spec.content)) stated.add(c.id);
|
|
256
|
+
}
|
|
257
|
+
const problems = adjudications.flatMap((a, at) =>
|
|
258
|
+
stated.has(a.criterion) ? [] : [`adjudication record ${at} names ${a.criterion}, which no spec states`],
|
|
259
|
+
);
|
|
260
|
+
if (problems.length > 0) {
|
|
261
|
+
throw new Error(
|
|
262
|
+
`${problems.join("; ")}. A judgement on a criterion that does not exist is never applied, so it would read ` +
|
|
263
|
+
`as nobody having judged. Fix the record.`,
|
|
264
|
+
);
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/** A judgement whose issue is not among the issues the census read. */
|
|
269
|
+
export interface OrphanedAdjudication {
|
|
270
|
+
at: number;
|
|
271
|
+
record: Adjudication;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/**
|
|
275
|
+
* The judgements naming an issue not among `issues` (#1643): closed since, or
|
|
276
|
+
* mistyped. Each applies to no row, so the census still runs, and each is
|
|
277
|
+
* printed beside the rows so a mistyped number sits next to the UNADJUDICATED
|
|
278
|
+
* row it was meant for instead of vanishing.
|
|
279
|
+
*/
|
|
280
|
+
export function orphanedAdjudications(
|
|
281
|
+
adjudications: readonly Adjudication[],
|
|
282
|
+
issues: readonly IssueRef[],
|
|
283
|
+
): OrphanedAdjudication[] {
|
|
284
|
+
const fetched = new Set(issues.map(i => i.number));
|
|
285
|
+
return adjudications.flatMap((record, at) => (fetched.has(record.issue) ? [] : [{ at, record }]));
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/** One line per orphaned judgement, saying why it applies to nothing. */
|
|
289
|
+
export function renderOrphaned(orphans: readonly OrphanedAdjudication[]): string[] {
|
|
290
|
+
return orphans.map(
|
|
291
|
+
({ at, record }) =>
|
|
292
|
+
`ORPHANED: adjudication record ${at} (${record.criterion}, #${record.issue}) names an issue that is not ` +
|
|
293
|
+
`open: closed since, or mistyped. It applies to no row; fix its number, or remove it if the issue closed.`,
|
|
294
|
+
);
|
|
295
|
+
}
|
|
296
|
+
|
|
236
297
|
/** Does this issue name this criterion, on a word boundary? */
|
|
237
298
|
export function issueNames(issue: IssueRef, id: string): boolean {
|
|
238
299
|
const pattern = oneScMentionPattern(id);
|
|
@@ -254,6 +315,7 @@ export function censusRows(
|
|
|
254
315
|
adjudications: readonly Adjudication[],
|
|
255
316
|
): CensusRow[] {
|
|
256
317
|
assertOneJudgementPerPair(adjudications);
|
|
318
|
+
assertAdjudicationsResolve(adjudications, specs);
|
|
257
319
|
const rows: CensusRow[] = [];
|
|
258
320
|
|
|
259
321
|
for (const spec of specs) {
|
|
@@ -435,9 +435,8 @@ description: Every command the rungate CLI exposes in this project, generated fr
|
|
|
435
435
|
|
|
436
436
|
## Command Routing
|
|
437
437
|
|
|
438
|
-
Generated from the CLI's
|
|
439
|
-
|
|
440
|
-
\`${cliPrefix} --help\` prints each command's own arguments.
|
|
438
|
+
Generated from the CLI's command registry. Run one as
|
|
439
|
+
\`${cliPrefix} <command>\`; \`--help\` prints its arguments.
|
|
441
440
|
|
|
442
441
|
${commandRoutingTable()}
|
|
443
442
|
`,
|
|
@@ -370,3 +370,99 @@ export function report(findings: ClosureFinding[], scanned: number): string {
|
|
|
370
370
|
blocks.join("\n\n")
|
|
371
371
|
);
|
|
372
372
|
}
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* A merged pull request and the issues GitHub says it closes (#1952).
|
|
376
|
+
*
|
|
377
|
+
* `closes` is `null` when the node carried no `closingIssuesReferences` at
|
|
378
|
+
* all: a field nobody selected and a pull request that closes nothing are
|
|
379
|
+
* different readings, and only the second is clean.
|
|
380
|
+
*/
|
|
381
|
+
export interface MergedCloser {
|
|
382
|
+
pull: number;
|
|
383
|
+
closes: { number: number; state: string }[] | null;
|
|
384
|
+
/** GitHub's own count, so a cut-short list is visible as one. */
|
|
385
|
+
closesTotal: number;
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
/**
|
|
389
|
+
* One merged pull request's GraphQL node, as the audit reads it.
|
|
390
|
+
*
|
|
391
|
+
* `repo` (`owner/name`) drops a closing reference into ANOTHER repository:
|
|
392
|
+
* GitHub resolves `Fixes other/repo#42` across repositories, and that issue
|
|
393
|
+
* is not this tracker's #42 (review of #2181; board-flow and work-status
|
|
394
|
+
* filter the same way). A node with no `repository` is kept, so a fixture
|
|
395
|
+
* written without it still reads.
|
|
396
|
+
*/
|
|
397
|
+
export function toMergedCloser(node: any, repo?: string): MergedCloser {
|
|
398
|
+
const refs = node?.closingIssuesReferences;
|
|
399
|
+
if (!refs || !Array.isArray(refs.nodes)) return { pull: Number(node?.number), closes: null, closesTotal: 0 };
|
|
400
|
+
const here = (n: any): boolean => {
|
|
401
|
+
const r = n?.repository;
|
|
402
|
+
if (!repo || !r) return true;
|
|
403
|
+
return `${r.owner?.login}/${r.name}`.toLowerCase() === repo.toLowerCase();
|
|
404
|
+
};
|
|
405
|
+
const all = refs.nodes as any[];
|
|
406
|
+
const kept = all.filter(here);
|
|
407
|
+
return {
|
|
408
|
+
pull: Number(node.number),
|
|
409
|
+
closes: kept.map((n: any) => ({ number: Number(n?.number), state: String(n?.state ?? "") })),
|
|
410
|
+
// The cut is judged on GitHub's count against what was RETURNED, before the
|
|
411
|
+
// cross-repo filter, so a filtered reference never reads as a truncation.
|
|
412
|
+
closesTotal: Number(refs.totalCount ?? all.length) - (all.length - kept.length),
|
|
413
|
+
};
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
export interface OpenCloserReading {
|
|
417
|
+
/** Each issue still OPEN while a merged pull request names it as closed. */
|
|
418
|
+
open: { pull: number; issue: number }[];
|
|
419
|
+
/** Pull requests whose closing list could not be read whole. */
|
|
420
|
+
unmeasured: number[];
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
/**
|
|
424
|
+
* SC-2751: every issue still OPEN that a merged pull request's closing
|
|
425
|
+
* reference names, paired with that pull request.
|
|
426
|
+
*
|
|
427
|
+
* #1937 merged with `closingIssuesReferences` resolving to #1948 before and
|
|
428
|
+
* after the merge, and #1948 stayed OPEN. The close GitHub was meant to make
|
|
429
|
+
* did not happen, and the rules forbid making it by hand (#925), so the only
|
|
430
|
+
* correct response is to report it: the tracker otherwise says shipped work
|
|
431
|
+
* is outstanding. A list GitHub cut short, or a node with no list, is
|
|
432
|
+
* UNMEASURED rather than clean — the missing reference may be the open one.
|
|
433
|
+
*/
|
|
434
|
+
export function openWithMergedCloser(pulls: readonly MergedCloser[]): OpenCloserReading {
|
|
435
|
+
const open: OpenCloserReading["open"] = [];
|
|
436
|
+
const unmeasured: number[] = [];
|
|
437
|
+
for (const p of pulls) {
|
|
438
|
+
if (p.closes === null || p.closesTotal > p.closes.length) unmeasured.push(p.pull);
|
|
439
|
+
for (const issue of p.closes ?? []) {
|
|
440
|
+
if (issue.state === "OPEN") open.push({ pull: p.pull, issue: issue.number });
|
|
441
|
+
}
|
|
442
|
+
}
|
|
443
|
+
return { open, unmeasured };
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
/** The reading as text, naming both numbers in every finding. Empty says so. */
|
|
447
|
+
export function openCloserReport(reading: OpenCloserReading, scanned: number): string {
|
|
448
|
+
const lines = [`Merged-closer audit: ${scanned} merged pull requests scanned.`];
|
|
449
|
+
if (reading.open.length === 0 && reading.unmeasured.length === 0) {
|
|
450
|
+
lines.push("none: every issue a merged pull request closes is closed.");
|
|
451
|
+
}
|
|
452
|
+
for (const f of reading.open) lines.push(`- #${f.issue} is OPEN, but #${f.pull} merged closing it`);
|
|
453
|
+
for (const n of reading.unmeasured) {
|
|
454
|
+
lines.push(`- UNMEASURED: #${n}'s closing references could not be read whole, so an open one may be missing`);
|
|
455
|
+
}
|
|
456
|
+
return lines.join("\n");
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
/**
|
|
460
|
+
* The merged pull requests a GraphQL response carries, or `null` when it
|
|
461
|
+
* carries no list at all. A response with no `repository`, or no
|
|
462
|
+
* `pullRequests`, is no reading, not an empty one (review of #2181): read as
|
|
463
|
+
* `[]` it would print "none" in exactly the no-data case.
|
|
464
|
+
*/
|
|
465
|
+
export function mergedPullNodes(data: any): unknown[] | null {
|
|
466
|
+
const nodes = data?.repository?.pullRequests?.nodes;
|
|
467
|
+
return Array.isArray(nodes) ? nodes : null;
|
|
468
|
+
}
|
|
@@ -304,3 +304,21 @@ export function selectRecentSessions<T extends { date: string }>(
|
|
|
304
304
|
);
|
|
305
305
|
return { rendered: ranked.slice(0, limit).map(d => d.s), undated };
|
|
306
306
|
}
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* How many priorities `PROJECT-STATE.md` renders (#1946). The renderer emitted
|
|
310
|
+
* one line per priority under SC-300's 200-line cap, so the next writer to
|
|
311
|
+
* record a priority had to delete one to push, under pressure and with no rule
|
|
312
|
+
* about what was safe to delete. Now the document shows the first ones in the
|
|
313
|
+
* order `project-state.json` lists them and says how many more the json holds,
|
|
314
|
+
* so recording state no longer grows the document that reports it.
|
|
315
|
+
*/
|
|
316
|
+
export const RENDERED_PRIORITIES_MAX = 12;
|
|
317
|
+
|
|
318
|
+
/** The priorities to render, and how many were left in the json. Pure. */
|
|
319
|
+
export function boundedPriorities(
|
|
320
|
+
priorities: readonly string[],
|
|
321
|
+
max: number = RENDERED_PRIORITIES_MAX,
|
|
322
|
+
): { shown: string[]; omitted: number } {
|
|
323
|
+
return { shown: priorities.slice(0, max), omitted: Math.max(0, priorities.length - max) };
|
|
324
|
+
}
|