@futurelastic/colab-handbook 1.20.4-rc.9 → 1.21.0-rc.1
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/audit/audit.mjs +70 -0
- package/package.json +1 -1
- package/templates/README.md +25 -3
- package/templates/ci-call.yml +73 -0
- package/tools/colab +64 -6
- package/tools/lib/ci-wait.js +16 -2
- package/tools/lib/gate-drift.js +110 -0
- package/tools/lib/git.js +44 -1
- package/tools/lib/stale-base.js +15 -2
- package/tools/lib/template-trunk.js +23 -4
- package/tools/lib/verify-runs.js +207 -15
package/audit/audit.mjs
CHANGED
|
@@ -123,6 +123,8 @@ const npmGuard = require("../tools/lib/npm-publish-guard.js");
|
|
|
123
123
|
const installRoute = require("../tools/lib/install-route.js");
|
|
124
124
|
const releaseRunner = require("../tools/lib/release-runner.js"); // #453
|
|
125
125
|
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
|
|
126
|
+
// #721: a copied CI gate, or one that never skips, is drift — the pure reading lives with its tests.
|
|
127
|
+
const gateDrift = require("../tools/lib/gate-drift.js");
|
|
126
128
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
127
129
|
const integrationProfile = require("../tools/lib/integration-profile.js"); // #610
|
|
128
130
|
const ciProfile = require("../tools/lib/ci-profile.js"); // #559
|
|
@@ -584,6 +586,13 @@ function listRemoteDir(slug, path) {
|
|
|
584
586
|
}
|
|
585
587
|
}
|
|
586
588
|
|
|
589
|
+
// #721: one GitHub REST read, parsed — null when it could not be read (offline, no auth, an API error).
|
|
590
|
+
function readRemoteJson(slug, path) {
|
|
591
|
+
const r = remoteCache.get(slug, `repos/${slug}/${path}`);
|
|
592
|
+
if (r.status !== "ok") return null;
|
|
593
|
+
try { return JSON.parse(r.text); } catch { return null; }
|
|
594
|
+
}
|
|
595
|
+
|
|
587
596
|
function listRemoteBranches(slug) {
|
|
588
597
|
const r = remoteCache.get(slug, `repos/${slug}/branches`, { paginate: true });
|
|
589
598
|
return r.status === "ok" ? r.items.map((b) => String(b.name)) : null; // null = could not determine, distinct from "no branches"
|
|
@@ -872,6 +881,12 @@ function makeSource(target) {
|
|
|
872
881
|
const slug = url ? githubSlugFromRemote(url) : null;
|
|
873
882
|
return slug ? readRemoteIssue(slug, num) : null;
|
|
874
883
|
},
|
|
884
|
+
// #721: a REST read under repos/<slug>/ on the same resolved remote; null = unreadable.
|
|
885
|
+
ghApi: (p) => {
|
|
886
|
+
const url = gitRemote.remoteUrl(root);
|
|
887
|
+
const slug = url ? githubSlugFromRemote(url) : null;
|
|
888
|
+
return slug ? readRemoteJson(slug, p) : null;
|
|
889
|
+
},
|
|
875
890
|
// Same remote-slug resolution as labels() above, one API call, and only when the
|
|
876
891
|
// identity scan was explicitly asked for — see readRemoteMetadata for the contract.
|
|
877
892
|
// An unresolvable remote is its own status, not "no-remote": the scan was asked for
|
|
@@ -930,6 +945,7 @@ function makeSource(target) {
|
|
|
930
945
|
isLinkedWorktree: () => false,
|
|
931
946
|
labels: () => listRemoteLabels(target.slug),
|
|
932
947
|
issue: (num) => readRemoteIssue(target.slug, num),
|
|
948
|
+
ghApi: (p) => readRemoteJson(target.slug, p),
|
|
933
949
|
// Anchor-link check is local-only by design (#158) — enumerating markdown remotely
|
|
934
950
|
// would be N `gh api` calls per repo across a fleet sweep. Empty list = the check
|
|
935
951
|
// scans nothing and emits nothing for a remote source, matching checkRunbook's
|
|
@@ -2187,6 +2203,8 @@ function auditRepoInner(target, ctx) {
|
|
|
2187
2203
|
info.predatesAxes = [];
|
|
2188
2204
|
info.suggestions = [];
|
|
2189
2205
|
const suggest = (t) => info.suggestions.push(t);
|
|
2206
|
+
// #721: the CI dedupe gate maintained once — a copy of it, or a gate that never skips, is drift.
|
|
2207
|
+
checkGateDrift(src, workflows, cfg?.trunk ?? null, warn, { self: isSelf, suggest });
|
|
2190
2208
|
if (integrationSuggestion) suggest(integrationSuggestion); // #610
|
|
2191
2209
|
if (!isSelf) checkStamps(src, ctx.handbook, ctx.templateNames, fail, warn, { ceremony, missingAxes, predatesAxes: info.predatesAxes, writesRaw, suggest });
|
|
2192
2210
|
|
|
@@ -2853,6 +2871,58 @@ function checkInstructionFilesCaller(src, workflows, trunk, warn) {
|
|
|
2853
2871
|
for (const f of instructionFilesCallerFindings({ readFile: (p) => src.readFile(p), workflows, trunk })) warn(f.text);
|
|
2854
2872
|
}
|
|
2855
2873
|
|
|
2874
|
+
// ---- CI gate drift (#721) ----------------------------------------------------
|
|
2875
|
+
// The dedupe gate lives once, in the handbook's reusable workflow (.github/workflows/ci-light.yml).
|
|
2876
|
+
// Two readings, both warn (drift, not customisation — the repo still owns its files):
|
|
2877
|
+
// 1. a workflow carrying its own copy of the gate instead of calling ci-light.yml — static, always;
|
|
2878
|
+
// 2. a guarded workflow whose last N trunk push runs never skipped although one landed a tree another
|
|
2879
|
+
// ref had already passed green — read from run history, so only where GitHub can be read.
|
|
2880
|
+
// The handbook itself is the source: its ci.yml and ci-light.yml carry the gate by design, so the
|
|
2881
|
+
// static reading is off here (self-audit); the history reading still runs.
|
|
2882
|
+
// Reading 1 is a warn only once the handbook's latest release tag carries ci-light.yml: before that
|
|
2883
|
+
// there is nothing to switch TO (a caller pins a tag), so it is a suggestion — the #607 posture for a
|
|
2884
|
+
// CI copy — and it turns into drift by itself the day a release ships the workflow.
|
|
2885
|
+
let reusableReleasedMemo;
|
|
2886
|
+
function reusableReleased() {
|
|
2887
|
+
if (reusableReleasedMemo !== undefined) return reusableReleasedMemo;
|
|
2888
|
+
const hb = handbookInfo(HANDBOOK_ROOT);
|
|
2889
|
+
reusableReleasedMemo = false;
|
|
2890
|
+
if (hb.hasGit && !hb.untagged) {
|
|
2891
|
+
try {
|
|
2892
|
+
execFileSync("git", ["-C", HANDBOOK_ROOT, "cat-file", "-e", `${hb.version}:${gateDrift.REUSABLE_PATH}`], { stdio: "ignore" });
|
|
2893
|
+
reusableReleasedMemo = hb.version;
|
|
2894
|
+
} catch { reusableReleasedMemo = false; }
|
|
2895
|
+
}
|
|
2896
|
+
return reusableReleasedMemo;
|
|
2897
|
+
}
|
|
2898
|
+
function checkGateDrift(src, workflows, trunk, warn, { self = false, suggest = () => {} } = {}) {
|
|
2899
|
+
const { callers, copies } = gateDrift.copiedGates({ readFile: (p) => src.readFile(p), workflows });
|
|
2900
|
+
if (!self && copies.length) {
|
|
2901
|
+
const released = reusableReleased();
|
|
2902
|
+
for (const wf of copies) {
|
|
2903
|
+
if (released) warn(gateDrift.copiedGateText(wf));
|
|
2904
|
+
else suggest(`${wf}: ${gateDrift.copiedGateText(wf)} — a suggestion until a handbook release tag carries ${gateDrift.REUSABLE_PATH}`);
|
|
2905
|
+
}
|
|
2906
|
+
}
|
|
2907
|
+
if (!trunk || typeof src.ghApi !== "function") return;
|
|
2908
|
+
for (const wf of [...callers, ...copies]) {
|
|
2909
|
+
if (self && wf === "ci-light.yml") continue; // the callee: its runs are its callers'
|
|
2910
|
+
const q = (p) => src.ghApi(`actions/workflows/${encodeURIComponent(wf)}/${p}`);
|
|
2911
|
+
const trunkList = q(`runs?branch=${encodeURIComponent(trunk)}&event=push&status=completed&per_page=${gateDrift.RECENT_TRUNK_RUNS}`);
|
|
2912
|
+
if (!trunkList || !Array.isArray(trunkList.workflow_runs)) continue; // unreadable or offline — say nothing
|
|
2913
|
+
const greenList = q("runs?event=push&status=success&per_page=50"); // the guard's own window (#493)
|
|
2914
|
+
if (!greenList || !Array.isArray(greenList.workflow_runs)) continue;
|
|
2915
|
+
const tree = (r) => (r.head_commit && r.head_commit.tree_id) || null;
|
|
2916
|
+
const trunkRuns = trunkList.workflow_runs.slice(0, gateDrift.RECENT_TRUNK_RUNS).map((r) => {
|
|
2917
|
+
const j = src.ghApi(`actions/runs/${r.id}/jobs?per_page=100`);
|
|
2918
|
+
return { id: r.id, tree: tree(r), created: r.created_at, jobs: j && Array.isArray(j.jobs) ? j.jobs : null };
|
|
2919
|
+
});
|
|
2920
|
+
const greenRuns = greenList.workflow_runs.map((r) => ({ id: r.id, branch: r.head_branch, tree: tree(r), created: r.created_at }));
|
|
2921
|
+
const r = gateDrift.gateNeverSkips({ trunkRuns, greenRuns, trunk });
|
|
2922
|
+
if (r.verdict === "drift") warn(gateDrift.inertGateText(wf, r));
|
|
2923
|
+
}
|
|
2924
|
+
}
|
|
2925
|
+
|
|
2856
2926
|
// ---- a deploy trigger that fires on a pre-release tag (#332) ---------------
|
|
2857
2927
|
// The logic lives in tools/lib/workflow-triggers.js (#338) so `colab release cut` refuses on the
|
|
2858
2928
|
// same finding; this maps its severity onto the audit's fail/warn.
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -2,10 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
Starting points you **copy into your own repo**. That is the entire model.
|
|
4
4
|
|
|
5
|
-
> **These are NOT called remotely — with
|
|
5
|
+
> **These are NOT called remotely — with two exceptions.** `instruction-files.yml` is a caller:
|
|
6
6
|
> its one job `uses:` this handbook's reusable `.github/workflows/instruction-files.yml` (#588,
|
|
7
|
-
> kept for compatibility — see *Where each file lives* below).
|
|
8
|
-
>
|
|
7
|
+
> kept for compatibility — see *Where each file lives* below). `ci-call.yml` is the other: it calls
|
|
8
|
+
> the reusable light lane `.github/workflows/ci-light.yml`, pinned to a release tag (#721 — see
|
|
9
|
+
> *The reusable light lane* below). Every other file here is copied, not called. (`dist-refs.yml` is a
|
|
9
10
|
> `workflow_call` workflow, but its caller is your own release workflow, in the same repo, via
|
|
10
11
|
> `uses: ./.github/workflows/dist-refs.yml` — the file still lives, in full, where it runs.) An earlier version of this
|
|
11
12
|
> handbook told repos to call shared workflows; that was reversed. Every other workflow now
|
|
@@ -102,6 +103,7 @@ check that reads one of these files is that tool's behaviour, documented with th
|
|
|
102
103
|
|
|
103
104
|
| File | Copy to | For | Notes |
|
|
104
105
|
|---|---|---|---|
|
|
106
|
+
| `ci-call.yml` | `.github/workflows/ci.yml` | Any Node, Python or Laravel repo that wants the light lane **called, not copied** (#721) | **A caller, not a copy:** triggers, concurrency and one `uses:` of the handbook's reusable `.github/workflows/ci-light.yml` — the dedupe gate, the secret scan, a `quick` and a `full` job, job-class `runs-on`. `colab template ci-call` writes this repo's trunk refs and pins the call to the release it stamps. Your commands go in `with:` (`toolchain`, `install`, `quick`, `full`); your own jobs sit beside the call. A copied gate is reported as drift. |
|
|
105
107
|
| `ci-node.yml` | `.github/workflows/ci.yml` | Pure Node repos: Vite SPA, node libs, Astro static, **Capacitor apps** | Resolves Node version from `project.yml` → `.nvmrc`/`engines` → **fails**. Never a default. Opt-in `Migration round-trip` job — `--roundtrip` writes it live, see *Migration round-trip* below. |
|
|
106
108
|
| `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
|
|
107
109
|
| `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. Toolchain and install steps are copied from the light lane's `build` job, so the two resolve the same versions — keep them in step; the `secrets` job's gitleaks install and `GITLEAKS_VERSION` likewise follow the light lane's `gitleaks` job. `TRUNK` is an edit point. |
|
|
@@ -176,6 +178,26 @@ The rule all of this keeps: [one verdict per tree](../CONVENTIONS.md#one-verdict
|
|
|
176
178
|
Opt out with `tree-reuse: off` (`project.schema.md`) when trunk's run proves something a branch
|
|
177
179
|
run cannot: secrets only trunk gets, `github.ref`-conditional steps, unpinned runner images.
|
|
178
180
|
|
|
181
|
+
### The reusable light lane — calling instead of copying (#721)
|
|
182
|
+
|
|
183
|
+
The guard above drifted copy by copy: measured across adopters (2026-11-09 → 11-11), missing in six
|
|
184
|
+
repositories and present but never skipping in three, and #717's fix reached a copy only through a manual
|
|
185
|
+
sync. `.github/workflows/ci-light.yml` carries the same guard, the same secret scan and the descriptor check
|
|
186
|
+
once, for every caller; `ci-call.yml` is the caller. What changes for you:
|
|
187
|
+
|
|
188
|
+
- **Only the caller is yours**: the triggers and `concurrency` (a called workflow cannot own either), the
|
|
189
|
+
`with:` block, and your own jobs beside the call. A job behind the gate reads `needs: ci` +
|
|
190
|
+
`if: ${{ !cancelled() && needs.ci.outputs.tested != 'true' }}`; a trunk-only job outside it is named
|
|
191
|
+
in `trunk-only-jobs` (#717).
|
|
192
|
+
- **Pinned to a release tag, never `main`.** `colab template ci-call` writes the version it stamps the copy
|
|
193
|
+
with; `colab update` moves a pristine copy's stamp and pin together.
|
|
194
|
+
- **The quick/full split is two jobs**: `quick` (descriptor check, lint, types, unit — the `quick` class)
|
|
195
|
+
and `full` (the light suite, the build — the `full` class); both run on every push the gate does not skip,
|
|
196
|
+
and both take the `trunk` class on a trunk ref under `runs-on: classes`.
|
|
197
|
+
- The copied `ci-<stack>.yml` templates still work and are still copied; moving them onto the caller is
|
|
198
|
+
tracked in #724. A repo carrying one is reported as drift — a suggestion until a handbook release tag carries
|
|
199
|
+
`ci-light.yml`, a warning from then on.
|
|
200
|
+
|
|
179
201
|
### Migration round-trip — have it from the first copy
|
|
180
202
|
|
|
181
203
|
`migration-grant: reviewer` grants only where a `Migration round-trip…` job passed at the
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# CI (light lane) — CALLER of the handbook's reusable workflow (#721). Copy to .github/workflows/ci.yml
|
|
2
|
+
# with `colab template ci-call --dest .github/workflows/ci.yml`: it writes this repo's trunk refs and pins the call to the handbook
|
|
3
|
+
# release it stamps the copy with. Unlike templates/ci-<stack>.yml, nothing below the `uses:` line is
|
|
4
|
+
# yours to maintain — the dedupe gate, the secret scan, the quick/full split and the job-class
|
|
5
|
+
# `runs-on` live once, in .github/workflows/ci-light.yml of the handbook, and a release moves them.
|
|
6
|
+
#
|
|
7
|
+
# EDIT POINTS are marked `# EDIT:` — the `with:` block is the only real one.
|
|
8
|
+
#
|
|
9
|
+
# Kept HERE because a called workflow cannot declare them (CONVENTIONS.md §7, "One verdict per tree"):
|
|
10
|
+
# - the triggers: every branch (#384 — a candidate gets a run of its own before the merge; '**'
|
|
11
|
+
# also covers `ship-batch/**`), no `pull_request` beside push (#512), and workflow_dispatch (the
|
|
12
|
+
# release workflow dispatches CI on a promotion its token cannot trigger, #440);
|
|
13
|
+
# - concurrency: one live run per branch, a trunk run never cancelled and in a group of its own (#512).
|
|
14
|
+
# Its trunk refs and the `trunk-branches` input name the same branches — `colab template` writes both.
|
|
15
|
+
name: CI
|
|
16
|
+
|
|
17
|
+
on:
|
|
18
|
+
push:
|
|
19
|
+
branches: ['**']
|
|
20
|
+
workflow_dispatch:
|
|
21
|
+
|
|
22
|
+
concurrency:
|
|
23
|
+
group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
|
|
24
|
+
cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
|
|
25
|
+
|
|
26
|
+
# The called jobs can only narrow these: the gate lists this workflow's runs and reads git objects.
|
|
27
|
+
permissions:
|
|
28
|
+
actions: read
|
|
29
|
+
contents: read
|
|
30
|
+
|
|
31
|
+
jobs:
|
|
32
|
+
ci:
|
|
33
|
+
# Pinned to a handbook release, never a branch: a caller tracking `main` would take every gate
|
|
34
|
+
# change the moment it merges there, untested against this repo. Move the tag deliberately
|
|
35
|
+
# (`colab update` refreshes a pristine copy to the current release).
|
|
36
|
+
uses: futurelastic/colab-handbook/.github/workflows/ci-light.yml@HANDBOOK_TAG
|
|
37
|
+
with:
|
|
38
|
+
trunk-branches: '["main","dev"]'
|
|
39
|
+
# EDIT: one stack — keep the lines for yours, delete the rest. Versions are resolved from
|
|
40
|
+
# .github/project.yml, then the manifest (.nvmrc / engines.node, .python-version /
|
|
41
|
+
# requires-python, composer.json require.php); none declared fails the job, never a default.
|
|
42
|
+
#
|
|
43
|
+
# Node:
|
|
44
|
+
toolchain: node
|
|
45
|
+
install: auto # npm ci / pnpm install --frozen-lockfile, from the lockfile
|
|
46
|
+
quick: npm run --if-present typecheck && npm run --if-present lint
|
|
47
|
+
full: npm test --if-present && npm run --if-present build
|
|
48
|
+
#
|
|
49
|
+
# Python:
|
|
50
|
+
# toolchain: python
|
|
51
|
+
# install: auto # pip install -e . (or -r requirements.txt), then requirements-dev.txt
|
|
52
|
+
# quick: python -m ruff check . && python -m mypy src
|
|
53
|
+
# full: python -m pytest -q -m "not heavy" || [ $? -eq 5 ]
|
|
54
|
+
#
|
|
55
|
+
# Laravel (PHP + Vite):
|
|
56
|
+
# toolchain: php,node
|
|
57
|
+
# install: auto # composer install, then npm ci
|
|
58
|
+
# quick: vendor/bin/pint --test
|
|
59
|
+
# full: cp .env.example .env && php artisan key:generate && npm run build && php artisan migrate --force && vendor/bin/pest --ci --exclude-group=heavy
|
|
60
|
+
#
|
|
61
|
+
# EDIT: self-hosted runners — `classes` runs each job on ["self-hosted", <class>]: `trunk` on a
|
|
62
|
+
# trunk ref, else `quick` or `full` (CONVENTIONS.md §7, "Runner classes"). A public repo keeps
|
|
63
|
+
# the default, ubuntu-latest. A bare label or a JSON label list also works.
|
|
64
|
+
# runs-on: classes
|
|
65
|
+
# runner-lane: my-repo-lane # only for a capped lane (rule 3)
|
|
66
|
+
#
|
|
67
|
+
# EDIT: name your trunk-only jobs below (deploy, publish) when they sit outside the gate (#717).
|
|
68
|
+
# trunk-only-jobs: Deploy
|
|
69
|
+
|
|
70
|
+
# Your own jobs go here, beside the call. Behind the gate (they skip when the tree already passed):
|
|
71
|
+
# needs: ci
|
|
72
|
+
# if: ${{ !cancelled() && needs.ci.outputs.tested != 'true' }}
|
|
73
|
+
# Trunk-only and ungated: no `if:` on the guard, and list the job's name in `trunk-only-jobs` above.
|
package/tools/colab
CHANGED
|
@@ -10113,6 +10113,17 @@ function cmdTemplate(argv) {
|
|
|
10113
10113
|
if (r.missed.length) trunkNotes.push(` ⚠ trunk: not found in this template, check by hand: ${r.missed.join(', ')}.`);
|
|
10114
10114
|
}
|
|
10115
10115
|
}
|
|
10116
|
+
// #721: the reusable-workflow caller calls the handbook version this copy is stamped with.
|
|
10117
|
+
if (ext === 'yml') {
|
|
10118
|
+
const pin = require('./lib/template-trunk').pinHandbookTag(body, version);
|
|
10119
|
+
body = pin.text;
|
|
10120
|
+
if (pin.pinned) trunkNotes.push(` pin: calls the reusable workflow at ${pin.pinned} — the version this copy is stamped with.`);
|
|
10121
|
+
if (pin.pinned && stamp.handbookInfo(root).hasGit) {
|
|
10122
|
+
const cr = spawnSync('git', ['-C', root, 'cat-file', '-e', `${pin.pinned}:.github/workflows/ci-light.yml`], { stdio: 'ignore' });
|
|
10123
|
+
if (!cr.error && cr.status !== 0) trunkNotes.push(` ⚠ pin: ${pin.pinned} does not carry .github/workflows/ci-light.yml — this copy cannot run until it calls a release that does; set the tag by hand.`);
|
|
10124
|
+
}
|
|
10125
|
+
if (pin.unpinned) trunkNotes.push(' ⚠ pin: the handbook has no tag, so `@HANDBOOK_TAG` is left in place — set it to a release tag that carries .github/workflows/ci-light.yml.');
|
|
10126
|
+
}
|
|
10116
10127
|
// #625: the round-trip job written live, at copy — the commit that creates the workflows.
|
|
10117
10128
|
const roundtripNotes = [];
|
|
10118
10129
|
if (opts.roundtrip && roundtrip.ALWAYS_ON.has(stem)) {
|
|
@@ -10261,7 +10272,7 @@ function inspectRepo(entry, ctx) {
|
|
|
10261
10272
|
const c = stamp.classifyStamped({
|
|
10262
10273
|
root: ctx.handbookRoot, hb: ctx.hb, tmplNames: ctx.tmplNames,
|
|
10263
10274
|
templateName: st.name, stampVersion: st.version, localText: text, comparable: true,
|
|
10264
|
-
render: (body) => require('./lib/template-trunk').renderForRepo(st.name, body, descDoc),
|
|
10275
|
+
render: (body) => require('./lib/template-trunk').renderForRepo(st.name, body, descDoc, st.version),
|
|
10265
10276
|
});
|
|
10266
10277
|
artifacts.push({ file: rel, template: st.name, applicable: c.state === 'behind', ...c });
|
|
10267
10278
|
} else {
|
|
@@ -10355,7 +10366,7 @@ function refreshArtifact(repo, art, ctx) {
|
|
|
10355
10366
|
const src = path.join(ctx.templatesDir, `${art.template}.yml`);
|
|
10356
10367
|
if (!fs.existsSync(src)) return { ok: false, err: `template ${art.template}.yml is not in the handbook` };
|
|
10357
10368
|
// Rendered exactly as `colab template <name> --force` would write it here (#526).
|
|
10358
|
-
const body = require('./lib/template-trunk').renderForRepo(art.template, fs.readFileSync(src, 'utf8'), repoDescriptorDoc(repo.path));
|
|
10369
|
+
const body = require('./lib/template-trunk').renderForRepo(art.template, fs.readFileSync(src, 'utf8'), repoDescriptorDoc(repo.path), ctx.hb.version);
|
|
10359
10370
|
const dest = path.join(repo.path, art.file);
|
|
10360
10371
|
try {
|
|
10361
10372
|
fs.mkdirSync(path.dirname(dest), { recursive: true });
|
|
@@ -12054,6 +12065,37 @@ function pushVerifiedWorkflowsAt(repoAbs, sha) {
|
|
|
12054
12065
|
return names;
|
|
12055
12066
|
}
|
|
12056
12067
|
|
|
12068
|
+
/**
|
|
12069
|
+
* #723: the workflows that SHOULD have a push run at `sha`, the head of `branch` — read from the
|
|
12070
|
+
* workflow files at that sha, the head commit's message (a skip directive), the repo's policy and the
|
|
12071
|
+
* workflows API's state (verify-runs.js `expectedWorkflows`). Null when the tree cannot be read (the
|
|
12072
|
+
* commit is not local and one fetch does not bring it): no expected set, so the runs that exist
|
|
12073
|
+
* decide, as before. GitHub only — a forge's commit statuses carry no workflow identity to match.
|
|
12074
|
+
*/
|
|
12075
|
+
function expectedWorkflowsAt(repoAbs, sha, branch) {
|
|
12076
|
+
if (!sha || !branch) return null;
|
|
12077
|
+
if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) {
|
|
12078
|
+
git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
|
|
12079
|
+
if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
|
|
12080
|
+
}
|
|
12081
|
+
const ls = git.git(['ls-tree', '--name-only', `${sha}:.github/workflows`], repoAbs);
|
|
12082
|
+
const defs = [];
|
|
12083
|
+
if (ls.ok) {
|
|
12084
|
+
for (const f of ls.stdout.split('\n').map((x) => x.trim()).filter((x) => /\.ya?ml$/.test(x))) {
|
|
12085
|
+
const rel = `.github/workflows/${f}`;
|
|
12086
|
+
const show = git.git(['show', `${sha}:${rel}`], repoAbs);
|
|
12087
|
+
if (show.ok) defs.push({ path: rel, text: show.stdout });
|
|
12088
|
+
}
|
|
12089
|
+
}
|
|
12090
|
+
if (!defs.length) return { expected: [], skipDirective: false };
|
|
12091
|
+
const msg = git.git(['log', '-1', '--format=%B', sha], repoAbs);
|
|
12092
|
+
const headMessage = msg.ok ? msg.stdout : null;
|
|
12093
|
+
if (verifyRuns.skipsWorkflows(headMessage)) return { expected: [], skipDirective: true }; // no API call spent
|
|
12094
|
+
return verifyRuns.expectedWorkflows({
|
|
12095
|
+
defs, branch, policy: verifyRuns.parsePolicy(projectDoc(repoAbs)), states: git.ghWorkflowStates(repoAbs), headMessage,
|
|
12096
|
+
});
|
|
12097
|
+
}
|
|
12098
|
+
|
|
12057
12099
|
/** Number of workflow files in `.github/workflows` at `sha`, or null when the tree cannot be read. */
|
|
12058
12100
|
function trunkWorkflowFiles(repoAbs, sha) {
|
|
12059
12101
|
if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
|
|
@@ -12479,7 +12521,9 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
|
|
|
12479
12521
|
// head row below never refuses on a run that policy sets aside (a release lane, an ignored workflow).
|
|
12480
12522
|
const rows = git.ghRunsForCommit(repoAbs, branch, headSha);
|
|
12481
12523
|
run = git.summarizeRunsForCommit(rows, headSha);
|
|
12482
|
-
|
|
12524
|
+
// #723: the workflows that should have fired at the head — one with no run there holds the head row.
|
|
12525
|
+
const exp = rows ? expectedWorkflowsAt(repoAbs, headSha, branch) : null;
|
|
12526
|
+
verifiedRun = git.summarizeRunsForCommit(rows, headSha, { verifying: verifyingPolicy(repoAbs), finishedRed: true, expected: exp ? exp.expected : [] });
|
|
12483
12527
|
}
|
|
12484
12528
|
// #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
|
|
12485
12529
|
// #682: on a forge, `headCi` is the branch head's own CI verdict (green / red / pending), its own
|
|
@@ -16863,6 +16907,15 @@ Exit codes — branch on these, never on the text:
|
|
|
16863
16907
|
4 RATE_LIMITED GitHub refused for quota (403/429) — the wait ENDS, it does not retry
|
|
16864
16908
|
5 UNKNOWN a read failed or returned a state it cannot classify
|
|
16865
16909
|
6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
|
|
16910
|
+
7 NO_RUN --sha with --branch: the deadline passed and a workflow whose definition at the
|
|
16911
|
+
head fires on a push to that branch still had NO run there (#723). The runs that
|
|
16912
|
+
do exist never stand in for it, so such a head is pending, never GREEN. The
|
|
16913
|
+
output names it (\`no-run:<workflow>\`) and how to get it a run — a hint only
|
|
16914
|
+
|
|
16915
|
+
Expected at a branch head (#723): a workflow file at the head sha triggered by \`push\`, whose
|
|
16916
|
+
branch filters match the branch, with no \`paths\`/\`paths-ignore\` filter, in ship-gate-workflows
|
|
16917
|
+
when declared, not in ship-ignore-workflows, and not disabled. None when the head commit carries a
|
|
16918
|
+
skip directive ([skip ci] …). Any doubt (an unreadable filter, an unread tree) means not expected.
|
|
16866
16919
|
|
|
16867
16920
|
On a remote the machine config's \`forges\` names as Forgejo (#678, #682), --sha reads the commit's
|
|
16868
16921
|
combined status instead — no gh call, no conditional request; a status has no run id, so <run-id>
|
|
@@ -16870,7 +16923,7 @@ is a usage error there. RED and --json name the contexts that are not green (\`n
|
|
|
16870
16923
|
|
|
16871
16924
|
It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
|
|
16872
16925
|
--json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
|
|
16873
|
-
detail, status, conclusion, url, notGreen? }`;
|
|
16926
|
+
detail, status, conclusion, url, notGreen?, missing?, hint? }`;
|
|
16874
16927
|
|
|
16875
16928
|
function cmdCiWait(argv) {
|
|
16876
16929
|
const opts = parseArgs(argv, {
|
|
@@ -16938,6 +16991,10 @@ function cmdCiWait(argv) {
|
|
|
16938
16991
|
}
|
|
16939
16992
|
|
|
16940
16993
|
const verifyPolicy = verifyingPolicy(repoAbs);
|
|
16994
|
+
// #723: on a branch head, the workflows that should have a run there — read once, before the loop. A
|
|
16995
|
+
// missing one holds green as pending and ends the wait NO_RUN (exit 7) at the deadline.
|
|
16996
|
+
const expectedSet = !fc && !runId && opts.branch ? expectedWorkflowsAt(repoAbs, opts.sha, opts.branch) : null;
|
|
16997
|
+
const expected = expectedSet ? expectedSet.expected : [];
|
|
16941
16998
|
// #681: inside a Forgejo Actions run (the release workflow waiting on CI at its own sha) the calling
|
|
16942
16999
|
// workflow's own contexts are dropped — a run never waits on itself (#425's rule; a no-op elsewhere).
|
|
16943
17000
|
const poll = fc ? () => ciWait.forgePoll(fc.ciVerdict(opts.sha, { branch: opts.branch || null, rowsFilter: (rows) => releaseCut.withoutOwnWorkflow(rows) }), fc.kind) : (etag) => {
|
|
@@ -16960,7 +17017,7 @@ function cmdCiWait(argv) {
|
|
|
16960
17017
|
}
|
|
16961
17018
|
// #503: the same verifying-runs policy ship reads — a wait on trunk's head ends when the CI
|
|
16962
17019
|
// that verifies the code ends, not when the post-CI release run does.
|
|
16963
|
-
summary = git.summarizeRunsForCommit(rows, opts.sha, { verifying: verifyPolicy });
|
|
17020
|
+
summary = git.summarizeRunsForCommit(rows, opts.sha, { verifying: verifyPolicy, expected });
|
|
16964
17021
|
const pick = rows.find((x) => x.databaseId === summary.databaseId);
|
|
16965
17022
|
summary = { ...summary, url: pick ? pick.url : null };
|
|
16966
17023
|
}
|
|
@@ -16985,13 +17042,14 @@ function cmdCiWait(argv) {
|
|
|
16985
17042
|
status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
|
|
16986
17043
|
...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
|
|
16987
17044
|
...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
|
|
17045
|
+
...(Array.isArray(s.missing) && s.missing.length ? { missing: s.missing, hint: verifyRuns.missingHint(s.missing, opts.branch) } : {}), // #723
|
|
16988
17046
|
...(s.readVia ? { readVia: s.readVia } : {}), // #654: the verdict names how it was read
|
|
16989
17047
|
...(Array.isArray(s.notGreen) && s.notGreen.length ? { notGreen: s.notGreen } : {}), // #682: forge contexts not green
|
|
16990
17048
|
};
|
|
16991
17049
|
if (opts.json) print(JSON.stringify(out, null, 2));
|
|
16992
17050
|
else {
|
|
16993
17051
|
print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
|
|
16994
|
-
`${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${readViaNote(s)}${notGreenNote(s)}`);
|
|
17052
|
+
`${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${verifyRuns.missingNote(s.missing, opts.branch)}${readViaNote(s)}${notGreenNote(s)}`);
|
|
16995
17053
|
}
|
|
16996
17054
|
return code;
|
|
16997
17055
|
}
|
package/tools/lib/ci-wait.js
CHANGED
|
@@ -35,6 +35,9 @@ const EXIT = Object.freeze({
|
|
|
35
35
|
RATE_LIMITED: 4,
|
|
36
36
|
UNKNOWN: 5,
|
|
37
37
|
ALREADY_WAITING: 6,
|
|
38
|
+
// #723: the deadline passed with an expected workflow still having NO run at the sha (only other
|
|
39
|
+
// workflows ran there). Not TIMEOUT: nothing is in flight to wait longer for — someone must get it a run.
|
|
40
|
+
NO_RUN: 7,
|
|
38
41
|
});
|
|
39
42
|
|
|
40
43
|
const DEFAULT_SCHEDULE_SEC = Object.freeze([30, 60, 120]);
|
|
@@ -112,10 +115,15 @@ function restRow(x) {
|
|
|
112
115
|
* The state of what is being waited on, from a summarized run (`{status, conclusion}`):
|
|
113
116
|
* `green` · `red` · `pending` · `unknown`. `none` (no run at the sha yet) is pending: runs appear
|
|
114
117
|
* seconds after a push, and the deadline bounds the wait if they never do.
|
|
118
|
+
*
|
|
119
|
+
* #723: a summary carrying `missing` (an expected workflow with no run at the sha) is never green —
|
|
120
|
+
* it is pending, like `none`: the run may still appear, and the deadline ends the wait as NO_RUN.
|
|
121
|
+
* A red stays red: a failure that already happened does not wait on a run that has not.
|
|
115
122
|
*/
|
|
116
123
|
function runState(s) {
|
|
117
124
|
if (!s) return 'unknown';
|
|
118
125
|
if (s.status === 'none') return 'pending';
|
|
126
|
+
if (Array.isArray(s.missing) && s.missing.length && s.status === 'completed' && s.conclusion === 'success') return 'pending';
|
|
119
127
|
if (s.status === 'completed') return s.conclusion === 'success' ? 'green' : 'red';
|
|
120
128
|
if (['queued', 'in_progress', 'waiting', 'requested', 'pending'].includes(s.status)) return 'pending';
|
|
121
129
|
return 'unknown';
|
|
@@ -162,7 +170,7 @@ function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_
|
|
|
162
170
|
const d = delayFor(i, schedule) * 1000;
|
|
163
171
|
if (d) {
|
|
164
172
|
const left = start + deadlineSec * 1000 - now();
|
|
165
|
-
if (left <= 0) return
|
|
173
|
+
if (left <= 0) return deadline(`still ${last ? last.state : 'unread'} at the ${fmtDuration(deadlineSec * 1000)} deadline`);
|
|
166
174
|
sleep(Math.min(d, left));
|
|
167
175
|
}
|
|
168
176
|
// The poll that lands on the deadline is the last one: it must read the truth, not a 304.
|
|
@@ -186,7 +194,13 @@ function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_
|
|
|
186
194
|
if (last.state === 'green') return done('GREEN', null);
|
|
187
195
|
if (last.state === 'red') return done('RED', null);
|
|
188
196
|
if (last.state !== 'pending') return done('UNKNOWN', `unrecognised state (${JSON.stringify(last.summary || null)})`);
|
|
189
|
-
if (now() - start >= deadlineSec * 1000) return
|
|
197
|
+
if (now() - start >= deadlineSec * 1000) return deadline(`still pending at the ${fmtDuration(deadlineSec * 1000)} deadline`);
|
|
198
|
+
}
|
|
199
|
+
// #723: a deadline that passes with an expected workflow still runless is NO_RUN, naming it.
|
|
200
|
+
function deadline(detail) {
|
|
201
|
+
const miss = last && last.summary && Array.isArray(last.summary.missing) ? last.summary.missing : [];
|
|
202
|
+
if (!miss.length) return done('TIMEOUT', detail);
|
|
203
|
+
return done('NO_RUN', `no-run:${miss.map((x) => x.name).join(',')} — no run of ${miss.length === 1 ? 'that workflow' : 'those workflows'} appeared by the ${fmtDuration(deadlineSec * 1000)} deadline`);
|
|
190
204
|
}
|
|
191
205
|
function done(outcome, detail, r) {
|
|
192
206
|
return { outcome, polls, notModified, forced, waitedMs: now() - start, last: last || r || null, detail };
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* CI gate drift (#721) — the pure half of two audit findings. No gh, no git, no I/O.
|
|
4
|
+
*
|
|
5
|
+
* The dedupe gate (CONVENTIONS.md §7, "One verdict per tree") used to live only in copies: each
|
|
6
|
+
* adopter copied a light CI template and owned the copy, so the gate drifted copy by copy — measured
|
|
7
|
+
* across adopters 2026-11-09 → 11-11, missing in six repositories and present but never skipping in
|
|
8
|
+
* three — and a template fix (#717) reached a copy only through a manual sync. The gate now lives once,
|
|
9
|
+
* in the handbook's reusable workflow (.github/workflows/ci-light.yml), and these two readings report
|
|
10
|
+
* what is left as DRIFT, not customisation:
|
|
11
|
+
*
|
|
12
|
+
* 1. copiedGates — a workflow that carries its own copy of the gate (its coined step name, or the
|
|
13
|
+
* guard's GUARD_NAME env) instead of calling ci-light.yml. Content decides, never the filename.
|
|
14
|
+
* 2. gateNeverSkips — of a guarded workflow's last N trunk push runs, at least one landed a tree a
|
|
15
|
+
* green push run on another ref had already passed, yet none of the N skipped: the gate is
|
|
16
|
+
* present and inert (a renamed guard, a trunk ref missing from its `if:`, a skip-chained run…).
|
|
17
|
+
* Read from run history, so it catches a gate that LOOKS right.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/** The workflow a caller names; `./.github/…` (a local call) and `owner/repo/.github/…@ref` both count. */
|
|
21
|
+
const REUSABLE_PATH = '.github/workflows/ci-light.yml';
|
|
22
|
+
const CALLER_RE = /^\s*uses:\s*["']?(?:\.\/|[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/)\.github\/workflows\/ci-light\.ya?ml(?:@[^\s"'#]+)?["']?\s*(?:#.*)?$/m;
|
|
23
|
+
/** The guard's coined step name (every light template since #418/#493), or its GUARD_NAME env (#511). */
|
|
24
|
+
const GATE_STEP_RE = /^\s*-\s*name:\s*["']?Look for a green run of this workflow at this sha(?: or tree)?["']?\s*$/m;
|
|
25
|
+
const GATE_ENV_RE = /^\s*GUARD_NAME:\s*\S/m;
|
|
26
|
+
/** How many trunk runs the inert-gate reading looks back over. */
|
|
27
|
+
const RECENT_TRUNK_RUNS = 10;
|
|
28
|
+
const GUARD_NAME = 'Already tested at this sha or tree?';
|
|
29
|
+
|
|
30
|
+
function isCiLightCaller(text) { return !!text && CALLER_RE.test(text); }
|
|
31
|
+
function hasCopiedGate(text) { return !!text && !isCiLightCaller(text) && (GATE_STEP_RE.test(text) || GATE_ENV_RE.test(text)); }
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* { callers: [file], copies: [file] } over `.github/workflows/<file>`. A workflow both calling
|
|
35
|
+
* ci-light.yml and carrying a gate step is a caller (the call is the gate; the step would be dead).
|
|
36
|
+
*/
|
|
37
|
+
function copiedGates({ readFile, workflows }) {
|
|
38
|
+
const callers = [];
|
|
39
|
+
const copies = [];
|
|
40
|
+
for (const wf of workflows || []) {
|
|
41
|
+
const text = readFile(`.github/workflows/${wf}`);
|
|
42
|
+
if (isCiLightCaller(text)) callers.push(wf);
|
|
43
|
+
else if (hasCopiedGate(text)) copies.push(wf);
|
|
44
|
+
}
|
|
45
|
+
return { callers, copies };
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Did one trunk run skip its suite through the gate? From its jobs (`[{name, conclusion}]`): the
|
|
50
|
+
* guard (by name, or as a called "<caller> / <guard>") succeeded and some other job was skipped.
|
|
51
|
+
* On trunk the guard always runs, and a job other than it skips there only when the gate said
|
|
52
|
+
* tested — or for a reason of its own (an opt-in job switched off), which reads as a skip and so can
|
|
53
|
+
* only HIDE drift, never invent it. null in → null out (an unreadable listing is not "no").
|
|
54
|
+
*/
|
|
55
|
+
function runSkipped(jobs) {
|
|
56
|
+
if (!Array.isArray(jobs)) return null;
|
|
57
|
+
const isGuard = (n) => n === GUARD_NAME || String(n).endsWith(` / ${GUARD_NAME}`);
|
|
58
|
+
const guardOk = jobs.some((j) => j && isGuard(j.name) && j.conclusion === 'success');
|
|
59
|
+
return guardOk && jobs.some((j) => j && !isGuard(j.name) && j.conclusion === 'skipped');
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The inert-gate reading. trunkRuns: newest first, [{id, tree, created, jobs}] — `jobs` as runSkipped
|
|
64
|
+
* reads it; greenRuns: [{id, branch, tree, created}] green push runs of the same workflow on any ref.
|
|
65
|
+
* Returns { verdict: 'drift' | 'ok' | 'unknown', considered, matched: [{trunk, cited}], reason }:
|
|
66
|
+
* - unknown: no trunk run to read, or a listing could not be read (`null` jobs) — say nothing;
|
|
67
|
+
* - ok: some run skipped, or no run in the window had a green tree to reuse (nothing to skip);
|
|
68
|
+
* - drift: at least one had one, and none of the window skipped.
|
|
69
|
+
*/
|
|
70
|
+
function gateNeverSkips({ trunkRuns, greenRuns, trunk, n = RECENT_TRUNK_RUNS }) {
|
|
71
|
+
if (!Array.isArray(trunkRuns) || !Array.isArray(greenRuns)) return { verdict: 'unknown', considered: 0, matched: [], reason: 'run history unreadable' };
|
|
72
|
+
const window = trunkRuns.slice(0, n);
|
|
73
|
+
if (!window.length) return { verdict: 'unknown', considered: 0, matched: [], reason: 'no trunk push run yet' };
|
|
74
|
+
const t = (x) => Date.parse(x) || 0;
|
|
75
|
+
const matched = [];
|
|
76
|
+
let skipped = 0;
|
|
77
|
+
for (const r of window) {
|
|
78
|
+
const s = runSkipped(r.jobs);
|
|
79
|
+
if (s === null) return { verdict: 'unknown', considered: window.length, matched: [], reason: `the jobs of run ${r.id} could not be read` };
|
|
80
|
+
if (s) { skipped++; continue; }
|
|
81
|
+
if (!r.tree) continue;
|
|
82
|
+
const cited = greenRuns.find((g) => g && g.tree === r.tree && g.id !== r.id && g.branch !== trunk && t(g.created) <= t(r.created));
|
|
83
|
+
if (cited) matched.push({ trunk: r.id, cited: cited.id, branch: cited.branch });
|
|
84
|
+
}
|
|
85
|
+
if (skipped) return { verdict: 'ok', considered: window.length, matched, reason: `${skipped} of the last ${window.length} trunk runs skipped through the gate` };
|
|
86
|
+
if (!matched.length) return { verdict: 'ok', considered: window.length, matched, reason: `no trunk run of the last ${window.length} landed a tree a branch had already passed` };
|
|
87
|
+
return {
|
|
88
|
+
verdict: 'drift', considered: window.length, matched,
|
|
89
|
+
reason: `none of the last ${window.length} trunk runs skipped, yet ${matched.length} landed a tree another ref had already passed green`,
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** The audit's two finding texts — one place, so the wording the docs quote cannot drift from the code. */
|
|
94
|
+
function copiedGateText(wf) {
|
|
95
|
+
return `drift: .github/workflows/${wf} carries its own copy of the CI dedupe gate instead of calling the handbook's ` +
|
|
96
|
+
`reusable workflow (${REUSABLE_PATH}) — a copy changes only by a manual sync, so a gate fix never reaches it ` +
|
|
97
|
+
'(#717 did not). Switch to templates/ci-call.yml (`colab template ci-call --dest .github/workflows/<this file>`) (#721)';
|
|
98
|
+
}
|
|
99
|
+
function inertGateText(wf, r) {
|
|
100
|
+
const ex = r.matched[0];
|
|
101
|
+
return `drift: the dedupe gate in .github/workflows/${wf} never skipped — ${r.reason} ` +
|
|
102
|
+
`(e.g. trunk run ${ex.trunk} could have cited run ${ex.cited} on ${ex.branch}). A gate that is present but inert ` +
|
|
103
|
+
'runs every landing twice; check the guard\'s `if:` names this trunk and GUARD_NAME is its job\'s name, or call ' +
|
|
104
|
+
`${REUSABLE_PATH} (templates/ci-call.yml) (#721)`;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
module.exports = {
|
|
108
|
+
REUSABLE_PATH, RECENT_TRUNK_RUNS, GUARD_NAME,
|
|
109
|
+
isCiLightCaller, hasCopiedGate, copiedGates, runSkipped, gateNeverSkips, copiedGateText, inertGateText,
|
|
110
|
+
};
|
package/tools/lib/git.js
CHANGED
|
@@ -1156,6 +1156,23 @@ function ghRunsForRef(repo, ref, sha, limit = 20) {
|
|
|
1156
1156
|
return runs.filter((x) => x && x.headSha === sha);
|
|
1157
1157
|
}
|
|
1158
1158
|
|
|
1159
|
+
/**
|
|
1160
|
+
* #723: the repo's workflows as a Map of file path → `{ state, id, name }` — one REST call. `state`
|
|
1161
|
+
* (`active`, `disabled_manually`, …): a disabled workflow never gets a run, so it is never expected at
|
|
1162
|
+
* a head. `id` / `name` are how its runs identify it (a run's `workflow_id`, its `name`). Null on any
|
|
1163
|
+
* failure: the caller then takes every workflow as active and matches runs by the definition's name.
|
|
1164
|
+
*/
|
|
1165
|
+
function ghWorkflowStates(repo) {
|
|
1166
|
+
const r = gh(['api', 'repos/{owner}/{repo}/actions/workflows?per_page=100'], { cwd: repo });
|
|
1167
|
+
if (!r.ok) return null;
|
|
1168
|
+
let j;
|
|
1169
|
+
try { j = JSON.parse(r.stdout); } catch (_) { return null; }
|
|
1170
|
+
if (!j || !Array.isArray(j.workflows)) return null;
|
|
1171
|
+
const m = new Map();
|
|
1172
|
+
for (const w of j.workflows) if (w && w.path) m.set(w.path, { state: w.state || null, id: w.id ?? null, name: w.name || null });
|
|
1173
|
+
return m;
|
|
1174
|
+
}
|
|
1175
|
+
|
|
1159
1176
|
function ghRunForCommit(repo, branch, sha, limit = 10, opts = {}) {
|
|
1160
1177
|
return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha, opts);
|
|
1161
1178
|
}
|
|
@@ -1267,6 +1284,14 @@ function excludedRunSummary(rows) {
|
|
|
1267
1284
|
* #688: a workflow whose every run at the sha was skipped is then set aside beside a run that can
|
|
1268
1285
|
* verify the code (setAsideWhollySkipped, below); the rows ride along as `skippedOnly`, and `allSkipped`
|
|
1269
1286
|
* says nothing but such workflows ran here. `runCount` no longer counts them (#461's rule).
|
|
1287
|
+
*
|
|
1288
|
+
* #723: `opts.expected` (verify-runs.js `expectedWorkflows(...).expected`, `[{name, path, dispatch}]`)
|
|
1289
|
+
* names the workflows that SHOULD have a run at the sha. One with no counted row there rides along as
|
|
1290
|
+
* `missing` (same entries), present only when non-empty. The summary's status and conclusion are left
|
|
1291
|
+
* exactly as the runs that exist make them — a caller that asked for `expected` reads `missing` and
|
|
1292
|
+
* holds a would-be green (ci-wait.runState, stale-base.githubBranchHeadRedVerdict). Measured: only a
|
|
1293
|
+
* small `instruction-files` workflow ran at a branch head, the repo's CI never got a run there, and the
|
|
1294
|
+
* head read green from that one unrelated run.
|
|
1270
1295
|
*/
|
|
1271
1296
|
function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
1272
1297
|
if (allForSha === null) return null;
|
|
@@ -1280,6 +1305,7 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
|
1280
1305
|
setAside = split.setAside;
|
|
1281
1306
|
dispatchCounted = split.dispatchCounted || [];
|
|
1282
1307
|
}
|
|
1308
|
+
const missing = missingExpected(owned, opts && opts.expected);
|
|
1283
1309
|
const { heads, superseded } = newestRunPerWorkflow(owned);
|
|
1284
1310
|
const { judged, skippedOnly, allSkipped } = setAsideWhollySkipped(heads, superseded, opts && opts.verifying);
|
|
1285
1311
|
const extra = {
|
|
@@ -1289,6 +1315,7 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
|
1289
1315
|
...(allSkipped ? { allSkipped: true } : {}),
|
|
1290
1316
|
...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
|
|
1291
1317
|
...(dispatchCounted.length ? { dispatchCounted: excludedRunSummary(dispatchCounted) } : {}),
|
|
1318
|
+
...(missing.length ? { missing: missing.map((e) => ({ name: e.name, path: e.path || null, dispatch: !!e.dispatch, ...(e.id != null ? { id: e.id } : {}) })) } : {}),
|
|
1292
1319
|
// #691: opt-in (`opts.finishedRed`), so no reader that never asked sees a new field — every
|
|
1293
1320
|
// JUDGED run that finished red: completed, and not success, cancelled or skipped (neither of
|
|
1294
1321
|
// those two executed anything). The summary's single `conclusion` names only the first not-green
|
|
@@ -1302,6 +1329,22 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
|
1302
1329
|
return { ...r, ...extra };
|
|
1303
1330
|
}
|
|
1304
1331
|
|
|
1332
|
+
/**
|
|
1333
|
+
* #723: the expected workflows with no counted row at the sha. A row stands for an expected workflow
|
|
1334
|
+
* when its workflow FILE id matches (`workflowId`, the workflows API's id), or its name matches the
|
|
1335
|
+
* definition's or the API's. A row carrying neither a name nor an id cannot be told apart from any
|
|
1336
|
+
* workflow, so its presence means nothing is called missing — absence of a field never adds a hold,
|
|
1337
|
+
* the same rule as everywhere above.
|
|
1338
|
+
*/
|
|
1339
|
+
function missingExpected(rows, expected) {
|
|
1340
|
+
const exp = Array.isArray(expected) ? expected.filter((e) => e && e.name) : [];
|
|
1341
|
+
if (!exp.length) return [];
|
|
1342
|
+
if (rows.some((x) => x && !x.workflowName && (x.workflowId === undefined || x.workflowId === null))) return [];
|
|
1343
|
+
const stands = (x, e) => !!x && ((e.id != null && x.workflowId != null && Number(x.workflowId) === Number(e.id))
|
|
1344
|
+
|| x.workflowName === e.name || (!!e.apiName && x.workflowName === e.apiName));
|
|
1345
|
+
return exp.filter((e) => !rows.some((x) => stands(x, e)));
|
|
1346
|
+
}
|
|
1347
|
+
|
|
1305
1348
|
/** #691: a run that ran and failed — completed, and not success, cancelled or skipped. */
|
|
1306
1349
|
function isFinishedRed(x) {
|
|
1307
1350
|
return !!x && x.status === 'completed' && x.conclusion !== 'success' && x.conclusion !== 'cancelled' && x.conclusion !== 'skipped';
|
|
@@ -1624,7 +1667,7 @@ module.exports = {
|
|
|
1624
1667
|
worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
|
|
1625
1668
|
dirtyTracked, dirtyUntracked, dirtyAny,
|
|
1626
1669
|
ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, ghRunsAtShaUnfiltered, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
|
|
1627
|
-
ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
|
|
1670
|
+
ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghWorkflowStates, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
|
|
1628
1671
|
ghRunJobCount, ghRunJobs, ghActiveRunsOfWorkflow, ghWorkflowDispatch,
|
|
1629
1672
|
ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
|
|
1630
1673
|
ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
|
package/tools/lib/stale-base.js
CHANGED
|
@@ -141,19 +141,32 @@ function branchHeadCiVerdict(a) {
|
|
|
141
141
|
* refuses here. `run.finishedRed` (tools/lib/git.js) lists every judged red run; without it the
|
|
142
142
|
* summary's own status/conclusion decides.
|
|
143
143
|
*
|
|
144
|
+
* #723: a head where an EXPECTED workflow has no run (`run.missing`, git.summarizeRunsForCommit's
|
|
145
|
+
* `opts.expected`) is pending, self-clearing, never a pass: ship --dry used to read READY on a head
|
|
146
|
+
* where only an unrelated workflow had run and the repo's CI never got a run at all. A red still wins
|
|
147
|
+
* (it is checked first). The detail names the missing workflow and how to get it a run — a hint only.
|
|
148
|
+
*
|
|
144
149
|
* @param {object} a
|
|
145
150
|
* @param {string|null} a.headSha - the branch head on the remote
|
|
146
151
|
* @param {object|null} a.run - summarizeRunsForCommit's verdict at headSha, verifying policy applied
|
|
147
152
|
* @param {string} a.branch
|
|
148
|
-
* @returns {null|{ok:false, verdict:'red', selfClearing:
|
|
153
|
+
* @returns {null|{ok:false, verdict:'red'|'pending', selfClearing:boolean, detail:string}}
|
|
149
154
|
*/
|
|
150
155
|
function githubBranchHeadRedVerdict(a) {
|
|
151
156
|
const run = a && a.run;
|
|
152
157
|
if (!a || !a.headSha || !run || run.status === 'none') return null;
|
|
153
158
|
const listed = Array.isArray(run.finishedRed) ? run.finishedRed : [];
|
|
154
159
|
const summaryRed = run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
|
|
155
|
-
if (!listed.length && !summaryRed) return null;
|
|
156
160
|
const at = `${a.branch}@${String(a.headSha).slice(0, 7)} (GitHub Actions)`;
|
|
161
|
+
const missing = Array.isArray(run.missing) ? run.missing : [];
|
|
162
|
+
if (!listed.length && !summaryRed) {
|
|
163
|
+
if (!missing.length) return null;
|
|
164
|
+
const { missingHint } = require('./verify-runs');
|
|
165
|
+
return { ok: false, verdict: 'pending', selfClearing: true,
|
|
166
|
+
detail: `${at} has no run of ${missing.map((x) => x.name).join(', ')}, though ${missing.length === 1 ? 'its' : 'their'} definition fires on a push to this branch — ` +
|
|
167
|
+
`the runs that exist there do not stand in for it (#723). Wait with \`colab ci-wait --sha ${a.headSha} --branch ${a.branch}\`; ` +
|
|
168
|
+
`if it ends NO_RUN (exit 7), ${missingHint(missing, a.branch)}` };
|
|
169
|
+
}
|
|
157
170
|
const failing = listed.length
|
|
158
171
|
? listed.map((x) => `${x.workflowName || 'run'} (${x.conclusion || 'none'})`).join(', ')
|
|
159
172
|
: `conclusion=${run.conclusion || 'none'}`;
|
|
@@ -54,7 +54,11 @@ function substituteTrunk(text, p) {
|
|
|
54
54
|
swap('concurrency group', `(${tplEq.join(' || ')}) && format(`, `(${p.refs.map(eq).join(' || ')}) && format(`);
|
|
55
55
|
swap('cancel-in-progress', `cancel-in-progress: \${{ ${TEMPLATE_REFS.map(ne).join(' && ')} }}`,
|
|
56
56
|
`cancel-in-progress: \${{ ${p.refs.map(ne).join(' && ')} }}`);
|
|
57
|
-
|
|
57
|
+
// #721: the reusable-workflow caller (templates/ci-call.yml) names its trunk refs in the `trunk-branches`
|
|
58
|
+
// input instead of a guard `if:` of its own — the guard lives in the called workflow.
|
|
59
|
+
const tplList = `trunk-branches: '${JSON.stringify(TEMPLATE_REFS)}'`;
|
|
60
|
+
if (out.includes(tplList)) swap('trunk-branches input', tplList, `trunk-branches: '${JSON.stringify(p.refs)}'`);
|
|
61
|
+
else swap("dedupe guard's if:", `github.event.created || ${tplEq.join(' || ')})`, `github.event.created || ${p.refs.map(eq).join(' || ')})`);
|
|
58
62
|
// ci-laravel's test tier (only present there): the release-gating branch is the trunk on a one-branch repo.
|
|
59
63
|
if (!p.twoBranch && p.trunk !== 'main' && out.includes('[ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]')) {
|
|
60
64
|
out = out.split('[ "$BASE_REF" = "main" ]').join(`[ "$BASE_REF" = "${p.trunk}" ]`);
|
|
@@ -71,10 +75,25 @@ function substituteTrunk(text, p) {
|
|
|
71
75
|
* `colab update` uses the same rendering both to recognise a pristine copy and to refresh one, so
|
|
72
76
|
* a refreshed file stays byte-identical to what `colab template <name> --force` would write.
|
|
73
77
|
*/
|
|
74
|
-
function renderForRepo(name, body, doc) {
|
|
78
|
+
function renderForRepo(name, body, doc, version) {
|
|
75
79
|
if (!/^ci-/.test(String(name || ''))) return body;
|
|
80
|
+
const pinned = version ? pinHandbookTag(body, version).text : body;
|
|
76
81
|
const p = protectedRefs(doc);
|
|
77
|
-
return p ? substituteTrunk(
|
|
82
|
+
return p ? substituteTrunk(pinned, p).text : pinned;
|
|
78
83
|
}
|
|
79
84
|
|
|
80
|
-
|
|
85
|
+
/**
|
|
86
|
+
* #721: the reusable-workflow caller pins the handbook by tag — `uses: …/ci-light.yml@HANDBOOK_TAG`
|
|
87
|
+
* in the template. A copy is written with the version its stamp records, so "copied from handbook X"
|
|
88
|
+
* and "calls handbook X" are one fact, and a refresh moves both together. `v0` (an untagged handbook)
|
|
89
|
+
* pins nothing: there is no tag to call, and the token is left for the copier to see.
|
|
90
|
+
*/
|
|
91
|
+
const HANDBOOK_TAG = 'HANDBOOK_TAG';
|
|
92
|
+
function pinHandbookTag(text, version) {
|
|
93
|
+
const token = `@${HANDBOOK_TAG}`;
|
|
94
|
+
if (!String(text).includes(token)) return { text, pinned: null };
|
|
95
|
+
if (!version || version === 'v0') return { text, pinned: null, unpinned: true };
|
|
96
|
+
return { text: text.split(token).join(`@${version}`), pinned: version };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
module.exports = { TEMPLATE_REFS, HANDBOOK_TAG, protectedRefs, substituteTrunk, renderForRepo, pinHandbookTag };
|
package/tools/lib/verify-runs.js
CHANGED
|
@@ -150,6 +150,28 @@ const BRANCH_TRIGGERS = Object.freeze(['push', 'pull_request', 'pull_request_tar
|
|
|
150
150
|
* of the three `on:` shapes (scalar, flow list, block map / block list) — not a YAML parser.
|
|
151
151
|
*/
|
|
152
152
|
function workflowTriggers(text) {
|
|
153
|
+
const parsed = onEvents(text);
|
|
154
|
+
if (!parsed) return null;
|
|
155
|
+
const { name, events } = parsed;
|
|
156
|
+
let verifies = false;
|
|
157
|
+
for (const [ev, e] of events) {
|
|
158
|
+
if (!BRANCH_TRIGGERS.includes(ev)) continue;
|
|
159
|
+
if (ev !== 'push') { verifies = true; break; }
|
|
160
|
+
const keys = e.body.map((b) => (/^([A-Za-z_-]+)\s*:/.exec(b.text) || [])[1]).filter(Boolean);
|
|
161
|
+
const tagsOnly = (keys.includes('tags') || keys.includes('tags-ignore')) && !keys.includes('branches') && !keys.includes('branches-ignore');
|
|
162
|
+
if (!tagsOnly) { verifies = true; break; }
|
|
163
|
+
}
|
|
164
|
+
return { name, verifiesBranches: verifies };
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* The top-level `name:` and the `on:` events of one workflow file: `{ name, events }`, or null when
|
|
169
|
+
* the text has no top-level `on:`. `events` maps an event name to `{ inline, body }` — `inline` is
|
|
170
|
+
* what follows `<event>:` on its own line ('' for the block form), `body` the child lines with their
|
|
171
|
+
* indent (`{ indent, text }`, text trimmed). The scalar and flow-list forms of `on:` give events with
|
|
172
|
+
* no inline value and no body. Shared by workflowTriggers (#567) and pushTrigger (#723).
|
|
173
|
+
*/
|
|
174
|
+
function onEvents(text) {
|
|
153
175
|
const lines = String(text || '').split(/\r?\n/);
|
|
154
176
|
let name = null;
|
|
155
177
|
let onIdx = -1;
|
|
@@ -162,10 +184,10 @@ function workflowTriggers(text) {
|
|
|
162
184
|
if (m && onIdx < 0) { onIdx = i; onInline = yamlScalar(m[1]); }
|
|
163
185
|
}
|
|
164
186
|
if (onIdx < 0) return null;
|
|
165
|
-
const events = new Map();
|
|
187
|
+
const events = new Map();
|
|
166
188
|
if (onInline) {
|
|
167
189
|
const list = onInline.startsWith('[') ? onInline.replace(/^\[|\]$/g, '').split(',') : [onInline];
|
|
168
|
-
for (const e of list) { const v = yamlScalar(e); if (v) events.set(v, []); }
|
|
190
|
+
for (const e of list) { const v = yamlScalar(e); if (v) events.set(v, { inline: '', body: [] }); }
|
|
169
191
|
} else {
|
|
170
192
|
let evIndent = null;
|
|
171
193
|
let cur = null;
|
|
@@ -178,21 +200,188 @@ function workflowTriggers(text) {
|
|
|
178
200
|
if (indent < evIndent) break;
|
|
179
201
|
if (indent === evIndent) {
|
|
180
202
|
const t = l.trim();
|
|
181
|
-
const
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
203
|
+
const li = /^-\s*(.+)$/.exec(t);
|
|
204
|
+
const mk = li ? null : /^([A-Za-z_]+)\s*:\s*(.*)$/.exec(t);
|
|
205
|
+
cur = li ? yamlScalar(li[1].replace(/:.*$/, '')) : (mk ? yamlScalar(mk[1]) : null);
|
|
206
|
+
if (cur) events.set(cur, { inline: mk ? yamlScalar(mk[2]) : '', body: [] });
|
|
207
|
+
} else if (cur) events.get(cur).body.push({ indent, text: l.trim() });
|
|
185
208
|
}
|
|
186
209
|
}
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
210
|
+
return { name, events };
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/** A YAML flow list `[a, 'b', "c"]` or a single scalar → the strings; '' → []. */
|
|
214
|
+
function flowList(v) {
|
|
215
|
+
const t = String(v || '').trim();
|
|
216
|
+
if (!t) return [];
|
|
217
|
+
const inner = t.startsWith('[') && t.endsWith(']') ? t.slice(1, -1) : t;
|
|
218
|
+
return inner.split(',').map(yamlScalar).filter(Boolean);
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
const PUSH_FILTER_KEYS = Object.freeze(['branches', 'branches-ignore', 'tags', 'tags-ignore', 'paths', 'paths-ignore']);
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* #723: what one workflow file says about a BRANCH PUSH — the question "should this workflow have a
|
|
225
|
+
* run at the head of branch B?" asks. Returns null when the text has no top-level `on:`, else
|
|
226
|
+
* `{ name, push, readable, branches, branchesIgnore, tagsOnly, paths, dispatch }`:
|
|
227
|
+
* push the triggers include `push`
|
|
228
|
+
* readable the push filters were read; false for a shape this small reader does not follow
|
|
229
|
+
* (a flow map `push: {…}`, an unknown key) — the caller then never expects a run
|
|
230
|
+
* branches / branchesIgnore the glob lists, null when absent
|
|
231
|
+
* tagsOnly `tags`/`tags-ignore` with no branch filter: a branch push never fires it
|
|
232
|
+
* paths a `paths` / `paths-ignore` filter is present: whether a push fires it depends on
|
|
233
|
+
* the files the push changed, which this reader does not judge
|
|
234
|
+
* dispatch the triggers include `workflow_dispatch` — `gh workflow run` can give it a run
|
|
235
|
+
* Not a YAML parser; the same deliberately small reader as workflowTriggers.
|
|
236
|
+
*/
|
|
237
|
+
function pushTrigger(text) {
|
|
238
|
+
const parsed = onEvents(text);
|
|
239
|
+
if (!parsed) return null;
|
|
240
|
+
const { name, events } = parsed;
|
|
241
|
+
const out = { name, push: events.has('push'), readable: true, branches: null, branchesIgnore: null,
|
|
242
|
+
tagsOnly: false, paths: false, dispatch: events.has('workflow_dispatch') };
|
|
243
|
+
if (!out.push) return out;
|
|
244
|
+
const e = events.get('push');
|
|
245
|
+
if (e.inline && !['null', '~', '{}'].includes(e.inline)) { out.readable = false; return out; }
|
|
246
|
+
const lists = {};
|
|
247
|
+
let key = null;
|
|
248
|
+
let keyIndent = null;
|
|
249
|
+
for (const b of e.body) {
|
|
250
|
+
if (keyIndent === null) keyIndent = b.indent;
|
|
251
|
+
if (b.indent === keyIndent) {
|
|
252
|
+
const m = /^([A-Za-z_-]+)\s*:\s*(.*)$/.exec(b.text);
|
|
253
|
+
if (!m || !PUSH_FILTER_KEYS.includes(m[1])) { out.readable = false; return out; }
|
|
254
|
+
key = m[1];
|
|
255
|
+
lists[key] = flowList(m[2]);
|
|
256
|
+
} else if (key && b.indent > keyIndent) {
|
|
257
|
+
const li = /^-\s*(.+)$/.exec(b.text);
|
|
258
|
+
if (!li) { out.readable = false; return out; }
|
|
259
|
+
lists[key].push(yamlScalar(li[1]));
|
|
260
|
+
} else { out.readable = false; return out; }
|
|
194
261
|
}
|
|
195
|
-
|
|
262
|
+
out.branches = lists.branches || null;
|
|
263
|
+
out.branchesIgnore = lists['branches-ignore'] || null;
|
|
264
|
+
out.tagsOnly = !!(lists.tags || lists['tags-ignore']) && !out.branches && !out.branchesIgnore;
|
|
265
|
+
out.paths = !!(lists.paths || lists['paths-ignore']);
|
|
266
|
+
return out;
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* One GitHub filter pattern (`*` not across `/`, `**` across, `?` / `+` / `[…]` on the preceding
|
|
271
|
+
* character as in a regex) → a RegExp over the whole branch name, or null when it cannot be read.
|
|
272
|
+
*/
|
|
273
|
+
function filterPatternRe(p) {
|
|
274
|
+
let re = '';
|
|
275
|
+
const s = String(p);
|
|
276
|
+
for (let i = 0; i < s.length; i++) {
|
|
277
|
+
const c = s[i];
|
|
278
|
+
if (c === '*') { if (s[i + 1] === '*') { re += '.*'; i++; } else re += '[^/]*'; }
|
|
279
|
+
else if (c === '?' || c === '+') re += c;
|
|
280
|
+
else if (c === '[') { const j = s.indexOf(']', i); if (j < 0) return null; re += s.slice(i, j + 1); i = j; }
|
|
281
|
+
else if (c === '\\') { if (i + 1 >= s.length) return null; re += s[i + 1].replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'); i++; }
|
|
282
|
+
else re += c.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
|
|
283
|
+
}
|
|
284
|
+
try { return new RegExp(`^${re}$`); } catch (_) { return null; }
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/**
|
|
288
|
+
* #723: does a push to `branch` pass a workflow's branch filters? true / false, or null when a
|
|
289
|
+
* pattern cannot be read. `branches` is ordered with `!` negations (the last match decides);
|
|
290
|
+
* `branches-ignore` excludes on any match. Neither list → true.
|
|
291
|
+
*/
|
|
292
|
+
function branchFilterMatches(branch, { branches = null, branchesIgnore = null } = {}) {
|
|
293
|
+
if (branches) {
|
|
294
|
+
let hit = false;
|
|
295
|
+
for (const raw of branches) {
|
|
296
|
+
const neg = raw.startsWith('!');
|
|
297
|
+
const re = filterPatternRe(neg ? raw.slice(1) : raw);
|
|
298
|
+
if (!re) return null;
|
|
299
|
+
if (re.test(branch)) hit = !neg;
|
|
300
|
+
}
|
|
301
|
+
return hit;
|
|
302
|
+
}
|
|
303
|
+
if (branchesIgnore) {
|
|
304
|
+
for (const raw of branchesIgnore) {
|
|
305
|
+
const re = filterPatternRe(raw);
|
|
306
|
+
if (!re) return null;
|
|
307
|
+
if (re.test(branch)) return false;
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
return true;
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** GitHub's skip directives (docs: "Skipping workflow runs") — a push run is not created for them. */
|
|
314
|
+
const SKIP_DIRECTIVES = Object.freeze(['[skip ci]', '[ci skip]', '[no ci]', '[skip actions]', '[actions skip]']);
|
|
315
|
+
|
|
316
|
+
function skipsWorkflows(message) {
|
|
317
|
+
const m = String(message || '');
|
|
318
|
+
const low = m.toLowerCase();
|
|
319
|
+
return SKIP_DIRECTIVES.some((d) => low.includes(d)) || /^skip-checks:\s*true\s*$/mi.test(m);
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/**
|
|
323
|
+
* #723: the workflows that SHOULD have a push run at the head of `branch` — the expected set a
|
|
324
|
+
* branch verdict reads before it may call the head green. A workflow is expected when its definition
|
|
325
|
+
* AT THE HEAD (GitHub reads the workflow file from the pushed commit):
|
|
326
|
+
* - is triggered by `push`, read cleanly, not tags-only, with no `paths` / `paths-ignore` filter,
|
|
327
|
+
* - passes its branch filters for `branch` (an unreadable pattern → not expected),
|
|
328
|
+
* - is not in `ship-ignore-workflows`, and is in `ship-gate-workflows` when that list is declared,
|
|
329
|
+
* - is not reported anything but `active` by the workflows API (`states`: path → `{state, id, name}`
|
|
330
|
+
* or a bare state string; null = unread, every workflow taken as active). The API's `id` and
|
|
331
|
+
* `name` ride on the entry, so a run is matched by its workflow id too (git.js missingExpected).
|
|
332
|
+
* Nothing is expected when the head commit's message carries a skip directive (`headMessage`).
|
|
333
|
+
*
|
|
334
|
+
* Every doubt resolves to NOT expected: that is today's reading (the runs that exist decide), so the
|
|
335
|
+
* set can only add a hold where a workflow demonstrably should have run, never invent one.
|
|
336
|
+
*
|
|
337
|
+
* @param {object} a
|
|
338
|
+
* @param {Array<{path:string, text:string}>} a.defs - the workflow files at the head
|
|
339
|
+
* @param {string} a.branch
|
|
340
|
+
* @param {object} [a.policy] - parsePolicy's `{gate, ignore}`
|
|
341
|
+
* @param {Map<string,(string|{state:string, id:number, name:string})>|null} [a.states]
|
|
342
|
+
* @param {string|null} [a.headMessage]
|
|
343
|
+
* @returns {{ expected: Array<{name:string, path:string, dispatch:boolean, id?:number, apiName?:string}>, skipDirective: boolean }}
|
|
344
|
+
*/
|
|
345
|
+
function expectedWorkflows({ defs, branch, policy = null, states = null, headMessage = null }) {
|
|
346
|
+
if (skipsWorkflows(headMessage)) return { expected: [], skipDirective: true };
|
|
347
|
+
const p = policy || { gate: null, ignore: [] };
|
|
348
|
+
const expected = [];
|
|
349
|
+
for (const d of defs || []) {
|
|
350
|
+
const t = pushTrigger(d.text);
|
|
351
|
+
if (!t || !t.push || !t.readable || t.tagsOnly || t.paths) continue;
|
|
352
|
+
if (branchFilterMatches(branch, t) !== true) continue;
|
|
353
|
+
const name = t.name || d.path;
|
|
354
|
+
if (p.ignore && p.ignore.includes(name)) continue;
|
|
355
|
+
if (p.gate && !p.gate.includes(name)) continue;
|
|
356
|
+
const st = states && states.has(d.path) ? states.get(d.path) : null;
|
|
357
|
+
const info = st && typeof st === 'object' ? st : { state: st };
|
|
358
|
+
if (info.state && info.state !== 'active') continue;
|
|
359
|
+
expected.push({ name, path: d.path, dispatch: t.dispatch,
|
|
360
|
+
...(info.id != null ? { id: info.id } : {}), ...(info.name && info.name !== name ? { apiName: info.name } : {}) });
|
|
361
|
+
}
|
|
362
|
+
return { expected, skipDirective: false };
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
/**
|
|
366
|
+
* #723: how to get a run for each missing workflow — a hint, never an action. `gh workflow run` where
|
|
367
|
+
* the workflow takes `workflow_dispatch` (#567 counts that run as the push run it stands in for);
|
|
368
|
+
* otherwise a draft PR, or an empty re-push, which is the implementer's call.
|
|
369
|
+
*/
|
|
370
|
+
function missingHint(missing, branch) {
|
|
371
|
+
const list = Array.isArray(missing) ? missing : [];
|
|
372
|
+
if (!list.length) return '';
|
|
373
|
+
const b = branch || '<branch>';
|
|
374
|
+
const parts = list.map((x) => (x.dispatch
|
|
375
|
+
? `\`gh workflow run ${String(x.path || x.name).split('/').pop()} --ref ${b}\``
|
|
376
|
+
: `${x.name}: no workflow_dispatch — open a draft PR (\`gh pr create --draft --head ${b}\`) or push an empty commit (the implementer's call)`));
|
|
377
|
+
return `to get the run: ${parts.join('; ')}`;
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/** #723: the verdict-detail suffix naming the expected workflows with no run at the sha — '' when none. */
|
|
381
|
+
function missingNote(missing, branch) {
|
|
382
|
+
const list = Array.isArray(missing) ? missing : [];
|
|
383
|
+
if (!list.length) return '';
|
|
384
|
+
return ` — no run of ${list.map((x) => x.name).join(', ')} at this sha, though ${list.length === 1 ? 'its' : 'their'} definition fires on a push to this branch (#723); ${missingHint(list, branch)}`;
|
|
196
385
|
}
|
|
197
386
|
|
|
198
387
|
/** The compact verdict-detail note for rows the lost-push rescue counted — '' when none. */
|
|
@@ -225,4 +414,7 @@ function skippedOnlyNote(rows) {
|
|
|
225
414
|
return ` — not judged, every run skipped so it ran nothing here (#688; name a workflow in ship-gate-workflows if it must run): ${names.join(', ')}`;
|
|
226
415
|
}
|
|
227
416
|
|
|
228
|
-
module.exports = {
|
|
417
|
+
module.exports = {
|
|
418
|
+
VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, SKIP_DIRECTIVES, parsePolicy, setAsideReason, splitVerifying, setAsideNote, skippedOnlyNote,
|
|
419
|
+
workflowTriggers, pushTrigger, branchFilterMatches, skipsWorkflows, expectedWorkflows, missingHint, missingNote, dispatchCountedNote,
|
|
420
|
+
};
|