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/README.md
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# RunGate
|
|
2
|
+
|
|
3
|
+
A ship harness for AI-first development: from issue to merged PR, with a report you can trust.
|
|
4
|
+
|
|
5
|
+
You should be able to trust that report without checking it again by hand. Coding agents can write a lot of code quickly. The hard part is believing what they say about it. "Tests pass", "0 regressions" and "security: clean" are only useful if the thing reporting them could have said something else. RunGate is built around that. The automation isn't really the product. The product is a report you don't have to re-measure.
|
|
6
|
+
|
|
7
|
+
> **Status: active development, pre-1.0.** Published on npm as [`rungate`](https://www.npmjs.com/package/rungate). It is used daily on this repo and is being proven on a second, unrelated project. Expect breaking changes between minor versions.
|
|
8
|
+
|
|
9
|
+
## What it does
|
|
10
|
+
|
|
11
|
+
RunGate sits between an issue tracker and a coding agent (Claude Code today; the design is agent-agnostic) and runs every change through a fixed pipeline:
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
issue → SCOPE → BUILD → VERIFY → CLOSE → SHIP_PASSED | SHIP_FAILED
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
- **Gates, not guidelines.** Each phase ends at a gate: typecheck, tests, test-first sequencing, security review, compliance grade, review currency, and commit receipt. A failed gate stops the ship. It is not just written into a log.
|
|
18
|
+
- **Specs with checkable criteria.** Work is driven by specs whose success criteria name the evidence that proves them. A criterion ticked without evidence is refused.
|
|
19
|
+
- **Spec → board, automatically.** A spec's phases become milestones, issues and `blocked by` edges on the GitHub project board. Nobody has to place the plan there by hand.
|
|
20
|
+
- **Project-specific agent rules.** `scaffold` gives a repo its agent files and a conformity suite. `extract-constraints` mines the repo's own docs and history for rules an agent couldn't work out from the code.
|
|
21
|
+
- **AI review that blocks.** AI code-review findings are judged and posted as review threads on the PR diff, and a blocking finding fails the check.
|
|
22
|
+
- **Workflows** for `ship`, `prove` (reproduce and attest a fix), `verify`, `batch-ship`, `ship-and-heal` and multi-agent `council` decisions.
|
|
23
|
+
|
|
24
|
+
## What "done" means
|
|
25
|
+
|
|
26
|
+
The project measures itself against falsifiable claims in [`SUCCESS.md`](SUCCESS.md). Each claim has a named check:
|
|
27
|
+
|
|
28
|
+
1. **Every gate can fail, and has been seen failing.** A mutant with the refusal removed must ship where the real gate refuses.
|
|
29
|
+
2. **Every number a run reports describes the committed tree.** No figure can come from before the last edit it describes.
|
|
30
|
+
3. **A bad ship is stopped, not described.** Every verdict the harness computes can return `SHIP_FAILED`.
|
|
31
|
+
4. **"Could not measure" never reads as "nothing wrong."** Missing, empty or broken input is a separate, loud result.
|
|
32
|
+
5. **It works on a repo that isn't this one.**
|
|
33
|
+
6. **A managed repo carries its own rules**, mined from that repo's history, not just a generic baseline.
|
|
34
|
+
7. **The plan is on the tracker, and no person or agent put it there.**
|
|
35
|
+
|
|
36
|
+
A green test suite, a passing gate and a merged PR don't count as progress unless they meet these claims. Each of them has been wrong in this repo before.
|
|
37
|
+
|
|
38
|
+
## Where it stands
|
|
39
|
+
|
|
40
|
+
- **Working:** the ship pipeline and gates, the spec tooling, AI-review adjudication, scaffolding, and release automation to npm. About 1,500 commits and 900 merged PRs, most shipped through the harness itself. Since 2026-10-19 the repo has been shipping directly while RunGate is stabilised.
|
|
41
|
+
- **In progress:** the *engine*. The goal is for a spec to become a readable project board with no hand-run steps ([ADR-009](docs/adr/ADR-009-engine-goal-and-build-order.md)), and for issue intake to be governed so every issue names the criterion it serves.
|
|
42
|
+
- **Next:** a full run on a consumer project with a different config layout (claim 5). Until that is done, consumer support is unproven.
|
|
43
|
+
|
|
44
|
+
Live session-by-session state is in [`PROJECT-STATE.md`](PROJECT-STATE.md).
|
|
45
|
+
|
|
46
|
+
## Quick start
|
|
47
|
+
|
|
48
|
+
Requires [Bun](https://bun.sh).
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
# In the repository you want to manage
|
|
52
|
+
bunx rungate scaffold . # agent files, rules and conformity suite
|
|
53
|
+
bunx rungate create-success # seed SUCCESS.md: what the project is for
|
|
54
|
+
bunx rungate create-spec "Title" # a spec with checkable success criteria
|
|
55
|
+
bunx rungate board-mirror --project <id> # show the spec's criteria on the project board
|
|
56
|
+
bunx rungate board-conformance # does the board match the spec? non-zero if not
|
|
57
|
+
bunx rungate --help # every command and its arguments
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Projects are configured in `.claude/rungate.json` (project slug, code and issue repos, dev/test/prod commands). See [`HARNESS.md`](HARNESS.md) for the schema and workflow entry points.
|
|
61
|
+
|
|
62
|
+
## Repository layout
|
|
63
|
+
|
|
64
|
+
| Path | What lives there |
|
|
65
|
+
|---|---|
|
|
66
|
+
| `bin/`, `lib/` | CLI and core library |
|
|
67
|
+
| `gates/` | Gate runner, ship orchestrator and gate tests |
|
|
68
|
+
| `workflows/` | `ship`, `prove`, `verify`, `council` and friends |
|
|
69
|
+
| `specs/` | Specs that govern the harness's own behaviour |
|
|
70
|
+
| `docs/adr/` | Architecture decisions |
|
|
71
|
+
| `templates/`, `prompts/` | What `scaffold` writes and the agents read |
|
|
72
|
+
| `test/` | The suite. Run with `bun scripts/test-clean-env.ts` |
|
|
73
|
+
|
|
74
|
+
## Development
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
bun install
|
|
78
|
+
bun scripts/test-clean-env.ts # the suite in a clean environment (trust this one)
|
|
79
|
+
bun test <file> # a single file
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Start with [`AGENTS.md`](AGENTS.md) and [`CODE-MAP.md`](CODE-MAP.md).
|
package/gates/.gate-salt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
c12fa16b484d2832d774f0c27f2e81e29259ed31eb32ca4332faa9ed6b42face
|
|
@@ -5,9 +5,9 @@
|
|
|
5
5
|
* SC-370 (HOOK-ARCHITECTURE-SPEC): Hook SC traceability
|
|
6
6
|
* SC-371 (HOOK-ARCHITECTURE-SPEC): No hook exceeds 150 lines
|
|
7
7
|
*
|
|
8
|
-
* TWO independent gates on one chokepoint —
|
|
9
|
-
* Both decisions live in lib/ and
|
|
10
|
-
* hooks are thin triggers).
|
|
8
|
+
* TWO independent gates on one chokepoint — a filing reaching Bash, in any
|
|
9
|
+
* spelling `createsIssue` knows (#1759). Both decisions live in lib/ and
|
|
10
|
+
* not here (#365, HOOK-ARCHITECTURE-SPEC: hooks are thin triggers).
|
|
11
11
|
*
|
|
12
12
|
* 1. **The VERIFY-phase lock** (#443, #365). Workflow discipline: during
|
|
13
13
|
* VERIFY, use verifyBlockers[] instead. Waived by the override labels in
|
package/lib/ai-review-rounds.ts
CHANGED
|
@@ -585,6 +585,105 @@ export function carryKey(finding: unknown, lineText?: unknown): string | null {
|
|
|
585
585
|
return `${file}\u0000${anchor}\u0000${summary}`;
|
|
586
586
|
}
|
|
587
587
|
|
|
588
|
+
/**
|
|
589
|
+
* THE SAME KEY WITH THE WORDING DROPPED — `file \0 t:<text>` (#1168).
|
|
590
|
+
*
|
|
591
|
+
* @identity file+text — `file` and the TEXT of the cited line, and nothing
|
|
592
|
+
* else. It answers a THIRD question, which is why it has a third name: not
|
|
593
|
+
* *is this the same finding* (`carryKey`, which adds the summary) and not
|
|
594
|
+
* *is this worth adjudicating* (`advisoryKey`), but **is this the same PLACE
|
|
595
|
+
* an earlier round already objected to**. It is derived from a `carryKey`
|
|
596
|
+
* string rather than from a finding, so the two cannot drift apart: there is
|
|
597
|
+
* no second parse of a finding here to disagree with the first.
|
|
598
|
+
*
|
|
599
|
+
* `carryKey` ends in the summary, and `suppressRepeats`' docblock below
|
|
600
|
+
* states what that buys: *a finding whose summary changed is not [a repeat]*.
|
|
601
|
+
* That was a deliberate trade — protect a genuinely different finding that
|
|
602
|
+
* happens to sit at a line an earlier round cited — and the measurement says
|
|
603
|
+
* it costs everything to buy nothing.
|
|
604
|
+
*
|
|
605
|
+
* Read on the last 25 merged pull requests of this repository, 25 round-2+
|
|
606
|
+
* findings: **0 repeats the full key could see, and 8 real ones**. Every one
|
|
607
|
+
* of the eight was the same defect restated in different words, every one
|
|
608
|
+
* confirmed by reading the pair, and **zero** were the case the summary
|
|
609
|
+
* component protects. The reviewer rewords on essentially every re-raise, so
|
|
610
|
+
* the population the full key can match is empty by construction — the `0` is
|
|
611
|
+
* the shape of the key, not the state of the repo.
|
|
612
|
+
*
|
|
613
|
+
* ## Only a TEXT anchor, and that is the whole safety argument
|
|
614
|
+
*
|
|
615
|
+
* `carryKey` falls back to `n:<line>` when the caller could not read the
|
|
616
|
+
* line. Two unrelated findings at line 4 of one file share that namespace and
|
|
617
|
+
* nothing else, so matching on it would suppress across completely different
|
|
618
|
+
* defects. This returns `null` for `n:` and the caller suppresses nothing —
|
|
619
|
+
* which also keeps the asymmetry `checkoutLineText`'s docblock describes from
|
|
620
|
+
* turning into over-suppression when a checkout cannot be read.
|
|
621
|
+
*
|
|
622
|
+
* ## A TEXT anchor is not automatically a DISTINCTIVE one
|
|
623
|
+
*
|
|
624
|
+
* A line reading `}` or `return null;` keys the same anchor wherever it
|
|
625
|
+
* recurs in its file, so two findings at two different occurrences collide
|
|
626
|
+
* here and this cannot tell them apart. That screen is the CALLER's, not
|
|
627
|
+
* this function's — it needs the file, and this takes a string. See
|
|
628
|
+
* `checkoutLineReader` and the uniqueness condition in
|
|
629
|
+
* `lib/ai-review-suppression.ts`.
|
|
630
|
+
*
|
|
631
|
+
* Measured on the same 25 pull requests, 60 findings carrying a text anchor:
|
|
632
|
+
* **5 — 8.3% — cite a line whose text recurs in its own file.** A minimum
|
|
633
|
+
* anchor LENGTH does not separate them and was the fix not taken: four of the
|
|
634
|
+
* five normalise to over twenty characters and one to forty-five
|
|
635
|
+
* (`for (const t of tokenize(heredocView(cmd))) {`). Counting occurrences is
|
|
636
|
+
* the only screen the reading supports.
|
|
637
|
+
*
|
|
638
|
+
* ## The direction this is allowed to be wrong in has CHANGED, deliberately
|
|
639
|
+
*
|
|
640
|
+
* Everything else here errs toward reporting a repeat twice. This errs toward
|
|
641
|
+
* calling two differently-worded findings one finding, which can be wrong,
|
|
642
|
+
* which is why the caller must report a DIFFERENT reason for it: a reader has
|
|
643
|
+
* to be able to tell a verbatim re-post from a judgement. The judgement is
|
|
644
|
+
* the only one of the two that can be appealed.
|
|
645
|
+
*
|
|
646
|
+
* Exported and total so there is one binding to mutate, and so the battery
|
|
647
|
+
* can drive it without a thread list.
|
|
648
|
+
*/
|
|
649
|
+
export function anchorOnlyKey(key: string | null): string | null {
|
|
650
|
+
if (typeof key !== "string") return null;
|
|
651
|
+
const parts = key.split("\u0000");
|
|
652
|
+
if (parts.length !== 3) return null;
|
|
653
|
+
const [file, anchor] = parts as [string, string, string];
|
|
654
|
+
if (!anchor.startsWith("t:") || anchor === "t:") return null;
|
|
655
|
+
if (file === "") return null;
|
|
656
|
+
return `${file}\u0000${anchor}`;
|
|
657
|
+
}
|
|
658
|
+
|
|
659
|
+
/**
|
|
660
|
+
* The normalised TEXT out of an anchor key, so the distinctiveness screen
|
|
661
|
+
* counts occurrences of the same string the key was built from (#1861).
|
|
662
|
+
*
|
|
663
|
+
* Not an identity and never used as one — it returns a component, and that
|
|
664
|
+
* is why it is not named `…Key`. It exists so the caller does not re-derive
|
|
665
|
+
* the text from the finding: a second derivation is a second decider, and the
|
|
666
|
+
* two would agree until one of them was mutated, at which point the other
|
|
667
|
+
* holds every case up. `null` for anything `anchorOnlyKey` would reject.
|
|
668
|
+
*/
|
|
669
|
+
export function anchorTextOf(anchorKey: string | null): string | null {
|
|
670
|
+
if (typeof anchorKey !== "string") return null;
|
|
671
|
+
const parts = anchorKey.split("\u0000");
|
|
672
|
+
if (parts.length !== 2) return null;
|
|
673
|
+
const anchor = parts[1] as string;
|
|
674
|
+
if (!anchor.startsWith("t:") || anchor === "t:") return null;
|
|
675
|
+
return anchor.slice(2);
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
/**
|
|
679
|
+
* The normalisation `carryKey` applies to a cited line, exported so a reader
|
|
680
|
+
* counting occurrences of that line compares like with like. One binding; a
|
|
681
|
+
* private copy in the reader would be the two-deciders fault again.
|
|
682
|
+
*/
|
|
683
|
+
export function normaliseLineText(v: unknown): string {
|
|
684
|
+
return normalise(v);
|
|
685
|
+
}
|
|
686
|
+
|
|
588
687
|
export interface SuppressionReading {
|
|
589
688
|
/** Findings this round may report. */
|
|
590
689
|
kept: ReviewFinding[];
|
|
@@ -14,8 +14,11 @@
|
|
|
14
14
|
* reformat moves — measured on #1616 as 11 threads for 3 findings. A thread
|
|
15
15
|
* is GitHub's own answer to the same question, so AC-1 moved the gate onto
|
|
16
16
|
* it: `priorKeysFrom` reads the list the carry step fetched and nothing else.
|
|
17
|
-
* The ledger reader
|
|
18
|
-
*
|
|
17
|
+
* The ledger reader that used to sit beside it is GONE — AC-5 stopped writing
|
|
18
|
+
* the snapshot it parsed and `ledgerPriorKeysFrom`, `readSnapshot` and
|
|
19
|
+
* `carryStateOf` were deleted with it. `test/ai-review-suppression.test.ts`
|
|
20
|
+
* (AS-0b) asserts all three stay absent, so this paragraph cannot go stale
|
|
21
|
+
* again in the other direction.
|
|
19
22
|
*
|
|
20
23
|
* ## Why the prior state arrives as a file and not as a fetch
|
|
21
24
|
*
|
|
@@ -56,7 +59,10 @@ import { isAbsolute, resolve, sep } from "path";
|
|
|
56
59
|
|
|
57
60
|
import {
|
|
58
61
|
AI_REVIEW_PRIOR_MEASURED,
|
|
62
|
+
anchorOnlyKey,
|
|
63
|
+
anchorTextOf,
|
|
59
64
|
carryKey,
|
|
65
|
+
normaliseLineText,
|
|
60
66
|
priorFindings,
|
|
61
67
|
readLedger,
|
|
62
68
|
type ReviewFinding,
|
|
@@ -81,6 +87,15 @@ export interface SuppressionInputs {
|
|
|
81
87
|
threads: string | null;
|
|
82
88
|
/** The text at a finding's cited line NOW, or `undefined`. */
|
|
83
89
|
lineTextFor: (finding: ReviewFinding) => string | undefined;
|
|
90
|
+
/**
|
|
91
|
+
* How many lines of `file` carry `normalisedText`, or `undefined` when the
|
|
92
|
+
* file could not be read (#1861).
|
|
93
|
+
*
|
|
94
|
+
* Optional, and absent means the anchor rule never fires. A caller that has
|
|
95
|
+
* not been rewired keeps the behaviour it had before the rule existed,
|
|
96
|
+
* which is the direction this module is allowed to be wrong in.
|
|
97
|
+
*/
|
|
98
|
+
anchorOccurrences?: (file: string, normalisedText: string) => number | undefined;
|
|
84
99
|
}
|
|
85
100
|
|
|
86
101
|
/** A prior set that was established, or the sentence saying it was not. */
|
|
@@ -144,6 +159,35 @@ export function priorKeysFrom(threads: string | null): PriorKeys {
|
|
|
144
159
|
return { status: "MEASURED", keys: reading.threads.map(t => t.key) };
|
|
145
160
|
}
|
|
146
161
|
|
|
162
|
+
/**
|
|
163
|
+
* Does this anchor identify ONE line of the file it names (#1861 round 3)?
|
|
164
|
+
*
|
|
165
|
+
* The screen the round-3 review asked for, and deliberately NOT the one it
|
|
166
|
+
* suggested. A minimum anchor length was the obvious fix and the measurement
|
|
167
|
+
* refuses it: of the five ambiguous anchors in the 60-finding corpus, four
|
|
168
|
+
* normalise to over twenty characters and the worst is forty-five. Length
|
|
169
|
+
* does not predict distinctiveness; counting the occurrences measures it.
|
|
170
|
+
*
|
|
171
|
+
* Every reading that is not exactly `1` answers `false`, including every way
|
|
172
|
+
* of failing to read. A caller with no counter, a file that is not there, a
|
|
173
|
+
* key whose text cannot be recovered and a path with two matching lines all
|
|
174
|
+
* mean the same thing here: this anchor cannot be shown to name one place,
|
|
175
|
+
* so nothing is suppressed on it.
|
|
176
|
+
*/
|
|
177
|
+
function uniqueAnchor(
|
|
178
|
+
inputs: SuppressionInputs,
|
|
179
|
+
finding: ReviewFinding,
|
|
180
|
+
anchorKey: string,
|
|
181
|
+
): boolean {
|
|
182
|
+
const count = inputs.anchorOccurrences;
|
|
183
|
+
if (count === undefined) return false;
|
|
184
|
+
const text = anchorTextOf(anchorKey);
|
|
185
|
+
if (text === null || text === "") return false;
|
|
186
|
+
const file = finding.file;
|
|
187
|
+
if (typeof file !== "string" || file === "") return false;
|
|
188
|
+
return count(file, text) === 1;
|
|
189
|
+
}
|
|
190
|
+
|
|
147
191
|
/**
|
|
148
192
|
* Build the gate the adjudicator is handed, or `null` when nothing is plumbed.
|
|
149
193
|
*
|
|
@@ -165,26 +209,126 @@ export function aiReviewSuppressionGate(inputs: SuppressionInputs): AiReviewSupp
|
|
|
165
209
|
// `AiReviewJuryGate`'s docblock names. `carryKey` is the shared rule and
|
|
166
210
|
// the within-round half is the growing `seen` set, exactly as
|
|
167
211
|
// `suppressRepeats` spells it.
|
|
212
|
+
// The keys an EARLIER round posted, kept apart from the growing set
|
|
213
|
+
// below so the two sentences can say which of them matched (#1861 round
|
|
214
|
+
// 3). They used to be one set, and the message said "an earlier round"
|
|
215
|
+
// for a duplicate that came from this round's own payload.
|
|
216
|
+
const priorSet = new Set<string>(prior.keys);
|
|
168
217
|
const seen = new Set<string>(prior.keys);
|
|
218
|
+
// #1168. The same prior set read with the wording dropped. Built from the
|
|
219
|
+
// SAME strings rather than from the threads a second time: two derivations
|
|
220
|
+
// of one identity are two deciders that agree, and a mutation of either
|
|
221
|
+
// leaves the other holding every case up.
|
|
222
|
+
const anchors = new Set<string>();
|
|
223
|
+
for (const k of prior.keys) {
|
|
224
|
+
const a = anchorOnlyKey(k);
|
|
225
|
+
if (a !== null) anchors.add(a);
|
|
226
|
+
}
|
|
169
227
|
const repeat = candidates.map(c => {
|
|
170
228
|
const key = carryKey(c, inputs.lineTextFor(c as ReviewFinding));
|
|
171
229
|
// Unkeyable CARRIES. It cannot be shown to be a repeat, and the
|
|
172
230
|
// direction this is allowed to be wrong in is toward reporting.
|
|
173
231
|
if (key === null) return null;
|
|
174
|
-
if (!seen.has(key)) {
|
|
175
|
-
seen.add(key);
|
|
176
|
-
return null;
|
|
177
|
-
}
|
|
178
232
|
const f = c as ReviewFinding;
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
233
|
+
const where = String(f.file ?? "(no file)");
|
|
234
|
+
const what = String(f.summary ?? "(no summary)");
|
|
235
|
+
if (seen.has(key)) {
|
|
236
|
+
// WHICH set matched is the difference between two true sentences and
|
|
237
|
+
// one false one. `priorSet` is fixed at the prior round's keys;
|
|
238
|
+
// anything else in `seen` was added by a sibling a few lines below.
|
|
239
|
+
return priorSet.has(key)
|
|
240
|
+
? `${where}: ${what} — already ` +
|
|
241
|
+
`raised on an earlier round of this pull request, so it is not raised again`
|
|
242
|
+
: `${where}: ${what} — listed more than once in this round's own ` +
|
|
243
|
+
`report, word for word, so it is reported once`;
|
|
244
|
+
}
|
|
245
|
+
const anchor = anchorOnlyKey(key);
|
|
246
|
+
// The wording differs and the anchor does not. Measured at #1168: of
|
|
247
|
+
// eight such collisions across 25 merged pull requests, eight were the
|
|
248
|
+
// same defect restated and none was a new finding at an old line. This
|
|
249
|
+
// is a JUDGEMENT rather than an identity, so it says so — the sentence
|
|
250
|
+
// is what lets a reader appeal it.
|
|
251
|
+
//
|
|
252
|
+
// And it fires only on an anchor that identifies ONE line of the file.
|
|
253
|
+
// `}` and `return null;` key the same anchor wherever they recur, so a
|
|
254
|
+
// new finding at a second occurrence would be suppressed as a
|
|
255
|
+
// restatement of a defect somewhere else entirely. Measured at #1861:
|
|
256
|
+
// 5 of 60 anchors in the corpus — 8.3% — recur in their own file. An
|
|
257
|
+
// unreadable file counts as NOT unique, because "I could not look" and
|
|
258
|
+
// "it appears once" must not be the same reading.
|
|
259
|
+
if (anchor !== null && anchors.has(anchor) && uniqueAnchor(inputs, f, anchor)) {
|
|
260
|
+
return (
|
|
261
|
+
`${where}: ${what} — an earlier round of this pull request already ` +
|
|
262
|
+
`raised a finding at the same line of text in this file, in different words, ` +
|
|
263
|
+
`so this is read as the same finding restated and is not raised again`
|
|
264
|
+
);
|
|
265
|
+
}
|
|
266
|
+
seen.add(key);
|
|
267
|
+
// `anchors` is NOT grown here, and the asymmetry with `seen` above is
|
|
268
|
+
// deliberate (#1861 round 1).
|
|
269
|
+
//
|
|
270
|
+
// `seen` growing is the established within-round rule and is safe on an
|
|
271
|
+
// EXACT key: two candidates with the same file, anchor AND wording are
|
|
272
|
+
// the same finding listed twice. The anchor key drops the wording, so
|
|
273
|
+
// growing it would suppress a second, differently-worded finding at the
|
|
274
|
+
// same line because a SIBLING in this very round cited it — and the
|
|
275
|
+
// sentence above, which says "an earlier round", would be false.
|
|
276
|
+
//
|
|
277
|
+
// It is also unmeasured: #1168's reading characterises cross-round
|
|
278
|
+
// collisions only, 8 of 8 restatements. It says nothing about two
|
|
279
|
+
// findings a reviewer raises at one line while looking at it once,
|
|
280
|
+
// which is the more plausible place for two genuine defects to share an
|
|
281
|
+
// anchor. Suppressing on evidence that was never taken is the thing
|
|
282
|
+
// this whole increment is a correction for.
|
|
283
|
+
return null;
|
|
183
284
|
});
|
|
184
285
|
return { repeat, unmeasured: null };
|
|
185
286
|
};
|
|
186
287
|
}
|
|
187
288
|
|
|
289
|
+
/**
|
|
290
|
+
* THE ONE PLACE A PRODUCTION `SuppressionInputs` IS ASSEMBLED (#1861 round 4).
|
|
291
|
+
*
|
|
292
|
+
* Two commands form this gate — `scripts/ai-review-findings.ts`, which decides
|
|
293
|
+
* the exit code, and `scripts/ai-review-threads.ts`, which posts the threads.
|
|
294
|
+
* `ai-review-threads.ts`' own comment states the invariant: the gate is *"the
|
|
295
|
+
* same function the adjudicator builds, over the same file, which is what
|
|
296
|
+
* makes 'already raised' one decision rather than two that agree until they
|
|
297
|
+
* do not"*. They ran BEFORE this existed as two hand-written object literals,
|
|
298
|
+
* and the round-4 review found the predicted consequence: `anchorOccurrences`
|
|
299
|
+
* was added to one of them, so the whole anchor rule was dead in the poster —
|
|
300
|
+
* the half that produces #1168's actual symptom, 11 threads for 3 findings.
|
|
301
|
+
*
|
|
302
|
+
* Returning the reader alongside the gate is the other half. The poster needs
|
|
303
|
+
* `lineTextFor` again for the key it writes INTO each thread, and it used to
|
|
304
|
+
* build a second `checkoutLineText` with a second cache. One reader, one
|
|
305
|
+
* cache, one normalisation — and nothing left for a future field to be wired
|
|
306
|
+
* into unevenly.
|
|
307
|
+
*
|
|
308
|
+
* `gate` is `null` when no thread list is plumbed, which is each command's
|
|
309
|
+
* pre-existing behaviour and is NOT the same as a gate that finds no repeats.
|
|
310
|
+
* `test/ai-review-suppression.test.ts` (AS-15) asserts neither command
|
|
311
|
+
* assembles its own.
|
|
312
|
+
*/
|
|
313
|
+
export function productionSuppression(
|
|
314
|
+
threadsPath: string | undefined,
|
|
315
|
+
root: string,
|
|
316
|
+
): {
|
|
317
|
+
gate: AiReviewSuppressionGate | null;
|
|
318
|
+
lineTextFor: (finding: ReviewFinding) => string | undefined;
|
|
319
|
+
} {
|
|
320
|
+
const reader = checkoutLineReader(root);
|
|
321
|
+
const gate =
|
|
322
|
+
threadsPath === undefined || threadsPath === ""
|
|
323
|
+
? null
|
|
324
|
+
: aiReviewSuppressionGate({
|
|
325
|
+
threads: readOrNull(threadsPath),
|
|
326
|
+
lineTextFor: reader.lineTextFor,
|
|
327
|
+
anchorOccurrences: reader.occurrencesOf,
|
|
328
|
+
});
|
|
329
|
+
return { gate, lineTextFor: reader.lineTextFor };
|
|
330
|
+
}
|
|
331
|
+
|
|
188
332
|
/**
|
|
189
333
|
* THE KEY-SYMMETRY HALF. The text at a finding's cited line, read out of the
|
|
190
334
|
* checkout.
|
|
@@ -208,16 +352,35 @@ export function aiReviewSuppressionGate(inputs: SuppressionInputs): AiReviewSupp
|
|
|
208
352
|
* RESOLVED path and not on the spelling.
|
|
209
353
|
*/
|
|
210
354
|
export function checkoutLineText(root: string): (finding: ReviewFinding) => string | undefined {
|
|
355
|
+
return checkoutLineReader(root).lineTextFor;
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
/**
|
|
359
|
+
* Both readings of the checkout, over ONE file cache.
|
|
360
|
+
*
|
|
361
|
+
* `lineTextFor` is the key-symmetry half documented above. `occurrencesOf`
|
|
362
|
+
* is the distinctiveness half #1861 added: how many lines of a file carry a
|
|
363
|
+
* given normalised text. They share a cache because they read the same files
|
|
364
|
+
* on the same run, and they share `normaliseLineText` with `carryKey`
|
|
365
|
+
* because a counter normalising differently from the key would count
|
|
366
|
+
* occurrences of a string the key never built.
|
|
367
|
+
*
|
|
368
|
+
* `undefined` from `occurrencesOf` is "I could not look" — an unreadable
|
|
369
|
+
* file, an absolute path, an escape out of the checkout — and the caller
|
|
370
|
+
* reads it as not-unique. Zero is a different fact (the file was read and
|
|
371
|
+
* the text is not in it) and is also not one, so both refuse.
|
|
372
|
+
*/
|
|
373
|
+
export function checkoutLineReader(root: string): {
|
|
374
|
+
lineTextFor: (finding: ReviewFinding) => string | undefined;
|
|
375
|
+
occurrencesOf: (file: string, normalisedText: string) => number | undefined;
|
|
376
|
+
} {
|
|
211
377
|
const base = resolve(root);
|
|
212
378
|
const cache = new Map<string, string[] | null>();
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
if (typeof file !== "string" || file === "") return undefined;
|
|
217
|
-
if (typeof line !== "number" || !Number.isInteger(line) || line < 1) return undefined;
|
|
218
|
-
if (isAbsolute(file)) return undefined;
|
|
379
|
+
const linesOf = (file: string): string[] | null => {
|
|
380
|
+
if (typeof file !== "string" || file === "") return null;
|
|
381
|
+
if (isAbsolute(file)) return null;
|
|
219
382
|
const path = resolve(base, file);
|
|
220
|
-
if (path !== base && !path.startsWith(base + sep)) return
|
|
383
|
+
if (path !== base && !path.startsWith(base + sep)) return null;
|
|
221
384
|
if (!cache.has(path)) {
|
|
222
385
|
try {
|
|
223
386
|
cache.set(path, readFileSync(path, "utf-8").split("\n"));
|
|
@@ -225,10 +388,26 @@ export function checkoutLineText(root: string): (finding: ReviewFinding) => stri
|
|
|
225
388
|
cache.set(path, null);
|
|
226
389
|
}
|
|
227
390
|
}
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
391
|
+
return cache.get(path) ?? null;
|
|
392
|
+
};
|
|
393
|
+
return {
|
|
394
|
+
lineTextFor: (finding: ReviewFinding) => {
|
|
395
|
+
const file = finding.file;
|
|
396
|
+
const line = finding.line;
|
|
397
|
+
if (typeof file !== "string") return undefined;
|
|
398
|
+
if (typeof line !== "number" || !Number.isInteger(line) || line < 1) return undefined;
|
|
399
|
+
const lines = linesOf(file);
|
|
400
|
+
if (lines === null) return undefined;
|
|
401
|
+
const text = lines[line - 1];
|
|
402
|
+
return typeof text === "string" && text.trim() !== "" ? text : undefined;
|
|
403
|
+
},
|
|
404
|
+
occurrencesOf: (file: string, normalisedText: string) => {
|
|
405
|
+
const lines = linesOf(file);
|
|
406
|
+
if (lines === null) return undefined;
|
|
407
|
+
let n = 0;
|
|
408
|
+
for (const l of lines) if (normaliseLineText(l) === normalisedText) n++;
|
|
409
|
+
return n;
|
|
410
|
+
},
|
|
232
411
|
};
|
|
233
412
|
}
|
|
234
413
|
|
package/lib/bash-write-guard.ts
CHANGED
|
@@ -803,8 +803,42 @@ export function stripQuoted(s: string): string {
|
|
|
803
803
|
* `stripQuoted` because a quoted PATH is a real argument while a heredoc
|
|
804
804
|
* body never is — it is the document being written, not a word of the
|
|
805
805
|
* command writing it.
|
|
806
|
+
*
|
|
807
|
+
* ## `blankComments`, and the three review rounds behind it (#1741)
|
|
808
|
+
*
|
|
809
|
+
* This function has two readers with OPPOSITE needs, and for a while it
|
|
810
|
+
* tried to serve both with one output.
|
|
811
|
+
*
|
|
812
|
+
* The write guard needs `#`-leading lines blanked. #1176: `# First, check if
|
|
813
|
+
* there's a test workflow-state.json` opened a quote that stayed open across
|
|
814
|
+
* the newline and swallowed the redirect on a later line, so a real write to
|
|
815
|
+
* a protected file read as quoted text. Two commands in a 5,513-command
|
|
816
|
+
* corpus did exactly that, both genuine writes.
|
|
817
|
+
*
|
|
818
|
+
* The filing parser needs them KEPT. `lib/issue-create-override.ts` builds
|
|
819
|
+
* its view from here, so a multi-line `gh issue create --body "…"` arrived
|
|
820
|
+
* with every `##` markdown heading deleted — the dedupe and the symptom scan
|
|
821
|
+
* were reading bodies with holes and nothing reported the loss.
|
|
822
|
+
*
|
|
823
|
+
* **The first three attempts all tried to make ONE output correct for both,
|
|
824
|
+
* by deciding per line whether the `#` was inside a quote. Each was a
|
|
825
|
+
* hand-rolled shell-comment predicate and each had a narrower view than the
|
|
826
|
+
* shell:** a `#` line inside a quote could open a heredoc and delete the
|
|
827
|
+
* lines after it; an inline comment's apostrophe set a carried state that
|
|
828
|
+
* suppressed the next line's blanking; and `echo hi;#…` was a comment the
|
|
829
|
+
* predicate did not recognise. Three rounds, three edges, same shape — so
|
|
830
|
+
* the fourth change is not a fourth predicate. `AGENTS.md` rule 5.
|
|
831
|
+
*
|
|
832
|
+
* **The parameter is the method change.** Blanking is a WRITE-GUARD safety
|
|
833
|
+
* measure; it was never something the filing parser wanted, and no quote
|
|
834
|
+
* tracking is needed to tell the two apart because the CALLER already knows
|
|
835
|
+
* which one it is. #1176 is untouched — the default is the old behaviour and
|
|
836
|
+
* every write-guard path takes it. `heredocView` passes `false` and lets
|
|
837
|
+
* `tokenize`, which implements the shell's comment rule for its own
|
|
838
|
+
* purposes, decide what a comment is on the side of the fence that cares.
|
|
806
839
|
*/
|
|
807
|
-
|
|
840
|
+
|
|
841
|
+
export function stripHeredocs(s: string, blankComments = true): string {
|
|
808
842
|
const lines = s.split('\n');
|
|
809
843
|
const out: string[] = [];
|
|
810
844
|
let i = 0;
|
|
@@ -816,11 +850,22 @@ export function stripHeredocs(s: string): string {
|
|
|
816
850
|
// a later line, so a real write to a protected file read as quoted text.
|
|
817
851
|
// Two commands in a 5,513-command corpus did exactly this, both of them
|
|
818
852
|
// genuine writes. Dropped here rather than in each caller because every
|
|
819
|
-
// arm reaches this function first.
|
|
820
|
-
|
|
821
|
-
|
|
853
|
+
// write-guard arm reaches this function first.
|
|
854
|
+
//
|
|
855
|
+
// **#1741: unconditional again, and the caller chooses.** Three
|
|
856
|
+
// revisions tried to decide per line whether the `#` was inside a
|
|
857
|
+
// quote, so that one output could serve the write guard and the filing
|
|
858
|
+
// parser at once. The docblock above says what each of the three cost.
|
|
859
|
+
// The reader that wants the comment kept now says so.
|
|
860
|
+
const looksComment = /^\s*#/.test(line);
|
|
861
|
+
out.push(looksComment && blankComments ? '' : line); // #1176: the OPERATOR's line is kept.
|
|
822
862
|
i++;
|
|
823
|
-
|
|
863
|
+
// A `#` line cannot open a heredoc. Read from the RAW line and not from
|
|
864
|
+
// what was pushed, so the exemption does not move when `blankComments`
|
|
865
|
+
// does — a `#` line that reaches `heredocDelimiter` deletes everything
|
|
866
|
+
// up to the terminator, and that is the bypass the second revision of
|
|
867
|
+
// this change shipped.
|
|
868
|
+
if (looksComment) continue;
|
|
824
869
|
const delim = heredocDelimiter(line);
|
|
825
870
|
if (!delim) continue;
|
|
826
871
|
// #1184: buffer the body rather than consuming to end-of-input. A
|