@futurelastic/colab-handbook 1.12.0-rc.26 → 1.12.0-rc.28
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 +37 -1
- package/tools/lib/migration-grant.js +88 -0
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-finalize.js +2 -2
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -3660,7 +3660,13 @@ It is minted only when ALL of these hold, checked before any network call:
|
|
|
3660
3660
|
- the record is well-formed AND passing (approve · checklist pass · escalation clear · CI pass) —
|
|
3661
3661
|
a grant carrying a failing review is a contradiction, so it is refused, not recorded;
|
|
3662
3662
|
- the branch is pushed, and --head (if given) equals origin's tip — the grant binds that tip;
|
|
3663
|
-
- this checkout's project.yml declares \`migration-grant: reviewer\` (#398; absent = human)
|
|
3663
|
+
- this checkout's project.yml declares \`migration-grant: reviewer\` (#398; absent = human);
|
|
3664
|
+
- checklist-items, when given, is <passed>/${migrationGrant.REVIEW_CHECKLIST_ITEMS} and, with checklist pass, every item
|
|
3665
|
+
passed (#457) — the record counts against the checklist the migration-review skill walks today.
|
|
3666
|
+
Then, read from CI after the tracker read and before anything is written (#457):
|
|
3667
|
+
- ci-roundtrip pass is TRUE at the head: the "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" job ran and
|
|
3668
|
+
passed there (the rule ship applies), and --ci-run, when given, is one of the runs at that
|
|
3669
|
+
head and carries the job. A repo whose CI has no such job cannot mint a reviewer grant at all.
|
|
3664
3670
|
COLAB_HUMAN=1 is still required for every role. The reviewer identity is DECLARED, not attested.
|
|
3665
3671
|
\`colab ship\` honours a reviewer grant only when ALL of (#401): P the target's project.yml says
|
|
3666
3672
|
\`migration-grant: reviewer\` · M this record is live, trusted and passing · HEAD its head is the
|
|
@@ -3796,9 +3802,36 @@ function migrationGrantReviewRecord(repoAbs, opts) {
|
|
|
3796
3802
|
if (!v.passing) {
|
|
3797
3803
|
throw new UserError(`the review does not pass (${migrationGrant.reviewRecordFailure(rec)}) — a grant carrying a failing review is a contradiction; nothing was posted`);
|
|
3798
3804
|
}
|
|
3805
|
+
// #457: checks only a NEW record faces (the checklist denominator) — local, so before the gh gate.
|
|
3806
|
+
const mintProblems = migrationGrant.mintRecordProblems(rec);
|
|
3807
|
+
if (mintProblems.length) throw new UserError(`the review record is invalid: ${mintProblems.join('; ')}`);
|
|
3799
3808
|
return rec;
|
|
3800
3809
|
}
|
|
3801
3810
|
|
|
3811
|
+
/**
|
|
3812
|
+
* #457: the record says `ci-roundtrip: pass` — read CI at its head and refuse unless the round-trip
|
|
3813
|
+
* job is really there and passed (tools/lib/migration-grant.js mintRoundtripCheck: the same
|
|
3814
|
+
* roundtripVerdict `colab ship` applies, plus the cited `ci-run` must carry the job). Needs gh, so
|
|
3815
|
+
* it runs in cmdMigrationGrantCreate after the tracker read and BEFORE the label is applied —
|
|
3816
|
+
* nothing is written when it refuses. The workflows guard diffs trunk against the reviewed head;
|
|
3817
|
+
* an unreadable diff counts as touched, failing closed exactly as shipMigrationCtx does.
|
|
3818
|
+
*/
|
|
3819
|
+
function migrationGrantRoundtripCheck(repoAbs, branch, rec) {
|
|
3820
|
+
if (rec['ci-roundtrip'] !== 'pass') return;
|
|
3821
|
+
const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
|
|
3822
|
+
const remote = git.remoteInfo(repoAbs).name || 'origin';
|
|
3823
|
+
let d = trunk ? git.git(['diff', '--name-only', `${remote}/${trunk}...${rec.head}`], repoAbs) : { ok: false };
|
|
3824
|
+
if (!d.ok && trunk) d = git.git(['diff', '--name-only', `${trunk}...${rec.head}`], repoAbs);
|
|
3825
|
+
const workflowsTouched = !d.ok || d.stdout.split('\n').some((f) => f.startsWith('.github/workflows/'));
|
|
3826
|
+
let runs = null;
|
|
3827
|
+
const list = git.ghRunsForCommit(repoAbs, branch, rec.head, 20);
|
|
3828
|
+
if (Array.isArray(list)) {
|
|
3829
|
+
runs = list.map((r) => ({ databaseId: r.databaseId, workflowName: r.workflowName || null, jobs: git.ghRunJobs(repoAbs, r.databaseId) }));
|
|
3830
|
+
}
|
|
3831
|
+
const c = migrationGrant.mintRoundtripCheck(rec, runs, { workflowsTouched });
|
|
3832
|
+
if (!c.ok) throw new UserError(`${c.reason}; nothing was posted`);
|
|
3833
|
+
}
|
|
3834
|
+
|
|
3802
3835
|
function cmdMigrationGrantCreate(repoAbs, num, opts) {
|
|
3803
3836
|
// --branch and branch existence are already validated by cmdMigrationGrant, ahead of the
|
|
3804
3837
|
// isGhUsable gate — see the comment there. Kept as a defensive re-check in case this function is
|
|
@@ -3822,6 +3855,9 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
|
|
|
3822
3855
|
|| `this repo has no \`${labels.MIGRATION_GRANT_LABEL}\` label`);
|
|
3823
3856
|
}
|
|
3824
3857
|
|
|
3858
|
+
// #457: a record claiming a CI round-trip pass is checked against CI BEFORE anything is written.
|
|
3859
|
+
if (opts.reviewRecord) migrationGrantRoundtripCheck(repoAbs, opts.branch, opts.reviewRecord);
|
|
3860
|
+
|
|
3825
3861
|
const editR = git.ghIssueEdit(repoAbs, num, labels.migrationGrantLabelArgs({}));
|
|
3826
3862
|
if (!editR.ok) throw new UserError(`gh edit #${num} failed (${editR.stderr.split('\n')[0] || editR.code})`);
|
|
3827
3863
|
|
|
@@ -345,6 +345,61 @@ function roundtripVerdict(jobs, opts) {
|
|
|
345
345
|
return { ok: true, legs, reason: '' };
|
|
346
346
|
}
|
|
347
347
|
|
|
348
|
+
/**
|
|
349
|
+
* #457 — the MINT-time half of R. `colab ship` re-reads the round-trip at the head (roundtripVerdict
|
|
350
|
+
* above, through shipMigrationCtx), so a false `ci-roundtrip: pass` never opened the gate — but the
|
|
351
|
+
* grant record itself could still assert a fact its cited run does not contain, and the issue then
|
|
352
|
+
* sat looking "granted" until a ship pass measured it. This applies the same verdict when the record
|
|
353
|
+
* is WRITTEN, so a record that says `pass` is refused unless CI agrees at `rec.head`.
|
|
354
|
+
*
|
|
355
|
+
* Pure: `runs` is every run at the head — `[{ databaseId, workflowName, jobs }]`, `jobs` being
|
|
356
|
+
* git.ghRunJobs rows — or null when the run list could not be read (a run with `jobs: null` is an
|
|
357
|
+
* unread run). Checks, in order:
|
|
358
|
+
* - the run list and every run's jobs were read (an unread result is never a pass);
|
|
359
|
+
* - roundtripVerdict over all their jobs is ok — the exact rule ship applies, workflows guard
|
|
360
|
+
* included, so a record mint can never accept what ship would refuse;
|
|
361
|
+
* - `ci-run`, when given, resolves to a run id (bare digits, or a `/runs/<id>` URL), names one of
|
|
362
|
+
* those runs, and that run itself carries a round-trip job — a record must not cite a run that
|
|
363
|
+
* does not contain the evidence it is cited for, even when a sibling run does.
|
|
364
|
+
* A record whose `ci-roundtrip` is not `pass` is not this function's to judge (it never mints).
|
|
365
|
+
* Returns { ok, reason, verdict }.
|
|
366
|
+
*/
|
|
367
|
+
function mintRoundtripCheck(rec, runs, opts) {
|
|
368
|
+
const o = opts || {};
|
|
369
|
+
const r = rec || {};
|
|
370
|
+
if (r['ci-roundtrip'] !== 'pass') return { ok: true, reason: '', verdict: null };
|
|
371
|
+
const sha = r.head ? String(r.head).slice(0, 7) : 'the head';
|
|
372
|
+
const no = (reason, verdict = null) => ({ ok: false, reason, verdict });
|
|
373
|
+
let jobs = null;
|
|
374
|
+
if (Array.isArray(runs) && runs.every((x) => x && Array.isArray(x.jobs))) {
|
|
375
|
+
jobs = [];
|
|
376
|
+
for (const x of runs) for (const j of x.jobs) jobs.push({ ...j, workflowName: x.workflowName || null });
|
|
377
|
+
}
|
|
378
|
+
const verdict = roundtripVerdict(jobs, { headSha: r.head, workflowsTouched: !!o.workflowsTouched });
|
|
379
|
+
if (!verdict.ok) {
|
|
380
|
+
const hint = verdict.reason.startsWith('no "') ? ` — this repo's CI must run the template's migrations job before a reviewer grant can record a pass` : '';
|
|
381
|
+
return no(`the record says ci-roundtrip: pass, but ${verdict.reason}${hint}`, verdict);
|
|
382
|
+
}
|
|
383
|
+
if (r['ci-run'] !== undefined && r['ci-run'] !== null && String(r['ci-run']) !== '') {
|
|
384
|
+
const id = parseRunId(r['ci-run']);
|
|
385
|
+
if (id === null) return no(`ci-run "${r['ci-run']}" does not name a run id (digits, or a URL ending /runs/<id>) — a cited run nobody can look up proves nothing`, verdict);
|
|
386
|
+
const cited = runs.find((x) => String(x.databaseId) === id);
|
|
387
|
+
if (!cited) return no(`ci-run ${id} is not a run at ${sha} — the record must cite the run that graded the head it binds`, verdict);
|
|
388
|
+
if (!cited.jobs.some((j) => j && typeof j.name === 'string' && j.name.startsWith(ROUNDTRIP_JOB_PREFIX))) {
|
|
389
|
+
return no(`ci-run ${id} has no "${ROUNDTRIP_JOB_PREFIX}" job — cite the run that carries the round-trip`, verdict);
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
return { ok: true, reason: '', verdict };
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
/** A run id from a `ci-run` value — bare digits, or the `/runs/<id>` segment of a run URL — or null. */
|
|
396
|
+
function parseRunId(v) {
|
|
397
|
+
const s = String(v).trim();
|
|
398
|
+
if (/^\d+$/.test(s)) return s;
|
|
399
|
+
const m = s.match(/\/runs\/(\d+)(?:[/?#]|$)/);
|
|
400
|
+
return m ? m[1] : null;
|
|
401
|
+
}
|
|
402
|
+
|
|
348
403
|
/** A step that reached a terminal conclusion other than skipped/cancelled — ci-cure.js stepRan. */
|
|
349
404
|
function stepRanOk(s) {
|
|
350
405
|
return !!s && s.status === 'completed' && s.conclusion !== 'skipped' && s.conclusion !== 'cancelled';
|
|
@@ -448,6 +503,37 @@ function validateReviewRecord(rec, marker) {
|
|
|
448
503
|
return { valid, passing, problems };
|
|
449
504
|
}
|
|
450
505
|
|
|
506
|
+
/** #457 — the checklist the migration-review skill walks has this many items, so a record's
|
|
507
|
+
* `checklist-items` is `<passed>/10`. Kept in step with skills/migration-review/SKILL.md (a test
|
|
508
|
+
* reads the skill and pins it). */
|
|
509
|
+
const REVIEW_CHECKLIST_ITEMS = 10;
|
|
510
|
+
|
|
511
|
+
/**
|
|
512
|
+
* #457 — record checks that apply only when a grant is MINTED, never when one is read. They are
|
|
513
|
+
* kept out of validateReviewRecord on purpose: that function is also ship's read path, and a
|
|
514
|
+
* grant recorded under an older, shorter checklist must not change meaning after the fact (ship
|
|
515
|
+
* re-verifies everything that matters — HEAD and the live round-trip — on its own). A new record,
|
|
516
|
+
* though, must be counted against the checklist that exists today:
|
|
517
|
+
* - `checklist-items`, when given, has denominator REVIEW_CHECKLIST_ITEMS;
|
|
518
|
+
* - `checklist: pass` with `checklist-items` N/M needs N = M — a pass with an item failing is a
|
|
519
|
+
* contradiction, the same way a grant carrying a failing review is.
|
|
520
|
+
* Returns a list of problems ([] = fine).
|
|
521
|
+
*/
|
|
522
|
+
function mintRecordProblems(rec) {
|
|
523
|
+
const r = rec || {};
|
|
524
|
+
const problems = [];
|
|
525
|
+
const items = r['checklist-items'];
|
|
526
|
+
if (items === undefined || items === null || !/^\d+\/\d+$/.test(String(items))) return problems;
|
|
527
|
+
const [a, b] = String(items).split('/').map(Number);
|
|
528
|
+
if (b !== REVIEW_CHECKLIST_ITEMS) {
|
|
529
|
+
problems.push(`"checklist-items" is ${items} — the migration-review checklist has ${REVIEW_CHECKLIST_ITEMS} items, so the record is <passed>/${REVIEW_CHECKLIST_ITEMS}`);
|
|
530
|
+
}
|
|
531
|
+
if (r.checklist === 'pass' && a !== b) {
|
|
532
|
+
problems.push(`"checklist" is pass but "checklist-items" is ${items} — a pass means every item passed`);
|
|
533
|
+
}
|
|
534
|
+
return problems;
|
|
535
|
+
}
|
|
536
|
+
|
|
451
537
|
/** Why a VALID record is not passing, as one line — or '' when it passes. */
|
|
452
538
|
function reviewRecordFailure(rec) {
|
|
453
539
|
const why = [];
|
|
@@ -638,4 +724,6 @@ module.exports = {
|
|
|
638
724
|
GRANT_POLICIES, parseGrantPolicy,
|
|
639
725
|
// #401 — ship honours a reviewer grant
|
|
640
726
|
ROUNDTRIP_JOB_PREFIX, roundtripVerdict, SHIP_CONDITION_TAG,
|
|
727
|
+
// #457 — the mint-time checks
|
|
728
|
+
REVIEW_CHECKLIST_ITEMS, mintRecordProblems, mintRoundtripCheck, parseRunId,
|
|
641
729
|
};
|
package/tools/lib/place.js
CHANGED
|
@@ -592,7 +592,7 @@ function ownsHold(rec, session) {
|
|
|
592
592
|
* (#317.)
|
|
593
593
|
*
|
|
594
594
|
* WHY THIS EXISTS. A ship session recovered an issue with a no-worktree claim, which minted a
|
|
595
|
-
* checkout hold under the identity string `
|
|
595
|
+
* checkout hold under the identity string `example-orchestrator-1545`. It then shipped, and every later
|
|
596
596
|
* squash-merge was refused by ITS OWN hold: the identity `colab ship` resolves comes from the
|
|
597
597
|
* worktree record or a branch-keyed claim, and a no-worktree claim carries `branch: null`, so the
|
|
598
598
|
* session presented a blank one. `ownsHold` is exact string equality and blank never matches, so a
|
|
@@ -663,7 +663,7 @@ function ownsPlace(rec, session, anchorOpts = {}) {
|
|
|
663
663
|
* no two consumers disagree (#317). Returns `{cls, rec, live, reason, remedy, conflict}`.
|
|
664
664
|
*
|
|
665
665
|
* The live specimen this closes was not a wrong answer; it was an UNCLASSIFIED one. `colab ship`
|
|
666
|
-
* printed `place "…" is held by session "
|
|
666
|
+
* printed `place "…" is held by session "example-orchestrator-1545"` and stopped — true, and useless:
|
|
667
667
|
* the reader could not tell from it whether the holder was itself, a corpse, or a live sibling, and
|
|
668
668
|
* those three need three different next moves. The refusal now names the class and the exact next
|
|
669
669
|
* command, and two of the six classes are not refusals at all.
|
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
* PURE BY CONSTRUCTION, the release-cut.js posture: no git, no network, no `gh`, no clock (`now` is
|
|
10
10
|
* passed in). The CLI in tools/colab is the measuring half.
|
|
11
11
|
*
|
|
12
|
-
* WHERE PER-CANDIDATE STATE LIVES (the contract
|
|
13
|
-
* consumer breaks, so it is frozen here and documented in tools/README.md, *Release finalize*):
|
|
12
|
+
* WHERE PER-CANDIDATE STATE LIVES (the contract a downstream dashboard's release view reads — change
|
|
13
|
+
* it and every consumer breaks, so it is frozen here and documented in tools/README.md, *Release finalize*):
|
|
14
14
|
*
|
|
15
15
|
* - the candidates are the annotated `vX.Y.Z-rc.N` tags on origin that `colab release cut` made
|
|
16
16
|
* (first line of the tag message ends `(colab release cut)`); nothing else stores them;
|