rungate 0.8.1 → 0.8.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/BashWriteGuard.hook.ts +19 -0
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/VerifyPhaseLock.hook.ts +68 -11
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +1249 -0
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-file-read.ts +17 -3
- package/lib/bash-write-guard.ts +2165 -51
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +12 -0
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/distribution-standing.ts +75 -4
- package/lib/failure-intake.ts +12 -4
- package/lib/file-claims.ts +335 -0
- package/lib/file-extensions.ts +81 -0
- package/lib/finding-arbiter.ts +1489 -0
- package/lib/finding-jury.ts +584 -0
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +259 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +160 -0
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/interpreters.ts +64 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +122 -11
- package/lib/issue-filing-gate.ts +1602 -0
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +10 -0
- package/lib/project-state-shape.ts +56 -5
- package/lib/publish-window.ts +287 -0
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +65 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1157 -18
- package/lib/scaffold/ai-review-step.ts +4672 -85
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/managed-workflow.ts +163 -4
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +462 -108
- package/lib/scanner.ts +10 -3
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +16 -0
- package/lib/ticked-sc-symbols.ts +361 -0
- package/lib/validators/spec-validators.ts +28 -2
- package/lib/workflow-actions.ts +18 -0
- package/package.json +3 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +542 -0
- package/scripts/audit-specs.ts +225 -23
- package/scripts/create-sc.ts +11 -0
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/generate-code-map.ts +6 -3
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +12 -0
- package/scripts/sync-sc-status.ts +93 -8
package/lib/cli-commands.ts
CHANGED
|
@@ -20,14 +20,46 @@
|
|
|
20
20
|
* not distributable, and recommended hand-scaffolding a project. Both
|
|
21
21
|
* readings of the repo were wrong, which is the state a single source fixes.
|
|
22
22
|
*
|
|
23
|
-
* ##
|
|
23
|
+
* ## A command script is run as an ENTRY MODULE, not imported
|
|
24
24
|
*
|
|
25
|
-
* None of them guards on `import.meta.main
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
25
|
+
* This section used to read: "None of them guards on `import.meta.main`
|
|
26
|
+
* … Adding an `import.meta.main` guard to any of them would silently turn its
|
|
27
|
+
* subcommand into a no-op, so `test/cli-contract.test.ts` runs every command
|
|
28
|
+
* for real." The hazard was named exactly. Both mitigations were false.
|
|
29
|
+
*
|
|
30
|
+
* Three scripts acquired the guard — and `import.meta.main` is FALSE for a
|
|
31
|
+
* dynamically imported module, so `await import(script)` loaded them, ran
|
|
32
|
+
* nothing, and exited 0. Measured on `3da782dc`, dispatcher against the same
|
|
33
|
+
* script run directly, in bytes of output:
|
|
34
|
+
*
|
|
35
|
+
* audit-specs 0 vs 2092 silent
|
|
36
|
+
* sync-spec-tests 0 vs 1254 silent
|
|
37
|
+
* extract-constraints 0 vs 57 silent
|
|
38
|
+
* ai-review-findings 270 vs 270 reached — see below
|
|
39
|
+
*
|
|
40
|
+
* Three of ten commands reported success having done nothing. The second
|
|
41
|
+
* mitigation is why nobody saw it: `test/cli-contract.test.ts` ran ONE
|
|
42
|
+
* command for real, `create-sc --list`, and its comment names this defect in
|
|
43
|
+
* as many words. One member of the population was enough to hold the
|
|
44
|
+
* assertion up while the other nine went unmeasured — the battery varied the
|
|
45
|
+
* dispatcher and held the COMMAND fixed, and the defect was on that axis
|
|
46
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, seventh shape).
|
|
47
|
+
*
|
|
48
|
+
* `scripts/ai-review-findings.ts` is the one that still worked, and it is the
|
|
49
|
+
* prior art rather than the exception: #675 hit this, documented the
|
|
50
|
+
* mechanism in its docblock, and worked around it by calling `main`
|
|
51
|
+
* unconditionally from a wrapper. That fixed one command and left the
|
|
52
|
+
* dispatcher as it was.
|
|
53
|
+
*
|
|
54
|
+
* So the fix is here, in the one place that decides how a command is invoked,
|
|
55
|
+
* rather than three more wrappers — a per-script workaround is three more
|
|
56
|
+
* places to forget, and the forgetting reads as the command succeeding.
|
|
57
|
+
* `runCommandScript` spawns the script with the running bun binary, which
|
|
58
|
+
* makes it the entry module and `import.meta.main` true, exactly as
|
|
59
|
+
* `bun scripts/audit-specs.ts` already was. A guard is now the normal thing
|
|
60
|
+
* for a script to have, instead of a trap.
|
|
30
61
|
*/
|
|
62
|
+
import { spawnSync } from "child_process";
|
|
31
63
|
|
|
32
64
|
export interface CliCommand {
|
|
33
65
|
/** The script this runs, relative to the package root. Must be in `files`. */
|
|
@@ -111,14 +143,35 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
|
|
|
111
143
|
// because a scaffolded consumer has no copy of rungate's sources at a path
|
|
112
144
|
// the workflow could hardcode. This registry is the path (#675).
|
|
113
145
|
//
|
|
114
|
-
// No `projectRootFlag`: the
|
|
115
|
-
// outside the checkout by design
|
|
116
|
-
// `--project-root <cwd>` would arrive as a
|
|
117
|
-
//
|
|
146
|
+
// No `projectRootFlag`: the arguments are the findings payload and the
|
|
147
|
+
// changed-path list, both of which live outside the checkout by design
|
|
148
|
+
// (`RUNNER_TEMP`), and appending `--project-root <cwd>` would arrive as a
|
|
149
|
+
// third positional. That absence is now load-bearing twice over — it is
|
|
150
|
+
// also why the changed-path list may safely BE a positional.
|
|
118
151
|
"ai-review-findings": {
|
|
119
152
|
script: "scripts/ai-review-findings.ts",
|
|
120
153
|
summary: "Adjudicate an AI review's findings payload — exits non-zero on a blocking finding",
|
|
121
|
-
|
|
154
|
+
// The second positional is the pull request's changed-path list, one path
|
|
155
|
+
// per line (#1204, #1435). It is OPTIONAL: no generated job supplies it
|
|
156
|
+
// yet, and an absent list reports its own state rather than switching a
|
|
157
|
+
// check off in silence.
|
|
158
|
+
usage: "rungate ai-review-findings <path-to-findings.json> [<path-to-changed-files.txt>]",
|
|
159
|
+
},
|
|
160
|
+
// Registered for the same reason `ai-review-findings` is, one workflow
|
|
161
|
+
// over (#1488): the generated `ai-review-unmeasured.yml` runs in a
|
|
162
|
+
// consumer's repository, which has no copy of rungate's sources at any
|
|
163
|
+
// path the workflow could name. This registry is the path.
|
|
164
|
+
//
|
|
165
|
+
// No `projectRootFlag`: every argument is a flag and the script reads no
|
|
166
|
+
// project tree at all — it talks to the GitHub API about a repository it
|
|
167
|
+
// is told the name of, so an appended `--project-root <cwd>` would be
|
|
168
|
+
// refused by `parseArgs` as an unknown argument.
|
|
169
|
+
"record-ai-review-unmeasured": {
|
|
170
|
+
script: "scripts/record-ai-review-unmeasured.ts",
|
|
171
|
+
summary: "Record WHICH kind of unmeasured each unmeasured AI-review round was",
|
|
172
|
+
usage:
|
|
173
|
+
"rungate record-ai-review-unmeasured --repo <owner/name> " +
|
|
174
|
+
"[--head-sha <sha> | --pr <n> | --limit <n>] [--write]",
|
|
122
175
|
},
|
|
123
176
|
};
|
|
124
177
|
|
|
@@ -127,6 +180,65 @@ export function publishedCommands(): string[] {
|
|
|
127
180
|
return Object.keys(CLI_COMMANDS);
|
|
128
181
|
}
|
|
129
182
|
|
|
183
|
+
/** What a dispatched command returned, and what it wrote when captured. */
|
|
184
|
+
export interface CommandRun {
|
|
185
|
+
/** The code to exit with. Never `null` — a killed or unspawnable child is non-zero. */
|
|
186
|
+
code: number;
|
|
187
|
+
/** Present only when `capture` was asked for. */
|
|
188
|
+
stdout?: string;
|
|
189
|
+
stderr?: string;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* Run a command's script AS AN ENTRY MODULE, and return the code to exit with.
|
|
194
|
+
*
|
|
195
|
+
* THE single binding for how a subcommand is invoked. The dispatcher calls
|
|
196
|
+
* nothing else, so there is one place to mutate and a test can watch the
|
|
197
|
+
* invocation stop being an entry-module run — see the docblock at the top of
|
|
198
|
+
* this file for the three commands that were silently no-ops when this was
|
|
199
|
+
* `await import(script)`.
|
|
200
|
+
*
|
|
201
|
+
* `process.execPath` rather than the string `"bun"`: the child must be the
|
|
202
|
+
* same runtime the parent is already running under, and a consumer's PATH is
|
|
203
|
+
* not ours to assume.
|
|
204
|
+
*
|
|
205
|
+
* ## Every way this can fail to run is non-zero
|
|
206
|
+
*
|
|
207
|
+
* `spawnSync` reports `status: null` for a child that never produced an exit
|
|
208
|
+
* code — killed by a signal, or never spawned at all. Mapping that to 0 would
|
|
209
|
+
* reinstate the defect this function exists to remove, one layer out: a
|
|
210
|
+
* command that did not run, reporting success.
|
|
211
|
+
*
|
|
212
|
+
* ONE `??`, not a `signal` branch beside it. The first version had both, and
|
|
213
|
+
* the separate branch made `?? 1` unreachable — no input could distinguish it
|
|
214
|
+
* from `?? 0`, so the case asserting "a script that cannot run is a failure"
|
|
215
|
+
* passed under that mutation. It was green because a missing script makes
|
|
216
|
+
* *bun* exit non-zero, which is a real status the `??` never sees
|
|
217
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, third shape: an assertion
|
|
218
|
+
* holding for a reason that is not the one claimed). Collapsed to one path,
|
|
219
|
+
* a SIGKILLed child reaches it and the mutation is caught.
|
|
220
|
+
*/
|
|
221
|
+
export function runCommandScript(
|
|
222
|
+
script: string,
|
|
223
|
+
args: string[],
|
|
224
|
+
opts?: { capture?: boolean },
|
|
225
|
+
): CommandRun {
|
|
226
|
+
const r = spawnSync(process.execPath, [script, ...args], {
|
|
227
|
+
stdio: opts?.capture ? "pipe" : "inherit",
|
|
228
|
+
encoding: "utf-8",
|
|
229
|
+
});
|
|
230
|
+
const captured = opts?.capture ? { stdout: r.stdout ?? "", stderr: r.stderr ?? "" } : {};
|
|
231
|
+
// A spawn error is not a verdict the script reached. Say so on stderr —
|
|
232
|
+
// under `stdio: "inherit"` the child wrote nothing and a bare exit code
|
|
233
|
+
// would be the silent failure again, one layer out.
|
|
234
|
+
if (r.error) {
|
|
235
|
+
const why = `rungate: could not run ${script}: ${r.error.message}`;
|
|
236
|
+
if (!opts?.capture) console.error(why);
|
|
237
|
+
return { code: 1, ...captured, ...(opts?.capture ? { stderr: why } : {}) };
|
|
238
|
+
}
|
|
239
|
+
return { code: r.status ?? 1, ...captured };
|
|
240
|
+
}
|
|
241
|
+
|
|
130
242
|
export function helpText(): string {
|
|
131
243
|
const rows = Object.entries(CLI_COMMANDS).map(
|
|
132
244
|
([name, c]) => ` ${name.padEnd(20)}${c.summary}\n ${" ".repeat(20)}${c.usage}`,
|
|
@@ -143,6 +255,135 @@ export function helpText(): string {
|
|
|
143
255
|
].join("\n");
|
|
144
256
|
}
|
|
145
257
|
|
|
258
|
+
/**
|
|
259
|
+
* The routing table for `.claude/rules/commands-routing.md`, generated.
|
|
260
|
+
*
|
|
261
|
+
* #1309 in one function. The scaffold routed specs, docs, key files and
|
|
262
|
+
* managed files and did not route COMMANDS, so a command reached an agent
|
|
263
|
+
* only if somebody had hand-written a row for it in `AGENTS.md`'s Commands
|
|
264
|
+
* table — four of ten, and the four were the four somebody happened to need
|
|
265
|
+
* in 2026-09. Measured over the always-loaded surface on `11a60f67`, seven of
|
|
266
|
+
* the ten were named in no file an agent loads, including `audit-specs`,
|
|
267
|
+
* whose whole job is reporting spec status. An agent spent a day
|
|
268
|
+
* hand-building a tracking mechanism that was already a subcommand.
|
|
269
|
+
*
|
|
270
|
+
* Generated from `CLI_COMMANDS` rather than written, because a hand-list is
|
|
271
|
+
* precisely what failed: the generated table is present and plausible, reads
|
|
272
|
+
* as complete, and nothing in it signals that six more commands exist.
|
|
273
|
+
*
|
|
274
|
+
* ## No usage strings here, deliberately
|
|
275
|
+
*
|
|
276
|
+
* `helpText()` carries them and `--help` prints them. This table is the
|
|
277
|
+
* always-loaded surface, which is at 93% of `SURFACE_BUDGET_BYTES` — adding
|
|
278
|
+
* ten usage lines would cost ~600 bytes to save one `--help`, and the thing
|
|
279
|
+
* an agent cannot discover by running a command is that the command EXISTS.
|
|
280
|
+
* The summary is what makes `audit-specs` findable by someone thinking "which
|
|
281
|
+
* criteria are covered"; the arguments are one invocation away.
|
|
282
|
+
*/
|
|
283
|
+
export function commandRoutingTable(): string {
|
|
284
|
+
const rows = Object.entries(CLI_COMMANDS).map(
|
|
285
|
+
([name, c]) => `| \`${name}\` | ${c.summary} |`,
|
|
286
|
+
);
|
|
287
|
+
return ["| Command | What it does |", "|---------|--------------|", ...rows].join("\n");
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* Every code span in a markdown document — fenced blocks and inline spans.
|
|
292
|
+
*
|
|
293
|
+
* `commandNamed` searches this slice rather than the whole document, and the
|
|
294
|
+
* slice is the point: `.claude/rules/harness-managed.md` says "a re-scaffold
|
|
295
|
+
* rewrites them" and `AGENTS.md` says "Re-scaffold", and neither of those
|
|
296
|
+
* routes anyone to the `scaffold` command. A command name is a thing you
|
|
297
|
+
* TYPE, so the region where it counts is the region reserved for things you
|
|
298
|
+
* type (`.claude/rules/checks-must-be-able-to-fail.md`, "search the slice,
|
|
299
|
+
* not the document").
|
|
300
|
+
*/
|
|
301
|
+
export function codeSpans(markdown: string): string {
|
|
302
|
+
const fenced = markdown.match(/```[\s\S]*?```/g) ?? [];
|
|
303
|
+
const withoutFences = markdown.replace(/```[\s\S]*?```/g, "\n");
|
|
304
|
+
const inline = withoutFences.match(/`[^`\n]+`/g) ?? [];
|
|
305
|
+
return [...fenced, ...inline].join("\n");
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* Is `name` typed, as a whole word, anywhere in this document's code spans?
|
|
310
|
+
*
|
|
311
|
+
* `.` is in the boundary class alongside `-` so that `scripts/convert-spec.ts`
|
|
312
|
+
* does not count as routing the `convert-spec` COMMAND. It is the script the
|
|
313
|
+
* command runs, named in the form a consumer cannot use, and treating a path
|
|
314
|
+
* as a routing is how `convert-spec` read as present while `bunx rungate
|
|
315
|
+
* convert-spec` was documented nowhere.
|
|
316
|
+
*
|
|
317
|
+
* The direction this is allowed to be wrong in is toward reporting a command
|
|
318
|
+
* UNROUTED: a routing form nobody thought of costs one generated row, and the
|
|
319
|
+
* other direction is a command that reads as discoverable and is not — which
|
|
320
|
+
* is the whole of #1309.
|
|
321
|
+
*/
|
|
322
|
+
export function commandNamed(markdown: string, name: string): boolean {
|
|
323
|
+
const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
324
|
+
return new RegExp(`(?<![a-z0-9.-])${escaped}(?![a-z0-9.-])`).test(codeSpans(markdown));
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
/** One always-loaded document, as `measureSurface` reports the population. */
|
|
328
|
+
export interface SurfaceDoc {
|
|
329
|
+
file: string;
|
|
330
|
+
text: string;
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
export interface CommandRoutingReading {
|
|
334
|
+
/** UNMEASURED FAILS. An empty search is not a clean one. */
|
|
335
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
336
|
+
unmeasuredReasons: string[];
|
|
337
|
+
/** Registered commands named nowhere in the surface. */
|
|
338
|
+
unrouted: string[];
|
|
339
|
+
filesSearched: number;
|
|
340
|
+
/** Bytes of code span searched. Zero is the instrument, not the answer. */
|
|
341
|
+
spanBytes: number;
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
/**
|
|
345
|
+
* Which registered commands are named nowhere an agent loads.
|
|
346
|
+
*
|
|
347
|
+
* Takes the surface as an argument rather than deriving it, because the
|
|
348
|
+
* population of always-loaded files is already decided once, by
|
|
349
|
+
* `measureSurface` in `scripts/check-instruction-surface.ts`. A second
|
|
350
|
+
* definition here would be two deciders that agree, and the one that matters
|
|
351
|
+
* — whether a `paths:` key has quietly moved a rule out of the launch surface
|
|
352
|
+
* — would be invisible to a check that had its own idea of what loads.
|
|
353
|
+
*
|
|
354
|
+
* The three UNMEASURED states are all ways this returns `[]` while having
|
|
355
|
+
* searched nothing: no documents, no code spans in any of them, or an empty
|
|
356
|
+
* registry. Each of them reads exactly like a tree where every command is
|
|
357
|
+
* routed (`.claude/rules/config-access.md`).
|
|
358
|
+
*/
|
|
359
|
+
export function commandRoutingReading(surface: SurfaceDoc[]): CommandRoutingReading {
|
|
360
|
+
const reasons: string[] = [];
|
|
361
|
+
const spans = surface.map(d => codeSpans(d.text)).join("\n");
|
|
362
|
+
const spanBytes = Buffer.byteLength(spans, "utf-8");
|
|
363
|
+
const names = publishedCommands();
|
|
364
|
+
|
|
365
|
+
if (surface.length === 0) {
|
|
366
|
+
reasons.push("the always-loaded surface came back empty — no documents were searched");
|
|
367
|
+
}
|
|
368
|
+
if (spanBytes === 0) {
|
|
369
|
+
reasons.push(
|
|
370
|
+
`${surface.length} document(s) yielded no code spans at all; a command name is only ` +
|
|
371
|
+
`counted inside one, so every command would read as unrouted for an instrument reason`,
|
|
372
|
+
);
|
|
373
|
+
}
|
|
374
|
+
if (names.length === 0) {
|
|
375
|
+
reasons.push("CLI_COMMANDS is empty — nothing to route, which is not the same as routed");
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
return {
|
|
379
|
+
reading: reasons.length > 0 ? "UNMEASURED" : "MEASURED",
|
|
380
|
+
unmeasuredReasons: reasons,
|
|
381
|
+
unrouted: names.filter(n => !surface.some(d => commandNamed(d.text, n))),
|
|
382
|
+
filesSearched: surface.length,
|
|
383
|
+
spanBytes,
|
|
384
|
+
};
|
|
385
|
+
}
|
|
386
|
+
|
|
146
387
|
/**
|
|
147
388
|
* Every `bunx <pkg> <cmd>` invocation in a markdown command table.
|
|
148
389
|
*
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A closing keyword GitHub will never act on (#1362).
|
|
3
|
+
*
|
|
4
|
+
* `.claude/rules/ship-workflow.md` says to put `Fixes #<N>` in the PR body and
|
|
5
|
+
* let the merge close the issue. What it cannot say, because nothing in the
|
|
6
|
+
* tree measured it until now, is that **a closing keyword inside a code span
|
|
7
|
+
* is inert**. GitHub parses the body as markdown and does not link a reference
|
|
8
|
+
* it finds inside backticks or a fenced block, so the PR merges, the author
|
|
9
|
+
* sees the sentence they wrote, and the issue stays open.
|
|
10
|
+
*
|
|
11
|
+
* Measured on `hornjason/pai-harness` at 2026-10-23T15:31Z: of **50** open
|
|
12
|
+
* issues, **27** carry at least one merged pull request cross-reference, from
|
|
13
|
+
* **65** distinct merged pull requests. Running this detector over all 65
|
|
14
|
+
* produced **one** report — PR #1208, naming #1148 and #1157. Its second line
|
|
15
|
+
* is the keyword and the number wrapped in backticks, the pull request says in
|
|
16
|
+
* prose that the work is done and verified, and `closingIssuesReferences` is
|
|
17
|
+
* empty. #1148 was rescued by the squash commit subject `fix(#1148): …`;
|
|
18
|
+
* #1157 was not in the title and is still open.
|
|
19
|
+
*
|
|
20
|
+
* ## Why this reports the INERT ones and not the live ones
|
|
21
|
+
*
|
|
22
|
+
* A function that decided which references DO close an issue would be a second
|
|
23
|
+
* decider competing with GitHub's own parser, and the two would agree on
|
|
24
|
+
* almost every input — `.claude/rules/checks-must-be-able-to-fail.md`'s fourth
|
|
25
|
+
* shape, where no behavioural test can tell a dead guard from a live one.
|
|
26
|
+
*
|
|
27
|
+
* This reports only what a caller can check against the API's own answer: the
|
|
28
|
+
* caller already knows `closingIssuesReferences`, and an empty one beside a
|
|
29
|
+
* keyword the author clearly meant is a disagreement worth refusing on. The
|
|
30
|
+
* question asked here is "did you write something that looks like it closes an
|
|
31
|
+
* issue and does not", which GitHub does not answer anywhere.
|
|
32
|
+
*
|
|
33
|
+
* ## Why the keyword must be ADJACENT to the number
|
|
34
|
+
*
|
|
35
|
+
* This repository writes negations constantly — `.claude/rules/` tells agents
|
|
36
|
+
* never to put a closing keyword next to an issue number they are not closing,
|
|
37
|
+
* and they comply by writing the denial in prose instead.
|
|
38
|
+
*
|
|
39
|
+
* The negative control, over the same 65 merged pull requests: loosening
|
|
40
|
+
* "adjacent" to "within 40 characters" produced **21** candidates, of which
|
|
41
|
+
* the same two were true and **19** were false. Three kinds of false, and only
|
|
42
|
+
* the first is a negation:
|
|
43
|
+
*
|
|
44
|
+
* - a denial — `Closes nothing — #523 stays open`, `Fixes nothing on its own —
|
|
45
|
+
* leaving #713 open`, `Neither issue is closed by this PR`;
|
|
46
|
+
* - prose about a DIFFERENT issue — `| #1281 | … | fixed, merged as #1288 |`;
|
|
47
|
+
* - a window artefact, where the 40 characters end mid-number and the
|
|
48
|
+
* candidate names an issue nobody wrote.
|
|
49
|
+
*
|
|
50
|
+
* So adjacency is not a convenience, it is the whole precision of the check,
|
|
51
|
+
* and widening it is the cheapest wrong fix available here: on the only corpus
|
|
52
|
+
* that exists, the loosened rule is wrong nineteen times out of twenty-one.
|
|
53
|
+
*/
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* The verbs GitHub acts on, in one declaring position.
|
|
57
|
+
*
|
|
58
|
+
* Taken from GitHub's documented list rather than invented. Every form is
|
|
59
|
+
* spelled out instead of stemmed: `close|closes|closed` and not `close[sd]?`
|
|
60
|
+
* with a comment, because a reader checking this against the documentation
|
|
61
|
+
* compares a list to a list.
|
|
62
|
+
*/
|
|
63
|
+
export const CLOSING_KEYWORDS: readonly string[] = [
|
|
64
|
+
"close",
|
|
65
|
+
"closes",
|
|
66
|
+
"closed",
|
|
67
|
+
"fix",
|
|
68
|
+
"fixes",
|
|
69
|
+
"fixed",
|
|
70
|
+
"resolve",
|
|
71
|
+
"resolves",
|
|
72
|
+
"resolved",
|
|
73
|
+
];
|
|
74
|
+
|
|
75
|
+
/** One closing keyword that is present in the prose and inert in the markup. */
|
|
76
|
+
export interface InertClosingReference {
|
|
77
|
+
/** The issue number the author wrote. */
|
|
78
|
+
issue: number;
|
|
79
|
+
/** The keyword as they spelled it, case preserved, for the message. */
|
|
80
|
+
keyword: string;
|
|
81
|
+
/** Which markup swallowed it. */
|
|
82
|
+
reason: "code-span" | "fenced-block";
|
|
83
|
+
/** The matched text, so a message can quote what to change. */
|
|
84
|
+
text: string;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Byte ranges the GitHub markdown parser will not scan for references.
|
|
89
|
+
*
|
|
90
|
+
* Fenced blocks are taken first and their ranges removed from the input the
|
|
91
|
+
* span scanner sees, because a fence contains backticks by definition and a
|
|
92
|
+
* span scanner run over the raw body would pair the fence delimiters with each
|
|
93
|
+
* other and report nonsense.
|
|
94
|
+
*/
|
|
95
|
+
function maskedRanges(body: string): { start: number; end: number; reason: InertClosingReference["reason"] }[] {
|
|
96
|
+
const out: { start: number; end: number; reason: InertClosingReference["reason"] }[] = [];
|
|
97
|
+
const fenced = /^[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?^[ \t]*\1[ \t]*$/gm;
|
|
98
|
+
for (const m of body.matchAll(fenced)) {
|
|
99
|
+
out.push({ start: m.index!, end: m.index! + m[0].length, reason: "fenced-block" });
|
|
100
|
+
}
|
|
101
|
+
const inFence = (i: number) => out.some(r => i >= r.start && i < r.end);
|
|
102
|
+
// Single-line code spans. `[^`\n]+` keeps a span from spilling across a line,
|
|
103
|
+
// which is what an unmatched backtick in ordinary prose would otherwise do —
|
|
104
|
+
// and an unmatched backtick is common in a body that quotes shell.
|
|
105
|
+
for (const m of body.matchAll(/(`+)([^`\n]+?)\1/g)) {
|
|
106
|
+
if (inFence(m.index!)) continue;
|
|
107
|
+
out.push({ start: m.index!, end: m.index! + m[0].length, reason: "code-span" });
|
|
108
|
+
}
|
|
109
|
+
return out;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Closing keywords in `body` that name an issue and will not fire.
|
|
114
|
+
*
|
|
115
|
+
* Deduplicated by issue number: a body that names the same issue twice inside
|
|
116
|
+
* backticks is one mistake, not two, and a message listing it twice reads as
|
|
117
|
+
* two problems to fix.
|
|
118
|
+
*/
|
|
119
|
+
export function inertClosingReferences(body: string): InertClosingReference[] {
|
|
120
|
+
if (!body) return [];
|
|
121
|
+
const ranges = maskedRanges(body);
|
|
122
|
+
const pattern = new RegExp(`\\b(${CLOSING_KEYWORDS.join("|")})\\b[ \\t]*:?[ \\t]*#(\\d+)\\b`, "gi");
|
|
123
|
+
const seen = new Set<number>();
|
|
124
|
+
const out: InertClosingReference[] = [];
|
|
125
|
+
for (const m of body.matchAll(pattern)) {
|
|
126
|
+
const hit = ranges.find(r => m.index! >= r.start && m.index! < r.end);
|
|
127
|
+
if (!hit) continue;
|
|
128
|
+
const issue = Number.parseInt(m[2]!, 10);
|
|
129
|
+
if (seen.has(issue)) continue;
|
|
130
|
+
seen.add(issue);
|
|
131
|
+
out.push({ issue, keyword: m[1]!, reason: hit.reason, text: m[0] });
|
|
132
|
+
}
|
|
133
|
+
return out;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* The refusal text.
|
|
138
|
+
*
|
|
139
|
+
* It names the issue, the markup and the remedy, because
|
|
140
|
+
* `.claude/rules/self-referential-tests.md` is explicit that a check without a
|
|
141
|
+
* remedy is an obstacle. The remedy here is one character of punctuation, so
|
|
142
|
+
* the message says exactly which.
|
|
143
|
+
*/
|
|
144
|
+
export function inertClosingMessage(refs: InertClosingReference[], prNumber: number): string {
|
|
145
|
+
const rows = refs
|
|
146
|
+
.map(r => ` ${r.text} — inside a ${r.reason}, so GitHub never linked it (issue #${r.issue})`)
|
|
147
|
+
.join("\n");
|
|
148
|
+
return (
|
|
149
|
+
`PR #${prNumber} has no closingIssuesReferences, and its body names ` +
|
|
150
|
+
`${refs.length === 1 ? "an issue" : "issues"} with a closing keyword that the markdown ` +
|
|
151
|
+
`parser cannot see:\n${rows}\n\n` +
|
|
152
|
+
`GitHub does not read a reference inside backticks or a fenced block, so this ` +
|
|
153
|
+
`pull request records no link to them and the merge will not close them. ` +
|
|
154
|
+
`Something else still might — PR #1208 carried two inert references and its squash ` +
|
|
155
|
+
`commit subject, "fix(#1148): …", closed that one anyway, while #1157 was not in ` +
|
|
156
|
+
`the title and stayed open after the body said in prose it was done. Do not rely ` +
|
|
157
|
+
`on that: it is a conventional-commit prefix that happens to be a closing keyword. ` +
|
|
158
|
+
`Remove the backticks from that line, then re-read the field rather than the body: ` +
|
|
159
|
+
`gh pr view ${prNumber} --json closingIssuesReferences. If the reference is ` +
|
|
160
|
+
`deliberately inert because you are quoting a keyword rather than using one, move ` +
|
|
161
|
+
`the quote so the number is not adjacent to the verb.`
|
|
162
|
+
);
|
|
163
|
+
}
|
package/lib/conformity.ts
CHANGED
|
@@ -10,6 +10,7 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSyn
|
|
|
10
10
|
import { tmpdir } from "os";
|
|
11
11
|
import type { Dirent } from "fs";
|
|
12
12
|
import { collectSpecFiles } from "./spec-files";
|
|
13
|
+
import { mayWrite, readDerivedDeclaration, skipLine } from "./derived-spec";
|
|
13
14
|
import {
|
|
14
15
|
ambiguousSpecNames,
|
|
15
16
|
readSpecRequirements,
|
|
@@ -328,6 +329,17 @@ export function flipPassingCheckboxes(): number {
|
|
|
328
329
|
for (const [specPath, ids] of byFile) {
|
|
329
330
|
if (!existsSync(specPath)) continue;
|
|
330
331
|
let content = readFileSync(specPath, "utf-8");
|
|
332
|
+
|
|
333
|
+
// #1286: the second checkbox flipper, asked BEFORE any counting. A tick
|
|
334
|
+
// on a spec a generator owns is discarded at the next regeneration,
|
|
335
|
+
// after breaking whatever pins the file — and a criterion counted as
|
|
336
|
+
// flipped in a file nobody wrote is a number that means nothing.
|
|
337
|
+
const derived = readDerivedDeclaration(content);
|
|
338
|
+
if (!mayWrite(derived)) {
|
|
339
|
+
console.warn(skipLine(specPath, derived));
|
|
340
|
+
continue;
|
|
341
|
+
}
|
|
342
|
+
|
|
331
343
|
let changed = false;
|
|
332
344
|
for (const id of ids) {
|
|
333
345
|
const unchecked = `- [ ] ${id}:`;
|
package/lib/create-sc.ts
CHANGED
|
@@ -14,10 +14,12 @@ import type { ScNamespaceReading, SourceReading } from "./sc-id-cross-tree";
|
|
|
14
14
|
import { readScNamespace } from "./sc-id-cross-tree";
|
|
15
15
|
import type { ScReservation, ScReservationReading } from "./sc-reservations";
|
|
16
16
|
import {
|
|
17
|
+
blocksInNamespace,
|
|
17
18
|
lowestFreeInBlock,
|
|
18
19
|
readScReservations,
|
|
20
|
+
SC_NAMESPACE,
|
|
19
21
|
RESERVATION_REFUSAL,
|
|
20
|
-
|
|
22
|
+
reservationsFor,
|
|
21
23
|
reservedCeiling,
|
|
22
24
|
reservedIdCount,
|
|
23
25
|
SC_RESERVATIONS_PATH,
|
|
@@ -347,11 +349,16 @@ export function takenScNumbers(
|
|
|
347
349
|
export function scReservationLeg(reading: ScReservationReading): SourceReading {
|
|
348
350
|
const label = `SC reservation store (${SC_RESERVATIONS_PATH})`;
|
|
349
351
|
if (reading.status === "read") {
|
|
352
|
+
// SC blocks only, on both numbers. `found` is documented as the size of
|
|
353
|
+
// the space the store removes from the allocator, and since #1363 an
|
|
354
|
+
// `FG`/`AR` block removes none of it — counting those would make the leg
|
|
355
|
+
// report a reading it did not take.
|
|
356
|
+
const sc = blocksInNamespace(reading.blocks, SC_NAMESPACE);
|
|
350
357
|
return {
|
|
351
|
-
label: `${label}: ${
|
|
358
|
+
label: `${label}: ${sc.length} block(s)`,
|
|
352
359
|
kind: "reservations",
|
|
353
360
|
status: "read",
|
|
354
|
-
found: reservedIdCount(
|
|
361
|
+
found: reservedIdCount(sc),
|
|
355
362
|
};
|
|
356
363
|
}
|
|
357
364
|
return {
|
|
@@ -386,16 +393,42 @@ export function allocateAgainstReservations(
|
|
|
386
393
|
owner: string | null,
|
|
387
394
|
taken: ReadonlySet<number>,
|
|
388
395
|
): number {
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
396
|
+
// SC blocks only, and the filter lives HERE rather than at the call site
|
|
397
|
+
// for the reason the docblock gives: this function is the single binding a
|
|
398
|
+
// mutation battery points at, and a filter applied by the caller would be a
|
|
399
|
+
// reservation-aware decision made somewhere this one cannot see.
|
|
400
|
+
//
|
|
401
|
+
// An `FG-45..60` block is not a claim on `SC-45..60`. Before #1363 it was
|
|
402
|
+
// read as one, which both pushed a stranger's allocation above 60 and
|
|
403
|
+
// answered the FG owner's next `create-sc` out of a block that describes
|
|
404
|
+
// different ids entirely.
|
|
405
|
+
blocks = blocksInNamespace(blocks, SC_NAMESPACE);
|
|
406
|
+
// EVERY block the owner holds, in declaration order, not the first one
|
|
407
|
+
// (#1541). Nothing has ever forbidden one owner from declaring two blocks
|
|
408
|
+
// and `overlapFault` does not refuse disjoint ones, so `find` was making a
|
|
409
|
+
// silent choice: with `100-102` spent and `200-299` empty under the same
|
|
410
|
+
// owner, the allocator refused and told the reader to WIDEN `100-102` — the
|
|
411
|
+
// one repair that cannot work, pointed at a block the owner had already
|
|
412
|
+
// moved past.
|
|
413
|
+
//
|
|
414
|
+
// Declaration order rather than lowest-first, because the order is a thing
|
|
415
|
+
// the person writing the store chose and `readScReservations` preserves it.
|
|
416
|
+
// Sorting here would relocate where existing owners allocate, which is a
|
|
417
|
+
// change to every block in the store dressed up as a bug fix.
|
|
418
|
+
const mine = reservationsFor(blocks, owner);
|
|
419
|
+
if (mine.length > 0) {
|
|
420
|
+
for (const block of mine) {
|
|
421
|
+
const free = lowestFreeInBlock(block, taken);
|
|
422
|
+
if (free !== null) return free;
|
|
397
423
|
}
|
|
398
|
-
|
|
424
|
+
// Only now is the owner out of room. The message names every block,
|
|
425
|
+
// because naming one invites widening it while another sits empty — and
|
|
426
|
+
// after #1541 that is no longer a hypothetical reader error.
|
|
427
|
+
const spent = mine.map(b => `${b.from}-${b.to}`).join(", ");
|
|
428
|
+
throw new ScReservationExhaustedError(
|
|
429
|
+
`every SC block reserved to ${mine[0].owner} (${spent}) is spent — ` +
|
|
430
|
+
`widen one in ${SC_RESERVATIONS_PATH} rather than allocating outside it`,
|
|
431
|
+
);
|
|
399
432
|
}
|
|
400
433
|
// No block of your own. The floor is still correct about what is WRITTEN;
|
|
401
434
|
// it knows nothing about what is DECLARED, so it is raised past every block
|