@futurelastic/colab-handbook 1.19.0 → 1.19.1-rc.2
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/package.json +1 -1
- package/tools/colab +100 -10
- package/tools/lib/adopt.js +2 -1
- package/tools/lib/ci-forgejo.js +15 -2
- package/tools/lib/ci-wait.js +12 -1
- package/tools/lib/codec/labels.d.ts +9 -0
- package/tools/lib/codec/labels.js +57 -0
- package/tools/lib/codec/samples.json +8 -0
- package/tools/lib/disposition.js +16 -14
- package/tools/lib/stale-base.js +47 -1
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -8022,7 +8022,7 @@ const DELIVERY_LABEL_COUNT = labels.conventionLabelNames()
|
|
|
8022
8022
|
const DEFERRED_LABEL_COUNT = labels.conventionLabelNames()
|
|
8023
8023
|
.filter((n) => n.startsWith(labels.DEFERRED_LABEL_PREFIX)).length;
|
|
8024
8024
|
|
|
8025
|
-
const HELP_LABELS = `colab labels --ensure [--refresh-descriptions [--keep a,b]] [--repo P]
|
|
8025
|
+
const HELP_LABELS = `colab labels --ensure [--refresh-descriptions [--keep a,b]] [--relabel-deprecated] [--prune-deprecated] [--repo P]
|
|
8026
8026
|
|
|
8027
8027
|
Create every convention label this repo is missing — CONVENTIONS.md §9 step 3, the ${labels.conventionLabelNames().length}-name set
|
|
8028
8028
|
(${NON_DELIVERY_LABEL_NAMES.map((n) => `\`${n}\``).join(', ')}, the ${DELIVERY_LABEL_COUNT} \`delivery:*\` values, and the ${DEFERRED_LABEL_COUNT} \`deferred:*\` values),
|
|
@@ -8041,6 +8041,13 @@ used to be typed out by hand (#206).
|
|
|
8041
8041
|
${labels.MINIMAL_LABEL_NAMES.map((n) => `\`${n}\``).join(', ')}. For a repo the fleet does not own
|
|
8042
8042
|
(CONVENTIONS.md §9, "Working in a repo you don't own") — every other
|
|
8043
8043
|
label is opt-in by use there, not provisioned on someone else's tracker
|
|
8044
|
+
--relabel-deprecated move every OPEN issue carrying a deprecated label (${codec.DEPRECATED_LABELS.map((d) => `\`${d.name}\``).join(', ')})
|
|
8045
|
+
onto its replacement — add the new label, remove the old (#683). Closed
|
|
8046
|
+
issues keep the old label as history. Without this flag they are only reported
|
|
8047
|
+
--prune-deprecated delete a deprecated label from the tracker — only once its window has ended
|
|
8048
|
+
(${codec.HUMAN_WAIT_ALIAS_UNTIL}) AND a non-search read confirms no open issue still
|
|
8049
|
+
carries it. Deleting strips the label from closed issues too, so it is never
|
|
8050
|
+
implied by --relabel-deprecated
|
|
8044
8051
|
--repo <path> repo root (default: git root of cwd)
|
|
8045
8052
|
|
|
8046
8053
|
Idempotent: a label already present is never re-created and reported under "already there" —
|
|
@@ -8062,9 +8069,15 @@ rejects) — each failure is reported by name, not just a bare non-zero.
|
|
|
8062
8069
|
function cmdLabels(argv) {
|
|
8063
8070
|
const opts = parseArgs(argv, {
|
|
8064
8071
|
values: { '--repo': 'repo', '--keep': 'keep' },
|
|
8065
|
-
flags: {
|
|
8072
|
+
flags: {
|
|
8073
|
+
'--ensure': 'ensure', '--refresh-descriptions': 'refresh', '--minimal': 'minimal',
|
|
8074
|
+
'--relabel-deprecated': 'relabel', '--prune-deprecated': 'prune', '-h': 'help', '--help': 'help',
|
|
8075
|
+
},
|
|
8066
8076
|
});
|
|
8067
8077
|
if (opts.help || !opts.ensure) return print(HELP_LABELS);
|
|
8078
|
+
if (opts.minimal && (opts.relabel || opts.prune)) {
|
|
8079
|
+
throw new UserError('--relabel-deprecated / --prune-deprecated move issues onto a label --minimal does not provision — drop --minimal');
|
|
8080
|
+
}
|
|
8068
8081
|
if (opts.keep !== undefined && !opts.refresh) {
|
|
8069
8082
|
throw new UserError('--keep only means something with --refresh-descriptions — without it no description is rewritten, so there is nothing to keep');
|
|
8070
8083
|
}
|
|
@@ -8135,6 +8148,51 @@ function cmdLabels(argv) {
|
|
|
8135
8148
|
print('(CONVENTIONS.md §8, Upstream; skills/handbook-sync/SKILL.md §7).');
|
|
8136
8149
|
}
|
|
8137
8150
|
}
|
|
8151
|
+
// #683: deprecated aliases (codec.DEPRECATED_LABELS). Only a label the tracker actually has is
|
|
8152
|
+
// read, so a repo that never carried an old spelling costs no extra call. --minimal skips this:
|
|
8153
|
+
// the replacement is outside the subset it provisions.
|
|
8154
|
+
if (!opts.minimal) {
|
|
8155
|
+
const have = new Set(present.map((l) => l.name));
|
|
8156
|
+
const target = (name) => have.has(name) || created.includes(name);
|
|
8157
|
+
const day = today();
|
|
8158
|
+
for (const d of codec.DEPRECATED_LABELS) {
|
|
8159
|
+
if (!have.has(d.name)) continue;
|
|
8160
|
+
const v = codec.deprecatedLabelDecision(d, { today: day, open: git.ghOpenIssueNumbersByLabel(repoAbs, d.name) });
|
|
8161
|
+
if (v.action === 'move') {
|
|
8162
|
+
const list = v.open.map((n) => `#${n}`).join(', ');
|
|
8163
|
+
if (!opts.relabel) {
|
|
8164
|
+
print(`Deprecated label in use: ${d.name} on ${list} — replaced by ${d.replacedBy} (alias window ends ${d.until}).`);
|
|
8165
|
+
print(' Move them: colab labels --ensure --relabel-deprecated');
|
|
8166
|
+
continue;
|
|
8167
|
+
}
|
|
8168
|
+
if (!target(d.replacedBy)) {
|
|
8169
|
+
failed.push({ name: d.name, error: `${d.replacedBy} is not on the tracker, so ${list} cannot move onto it` });
|
|
8170
|
+
continue;
|
|
8171
|
+
}
|
|
8172
|
+
const moved = [];
|
|
8173
|
+
for (const n of v.open) {
|
|
8174
|
+
const r = git.ghIssueEdit(repoAbs, n, ['--add-label', d.replacedBy, '--remove-label', d.name]);
|
|
8175
|
+
if (r.ok) moved.push(`#${n}`);
|
|
8176
|
+
else failed.push({ name: `${d.name} on #${n}`, error: (r.stderr || '').trim() || 'gh issue edit failed' });
|
|
8177
|
+
}
|
|
8178
|
+
if (moved.length) print(`Relabelled ${d.name} → ${d.replacedBy}: ${moved.join(', ')}`);
|
|
8179
|
+
} else if (v.action === 'delete') {
|
|
8180
|
+
if (!opts.prune) {
|
|
8181
|
+
print(`Deprecated label ${d.name}: no open issue carries it and its window ended ${d.until} — delete it: colab labels --ensure --prune-deprecated`);
|
|
8182
|
+
continue;
|
|
8183
|
+
}
|
|
8184
|
+
const r = git.ghLabelDelete(repoAbs, d.name);
|
|
8185
|
+
if (r.ok) print(`Deleted deprecated label: ${d.name}`);
|
|
8186
|
+
else failed.push({ name: d.name, error: (r.stderr || '').trim() || 'gh label delete failed' });
|
|
8187
|
+
} else if (v.reason === 'unread') {
|
|
8188
|
+
const why = `could not read the open issues carrying ${d.name} — left as it is`;
|
|
8189
|
+
if (opts.relabel || opts.prune) failed.push({ name: d.name, error: why });
|
|
8190
|
+
else print(`Deprecated label ${d.name}: ${why}`);
|
|
8191
|
+
} else {
|
|
8192
|
+
print(`Deprecated label ${d.name}: no open issue carries it; kept until its window ends ${d.until}${opts.prune ? ' (--prune-deprecated deletes it only after that)' : ''}.`);
|
|
8193
|
+
}
|
|
8194
|
+
}
|
|
8195
|
+
}
|
|
8138
8196
|
if (failed.length) {
|
|
8139
8197
|
print('Failed:');
|
|
8140
8198
|
for (const f of failed) print(` ${f.name} — ${f.error}`);
|
|
@@ -11991,6 +12049,7 @@ function readForgeCiVerdict(repoAbs, fc, target, trunk) {
|
|
|
11991
12049
|
if (!run) return unread(`${engine} commit-status read failed for ${target}@${shortSha(sha)} — cannot confirm CI`);
|
|
11992
12050
|
const at = `${via}@${shortSha(run.sha || sha)} (${engine} commit status)`;
|
|
11993
12051
|
let verdict = classifyCiRun(repoAbs, run, at);
|
|
12052
|
+
if (!verdict.ok) verdict = { ...verdict, detail: verdict.detail + notGreenNote(run) }; // #682: name the contexts
|
|
11994
12053
|
if (run.status === 'none' && target === trunk) {
|
|
11995
12054
|
const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha), { graceSec: ciProfileFor(repoAbs).th.emptyReadGraceSec });
|
|
11996
12055
|
if (fresh.fresh) {
|
|
@@ -12066,6 +12125,12 @@ function classifyCiRun(repoAbs, run, at) {
|
|
|
12066
12125
|
return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) + verifyRuns.dispatchCountedNote(run && run.dispatchCounted) + readViaNote(run) };
|
|
12067
12126
|
}
|
|
12068
12127
|
|
|
12128
|
+
/** #682: a forge verdict's not-green contexts, named — '' on GitHub, or when every context is green. */
|
|
12129
|
+
function notGreenNote(run) {
|
|
12130
|
+
const ng = run && Array.isArray(run.notGreen) ? run.notGreen : [];
|
|
12131
|
+
return ng.length ? ` — not green: ${ng.map((x) => `${x.name} (${x.status === 'completed' ? (x.conclusion || 'none') : x.status})`).join(', ')}` : '';
|
|
12132
|
+
}
|
|
12133
|
+
|
|
12069
12134
|
/**
|
|
12070
12135
|
* #651: the runs were read from the unfiltered `actions/runs` listing because the forge's filtered
|
|
12071
12136
|
* queries (`head_sha=` / `branch=`) answered nothing. The verdict is judged as usual. The note says
|
|
@@ -12278,9 +12343,16 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
|
|
|
12278
12343
|
if (headSha && fc) run = fc.ciVerdict(headSha, { branch });
|
|
12279
12344
|
else if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
|
|
12280
12345
|
// #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
|
|
12281
|
-
|
|
12346
|
+
// #682: on a forge, `headCi` is the branch head's own CI verdict (green / red / pending), its own
|
|
12347
|
+
// row — the class code-ship B1a reads through `colab ci-wait` on GitHub. null on GitHub, and where
|
|
12348
|
+
// the head has no run to judge (the stale-base row speaks for those).
|
|
12349
|
+
const headCi = fc ? staleBase.branchHeadCiVerdict({ headSha, run, branch, engine: fc.kind }) : null;
|
|
12350
|
+
return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ciReadable: !!(fc || gh) }), run, headSha, headCi };
|
|
12282
12351
|
}
|
|
12283
12352
|
|
|
12353
|
+
/** #682: the forge branch-head CI row's name — one spelling for the JSON and the prose table. */
|
|
12354
|
+
const BRANCH_HEAD_CI_ROW = 'branch CI green at its head (#682)';
|
|
12355
|
+
|
|
12284
12356
|
/**
|
|
12285
12357
|
* #294: WHICH paths are dirty in the trunk checkout, and — where the signal is strong enough — a
|
|
12286
12358
|
* likely owner. Never a precondition: it enriches the ALREADY-COMPUTED "trunk checkout ready"
|
|
@@ -13102,6 +13174,8 @@ function cmdShipDryJson(opts) {
|
|
|
13102
13174
|
} else {
|
|
13103
13175
|
checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
|
|
13104
13176
|
class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
|
|
13177
|
+
const hc = staleJson.headCi; // #682: forge only — a red head needs a person, a running one clears
|
|
13178
|
+
if (hc) checks.push({ name: BRANCH_HEAD_CI_ROW, ok: hc.ok, class: hc.ok ? null : (hc.selfClearing ? SELF_CLEARING : HUMAN_GATED), verdict: hc.verdict, detail: hc.detail });
|
|
13105
13179
|
}
|
|
13106
13180
|
// #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
|
|
13107
13181
|
// its own (a real ship dispatches it); a red, or no heavy lane at all, needs a person.
|
|
@@ -14353,7 +14427,9 @@ function cmdShip(argv) {
|
|
|
14353
14427
|
docsRowOk = row.ok && docsCi.scan.ok;
|
|
14354
14428
|
} else {
|
|
14355
14429
|
checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
|
|
14430
|
+
if (staleResult.headCi) checks.push([staleResult.headCi.ok ? '✓' : '✗', BRANCH_HEAD_CI_ROW, staleResult.headCi.detail]); // #682
|
|
14356
14431
|
}
|
|
14432
|
+
const headCiOk = docsCi.applies || !staleResult.headCi || staleResult.headCi.ok;
|
|
14357
14433
|
// #610: integration-profile: gated — the heavy lane green at the branch head. A missing or running
|
|
14358
14434
|
// heavy run is a pause (⏸, taken below once every real precondition passes); only a red, or no
|
|
14359
14435
|
// heavy lane at all, fails the table.
|
|
@@ -14385,7 +14461,7 @@ function cmdShip(argv) {
|
|
|
14385
14461
|
// issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
|
|
14386
14462
|
// have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
|
|
14387
14463
|
// checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
|
|
14388
|
-
const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk && heavyOk;
|
|
14464
|
+
const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && headCiOk && coreOk && recOk && heavyOk;
|
|
14389
14465
|
|
|
14390
14466
|
// ---- report the table ----
|
|
14391
14467
|
print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
|
|
@@ -16556,9 +16632,13 @@ Exit codes — branch on these, never on the text:
|
|
|
16556
16632
|
5 UNKNOWN a read failed or returned a state it cannot classify
|
|
16557
16633
|
6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
|
|
16558
16634
|
|
|
16635
|
+
On a remote the machine config's \`forges\` names as Forgejo (#678, #682), --sha reads the commit's
|
|
16636
|
+
combined status instead — no gh call, no conditional request; a status has no run id, so <run-id>
|
|
16637
|
+
is a usage error there. RED and --json name the contexts that are not green (\`notGreen\`).
|
|
16638
|
+
|
|
16559
16639
|
It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
|
|
16560
16640
|
--json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
|
|
16561
|
-
detail, status, conclusion, url }`;
|
|
16641
|
+
detail, status, conclusion, url, notGreen? }`;
|
|
16562
16642
|
|
|
16563
16643
|
function cmdCiWait(argv) {
|
|
16564
16644
|
const opts = parseArgs(argv, {
|
|
@@ -16587,9 +16667,16 @@ function cmdCiWait(argv) {
|
|
|
16587
16667
|
}
|
|
16588
16668
|
opts.sha = full;
|
|
16589
16669
|
}
|
|
16590
|
-
|
|
16670
|
+
// #682: a remote the engine map names as a forge (#678) is read from its commit statuses, never
|
|
16671
|
+
// through gh — which would answer `no known GitHub host` (exit 5) for every wait there.
|
|
16672
|
+
const fc = forgeCi(repoAbs);
|
|
16673
|
+
if (fc && runId) {
|
|
16674
|
+
warn(`the remote is a ${fc.kind} forge — a commit status has no run id to wait on; pass --sha <sha> [--branch <b>]`);
|
|
16675
|
+
return ciWait.EXIT.USAGE;
|
|
16676
|
+
}
|
|
16677
|
+
if (!fc && !git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
|
|
16591
16678
|
|
|
16592
|
-
const target = runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}
|
|
16679
|
+
const target = (runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`) + (fc ? ` (${fc.kind} commit status)` : '');
|
|
16593
16680
|
const apiPath = runId
|
|
16594
16681
|
? `repos/{owner}/{repo}/actions/runs/${runId}`
|
|
16595
16682
|
: `repos/{owner}/{repo}/actions/runs?head_sha=${encodeURIComponent(opts.sha)}${opts.branch ? `&branch=${encodeURIComponent(opts.branch)}` : ''}&per_page=100`;
|
|
@@ -16619,7 +16706,7 @@ function cmdCiWait(argv) {
|
|
|
16619
16706
|
}
|
|
16620
16707
|
|
|
16621
16708
|
const verifyPolicy = verifyingPolicy(repoAbs);
|
|
16622
|
-
const poll = (etag) => {
|
|
16709
|
+
const poll = fc ? () => ciWait.forgePoll(fc.ciVerdict(opts.sha, { branch: opts.branch || null }), fc.kind) : (etag) => {
|
|
16623
16710
|
const r = git.ghApiConditional(repoAbs, apiPath, etag);
|
|
16624
16711
|
if (r.kind !== 'ok') return r;
|
|
16625
16712
|
let summary;
|
|
@@ -16665,11 +16752,12 @@ function cmdCiWait(argv) {
|
|
|
16665
16752
|
...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
|
|
16666
16753
|
...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
|
|
16667
16754
|
...(s.readVia ? { readVia: s.readVia } : {}), // #654: the verdict names how it was read
|
|
16755
|
+
...(Array.isArray(s.notGreen) && s.notGreen.length ? { notGreen: s.notGreen } : {}), // #682: forge contexts not green
|
|
16668
16756
|
};
|
|
16669
16757
|
if (opts.json) print(JSON.stringify(out, null, 2));
|
|
16670
16758
|
else {
|
|
16671
16759
|
print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
|
|
16672
|
-
`${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)}`);
|
|
16760
|
+
`${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)}`);
|
|
16673
16761
|
}
|
|
16674
16762
|
return code;
|
|
16675
16763
|
}
|
|
@@ -17902,7 +17990,9 @@ Commands:
|
|
|
17902
17990
|
labels --ensure [--repo P] create every missing convention label (§9 step 3, #206) —
|
|
17903
17991
|
idempotent, reports created vs already-there, and names every
|
|
17904
17992
|
label whose description drifted (#364); --refresh-descriptions
|
|
17905
|
-
[--keep a,b] rewrites those to the handbook's text
|
|
17993
|
+
[--keep a,b] rewrites those to the handbook's text;
|
|
17994
|
+
--relabel-deprecated moves open issues off a deprecated
|
|
17995
|
+
label, --prune-deprecated deletes it after its window (#683)
|
|
17906
17996
|
config [show|add-repo P|rm-repo P|set K V]
|
|
17907
17997
|
|
|
17908
17998
|
State is machine-local at ~/.colab/ (override with COLAB_HOME). Run any command with
|
package/tools/lib/adopt.js
CHANGED
|
@@ -34,6 +34,7 @@ const yaml = require('./yaml.js');
|
|
|
34
34
|
const { consumerEvidence, describeEvidence } = require('./consumer-evidence.js');
|
|
35
35
|
const { evaluateExposure } = require('./exposure-shape.js');
|
|
36
36
|
const { UserError } = require('./util.js');
|
|
37
|
+
const labels = require('./codec/labels.js');
|
|
37
38
|
|
|
38
39
|
const ROW_NAMES = ['tier', 'room', 'exposure', 'writes', 'channels'];
|
|
39
40
|
|
|
@@ -397,7 +398,7 @@ function remainingSteps(ctx = {}) {
|
|
|
397
398
|
const steps = [];
|
|
398
399
|
if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
|
|
399
400
|
steps.push(
|
|
400
|
-
{ n: 3, text:
|
|
401
|
+
{ n: 3, text: `Create the full label set (${labels.conventionLabelNames().length} names) — \`colab labels --ensure\`, CONVENTIONS.md §9 step 3 (#206)` },
|
|
401
402
|
{ n: 4, text: 'Optional: add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4. Needs repo ADMIN (push access alone gets `HTTP 404 …/topics`); nothing in colab or the audit reads it, so skip it when you are not one (#522)' },
|
|
402
403
|
);
|
|
403
404
|
if (ctx.fork) {
|
package/tools/lib/ci-forgejo.js
CHANGED
|
@@ -122,9 +122,22 @@ function create(repoAbs, eng) {
|
|
|
122
122
|
if (page === MAX_PAGES) return null; // more statuses than we read: never a partial verdict
|
|
123
123
|
}
|
|
124
124
|
const rows = rowsFromPages(full, pages);
|
|
125
|
-
|
|
125
|
+
if (rows === null) return null;
|
|
126
|
+
const summary = require('./git').summarizeRunsForCommit(rows, full);
|
|
127
|
+
// #682: additive — the contexts that keep this sha from green, so a refusal can name them.
|
|
128
|
+
const ng = notGreen(rows);
|
|
129
|
+
return ng.length ? { ...summary, notGreen: ng } : summary;
|
|
126
130
|
},
|
|
127
131
|
};
|
|
128
132
|
}
|
|
129
133
|
|
|
130
|
-
|
|
134
|
+
/**
|
|
135
|
+
* #682: every context that is not `success` — still pending, or finished red — in the compact
|
|
136
|
+
* `{name, status, conclusion}` shape a verdict detail names them by. Pure; [] when all are green.
|
|
137
|
+
*/
|
|
138
|
+
function notGreen(rows) {
|
|
139
|
+
return (rows || []).filter((x) => !(x.status === 'completed' && x.conclusion === 'success'))
|
|
140
|
+
.map((x) => ({ name: x.workflowName || 'unnamed', status: x.status, conclusion: x.conclusion || null }));
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
module.exports = { create, withFetcher, statusRow, rowsFromPages, notGreen, PAGE_LIMIT };
|
package/tools/lib/ci-wait.js
CHANGED
|
@@ -118,6 +118,17 @@ function runState(s) {
|
|
|
118
118
|
return 'unknown';
|
|
119
119
|
}
|
|
120
120
|
|
|
121
|
+
/**
|
|
122
|
+
* #682: one poll on a forge the engine map names, from its `ciVerdict` summary (tools/lib/ci-forgejo.js)
|
|
123
|
+
* — the waitLoop result shape, with no ETag (a forge read is never conditional, so no 304 can pin a
|
|
124
|
+
* stale state). A null summary is a failed read: `error`, which ends the wait UNKNOWN, never "keep
|
|
125
|
+
* waiting". Pure.
|
|
126
|
+
*/
|
|
127
|
+
function forgePoll(summary, engine = 'forge') {
|
|
128
|
+
if (!summary) return { kind: 'error', status: null, detail: `${engine} commit-status read failed` };
|
|
129
|
+
return { kind: 'ok', status: 200, etag: null, summary, state: runState(summary) };
|
|
130
|
+
}
|
|
131
|
+
|
|
121
132
|
/**
|
|
122
133
|
* #505: how many 304s in a row may stand for the state before the next poll re-reads without
|
|
123
134
|
* `If-None-Match`. Measured: the runs-list read kept answering 304 for ten minutes while every run
|
|
@@ -223,6 +234,6 @@ function sleepSync(ms) {
|
|
|
223
234
|
|
|
224
235
|
module.exports = {
|
|
225
236
|
EXIT, DEFAULT_SCHEDULE_SEC, DEFAULT_DEADLINE_SEC, DEFAULT_MAX_NOT_MODIFIED,
|
|
226
|
-
delayFor, parseHttp, classifyResponse, restRow, runState, waitLoop, fmtDuration, parseDuration,
|
|
237
|
+
delayFor, parseHttp, classifyResponse, restRow, runState, forgePoll, waitLoop, fmtDuration, parseDuration,
|
|
227
238
|
acquireLock, sleepSync,
|
|
228
239
|
};
|
|
@@ -22,6 +22,15 @@ export const CONVENTION_LABELS: ConventionLabel[];
|
|
|
22
22
|
export function conventionLabelNames(): string[];
|
|
23
23
|
export function missingConventionLabels(present: LabelLike[] | null | undefined): string[];
|
|
24
24
|
export function staleConventionDescriptions(present: LabelLike[] | null | undefined): { name: string; have: string; want: string }[];
|
|
25
|
+
/** #683: a deprecated spelling, the label replacing it, and the last day (YYYY-MM-DD) of its window. */
|
|
26
|
+
export interface DeprecatedLabel { name: string; replacedBy: string; until: string; }
|
|
27
|
+
export const HUMAN_WAIT_ALIAS_UNTIL: string;
|
|
28
|
+
export const DEPRECATED_LABELS: ReadonlyArray<DeprecatedLabel>;
|
|
29
|
+
export function deprecatedLabel(name: LabelLike): DeprecatedLabel | null;
|
|
30
|
+
export function deprecatedLabelDecision(entry: DeprecatedLabel, facts?: { today?: string; open?: number[] | null }):
|
|
31
|
+
| { action: 'move'; reason: 'open'; open: number[] }
|
|
32
|
+
| { action: 'delete'; reason: 'spent'; open: [] }
|
|
33
|
+
| { action: 'keep'; reason: 'unread' | 'window' | 'bad-date'; open: [] };
|
|
25
34
|
export const MINIMAL_LABEL_NAMES: string[];
|
|
26
35
|
export function minimalConventionLabels(): ConventionLabel[];
|
|
27
36
|
|
|
@@ -213,6 +213,15 @@
|
|
|
213
213
|
* malignant-absence reason above: the moment a human wants to veto is a test period that is
|
|
214
214
|
* already counting down, and a label the repo never created cannot be applied in that moment —
|
|
215
215
|
* the veto would silently not exist. Only a human removes it; no command in this repo does.
|
|
216
|
+
*
|
|
217
|
+
* `blocked:needs-human` joined the set in #683: the park label for "waits until a person decides
|
|
218
|
+
* or acts" — the label form of the `needs-human` disposition (tools/lib/disposition.js). Before
|
|
219
|
+
* it the wait had two role-named spellings (DEPRECATED_LABELS below), neither provisioned, so
|
|
220
|
+
* adopters hand-created them with different colours and descriptions, and on an install where
|
|
221
|
+
* the person who lifts the park is not the install's owner the name pointed at someone else.
|
|
222
|
+
* Provisioned for the malignant-absence reason above: a park a session wants to record must be
|
|
223
|
+
* appliable at that moment. Not in MINIMAL_LABEL_NAMES — a session's start → wrap → ship path
|
|
224
|
+
* does not write it.
|
|
216
225
|
*/
|
|
217
226
|
|
|
218
227
|
const CONVENTION_LABELS = [
|
|
@@ -239,8 +248,55 @@ const CONVENTION_LABELS = [
|
|
|
239
248
|
{ name: 'deferred:measurement', color: '7C6F57', description: 'Parked until a metric crosses a threshold — name the metric and the threshold on the issue' },
|
|
240
249
|
{ name: 'deferred:external-party', color: '6E5494', description: 'Parked until someone outside this repo acts — name who, and pair with review-by:<date>' },
|
|
241
250
|
{ name: 'release-hold', color: 'E11D21', description: 'Human veto on a release tracking issue: its candidate is not finalized while this is present' },
|
|
251
|
+
{ name: 'blocked:needs-human', color: 'D93F0B', description: 'Parked until a person decides or acts — a decision or an act only a person can give' },
|
|
242
252
|
];
|
|
243
253
|
|
|
254
|
+
// The label alias table (#683) — deprecated spellings of a convention label, each with the label
|
|
255
|
+
// that replaces it and the last day of its migration window (YYYY-MM-DD). Read, never written:
|
|
256
|
+
// nothing in this repo applies one. `colab labels --ensure` reports open issues still carrying
|
|
257
|
+
// one, `--relabel-deprecated` moves them, and `--prune-deprecated` deletes the old label once the
|
|
258
|
+
// window is over (deprecatedLabelDecision below). The window is a DATE, not a release count:
|
|
259
|
+
// minor releases here ship days apart, so a release-counted window would close before most
|
|
260
|
+
// adopters had synced once. Dropping an entry is a separate change, made after its date.
|
|
261
|
+
const HUMAN_WAIT_ALIAS_UNTIL = '2027-01-06';
|
|
262
|
+
const DEPRECATED_LABELS = Object.freeze([
|
|
263
|
+
Object.freeze({ name: 'blocked:needs-owner', replacedBy: 'blocked:needs-human', until: HUMAN_WAIT_ALIAS_UNTIL }),
|
|
264
|
+
Object.freeze({ name: 'blocked:needs-boss', replacedBy: 'blocked:needs-human', until: HUMAN_WAIT_ALIAS_UNTIL }),
|
|
265
|
+
]);
|
|
266
|
+
|
|
267
|
+
/** The DEPRECATED_LABELS entry for `name`, or null. Tolerant of a label object or a bare string. */
|
|
268
|
+
function deprecatedLabel(name) {
|
|
269
|
+
const s = name && typeof name === 'object' ? name.name : name;
|
|
270
|
+
return DEPRECATED_LABELS.find((d) => d.name === s) || null;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* What to do with one deprecated label on one tracker — pure, so the clock and the tracker read
|
|
275
|
+
* are both inputs (#683). `entry` is a DEPRECATED_LABELS row, `today` a YYYY-MM-DD string, `open`
|
|
276
|
+
* the open issue numbers carrying the label from a NON-search read (null = could not read).
|
|
277
|
+
*
|
|
278
|
+
* Returns { action, reason, open }:
|
|
279
|
+
* - `move` — open issues carry it: relabel them onto `entry.replacedBy`. Moving is always
|
|
280
|
+
* allowed, inside the window or after it.
|
|
281
|
+
* - `delete` — the window is over (today is after `until`) AND the read confirms no open issue
|
|
282
|
+
* carries it: the label object may be deleted.
|
|
283
|
+
* - `keep` — anything else: `unread` (the read failed — never read as "none open"), `window`
|
|
284
|
+
* (still inside the window; aliases are guaranteed until `until`), `bad-date`.
|
|
285
|
+
*
|
|
286
|
+
* Deleting a label object strips it from closed issues too and cannot be undone from the tracker,
|
|
287
|
+
* so every unclear input keeps — the same posture as group-labels.js's spent-label teardown.
|
|
288
|
+
*/
|
|
289
|
+
function deprecatedLabelDecision(entry, { today, open } = {}) {
|
|
290
|
+
if (!Array.isArray(open)) return { action: 'keep', reason: 'unread', open: [] };
|
|
291
|
+
if (open.length) return { action: 'move', reason: 'open', open: [...open] };
|
|
292
|
+
const day = /^\d{4}-\d{2}-\d{2}$/;
|
|
293
|
+
if (!entry || !day.test(String(entry.until)) || !day.test(String(today))) {
|
|
294
|
+
return { action: 'keep', reason: 'bad-date', open: [] };
|
|
295
|
+
}
|
|
296
|
+
if (today <= entry.until) return { action: 'keep', reason: 'window', open: [] };
|
|
297
|
+
return { action: 'delete', reason: 'spent', open: [] };
|
|
298
|
+
}
|
|
299
|
+
|
|
244
300
|
// The DELIVERY label prefix (CONVENTIONS.md §5, Delivery type). Six fixed values, unlike
|
|
245
301
|
// `group:<key>` — provisioned up front in CONVENTION_LABELS above, not created on demand.
|
|
246
302
|
const DELIVERY_LABEL_PREFIX = 'delivery:';
|
|
@@ -707,6 +763,7 @@ function encodeLabel(label) {
|
|
|
707
763
|
|
|
708
764
|
module.exports = {
|
|
709
765
|
CONVENTION_LABELS, conventionLabelNames, missingConventionLabels, staleConventionDescriptions,
|
|
766
|
+
HUMAN_WAIT_ALIAS_UNTIL, DEPRECATED_LABELS, deprecatedLabel, deprecatedLabelDecision,
|
|
710
767
|
MINIMAL_LABEL_NAMES, minimalConventionLabels,
|
|
711
768
|
READINESS_LABEL, readinessLabelArgs, readinessMissingLabelHint, readinessMarkedMessage,
|
|
712
769
|
TRACKING_LABEL,
|
package/tools/lib/disposition.js
CHANGED
|
@@ -69,19 +69,21 @@ const HUMAN = 'human';
|
|
|
69
69
|
* GitHub's close reason takes. Frozen and closed: a kind outside this list is not a disposition
|
|
70
70
|
* with an unknown authority, it is not a disposition.
|
|
71
71
|
*/
|
|
72
|
-
const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-
|
|
72
|
+
const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-human', 'not planned', 'leave']);
|
|
73
73
|
|
|
74
74
|
/**
|
|
75
|
-
* #609 — names this module still READS but never writes.
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
75
|
+
* #609, #683 — the alias table: names this module still READS but never writes. The person-wait
|
|
76
|
+
* kind is `needs-human` — it names the wait, not a role, so it reads right on any install,
|
|
77
|
+
* whoever lifts the park. Both older names are deprecated aliases of it. During the switch a
|
|
78
|
+
* reader must accept them, or an issue marked under an old name reads as unrecognised — "not
|
|
79
|
+
* cleared" — to a tool that only knows the new one. Each alias classifies exactly like the kind
|
|
80
|
+
* it maps to. Kept out of KINDS / TOKENS / TOKEN_BY_KIND on purpose: those are what a writer may
|
|
81
|
+
* emit, and `formatMarker` refuses an alias. The window the aliases are guaranteed for is the
|
|
82
|
+
* label alias table's date (`HUMAN_WAIT_ALIAS_UNTIL`, tools/lib/codec/labels.js). Reading does
|
|
83
|
+
* not stop at that date; dropping an entry is a separate change, made after it.
|
|
82
84
|
*/
|
|
83
|
-
const LEGACY_KINDS = Object.freeze({ 'needs-boss': 'needs-
|
|
84
|
-
const LEGACY_TOKENS = Object.freeze({ 'needs-boss': 'needs-
|
|
85
|
+
const LEGACY_KINDS = Object.freeze({ 'needs-owner': 'needs-human', 'needs-boss': 'needs-human' });
|
|
86
|
+
const LEGACY_TOKENS = Object.freeze({ 'needs-owner': 'needs-human', 'needs-boss': 'needs-human' });
|
|
85
87
|
|
|
86
88
|
/**
|
|
87
89
|
* The same seven by MARKER TOKEN. No token is a prefix or a decorated variant of another — the
|
|
@@ -94,13 +96,13 @@ const TOKEN_BY_KIND = Object.freeze({
|
|
|
94
96
|
split: 'split',
|
|
95
97
|
'routed-out': 'routed-out',
|
|
96
98
|
hold: 'hold',
|
|
97
|
-
'needs-
|
|
99
|
+
'needs-human': 'needs-human',
|
|
98
100
|
'not planned': 'not-planned',
|
|
99
101
|
leave: 'leave',
|
|
100
102
|
});
|
|
101
103
|
const KIND_BY_TOKEN = Object.freeze({
|
|
102
104
|
...Object.fromEntries(Object.entries(TOKEN_BY_KIND).map(([kind, token]) => [token, kind])),
|
|
103
|
-
...LEGACY_TOKENS, // read-only: a legacy token parses to the current kind (#609)
|
|
105
|
+
...LEGACY_TOKENS, // read-only: a legacy token parses to the current kind (#609, #683)
|
|
104
106
|
});
|
|
105
107
|
const TOKENS = Object.freeze(Object.values(TOKEN_BY_KIND));
|
|
106
108
|
|
|
@@ -348,11 +350,11 @@ function classify(facts) {
|
|
|
348
350
|
: verdict(kind, AGENT, true, 'the park names what it is waiting on — the agent applies', []);
|
|
349
351
|
}
|
|
350
352
|
|
|
351
|
-
case 'needs-
|
|
353
|
+
case 'needs-human':
|
|
352
354
|
// Record-first: the pass writes the question down with the apply lever pre-filled and moves
|
|
353
355
|
// on. It does not stop and wait, and it never applies this itself.
|
|
354
356
|
return verdict(kind, HUMAN, true,
|
|
355
|
-
'never applied by an agent — the agent records the question,
|
|
357
|
+
'never applied by an agent — the agent records the question, a person answers, the issue returns to intake', []);
|
|
356
358
|
|
|
357
359
|
case 'not planned': {
|
|
358
360
|
const sup = f.supersededBy && typeof f.supersededBy === 'object' ? f.supersededBy : {};
|
package/tools/lib/stale-base.js
CHANGED
|
@@ -77,4 +77,50 @@ function staleBaseVerdict(a) {
|
|
|
77
77
|
'push, wait on the new run (15-minute bound), then re-run ship' };
|
|
78
78
|
}
|
|
79
79
|
|
|
80
|
-
|
|
80
|
+
/**
|
|
81
|
+
* #682: is the branch head's OWN CI green? Read on a forge the engine map names (#678), where no
|
|
82
|
+
* `colab ci-wait` used to exist for code-ship B1a to classify the branch with — so a red or running
|
|
83
|
+
* branch head passed `colab ship --dry` as READY on the stale-base row alone (that row asks only
|
|
84
|
+
* whether the run saw the base). The forge's summary is the same `ciVerdict` the trunk row reads.
|
|
85
|
+
*
|
|
86
|
+
* completed / success -> green, passes
|
|
87
|
+
* completed / other -> red, human-gated: a branch lands only on its own green (C7.contract.03);
|
|
88
|
+
* whether it is red:infra (one re-run) or red:finding (send back) is B1a's
|
|
89
|
+
* anything unfinished -> pending, self-clearing: wait (`colab ci-wait`), then ship again
|
|
90
|
+
*
|
|
91
|
+
* Returns null where this row says nothing: no head on the remote, an unread run (the stale-base
|
|
92
|
+
* row already refuses that as `unread`), or no status at all (the `none` row of Branch CI governs).
|
|
93
|
+
* `run.notGreen` (tools/lib/ci-forgejo.js) names the contexts that keep the sha from green.
|
|
94
|
+
*
|
|
95
|
+
* @param {object} a
|
|
96
|
+
* @param {string|null} a.headSha - the branch head on the remote
|
|
97
|
+
* @param {object|null} a.run - the forge's ciVerdict summary at headSha
|
|
98
|
+
* @param {string} a.branch
|
|
99
|
+
* @param {string} [a.engine] - for the detail line, e.g. 'forgejo'
|
|
100
|
+
* @returns {null|{ok:boolean, verdict:'green'|'red'|'pending', selfClearing:boolean, detail:string}}
|
|
101
|
+
*/
|
|
102
|
+
function branchHeadCiVerdict(a) {
|
|
103
|
+
const run = a && a.run;
|
|
104
|
+
if (!a || !a.headSha || !run || run.status === 'none') return null;
|
|
105
|
+
const at = `${a.branch}@${String(a.headSha).slice(0, 7)} (${a.engine || 'forge'} commit status)`;
|
|
106
|
+
const ng = Array.isArray(run.notGreen) ? run.notGreen : [];
|
|
107
|
+
const name = (x) => `${x.name} (${x.status === 'completed' ? (x.conclusion || 'none') : x.status})`;
|
|
108
|
+
if (run.status === 'completed' && run.conclusion === 'success') {
|
|
109
|
+
const n = run.runCount == null ? 1 : run.runCount;
|
|
110
|
+
return { ok: true, verdict: 'green', selfClearing: false, detail: `${n} context${n === 1 ? '' : 's'} at ${at}: ${n === 1 ? 'success' : 'all success'}` };
|
|
111
|
+
}
|
|
112
|
+
if (run.status === 'completed') {
|
|
113
|
+
const red = ng.filter((x) => x.status === 'completed');
|
|
114
|
+
const still = ng.filter((x) => x.status !== 'completed');
|
|
115
|
+
return { ok: false, verdict: 'red', selfClearing: false,
|
|
116
|
+
detail: `${at} is red — failing: ${red.length ? red.map(name).join(', ') : `conclusion=${run.conclusion || 'none'}`}` +
|
|
117
|
+
`${still.length ? `; still running: ${still.map(name).join(', ')}` : ''}. A branch lands only on its own green (C7.contract.03): ` +
|
|
118
|
+
'red:infra → re-run once; red:finding → send it back (code-ship B1a)' };
|
|
119
|
+
}
|
|
120
|
+
const still = ng.filter((x) => x.status !== 'completed');
|
|
121
|
+
return { ok: false, verdict: 'pending', selfClearing: true,
|
|
122
|
+
detail: `${at} has not finished — still running: ${still.length ? still.map(name).join(', ') : `status=${run.status}`}. ` +
|
|
123
|
+
`Wait with \`colab ci-wait --sha ${a.headSha} --branch ${a.branch}\`, then run ship again` };
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
module.exports = { staleBaseVerdict, branchHeadCiVerdict };
|