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
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The workflow that runs the unmeasured classifier automatically (#1488).
|
|
3
|
+
*
|
|
4
|
+
* #1486 shipped the classifier — `lib/ai-review-unmeasured.ts` — and a
|
|
5
|
+
* recorder somebody has to type, `scripts/record-ai-review-unmeasured.ts`.
|
|
6
|
+
* It works: #1470's ledger comment carries five `"unmeasured": "declined"`
|
|
7
|
+
* beside five intact `"findings": null`. What it does not do is run, and the
|
|
8
|
+
* evidence it reads has a deadline. Actions logs expire, so every round whose
|
|
9
|
+
* log ages out loses its discriminator permanently. The classifier makes the
|
|
10
|
+
* question answerable; until this file it did not make it answered.
|
|
11
|
+
*
|
|
12
|
+
* ## Why this is a second workflow and not a step in the ai-review job
|
|
13
|
+
*
|
|
14
|
+
* The persist step runs MID-JOB, between the reviewer and the adjudicator,
|
|
15
|
+
* and `gh run view --job <id> --log` on a running job answers
|
|
16
|
+
*
|
|
17
|
+
* ```
|
|
18
|
+
* run <id> is still in progress; logs will be available when it is complete
|
|
19
|
+
* ```
|
|
20
|
+
*
|
|
21
|
+
* There is no moment inside that job at which the log exists to be read. Two
|
|
22
|
+
* older readings agree and are now corroboration rather than the argument:
|
|
23
|
+
* `AI_REVIEW_APP_INSTALL_CAUSE`'s docblock (*"A later step cannot read a
|
|
24
|
+
* previous step's stdout"*, #803), and `test/ai-review-payload-reading.test.ts`
|
|
25
|
+
* AC-6, which refuses the action's skip prose anywhere in the generated
|
|
26
|
+
* script because *"the check cannot tell a grep from a mention"*.
|
|
27
|
+
*
|
|
28
|
+
* `workflow_run: completed` fires after the job ends, which is the first
|
|
29
|
+
* moment the log is served.
|
|
30
|
+
*
|
|
31
|
+
* ## It is not a required check and it must never look like one
|
|
32
|
+
*
|
|
33
|
+
* A `workflow_run` workflow reports no status to the pull request, so it
|
|
34
|
+
* cannot gate anything and cannot hang a merge queue. That is why it is the
|
|
35
|
+
* one generated workflow with no `merge_group` trigger —
|
|
36
|
+
* `test/merge-group-trigger.test.ts` narrows its population to the workflows
|
|
37
|
+
* that CAN be required, and `test/ai-review-unmeasured-workflow.test.ts`
|
|
38
|
+
* AC-7 asserts this file is outside it for the stated reason rather than by
|
|
39
|
+
* being forgotten.
|
|
40
|
+
*
|
|
41
|
+
* ## The subscription is DERIVED, not spelled twice
|
|
42
|
+
*
|
|
43
|
+
* `workflow_run.workflows` matches on a workflow's `name:`. Two literals
|
|
44
|
+
* reading `AI Review` in two files is two deciders agreeing, and a rename of
|
|
45
|
+
* one would leave this workflow subscribed to a workflow that no longer
|
|
46
|
+
* exists — firing never, which is indistinguishable from firing and finding
|
|
47
|
+
* nothing to classify. So `AI_REVIEW_WORKFLOW_NAME` is declared here, the
|
|
48
|
+
* generated `ai-review.yml` renders its `name:` from it, and AC-8 asserts
|
|
49
|
+
* the subscription names the workflow the generator actually produced.
|
|
50
|
+
*
|
|
51
|
+
* ## The known boundary: two of these jobs can lose one reading
|
|
52
|
+
*
|
|
53
|
+
* The ledger PATCH is a read-modify-write of one comment. Two review rounds
|
|
54
|
+
* finishing close together fire two of these jobs, both read the ledger
|
|
55
|
+
* before either writes, and the later write can drop the earlier round's
|
|
56
|
+
* discriminator. Recorded rather than papered over, because the obvious fix
|
|
57
|
+
* is worse: a `concurrency:` group holds at most one pending run and
|
|
58
|
+
* **cancels** whatever arrives behind it, so a burst would classify nothing
|
|
59
|
+
* at all — and a cancelled run and a run that found nothing to classify are
|
|
60
|
+
* the same absence, which is this feature's own defect.
|
|
61
|
+
*
|
|
62
|
+
* The recovery is the one #1488 already names. A round that lost its
|
|
63
|
+
* reading still reads NOT_RECORDED, so the next round on that pull request
|
|
64
|
+
* records it, and `scripts/record-ai-review-unmeasured.ts` over a window
|
|
65
|
+
* catches whatever is left while its log still exists.
|
|
66
|
+
*/
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* The `name:` of the workflow that produces the rounds this one classifies.
|
|
70
|
+
*
|
|
71
|
+
* Declared HERE rather than in `lib/scaffold/steps.ts` beside the file it
|
|
72
|
+
* titles, because the subscriber is the side that breaks silently: a
|
|
73
|
+
* workflow whose `workflows:` list names nothing never runs, and a workflow
|
|
74
|
+
* that never runs emits no annotation, no log and no check.
|
|
75
|
+
*/
|
|
76
|
+
export const AI_REVIEW_WORKFLOW_NAME = "AI Review";
|
|
77
|
+
|
|
78
|
+
/** The file this module generates, under `.github/workflows/`. */
|
|
79
|
+
export const AI_REVIEW_UNMEASURED_WORKFLOW_FILE = "ai-review-unmeasured.yml";
|
|
80
|
+
|
|
81
|
+
/** The one job in it. */
|
|
82
|
+
export const AI_REVIEW_UNMEASURED_JOB = "record-unmeasured";
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* The CLI command the step runs.
|
|
86
|
+
*
|
|
87
|
+
* Spelled once, and `lib/cli-commands.ts` must register it or the generated
|
|
88
|
+
* workflow invokes a command `bin/rungate.ts` will refuse — which is #675's
|
|
89
|
+
* defect, a documented interface with nothing behind it.
|
|
90
|
+
*/
|
|
91
|
+
export const AI_REVIEW_UNMEASURED_COMMAND = "record-ai-review-unmeasured";
|
|
92
|
+
|
|
93
|
+
/** `owner/name` of the repository whose ledger comments are being patched. */
|
|
94
|
+
export const AI_REVIEW_UNMEASURED_REPO_VAR = "AI_REVIEW_UNMEASURED_REPO";
|
|
95
|
+
|
|
96
|
+
/** The head commit of the run that just finished. */
|
|
97
|
+
export const AI_REVIEW_UNMEASURED_SHA_VAR = "AI_REVIEW_UNMEASURED_HEAD_SHA";
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* The step's `run:` body.
|
|
101
|
+
*
|
|
102
|
+
* Exported so `test/ai-review-unmeasured-workflow.test.ts` executes THIS
|
|
103
|
+
* text, rather than a paraphrase of it, against a planted ledger and a stub
|
|
104
|
+
* `gh`. A test that asserts on a string the job never runs is the shape
|
|
105
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` opens with.
|
|
106
|
+
*
|
|
107
|
+
* ## Every line of it is about one of two conflations
|
|
108
|
+
*
|
|
109
|
+
* **An absent sha is UNMEASURED, not "no rounds to classify".** A
|
|
110
|
+
* `workflow_run` payload with no `head_sha` is a reading that could not be
|
|
111
|
+
* taken. Exiting 0 silently here would report the same thing as a run that
|
|
112
|
+
* read forty rounds and found them all already recorded.
|
|
113
|
+
*
|
|
114
|
+
* **The recorder's own exit code is this step's.** It exits non-zero when it
|
|
115
|
+
* REFUSED a pull request — an unlocatable fence, a body that would not read
|
|
116
|
+
* back, a failed PATCH — and those are the cases where a round's reading was
|
|
117
|
+
* taken and then dropped, with the log now one day closer to expiry. A
|
|
118
|
+
* `continue-on-error` or a `|| true` here would convert each of them into a
|
|
119
|
+
* green check, which is this feature's own defect reintroduced in its
|
|
120
|
+
* delivery mechanism.
|
|
121
|
+
*
|
|
122
|
+
* Note what is NOT here: no filter on the finished run's conclusion. A
|
|
123
|
+
* declined run SUCCEEDS — the action exits zero on its own
|
|
124
|
+
* workflow-validation guard — so `if: failure()` would skip exactly the
|
|
125
|
+
* population #1455 is about, and `conclusion == 'success'` would admit it by
|
|
126
|
+
* accident rather than on purpose. The classifier reads the log; nothing
|
|
127
|
+
* upstream of it gets to pre-judge which runs are worth reading.
|
|
128
|
+
*/
|
|
129
|
+
export function buildRecordUnmeasuredScript(version: string): string {
|
|
130
|
+
return `set -u
|
|
131
|
+
if [ -z "\${${AI_REVIEW_UNMEASURED_SHA_VAR}}" ]; then
|
|
132
|
+
echo "::warning title=AI review unmeasured UNMEASURED::The workflow_run payload carried no head_sha, so no pull request could be resolved and no round was classified. This is UNMEASURED — not a run with nothing to classify. The two are the same green check from outside, which is the conflation this workflow exists to undo."
|
|
133
|
+
exit 0
|
|
134
|
+
fi
|
|
135
|
+
# The FULL log of each round's own run, never --log-failed: the skip line is
|
|
136
|
+
# emitted by a step that SUCCEEDS, so --log-failed returns 0 bytes on a
|
|
137
|
+
# declined run. Never the clock either. Both readings are measured in
|
|
138
|
+
# lib/ai-review-unmeasured.ts and both are wrong.
|
|
139
|
+
#
|
|
140
|
+
# --write, because a reading taken and not stored is a log fetched one day
|
|
141
|
+
# before it expired and thrown away.
|
|
142
|
+
bunx rungate@${version} ${AI_REVIEW_UNMEASURED_COMMAND} \\
|
|
143
|
+
--repo "\${${AI_REVIEW_UNMEASURED_REPO_VAR}}" \\
|
|
144
|
+
--head-sha "\${${AI_REVIEW_UNMEASURED_SHA_VAR}}" \\
|
|
145
|
+
--write
|
|
146
|
+
`;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
export interface UnmeasuredWorkflowOptions {
|
|
150
|
+
/** The `runs-on:` value, already JSON-quoted by the caller. */
|
|
151
|
+
runsOn: string;
|
|
152
|
+
/** The pinned `oven-sh/setup-bun` action reference. */
|
|
153
|
+
setupBun: string;
|
|
154
|
+
/**
|
|
155
|
+
* The `with:` body of that step, at ten spaces.
|
|
156
|
+
*
|
|
157
|
+
* `setupBunWith` renders the project's single bun declaration and nothing
|
|
158
|
+
* else; the `- uses:` line around it is the caller's, exactly as it is for
|
|
159
|
+
* the other three generated workflows. Taking the composed block instead
|
|
160
|
+
* would put a second renderer of that declaration in the tree, which is
|
|
161
|
+
* the defect #622 removed.
|
|
162
|
+
*/
|
|
163
|
+
setupBunWith: string;
|
|
164
|
+
/** The published harness version the step runs through `bunx`. */
|
|
165
|
+
version: string;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* The whole `ai-review-unmeasured.yml` body.
|
|
170
|
+
*
|
|
171
|
+
* No `actions/checkout`. The step reads nothing out of the repository — it
|
|
172
|
+
* talks to the GitHub API about a repository it is told the name of — and a
|
|
173
|
+
* `workflow_run` workflow that checks out code is the shape that turns a
|
|
174
|
+
* fork's pull request into code execution with a write token.
|
|
175
|
+
*/
|
|
176
|
+
export function buildAiReviewUnmeasuredWorkflow(opts: UnmeasuredWorkflowOptions): string {
|
|
177
|
+
const script = buildRecordUnmeasuredScript(opts.version)
|
|
178
|
+
.trimEnd()
|
|
179
|
+
.split("\n")
|
|
180
|
+
.map(line => (line === "" ? "" : ` ${line}`))
|
|
181
|
+
.join("\n");
|
|
182
|
+
|
|
183
|
+
return `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
|
|
184
|
+
#
|
|
185
|
+
# WHICH KIND of unmeasured each unmeasured AI review round was (#1488).
|
|
186
|
+
#
|
|
187
|
+
# 48 of 117 rounds across the 45 most recent pull requests recorded
|
|
188
|
+
# \`findings: null\` — a round nobody read — and nothing said whether that was
|
|
189
|
+
# the action declining on its own workflow-validation guard (#1455), a run
|
|
190
|
+
# that reviewed and wrote no payload (#1478), or a payload that did not
|
|
191
|
+
# parse. Three facts that cost the same and are fixed differently, and a row
|
|
192
|
+
# that cannot tell them apart is a row nobody can act on.
|
|
193
|
+
#
|
|
194
|
+
# The evidence is the finished run's FULL job log, and it is only readable
|
|
195
|
+
# from OUTSIDE the run: the persist step that writes the round runs mid-job,
|
|
196
|
+
# and the Actions log endpoint refuses a job that is still running. Hence a
|
|
197
|
+
# second workflow on \`workflow_run: completed\` rather than a step.
|
|
198
|
+
#
|
|
199
|
+
# THIS WORKFLOW REPORTS NO STATUS TO THE PULL REQUEST. A \`workflow_run\`
|
|
200
|
+
# workflow cannot be a required check and cannot hang a merge queue, which is
|
|
201
|
+
# why — alone among the generated workflows — it declares no \`merge_group\`
|
|
202
|
+
# trigger. Do not add one: it would fire with no \`workflow_run\` context.
|
|
203
|
+
#
|
|
204
|
+
# IT WRITES, SO READ WHAT IT CAN REACH. The only write is a PATCH of the
|
|
205
|
+
# AI-review ledger comment on the pull request carrying the finished run's
|
|
206
|
+
# head commit. It checks out no code, which is what keeps a fork's pull
|
|
207
|
+
# request from reaching a write token through it.
|
|
208
|
+
name: AI Review Unmeasured
|
|
209
|
+
|
|
210
|
+
on:
|
|
211
|
+
workflow_run:
|
|
212
|
+
# The NAME of the producing workflow, which is the only thing
|
|
213
|
+
# \`workflow_run\` matches on. Generated from one constant shared with the
|
|
214
|
+
# file it names, because a subscription to a renamed workflow fires never
|
|
215
|
+
# and firing never looks exactly like finding nothing to classify.
|
|
216
|
+
workflows: ["${AI_REVIEW_WORKFLOW_NAME}"]
|
|
217
|
+
types: [completed]
|
|
218
|
+
|
|
219
|
+
permissions:
|
|
220
|
+
contents: read
|
|
221
|
+
# Read the finished run's full job log. The whole reading.
|
|
222
|
+
actions: read
|
|
223
|
+
# PATCH the findings ledger comment with the discriminator (#1486).
|
|
224
|
+
pull-requests: write
|
|
225
|
+
|
|
226
|
+
jobs:
|
|
227
|
+
${AI_REVIEW_UNMEASURED_JOB}:
|
|
228
|
+
runs-on: ${opts.runsOn}
|
|
229
|
+
steps:
|
|
230
|
+
- uses: ${opts.setupBun}
|
|
231
|
+
with:
|
|
232
|
+
${opts.setupBunWith}
|
|
233
|
+
- name: Record which kind of unmeasured each round was
|
|
234
|
+
env:
|
|
235
|
+
${AI_REVIEW_UNMEASURED_REPO_VAR}: \${{ github.repository }}
|
|
236
|
+
${AI_REVIEW_UNMEASURED_SHA_VAR}: \${{ github.event.workflow_run.head_sha }}
|
|
237
|
+
# The recorder shells out to \`gh\`. No secret is involved: the
|
|
238
|
+
# run's own token carries exactly the three permissions above.
|
|
239
|
+
GH_TOKEN: \${{ github.token }}
|
|
240
|
+
run: |
|
|
241
|
+
${script}
|
|
242
|
+
`;
|
|
243
|
+
}
|
|
@@ -265,7 +265,137 @@ function revokedSubKeys(
|
|
|
265
265
|
const emitted = new Set(parseSubKeys(generated.lines).blocks.map(s => s.key));
|
|
266
266
|
return parseSubKeys(before.lines)
|
|
267
267
|
.blocks.filter(s => owned.has(s.key) && !emitted.has(s.key))
|
|
268
|
-
.map(s => ({ section, key: s.key, lines: s.lines }));
|
|
268
|
+
.map(s => ({ section, key: s.key, lines: s.lines, reason: "computed" as const }));
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* The sub-key PATHS the generators author outright, dotted (#1148).
|
|
273
|
+
*
|
|
274
|
+
* ## The gap this closes
|
|
275
|
+
*
|
|
276
|
+
* `mergeTopLevelSection` is additive: a sub-key both sides declare keeps the
|
|
277
|
+
* consumer's value. That is right for a local knob and it leaves the harness
|
|
278
|
+
* with no channel for a REMOVAL. #1136 took the `branches:` filter off
|
|
279
|
+
* `on.pull_request` — a filter that silently suppressed CI on every
|
|
280
|
+
* stacked pull request — and no consumer who already had the file could ever
|
|
281
|
+
* receive it, because `pull_request` is a sub-key both sides declare.
|
|
282
|
+
*
|
|
283
|
+
* ## Why this and not the `generated-sha` marker
|
|
284
|
+
*
|
|
285
|
+
* #1148 proposed regenerating a top-level `on:` block whose marker reads
|
|
286
|
+
* VERIFIED, on the reading that a verified marker proves the bytes are the
|
|
287
|
+
* harness's own output. It does not, and `restorableIntro` above already says
|
|
288
|
+
* so: the marker proves the harness WROTE the bytes, not that it AUTHORED
|
|
289
|
+
* them. The merge carries a consumer's value forward and re-stamps, so one
|
|
290
|
+
* re-scaffold launders a hand-edited `on:` into VERIFIED bytes — measured in
|
|
291
|
+
* `test/scaffold-on-trigger-authored.test.ts` AC-5. A fix gated on VERIFIED
|
|
292
|
+
* would delete the customisation #1148's own control demands be kept, and
|
|
293
|
+
* that control could not catch it: a freshly hand-edited fixture reads
|
|
294
|
+
* UNPROVEN, so it never reaches the branch that does the damage.
|
|
295
|
+
*
|
|
296
|
+
* So the discriminator is an explicit claim about the GENERATOR, which the
|
|
297
|
+
* harness can make, rather than an inference from a digest, which it cannot.
|
|
298
|
+
* `HARNESS_COMPUTED_SUBKEYS` is the same move one level up (#923).
|
|
299
|
+
*
|
|
300
|
+
* ## Why a module constant and not a per-file map
|
|
301
|
+
*
|
|
302
|
+
* #923 is keyed by FILE because an unscoped revoker would make
|
|
303
|
+
* `permissions.id-token` withdrawable in a workflow whose generator never
|
|
304
|
+
* emits it under any config — a consumer's own grant removed by a feature
|
|
305
|
+
* that was not reasoning about their file. That risk is handled structurally
|
|
306
|
+
* here instead: `withdrawAuthoredPaths` withdraws a leaf only where the
|
|
307
|
+
* generated file still emits the PARENT sub-key, so a generator silent about
|
|
308
|
+
* `pull_request` makes no claim on the consumer's copy of it. The emission
|
|
309
|
+
* gate is the scope, and it is tighter than a filename would be because it
|
|
310
|
+
* tracks what the generator actually did rather than which file it wrote.
|
|
311
|
+
*
|
|
312
|
+
* Narrow on purpose. `on.push.branches` is deliberately absent: a `push`
|
|
313
|
+
* filter asks which branches earn a run on their own, which is a different
|
|
314
|
+
* question, and #1136 left it alone for that reason.
|
|
315
|
+
*/
|
|
316
|
+
export const HARNESS_AUTHORED_PATHS: ReadonlySet<string> = new Set(["on.pull_request.branches"]);
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* A sub-block split into the comments introducing it and the key line onward.
|
|
320
|
+
*
|
|
321
|
+
* `parseSubKeys` emits a block as `[...pending comments, keyLine, ...body]` —
|
|
322
|
+
* the comments it was holding back come FIRST and the key line is not
|
|
323
|
+
* `lines[0]`. Re-applying the parser to such a block without this split reads
|
|
324
|
+
* the first comment as the key line, slices it off, and then finds the key
|
|
325
|
+
* itself at the body's base indent: the leaves come back as the block's own
|
|
326
|
+
* name and the real leaves are invisible.
|
|
327
|
+
*
|
|
328
|
+
* That is not hypothetical. The first draft of `withdrawAuthoredPaths` did
|
|
329
|
+
* exactly this, passed eleven cases, and withdrew NOTHING from the three real
|
|
330
|
+
* generated workflows — every one of which introduces `pull_request:` with a
|
|
331
|
+
* comment block. The unit fixtures had no comment above the trigger, so they
|
|
332
|
+
* measured a shape the generator never emits.
|
|
333
|
+
*/
|
|
334
|
+
function splitBlockIntro(lines: string[]): [string[], string[]] {
|
|
335
|
+
const at = lines.findIndex(l => l.trim() !== "" && !l.trimStart().startsWith("#"));
|
|
336
|
+
return at <= 0 ? [[], lines] : [lines.slice(0, at), lines.slice(at)];
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
/**
|
|
340
|
+
* The consumer's section with every authored leaf the generator has stopped
|
|
341
|
+
* emitting taken out, and the record of what went (#1148).
|
|
342
|
+
*
|
|
343
|
+
* Reads both sides through the same `parseSubKeys` the rest of the merge uses
|
|
344
|
+
* — applied twice, because the binding takes a key line followed by its body
|
|
345
|
+
* and a sub-block is that shape once `splitBlockIntro` has taken the
|
|
346
|
+
* introducing comments off it. One parser, so the thing removed and the thing
|
|
347
|
+
* reported removed cannot be two different readings (#834).
|
|
348
|
+
*/
|
|
349
|
+
function withdrawAuthoredPaths(
|
|
350
|
+
section: string,
|
|
351
|
+
before: Section,
|
|
352
|
+
generated: Section,
|
|
353
|
+
): { section: Section; withdrawn: RevokedSubKey[] } {
|
|
354
|
+
// The same scalar guard `mergeTopLevelSection` opens with: `on: [push]` has
|
|
355
|
+
// no sub-keys to withdraw and no way to express the removal if it did.
|
|
356
|
+
if (!/^[A-Za-z_][A-Za-z0-9_.\-]*:\s*(#.*)?$/.test(before.lines[0])) {
|
|
357
|
+
return { section: before, withdrawn: [] };
|
|
358
|
+
}
|
|
359
|
+
const parsed = parseSubKeys(before.lines);
|
|
360
|
+
const generatedByKey = new Map(parseSubKeys(generated.lines).blocks.map(s => [s.key, s] as const));
|
|
361
|
+
const withdrawn: RevokedSubKey[] = [];
|
|
362
|
+
|
|
363
|
+
const blocks = parsed.blocks.map(block => {
|
|
364
|
+
const gen = generatedByKey.get(block.key);
|
|
365
|
+
// THE EMISSION GATE. A generator that does not emit this trigger is making
|
|
366
|
+
// no statement about the consumer's copy of it.
|
|
367
|
+
if (gen === undefined) return block;
|
|
368
|
+
const [intro, fromKey] = splitBlockIntro(block.lines);
|
|
369
|
+
const consumerLeaves = parseSubKeys(fromKey);
|
|
370
|
+
const emitted = new Set(parseSubKeys(splitBlockIntro(gen.lines)[1]).blocks.map(s => s.key));
|
|
371
|
+
const gone = consumerLeaves.blocks.filter(
|
|
372
|
+
leaf => HARNESS_AUTHORED_PATHS.has(`${section}.${block.key}.${leaf.key}`) && !emitted.has(leaf.key),
|
|
373
|
+
);
|
|
374
|
+
if (gone.length === 0) return block;
|
|
375
|
+
for (const leaf of gone) {
|
|
376
|
+
withdrawn.push({
|
|
377
|
+
section: `${section}.${block.key}`,
|
|
378
|
+
key: leaf.key,
|
|
379
|
+
lines: leaf.lines,
|
|
380
|
+
reason: "authored",
|
|
381
|
+
});
|
|
382
|
+
}
|
|
383
|
+
const dropped = new Set(gone.map(l => l.key));
|
|
384
|
+
return {
|
|
385
|
+
...block,
|
|
386
|
+
lines: [
|
|
387
|
+
...intro,
|
|
388
|
+
...consumerLeaves.head,
|
|
389
|
+
...consumerLeaves.blocks.filter(l => !dropped.has(l.key)).flatMap(l => l.lines),
|
|
390
|
+
],
|
|
391
|
+
};
|
|
392
|
+
});
|
|
393
|
+
|
|
394
|
+
if (withdrawn.length === 0) return { section: before, withdrawn: [] };
|
|
395
|
+
return {
|
|
396
|
+
section: { ...before, lines: [...parsed.head, ...blocks.flatMap(b => b.lines)] },
|
|
397
|
+
withdrawn,
|
|
398
|
+
};
|
|
269
399
|
}
|
|
270
400
|
|
|
271
401
|
/**
|
|
@@ -337,12 +467,28 @@ const NO_COMPUTED_SUBKEYS: ComputedSubKeys = new Map();
|
|
|
337
467
|
|
|
338
468
|
/** A sub-key the merge withdrew because the generator stopped emitting it (#923). */
|
|
339
469
|
export interface RevokedSubKey {
|
|
340
|
-
/**
|
|
470
|
+
/**
|
|
471
|
+
* The key it sat under: a top-level key for a `computed` withdrawal, and a
|
|
472
|
+
* dotted path (`on.pull_request`) for an `authored` one, which reaches a
|
|
473
|
+
* level deeper.
|
|
474
|
+
*/
|
|
341
475
|
section: string;
|
|
342
476
|
/** The sub-key itself. */
|
|
343
477
|
key: string;
|
|
344
478
|
/** Its lines as they stood in the consumer's file, comment block included. */
|
|
345
479
|
lines: string[];
|
|
480
|
+
/**
|
|
481
|
+
* Which ownership claim took it away (#1148).
|
|
482
|
+
*
|
|
483
|
+
* Carried rather than inferred at the reporting layer, because the two
|
|
484
|
+
* withdrawals have different causes and therefore different advice.
|
|
485
|
+
* `computed` means the project's `ci` config stopped producing a derived
|
|
486
|
+
* grant; `authored` means the GENERATOR stopped emitting a path the harness
|
|
487
|
+
* names as its own. Reporting the second with the first's sentence sends a
|
|
488
|
+
* consumer to a config key that has nothing to do with what was removed —
|
|
489
|
+
* correct-but-misdescribed, which is the expensive kind of accurate.
|
|
490
|
+
*/
|
|
491
|
+
reason: "computed" | "authored";
|
|
346
492
|
}
|
|
347
493
|
|
|
348
494
|
/**
|
|
@@ -773,9 +919,22 @@ export function mergeManagedWorkflowRecording(
|
|
|
773
919
|
// to make impossible.
|
|
774
920
|
let merged: string[];
|
|
775
921
|
if (gen !== undefined && !declined.has(section.key)) {
|
|
776
|
-
|
|
922
|
+
// An authored path the generator has stopped emitting goes FIRST, for
|
|
923
|
+
// the reason #923 gives for ordering its own withdrawal before the
|
|
924
|
+
// merge: the sub-key merge's job is to carry what the generator newly
|
|
925
|
+
// emits into the consumer's section, and running it over a section that
|
|
926
|
+
// still holds a withdrawn leaf would have it decide ownership of a line
|
|
927
|
+
// that is on its way out.
|
|
928
|
+
//
|
|
929
|
+
// Inside the `!declined` arm for the reason #923 is: a consumer who has
|
|
930
|
+
// named this top-level key in `ci.workflowOverrides` has taken the whole
|
|
931
|
+
// block back, and reaching into it is the deletion-without-a-route that
|
|
932
|
+
// #839's hatch exists to make impossible.
|
|
933
|
+
const authored = withdrawAuthoredPaths(section.key, consumer, gen);
|
|
934
|
+
revoked.push(...authored.withdrawn);
|
|
935
|
+
const withdrawn = revokedSubKeys(section.key, authored.section, gen, computed);
|
|
777
936
|
revoked.push(...withdrawn);
|
|
778
|
-
merged = mergeTopLevelSection(withoutRevoked(
|
|
937
|
+
merged = mergeTopLevelSection(withoutRevoked(authored.section, withdrawn), gen);
|
|
779
938
|
} else {
|
|
780
939
|
merged = consumer.lines;
|
|
781
940
|
}
|
|
@@ -156,6 +156,20 @@ export const OWNED_FILES: OwnedFile[] = [
|
|
|
156
156
|
customize: "Set `ci.vertex` in `.claude/rungate/config.json` to authenticate on Vertex with Workload Identity Federation; add your own jobs alongside the generated `ai-review` job",
|
|
157
157
|
avoid: "Don't edit the generated `ai-review` job",
|
|
158
158
|
},
|
|
159
|
+
{
|
|
160
|
+
// #1488. The `workflow_run: completed` half of the AI review: it runs
|
|
161
|
+
// the unmeasured classifier after the review job ends, which is the
|
|
162
|
+
// first moment that job's log is served. Declared the moment the
|
|
163
|
+
// generator learned to write it — the whole of #631's lesson one file
|
|
164
|
+
// over is that ownership has to travel with the bytes, and a workflow
|
|
165
|
+
// the generator writes and this list does not name is a consumer's hand
|
|
166
|
+
// edit overwritten in silence.
|
|
167
|
+
path: ".github/workflows/ai-review-unmeasured.yml",
|
|
168
|
+
strategy: "job-preserving",
|
|
169
|
+
servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
|
|
170
|
+
customize: "Set `ci.runner` in `.claude/rungate/config.json`; add your own jobs alongside the generated `record-unmeasured` job",
|
|
171
|
+
avoid: "Don't edit the generated `record-unmeasured` job, and don't give it a `merge_group` trigger — it reports no status to the pull request and cannot be a required check",
|
|
172
|
+
},
|
|
159
173
|
{
|
|
160
174
|
// `regenerate` until #655, and the declaration was never consulted:
|
|
161
175
|
// `generateAgentBriefsStep` called `writeFileSync` directly, so the row
|