rungate 0.8.25 → 0.8.27
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/gates/.gate-salt +1 -1
- package/lib/board-mirror.ts +28 -9
- package/lib/cli-commands.ts +11 -3
- package/lib/finding-promotion.ts +57 -0
- package/lib/issue-repair.ts +124 -0
- package/lib/scaffold/managed-workflow.ts +112 -26
- package/lib/scaffold/owned-files.ts +16 -6
- package/lib/scaffold/specs-placed-workflow.ts +252 -0
- package/lib/scaffold/steps.ts +26 -1
- package/lib/spec-placement.ts +357 -11
- package/package.json +2 -1
- package/scripts/board-conformance.ts +259 -26
- package/scripts/board-mirror.ts +72 -22
- package/scripts/board-scope.ts +149 -0
- package/scripts/board-snapshot.ts +136 -15
- package/scripts/create-sc.ts +34 -2
- package/scripts/plan-issues.ts +221 -14
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `.github/workflows/specs-placed.yml`, generated — SC-2780, ADR-018 Decision 1.
|
|
3
|
+
*
|
|
4
|
+
* A push to main that changes `specs/` runs every opted-in family through the
|
|
5
|
+
* engine with no command typed by hand: milestones from each family's
|
|
6
|
+
* placement table, each open issue moved into the phase its criteria hold,
|
|
7
|
+
* the phase-order links, the queue label, and the board's Criteria column.
|
|
8
|
+
*
|
|
9
|
+
* ## The families are read at RUN time, from the specs
|
|
10
|
+
*
|
|
11
|
+
* `rungate plan-issues --families` prints the opted-in families, one
|
|
12
|
+
* `<prefix><TAB><spec>` line each. It is the same reading `plan-issues
|
|
13
|
+
* --place` takes, so the loop and the placement never disagree about which
|
|
14
|
+
* specs are on the board, and a newly opted-in spec needs no re-scaffold.
|
|
15
|
+
* A spec whose `board:` block or placement table cannot be read makes that
|
|
16
|
+
* command refuse, so the run goes red by name instead of skipping the spec.
|
|
17
|
+
*
|
|
18
|
+
* ## The order is the one each step needs
|
|
19
|
+
*
|
|
20
|
+
* plan-spec per family, so every phase has its milestone
|
|
21
|
+
* plan-issues --place, so issues sit in the phase their criteria hold
|
|
22
|
+
* plan-deps per family, so the links follow the issues' NEW milestones
|
|
23
|
+
* board-mirror --queue-label, because a milestone set by GITHUB_TOKEN
|
|
24
|
+
* fires no `milestoned` event, so phase-order.yml never sees it
|
|
25
|
+
* board-mirror the Criteria column on the board
|
|
26
|
+
*
|
|
27
|
+
* Placing before `plan-deps` is ADR-019 Decision 2: #1722's links follow its
|
|
28
|
+
* move into Phase 10 in the same run.
|
|
29
|
+
*
|
|
30
|
+
* ## It never writes while an earlier ADR placement is running
|
|
31
|
+
*
|
|
32
|
+
* One merge often changes both `specs/` and an ADR, which fires this and
|
|
33
|
+
* `adr-accepted.yml` together, and both write milestones and links (ADR-018,
|
|
34
|
+
* "Not decided here"). A shared `concurrency:` group would serialise them
|
|
35
|
+
* but cancels whatever is pending behind the running run. A cancelled
|
|
36
|
+
* `adr-accepted` run is an accepted ADR whose plan is never placed, with
|
|
37
|
+
* nothing saying so. So this workflow keeps a group of its own, which only
|
|
38
|
+
* cancels its own pending runs, and each of those re-reads the whole tree.
|
|
39
|
+
* Its first step then waits until no `adr-accepted` run created before it is
|
|
40
|
+
* still unfinished.
|
|
41
|
+
*
|
|
42
|
+
* ## It calls the published CLI
|
|
43
|
+
*
|
|
44
|
+
* Like every generated workflow it runs `bunx rungate@<version>`, so the
|
|
45
|
+
* commands it calls must be in a published release before this file is
|
|
46
|
+
* (`docs/guides/RELEASING.md`, "A command a generated workflow calls ships
|
|
47
|
+
* BEFORE the workflow that calls it"). `--families` and `--place` shipped in
|
|
48
|
+
* 0.8.26.
|
|
49
|
+
*/
|
|
50
|
+
|
|
51
|
+
import { ADR_ACCEPTED_WORKFLOW_FILE } from "./adr-accepted-workflow";
|
|
52
|
+
|
|
53
|
+
/** The file this module generates, under `.github/workflows/`. */
|
|
54
|
+
export const SPECS_PLACED_WORKFLOW_FILE = "specs-placed.yml";
|
|
55
|
+
|
|
56
|
+
/** The one job in it. */
|
|
57
|
+
export const SPECS_PLACED_JOB = "run-the-engine";
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Every command the job calls, in run order. Each must be registered in
|
|
61
|
+
* `lib/cli-commands.ts`, or the workflow calls a command `bin/rungate.ts`
|
|
62
|
+
* refuses (#675's defect).
|
|
63
|
+
*/
|
|
64
|
+
export const SPECS_PLACED_COMMANDS = ["plan-issues", "plan-spec", "plan-deps", "board-mirror"] as const;
|
|
65
|
+
|
|
66
|
+
/** Its own group: it cancels only its own pending runs, each of which re-reads the tree. */
|
|
67
|
+
export const SPECS_PLACED_GROUP = "specs-placed";
|
|
68
|
+
|
|
69
|
+
/** How long the first step waits for an earlier ADR placement, in 20-second polls. */
|
|
70
|
+
export const WAIT_POLLS = 90;
|
|
71
|
+
|
|
72
|
+
export interface SpecsPlacedWorkflowOptions {
|
|
73
|
+
/** The `runs-on:` value, already JSON-quoted by the caller. */
|
|
74
|
+
runsOn: string;
|
|
75
|
+
/** The pinned `actions/checkout` reference. */
|
|
76
|
+
checkout: string;
|
|
77
|
+
/** The pinned `oven-sh/setup-bun` reference. */
|
|
78
|
+
setupBun: string;
|
|
79
|
+
/** The `with:` body of that step, at ten spaces — the project's single bun declaration (#622). */
|
|
80
|
+
setupBunWith: string;
|
|
81
|
+
/** The step's `env:` block, from `setupBunEnv` (#2039). */
|
|
82
|
+
setupBunEnv: string;
|
|
83
|
+
/** The published harness version every step runs through `bunx`. */
|
|
84
|
+
version: string;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* The wait step's script. The GitHub API lists the ADR workflow's runs; any
|
|
89
|
+
* not yet `completed` and created before this run is waited for. Runs created
|
|
90
|
+
* AFTER this one are not, so the two workflows can never wait on each other.
|
|
91
|
+
* Every page is read: the list is newest-first, so an earlier run still going
|
|
92
|
+
* falls off page one once 100 newer runs exist. A list it cannot read fails
|
|
93
|
+
* the step, through `pipefail`, rather than reading as "none unfinished".
|
|
94
|
+
*/
|
|
95
|
+
export function buildWaitScript(): string {
|
|
96
|
+
return `set -euo pipefail
|
|
97
|
+
mine=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --jq .created_at)
|
|
98
|
+
for poll in $(seq 1 ${WAIT_POLLS}); do
|
|
99
|
+
earlier=$(gh api --paginate "repos/$GITHUB_REPOSITORY/actions/workflows/${ADR_ACCEPTED_WORKFLOW_FILE}/runs?per_page=100" --jq ".workflow_runs[] | select(.status != \\"completed\\" and .created_at < \\"$mine\\") | .id" | paste -sd ' ' -)
|
|
100
|
+
if [ -z "$earlier" ]; then
|
|
101
|
+
echo "No earlier ${ADR_ACCEPTED_WORKFLOW_FILE} run is unfinished; going ahead."
|
|
102
|
+
exit 0
|
|
103
|
+
fi
|
|
104
|
+
echo "Waiting for ${ADR_ACCEPTED_WORKFLOW_FILE} run(s) $earlier to finish (poll $poll of ${WAIT_POLLS})."
|
|
105
|
+
sleep 20
|
|
106
|
+
done
|
|
107
|
+
echo "::error::${ADR_ACCEPTED_WORKFLOW_FILE} run(s) $earlier are still unfinished after $((${WAIT_POLLS} * 20 / 60)) minutes, so this run wrote nothing rather than write the board beside them. Re-run it once they finish."
|
|
108
|
+
exit 1`;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* A loop over the families file, one command per family. It reads the file on
|
|
113
|
+
* descriptor 3, so a command inside the loop that reads standard input cannot
|
|
114
|
+
* swallow the families after it. One family's refusal does not stop the next;
|
|
115
|
+
* the step exits red at the end, naming every family that refused.
|
|
116
|
+
*/
|
|
117
|
+
export function buildFamilyLoop(version: string, command: (cli: string) => string, what: string): string {
|
|
118
|
+
const cli = `bunx rungate@${version}`;
|
|
119
|
+
return `set -uo pipefail
|
|
120
|
+
refused=""
|
|
121
|
+
while IFS=$'\\t' read -r prefix spec <&3; do
|
|
122
|
+
[ -n "$prefix" ] || continue
|
|
123
|
+
echo "== $prefix ($spec)"
|
|
124
|
+
if ! ${command(cli)}; then
|
|
125
|
+
refused="$refused [$prefix]"
|
|
126
|
+
fi
|
|
127
|
+
done 3< families.tsv
|
|
128
|
+
if [ -n "$refused" ]; then
|
|
129
|
+
echo "::error::${what} refused for$refused. Every other family was still run."
|
|
130
|
+
exit 1
|
|
131
|
+
fi`;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** The whole `specs-placed.yml` body. */
|
|
135
|
+
export function buildSpecsPlacedWorkflow(opts: SpecsPlacedWorkflowOptions): string {
|
|
136
|
+
const cli = `bunx rungate@${opts.version}`;
|
|
137
|
+
const indent = (script: string) => script.split("\n").map(l => (l === "" ? "" : ` ${l}`)).join("\n");
|
|
138
|
+
const milestones = buildFamilyLoop(
|
|
139
|
+
opts.version,
|
|
140
|
+
c => `${c} plan-spec "$spec" --repo "$GITHUB_REPOSITORY" --prefix "$prefix" --write`,
|
|
141
|
+
"plan-spec",
|
|
142
|
+
);
|
|
143
|
+
const links = buildFamilyLoop(
|
|
144
|
+
opts.version,
|
|
145
|
+
c => `${c} plan-deps --repo "$GITHUB_REPOSITORY" --milestone-prefix "$prefix" --write`,
|
|
146
|
+
"plan-deps",
|
|
147
|
+
);
|
|
148
|
+
|
|
149
|
+
return `# Managed by rungate — do not edit. Opt a spec in with
|
|
150
|
+
# board: { scope: active, prefix: <Name> } in its frontmatter and give it a
|
|
151
|
+
# placement table; nothing here names a spec.
|
|
152
|
+
#
|
|
153
|
+
# SC-2780 (ADR-018 Decision 1): a push to main that changes specs/ runs every
|
|
154
|
+
# opted-in family through the engine, with no command typed by hand.
|
|
155
|
+
#
|
|
156
|
+
# plan-issues --families which specs are on the board, read at run time
|
|
157
|
+
# plan-spec each family's milestones
|
|
158
|
+
# plan-issues --place each open issue into the phase its criteria hold
|
|
159
|
+
# plan-deps each family's phase-order links, after the moves
|
|
160
|
+
# board-mirror the queue label, then the Criteria column
|
|
161
|
+
#
|
|
162
|
+
# Every command is idempotent, so a re-run writes only what is missing.
|
|
163
|
+
#
|
|
164
|
+
# CREDENTIALS, SPLIT BY STEP. Issue, milestone, label and link writes use the
|
|
165
|
+
# job's own GITHUB_TOKEN. RUNGATE_PROJECT_TOKEN reaches only the board step.
|
|
166
|
+
name: Specs changed — run every opted-in family through the engine
|
|
167
|
+
|
|
168
|
+
on:
|
|
169
|
+
push:
|
|
170
|
+
branches: [main]
|
|
171
|
+
paths: ["specs/**"]
|
|
172
|
+
|
|
173
|
+
permissions:
|
|
174
|
+
contents: read
|
|
175
|
+
# Milestones, issues, labels and blocked-by links.
|
|
176
|
+
issues: write
|
|
177
|
+
# The wait step lists adr-accepted.yml's runs.
|
|
178
|
+
actions: read
|
|
179
|
+
|
|
180
|
+
# Its own group, never adr-accepted's: a shared group cancels the run pending
|
|
181
|
+
# behind the running one, and a cancelled adr-accepted run is a plan that is
|
|
182
|
+
# never placed. The wait step below keeps the two from writing at once.
|
|
183
|
+
concurrency:
|
|
184
|
+
group: ${SPECS_PLACED_GROUP}
|
|
185
|
+
cancel-in-progress: false
|
|
186
|
+
|
|
187
|
+
jobs:
|
|
188
|
+
${SPECS_PLACED_JOB}:
|
|
189
|
+
runs-on: ${opts.runsOn}
|
|
190
|
+
steps:
|
|
191
|
+
- name: Wait for an earlier ADR placement to finish
|
|
192
|
+
env:
|
|
193
|
+
GH_TOKEN: \${{ github.token }}
|
|
194
|
+
run: |
|
|
195
|
+
${indent(buildWaitScript())}
|
|
196
|
+
|
|
197
|
+
- uses: ${opts.checkout}
|
|
198
|
+
- uses: ${opts.setupBun}
|
|
199
|
+
with:
|
|
200
|
+
${opts.setupBunWith}
|
|
201
|
+
${opts.setupBunEnv}
|
|
202
|
+
# No token: the package is fetched before any step that holds one.
|
|
203
|
+
- id: families
|
|
204
|
+
name: Which specs are on the board?
|
|
205
|
+
run: |
|
|
206
|
+
${cli} plan-issues --families > families.tsv
|
|
207
|
+
echo "Opted-in families:"
|
|
208
|
+
cat families.tsv
|
|
209
|
+
if [ -s families.tsv ]; then echo "any=true" >> "$GITHUB_OUTPUT"; else echo "any=false" >> "$GITHUB_OUTPUT"; fi
|
|
210
|
+
|
|
211
|
+
- name: Milestones from each family's placement table
|
|
212
|
+
if: steps.families.outputs.any == 'true'
|
|
213
|
+
env:
|
|
214
|
+
GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
|
|
215
|
+
run: |
|
|
216
|
+
${indent(milestones)}
|
|
217
|
+
|
|
218
|
+
- name: Each open issue into the phase its criteria hold
|
|
219
|
+
if: steps.families.outputs.any == 'true'
|
|
220
|
+
env:
|
|
221
|
+
GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
|
|
222
|
+
run: ${cli} plan-issues --place --repo "$GITHUB_REPOSITORY" --write
|
|
223
|
+
|
|
224
|
+
# \`!cancelled()\`: each of these reads the whole tracker and writes only
|
|
225
|
+
# what is missing, so it never depends on an earlier step succeeding
|
|
226
|
+
# (#2239). The run is still red when one of those failed.
|
|
227
|
+
- name: Phase-order links for each family
|
|
228
|
+
if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
|
|
229
|
+
env:
|
|
230
|
+
GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
|
|
231
|
+
run: |
|
|
232
|
+
${indent(links)}
|
|
233
|
+
|
|
234
|
+
- name: Queue label on every opted-in family's phase issue
|
|
235
|
+
if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
|
|
236
|
+
env:
|
|
237
|
+
GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
|
|
238
|
+
run: ${cli} board-mirror --queue-label --repo "$GITHUB_REPOSITORY" --write
|
|
239
|
+
|
|
240
|
+
- name: Criteria column on the board
|
|
241
|
+
if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
|
|
242
|
+
env:
|
|
243
|
+
GITHUB_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
|
|
244
|
+
PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
|
|
245
|
+
run: |
|
|
246
|
+
if [ -z "$PROJECT_ID" ]; then
|
|
247
|
+
echo "::error::UNMEASURED — RUNGATE_PROJECT_ID is not set, so there is no board to write."
|
|
248
|
+
exit 1
|
|
249
|
+
fi
|
|
250
|
+
${cli} board-mirror --project "$PROJECT_ID" --write
|
|
251
|
+
`;
|
|
252
|
+
}
|
package/lib/scaffold/steps.ts
CHANGED
|
@@ -49,6 +49,7 @@ import {
|
|
|
49
49
|
buildAiReviewUnmeasuredWorkflow,
|
|
50
50
|
} from "./ai-review-unmeasured-workflow";
|
|
51
51
|
import { buildAdrAcceptedWorkflow } from "./adr-accepted-workflow";
|
|
52
|
+
import { buildSpecsPlacedWorkflow } from "./specs-placed-workflow";
|
|
52
53
|
import { buildClosingReferencesWorkflow } from "./closing-references-workflow";
|
|
53
54
|
import { buildIntakeWorkflow } from "./intake-workflow";
|
|
54
55
|
import { buildBoardReadyWorkflow } from "./board-ready-workflow";
|
|
@@ -2908,6 +2909,16 @@ function revocationActions(label: string, revoked: readonly RevokedSubKey[]): st
|
|
|
2908
2909
|
const topLevel = r.section.split(".")[0];
|
|
2909
2910
|
const keep =
|
|
2910
2911
|
`Name \`${topLevel}\` in \`ci.workflowOverrides\` to keep it, and re-scaffold.`;
|
|
2912
|
+
// #2292: an authored path brought to the generator's value is not a
|
|
2913
|
+
// withdrawal, and calling it one would tell the consumer something was
|
|
2914
|
+
// taken away when something was written.
|
|
2915
|
+
if (r.reason === "asserted") {
|
|
2916
|
+
return (
|
|
2917
|
+
`REWRITTEN: ${label} now declares \`${r.section}: ${r.key}\` as this version of the ` +
|
|
2918
|
+
`generator writes it — the harness authors that path, so a stale or hand-set value ` +
|
|
2919
|
+
`there is replaced on every scaffold. ${keep}`
|
|
2920
|
+
);
|
|
2921
|
+
}
|
|
2911
2922
|
return r.reason === "authored"
|
|
2912
2923
|
? `REVOKED: ${label} no longer declares \`${r.section}: ${r.key}\` — the harness ` +
|
|
2913
2924
|
`authors that path and this version of the generator does not emit it, so the ` +
|
|
@@ -4380,6 +4391,8 @@ ${setupBunEnv(" ")}
|
|
|
4380
4391
|
: `permissions:\n contents: read\n # Mint the OIDC token Workload Identity Federation exchanges (#631).\n id-token: write\n # Count this pull request's previous AI Review runs — the round budget (#1168).\n actions: read\n${ledgerPermission}`;
|
|
4381
4392
|
|
|
4382
4393
|
const aiReviewYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
|
|
4394
|
+
# The trigger types under on.pull_request are the harness's and are rewritten
|
|
4395
|
+
# on every scaffold; add your own triggers or jobs alongside (#2292).
|
|
4383
4396
|
#
|
|
4384
4397
|
${buildOutcomesHeader(vertex)}#
|
|
4385
4398
|
# This job is deliberately unconditional. A job skipped by a condition reports
|
|
@@ -4492,6 +4505,18 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
|
|
|
4492
4505
|
milestonePrefix: boardInputs.milestonePrefix,
|
|
4493
4506
|
});
|
|
4494
4507
|
|
|
4508
|
+
// SC-2780, ADR-018 Decision 1: a push to main that changes specs/ runs
|
|
4509
|
+
// every opted-in family through the engine. The families are read at run
|
|
4510
|
+
// time by the published CLI, so nothing here names a spec.
|
|
4511
|
+
const specsPlacedYml = buildSpecsPlacedWorkflow({
|
|
4512
|
+
runsOn,
|
|
4513
|
+
checkout: actionRef("actions/checkout"),
|
|
4514
|
+
setupBun: actionRef("oven-sh/setup-bun"),
|
|
4515
|
+
setupBunWith: bunStep,
|
|
4516
|
+
setupBunEnv: setupBunEnv(" "),
|
|
4517
|
+
version: harnessVersion(),
|
|
4518
|
+
});
|
|
4519
|
+
|
|
4495
4520
|
// #2045, ADR-014 row 2: the closing-references check, generated so a
|
|
4496
4521
|
// consumer gets ADR-013 rule 9 step 4 and this repository's copy is the
|
|
4497
4522
|
// generated one. It calls the published CLI, at the generating version.
|
|
@@ -4555,7 +4580,7 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
|
|
|
4555
4580
|
// lib/conformity.ts reads back, and the two are held together by
|
|
4556
4581
|
// test/ai-review-workflow.test.ts AC-1, which looks for the constant's
|
|
4557
4582
|
// filename in what this loop actually wrote.
|
|
4558
|
-
for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml], ["ai-review.yml", aiReviewYml], ["ai-review-unmeasured.yml", aiReviewUnmeasuredYml], ["adr-accepted.yml", adrAcceptedYml], ["closing-references.yml", closingReferencesYml], ["board-ready.yml", boardReadyYml], ["board-intake.yml", boardIntakeYml], ["intake.yml", intakeYml]] as const) {
|
|
4583
|
+
for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml], ["ai-review.yml", aiReviewYml], ["ai-review-unmeasured.yml", aiReviewUnmeasuredYml], ["adr-accepted.yml", adrAcceptedYml], ["closing-references.yml", closingReferencesYml], ["board-ready.yml", boardReadyYml], ["board-intake.yml", boardIntakeYml], ["intake.yml", intakeYml], ["specs-placed.yml", specsPlacedYml]] as const) {
|
|
4559
4584
|
const label = `.github/workflows/${name}`;
|
|
4560
4585
|
try {
|
|
4561
4586
|
// Keyed by FILE, and the lookup is here because this loop is the only
|