rungate 0.8.26 → 0.8.28
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/bin/rungate.ts +5 -1
- package/gates/.gate-salt +1 -1
- package/lib/ai-review-threads.ts +152 -9
- package/lib/blocked-by-write.ts +95 -0
- package/lib/board-mirror.ts +28 -9
- package/lib/cli-commands.ts +40 -4
- package/lib/config-trackable.ts +91 -6
- package/lib/consumer-triage.ts +214 -0
- package/lib/issue-filing-gate.ts +84 -23
- package/lib/live-issues.ts +5 -0
- package/lib/scaffold/adr-accepted-workflow.ts +5 -6
- package/lib/scaffold/board-project-step.ts +49 -0
- package/lib/scaffold/human-steps.ts +39 -3
- package/lib/scaffold/owned-files.ts +14 -4
- package/lib/scaffold/spec-scope.ts +215 -0
- package/lib/scaffold/specs-placed-workflow.ts +249 -0
- package/lib/scaffold/steps.ts +14 -1
- package/lib/scaffold/write-steps.ts +9 -1
- package/lib/spec-placement.ts +89 -0
- package/lib/success-doc.ts +1 -1
- package/package.json +4 -1
- package/scripts/ai-review-threads.ts +42 -8
- package/scripts/board-conformance.ts +142 -8
- package/scripts/board-scope.ts +149 -0
- package/scripts/board-snapshot.ts +121 -5
- package/scripts/consumer-triage.ts +235 -0
- package/scripts/plan-deps.ts +58 -8
- package/scripts/plan-issues.ts +9 -3
- package/scripts/status-view.ts +955 -0
- package/scripts/sync-sc-status.ts +64 -4
package/bin/rungate.ts
CHANGED
|
@@ -74,7 +74,11 @@ if (!existsSync(script)) {
|
|
|
74
74
|
// Only added when the caller did not say otherwise, and only for commands
|
|
75
75
|
// that accept the flag — a script that does not would read it as a
|
|
76
76
|
// positional argument.
|
|
77
|
-
|
|
77
|
+
// Either spelling counts as the caller saying so: `--project-root=<dir>` read
|
|
78
|
+
// as absent appended the cwd AFTER it, and a last-one-wins reader then took
|
|
79
|
+
// the cwd over the directory the caller named (review of #2365).
|
|
80
|
+
const givesRoot = rest.some(a => a === "--project-root" || a.startsWith("--project-root="));
|
|
81
|
+
const needsRoot = command.projectRootFlag && !givesRoot;
|
|
78
82
|
const args = needsRoot ? [...rest, "--project-root", process.cwd()] : rest;
|
|
79
83
|
|
|
80
84
|
// Run the script as an ENTRY MODULE, so `import.meta.main` is true inside it
|
package/gates/.gate-salt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
545e0acc9e8aaebb75f5345bedfc501cbc22cbbef652611467898dcd4736a772
|
package/lib/ai-review-threads.ts
CHANGED
|
@@ -167,10 +167,59 @@ export type AiReviewThreadOutcome =
|
|
|
167
167
|
| "BLOCKED_BY_PENDING_REVIEW"
|
|
168
168
|
| "FAILED";
|
|
169
169
|
|
|
170
|
-
/**
|
|
170
|
+
/**
|
|
171
|
+
* One entry of a refusal's structured `errors[]` (#2363). GitHub sends objects
|
|
172
|
+
* naming a `field` and a `code`, or bare strings, which arrive here as
|
|
173
|
+
* `{ message }`.
|
|
174
|
+
*/
|
|
175
|
+
export interface AiReviewApiError {
|
|
176
|
+
field?: string;
|
|
177
|
+
code?: string;
|
|
178
|
+
message?: string;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* What the API said. `status` is `null` for a failure that never got one.
|
|
183
|
+
* `errors` is the structured body when the refusal carried one; absent, the
|
|
184
|
+
* classifiers fall back to the message text.
|
|
185
|
+
*/
|
|
171
186
|
export type AiReviewThreadResponse =
|
|
172
187
|
| { ok: true }
|
|
173
|
-
| { ok: false; status: number | null; message: string };
|
|
188
|
+
| { ok: false; status: number | null; message: string; errors?: AiReviewApiError[] };
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* A thrown Octokit error as a refusal, keeping `response.data.errors` (#2363).
|
|
192
|
+
* The status and message alone threw away the one part GitHub states as data,
|
|
193
|
+
* which left every classifier matching serialized text.
|
|
194
|
+
*/
|
|
195
|
+
export function refusalFrom(e: unknown): Extract<AiReviewThreadResponse, { ok: false }> {
|
|
196
|
+
const err = e as { status?: unknown; message?: unknown; response?: { data?: { errors?: unknown } } };
|
|
197
|
+
const status = typeof err.status === "number" ? err.status : null;
|
|
198
|
+
const message = typeof err.message === "string" ? err.message : String(e);
|
|
199
|
+
const raw = err.response?.data?.errors;
|
|
200
|
+
if (!Array.isArray(raw)) return { ok: false, status, message };
|
|
201
|
+
const errors: AiReviewApiError[] = raw.map(x => {
|
|
202
|
+
if (typeof x === "string") return { message: x };
|
|
203
|
+
const o = (x ?? {}) as Record<string, unknown>;
|
|
204
|
+
return {
|
|
205
|
+
...(typeof o.field === "string" ? { field: o.field } : {}),
|
|
206
|
+
...(typeof o.code === "string" ? { code: o.code } : {}),
|
|
207
|
+
...(typeof o.message === "string" ? { message: o.message } : {}),
|
|
208
|
+
};
|
|
209
|
+
});
|
|
210
|
+
return { ok: false, status, message, errors };
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* The pull-request-level fallback (#2338): a finding GitHub refuses at the line
|
|
215
|
+
* AND at the file goes here instead of being lost. `existing` is every body
|
|
216
|
+
* already on the pull request's conversation, so a later round does not post
|
|
217
|
+
* the same finding again.
|
|
218
|
+
*/
|
|
219
|
+
export interface AiReviewPullCommenter {
|
|
220
|
+
post: (body: string) => Promise<AiReviewThreadResponse>;
|
|
221
|
+
existing: readonly string[];
|
|
222
|
+
}
|
|
174
223
|
|
|
175
224
|
/** Sends one comment. The only thing in this module that touches a network. */
|
|
176
225
|
export type AiReviewThreadPoster = (
|
|
@@ -185,6 +234,8 @@ export interface AiReviewThreadsResult {
|
|
|
185
234
|
posted: number;
|
|
186
235
|
/** Of those, how many only succeeded after dropping to file level. */
|
|
187
236
|
demoted: number;
|
|
237
|
+
/** Of those, how many went on the conversation because GitHub refused the file too (#2338). */
|
|
238
|
+
pullComments: number;
|
|
188
239
|
/** One sentence per thing worth reading, in the order it happened. */
|
|
189
240
|
detail: string[];
|
|
190
241
|
}
|
|
@@ -209,6 +260,41 @@ const FORBIDDEN = 403;
|
|
|
209
260
|
*/
|
|
210
261
|
const PENDING_REVIEW_CONDITION = /pending review/i;
|
|
211
262
|
|
|
263
|
+
/**
|
|
264
|
+
* The 422 that means "this path is not in the pull request's diff" — GitHub
|
|
265
|
+
* names the FIELD, either as `pull_request_review_thread.path` (the #1740
|
|
266
|
+
* reading: `… .path "could not be resolved"`) or as `"field":"path"` in its
|
|
267
|
+
* errors array. The bare word "path" anywhere in a message is not that
|
|
268
|
+
* (review of #2358): any other 422, a stale `commit_id` among them, is a
|
|
269
|
+
* request this producer got wrong and stays a failure rather than moving to
|
|
270
|
+
* the conversation.
|
|
271
|
+
*/
|
|
272
|
+
const OFF_DIFF_CONDITION = /pull_request_review_thread\.path\b|"field"\s*:\s*"path"/;
|
|
273
|
+
|
|
274
|
+
/** The fields a refusal's structured body names, or `null` when it names none. */
|
|
275
|
+
function fieldsNamed(answer: Extract<AiReviewThreadResponse, { ok: false }>): string[] | null {
|
|
276
|
+
const fields = (answer.errors ?? []).flatMap(e => (e.field === undefined ? [] : [e.field]));
|
|
277
|
+
return fields.length === 0 ? null : fields;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/** Every piece of text a refusal carries: its message and each error's message. */
|
|
281
|
+
function refusalText(answer: Extract<AiReviewThreadResponse, { ok: false }>): string {
|
|
282
|
+
return [answer.message, ...(answer.errors ?? []).flatMap(e => (e.message === undefined ? [] : [e.message]))].join("\n");
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/**
|
|
286
|
+
* The off-diff 422 (#2338), decided from `errors[].field` when GitHub named
|
|
287
|
+
* one (#2363): `path`, or a dotted name ending in `.path`, is off-diff and
|
|
288
|
+
* any other field is not, whatever the message says. With no field named, the
|
|
289
|
+
* text decides — the message and each error's own message — through {@link OFF_DIFF_CONDITION}.
|
|
290
|
+
*/
|
|
291
|
+
function isOffDiffRefusal(answer: AiReviewThreadResponse): boolean {
|
|
292
|
+
if (answer.ok || answer.status !== UNPROCESSABLE) return false;
|
|
293
|
+
const fields = fieldsNamed(answer);
|
|
294
|
+
if (fields !== null) return fields.some(f => f === "path" || f.endsWith(".path"));
|
|
295
|
+
return OFF_DIFF_CONDITION.test(refusalText(answer));
|
|
296
|
+
}
|
|
297
|
+
|
|
212
298
|
/**
|
|
213
299
|
* One binding, so a mutation of it is observable. Both halves are required:
|
|
214
300
|
* the status narrows it to a validation refusal, the condition says WHICH —
|
|
@@ -217,7 +303,7 @@ const PENDING_REVIEW_CONDITION = /pending review/i;
|
|
|
217
303
|
*/
|
|
218
304
|
function isPendingReviewRefusal(answer: AiReviewThreadResponse): boolean {
|
|
219
305
|
return (
|
|
220
|
-
!answer.ok && answer.status === UNPROCESSABLE && PENDING_REVIEW_CONDITION.test(answer
|
|
306
|
+
!answer.ok && answer.status === UNPROCESSABLE && PENDING_REVIEW_CONDITION.test(refusalText(answer))
|
|
221
307
|
);
|
|
222
308
|
}
|
|
223
309
|
|
|
@@ -255,6 +341,7 @@ export async function postReviewThreads(
|
|
|
255
341
|
post: AiReviewThreadPoster,
|
|
256
342
|
keyFor?: (finding: Record<string, unknown>) => string | null,
|
|
257
343
|
fork?: boolean | null,
|
|
344
|
+
comment?: AiReviewPullCommenter,
|
|
258
345
|
): Promise<AiReviewThreadsResult> {
|
|
259
346
|
const detail: string[] = [];
|
|
260
347
|
|
|
@@ -262,17 +349,21 @@ export async function postReviewThreads(
|
|
|
262
349
|
detail.push(
|
|
263
350
|
"the review produced no usable reading, so there was nothing to post — this is not a review that found nothing",
|
|
264
351
|
);
|
|
265
|
-
return { outcome: "UNMEASURED", attempted: 0, posted: 0, demoted: 0, detail };
|
|
352
|
+
return { outcome: "UNMEASURED", attempted: 0, posted: 0, demoted: 0, pullComments: 0, detail };
|
|
266
353
|
}
|
|
267
354
|
|
|
268
355
|
const requests = reviewThreadRequests(reading, keyFor);
|
|
269
356
|
if (requests.length === 0) {
|
|
270
357
|
detail.push("the reading located no finding that could be anchored to a path in this diff");
|
|
271
|
-
return { outcome: "NOTHING_TO_POST", attempted: 0, posted: 0, demoted: 0, detail };
|
|
358
|
+
return { outcome: "NOTHING_TO_POST", attempted: 0, posted: 0, demoted: 0, pullComments: 0, detail };
|
|
272
359
|
}
|
|
273
360
|
|
|
274
361
|
let posted = 0;
|
|
275
362
|
let demoted = 0;
|
|
363
|
+
let pullComments = 0;
|
|
364
|
+
const alreadyOnConversation = new Set((comment?.existing ?? []).map(threadKeyFrom).filter((k): k is string => k !== null));
|
|
365
|
+
/** Keys this call put on the conversation, so a repeat can say WHEN (review of #2358). */
|
|
366
|
+
const postedThisRound = new Set<string>();
|
|
276
367
|
let forbidden = 0;
|
|
277
368
|
let pending = 0;
|
|
278
369
|
let failed = 0;
|
|
@@ -302,6 +393,56 @@ export async function postReviewThreads(
|
|
|
302
393
|
if (answer.ok) demoted += 1;
|
|
303
394
|
}
|
|
304
395
|
|
|
396
|
+
// #2338: refused at the file too. The path is not in this pull request's
|
|
397
|
+
// diff as GitHub sees it (a branch behind its base is the measured cause),
|
|
398
|
+
// so the finding goes on the conversation rather than nowhere.
|
|
399
|
+
if (
|
|
400
|
+
!answer.ok &&
|
|
401
|
+
answer.status === UNPROCESSABLE &&
|
|
402
|
+
comment !== undefined &&
|
|
403
|
+
!isPendingReviewRefusal(answer) &&
|
|
404
|
+
isOffDiffRefusal(answer)
|
|
405
|
+
) {
|
|
406
|
+
const key = threadKeyFrom(request.body);
|
|
407
|
+
if (key !== null && alreadyOnConversation.has(key)) {
|
|
408
|
+
posted += 1;
|
|
409
|
+
pullComments += 1;
|
|
410
|
+
const when = postedThisRound.has(key) ? "earlier in this round" : "from an earlier round";
|
|
411
|
+
detail.push(`${where}: not in this pull request's diff, and already on its conversation ${when}, so not posted again`);
|
|
412
|
+
continue;
|
|
413
|
+
}
|
|
414
|
+
const viaConversation = await comment.post(
|
|
415
|
+
`**\`${where}\` is not in this pull request's diff, so this finding could not go on it.** ` +
|
|
416
|
+
`GitHub refused it ${request.line === null ? "at the file" : "at the line and at the file"}. ` +
|
|
417
|
+
`The branch may be behind its base; rebasing usually puts the file back in the diff.\n\n` +
|
|
418
|
+
request.body,
|
|
419
|
+
);
|
|
420
|
+
if (viaConversation.ok) {
|
|
421
|
+
// Within the round too: a second finding with this key is the same finding (review of #2358).
|
|
422
|
+
if (key !== null) {
|
|
423
|
+
alreadyOnConversation.add(key);
|
|
424
|
+
postedThisRound.add(key);
|
|
425
|
+
}
|
|
426
|
+
posted += 1;
|
|
427
|
+
pullComments += 1;
|
|
428
|
+
detail.push(`${where}: not in this pull request's diff (422 ${request.line === null ? "at the file" : "at the line and at the file"}), so it was posted on the conversation instead`);
|
|
429
|
+
continue;
|
|
430
|
+
}
|
|
431
|
+
// A 403 here is the token, not the finding: the fork branch below
|
|
432
|
+
// decides it exactly as it decides a refused review comment (review of
|
|
433
|
+
// #2358 — a fork's read-only token must degrade, never fail).
|
|
434
|
+
if (!viaConversation.ok && viaConversation.status === FORBIDDEN) {
|
|
435
|
+
answer = viaConversation;
|
|
436
|
+
} else {
|
|
437
|
+
failed += 1;
|
|
438
|
+
detail.push(
|
|
439
|
+
`${where}: not in this pull request's diff (422 ${request.line === null ? "at the file" : "at the line and at the file"}), and the conversation comment was refused too: ` +
|
|
440
|
+
`${viaConversation.status ?? "no status"} — ${viaConversation.message}`,
|
|
441
|
+
);
|
|
442
|
+
continue;
|
|
443
|
+
}
|
|
444
|
+
}
|
|
445
|
+
|
|
305
446
|
if (answer.ok) {
|
|
306
447
|
posted += 1;
|
|
307
448
|
continue;
|
|
@@ -336,10 +477,10 @@ export async function postReviewThreads(
|
|
|
336
477
|
// -review lock, and all three outrank a partial success — a round that
|
|
337
478
|
// posted three of four comments has lost a finding and must say so.
|
|
338
479
|
if (failed > 0) {
|
|
339
|
-
return { outcome: "FAILED", attempted: requests.length, posted, demoted, detail };
|
|
480
|
+
return { outcome: "FAILED", attempted: requests.length, posted, demoted, pullComments, detail };
|
|
340
481
|
}
|
|
341
482
|
if (forbidden > 0) {
|
|
342
|
-
return { outcome: "DEGRADED_NO_WRITE", attempted: requests.length, posted, demoted, detail };
|
|
483
|
+
return { outcome: "DEGRADED_NO_WRITE", attempted: requests.length, posted, demoted, pullComments, detail };
|
|
343
484
|
}
|
|
344
485
|
if (pending > 0) {
|
|
345
486
|
return {
|
|
@@ -347,14 +488,16 @@ export async function postReviewThreads(
|
|
|
347
488
|
attempted: requests.length,
|
|
348
489
|
posted,
|
|
349
490
|
demoted,
|
|
491
|
+
pullComments,
|
|
350
492
|
detail,
|
|
351
493
|
};
|
|
352
494
|
}
|
|
353
495
|
detail.push(
|
|
354
496
|
`posted ${posted} review ${posted === 1 ? "comment" : "comments"}` +
|
|
355
|
-
(demoted === 0 ? "" : `, ${demoted} at file level after a line was refused`)
|
|
497
|
+
(demoted === 0 ? "" : `, ${demoted} at file level after a line was refused`) +
|
|
498
|
+
(pullComments === 0 ? "" : `, ${pullComments} on the conversation because the file is not in this pull request's diff`),
|
|
356
499
|
);
|
|
357
|
-
return { outcome: "POSTED", attempted: requests.length, posted, demoted, detail };
|
|
500
|
+
return { outcome: "POSTED", attempted: requests.length, posted, demoted, pullComments, detail };
|
|
358
501
|
}
|
|
359
502
|
|
|
360
503
|
/**
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one writer of `blocked by` links — #2345.
|
|
3
|
+
*
|
|
4
|
+
* `gh issue edit --add-blocked-by` exists only in recent `gh` releases. A
|
|
5
|
+
* consumer's self-hosted runner with an older `gh` failed every edge of a
|
|
6
|
+
* 35-issue plan with `unknown flag: --add-blocked-by` (2026-11-17). `gh api`
|
|
7
|
+
* is in every release, so links are written through the REST dependencies
|
|
8
|
+
* endpoint instead, and the runner's `gh` version stops mattering.
|
|
9
|
+
*
|
|
10
|
+
* **`issue_id` is the blocker's DATABASE id, not its number.** A number is
|
|
11
|
+
* accepted too and links whichever issue has that database id — measured
|
|
12
|
+
* 2026-11-05, recorded in `scripts/board-walkthrough.ts`. So each blocker's id
|
|
13
|
+
* is read first, and the blocked issue's links are read back once all are
|
|
14
|
+
* written: every blocker must be there, or the write is refused, never
|
|
15
|
+
* reported as wired. The read-back and not the POST's reply, because GitHub's
|
|
16
|
+
* documentation does not say which of the two issues that reply describes.
|
|
17
|
+
*
|
|
18
|
+
* **Calls, per blocked issue:** one id read per blocker not yet in `ids` (a
|
|
19
|
+
* caller writing many groups passes one map, so a blocker shared by many
|
|
20
|
+
* issues is read once), one POST per link, and one read-back. The REST
|
|
21
|
+
* endpoint takes one link per call, so a group can no longer be one call the
|
|
22
|
+
* way `issue edit --add-blocked-by a --add-blocked-by b` was.
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
/** How a `gh` call is made. Injected so a test never shells out. */
|
|
26
|
+
export type GhExec = (args: readonly string[]) => string;
|
|
27
|
+
|
|
28
|
+
function databaseId(repo: string, blocker: number, exec: GhExec, ids: Map<string, number>): number {
|
|
29
|
+
// Keyed by repository too: a dependency may cross repositories, so the same
|
|
30
|
+
// number in another repository is another issue (review of #2357).
|
|
31
|
+
const key = `${repo}#${blocker}`;
|
|
32
|
+
const known = ids.get(key);
|
|
33
|
+
if (known !== undefined) return known;
|
|
34
|
+
const raw = exec(["api", `repos/${repo}/issues/${blocker}`, "--jq", ".id"]).trim();
|
|
35
|
+
const id = Number(raw);
|
|
36
|
+
if (!Number.isSafeInteger(id) || id <= 0) {
|
|
37
|
+
throw new Error(`#${blocker}: could not read its database id (got "${raw.slice(0, 40)}"), so no link was written`);
|
|
38
|
+
}
|
|
39
|
+
ids.set(key, id);
|
|
40
|
+
return id;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export function addBlockers(
|
|
44
|
+
repo: string,
|
|
45
|
+
blocked: number,
|
|
46
|
+
blockers: readonly number[],
|
|
47
|
+
exec: GhExec,
|
|
48
|
+
ids: Map<string, number> = new Map(),
|
|
49
|
+
): void {
|
|
50
|
+
if (blockers.length === 0) return;
|
|
51
|
+
// Every id before any write, so an unreadable one writes nothing for this issue.
|
|
52
|
+
const resolved = blockers.map(b => ({ number: b, id: databaseId(repo, b, exec, ids) }));
|
|
53
|
+
for (const b of resolved) {
|
|
54
|
+
exec(["api", "-X", "POST", `repos/${repo}/issues/${blocked}/dependencies/blocked_by`, "-F", `issue_id=${b.id}`]);
|
|
55
|
+
}
|
|
56
|
+
// One number per line: `--paginate` concatenates pages, so one JSON document would not parse.
|
|
57
|
+
const linked = new Set(
|
|
58
|
+
exec(["api", "--paginate", `repos/${repo}/issues/${blocked}/dependencies/blocked_by?per_page=100`, "--jq", ".[].number"])
|
|
59
|
+
.split("\n")
|
|
60
|
+
.map(l => l.trim())
|
|
61
|
+
.filter(l => l !== "")
|
|
62
|
+
.map(Number),
|
|
63
|
+
);
|
|
64
|
+
const missing = blockers.filter(b => !linked.has(b));
|
|
65
|
+
if (missing.length > 0) {
|
|
66
|
+
throw new Error(
|
|
67
|
+
`#${blocked}: the writes returned, but ${missing.map(b => `#${b}`).join(", ")} ${missing.length === 1 ? "is" : "are"} not among its blockers ` +
|
|
68
|
+
`on read-back (${linked.size === 0 ? "none" : [...linked].map(n => `#${n}`).join(", ")})`,
|
|
69
|
+
);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Remove one `blocked by` link, through the same REST endpoint and by the same
|
|
75
|
+
* database id — `issue edit --remove-blocked-by` is missing from the same old
|
|
76
|
+
* `gh` (review of #2357). Read back afterwards: a link still there is refused.
|
|
77
|
+
*/
|
|
78
|
+
export function removeBlocker(
|
|
79
|
+
repo: string,
|
|
80
|
+
blocked: number,
|
|
81
|
+
blocker: number,
|
|
82
|
+
exec: GhExec,
|
|
83
|
+
ids: Map<string, number> = new Map(),
|
|
84
|
+
): void {
|
|
85
|
+
const id = databaseId(repo, blocker, exec, ids);
|
|
86
|
+
exec(["api", "-X", "DELETE", `repos/${repo}/issues/${blocked}/dependencies/blocked_by/${id}`]);
|
|
87
|
+
const linked = exec(["api", "--paginate", `repos/${repo}/issues/${blocked}/dependencies/blocked_by?per_page=100`, "--jq", ".[].number"])
|
|
88
|
+
.split("\n")
|
|
89
|
+
.map(l => l.trim())
|
|
90
|
+
.filter(l => l !== "")
|
|
91
|
+
.map(Number);
|
|
92
|
+
if (linked.includes(blocker)) {
|
|
93
|
+
throw new Error(`#${blocked}: the removal returned, but #${blocker} is still among its blockers on read-back`);
|
|
94
|
+
}
|
|
95
|
+
}
|
package/lib/board-mirror.ts
CHANGED
|
@@ -170,9 +170,17 @@ function unmeasuredSweep(reasons: string[]): SpecSweep {
|
|
|
170
170
|
return { reading: "UNMEASURED", specs: [], ids: [], collisions: [], unmeasuredReasons: reasons };
|
|
171
171
|
}
|
|
172
172
|
|
|
173
|
-
|
|
173
|
+
/**
|
|
174
|
+
* Which files under `<root>/specs` are specs — the ONE answer, shared by
|
|
175
|
+
* {@link specCriteriaIn} and `rungate board-scope` (#2275). It refuses only on
|
|
176
|
+
* what stops it locating a file; whether any spec states a criterion is the
|
|
177
|
+
* id sweep's question, not this one's.
|
|
178
|
+
*/
|
|
179
|
+
export function specFilesIn(
|
|
180
|
+
root: string,
|
|
181
|
+
readDir: SpecDirReader = readSpecDir,
|
|
182
|
+
): { reading: "MEASURED"; paths: string[] } | { reading: "UNMEASURED"; reasons: string[] } {
|
|
174
183
|
const dir = join(root, "specs");
|
|
175
|
-
let files: string[];
|
|
176
184
|
try {
|
|
177
185
|
const entries = readDir(dir).filter(e => e.isFile() && e.name.endsWith(".md"));
|
|
178
186
|
// `parentPath` is the ONLY field that can be trusted to name a nested
|
|
@@ -189,23 +197,34 @@ export function specCriteriaIn(root: string, readDir: SpecDirReader = readSpecDi
|
|
|
189
197
|
// not a sweep with fewer specs in it.
|
|
190
198
|
const unlocatable = unlocatableEntries(entries);
|
|
191
199
|
if (unlocatable.length > 0) {
|
|
192
|
-
return
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
`
|
|
196
|
-
|
|
200
|
+
return {
|
|
201
|
+
reading: "UNMEASURED",
|
|
202
|
+
reasons: [
|
|
203
|
+
`this runtime does not report Dirent.parentPath, so ${unlocatable.length} spec file(s) ` +
|
|
204
|
+
`under ${dir} cannot be located — a nested spec would be read as a top-level one. ` +
|
|
205
|
+
`Nothing was read: ${unlocatable.map(e => e.name).sort().join(", ")}`,
|
|
206
|
+
],
|
|
207
|
+
};
|
|
197
208
|
}
|
|
198
209
|
// `as string` rather than a second `typeof e.parentPath === "string"`:
|
|
199
210
|
// the refusal above already decided that question for every entry here,
|
|
200
211
|
// and a second decider answering it again is one no behavioural test can
|
|
201
212
|
// tell apart from the first.
|
|
202
|
-
|
|
213
|
+
const paths = entries
|
|
203
214
|
.map(e => relative(root, join(e.parentPath as string, e.name)).split(sep).join("/"))
|
|
204
215
|
.filter(p => !(NOT_A_SPEC as readonly string[]).includes(p))
|
|
205
216
|
.sort();
|
|
217
|
+
return { reading: "MEASURED", paths };
|
|
206
218
|
} catch (e) {
|
|
207
|
-
return
|
|
219
|
+
return { reading: "UNMEASURED", reasons: [`could not read ${dir}: ${(e as Error).message}`] };
|
|
208
220
|
}
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
export function specCriteriaIn(root: string, readDir: SpecDirReader = readSpecDir): SpecSweep {
|
|
224
|
+
const dir = join(root, "specs");
|
|
225
|
+
const listed = specFilesIn(root, readDir);
|
|
226
|
+
if ("reasons" in listed) return unmeasuredSweep(listed.reasons);
|
|
227
|
+
const files = listed.paths;
|
|
209
228
|
|
|
210
229
|
const specs: SpecCriteria[] = [];
|
|
211
230
|
const reasons: string[] = [];
|
package/lib/cli-commands.ts
CHANGED
|
@@ -124,6 +124,17 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
|
|
|
124
124
|
summary: "Report which success criteria are matched, unmatched or uncovered",
|
|
125
125
|
usage: "rungate audit-specs",
|
|
126
126
|
},
|
|
127
|
+
// #2360: a consumer ticks its own criteria from its own test claims. The
|
|
128
|
+
// script was in `files[]` and reachable from nothing, and it read
|
|
129
|
+
// `join(import.meta.dir, "..")` — run from node_modules it ticked nothing
|
|
130
|
+
// of the consumer's and reported on rungate's specs. `projectRootFlag` is
|
|
131
|
+
// load-bearing, as on `audit-spec-evidence`.
|
|
132
|
+
"sync-sc-status": {
|
|
133
|
+
script: "scripts/sync-sc-status.ts",
|
|
134
|
+
summary: "Tick each criterion a passing test claims, in this project's specs",
|
|
135
|
+
usage: "rungate sync-sc-status [--dry-run] [--report] [--only <SC-id,…>] [--project-root <dir>]",
|
|
136
|
+
projectRootFlag: true,
|
|
137
|
+
},
|
|
127
138
|
// Registered because `create-spec` SHIPS and stamps every generated spec
|
|
128
139
|
// with `evidence: required`, and this is the only thing that enforces that
|
|
129
140
|
// key (#1639). Without the entry the published package emitted a document
|
|
@@ -227,7 +238,7 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
|
|
|
227
238
|
// argument it would read as a positional.
|
|
228
239
|
"board-conformance": {
|
|
229
240
|
script: "scripts/board-conformance.ts",
|
|
230
|
-
summary: "
|
|
241
|
+
summary: "Whether the board says what the spec says, reading by reading",
|
|
231
242
|
usage: "rungate board-conformance [--reading <name>] [--snapshot <path>] [--list-readings]",
|
|
232
243
|
},
|
|
233
244
|
// Step 4 of ADR-003, in reverse. The issue template's own footer says a
|
|
@@ -239,11 +250,36 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
|
|
|
239
250
|
"plan-issues": {
|
|
240
251
|
script: "scripts/plan-issues.ts",
|
|
241
252
|
summary:
|
|
242
|
-
"Apply an approved issue plan
|
|
253
|
+
"Apply an approved issue plan: --decompose files issues, --repair links and demotes them",
|
|
243
254
|
usage:
|
|
244
255
|
"rungate plan-issues (--repair | --decompose) <plan.md> --repo <owner/name> [--write] [--json]",
|
|
245
256
|
projectRootFlag: true,
|
|
246
257
|
},
|
|
258
|
+
// ADR-020 Decision 1 (SC-2782): every open `from-consumer` issue with no
|
|
259
|
+
// verdict marker gets exactly one, from `lib/consumer-triage.ts`. Reads the
|
|
260
|
+
// tracker AND the tree (the opted-in specs place an issue), hence the root flag.
|
|
261
|
+
"consumer-triage": {
|
|
262
|
+
script: "scripts/consumer-triage.ts",
|
|
263
|
+
summary: "Give each consumer-filed issue with no verdict exactly one",
|
|
264
|
+
usage: "rungate consumer-triage --repo <owner/name> [--write] [--json]",
|
|
265
|
+
projectRootFlag: true,
|
|
266
|
+
},
|
|
267
|
+
// #2275, onboarding existing specs. Read-only: what each spec holds, its
|
|
268
|
+
// `board:` setting, and a looks-done hint per unticked criterion. It never
|
|
269
|
+
// ticks. Reads the working directory, so it takes no root flag.
|
|
270
|
+
"board-scope": {
|
|
271
|
+
script: "scripts/board-scope.ts",
|
|
272
|
+
summary: "Spec criteria and opt-in, with looks-done hints",
|
|
273
|
+
usage: "rungate board-scope [--spec <path>] [--json]",
|
|
274
|
+
},
|
|
275
|
+
// #2330. The pinned "where we are" view as a command a consumer can run:
|
|
276
|
+
// every family's phases with their open issues and blockers. Reads the
|
|
277
|
+
// working directory and its origin remote, so it takes no root flag.
|
|
278
|
+
board: {
|
|
279
|
+
script: "scripts/status-view.ts",
|
|
280
|
+
summary: "Each phase's open issues and blockers",
|
|
281
|
+
usage: "rungate board [--repo <owner/name>] [--markdown] (repository defaults to GITHUB_REPOSITORY, then the origin remote)",
|
|
282
|
+
},
|
|
247
283
|
// Step 5 of ADR-003. `plan-spec` turns the placement table into milestones;
|
|
248
284
|
// this turns the ORDER of those milestones into `blocked by` edges, which is
|
|
249
285
|
// AGENTS.md rule 4 — ordering is data, not prose.
|
|
@@ -302,7 +338,7 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
|
|
|
302
338
|
// `projectRootFlag`: it reads `process.cwd()`, which the child inherits.
|
|
303
339
|
"unaccounted-work": {
|
|
304
340
|
script: "scripts/unaccounted-work.ts",
|
|
305
|
-
summary: "
|
|
341
|
+
summary: "Undone work declared in prose that no open issue covers",
|
|
306
342
|
usage:
|
|
307
343
|
"rungate unaccounted-work [--project-root <dir>] [--repo <owner/name>] [--issues-fixture <file.json>] [--json] " +
|
|
308
344
|
"(exit 1 when work is unaccounted, 2 when a source could not be read)",
|
|
@@ -312,7 +348,7 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
|
|
|
312
348
|
// each intake source runs on its own trigger.
|
|
313
349
|
intake: {
|
|
314
350
|
script: "scripts/intake.ts",
|
|
315
|
-
summary: "Run each intake source and print its reading
|
|
351
|
+
summary: "Run each intake source and print its reading, MEASURED or UNMEASURED",
|
|
316
352
|
usage:
|
|
317
353
|
"rungate intake [--project-root <dir>] [--source <id>] [--json] " +
|
|
318
354
|
"(advisory: an unreadable source prints UNMEASURED and exits 0; exit 2 on a bad argument)",
|
package/lib/config-trackable.ts
CHANGED
|
@@ -107,7 +107,7 @@
|
|
|
107
107
|
* measured before and after, and a single new entry reverts the write.
|
|
108
108
|
*/
|
|
109
109
|
import { spawnSync } from "child_process";
|
|
110
|
-
import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
|
|
110
|
+
import { existsSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
|
|
111
111
|
import { join } from "path";
|
|
112
112
|
import {
|
|
113
113
|
DIRECTORY_CONFIG_FILES,
|
|
@@ -183,18 +183,34 @@ function matchedByIgnoreRules(root: string, paths: readonly string[]): Trackable
|
|
|
183
183
|
return { ignored: paths.filter(p => matched.has(p)), failure: null };
|
|
184
184
|
}
|
|
185
185
|
|
|
186
|
+
/** git's own refusal outside a repository: exit 128, and it says so. */
|
|
187
|
+
const NOT_A_REPOSITORY = /not a git repository/i;
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* Whether `root` is inside a work tree. "Outside" is only git's own exit-128
|
|
191
|
+
* refusal saying so, or a probe from inside `.git` itself; a git that could
|
|
192
|
+
* not run, or failed any other way, is a failure string, never "outside"
|
|
193
|
+
* (review of #2359 — the same fail-open in two callers).
|
|
194
|
+
*/
|
|
195
|
+
function workTreeProbe(root: string): "inside" | "outside" | { failure: string } {
|
|
196
|
+
const r = git(root, ["rev-parse", "--is-inside-work-tree"]);
|
|
197
|
+
if (r.status === 128 && NOT_A_REPOSITORY.test(r.stderr)) return "outside";
|
|
198
|
+
if (r.status !== 0) return { failure: `git rev-parse failed (${r.status}): ${r.stderr.trim() || "no output"}` };
|
|
199
|
+
return r.stdout.trim() === "true" ? "inside" : "outside";
|
|
200
|
+
}
|
|
201
|
+
|
|
186
202
|
/**
|
|
187
203
|
* Whether this project's ignore rules mark the rungate config disposable.
|
|
188
204
|
*
|
|
189
205
|
* A project that is not a git repository has no ignore rules and nothing can
|
|
190
206
|
* delete the file on a checkout, so that is `{ ignored: [], failure: null }`
|
|
191
|
-
* and not an error — the harness scaffolds into trees that are not repos.
|
|
207
|
+
* and not an error — the harness scaffolds into trees that are not repos. A
|
|
208
|
+
* git that cannot answer is a `failure`, not that case.
|
|
192
209
|
*/
|
|
193
210
|
export function configPathsIgnored(root: string): TrackableReading {
|
|
194
|
-
const
|
|
195
|
-
if (
|
|
196
|
-
|
|
197
|
-
}
|
|
211
|
+
const probe = workTreeProbe(root);
|
|
212
|
+
if (probe === "outside") return { ignored: [], failure: null };
|
|
213
|
+
if (probe !== "inside") return { ignored: [], failure: probe.failure };
|
|
198
214
|
return matchedByIgnoreRules(root, RUNGATE_CONFIG_IGNORE_PATHS);
|
|
199
215
|
}
|
|
200
216
|
|
|
@@ -437,3 +453,72 @@ export function ensureConfigTrackable(
|
|
|
437
453
|
`and is now committable; commit it, or the next branch switch deletes it)`,
|
|
438
454
|
);
|
|
439
455
|
}
|
|
456
|
+
|
|
457
|
+
/**
|
|
458
|
+
* The concrete files a set of owned-file rows names on disk. A row is a path,
|
|
459
|
+
* or a `<dir>/*<ext>` class (`.claude/agents/*.md`), expanded to the files of
|
|
460
|
+
* that directory with that extension. Absent files are left out: an ignore
|
|
461
|
+
* rule only matters for a file that was written. A directory that exists but
|
|
462
|
+
* cannot be listed is a `failure`, not an absence (review of #2359): only
|
|
463
|
+
* ENOENT means nothing was written there.
|
|
464
|
+
*/
|
|
465
|
+
function ownedPathsOnDisk(root: string, rows: readonly string[]): { paths: string[]; failures: string[] } {
|
|
466
|
+
const out: string[] = [];
|
|
467
|
+
const failures: string[] = [];
|
|
468
|
+
for (const row of rows) {
|
|
469
|
+
const star = row.lastIndexOf("/*");
|
|
470
|
+
if (star === -1) {
|
|
471
|
+
if (existsSync(join(root, row))) out.push(row);
|
|
472
|
+
continue;
|
|
473
|
+
}
|
|
474
|
+
const dir = row.slice(0, star);
|
|
475
|
+
const ext = row.slice(star + 2);
|
|
476
|
+
let names: string[];
|
|
477
|
+
try {
|
|
478
|
+
names = readdirSync(join(root, dir));
|
|
479
|
+
} catch (e) {
|
|
480
|
+
const code = (e as NodeJS.ErrnoException).code;
|
|
481
|
+
// ENOENT: the directory was not written, so nothing in it can be ignored.
|
|
482
|
+
if (code !== "ENOENT") failures.push(`${dir} could not be listed (${code ?? (e as Error).message})`);
|
|
483
|
+
continue;
|
|
484
|
+
}
|
|
485
|
+
for (const n of names.sort()) if (n.endsWith(ext)) out.push(`${dir}/${n}`);
|
|
486
|
+
}
|
|
487
|
+
return { paths: out, failures };
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
/**
|
|
491
|
+
* #2347: name every owned file this scaffold left in a path the project's
|
|
492
|
+
* ignore rules match. Such a file is written, never committed, and so never
|
|
493
|
+
* ships, which on one consumer was the `/dry-run` command (`.claude/*`
|
|
494
|
+
* ignored, agents and rules negated, commands not). It only reports: whether
|
|
495
|
+
* scaffold should also make the path trackable is a decision recorded on
|
|
496
|
+
* #2347, not taken here. A tree that is not a repository has no ignore rules
|
|
497
|
+
* and gets no line; a git that cannot answer gets an UNMEASURED line, never
|
|
498
|
+
* a clean silence. "Not a repository" is only git's own exit-128 refusal
|
|
499
|
+
* saying so; a git that could not run, or failed any other way, is
|
|
500
|
+
* UNMEASURED (review of #2359).
|
|
501
|
+
*/
|
|
502
|
+
export function reportIgnoredOwnedFiles(root: string, actions: string[], rows: readonly string[]): void {
|
|
503
|
+
const unmeasured = (why: string) =>
|
|
504
|
+
actions.push(`UNMEASURED: whether any file scaffold owns is ignored could not be read — ${why}`);
|
|
505
|
+
const probe = workTreeProbe(root);
|
|
506
|
+
if (probe === "outside") return;
|
|
507
|
+
if (probe !== "inside") {
|
|
508
|
+
unmeasured(probe.failure);
|
|
509
|
+
return;
|
|
510
|
+
}
|
|
511
|
+
const owned = ownedPathsOnDisk(root, rows);
|
|
512
|
+
for (const f of owned.failures) unmeasured(f);
|
|
513
|
+
const reading = matchedByIgnoreRules(root, owned.paths);
|
|
514
|
+
if (reading.failure !== null) {
|
|
515
|
+
unmeasured(reading.failure);
|
|
516
|
+
return;
|
|
517
|
+
}
|
|
518
|
+
for (const path of reading.ignored) {
|
|
519
|
+
actions.push(
|
|
520
|
+
`IGNORED: ${path} is written by scaffold, but this project's ignore rules match it, so it will not be ` +
|
|
521
|
+
`committed and will not ship; \`git check-ignore -v ${path}\` names the rule, and a \`!\` line after it un-ignores the path`,
|
|
522
|
+
);
|
|
523
|
+
}
|
|
524
|
+
}
|