rungate 0.8.13 → 0.8.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +82 -0
- package/gates/.gate-salt +1 -1
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +50 -5
- package/lib/board-flow.ts +235 -0
- package/lib/board-lane-health.ts +381 -0
- package/lib/board-mirror.ts +53 -35
- package/lib/board-ready-fanout.ts +56 -13
- package/lib/board-ready-rule.ts +545 -0
- package/lib/board-throughput.ts +136 -0
- package/lib/board-walkthrough.ts +240 -0
- package/lib/body-evidence.ts +203 -0
- package/lib/branch-protection.ts +399 -9
- package/lib/conformity.ts +95 -2
- package/lib/filing-compliance.ts +367 -0
- package/lib/finding-arbiter.ts +79 -5
- package/lib/generators/agents-md.ts +149 -0
- package/lib/github.ts +79 -0
- package/lib/graphql-cursor.ts +80 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +33 -3
- package/lib/issue-file-overlap.ts +340 -0
- package/lib/issue-filing-gate.ts +173 -8
- package/lib/issue-repair.ts +13 -9
- package/lib/issue-shape.ts +196 -0
- package/lib/scaffold/ai-review-findings.ts +9 -1
- package/lib/scaffold/ai-review-step.ts +35 -1
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +34 -11
- package/lib/spec-placement.ts +108 -0
- package/lib/stage-ladder.ts +28 -3
- package/lib/work-status.ts +423 -0
- package/package.json +1 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/board-mirror.ts +221 -8
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-spec.ts +79 -1
package/lib/github.ts
CHANGED
|
@@ -46,6 +46,12 @@ export interface GitHubClient {
|
|
|
46
46
|
* `listMilestones` below passes `all` and does not expose the choice.
|
|
47
47
|
*/
|
|
48
48
|
listMilestones: (params: { owner: string; repo: string; state?: string; per_page?: number }) => Promise<{ data: any[] }>;
|
|
49
|
+
/**
|
|
50
|
+
* One issue's comments. Paginated by the caller — `listIssueComments`
|
|
51
|
+
* below walks every page, because a single page silently truncates and
|
|
52
|
+
* a short list reads as a smaller answer rather than a wrong one.
|
|
53
|
+
*/
|
|
54
|
+
listComments: (params: { owner: string; repo: string; issue_number: number; per_page?: number; page?: number }) => Promise<{ data: any[] }>;
|
|
49
55
|
createMilestone: (params: { owner: string; repo: string; title: string; description?: string }) => Promise<{ data: any }>;
|
|
50
56
|
updateMilestone: (params: { owner: string; repo: string; milestone_number: number; title?: string; description?: string }) => Promise<{ data: any }>;
|
|
51
57
|
};
|
|
@@ -623,6 +629,79 @@ export async function listOpenIssues(
|
|
|
623
629
|
return { considered: rows.length, perPage, truncated: rows.length >= perPage, droppedRows, issues };
|
|
624
630
|
}
|
|
625
631
|
|
|
632
|
+
/**
|
|
633
|
+
* Every comment on an issue, in creation order, across every page.
|
|
634
|
+
*
|
|
635
|
+
* SC-893: infrastructure reaches GitHub through Octokit, never through a `gh`
|
|
636
|
+
* subprocess. This replaced a `gh api --paginate --jq .[].created_at` call in
|
|
637
|
+
* `lib/filing-compliance.ts`, which was the last one in `lib/`.
|
|
638
|
+
*
|
|
639
|
+
* Pagination is a loop rather than a single `per_page: 100` read: a busy
|
|
640
|
+
* issue passes 100 comments, and a truncated list is not a smaller answer —
|
|
641
|
+
* it is a wrong one, and the reading it feeds is a compliance rate.
|
|
642
|
+
*/
|
|
643
|
+
export async function listIssueComments(
|
|
644
|
+
client: GitHubClient,
|
|
645
|
+
repoSlug: string,
|
|
646
|
+
issueNumber: number,
|
|
647
|
+
): Promise<{ created_at: string }[]> {
|
|
648
|
+
const { owner, repo } = parseOwnerRepo(repoSlug);
|
|
649
|
+
const perPage = 100;
|
|
650
|
+
// AN UNBOUNDED PAGE WALK IS NOT A READING, IT IS A HANG. This loop used to
|
|
651
|
+
// terminate only on a short page, so a server-side paging bug, a `page`
|
|
652
|
+
// param silently ignored, or a client that always answers with a full page
|
|
653
|
+
// held the calling process open forever with no reading and no error. The
|
|
654
|
+
// sibling `listOpenIssues` above takes the opposite tradeoff on purpose —
|
|
655
|
+
// one page, and a `truncated` flag — so neither function should simply
|
|
656
|
+
// trust the server to end the walk.
|
|
657
|
+
//
|
|
658
|
+
// 100 pages is 10,000 comments on one issue. Reaching it means the
|
|
659
|
+
// assumption is wrong, which is UNMEASURED rather than a long answer.
|
|
660
|
+
const maxPages = 100;
|
|
661
|
+
const out: { created_at: string }[] = [];
|
|
662
|
+
for (let page = 1; ; page++) {
|
|
663
|
+
if (page > maxPages) {
|
|
664
|
+
throw new Error(
|
|
665
|
+
`listComments walked ${maxPages} pages without a short page, so this read is ` +
|
|
666
|
+
`UNMEASURED rather than complete. Either the issue has more than ${maxPages * perPage} ` +
|
|
667
|
+
`comments or the server is not honouring the page parameter.`,
|
|
668
|
+
);
|
|
669
|
+
}
|
|
670
|
+
const response = await client.rest.issues.listComments({
|
|
671
|
+
owner,
|
|
672
|
+
repo,
|
|
673
|
+
issue_number: issueNumber,
|
|
674
|
+
per_page: perPage,
|
|
675
|
+
page,
|
|
676
|
+
});
|
|
677
|
+
// A SHAPE WE DID NOT EXPECT IS A FAILURE, NOT AN EMPTY PAGE. This read
|
|
678
|
+
// `Array.isArray(response?.data) ? response.data : []`, which turned any
|
|
679
|
+
// unexpected payload into a legitimately empty page: the loop then saw
|
|
680
|
+
// `rows.length < perPage`, returned what it had, and the caller reported
|
|
681
|
+
// MEASURED with zero comments. That is "nobody commented" where the truth
|
|
682
|
+
// is "we could not tell" — the exact conflation this module's header
|
|
683
|
+
// forbids, reached without any failure ever being observed. Throwing puts
|
|
684
|
+
// it back on the UNMEASURED path, which carries its own sentence.
|
|
685
|
+
if (!Array.isArray(response?.data)) {
|
|
686
|
+
throw new Error(
|
|
687
|
+
`listComments resolved with data of an unexpected shape (${
|
|
688
|
+
response?.data === null || response?.data === undefined
|
|
689
|
+
? String(response?.data)
|
|
690
|
+
: typeof response.data
|
|
691
|
+
}), so this page is UNMEASURED rather than empty. ` +
|
|
692
|
+
`A non-array payload is not zero comments.`,
|
|
693
|
+
);
|
|
694
|
+
}
|
|
695
|
+
const rows = response.data;
|
|
696
|
+
for (const row of rows) {
|
|
697
|
+
if (row !== null && typeof row === "object" && typeof row.created_at === "string") {
|
|
698
|
+
out.push({ created_at: row.created_at as string });
|
|
699
|
+
}
|
|
700
|
+
}
|
|
701
|
+
if (rows.length < perPage) return out;
|
|
702
|
+
}
|
|
703
|
+
}
|
|
704
|
+
|
|
626
705
|
/**
|
|
627
706
|
* Add a comment to an issue.
|
|
628
707
|
*/
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One decider for "is there another page, and what is its cursor".
|
|
3
|
+
*
|
|
4
|
+
* Covers SC-2720, SC-2721 (specs/BOARD-FLOW-SPEC.md).
|
|
5
|
+
*
|
|
6
|
+
* ## Why this is a module and not four `if`s
|
|
7
|
+
*
|
|
8
|
+
* Every GraphQL pager in this repository spelled the same line:
|
|
9
|
+
*
|
|
10
|
+
* ```ts
|
|
11
|
+
* c = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null;
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* and every one of them **ends the loop and returns a confident partial
|
|
15
|
+
* reading** for three different malformed pages: a `pageInfo` that is
|
|
16
|
+
* absent, one that exists without `hasNextPage`, and one whose `endCursor`
|
|
17
|
+
* is `""`. The last is the nastiest — an empty string passes a `typeof`
|
|
18
|
+
* check and is then falsy, so a guard that looks correct lets it through.
|
|
19
|
+
*
|
|
20
|
+
* All three were found on `lib/board-throughput.ts` across two pull
|
|
21
|
+
* requests, one variant at a time, and the third was found with the
|
|
22
|
+
* correct spelling already sitting in `scripts/board-status-sweep.ts`.
|
|
23
|
+
* Fixing them one site at a time is the defect that keeps producing the
|
|
24
|
+
* defect: `.claude/rules/checks-must-be-able-to-fail.md` calls a
|
|
25
|
+
* behavioural suite over N copies "catches only the last one to regress".
|
|
26
|
+
*
|
|
27
|
+
* So the property is asserted across the sites rather than repaired at
|
|
28
|
+
* them. One binding, one mutation, every pager.
|
|
29
|
+
*
|
|
30
|
+
* ## A truncation is UNMEASURED, and that is not the same as an error
|
|
31
|
+
*
|
|
32
|
+
* The caller decides what to do — refuse the run, mark a row, throw — but
|
|
33
|
+
* it may not decide that a page it could not read was the last one. That
|
|
34
|
+
* distinction is the whole point and it is why `done` and `unreadable` are
|
|
35
|
+
* separate cases rather than one nullable cursor.
|
|
36
|
+
*/
|
|
37
|
+
|
|
38
|
+
export type CursorReading =
|
|
39
|
+
/** There is another page, and this is a cursor that can fetch it. */
|
|
40
|
+
| { readonly kind: "more"; readonly cursor: string }
|
|
41
|
+
/** That was the last page. The reading is complete. */
|
|
42
|
+
| { readonly kind: "done" }
|
|
43
|
+
/** The page could not say. **Never treat this as `done`.** */
|
|
44
|
+
| { readonly kind: "unreadable"; readonly why: string };
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Read a connection's `pageInfo`.
|
|
48
|
+
*
|
|
49
|
+
* Takes `unknown` on purpose: every caller is handing over a value parsed
|
|
50
|
+
* from a network response, and typing the parameter as a well-formed
|
|
51
|
+
* `pageInfo` would make the compiler assert exactly the property this
|
|
52
|
+
* function exists to check.
|
|
53
|
+
*/
|
|
54
|
+
export function nextCursor(pageInfo: unknown): CursorReading {
|
|
55
|
+
if (typeof pageInfo !== "object" || pageInfo === null) {
|
|
56
|
+
return {
|
|
57
|
+
kind: "unreadable",
|
|
58
|
+
why: "the page carried no pageInfo, so whether more pages exist is unknown",
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
const info = pageInfo as { hasNextPage?: unknown; endCursor?: unknown };
|
|
62
|
+
if (typeof info.hasNextPage !== "boolean") {
|
|
63
|
+
return {
|
|
64
|
+
kind: "unreadable",
|
|
65
|
+
why: `pageInfo.hasNextPage is ${typeof info.hasNextPage}, not a boolean, so "no more pages" cannot be read from it`,
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
if (!info.hasNextPage) return { kind: "done" };
|
|
69
|
+
// **Non-empty, not merely a string.** `""` is a string and is falsy, so
|
|
70
|
+
// a `typeof` check passes it and `while (cursor)` then ends the loop —
|
|
71
|
+
// a guard that reads correctly and admits the exact value it was
|
|
72
|
+
// written to exclude. ai-review round 1 of #1794.
|
|
73
|
+
if (typeof info.endCursor !== "string" || info.endCursor.length === 0) {
|
|
74
|
+
return {
|
|
75
|
+
kind: "unreadable",
|
|
76
|
+
why: "the page says more exist and gave no usable endCursor, so the rest cannot be fetched",
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
return { kind: "more", cursor: info.endCursor };
|
|
80
|
+
}
|
|
@@ -1,3 +1,6 @@
|
|
|
1
|
+
import { homedir } from "os";
|
|
2
|
+
import { join, resolve } from "path";
|
|
3
|
+
|
|
1
4
|
import { interpreterPrograms, stripHeredocs } from "./bash-write-guard";
|
|
2
5
|
|
|
3
6
|
/**
|
|
@@ -259,7 +262,160 @@ export function clauses(cmd: string, depth = 0): string[][] {
|
|
|
259
262
|
* is worse than either position.
|
|
260
263
|
*/
|
|
261
264
|
function heredocView(cmd: string): string {
|
|
262
|
-
|
|
265
|
+
// `blankComments: false` (#1741). The blanking is #1176's write-guard
|
|
266
|
+
// safety measure and this parser never wanted it: it deleted every `##`
|
|
267
|
+
// markdown heading from a multi-line `gh issue create --body "…"`, so the
|
|
268
|
+
// dedupe and the symptom scan read bodies with holes. `tokenize` below
|
|
269
|
+
// implements the shell's comment rule for this side of the fence, where a
|
|
270
|
+
// wrong answer costs a misparsed flag rather than an unseen write.
|
|
271
|
+
return [
|
|
272
|
+
stripHeredocs(cmd, false),
|
|
273
|
+
...interpreterPrograms(cmd).map(p => p.program),
|
|
274
|
+
].join("\n");
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/**
|
|
278
|
+
* The directory the first `gh issue create` in this command runs in (#1833).
|
|
279
|
+
*
|
|
280
|
+
* **An issue is a repository object, so nothing about a filing may depend on
|
|
281
|
+
* the session that happened to type it.** The gate used to hand every stage
|
|
282
|
+
* `process.cwd()` — the directory the HOOK was spawned in, which is the
|
|
283
|
+
* session's launch directory and not the command's. Measured 2026-11-06: one
|
|
284
|
+
* `gh issue create` run in `rg-wt-1675` was attributed to `rg-wt-threads2`,
|
|
285
|
+
* named a branch the command never touched, and reported a 735-byte
|
|
286
|
+
* `--body-file` as unreadable because it looked for it in the other checkout.
|
|
287
|
+
*
|
|
288
|
+
* **The directory is IN the command, and that is not a coincidence.** This
|
|
289
|
+
* repository forbids a top-level `cd` (`hooks/TopLevelCdGuard.hook.ts`), so
|
|
290
|
+
* every command that runs somewhere other than the session's directory
|
|
291
|
+
* spells that directory out — `(cd <path> && …)`. There is nowhere else to
|
|
292
|
+
* read it from: the hook payload carries the SESSION's directory, which is
|
|
293
|
+
* the value that was already wrong.
|
|
294
|
+
*
|
|
295
|
+
* **Subshell-aware, because the shell is.** A `cd` inside `( … )` or a
|
|
296
|
+
* backtick pair is undone when that scope closes, so
|
|
297
|
+
* `(cd /a && echo) && gh issue create` files from `from` and not from `/a`.
|
|
298
|
+
* `entered` is that stack. A backtick is a TOGGLE and not an opener —
|
|
299
|
+
* backticks do not nest, so the second one pops the scope the first pushed.
|
|
300
|
+
* Pushing on both was the first spelling of this, and it leaked a
|
|
301
|
+
* command-substitution's `cd` into everything after the closing backtick.
|
|
302
|
+
*
|
|
303
|
+
* **It descends into `-c` and `eval` arguments, exactly where `clauses()`
|
|
304
|
+
* does and for the same reason.** `bash -c "cd /wt/a && gh issue create …"`
|
|
305
|
+
* is a filing — `createsIssue` sees it through that recursion — so a reader
|
|
306
|
+
* of the top-level token stream alone would detect the filing and attribute
|
|
307
|
+
* it to the session, which is the whole of #1833 reached by another route.
|
|
308
|
+
* The inner scope's directory is discarded and only a filing found inside it
|
|
309
|
+
* is kept, because a wrapper's `cd` does not outlive the wrapper.
|
|
310
|
+
*
|
|
311
|
+
* `$(…)` needs nothing: `tokenize` already emits `$` and `(` separately, so
|
|
312
|
+
* a command substitution pushes and pops through the same stack.
|
|
313
|
+
*
|
|
314
|
+
* ## Two documented limits, both asserted rather than assumed
|
|
315
|
+
*
|
|
316
|
+
* **One answer per command, taken at the FIRST filing.** A command filing
|
|
317
|
+
* twice from two different directories would need two, and no such command
|
|
318
|
+
* has ever been written here; one binding that is sometimes coarse beats two
|
|
319
|
+
* that can disagree (`.claude/rules/checks-must-be-able-to-fail.md`, the
|
|
320
|
+
* fourth shape).
|
|
321
|
+
*
|
|
322
|
+
* **A `cd` this cannot resolve leaves the directory alone.** `cd -` is the
|
|
323
|
+
* only such spelling — it needs `OLDPWD`, which is the shell's state and not
|
|
324
|
+
* the command's text. A bare `cd` IS resolvable and goes to `homedir()`.
|
|
325
|
+
*/
|
|
326
|
+
export function filingDirectory(cmd: string, from: string): string {
|
|
327
|
+
return scanForFiling(cmd, from, 0).found ?? from;
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
/**
|
|
331
|
+
* One scope's worth of the scan: the filing's directory if this text files,
|
|
332
|
+
* and the directory the text ends in.
|
|
333
|
+
*
|
|
334
|
+
* `depth` bounds the `-c` recursion at the same 4 `clauses()` uses — a
|
|
335
|
+
* wrapper chain that deep is not an accident, and the two readers must agree
|
|
336
|
+
* about which commands exist or one of them attributes a filing the other
|
|
337
|
+
* cannot see.
|
|
338
|
+
*/
|
|
339
|
+
function scanForFiling(
|
|
340
|
+
cmd: string,
|
|
341
|
+
from: string,
|
|
342
|
+
depth: number,
|
|
343
|
+
): { found: string | null; dir: string } {
|
|
344
|
+
let dir = from;
|
|
345
|
+
const entered: string[] = [];
|
|
346
|
+
let inBacktick = false;
|
|
347
|
+
let clause: string[] = [];
|
|
348
|
+
let found: string | null = null;
|
|
349
|
+
|
|
350
|
+
const settle = (): void => {
|
|
351
|
+
if (found !== null || clause.length === 0) return;
|
|
352
|
+
if (createsIssue(clause)) {
|
|
353
|
+
found = dir;
|
|
354
|
+
return;
|
|
355
|
+
}
|
|
356
|
+
// Before the `cd`, not after: a wrapper's argument runs in the directory
|
|
357
|
+
// the wrapper was invoked from, and the clause cannot be both.
|
|
358
|
+
if (depth < 4) {
|
|
359
|
+
for (const inner of commandArguments(clause)) {
|
|
360
|
+
const nested = scanForFiling(inner, dir, depth + 1);
|
|
361
|
+
if (nested.found !== null) {
|
|
362
|
+
found = nested.found;
|
|
363
|
+
return;
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
if (clause[0] === "cd") dir = cdTarget(clause.slice(1), dir);
|
|
368
|
+
};
|
|
369
|
+
|
|
370
|
+
const close = (): void => {
|
|
371
|
+
settle();
|
|
372
|
+
clause = [];
|
|
373
|
+
// An unbalanced closer is a malformed command, not a reason to pop an
|
|
374
|
+
// empty stack and lose the directory the filing actually ran in.
|
|
375
|
+
if (entered.length > 0) dir = entered.pop()!;
|
|
376
|
+
};
|
|
377
|
+
|
|
378
|
+
for (const t of tokenize(heredocView(cmd))) {
|
|
379
|
+
if (t === "`") {
|
|
380
|
+
if (inBacktick) close();
|
|
381
|
+
else {
|
|
382
|
+
settle();
|
|
383
|
+
clause = [];
|
|
384
|
+
entered.push(dir);
|
|
385
|
+
}
|
|
386
|
+
inBacktick = !inBacktick;
|
|
387
|
+
continue;
|
|
388
|
+
}
|
|
389
|
+
if (t === "(") {
|
|
390
|
+
settle();
|
|
391
|
+
clause = [];
|
|
392
|
+
entered.push(dir);
|
|
393
|
+
continue;
|
|
394
|
+
}
|
|
395
|
+
if (t === ")") {
|
|
396
|
+
close();
|
|
397
|
+
continue;
|
|
398
|
+
}
|
|
399
|
+
if (SEPARATORS.has(t)) {
|
|
400
|
+
settle();
|
|
401
|
+
clause = [];
|
|
402
|
+
continue;
|
|
403
|
+
}
|
|
404
|
+
clause.push(t);
|
|
405
|
+
}
|
|
406
|
+
settle();
|
|
407
|
+
return { found, dir };
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
/** Where a `cd` with these arguments lands, or `dir` when it cannot be read. */
|
|
411
|
+
function cdTarget(args: string[], dir: string): string {
|
|
412
|
+
const path = args.filter(a => !a.startsWith("-"));
|
|
413
|
+
if (path.length === 0) return args.includes("-") ? dir : homedir();
|
|
414
|
+
if (path.length > 1) return dir;
|
|
415
|
+
const target = path[0];
|
|
416
|
+
if (target === "~") return homedir();
|
|
417
|
+
if (target.startsWith("~/")) return join(homedir(), target.slice(2));
|
|
418
|
+
return resolve(dir, target);
|
|
263
419
|
}
|
|
264
420
|
|
|
265
421
|
/** Arguments of this clause that are themselves commands. */
|
|
@@ -278,11 +434,253 @@ function commandArguments(tokens: string[]): string[] {
|
|
|
278
434
|
const basename = (t: string) => t.split("/").pop()!;
|
|
279
435
|
|
|
280
436
|
/**
|
|
281
|
-
*
|
|
437
|
+
* `gh api` flags that do NOT consume the following token.
|
|
438
|
+
*
|
|
439
|
+
* **Read off `gh api --help` on 2026-11-06, not guessed.** Rounds 1 and 2
|
|
440
|
+
* of #1805 each repaired one spelling of this parser that had been reasoned
|
|
441
|
+
* about rather than enumerated, and the enumeration immediately produced
|
|
442
|
+
* two things neither round had: `--allow-escape-sequences` was missing from
|
|
443
|
+
* this set, and `-f` is `--raw-field` while `-F` is `--field` — the
|
|
444
|
+
* opposite of what the round-1 comment said.
|
|
445
|
+
*
|
|
446
|
+
* Everything else beginning with `-` is assumed to take a value, which is
|
|
447
|
+
* the same conservative convention `BOOLEAN_FLAGS` follows above: guessing
|
|
448
|
+
* that a flag takes a value makes the scan skip a token it should have
|
|
449
|
+
* read, and the failure is a filing the gate does not recognise — visible.
|
|
450
|
+
* Guessing the other way desyncs the scan and makes a flag's VALUE read as
|
|
451
|
+
* the endpoint, which is a filing recognised against the wrong URL.
|
|
452
|
+
*/
|
|
453
|
+
export const API_BOOLEAN_FLAGS = new Set([
|
|
454
|
+
"--allow-escape-sequences",
|
|
455
|
+
"--paginate",
|
|
456
|
+
"-i",
|
|
457
|
+
"--include",
|
|
458
|
+
"--silent",
|
|
459
|
+
"--slurp",
|
|
460
|
+
"--verbose",
|
|
461
|
+
]);
|
|
462
|
+
|
|
463
|
+
/**
|
|
464
|
+
* Flags of `gh api` whose value is a `key=value` field.
|
|
465
|
+
*
|
|
466
|
+
* `-F`/`--field` is typed and `-f`/`--raw-field` is a string; the
|
|
467
|
+
* distinction does not matter to a gate reading titles. Both also accept
|
|
468
|
+
* `key=@path` and `key=@-` to take the value from a file or stdin — a
|
|
469
|
+
* DECLARED limit here: the key is seen, so the clause is still recognised
|
|
470
|
+
* as a filing, but the value resolves to the literal `@path` rather than
|
|
471
|
+
* the file's contents, so the dedupe compares a path. That is the safe
|
|
472
|
+
* direction — adjudicated, not missed — and it is written down rather than
|
|
473
|
+
* left for a sixth round to find.
|
|
474
|
+
*/
|
|
475
|
+
const API_FIELD_FLAGS = new Set(["--field", "-F", "--raw-field", "-f"]);
|
|
476
|
+
|
|
477
|
+
/** A `gh api` clause, read in one walk. */
|
|
478
|
+
export interface ApiCall {
|
|
479
|
+
/** The first positional token — the endpoint — or `null`. */
|
|
480
|
+
readonly endpoint: string | null;
|
|
481
|
+
/** `-X`/`--method`, upper-cased, or `null` when it was not given. */
|
|
482
|
+
readonly method: string | null;
|
|
483
|
+
/** Every `key=value` field, last on the LINE wins, as `gh` reads them. */
|
|
484
|
+
readonly fields: Map<string, string>;
|
|
485
|
+
/** Was a body supplied with `--input`? */
|
|
486
|
+
readonly hasInput: boolean;
|
|
487
|
+
}
|
|
488
|
+
|
|
489
|
+
/**
|
|
490
|
+
* ONE walk over a `gh api` clause's tokens.
|
|
491
|
+
*
|
|
492
|
+
* ai-review round 1 of #1805 raised four findings and all four were this
|
|
493
|
+
* function not existing. The first cut read the endpoint with its own loop
|
|
494
|
+
* and the method and fields with `flagValues`, which consults
|
|
495
|
+
* `BOOLEAN_FLAGS` — the set belonging to `gh issue create`. So
|
|
496
|
+
* `gh api --silent -f title=… repos/o/r/issues`, which files an issue,
|
|
497
|
+
* desynced: `--silent` was assumed to take a value, the scan skipped the
|
|
498
|
+
* `-f`, and the clause resolved to no fields and no method. Two scanners
|
|
499
|
+
* with two grammars over one command, and only one of them had been told
|
|
500
|
+
* which command it was reading.
|
|
501
|
+
*
|
|
502
|
+
* Reading the fields in one pass is also what makes *last wins* true. The
|
|
503
|
+
* first cut collected every `-f` and then every `-F`, so
|
|
504
|
+
* `-F title=A -f title=B` landed on `A` — the opposite of what `gh` sends.
|
|
505
|
+
*
|
|
506
|
+
* ## Two deliberate readings
|
|
507
|
+
*
|
|
508
|
+
* **`--` does not end the walk.** pflag treats it as end-of-options, so a
|
|
509
|
+
* real `gh` may well reject what follows; this skips it and keeps reading,
|
|
510
|
+
* which can only make a clause MORE likely to be seen as a filing. That is
|
|
511
|
+
* the safe direction for a gate, and `--` becoming the endpoint was a
|
|
512
|
+
* filing that walked straight through.
|
|
513
|
+
*
|
|
514
|
+
* **An unknown flag takes a value**, the same convention `BOOLEAN_FLAGS`
|
|
515
|
+
* follows: guessing that way costs a skipped token and an unrecognised
|
|
516
|
+
* filing, which is visible. Guessing the other way desyncs the scan and
|
|
517
|
+
* reads a flag's value as the endpoint — a filing recognised against the
|
|
518
|
+
* wrong URL, which is worse and quieter.
|
|
519
|
+
*/
|
|
520
|
+
export function apiCall(tokens: string[]): ApiCall | null {
|
|
521
|
+
const rest = afterGhSubcommand(tokens, "api");
|
|
522
|
+
if (rest === null) return null;
|
|
523
|
+
let endpoint: string | null = null;
|
|
524
|
+
let method: string | null = null;
|
|
525
|
+
let hasInput = false;
|
|
526
|
+
const fields = new Map<string, string>();
|
|
527
|
+
for (let i = 0; i < rest.length; i++) {
|
|
528
|
+
const t = rest[i];
|
|
529
|
+
if (t === "--") continue;
|
|
530
|
+
if (!t.startsWith("-") || t === "-") {
|
|
531
|
+
// Normalised HERE and nowhere else. Five consumers read this field;
|
|
532
|
+
// normalising at each of them is five chances to forget, and round 3
|
|
533
|
+
// of #1805 is what forgetting once costs.
|
|
534
|
+
if (endpoint === null) endpoint = barePath(t);
|
|
535
|
+
continue;
|
|
536
|
+
}
|
|
537
|
+
// **The attached short form is resolved BEFORE the `=` split, and the
|
|
538
|
+
// order is the whole of it.** `-ftitle=x` is one token whose value is
|
|
539
|
+
// itself a `key=value` pair, so splitting on the first `=` reads the
|
|
540
|
+
// flag as `-ftitle` and drops the field — and a field flag's value is
|
|
541
|
+
// ALWAYS a pair, so the one attached form that matters was the only
|
|
542
|
+
// one that could not work. ai-review round 2 of #1805; the round
|
|
543
|
+
// before it shipped this as a comment with no case behind it.
|
|
544
|
+
let name = t;
|
|
545
|
+
let value: string | null = null;
|
|
546
|
+
const attached = t.startsWith("--") ? null : /^-([A-Za-z])(.+)$/.exec(t);
|
|
547
|
+
if (attached !== null) {
|
|
548
|
+
name = `-${attached[1]}`;
|
|
549
|
+
value = attached[2];
|
|
550
|
+
} else {
|
|
551
|
+
const eq = t.indexOf("=");
|
|
552
|
+
if (eq !== -1) {
|
|
553
|
+
name = t.slice(0, eq);
|
|
554
|
+
value = t.slice(eq + 1);
|
|
555
|
+
}
|
|
556
|
+
}
|
|
557
|
+
if (value === null && !API_BOOLEAN_FLAGS.has(name) && i + 1 < rest.length) {
|
|
558
|
+
value = rest[++i];
|
|
559
|
+
}
|
|
560
|
+
if (name === "--input") hasInput = true;
|
|
561
|
+
else if (name === "-X" || name === "--method") {
|
|
562
|
+
if (value !== null) method = value.toUpperCase();
|
|
563
|
+
} else if (API_FIELD_FLAGS.has(name) && value !== null) {
|
|
564
|
+
const at = value.indexOf("=");
|
|
565
|
+
if (at > 0) fields.set(value.slice(0, at), value.slice(at + 1));
|
|
566
|
+
}
|
|
567
|
+
}
|
|
568
|
+
return { endpoint, method, fields, hasInput };
|
|
569
|
+
}
|
|
570
|
+
|
|
571
|
+
/** The REST issues COLLECTION — `repos/<owner>/<repo>/issues`, nothing deeper. */
|
|
572
|
+
const ISSUES_COLLECTION = /^\/?repos\/([^/?]+)\/([^/?]+)\/issues\/?(?:\?.*)?$/;
|
|
573
|
+
|
|
574
|
+
/**
|
|
575
|
+
* An endpoint as a bare path, whichever way it was written.
|
|
576
|
+
*
|
|
577
|
+
* `gh api` takes a fully-qualified URL as well as a path — it is how a
|
|
578
|
+
* Link-header pagination URL is replayed and how a GitHub Enterprise host
|
|
579
|
+
* is addressed — and posts it exactly the same way. ai-review round 3 of
|
|
580
|
+
* #1805: `https://api.github.com/repos/o/r/issues` matched neither the
|
|
581
|
+
* collection regex nor `graphql`, so a filing spelled that way walked
|
|
582
|
+
* around a gate that had just been widened twice.
|
|
583
|
+
*
|
|
584
|
+
* The `/api/v3` and `/api` prefixes are GHES's REST and GraphQL mounts.
|
|
585
|
+
* Stripping them makes the two hosts one shape, which is the point: a
|
|
586
|
+
* second regex per host is a second decider.
|
|
587
|
+
*/
|
|
588
|
+
function barePath(endpoint: string): string {
|
|
589
|
+
const withoutHost = endpoint.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, "");
|
|
590
|
+
return withoutHost.replace(/^\/api(?:\/v3)?\//, "/").replace(/^\//, "");
|
|
591
|
+
}
|
|
592
|
+
|
|
593
|
+
/**
|
|
594
|
+
* The `owner/repo` a `gh api` filing targets, or `null`.
|
|
595
|
+
*
|
|
596
|
+
* The REST path carries it; a GraphQL `createIssue` carries a
|
|
597
|
+
* `repositoryId`, which is an opaque node id and not a slug, so that one is
|
|
598
|
+
* honestly `null` rather than guessed at. `null` means the dedupe runs
|
|
599
|
+
* against the session's default repo, which is the existing behaviour for
|
|
600
|
+
* a `gh issue create` with no `--repo`.
|
|
601
|
+
*/
|
|
602
|
+
export function apiFilingRepo(tokens: string[]): string | null {
|
|
603
|
+
const call = apiCall(tokens);
|
|
604
|
+
const m = call === null ? null : ISSUES_COLLECTION.exec(call.endpoint ?? "");
|
|
605
|
+
return m === null ? null : `${m[1]}/${m[2]}`;
|
|
606
|
+
}
|
|
607
|
+
|
|
608
|
+
/**
|
|
609
|
+
* The fields of a REST issues-collection filing, or `null`.
|
|
610
|
+
*
|
|
611
|
+
* `null` for every clause that is not one — including `graphql`, which has
|
|
612
|
+
* its own reader — so a caller gets a map only when the map means what it
|
|
613
|
+
* thinks it means.
|
|
614
|
+
*/
|
|
615
|
+
export function apiRestFields(tokens: string[]): Map<string, string> | null {
|
|
616
|
+
const call = apiCall(tokens);
|
|
617
|
+
if (call === null || !ISSUES_COLLECTION.test(call.endpoint ?? "")) return null;
|
|
618
|
+
return call.fields;
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
/**
|
|
622
|
+
* The GraphQL `query` variables this clause passes, or `null`.
|
|
623
|
+
*
|
|
624
|
+
* `gh api graphql -f query='mutation($title: String!){…}' -f title="…"` is
|
|
625
|
+
* the form `gh`'s own documentation recommends, because it avoids escaping
|
|
626
|
+
* quotes by hand. ai-review round 1 of #1805: the first cut read literals
|
|
627
|
+
* out of the document only, so the idiomatic spelling resolved to an empty
|
|
628
|
+
* title and an empty body — counted as a filing and compared against
|
|
629
|
+
* nothing, which is the one outcome worse than not counting it.
|
|
630
|
+
*/
|
|
631
|
+
export function graphqlVariables(tokens: string[]): Map<string, string> | null {
|
|
632
|
+
const call = apiCall(tokens);
|
|
633
|
+
if (call === null || call.endpoint !== "graphql") return null;
|
|
634
|
+
return call.fields;
|
|
635
|
+
}
|
|
636
|
+
|
|
637
|
+
/** The tokens after `gh <sub>`, or `null` when this clause is not that. */
|
|
638
|
+
function afterGhSubcommand(tokens: string[], sub: string): string[] | null {
|
|
639
|
+
for (let i = 0; i + 1 < tokens.length; i++) {
|
|
640
|
+
if (basename(tokens[i]) === "gh" && tokens[i + 1] === sub) return tokens.slice(i + 2);
|
|
641
|
+
}
|
|
642
|
+
return null;
|
|
643
|
+
}
|
|
644
|
+
|
|
645
|
+
/** A `mutation { … createIssue( … ) … }` in a GraphQL document. */
|
|
646
|
+
const CREATE_ISSUE_MUTATION = /\bmutation\b[\s\S]*\bcreateIssue\s*\(/;
|
|
647
|
+
|
|
648
|
+
/**
|
|
649
|
+
* The GraphQL document this clause sends, or `null`.
|
|
650
|
+
*
|
|
651
|
+
* `gh api graphql` takes it as the `query` field whichever field flag
|
|
652
|
+
* spells it.
|
|
653
|
+
*/
|
|
654
|
+
export function graphqlDocument(tokens: string[]): string | null {
|
|
655
|
+
return graphqlVariables(tokens)?.get("query") ?? null;
|
|
656
|
+
}
|
|
657
|
+
|
|
658
|
+
/**
|
|
659
|
+
* Does this clause create an issue?
|
|
660
|
+
*
|
|
661
|
+
* Three spellings, one decider (#1759). Measured on 2026-11-02, the first
|
|
662
|
+
* two of these returned nothing: `gh api repos/<o>/<r>/issues` and a
|
|
663
|
+
* `createIssue` GraphQL mutation both file an issue and neither is spelled
|
|
664
|
+
* `gh issue create`, so two of three filings walked around the gate that
|
|
665
|
+
* exists to count them.
|
|
282
666
|
*
|
|
283
667
|
* Compared on the basename, because `/usr/bin/gh issue create` and
|
|
284
668
|
* `./gh issue create` are the same command and the first version of this
|
|
285
669
|
* function allowed both.
|
|
670
|
+
*
|
|
671
|
+
* ## Reading is not filing, and that is the hard half
|
|
672
|
+
*
|
|
673
|
+
* `repos/<o>/<r>/issues` is the LIST endpoint as well as the create
|
|
674
|
+
* endpoint; the method is what separates them, and `gh api` chooses POST
|
|
675
|
+
* implicitly when any field is supplied. So a create is *fields present or
|
|
676
|
+
* POST asked for*, and an explicit `GET`/`HEAD` is a read whatever else is
|
|
677
|
+
* on the line.
|
|
678
|
+
*
|
|
679
|
+
* The regex stops at the collection — `issues/1759/comments` is deeper and
|
|
680
|
+
* is not a filing. That boundary is load-bearing rather than tidy: this
|
|
681
|
+
* gate's own refusals tell an agent to post a comment instead, so a parser
|
|
682
|
+
* that read any `gh api` touching `issues` would refuse the remedy it
|
|
683
|
+
* prescribes.
|
|
286
684
|
*/
|
|
287
685
|
export function createsIssue(tokens: string[]): boolean {
|
|
288
686
|
for (let i = 0; i + 2 < tokens.length; i++) {
|
|
@@ -290,7 +688,21 @@ export function createsIssue(tokens: string[]): boolean {
|
|
|
290
688
|
return true;
|
|
291
689
|
}
|
|
292
690
|
}
|
|
293
|
-
|
|
691
|
+
const call = apiCall(tokens);
|
|
692
|
+
if (call === null) return false;
|
|
693
|
+
const { endpoint, method, fields, hasInput } = call;
|
|
694
|
+
if (method === "GET" || method === "HEAD") return false;
|
|
695
|
+
if (endpoint === "graphql") {
|
|
696
|
+
// `--input` puts the document in a file, or on stdin, and this does
|
|
697
|
+
// not read it. A document nobody read is UNMEASURED, not absent, and
|
|
698
|
+
// UNMEASURED adjudicates — the same reading the REST arm below already
|
|
699
|
+
// takes of the same flag. ai-review round 3 of #1805 found the two
|
|
700
|
+
// arms disagreeing about one flag, which is the only fact that makes
|
|
701
|
+
// either of them wrong.
|
|
702
|
+
return hasInput || CREATE_ISSUE_MUTATION.test(fields.get("query") ?? "");
|
|
703
|
+
}
|
|
704
|
+
if (!ISSUES_COLLECTION.test(endpoint ?? "")) return false;
|
|
705
|
+
return fields.size > 0 || hasInput || method === "POST";
|
|
294
706
|
}
|
|
295
707
|
|
|
296
708
|
/**
|
|
@@ -496,6 +496,22 @@ export function planDecomposition(
|
|
|
496
496
|
* spelling of, so one reader finds both a created issue and a repaired one.
|
|
497
497
|
* The files are listed because rule 2 is about the issue, not about the plan:
|
|
498
498
|
* an issue whose file list lives only in a plan file is one nobody can check.
|
|
499
|
+
*
|
|
500
|
+
* ## #1741 — this is a CONSUMER of `lib/issue-shape.ts`, not a second opinion
|
|
501
|
+
*
|
|
502
|
+
* It used to emit two of the form's five fields under headings of its own
|
|
503
|
+
* choosing (`## Criterion` for what the form calls *What must become true*,
|
|
504
|
+
* and no proof section at all), which is exactly why the filing gate could
|
|
505
|
+
* not require the form's fields: doing so would have refused every row of
|
|
506
|
+
* every plan. `test/issue-shape.test.ts` now binds the headings here to
|
|
507
|
+
* `requiredSections("spec-work")` by EQUALITY in both directions, so this
|
|
508
|
+
* generator cannot drift from the form and the form cannot drift from it.
|
|
509
|
+
*
|
|
510
|
+
* **The proof section is derived, not a placeholder.** Every decomposed row
|
|
511
|
+
* has exactly one honest answer to *how we will know* — a test naming the
|
|
512
|
+
* criterion id, which is AGENTS.md rule 6 — and it names `row.criterion`, so
|
|
513
|
+
* a row that lost its criterion produces a body that says so rather than a
|
|
514
|
+
* body carrying a sentence true of anything.
|
|
499
515
|
*/
|
|
500
516
|
export function decomposedBody(
|
|
501
517
|
row: DecompositionRow,
|
|
@@ -503,17 +519,31 @@ export function decomposedBody(
|
|
|
503
519
|
planPath: string,
|
|
504
520
|
): string {
|
|
505
521
|
return [
|
|
506
|
-
`##
|
|
522
|
+
`## What must become true`,
|
|
507
523
|
``,
|
|
508
524
|
`${row.outcome}`,
|
|
509
525
|
``,
|
|
526
|
+
// Criteria BEFORE files, which is the order `ISSUE_SECTIONS` declares
|
|
527
|
+
// and the order both forms show. It used to be the other way round, and
|
|
528
|
+
// `lib/issue-shape.ts`'s docblock claimed the order was load-bearing
|
|
529
|
+
// here while the two disagreed — caught by review. `IS-30` now asserts
|
|
530
|
+
// the ORDER and not just the set, so the claim is tested rather than
|
|
531
|
+
// written down.
|
|
532
|
+
criteriaHeading,
|
|
533
|
+
``,
|
|
534
|
+
row.criterion,
|
|
535
|
+
``,
|
|
510
536
|
`## Files this will change`,
|
|
511
537
|
``,
|
|
512
538
|
...row.files.map(f => `- \`${f}\``),
|
|
513
539
|
``,
|
|
514
|
-
|
|
540
|
+
`## How we will know`,
|
|
515
541
|
``,
|
|
516
|
-
row.criterion,
|
|
542
|
+
`A test names \`${row.criterion}\` in a declaring position, and`,
|
|
543
|
+
`\`bun scripts/sync-sc-status.ts\` ticks the criterion from that claim.`,
|
|
544
|
+
`The tick comes from the test, never from closing this issue — AGENTS.md`,
|
|
545
|
+
`rule 6, and \`.claude/rules/claiming-sc-coverage.md\` for what counts as`,
|
|
546
|
+
`a claim rather than a citation.`,
|
|
517
547
|
``,
|
|
518
548
|
`---`,
|
|
519
549
|
``,
|