rungate 0.8.13 → 0.8.16
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 +182 -0
- package/gates/.gate-salt +1 -1
- package/hooks/HarnessAFKGate.hook.ts +5 -1
- package/hooks/HookCurrency.hook.ts +11 -8
- package/hooks/MergeGuard.hook.ts +7 -1
- package/hooks/StaleTTLCleanup.hook.ts +4 -4
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/hooks/lib/findWorkflow.ts +3 -2
- package/hooks/lib/paths.ts +14 -2
- package/hooks/lib/utils.ts +23 -3
- package/lib/active-milestone.ts +50 -0
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +397 -23
- package/lib/board-flow.ts +280 -0
- package/lib/board-lane-health.ts +578 -0
- package/lib/board-mirror.ts +136 -39
- package/lib/board-ready-fanout.ts +297 -14
- package/lib/board-ready-rule.ts +1211 -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/bun-version.ts +36 -0
- package/lib/cli-commands.ts +75 -4
- package/lib/closing-reference-audit.ts +307 -6
- package/lib/config-loader.ts +254 -25
- package/lib/config-readers.ts +170 -10
- package/lib/config-trackable.ts +96 -57
- package/lib/conformity.ts +121 -7
- package/lib/create-sc.ts +25 -2
- package/lib/derived-spec.ts +21 -9
- package/lib/filing-compliance.ts +367 -0
- package/lib/filing-plan.ts +47 -21
- package/lib/finding-arbiter.ts +79 -5
- package/lib/finding-jury.ts +43 -4
- package/lib/finding-promotion.ts +1123 -0
- package/lib/generators/agents-md.ts +149 -0
- package/lib/git-isolation.ts +137 -1
- package/lib/github-api-base.ts +66 -0
- package/lib/github.ts +194 -9
- package/lib/graphql-cursor.ts +80 -0
- package/lib/hook-scopes.ts +78 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +124 -7
- package/lib/issue-extraction.ts +9 -7
- package/lib/issue-file-overlap.ts +373 -0
- package/lib/issue-filing-gate.ts +1109 -52
- package/lib/issue-repair.ts +90 -9
- package/lib/issue-shape.ts +199 -0
- package/lib/live-issues.ts +31 -2
- package/lib/local-work.ts +423 -0
- package/lib/markdown-fence.ts +134 -0
- package/lib/milestone-title.ts +46 -0
- package/lib/scaffold/ai-review-findings.ts +148 -3
- package/lib/scaffold/ai-review-step.ts +65 -5
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
- package/lib/scaffold/steps.ts +115 -9
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +55 -11
- package/lib/spec-placement.ts +203 -13
- package/lib/spec-registry.ts +75 -16
- package/lib/spec-source.ts +609 -0
- package/lib/spec-write-sweep.ts +4 -0
- package/lib/stage-ladder.ts +896 -3
- package/lib/state-claim-readings.ts +252 -0
- package/lib/success-doc.ts +7 -6
- package/lib/test-command-positions.ts +135 -1
- package/lib/work-status.ts +551 -0
- package/lib/worktree-repo.ts +14 -2
- package/package.json +7 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/audit-closing-references.ts +330 -0
- package/scripts/audit-specs.ts +59 -103
- package/scripts/board-conformance.ts +747 -40
- package/scripts/board-mirror.ts +594 -13
- package/scripts/board-ready.ts +979 -0
- package/scripts/board-snapshot.ts +464 -12
- package/scripts/claim-files.ts +578 -0
- package/scripts/criterion-inventory.ts +526 -50
- package/scripts/finding-promotion.ts +547 -0
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-issues.ts +279 -40
- package/scripts/plan-spec.ts +105 -3
- package/scripts/sync-sc-status.ts +147 -7
- package/scripts/worktree-census.ts +958 -0
- package/scripts/worktree-sweep.ts +269 -0
|
@@ -402,15 +402,21 @@ export function parseDecompositionPlan(content: string): DecompositionReading {
|
|
|
402
402
|
export interface LiveTracker {
|
|
403
403
|
/** Title → number, for every OPEN issue. The idempotence key. */
|
|
404
404
|
openTitles: Map<string, number>;
|
|
405
|
+
/** Title → number, for every CLOSED issue. A row matching one is done, never re-filed (SC-2738). */
|
|
406
|
+
closedTitles: Map<string, number>;
|
|
405
407
|
/** Milestone titles that exist. A plan naming one that does not is refused. */
|
|
406
408
|
milestones: Set<string>;
|
|
409
|
+
/** Every criterion id a spec under `specs/` states. A row naming any other is refused (SC-2738). */
|
|
410
|
+
statedCriteria: ReadonlySet<string>;
|
|
407
411
|
}
|
|
408
412
|
|
|
409
413
|
export type DecomposeAction =
|
|
410
414
|
/** Nothing on the tracker has this title; create it. */
|
|
411
415
|
| { kind: "create"; row: DecompositionRow; title: string; body: string }
|
|
412
416
|
/** An open issue already has this exact title. Re-runs land here. */
|
|
413
|
-
| { kind: "exists"; row: DecompositionRow; number: number }
|
|
417
|
+
| { kind: "exists"; row: DecompositionRow; number: number }
|
|
418
|
+
/** Only a CLOSED issue has this title: the work is done, so nothing is filed. */
|
|
419
|
+
| { kind: "closed"; row: DecompositionRow; number: number };
|
|
414
420
|
|
|
415
421
|
export interface DecompositionPlan {
|
|
416
422
|
/** UNMEASURED means apply NOTHING — not "apply the readable part". */
|
|
@@ -437,9 +443,24 @@ export interface DecompositionPlan {
|
|
|
437
443
|
* would authorise every one of them, because the plan still names them.
|
|
438
444
|
*
|
|
439
445
|
* The match is exact, for the reason `lib/filing-plan.ts` gives about
|
|
440
|
-
* substrings.
|
|
441
|
-
*
|
|
442
|
-
*
|
|
446
|
+
* substrings.
|
|
447
|
+
*
|
|
448
|
+
* ## A closed issue counts too (SC-2738)
|
|
449
|
+
*
|
|
450
|
+
* This used to read open titles only, on the reasoning that a duplicate
|
|
451
|
+
* somebody can close beats refusing to file. That held while a person read
|
|
452
|
+
* every dry run. ADR-013's first dry run proposed re-creating three rows whose
|
|
453
|
+
* issues had already closed, and once a merge runs this with nobody watching
|
|
454
|
+
* (`.github/workflows/adr-accepted.yml`) that proposal is a duplicate filed
|
|
455
|
+
* for real. So a row whose title only a closed issue holds is `closed`: not
|
|
456
|
+
* filed, and its number still resolves the rows blocked by it. An open issue
|
|
457
|
+
* with the same title wins, because that is the live one.
|
|
458
|
+
*
|
|
459
|
+
* ## A criterion no spec states is refused (SC-2738)
|
|
460
|
+
*
|
|
461
|
+
* The parser checks an id's shape and nothing else, so a transposed digit
|
|
462
|
+
* filed an issue serving a criterion that does not exist, and no test could
|
|
463
|
+
* ever tick it.
|
|
443
464
|
*/
|
|
444
465
|
export function planDecomposition(
|
|
445
466
|
rows: readonly DecompositionRow[],
|
|
@@ -461,6 +482,15 @@ export function planDecomposition(
|
|
|
461
482
|
}
|
|
462
483
|
}
|
|
463
484
|
|
|
485
|
+
for (const r of rows) {
|
|
486
|
+
if (!live.statedCriteria.has(r.criterion)) {
|
|
487
|
+
reasons.push(
|
|
488
|
+
`line ${r.line}: criterion "${r.criterion}" is stated in no spec under specs/ — ` +
|
|
489
|
+
`write it as a \`- [ ] ${r.criterion}: …\` line in the governing spec first, or correct the row`,
|
|
490
|
+
);
|
|
491
|
+
}
|
|
492
|
+
}
|
|
493
|
+
|
|
464
494
|
const actions: DecomposeAction[] = [];
|
|
465
495
|
for (const r of rows) {
|
|
466
496
|
const existing = live.openTitles.get(r.outcome);
|
|
@@ -468,6 +498,11 @@ export function planDecomposition(
|
|
|
468
498
|
actions.push({ kind: "exists", row: r, number: existing });
|
|
469
499
|
continue;
|
|
470
500
|
}
|
|
501
|
+
const closed = live.closedTitles.get(r.outcome);
|
|
502
|
+
if (closed !== undefined) {
|
|
503
|
+
actions.push({ kind: "closed", row: r, number: closed });
|
|
504
|
+
continue;
|
|
505
|
+
}
|
|
471
506
|
actions.push({
|
|
472
507
|
kind: "create",
|
|
473
508
|
row: r,
|
|
@@ -496,6 +531,22 @@ export function planDecomposition(
|
|
|
496
531
|
* spelling of, so one reader finds both a created issue and a repaired one.
|
|
497
532
|
* The files are listed because rule 2 is about the issue, not about the plan:
|
|
498
533
|
* an issue whose file list lives only in a plan file is one nobody can check.
|
|
534
|
+
*
|
|
535
|
+
* ## #1741 — this is a CONSUMER of `lib/issue-shape.ts`, not a second opinion
|
|
536
|
+
*
|
|
537
|
+
* It used to emit two of the form's five fields under headings of its own
|
|
538
|
+
* choosing (`## Criterion` for what the form calls *What must become true*,
|
|
539
|
+
* and no proof section at all), which is exactly why the filing gate could
|
|
540
|
+
* not require the form's fields: doing so would have refused every row of
|
|
541
|
+
* every plan. `test/issue-shape.test.ts` now binds the headings here to
|
|
542
|
+
* `requiredSections("spec-work")` by EQUALITY in both directions, so this
|
|
543
|
+
* generator cannot drift from the form and the form cannot drift from it.
|
|
544
|
+
*
|
|
545
|
+
* **The proof section is derived, not a placeholder.** Every decomposed row
|
|
546
|
+
* has exactly one honest answer to *how we will know* — a test naming the
|
|
547
|
+
* criterion id, which is AGENTS.md rule 6 — and it names `row.criterion`, so
|
|
548
|
+
* a row that lost its criterion produces a body that says so rather than a
|
|
549
|
+
* body carrying a sentence true of anything.
|
|
499
550
|
*/
|
|
500
551
|
export function decomposedBody(
|
|
501
552
|
row: DecompositionRow,
|
|
@@ -503,17 +554,31 @@ export function decomposedBody(
|
|
|
503
554
|
planPath: string,
|
|
504
555
|
): string {
|
|
505
556
|
return [
|
|
506
|
-
`##
|
|
557
|
+
`## What must become true`,
|
|
507
558
|
``,
|
|
508
559
|
`${row.outcome}`,
|
|
509
560
|
``,
|
|
561
|
+
// Criteria BEFORE files, which is the order `ISSUE_SECTIONS` declares
|
|
562
|
+
// and the order both forms show. It used to be the other way round, and
|
|
563
|
+
// `lib/issue-shape.ts`'s docblock claimed the order was load-bearing
|
|
564
|
+
// here while the two disagreed — caught by review. `IS-30` now asserts
|
|
565
|
+
// the ORDER and not just the set, so the claim is tested rather than
|
|
566
|
+
// written down.
|
|
567
|
+
criteriaHeading,
|
|
568
|
+
``,
|
|
569
|
+
row.criterion,
|
|
570
|
+
``,
|
|
510
571
|
`## Files this will change`,
|
|
511
572
|
``,
|
|
512
573
|
...row.files.map(f => `- \`${f}\``),
|
|
513
574
|
``,
|
|
514
|
-
|
|
575
|
+
`## How we will know`,
|
|
515
576
|
``,
|
|
516
|
-
row.criterion,
|
|
577
|
+
`A test names \`${row.criterion}\` in a declaring position, and`,
|
|
578
|
+
`\`bun scripts/sync-sc-status.ts\` ticks the criterion from that claim.`,
|
|
579
|
+
`The tick comes from the test, never from closing this issue — AGENTS.md`,
|
|
580
|
+
`rule 6, and \`.claude/rules/claiming-sc-coverage.md\` for what counts as`,
|
|
581
|
+
`a claim rather than a citation.`,
|
|
517
582
|
``,
|
|
518
583
|
`---`,
|
|
519
584
|
``,
|
|
@@ -521,3 +586,55 @@ export function decomposedBody(
|
|
|
521
586
|
`The plan is the record of why this is one issue and not two.`,
|
|
522
587
|
].join("\n");
|
|
523
588
|
}
|
|
589
|
+
|
|
590
|
+
/**
|
|
591
|
+
* The `status:` an ADR's FRONTMATTER declares, or `null` when it has none.
|
|
592
|
+
*
|
|
593
|
+
* Only the frontmatter: an ADR's body quotes statuses freely ("revision 2 was
|
|
594
|
+
* accepted"), and a body line must not be able to file a plan.
|
|
595
|
+
*/
|
|
596
|
+
export function adrStatus(text: string): string | null {
|
|
597
|
+
const lines = text.split("\n");
|
|
598
|
+
if (lines[0]?.trim() !== "---") return null;
|
|
599
|
+
for (let i = 1; i < lines.length; i++) {
|
|
600
|
+
const line = lines[i]!;
|
|
601
|
+
if (line.trim() === "---") return null;
|
|
602
|
+
// Quotes and case are YAML spelling, not a different status: `"accepted"`
|
|
603
|
+
// and `Accepted` were read as not-accepted and the plan was silently
|
|
604
|
+
// never placed (security review of #2009).
|
|
605
|
+
const m = /^status:\s*(.*?)\s*$/.exec(line);
|
|
606
|
+
if (m) return m[1]!.replace(/^(["'])(.*)\1$/, "$2").trim().toLowerCase();
|
|
607
|
+
}
|
|
608
|
+
return null;
|
|
609
|
+
}
|
|
610
|
+
|
|
611
|
+
/**
|
|
612
|
+
* Did this change ACCEPT the ADR? True only when it is `accepted` now and was
|
|
613
|
+
* not before — `before` is `null` for a file the earlier commit did not have.
|
|
614
|
+
* An edit to an ADR that was already accepted is not an acceptance, so it
|
|
615
|
+
* re-runs nothing (SC-2738).
|
|
616
|
+
*/
|
|
617
|
+
export function newlyAccepted(before: string | null, after: string): boolean {
|
|
618
|
+
return adrStatus(after) === "accepted" && (before === null || adrStatus(before) !== "accepted");
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
/** The author associations whose closed issue may stand for a plan's row. */
|
|
622
|
+
export const TRUSTED_AUTHORS: readonly string[] = ["OWNER", "MEMBER", "COLLABORATOR"];
|
|
623
|
+
|
|
624
|
+
/**
|
|
625
|
+
* May this CLOSED issue stand for a plan row with the same title? (SC-2738)
|
|
626
|
+
*
|
|
627
|
+
* Only finished work by somebody who can merge. Security review of #2009: on a
|
|
628
|
+
* public repository anyone can open an issue titled with a row's outcome
|
|
629
|
+
* (copied from the open ADR pull request) and close it themselves; read as
|
|
630
|
+
* done, the row is never filed and its dependents point at the stranger's
|
|
631
|
+
* issue. A close as "not planned" or "duplicate" is not finished work either.
|
|
632
|
+
*/
|
|
633
|
+
export function closedIssueCounts(issue: { state_reason: string | null; author_association: string }): boolean {
|
|
634
|
+
return issue.state_reason === "completed" && TRUSTED_AUTHORS.includes(issue.author_association);
|
|
635
|
+
}
|
|
636
|
+
|
|
637
|
+
/** Whether a document carries a Decomposition table for `--decompose` to read. */
|
|
638
|
+
export function hasDecompositionTable(text: string): boolean {
|
|
639
|
+
return /^\|\s*Criterion\s*\|\s*Outcome\s*\|/m.test(text);
|
|
640
|
+
}
|
package/lib/issue-extraction.ts
CHANGED
|
@@ -36,6 +36,8 @@
|
|
|
36
36
|
* documentation is briefed to an agent as a thing to build.
|
|
37
37
|
*/
|
|
38
38
|
|
|
39
|
+
import { closesFence, fenceOpening, type FenceOpening } from "./markdown-fence";
|
|
40
|
+
|
|
39
41
|
/**
|
|
40
42
|
* Markers that identify a blockquote as harness-authored metadata rather than
|
|
41
43
|
* the author's prose.
|
|
@@ -129,22 +131,22 @@ export interface CriteriaReading {
|
|
|
129
131
|
export function stripCodeBlocks(body: string): string {
|
|
130
132
|
const lines = String(body ?? "").split("\n");
|
|
131
133
|
const out: string[] = [];
|
|
132
|
-
let fence:
|
|
134
|
+
let fence: FenceOpening | null = null;
|
|
133
135
|
let inList = false;
|
|
134
136
|
|
|
135
137
|
for (const line of lines) {
|
|
136
138
|
if (fence !== null) {
|
|
137
139
|
// A closing fence is the same character, at least as long, alone on its
|
|
138
|
-
// line. Anything else is
|
|
139
|
-
|
|
140
|
+
// line — `lib/markdown-fence.ts`'s rule (#2135). Anything else is
|
|
141
|
+
// content. Three spaces at most, because four is indented code here.
|
|
140
142
|
out.push("");
|
|
141
|
-
if (
|
|
143
|
+
if ((fenceOpening(line)?.indent ?? 4) <= 3 && closesFence(line, fence)) fence = null;
|
|
142
144
|
continue;
|
|
143
145
|
}
|
|
144
146
|
|
|
145
|
-
const open = line
|
|
146
|
-
if (open) {
|
|
147
|
-
fence = open
|
|
147
|
+
const open = fenceOpening(line);
|
|
148
|
+
if (open !== null && open.indent <= 3) {
|
|
149
|
+
fence = open;
|
|
148
150
|
out.push("");
|
|
149
151
|
continue;
|
|
150
152
|
}
|
|
@@ -0,0 +1,373 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* #1743 — two issues editing the same file both sit in the pickable set with
|
|
3
|
+
* nothing saying so.
|
|
4
|
+
*
|
|
5
|
+
* ## The measurement
|
|
6
|
+
*
|
|
7
|
+
* Over the 20 open issues carrying no milestone on 2026-11-03: 16 declare at
|
|
8
|
+
* least one file, and there are 10 overlapping pairs — among them a cluster of
|
|
9
|
+
* four, #1407, #1425, #1585 and #1355, all rewriting one file. Hand four
|
|
10
|
+
* agents the unblocked, unassigned set and four of them collide. Rule 2 in
|
|
11
|
+
* `AGENTS.md` already makes every issue name its files; nothing reads them.
|
|
12
|
+
*
|
|
13
|
+
* ## A conflict is not a dependency, and the edge is a borrowed primitive
|
|
14
|
+
*
|
|
15
|
+
* 20 of the 23 milestone-less issues are genuinely unblocked, and inventing an
|
|
16
|
+
* ordering for them would make the board lie about what is pickable — which is
|
|
17
|
+
* exactly why `lib/issue-shape.ts` leaves the *Blocked by* field optional. What
|
|
18
|
+
* these issues have is a file conflict. `blocked by` is the output only because
|
|
19
|
+
* it is the one primitive GitHub gives us for *not these two at once*, and the
|
|
20
|
+
* note this file composes says so in words rather than filing the edge itself.
|
|
21
|
+
*
|
|
22
|
+
* **Nothing here blocks a filing.** The gate appends a note; a human or an
|
|
23
|
+
* agent decides. A warning that refused would turn every second issue about a
|
|
24
|
+
* busy file into an argument with a tool.
|
|
25
|
+
*
|
|
26
|
+
* ## Where the heading comes from
|
|
27
|
+
*
|
|
28
|
+
* `lib/issue-shape.ts`, and nowhere else. Spelling the file-list heading here
|
|
29
|
+
* as well would be *two deciders that agree* from
|
|
30
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`: a mutation of either would
|
|
31
|
+
* leave the other holding every case up, and both would read as covered.
|
|
32
|
+
* `FO-10` in `test/issue-file-overlap.test.ts` asserts the string is absent
|
|
33
|
+
* from this source.
|
|
34
|
+
*/
|
|
35
|
+
|
|
36
|
+
import { ISSUE_SECTIONS, headingFor, headingOccurrencesOf } from "./issue-shape";
|
|
37
|
+
import { readFences } from "./markdown-fence";
|
|
38
|
+
|
|
39
|
+
/** An issue reduced to the thing this file reasons about. */
|
|
40
|
+
export interface IssueFiles {
|
|
41
|
+
readonly id: number;
|
|
42
|
+
readonly files: readonly string[];
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** One file, and the open issues contending for it. */
|
|
46
|
+
export interface FileContention {
|
|
47
|
+
/** The path they all declare. */
|
|
48
|
+
readonly file: string;
|
|
49
|
+
/** The issue to do FIRST. Lowest number, so a re-run names the same one. */
|
|
50
|
+
readonly lead: number;
|
|
51
|
+
/** The rest, ascending — the ones a `blocked by` edge would point at. */
|
|
52
|
+
readonly blocked: readonly number[];
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
const FILES_SECTION = ISSUE_SECTIONS.find(s => s.id === "files");
|
|
56
|
+
|
|
57
|
+
if (FILES_SECTION === undefined) {
|
|
58
|
+
// Loud at import rather than an empty reading at call time. A section id the
|
|
59
|
+
// decider no longer knows is a decision somebody made; it must not surface
|
|
60
|
+
// as "no issue declares any file", which is indistinguishable from a quiet
|
|
61
|
+
// board.
|
|
62
|
+
throw new Error("lib/issue-file-overlap.ts: lib/issue-shape.ts declares no `files` section");
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const FILES_HEADING = headingFor(FILES_SECTION);
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* The paths an issue body declares, in the order it declares them.
|
|
69
|
+
*
|
|
70
|
+
* Reads ONLY the section the decider names, and stops at the next heading: the
|
|
71
|
+
* sections either side are prose about the change, and a census that runs past
|
|
72
|
+
* its own boundary grows a population nobody declared.
|
|
73
|
+
*
|
|
74
|
+
* **The direction this is allowed to be wrong in is toward reading FEWER
|
|
75
|
+
* files.** A path it misses costs a warning nobody gets. A path it invents —
|
|
76
|
+
* a word out of a sentence — costs a collision report against a file that does
|
|
77
|
+
* not exist, which is how a warning channel becomes noise people skip. So a
|
|
78
|
+
* candidate must be a single word that looks like a path.
|
|
79
|
+
*/
|
|
80
|
+
export function declaredFiles(body: string): string[] {
|
|
81
|
+
const out: string[] = [];
|
|
82
|
+
for (const line of filesSectionLines(body)) {
|
|
83
|
+
for (const path of pathsOnLine(line)) if (!out.includes(path)) out.push(path);
|
|
84
|
+
}
|
|
85
|
+
return out;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** The lines under the file-list heading, outside any fenced block. */
|
|
89
|
+
function filesSectionLines(body: string): string[] {
|
|
90
|
+
const at = headingOccurrencesOf(body, FILES_HEADING)[0];
|
|
91
|
+
if (at === undefined) return [];
|
|
92
|
+
|
|
93
|
+
// Read over the whole body, so the heading line's own index is where the
|
|
94
|
+
// section starts; `~~~` fences too (#2130).
|
|
95
|
+
const lines = body.split("\n");
|
|
96
|
+
const { roles } = readFences(lines);
|
|
97
|
+
const headingLine = body.slice(0, at).split("\n").length - 1;
|
|
98
|
+
const out: string[] = [];
|
|
99
|
+
for (let i = headingLine + 1; i < lines.length; i++) {
|
|
100
|
+
if (roles[i] !== "prose") continue;
|
|
101
|
+
if (/^#{1,6}\s+\S/.test(lines[i]!)) break; // the next section
|
|
102
|
+
out.push(lines[i]!);
|
|
103
|
+
}
|
|
104
|
+
return out;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* The path a list line names, or null when the line is prose.
|
|
109
|
+
*
|
|
110
|
+
* A path is **a single word containing a `/` and ending in an alphabetic
|
|
111
|
+
* extension of two to five characters**, and every backticked span on the line
|
|
112
|
+
* is offered to that rule rather than only the first.
|
|
113
|
+
*
|
|
114
|
+
* ## The separator is there because four rounds of review said so
|
|
115
|
+
*
|
|
116
|
+
* Three of this PR's five review rounds asked one question — *which token is a
|
|
117
|
+
* path* — and each found a token the then-current rule let through:
|
|
118
|
+
*
|
|
119
|
+
* | round | token | what was admitting it |
|
|
120
|
+
* |---|---|---|
|
|
121
|
+
* | 1 | `2.0`, `v2.1`, `i.e` | any dotted word counted |
|
|
122
|
+
* | 2 | `N/A` | a `/` alone counted, with nothing else checked |
|
|
123
|
+
* | 4 | `Node.js`, `GitHub.com` | an extension alone counted |
|
|
124
|
+
*
|
|
125
|
+
* Round 2's `N/A` was the costly one: the files section is REQUIRED and
|
|
126
|
+
* `missingSections` demands content under the heading, so *N/A* is exactly
|
|
127
|
+
* what somebody writes when they have nothing to put there, and every issue
|
|
128
|
+
* that wrote it collided with every other one.
|
|
129
|
+
*
|
|
130
|
+
* Rounds 1 and 2 were repaired by widening and narrowing one predicate, and
|
|
131
|
+
* round 4 arrived on the half the last repair had loosened. `AGENTS.md` rule 5
|
|
132
|
+
* says stop repairing at the third round and re-scope, so: **a path needs both
|
|
133
|
+
* halves — a separator AND an extension — and the class is closed.** There is
|
|
134
|
+
* no third shape left for a fifth token to arrive through. The alternative was
|
|
135
|
+
* a fourth special case, and a predicate accumulating special cases is the
|
|
136
|
+
* `stripHeredocs` shape from #1808, which cost four rounds before it was
|
|
137
|
+
* deleted.
|
|
138
|
+
*
|
|
139
|
+
* ## What this MISSES, said out loud
|
|
140
|
+
*
|
|
141
|
+
* - **Every root file** — `package.json`, `AGENTS.md`, `CLAUDE.md`. The
|
|
142
|
+
* deliberate cost of the separator, and the one real loss: those files are
|
|
143
|
+
* contested often. Buying them back needs a mechanism rather than a
|
|
144
|
+
* heuristic — the repository's own tracked-file list, which this module
|
|
145
|
+
* cannot see and should not grow a repo handle for at round five. That is a
|
|
146
|
+
* second issue, not a fourth branch.
|
|
147
|
+
* - An extension-less file — `Makefile`, `lib/issue-shape` — and a dotfile
|
|
148
|
+
* like `.gitignore`.
|
|
149
|
+
* - A URL is rejected outright on `://`, so a link to a file in another
|
|
150
|
+
* repository is not read as a file in this one.
|
|
151
|
+
*
|
|
152
|
+
* `FO-52` and `FO-57` assert the misses rather than leaving them in prose,
|
|
153
|
+
* because an earlier version of this comment claimed `Makefile` was read while
|
|
154
|
+
* the code rejected it.
|
|
155
|
+
*
|
|
156
|
+
* Every one of those is the direction `declaredFiles` declares two paragraphs
|
|
157
|
+
* up: this reader may read too few files, never a file that does not exist. A
|
|
158
|
+
* missed path costs a warning nobody gets; an invented one costs a collision
|
|
159
|
+
* report against a file that is not there, which is how the channel becomes
|
|
160
|
+
* noise people skip.
|
|
161
|
+
*/
|
|
162
|
+
function pathsOnLine(line: string): string[] {
|
|
163
|
+
const bare = line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, "").trim();
|
|
164
|
+
const quoted = [...bare.matchAll(/`([^`]+)`/g)].map(m => m[1].trim());
|
|
165
|
+
const candidates = quoted.length > 0 ? quoted : [bare];
|
|
166
|
+
|
|
167
|
+
return candidates.filter(isPath).map(c => c.replace(/^\.\//, ""));
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* One word, containing a `/`, ending in an alphabetic extension.
|
|
172
|
+
*
|
|
173
|
+
* **A repo-relative path, and nothing else.** The separator is the whole of
|
|
174
|
+
* the rule that was missing. See `pathsOnLine` for why it is here rather than
|
|
175
|
+
* a fourth special case.
|
|
176
|
+
*/
|
|
177
|
+
function isPath(candidate: string): boolean {
|
|
178
|
+
if (candidate === "" || /\s/.test(candidate)) return false;
|
|
179
|
+
if (candidate.includes("://")) return false; // a URL, not a file
|
|
180
|
+
return candidate.includes("/") && /[A-Za-z][^/]*\.[A-Za-z]{2,5}$/.test(candidate);
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* The paths both issues declare, in the first one's order.
|
|
185
|
+
*
|
|
186
|
+
* Exact paths. Deliberately no stem matching between a source file and its
|
|
187
|
+
* test: they are edited together constantly and by the SAME issue, so treating
|
|
188
|
+
* them as one file would make nearly every pair collide and the warning would
|
|
189
|
+
* be worth nothing.
|
|
190
|
+
*/
|
|
191
|
+
export function sharedFiles(a: readonly string[], b: readonly string[]): string[] {
|
|
192
|
+
return a.filter(p => b.includes(p));
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* Every file more than one of these issues declares, lowest lead first.
|
|
197
|
+
*
|
|
198
|
+
* **The unit is a FILE, and that is the correction this went through.** The
|
|
199
|
+
* first version clustered ISSUES by transitive union: two issues sharing
|
|
200
|
+
* nothing directly landed in one group when both collided with a third, and
|
|
201
|
+
* the group then carried the union of everyone's contested paths. Reported to
|
|
202
|
+
* a reader it over-claimed — #100 on `lib/a.ts` and a filing on `lib/b.ts`
|
|
203
|
+
* were told they shared work, on the strength of a #200 that declares both.
|
|
204
|
+
*
|
|
205
|
+
* A file is the thing two issues actually contend for, so it is the thing this
|
|
206
|
+
* reading is keyed on. Every id in a row declares that row's path. There is
|
|
207
|
+
* nothing left to over-claim with, and the union-find went with it.
|
|
208
|
+
*
|
|
209
|
+
* `lead` is the LOWEST number, which is the oldest issue and the one the rest
|
|
210
|
+
* queue behind. Stable by construction: a reading whose lead moved between
|
|
211
|
+
* runs would hand out a different set of edges each time and the board would
|
|
212
|
+
* churn.
|
|
213
|
+
*/
|
|
214
|
+
export function contestedFiles(issues: readonly IssueFiles[]): FileContention[] {
|
|
215
|
+
const by = new Map<string, number[]>();
|
|
216
|
+
for (const issue of issues) {
|
|
217
|
+
for (const path of new Set(issue.files)) {
|
|
218
|
+
by.set(path, [...(by.get(path) ?? []), issue.id]);
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
return [...by.entries()]
|
|
223
|
+
.filter(([, ids]) => ids.length > 1)
|
|
224
|
+
.map(([file, ids]) => {
|
|
225
|
+
const sorted = [...ids].sort((a, b) => a - b);
|
|
226
|
+
return { file, lead: sorted[0], blocked: sorted.slice(1) };
|
|
227
|
+
})
|
|
228
|
+
.sort((a, b) => a.lead - b.lead || a.file.localeCompare(b.file));
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* Which of these issues contend for a file — #1976, SC-2761.
|
|
233
|
+
*
|
|
234
|
+
* What `scripts/work-status.ts` prints under START HERE and PROMOTION
|
|
235
|
+
* CANDIDATES, so the page says which of the startable issues can run at once.
|
|
236
|
+
* `contestedFiles` over `declaredFiles`: one reading of a body, one decider
|
|
237
|
+
* of contention, keyed by FILE for the reason that function records. An
|
|
238
|
+
* issue naming no files is in no row, so two silent issues are never grouped
|
|
239
|
+
* on a shared empty set.
|
|
240
|
+
*/
|
|
241
|
+
export function fileOverlapGroups(
|
|
242
|
+
issues: readonly { readonly number: number; readonly body?: string | null }[],
|
|
243
|
+
): FileContention[] {
|
|
244
|
+
return contestedFiles(issues.map(i => ({ id: i.number, files: declaredFiles(i.body ?? "") })));
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* The lines the report prints for one list of `listed` issues. Nothing for a
|
|
249
|
+
* list of one, which cannot collide with itself; a clean line when nothing is
|
|
250
|
+
* contested, so "no collisions" is said rather than left as silence.
|
|
251
|
+
*/
|
|
252
|
+
export function overlapLines(groups: readonly FileContention[], listed: number): string[] {
|
|
253
|
+
if (listed < 2) return [];
|
|
254
|
+
if (groups.length === 0) {
|
|
255
|
+
return [" No two of these name the same file, so any of them can run at once."];
|
|
256
|
+
}
|
|
257
|
+
return [
|
|
258
|
+
" Collide on a file (start one per row, not two):",
|
|
259
|
+
...groups.map(g => ` ${g.file}: #${[g.lead, ...g.blocked].join(", #")}`),
|
|
260
|
+
];
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/**
|
|
264
|
+
* Corpus rows as the thing this file reasons about.
|
|
265
|
+
*
|
|
266
|
+
* Takes the structural shape rather than importing `Finding`, so the direction
|
|
267
|
+
* of the dependency stays one way: `lib/issue-filing-gate.ts` reads this file,
|
|
268
|
+
* and this file knows nothing about the gate.
|
|
269
|
+
*
|
|
270
|
+
* **A row whose id is not a number is dropped, not coerced.** The corpus also
|
|
271
|
+
* carries in-command siblings keyed by position and the `new` marker for an
|
|
272
|
+
* unfiled finding, and `Number("new")` is `NaN` — an id that would print as
|
|
273
|
+
* `#NaN` in a warning and point at nothing.
|
|
274
|
+
*/
|
|
275
|
+
export function asIssueFiles(rows: readonly { id: string; body: string }[]): IssueFiles[] {
|
|
276
|
+
const out: IssueFiles[] = [];
|
|
277
|
+
for (const row of rows) {
|
|
278
|
+
const id = Number(row.id);
|
|
279
|
+
if (!Number.isInteger(id) || id <= 0) continue;
|
|
280
|
+
const files = declaredFiles(row.body);
|
|
281
|
+
if (files.length > 0) out.push({ id, files });
|
|
282
|
+
}
|
|
283
|
+
return out;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/**
|
|
287
|
+
* The open issues this body shares a file with, and WHICH files, ascending.
|
|
288
|
+
*
|
|
289
|
+
* **DIRECT overlap, and the word is load-bearing.** The first version ran the
|
|
290
|
+
* body through a transitive clustering with the rest and reported the group it
|
|
291
|
+
* landed in, on the argument that everything in a contested set costs the same
|
|
292
|
+
* to pick up. The review of this PR showed that argument is false, with a case
|
|
293
|
+
* I had written no test for:
|
|
294
|
+
*
|
|
295
|
+
* #100 declares lib/a.ts
|
|
296
|
+
* #200 declares lib/a.ts AND lib/b.ts
|
|
297
|
+
* the filing declares lib/b.ts
|
|
298
|
+
*
|
|
299
|
+
* One group, transitively — and the note then told the filer they shared
|
|
300
|
+
* `lib/a.ts` with #100, which neither of them is true of, and offered
|
|
301
|
+
* `--add-blocked-by 100` on that basis. A warning that names a file the reader
|
|
302
|
+
* never wrote is the fastest way to teach them to skip the channel. `FO-45`
|
|
303
|
+
* and `FG-229` are that case.
|
|
304
|
+
*
|
|
305
|
+
* Transitivity is still right for the question `contestedFiles` answers —
|
|
306
|
+
* *what does the pickable set look like* — because there every id in a row
|
|
307
|
+
* declares that row's path. It is wrong for *what does THIS body collide
|
|
308
|
+
* with*, and those are two questions.
|
|
309
|
+
*/
|
|
310
|
+
export function collisionsWith(body: string, corpus: readonly IssueFiles[]): IssueFiles[] {
|
|
311
|
+
const mine = declaredFiles(body);
|
|
312
|
+
if (mine.length === 0) return [];
|
|
313
|
+
|
|
314
|
+
return corpus
|
|
315
|
+
.map(issue => ({ id: issue.id, files: sharedFiles(mine, issue.files) }))
|
|
316
|
+
.filter(hit => hit.files.length > 0)
|
|
317
|
+
.sort((a, b) => a.id - b.id);
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/**
|
|
321
|
+
* The note an agent reads when the body they are filing collides, or null.
|
|
322
|
+
*
|
|
323
|
+
* Null rather than an empty string: `lib/issue-filing-gate.ts` joins its
|
|
324
|
+
* notes, so an empty one is blank space in a refusal nobody can account for,
|
|
325
|
+
* and a channel that always has something in it is a channel people skip.
|
|
326
|
+
*
|
|
327
|
+
* **Every path printed here is one the filing itself declared**, and it is
|
|
328
|
+
* attributed to an issue that declared it too — `collisionsWith` carries the
|
|
329
|
+
* intersection rather than either side's whole list, so there is nothing for
|
|
330
|
+
* this function to over-claim with.
|
|
331
|
+
*
|
|
332
|
+
* It names the remedy. A warning that does not say what to type is a warning
|
|
333
|
+
* nobody can act on — `.claude/rules/config-access.md` makes that point about
|
|
334
|
+
* UNMEASURED and it is true of every channel this gate writes to.
|
|
335
|
+
*
|
|
336
|
+
* The closing line is `contestedFiles` over the OPEN corpus alone, with this
|
|
337
|
+
* body nowhere in it: a file two or more issues already contend for is a queue
|
|
338
|
+
* the filer is joining, not a pair they are forming, and the oldest is the one
|
|
339
|
+
* the rest go behind. `FO-46` pins the count at three where four issues would
|
|
340
|
+
* be the tempting number.
|
|
341
|
+
*/
|
|
342
|
+
export function overlapNote(body: string, corpus: readonly IssueFiles[]): string | null {
|
|
343
|
+
const collisions = collisionsWith(body, corpus);
|
|
344
|
+
if (collisions.length === 0) return null;
|
|
345
|
+
|
|
346
|
+
const flags = collisions.map(c => `--add-blocked-by ${c.id}`).join(" ");
|
|
347
|
+
const mine = new Set(collisions.flatMap(c => c.files));
|
|
348
|
+
const queues = contestedFiles(corpus)
|
|
349
|
+
.filter(c => mine.has(c.file))
|
|
350
|
+
.map(
|
|
351
|
+
c =>
|
|
352
|
+
`\`${c.file}\` already has ${c.blocked.length + 1} open issues on it — ` +
|
|
353
|
+
`#${c.lead} is the oldest.`,
|
|
354
|
+
);
|
|
355
|
+
|
|
356
|
+
return [
|
|
357
|
+
`**${plural(collisions.length)} already open ${collisions.length === 1 ? "names" : "name"} ` +
|
|
358
|
+
"a file this one names:**",
|
|
359
|
+
"",
|
|
360
|
+
...collisions.map(c => `- #${c.id} — ${c.files.map(f => `\`${f}\``).join(", ")}`),
|
|
361
|
+
...(queues.length > 0 ? ["", ...queues] : []),
|
|
362
|
+
"",
|
|
363
|
+
"Two sessions editing one file, with nothing on the tracker saying so, is",
|
|
364
|
+
"the conflict this is warning about — it is NOT a dependency, and the board",
|
|
365
|
+
"should not grow an ordering nobody meant. Order them only if you do:",
|
|
366
|
+
"",
|
|
367
|
+
` gh issue edit <this issue> ${flags}`,
|
|
368
|
+
].join("\n");
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
function plural(n: number): string {
|
|
372
|
+
return n === 1 ? "An issue" : `${n} issues`;
|
|
373
|
+
}
|