@futurelastic/colab-handbook 1.12.0 → 1.13.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/README.md +243 -213
- package/README.vi.md +246 -186
- package/audit/audit.mjs +193 -10
- package/package.json +6 -1
- package/templates/README.md +30 -2
- package/templates/ci-laravel.yml +102 -21
- package/templates/ci-node.yml +61 -3
- package/templates/ci-python.yml +52 -3
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +368 -0
- package/templates/deploy-container.yml +219 -0
- package/templates/dist-refs.yml +6 -0
- package/templates/docs-lint.mjs +1 -1
- package/templates/npx-launcher.mjs +118 -20
- package/templates/npx-service.mjs +828 -0
- package/templates/release-auto.yml +341 -32
- package/tools/colab +1691 -254
- package/tools/lib/adopt.js +373 -14
- package/tools/lib/branch-name.js +29 -1
- package/tools/lib/ci-cure.js +522 -31
- package/tools/lib/ci-grant.js +289 -22
- package/tools/lib/ci-wait.js +203 -0
- package/tools/lib/claim-comments.js +13 -64
- package/tools/lib/claim-identity.js +4 -7
- package/tools/lib/codec/claim.d.ts +41 -0
- package/tools/lib/codec/claim.js +151 -0
- package/tools/lib/codec/decision.d.ts +29 -0
- package/tools/lib/codec/decision.js +81 -0
- package/tools/lib/codec/grants.d.ts +82 -0
- package/tools/lib/codec/grants.js +268 -0
- package/tools/lib/codec/hold.d.ts +26 -0
- package/tools/lib/codec/hold.js +152 -0
- package/tools/lib/codec/index.d.ts +21 -0
- package/tools/lib/codec/index.js +32 -0
- package/tools/lib/codec/labels.d.ts +65 -0
- package/tools/lib/codec/labels.js +716 -0
- package/tools/lib/codec/markers.d.ts +35 -0
- package/tools/lib/codec/markers.js +138 -0
- package/tools/lib/codec/release.d.ts +17 -0
- package/tools/lib/codec/release.js +69 -0
- package/tools/lib/codec/samples.json +762 -0
- package/tools/lib/codeowners.js +68 -4
- package/tools/lib/container-close.js +38 -0
- package/tools/lib/cure-diff.js +198 -9
- package/tools/lib/decision-record.js +15 -39
- package/tools/lib/docs-only.js +15 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/git.js +303 -42
- package/tools/lib/group-labels.js +65 -0
- package/tools/lib/install-check.js +14 -8
- package/tools/lib/install-route.js +139 -0
- package/tools/lib/instruction-file.js +1 -0
- package/tools/lib/labels.js +22 -647
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/migration-grant.js +206 -104
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-cut.js +199 -25
- package/tools/lib/release-finalize.js +111 -23
- package/tools/lib/release-policy.js +130 -22
- package/tools/lib/release-runner.js +125 -0
- package/tools/lib/release-tag.js +3 -1
- package/tools/lib/scratch-dirs.js +106 -0
- package/tools/lib/ship-batch.js +36 -1
- package/tools/lib/stamp.js +7 -0
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +64 -0
- package/tools/lib/tree-green.js +88 -0
- package/tools/lib/util.js +17 -1
- package/tools/lib/verify-runs.js +104 -0
- package/tools/lib/wake.js +8 -90
- package/tools/lib/workflow-triggers.js +48 -0
package/tools/lib/local-adopt.js
CHANGED
|
@@ -20,12 +20,16 @@
|
|
|
20
20
|
* Everything here is pure (text in, text/verdict out); tools/colab does the IO.
|
|
21
21
|
*/
|
|
22
22
|
|
|
23
|
+
const scratchDirs = require('./scratch-dirs');
|
|
24
|
+
|
|
23
25
|
/**
|
|
24
26
|
* Paths hidden by `.git/info/exclude`, root-anchored (a leading `/`) so they match only at the
|
|
25
27
|
* repo root — `CLAUDE.local.md` in a subdirectory the owner commits must stay visible.
|
|
26
|
-
*
|
|
28
|
+
* The session scratch dirs (plans, briefs — #488) are appended by `localExcludePaths` from
|
|
29
|
+
* scratch-dirs.js, so a configured COLAB_PLANS_DIR / COLAB_BRIEFS_DIR is hidden too; the legacy
|
|
30
|
+
* `.claude/plans/` stays among them.
|
|
27
31
|
*/
|
|
28
|
-
const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md'
|
|
32
|
+
const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md'];
|
|
29
33
|
|
|
30
34
|
/**
|
|
31
35
|
* LOCAL_EXCLUDE_PATHS plus the worktree subdir (`colab worktree new` creates worktrees INSIDE the
|
|
@@ -33,9 +37,9 @@ const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md', '/.clau
|
|
|
33
37
|
* `.gitignore`; the owner's repo does not, so without this line every worktree shows up in the
|
|
34
38
|
* main checkout's `git status` — measured on the #393 fixture the moment the first one was cut.
|
|
35
39
|
*/
|
|
36
|
-
function localExcludePaths(worktreeSubdir) {
|
|
40
|
+
function localExcludePaths(worktreeSubdir, env = process.env) {
|
|
37
41
|
const sub = String(worktreeSubdir || '.worktrees').replace(/^\/+|\/+$/g, '');
|
|
38
|
-
return [...LOCAL_EXCLUDE_PATHS, `/${sub}/`];
|
|
42
|
+
return [...LOCAL_EXCLUDE_PATHS, ...scratchDirs.excludeLines(env), `/${sub}/`];
|
|
39
43
|
}
|
|
40
44
|
|
|
41
45
|
const EXCLUDE_HEADER = '# colab-handbook: local-only adoption (#393) — handbook files this clone keeps out of the owner\'s history';
|
|
@@ -41,29 +41,26 @@
|
|
|
41
41
|
* this branch and this issue may rely on.
|
|
42
42
|
*/
|
|
43
43
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
const
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
/** The exact grant-comment body. Keep in lockstep with GRANT_RE. */
|
|
44
|
+
// The wire format — both marks, both regexes, and the encode/decode pairs — lives in
|
|
45
|
+
// codec/grants.js (#498, epic #496). Re-exported below under the names this module always had.
|
|
46
|
+
// Mark design (distinct leading emoji, so neither regex can match the other mark's body) is
|
|
47
|
+
// documented there; the grant-revoke-mark-collision test still pins it here.
|
|
48
|
+
const crypto = require('crypto');
|
|
49
|
+
const codec = require('./codec/grants');
|
|
50
|
+
const GRANT_MARK = codec.MIGRATION_GRANT_MARK;
|
|
51
|
+
const REVOKE_MARK = codec.MIGRATION_REVOKE_MARK;
|
|
52
|
+
const GRANT_RE = codec.MIGRATION_GRANT_RE;
|
|
53
|
+
const REVOKE_RE = codec.MIGRATION_REVOKE_RE;
|
|
54
|
+
|
|
55
|
+
/** The exact grant-comment body (codec `encodeMigrationGrant`, canonical tail). */
|
|
57
56
|
function grantCommentBody(branch, host, iso) {
|
|
58
|
-
return
|
|
59
|
-
+ ' — this exempts THIS BRANCH only, and expires when this issue closes.';
|
|
57
|
+
return codec.encodeMigrationGrant({ branch, host, at: iso });
|
|
60
58
|
}
|
|
61
59
|
|
|
62
|
-
/** The exact revoke-comment body
|
|
60
|
+
/** The exact revoke-comment body (codec `encodeMigrationRevoke`). `branch` is the branch named in
|
|
63
61
|
* the record for the audit trail — revocation itself is NOT branch-scoped (see evaluateIssue doc). */
|
|
64
62
|
function revokeCommentBody(branch, host, iso) {
|
|
65
|
-
return
|
|
66
|
-
+ ' — every grant on this issue up to this point is cancelled.';
|
|
63
|
+
return codec.encodeMigrationRevoke({ branch, host, at: iso });
|
|
67
64
|
}
|
|
68
65
|
|
|
69
66
|
/**
|
|
@@ -198,13 +195,15 @@ function evaluateIssue(record, branch, issueNum, labelName, opts) {
|
|
|
198
195
|
* read (the caller's job, not this function's — see tools/colab's shipMigrationGate).
|
|
199
196
|
*
|
|
200
197
|
* `ctx` (#401) — OPTIONAL, and absent means exactly the pre-#401 behaviour (human grants only,
|
|
201
|
-
* byte-identical output). Given, it is `{ policy, headSha, roundtrip }` and the ONE rule every
|
|
198
|
+
* byte-identical output). Given, it is `{ policy, headSha, contentId, roundtrip }` and the ONE rule every
|
|
202
199
|
* ship path shares (`--dry`, `--dry --json`, a real/auto-trunk ship, and batch — which reads
|
|
203
200
|
* through `--dry --json`) — so no path can accept a grant another refuses. Per issue:
|
|
204
201
|
* 1. a live human grant passes, unchanged — it wins where both roles exist;
|
|
205
202
|
* 2. otherwise a reviewer grant passes only when ALL of: P policy is `reviewer` · M a valid,
|
|
206
|
-
* passing, trusted, branch-bound reviewer marker + record · HEAD the
|
|
207
|
-
* `headSha
|
|
203
|
+
* passing, trusted, branch-bound reviewer marker + record · HEAD the grant binds the shipped
|
|
204
|
+
* head — the record's head equals `headSha`, or (#508) the record's migration content id
|
|
205
|
+
* equals `contentId`, the id at `headSha` · R `roundtrip()` says the live CI round-trip passed
|
|
206
|
+
* on the SHIPPED head (never the reviewed one).
|
|
208
207
|
* R is a THUNK, called at most once per set and only once some issue has cleared P, M and HEAD —
|
|
209
208
|
* so a no-migration, human-granted or already-failing ship pays for no CI read. A thunk returning
|
|
210
209
|
* anything but `{ ok: true }` (including `null`, a failed read) fails R closed.
|
|
@@ -242,23 +241,23 @@ function evaluateShipSet(issues, records, branch, labelName, ctx) {
|
|
|
242
241
|
reason: policy === 'reviewer' ? `${h.reason}, and no live reviewer grant either` : h.reason });
|
|
243
242
|
continue;
|
|
244
243
|
}
|
|
245
|
-
const r = evaluateReviewerGrant(rec, { branch, headSha: ctx.headSha, issueNum: n, labelName, policy });
|
|
244
|
+
const r = evaluateReviewerGrant(rec, { branch, headSha: ctx.headSha, contentId: ctx.contentId, issueNum: n, labelName, policy });
|
|
246
245
|
if (!r.ok) {
|
|
247
246
|
const failed = !r.checks.policy ? 'policy' : !r.checks.marker ? 'marker' : 'head';
|
|
248
247
|
missing.push({ issue: n, failed, reason: `reviewer grant [${SHIP_CONDITION_TAG[failed]}]: ${r.reason}` });
|
|
249
248
|
continue;
|
|
250
249
|
}
|
|
251
|
-
pending.push({ n, g: r.grant });
|
|
250
|
+
pending.push({ n, g: r.grant, via: r.via });
|
|
252
251
|
}
|
|
253
252
|
if (pending.length > 0) {
|
|
254
253
|
let rt = null;
|
|
255
254
|
try { rt = typeof ctx.roundtrip === 'function' ? ctx.roundtrip() : null; } catch (_) { rt = null; }
|
|
256
255
|
const ok = !!rt && rt.ok === true;
|
|
257
256
|
const why = rt && rt.reason ? rt.reason : 'the CI round-trip could not be read — an unread result is never a pass';
|
|
258
|
-
for (const { n, g } of pending) {
|
|
257
|
+
for (const { n, g, via } of pending) {
|
|
259
258
|
if (ok) {
|
|
260
|
-
granted.push({ issue: n, role: 'reviewer', reviewer: g.reviewer, head: g.head,
|
|
261
|
-
branch: g.branch, by: g.login, at: g.at });
|
|
259
|
+
granted.push({ issue: n, role: 'reviewer', reviewer: g.reviewer, head: g.head, via,
|
|
260
|
+
migrations: (g.record && g.record.migrations) || null, branch: g.branch, by: g.login, at: g.at });
|
|
262
261
|
} else {
|
|
263
262
|
missing.push({ issue: n, failed: 'roundtrip',
|
|
264
263
|
reason: `reviewer grant [${SHIP_CONDITION_TAG.roundtrip}]: #${n}: ${why}` });
|
|
@@ -345,6 +344,61 @@ function roundtripVerdict(jobs, opts) {
|
|
|
345
344
|
return { ok: true, legs, reason: '' };
|
|
346
345
|
}
|
|
347
346
|
|
|
347
|
+
/**
|
|
348
|
+
* #457 — the MINT-time half of R. `colab ship` re-reads the round-trip at the head (roundtripVerdict
|
|
349
|
+
* above, through shipMigrationCtx), so a false `ci-roundtrip: pass` never opened the gate — but the
|
|
350
|
+
* grant record itself could still assert a fact its cited run does not contain, and the issue then
|
|
351
|
+
* sat looking "granted" until a ship pass measured it. This applies the same verdict when the record
|
|
352
|
+
* is WRITTEN, so a record that says `pass` is refused unless CI agrees at `rec.head`.
|
|
353
|
+
*
|
|
354
|
+
* Pure: `runs` is every run at the head — `[{ databaseId, workflowName, jobs }]`, `jobs` being
|
|
355
|
+
* git.ghRunJobs rows — or null when the run list could not be read (a run with `jobs: null` is an
|
|
356
|
+
* unread run). Checks, in order:
|
|
357
|
+
* - the run list and every run's jobs were read (an unread result is never a pass);
|
|
358
|
+
* - roundtripVerdict over all their jobs is ok — the exact rule ship applies, workflows guard
|
|
359
|
+
* included, so a record mint can never accept what ship would refuse;
|
|
360
|
+
* - `ci-run`, when given, resolves to a run id (bare digits, or a `/runs/<id>` URL), names one of
|
|
361
|
+
* those runs, and that run itself carries a round-trip job — a record must not cite a run that
|
|
362
|
+
* does not contain the evidence it is cited for, even when a sibling run does.
|
|
363
|
+
* A record whose `ci-roundtrip` is not `pass` is not this function's to judge (it never mints).
|
|
364
|
+
* Returns { ok, reason, verdict }.
|
|
365
|
+
*/
|
|
366
|
+
function mintRoundtripCheck(rec, runs, opts) {
|
|
367
|
+
const o = opts || {};
|
|
368
|
+
const r = rec || {};
|
|
369
|
+
if (r['ci-roundtrip'] !== 'pass') return { ok: true, reason: '', verdict: null };
|
|
370
|
+
const sha = r.head ? String(r.head).slice(0, 7) : 'the head';
|
|
371
|
+
const no = (reason, verdict = null) => ({ ok: false, reason, verdict });
|
|
372
|
+
let jobs = null;
|
|
373
|
+
if (Array.isArray(runs) && runs.every((x) => x && Array.isArray(x.jobs))) {
|
|
374
|
+
jobs = [];
|
|
375
|
+
for (const x of runs) for (const j of x.jobs) jobs.push({ ...j, workflowName: x.workflowName || null });
|
|
376
|
+
}
|
|
377
|
+
const verdict = roundtripVerdict(jobs, { headSha: r.head, workflowsTouched: !!o.workflowsTouched });
|
|
378
|
+
if (!verdict.ok) {
|
|
379
|
+
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` : '';
|
|
380
|
+
return no(`the record says ci-roundtrip: pass, but ${verdict.reason}${hint}`, verdict);
|
|
381
|
+
}
|
|
382
|
+
if (r['ci-run'] !== undefined && r['ci-run'] !== null && String(r['ci-run']) !== '') {
|
|
383
|
+
const id = parseRunId(r['ci-run']);
|
|
384
|
+
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);
|
|
385
|
+
const cited = runs.find((x) => String(x.databaseId) === id);
|
|
386
|
+
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);
|
|
387
|
+
if (!cited.jobs.some((j) => j && typeof j.name === 'string' && j.name.startsWith(ROUNDTRIP_JOB_PREFIX))) {
|
|
388
|
+
return no(`ci-run ${id} has no "${ROUNDTRIP_JOB_PREFIX}" job — cite the run that carries the round-trip`, verdict);
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
return { ok: true, reason: '', verdict };
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
/** A run id from a `ci-run` value — bare digits, or the `/runs/<id>` segment of a run URL — or null. */
|
|
395
|
+
function parseRunId(v) {
|
|
396
|
+
const s = String(v).trim();
|
|
397
|
+
if (/^\d+$/.test(s)) return s;
|
|
398
|
+
const m = s.match(/\/runs\/(\d+)(?:[/?#]|$)/);
|
|
399
|
+
return m ? m[1] : null;
|
|
400
|
+
}
|
|
401
|
+
|
|
348
402
|
/** A step that reached a terminal conclusion other than skipped/cancelled — ci-cure.js stepRan. */
|
|
349
403
|
function stepRanOk(s) {
|
|
350
404
|
return !!s && s.status === 'completed' && s.conclusion !== 'skipped' && s.conclusion !== 'cancelled';
|
|
@@ -373,37 +427,18 @@ function stepRanOk(s) {
|
|
|
373
427
|
// `head` itself rather than rely on the recorded value.
|
|
374
428
|
// ============================================================================================
|
|
375
429
|
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
const
|
|
430
|
+
// The reviewer grant's wire format — mark, regex, fence, field table — lives in codec/grants.js
|
|
431
|
+
// (#498). GRANT_RE (the human marker, the one today's ship gate reads) never matches it: distinct
|
|
432
|
+
// leading emoji, on purpose.
|
|
433
|
+
const REVIEW_GRANT_MARK = codec.REVIEW_GRANT_MARK;
|
|
434
|
+
const REVIEWER_ROLE = codec.REVIEWER_ROLE;
|
|
380
435
|
const GRANT_ROLES = Object.freeze(['human', REVIEWER_ROLE]);
|
|
381
|
-
|
|
382
|
-
const
|
|
383
|
-
|
|
384
|
-
/** The fenced block's info string — the record is found by it, never by position. */
|
|
385
|
-
const REVIEW_RECORD_FENCE = 'migration-review';
|
|
386
|
-
const REVIEW_RECORD_VERSION = '1';
|
|
387
|
-
|
|
436
|
+
const REVIEW_GRANT_RE = codec.REVIEW_GRANT_RE;
|
|
437
|
+
const REVIEW_RECORD_FENCE = codec.REVIEW_RECORD_FENCE;
|
|
438
|
+
const REVIEW_RECORD_VERSION = codec.REVIEW_RECORD_VERSION;
|
|
388
439
|
const SHA40_RE = /^[0-9a-f]{40}$/;
|
|
389
|
-
|
|
390
|
-
const
|
|
391
|
-
|
|
392
|
-
/** Every key a v1 record may carry, and what each accepts. `required: false` keys may be absent.
|
|
393
|
-
* Order here is the order reviewGrantCommentBody() writes them in. */
|
|
394
|
-
const REVIEW_RECORD_FIELDS = Object.freeze([
|
|
395
|
-
{ key: 'v', required: true, values: [REVIEW_RECORD_VERSION] },
|
|
396
|
-
{ key: 'role', required: true, values: [REVIEWER_ROLE] },
|
|
397
|
-
{ key: 'reviewer', required: true, re: REVIEWER_ID_RE, hint: 'letters, digits, . _ @ -' },
|
|
398
|
-
{ key: 'head', required: true, re: SHA40_RE, hint: 'a full 40-hex commit sha' },
|
|
399
|
-
{ key: 'verdict', required: true, values: ['approve', 'reject'] },
|
|
400
|
-
{ key: 'checklist', required: true, values: ['pass', 'fail'] },
|
|
401
|
-
{ key: 'checklist-items', required: false, re: /^\d+\/\d+$/, hint: 'N/M, e.g. 7/7' },
|
|
402
|
-
{ key: 'escalation', required: true, re: CONDITION_ID_RE, hint: 'a condition id, lowercase-hyphenated' },
|
|
403
|
-
{ key: 'escalation-result', required: true, values: ['clear', 'escalated'] },
|
|
404
|
-
{ key: 'ci-roundtrip', required: true, values: ['pass', 'fail', 'pending'] },
|
|
405
|
-
{ key: 'ci-run', required: false, re: /^\S+$/, hint: 'a run id or URL, no spaces' },
|
|
406
|
-
]);
|
|
440
|
+
/** Every key a v1 record may carry, and what each accepts (codec/grants.js). */
|
|
441
|
+
const REVIEW_RECORD_FIELDS = codec.REVIEW_RECORD_FIELDS;
|
|
407
442
|
const REVIEW_RECORD_KEYS = new Set(REVIEW_RECORD_FIELDS.map((f) => f.key));
|
|
408
443
|
|
|
409
444
|
/**
|
|
@@ -448,6 +483,37 @@ function validateReviewRecord(rec, marker) {
|
|
|
448
483
|
return { valid, passing, problems };
|
|
449
484
|
}
|
|
450
485
|
|
|
486
|
+
/** #457 — the checklist the migration-review skill walks has this many items, so a record's
|
|
487
|
+
* `checklist-items` is `<passed>/10`. Kept in step with skills/migration-review/SKILL.md (a test
|
|
488
|
+
* reads the skill and pins it). */
|
|
489
|
+
const REVIEW_CHECKLIST_ITEMS = 10;
|
|
490
|
+
|
|
491
|
+
/**
|
|
492
|
+
* #457 — record checks that apply only when a grant is MINTED, never when one is read. They are
|
|
493
|
+
* kept out of validateReviewRecord on purpose: that function is also ship's read path, and a
|
|
494
|
+
* grant recorded under an older, shorter checklist must not change meaning after the fact (ship
|
|
495
|
+
* re-verifies everything that matters — HEAD and the live round-trip — on its own). A new record,
|
|
496
|
+
* though, must be counted against the checklist that exists today:
|
|
497
|
+
* - `checklist-items`, when given, has denominator REVIEW_CHECKLIST_ITEMS;
|
|
498
|
+
* - `checklist: pass` with `checklist-items` N/M needs N = M — a pass with an item failing is a
|
|
499
|
+
* contradiction, the same way a grant carrying a failing review is.
|
|
500
|
+
* Returns a list of problems ([] = fine).
|
|
501
|
+
*/
|
|
502
|
+
function mintRecordProblems(rec) {
|
|
503
|
+
const r = rec || {};
|
|
504
|
+
const problems = [];
|
|
505
|
+
const items = r['checklist-items'];
|
|
506
|
+
if (items === undefined || items === null || !/^\d+\/\d+$/.test(String(items))) return problems;
|
|
507
|
+
const [a, b] = String(items).split('/').map(Number);
|
|
508
|
+
if (b !== REVIEW_CHECKLIST_ITEMS) {
|
|
509
|
+
problems.push(`"checklist-items" is ${items} — the migration-review checklist has ${REVIEW_CHECKLIST_ITEMS} items, so the record is <passed>/${REVIEW_CHECKLIST_ITEMS}`);
|
|
510
|
+
}
|
|
511
|
+
if (r.checklist === 'pass' && a !== b) {
|
|
512
|
+
problems.push(`"checklist" is pass but "checklist-items" is ${items} — a pass means every item passed`);
|
|
513
|
+
}
|
|
514
|
+
return problems;
|
|
515
|
+
}
|
|
516
|
+
|
|
451
517
|
/** Why a VALID record is not passing, as one line — or '' when it passes. */
|
|
452
518
|
function reviewRecordFailure(rec) {
|
|
453
519
|
const why = [];
|
|
@@ -464,48 +530,25 @@ function reviewRecordFailure(rec) {
|
|
|
464
530
|
* caller (tools/colab) validates it with validateReviewRecord BEFORE calling this.
|
|
465
531
|
*/
|
|
466
532
|
function reviewGrantCommentBody(branch, host, iso, rec) {
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
for (const f of REVIEW_RECORD_FIELDS) {
|
|
472
|
-
const v = rec[f.key];
|
|
473
|
-
if (v === undefined || v === null || String(v) === '') continue;
|
|
474
|
-
lines.push(`${f.key}: ${v}`);
|
|
475
|
-
}
|
|
476
|
-
return `${head}\n\n\`\`\`${REVIEW_RECORD_FENCE}\n${lines.join('\n')}\n\`\`\``;
|
|
533
|
+
// Only the v1 fields are written — an unknown key on `rec` never reaches the comment.
|
|
534
|
+
const record = {};
|
|
535
|
+
for (const f of REVIEW_RECORD_FIELDS) if (Object.prototype.hasOwnProperty.call(rec, f.key)) record[f.key] = rec[f.key];
|
|
536
|
+
return codec.encodeReviewGrant({ role: rec.role, reviewer: rec.reviewer, branch, head: rec.head, host, at: iso, record });
|
|
477
537
|
}
|
|
478
538
|
|
|
479
539
|
/**
|
|
480
540
|
* Parse a reviewer-grant comment body → { marker, record, problems } or null when the first line
|
|
481
|
-
* is not a reviewer-grant marker at all. The
|
|
482
|
-
*
|
|
483
|
-
*
|
|
541
|
+
* is not a reviewer-grant marker at all. The codec (`decodeReviewGrant`) reads the syntax; this adds
|
|
542
|
+
* validateReviewRecord's findings. A marker with no record block, or a block with a malformed line,
|
|
543
|
+
* returns problems — never a record silently missing fields.
|
|
484
544
|
*/
|
|
485
545
|
function parseReviewGrant(body) {
|
|
486
|
-
const
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
const
|
|
491
|
-
|
|
492
|
-
const fm = text.match(fence);
|
|
493
|
-
if (!fm) {
|
|
494
|
-
problems.push(`no \`\`\`${REVIEW_RECORD_FENCE} block — a reviewer grant without its review record is not a grant`);
|
|
495
|
-
return { marker, record: null, problems };
|
|
496
|
-
}
|
|
497
|
-
const record = {};
|
|
498
|
-
for (const raw of fm[1].split('\n')) {
|
|
499
|
-
const line = raw.trim();
|
|
500
|
-
if (line === '') continue;
|
|
501
|
-
const kv = line.match(/^([a-z][a-z-]*):\s*(.*)$/);
|
|
502
|
-
if (!kv) { problems.push(`record line ${JSON.stringify(line)} is not "key: value"`); continue; }
|
|
503
|
-
if (Object.prototype.hasOwnProperty.call(record, kv[1])) { problems.push(`"${kv[1]}" appears twice`); continue; }
|
|
504
|
-
record[kv[1]] = kv[2].trim();
|
|
505
|
-
}
|
|
506
|
-
const v = validateReviewRecord(record, marker);
|
|
507
|
-
problems.push(...v.problems);
|
|
508
|
-
return { marker, record, problems };
|
|
546
|
+
const d = codec.decodeReviewGrant(body);
|
|
547
|
+
if (!d) return null;
|
|
548
|
+
const marker = { role: d.role, reviewer: d.reviewer, branch: d.branch, head: d.head, host: d.host, at: d.at };
|
|
549
|
+
if (!d.record) return { marker, record: null, problems: d.problems };
|
|
550
|
+
const v = validateReviewRecord(d.record, marker);
|
|
551
|
+
return { marker, record: d.record, problems: [...d.problems, ...v.problems] };
|
|
509
552
|
}
|
|
510
553
|
|
|
511
554
|
/**
|
|
@@ -546,22 +589,76 @@ function liveGrantRecords(comments) {
|
|
|
546
589
|
}
|
|
547
590
|
|
|
548
591
|
/**
|
|
549
|
-
*
|
|
550
|
-
*
|
|
551
|
-
*
|
|
552
|
-
*
|
|
592
|
+
* #508 — the CONTENT ID of a branch's migration files: what a reviewer actually reviewed. Pure:
|
|
593
|
+
* `entries` is `[{ path, blob }]`, one per migration path the branch changes against its base
|
|
594
|
+
* (tools/colab newMigrations — the same rule the gate fires on), `blob` the git blob id of that
|
|
595
|
+
* path at the head, or null when the head deletes it. The id is a sha256 over the SORTED
|
|
596
|
+
* `path<TAB>blob` lines, so it is independent of listing order and of everything outside those
|
|
597
|
+
* files: a merge-of-trunk sync, or any commit that leaves every migration byte-identical, keeps
|
|
598
|
+
* it; editing, adding, removing or renaming a migration changes it. Returns null for an empty or
|
|
599
|
+
* unreadable set — there is nothing to bind, and null never equals a recorded id.
|
|
600
|
+
*/
|
|
601
|
+
function migrationContentId(entries) {
|
|
602
|
+
if (!Array.isArray(entries) || entries.length === 0) return null;
|
|
603
|
+
const lines = [];
|
|
604
|
+
for (const e of entries) {
|
|
605
|
+
if (!e || typeof e.path !== 'string' || e.path === '') return null;
|
|
606
|
+
const blob = e.blob == null ? '-' : String(e.blob).toLowerCase();
|
|
607
|
+
if (blob !== '-' && !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(blob)) return null;
|
|
608
|
+
lines.push(`${e.path}\t${blob}\n`);
|
|
609
|
+
}
|
|
610
|
+
lines.sort();
|
|
611
|
+
return crypto.createHash('sha256').update(lines.join('')).digest('hex');
|
|
612
|
+
}
|
|
613
|
+
|
|
614
|
+
/**
|
|
615
|
+
* #508 — `git ls-tree -z <sha> -- <paths…>` output → migrationContentId's entries, one per path in
|
|
616
|
+
* `paths` (a path the tree lacks is a deletion: blob null). Pure, so the parse is testable without
|
|
617
|
+
* the CLI; tools/colab migrationContentAt runs the git half.
|
|
618
|
+
*/
|
|
619
|
+
function migrationEntriesFromLsTree(stdout, paths) {
|
|
620
|
+
const blobs = new Map();
|
|
621
|
+
for (const rec of String(stdout || '').split('\0')) {
|
|
622
|
+
const m = rec.match(/^\d+ blob ([0-9a-f]+)\t([\s\S]+)$/);
|
|
623
|
+
if (m) blobs.set(m[2], m[1]);
|
|
624
|
+
}
|
|
625
|
+
return (paths || []).map((p) => ({ path: p, blob: blobs.get(p) || null }));
|
|
626
|
+
}
|
|
627
|
+
|
|
628
|
+
const SHA256_RE = /^[0-9a-f]{64}$/;
|
|
629
|
+
|
|
630
|
+
/**
|
|
631
|
+
* The binding of a grant to what the branch now is. A human grant is branch-bound, not HEAD-bound
|
|
632
|
+
* (unchanged since #98) → unbound, ok. A reviewer grant needs `branchHeadSha` to be a full 40-hex
|
|
633
|
+
* sha (R reads CI there; "could not confirm the HEAD" is never read as a match, never a prefix
|
|
634
|
+
* match), and then binds one of two ways:
|
|
635
|
+
* - its record names `migrations` (#508) → CONTENT-bound: ok when the head IS the reviewed head,
|
|
636
|
+
* or when `contentId` — migrationContentId at the head — equals the recorded id. A sync that
|
|
637
|
+
* only merges trunk in keeps the grant; any change to a migration file voids it.
|
|
638
|
+
* - no `migrations` (a record minted before #508) → HEAD-bound, exactly as before: only the
|
|
639
|
+
* reviewed commit itself.
|
|
640
|
+
* Returns { bound, ok, via: 'head' | 'content' | null, reason }.
|
|
553
641
|
*/
|
|
554
|
-
function grantHeadBinding(grant, branchHeadSha) {
|
|
555
|
-
if (!grant || grant.role === 'human' || grant.role === undefined) return { bound: false, ok: true, reason: '' };
|
|
642
|
+
function grantHeadBinding(grant, branchHeadSha, contentId) {
|
|
643
|
+
if (!grant || grant.role === 'human' || grant.role === undefined) return { bound: false, ok: true, via: null, reason: '' };
|
|
556
644
|
const want = String(grant.head || '').toLowerCase();
|
|
557
645
|
const have = String(branchHeadSha || '').toLowerCase();
|
|
558
646
|
if (!SHA40_RE.test(have)) {
|
|
559
|
-
return { bound: true, ok: false, reason: `cannot confirm the branch HEAD (${have ? `"${have}" is not a full sha` : 'no sha given'}) — a reviewer grant is
|
|
647
|
+
return { bound: true, ok: false, via: null, reason: `cannot confirm the branch HEAD (${have ? `"${have}" is not a full sha` : 'no sha given'}) — a reviewer grant is judged at one commit` };
|
|
648
|
+
}
|
|
649
|
+
if (want === have) return { bound: true, ok: true, via: 'head', reason: '' };
|
|
650
|
+
const recorded = grant.record && grant.record.migrations ? String(grant.record.migrations).toLowerCase() : '';
|
|
651
|
+
if (!recorded) {
|
|
652
|
+
return { bound: true, ok: false, via: null, reason: `reviewer grant is bound to ${want.slice(0, 7)}, branch is at ${have.slice(0, 7)} — a new commit voids it (the record names no migration content id, so it binds the HEAD alone)` };
|
|
653
|
+
}
|
|
654
|
+
const now = String(contentId || '').toLowerCase();
|
|
655
|
+
if (!SHA256_RE.test(now)) {
|
|
656
|
+
return { bound: true, ok: false, via: null, reason: `reviewer grant covers migration content ${recorded.slice(0, 12)}, and the content at ${have.slice(0, 7)} could not be read — an unread id is never a match` };
|
|
560
657
|
}
|
|
561
|
-
if (
|
|
562
|
-
return { bound: true, ok: false, reason: `reviewer grant
|
|
658
|
+
if (now !== recorded) {
|
|
659
|
+
return { bound: true, ok: false, via: null, reason: `reviewer grant covers migration content ${recorded.slice(0, 12)} (reviewed at ${want.slice(0, 7)}), the branch at ${have.slice(0, 7)} carries ${now.slice(0, 12)} — a migration file changed since the review, which voids it` };
|
|
563
660
|
}
|
|
564
|
-
return { bound: true, ok: true, reason: '' };
|
|
661
|
+
return { bound: true, ok: true, via: 'content', reason: '' };
|
|
565
662
|
}
|
|
566
663
|
|
|
567
664
|
/** `migration-grant:` values, in project.yml (#398). Absent = human, today's behaviour. */
|
|
@@ -590,7 +687,8 @@ function parseGrantPolicy(doc) {
|
|
|
590
687
|
|
|
591
688
|
/**
|
|
592
689
|
* The reviewer-grant verdict for one issue — P, M and HEAD of the ship rule; evaluateShipSet()
|
|
593
|
-
* (#401) calls it and adds R. `ctx` = { branch, headSha, issueNum, labelName, policy } where
|
|
690
|
+
* (#401) calls it and adds R. `ctx` = { branch, headSha, contentId, issueNum, labelName, policy } where
|
|
691
|
+
* `contentId` (#508) is migrationContentId at `headSha` (grantHeadBinding), and
|
|
594
692
|
* `policy` is parseGrantPolicy(...).policy. Checks, cheapest/most-fundamental first, each with its
|
|
595
693
|
* own reason: read failed · not open · no label · policy not `reviewer` · no live reviewer grant ·
|
|
596
694
|
* branch mismatch · untrusted author · record invalid · record not passing · HEAD binding.
|
|
@@ -618,10 +716,10 @@ function evaluateReviewerGrant(record, ctx) {
|
|
|
618
716
|
if (!g.valid) return no(`#${issue}'s reviewer grant has an invalid review record: ${(g.problems || []).join('; ') || 'unreadable'}`, g);
|
|
619
717
|
if (!g.passing) return no(`#${issue}'s review record does not pass: ${reviewRecordFailure(g.record)}`, g);
|
|
620
718
|
checks.marker = true;
|
|
621
|
-
const hb = grantHeadBinding(g, c.headSha);
|
|
719
|
+
const hb = grantHeadBinding(g, c.headSha, c.contentId);
|
|
622
720
|
if (!hb.ok) return no(`#${issue}: ${hb.reason}`, g);
|
|
623
721
|
checks.head = true;
|
|
624
|
-
return { issue, ok: true, grant: g, reason: '', checks };
|
|
722
|
+
return { issue, ok: true, grant: g, via: hb.via, reason: '', checks };
|
|
625
723
|
}
|
|
626
724
|
|
|
627
725
|
module.exports = {
|
|
@@ -634,8 +732,12 @@ module.exports = {
|
|
|
634
732
|
REVIEW_RECORD_FENCE, REVIEW_RECORD_FIELDS,
|
|
635
733
|
validateReviewRecord, reviewRecordFailure, reviewGrantCommentBody, parseReviewGrant,
|
|
636
734
|
liveGrantRecords, grantHeadBinding, evaluateReviewerGrant,
|
|
735
|
+
// #508 — bind to the reviewed migration content, not the HEAD
|
|
736
|
+
migrationContentId, migrationEntriesFromLsTree,
|
|
637
737
|
// #398 — repo policy
|
|
638
738
|
GRANT_POLICIES, parseGrantPolicy,
|
|
639
739
|
// #401 — ship honours a reviewer grant
|
|
640
740
|
ROUNDTRIP_JOB_PREFIX, roundtripVerdict, SHIP_CONDITION_TAG,
|
|
741
|
+
// #457 — the mint-time checks
|
|
742
|
+
REVIEW_CHECKLIST_ITEMS, mintRecordProblems, mintRoundtripCheck, parseRunId,
|
|
641
743
|
};
|
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.
|