@futurelastic/colab-handbook 1.12.0-rc.63 → 1.12.0-rc.65
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/templates/ci-laravel.yml +50 -18
- package/tools/colab +47 -9
- package/tools/lib/codec/grants.d.ts +4 -0
- package/tools/lib/codec/grants.js +19 -3
- package/tools/lib/migration-grant.js +81 -21
package/package.json
CHANGED
package/templates/ci-laravel.yml
CHANGED
|
@@ -45,8 +45,8 @@
|
|
|
45
45
|
# The last two bullets fire ONLY when rows exist — on an empty table every one of
|
|
46
46
|
# them passes on both engines. Set ROUNDTRIP_SEEDER below, or they go unchecked.
|
|
47
47
|
#
|
|
48
|
-
# Not gated on RUN_TESTS: a bad migration is cheapest to fix on the branch that adds
|
|
49
|
-
# it, so this runs on every push, not only on main.
|
|
48
|
+
# Not gated on RUN_TESTS: a bad migration is cheapest to fix on the branch that adds or
|
|
49
|
+
# modifies it, so this runs on every push, not only on main.
|
|
50
50
|
|
|
51
51
|
name: CI
|
|
52
52
|
|
|
@@ -461,14 +461,19 @@ jobs:
|
|
|
461
461
|
# Migration round-trip — see the header for what each engine catches.
|
|
462
462
|
#
|
|
463
463
|
# 1. migrate from zero (schema snapshot A)
|
|
464
|
-
# 2. migrate:rollback the
|
|
465
|
-
#
|
|
464
|
+
# 2. migrate:rollback back to the OLDEST migration this change adds OR modifies —
|
|
465
|
+
# every down() it touched runs, plus the untouched ones after
|
|
466
|
+
# it (all migrations when the change touches none)
|
|
466
467
|
# 3. seed only if ROUNDTRIP_SEEDER is set, and only when the change
|
|
467
|
-
#
|
|
468
|
-
# 4. migrate again — the
|
|
468
|
+
# touches migrations: rows land at the PRE-change schema
|
|
469
|
+
# 4. migrate again — the touched migrations land on those rows (snapshot B)
|
|
469
470
|
# 5. compare B must equal A — a down() that does not exactly undo its
|
|
470
471
|
# up() leaves a schema that differs on the second pass
|
|
471
472
|
#
|
|
473
|
+
# MODIFIED counts as touched, not only added (#507): a branch that only repairs an
|
|
474
|
+
# existing down() must see that down() run, and a branch that adds one migration and
|
|
475
|
+
# repairs an older one must roll back past the older one, not just the newest step.
|
|
476
|
+
#
|
|
472
477
|
# Steps 2-4 are the shape of a real deploy: new migrations landing on tables that
|
|
473
478
|
# already hold rows written before they existed. That is why the seed sits BETWEEN
|
|
474
479
|
# the rollback and the second migrate — rows seeded after the new migrations would
|
|
@@ -533,7 +538,7 @@ jobs:
|
|
|
533
538
|
steps:
|
|
534
539
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
535
540
|
with:
|
|
536
|
-
# Full history: step
|
|
541
|
+
# Full history: the count step diffs the migrations this change touches against trunk.
|
|
537
542
|
fetch-depth: 0
|
|
538
543
|
persist-credentials: false
|
|
539
544
|
|
|
@@ -580,7 +585,7 @@ jobs:
|
|
|
580
585
|
- name: Discover packages
|
|
581
586
|
run: php artisan package:discover --ansi
|
|
582
587
|
|
|
583
|
-
- name:
|
|
588
|
+
- name: Find the migrations this change adds or modifies
|
|
584
589
|
env:
|
|
585
590
|
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
|
|
586
591
|
run: |
|
|
@@ -597,15 +602,24 @@ jobs:
|
|
|
597
602
|
base="$(git rev-parse -q --verify 'HEAD^' || true)"
|
|
598
603
|
fi
|
|
599
604
|
fi
|
|
600
|
-
|
|
605
|
+
# Added, Modified, and Renamed (a rename is a new name to the migrator) — not
|
|
606
|
+
# added only (#507): a branch that only repairs an existing down() got a green
|
|
607
|
+
# round-trip that never ran it.
|
|
608
|
+
touched=""
|
|
601
609
|
if [ -n "$base" ]; then
|
|
602
|
-
|
|
610
|
+
touched="$(git diff --name-status --diff-filter=AMR "$base" HEAD -- "$MIGRATIONS_PATH" | awk -F'\t' '$NF ~ /\.php$/ { print substr($1,1,1) "\t" $NF }')"
|
|
603
611
|
fi
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
612
|
+
# The migrator orders by file name, so the oldest touched one is the smallest
|
|
613
|
+
# base name; step 2 rolls back to it and everything after it.
|
|
614
|
+
from="$(printf '%s\n' "$touched" | awk -F'\t' 'NF { n=$2; sub(/.*\//, "", n); sub(/\.php$/, "", n); print n }' | LC_ALL=C sort | head -1)"
|
|
615
|
+
echo "ROUNDTRIP_FROM=$from" >> "$GITHUB_ENV"
|
|
616
|
+
if [ -n "$from" ]; then
|
|
617
|
+
added="$(printf '%s\n' "$touched" | grep -c '^A' || true)"
|
|
618
|
+
modified="$(printf '%s\n' "$touched" | grep -c '^[MR]' || true)"
|
|
619
|
+
echo "This change touches migrations (vs ${base_ref}): $added added, $modified modified. Step 2 rolls back to the oldest, $from, so every down() listed below runs:"
|
|
620
|
+
printf '%s\n' "$touched" | sed 's/^A\t/ added /; s/^[MR]\t/ modified /'
|
|
607
621
|
else
|
|
608
|
-
echo "This change adds no migrations (vs ${base_ref:-nothing}); step
|
|
622
|
+
echo "This change adds or modifies no migrations (vs ${base_ref:-nothing}); step 2 rolls back all of them."
|
|
609
623
|
fi
|
|
610
624
|
|
|
611
625
|
- name: Write the schema snapshot script
|
|
@@ -637,6 +651,18 @@ jobs:
|
|
|
637
651
|
ksort($out);
|
|
638
652
|
echo json_encode($out, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), "\n";
|
|
639
653
|
PHP
|
|
654
|
+
# How many migrations step 2 must roll back to reach ROUNDTRIP_FROM: the rows of
|
|
655
|
+
# the migrations table at or after it. Read from the table, not by counting
|
|
656
|
+
# files, so migrations a package registers from another path are counted too.
|
|
657
|
+
cat > "$RUNNER_TEMP/rollback-steps.php" <<'PHP'
|
|
658
|
+
<?php
|
|
659
|
+
require getcwd() . '/vendor/autoload.php';
|
|
660
|
+
$app = require getcwd() . '/bootstrap/app.php';
|
|
661
|
+
$app->make(Illuminate\Contracts\Console\Kernel::class)->bootstrap();
|
|
662
|
+
$m = config('database.migrations');
|
|
663
|
+
$table = is_array($m) ? ($m['table'] ?? 'migrations') : ($m ?: 'migrations');
|
|
664
|
+
echo Illuminate\Support\Facades\DB::table($table)->where('migration', '>=', getenv('ROUNDTRIP_FROM'))->count(), "\n";
|
|
665
|
+
PHP
|
|
640
666
|
|
|
641
667
|
- name: 1. migrate from zero
|
|
642
668
|
run: |
|
|
@@ -645,16 +671,22 @@ jobs:
|
|
|
645
671
|
|
|
646
672
|
- name: 2. roll back
|
|
647
673
|
run: |
|
|
648
|
-
|
|
649
|
-
|
|
674
|
+
set -euo pipefail
|
|
675
|
+
steps=0
|
|
676
|
+
if [ -n "$ROUNDTRIP_FROM" ]; then
|
|
677
|
+
steps="$(php "$RUNNER_TEMP/rollback-steps.php")"
|
|
678
|
+
fi
|
|
679
|
+
if [ "$steps" -gt 0 ]; then
|
|
680
|
+
echo "Rolling back $steps migration(s), down to $ROUNDTRIP_FROM."
|
|
681
|
+
php artisan migrate:rollback --step="$steps" --force
|
|
650
682
|
else
|
|
651
683
|
# Everything ran in one batch at step 1, so this rolls all of it back.
|
|
652
684
|
php artisan migrate:rollback --force
|
|
653
685
|
fi
|
|
654
686
|
|
|
655
687
|
- name: 3. seed rows at the pre-change schema
|
|
656
|
-
# No
|
|
657
|
-
if: env.ROUNDTRIP_SEEDER != '' && env.
|
|
688
|
+
# No touched migrations = nothing lands on the rows, and the schema is empty anyway.
|
|
689
|
+
if: env.ROUNDTRIP_SEEDER != '' && env.ROUNDTRIP_FROM != ''
|
|
658
690
|
run: php artisan db:seed --class="$ROUNDTRIP_SEEDER" --force
|
|
659
691
|
|
|
660
692
|
- name: 4. migrate again
|
package/tools/colab
CHANGED
|
@@ -3715,7 +3715,11 @@ ROLE-TAGGED GRANTS (#397). --role defaults to \`human\` — the grant above, unc
|
|
|
3715
3715
|
--role ${migrationGrant.REVIEWER_ROLE} the comment is a \`${migrationGrant.REVIEW_GRANT_MARK}\` instead:
|
|
3716
3716
|
it names the declared reviewer and carries a REVIEW RECORD (a \`\`\`${migrationGrant.REVIEW_RECORD_FENCE}
|
|
3717
3717
|
block — verdict, checklist result, the escalation condition checked, the CI round-trip result, and
|
|
3718
|
-
the reviewed HEAD sha
|
|
3718
|
+
the reviewed HEAD sha, and — #508 — \`migrations\`, a content id over the branch's migration files at
|
|
3719
|
+
that HEAD, computed here, never a flag). A reviewer grant is bound to that CONTENT: a commit that
|
|
3720
|
+
leaves every migration file byte-identical (the trunk sync ship requires) keeps it; editing, adding,
|
|
3721
|
+
removing or renaming a migration voids it. A branch with no migration file gets no id and is bound to
|
|
3722
|
+
its HEAD alone, as is every record minted before #508.
|
|
3719
3723
|
It is minted only when ALL of these hold, checked before any network call:
|
|
3720
3724
|
- the record is well-formed AND passing (approve · checklist pass · escalation clear · CI pass) —
|
|
3721
3725
|
a grant carrying a failing review is a contradiction, so it is refused, not recorded;
|
|
@@ -3730,8 +3734,9 @@ Then, read from CI after the tracker read and before anything is written (#457):
|
|
|
3730
3734
|
COLAB_HUMAN=1 is still required for every role. The reviewer identity is DECLARED, not attested.
|
|
3731
3735
|
\`colab ship\` honours a reviewer grant only when ALL of (#401): P the target's project.yml says
|
|
3732
3736
|
\`migration-grant: reviewer\` · M this record is live, trusted and passing · HEAD its head is the
|
|
3733
|
-
branch's exact remote head
|
|
3734
|
-
|
|
3737
|
+
branch's exact remote head, or its \`migrations\` id equals the id at that head · R the live
|
|
3738
|
+
"${migrationGrant.ROUNDTRIP_JOB_PREFIX}" CI job passed on the SHIPPED head (re-read by ship, never
|
|
3739
|
+
taken from the record). Any condition failing → a human runs Phase B.
|
|
3735
3740
|
|
|
3736
3741
|
Options:
|
|
3737
3742
|
--branch <branch> required for --branch grants; a grant is never inferred from HEAD
|
|
@@ -3850,11 +3855,22 @@ function migrationGrantReviewRecord(repoAbs, opts) {
|
|
|
3850
3855
|
throw new UserError(`--head ${String(opts.head).slice(0, 12)} is not origin's tip of "${opts.branch}" (${tip.slice(0, 12)}) — the review covers a commit the grant would not bind; re-review the tip`);
|
|
3851
3856
|
}
|
|
3852
3857
|
|
|
3858
|
+
// #508: bind what was reviewed — the branch's migration files at the tip, by content. Same path
|
|
3859
|
+
// rule the ship gate fires on (newMigrations), against origin's trunk. A branch with no migration
|
|
3860
|
+
// to review gets no id and stays HEAD-bound.
|
|
3861
|
+
const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
|
|
3862
|
+
const remote = git.remoteInfo(repoAbs).name || 'origin';
|
|
3863
|
+
let base = trunk ? `${remote}/${trunk}` : null;
|
|
3864
|
+
if (base && !git.git(['rev-parse', '--verify', '--quiet', `${base}^{commit}`], repoAbs).ok) base = trunk;
|
|
3865
|
+
const migrations = base ? newMigrations(repoAbs, base, tip) : [];
|
|
3866
|
+
const contentId = migrationContentAt(repoAbs, migrations, tip);
|
|
3867
|
+
|
|
3853
3868
|
const rec = {
|
|
3854
3869
|
v: '1', role, reviewer: opts.reviewer, head: tip,
|
|
3855
3870
|
verdict: opts.verdict, checklist: opts.checklist, 'checklist-items': opts.checklistItems,
|
|
3856
3871
|
escalation: opts.escalation, 'escalation-result': opts.escalationResult,
|
|
3857
3872
|
'ci-roundtrip': opts.ciRoundtrip, 'ci-run': opts.ciRun,
|
|
3873
|
+
migrations: contentId || undefined,
|
|
3858
3874
|
};
|
|
3859
3875
|
for (const k of Object.keys(rec)) if (rec[k] === undefined) delete rec[k];
|
|
3860
3876
|
const v = migrationGrant.validateReviewRecord(rec);
|
|
@@ -3937,7 +3953,11 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
|
|
|
3937
3953
|
|
|
3938
3954
|
if (opts.reviewRecord) {
|
|
3939
3955
|
print(`Recorded a ${migrationGrant.REVIEWER_ROLE} grant on #${num} in ${shortRepo(repoAbs)} — reviewer "${opts.reviewRecord.reviewer}", branch "${opts.branch}" @ ${opts.reviewRecord.head.slice(0, 12)}.`);
|
|
3940
|
-
|
|
3956
|
+
if (opts.reviewRecord.migrations) {
|
|
3957
|
+
print(` Bound to the reviewed migration content ${opts.reviewRecord.migrations.slice(0, 12)}: a commit that leaves every migration file byte-identical (a trunk sync) keeps it, any change to one voids it. It expires the moment the issue closes.`);
|
|
3958
|
+
} else {
|
|
3959
|
+
print(' Bound to that HEAD: any new commit voids it. It expires the moment the issue closes.');
|
|
3960
|
+
}
|
|
3941
3961
|
print(` colab ship honours it only while the "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" CI job has passed on that HEAD and the policy still says reviewer.`);
|
|
3942
3962
|
print(` Revoke any time: colab migration-grant ${num} --revoke`);
|
|
3943
3963
|
return 0;
|
|
@@ -9616,6 +9636,19 @@ function newMigrations(mainRoot, trunk, branch) {
|
|
|
9616
9636
|
return r.stdout.split('\n').filter(Boolean).filter((f) => migrationPaths.isMigrationPath(f, declared));
|
|
9617
9637
|
}
|
|
9618
9638
|
|
|
9639
|
+
/**
|
|
9640
|
+
* #508 — the content id (migration-grant.js migrationContentId) of `paths` — the branch's migration
|
|
9641
|
+
* files, newMigrations' list — as they stand at `sha`: one `git ls-tree` for their blob ids, a path
|
|
9642
|
+
* the commit no longer has counting as deleted. null when the tree cannot be read or there is
|
|
9643
|
+
* nothing to bind; null never matches a recorded id, so an unreadable tree fails the binding closed.
|
|
9644
|
+
*/
|
|
9645
|
+
function migrationContentAt(repoAbs, paths, sha) {
|
|
9646
|
+
if (!sha || !Array.isArray(paths) || paths.length === 0) return null;
|
|
9647
|
+
const r = git.git(['ls-tree', '-z', sha, '--', ...paths], repoAbs);
|
|
9648
|
+
if (!r.ok) return null;
|
|
9649
|
+
return migrationGrant.migrationContentId(migrationGrant.migrationEntriesFromLsTree(r.stdout, paths));
|
|
9650
|
+
}
|
|
9651
|
+
|
|
9619
9652
|
/**
|
|
9620
9653
|
* The `no new migrations` row, whole (#98, #401) — the ONE function every ship path calls:
|
|
9621
9654
|
* `ship --dry`, a real or auto-trunk `ship` (both cmdShip), and `ship --dry --json` (cmdShipDryJson,
|
|
@@ -9633,6 +9666,8 @@ function newMigrations(mainRoot, trunk, branch) {
|
|
|
9633
9666
|
* evaluateShipSet ctx: the policy (P) from project.yml AT THE TARGET TIP — what the branch merges
|
|
9634
9667
|
* into, not a working file the branch could have edited; the HEAD — the branch's remote head (what
|
|
9635
9668
|
* CI ran), which must equal the local ref (what the squash takes), or no reviewer grant can bind;
|
|
9669
|
+
* the migration content id at that HEAD (#508), which a content-bound grant matches instead of
|
|
9670
|
+
* the reviewed HEAD — so the merge-of-trunk sync ship itself demands does not void the grant;
|
|
9636
9671
|
* and R lazily — every job of every run at that HEAD, read only once some issue clears P+M+HEAD.
|
|
9637
9672
|
*/
|
|
9638
9673
|
function shipMigrationGate(repoAbs, gh, target, branch, issues) {
|
|
@@ -9646,7 +9681,7 @@ function shipMigrationGate(repoAbs, gh, target, branch, issues) {
|
|
|
9646
9681
|
} else {
|
|
9647
9682
|
const records = {};
|
|
9648
9683
|
for (const n of issues) records[n] = git.ghIssueView(repoAbs, n, ['state', 'labels', 'comments']);
|
|
9649
|
-
ctx = shipMigrationCtx(repoAbs, gh, target, branch);
|
|
9684
|
+
ctx = shipMigrationCtx(repoAbs, gh, target, branch, migrations);
|
|
9650
9685
|
grants = migrationGrant.evaluateShipSet(issues, records, branch, labels.MIGRATION_GRANT_LABEL, ctx);
|
|
9651
9686
|
}
|
|
9652
9687
|
return { migrations, ok: grants.ok, ...migDetail(migrations, grants, target, branch, ctx) };
|
|
@@ -9654,7 +9689,7 @@ function shipMigrationGate(repoAbs, gh, target, branch, issues) {
|
|
|
9654
9689
|
|
|
9655
9690
|
/** P, HEAD and the R thunk for shipMigrationGate. The thunk memoises its one verdict on the ctx
|
|
9656
9691
|
* (`roundtripResult`) so the payload can report what R saw without a second read. */
|
|
9657
|
-
function shipMigrationCtx(repoAbs, gh, target, branch) {
|
|
9692
|
+
function shipMigrationCtx(repoAbs, gh, target, branch, migrations) {
|
|
9658
9693
|
const policy = migrationGrant.parseGrantPolicy(projectDocAt(repoAbs, target)).policy;
|
|
9659
9694
|
const remote = git.remoteInfo(repoAbs).name || 'origin';
|
|
9660
9695
|
const ls = git.git(['ls-remote', remote, `refs/heads/${branch}`], repoAbs);
|
|
@@ -9666,7 +9701,9 @@ function shipMigrationCtx(repoAbs, gh, target, branch) {
|
|
|
9666
9701
|
else if (localSha && localSha !== remoteSha) headNote = `local ${branch} is ${localSha.slice(0, 7)}, ${remote} is ${remoteSha.slice(0, 7)} — push or pull until they agree`;
|
|
9667
9702
|
else headSha = remoteSha;
|
|
9668
9703
|
const trust = trustAt(repoAbs, target);
|
|
9669
|
-
|
|
9704
|
+
// #508: what the branch's migration files ARE at the shipped head, for a content-bound grant.
|
|
9705
|
+
const contentId = headSha ? migrationContentAt(repoAbs, migrations, headSha) : null;
|
|
9706
|
+
const ctx = { policy, headSha, contentId, headNote, roundtripResult: null, trust,
|
|
9670
9707
|
labelActors: (n) => git.ghIssueLabelActors(repoAbs, n, labels.MIGRATION_GRANT_LABEL) };
|
|
9671
9708
|
ctx.roundtrip = () => {
|
|
9672
9709
|
const d = git.git(['diff', '--name-only', `${target}...${branch}`], repoAbs);
|
|
@@ -9700,16 +9737,17 @@ function migDetail(migrations, grants, target, branch, ctx) {
|
|
|
9700
9737
|
branch, files: [...migrations],
|
|
9701
9738
|
policy: ctx ? ctx.policy : null,
|
|
9702
9739
|
headSha: ctx ? ctx.headSha : null,
|
|
9740
|
+
contentId: ctx ? ctx.contentId || null : null,
|
|
9703
9741
|
// #407: the human list as read from the TARGET — null when undeclared (association class).
|
|
9704
9742
|
trustHumans: ctx && ctx.trust && ctx.trust.declared ? [...ctx.trust.humans] : null,
|
|
9705
9743
|
roundtrip: ctx && ctx.roundtripResult ? { ok: ctx.roundtripResult.ok, reason: ctx.roundtripResult.reason } : null,
|
|
9706
9744
|
granted: grants.granted.map((g) => ({ issue: g.issue, role: g.role || 'human', by: g.by, at: g.at,
|
|
9707
|
-
...(g.role === 'reviewer' ? { reviewer: g.reviewer, head: g.head } : {}) })),
|
|
9745
|
+
...(g.role === 'reviewer' ? { reviewer: g.reviewer, head: g.head, via: g.via || 'head', migrations: g.migrations || null } : {}) })),
|
|
9708
9746
|
missing: grants.missing.map((m) => ({ issue: m.issue, failed: m.failed || null,
|
|
9709
9747
|
reason: m.failed === 'head' && ctx && ctx.headNote ? `${m.reason} (${ctx.headNote})` : m.reason })),
|
|
9710
9748
|
};
|
|
9711
9749
|
if (grants.ok) {
|
|
9712
|
-
const by = grants.granted.map((g) => (g.role === 'reviewer' ? `#${g.issue} (reviewer ${g.reviewer} @ ${String(g.head).slice(0, 7)}, CI round-trip passed)` : '#' + g.issue)).join(' ');
|
|
9750
|
+
const by = grants.granted.map((g) => (g.role === 'reviewer' ? `#${g.issue} (reviewer ${g.reviewer} @ ${String(g.head).slice(0, 7)}${g.via === 'content' ? `, migration content ${String(g.migrations).slice(0, 12)} unchanged since` : ''}, CI round-trip passed)` : '#' + g.issue)).join(' ');
|
|
9713
9751
|
const roles = [...new Set(grants.granted.map((g) => g.role || 'human'))].join('+');
|
|
9714
9752
|
return { text: `${migrations.length} present, exempted by a ${roles} grant on ${by} for branch "${branch}" — ${files}`, payload };
|
|
9715
9753
|
}
|
|
@@ -24,6 +24,10 @@ export const REVIEW_RECORD_FENCE: 'migration-review';
|
|
|
24
24
|
export const REVIEW_RECORD_VERSION: '1';
|
|
25
25
|
export interface ReviewRecordField { key: string; required: boolean; values?: string[]; re?: RegExp; hint?: string; }
|
|
26
26
|
export const REVIEW_RECORD_FIELDS: ReadonlyArray<ReviewRecordField>;
|
|
27
|
+
/** Canonical tail of a HEAD-bound reviewer grant (a record with no `migrations` content id). */
|
|
28
|
+
export const REVIEW_GRANT_TAIL: string;
|
|
29
|
+
/** Canonical tail of a content-bound reviewer grant (#508 — the record names `migrations`). */
|
|
30
|
+
export const REVIEW_GRANT_CONTENT_TAIL: string;
|
|
27
31
|
|
|
28
32
|
export interface DecodedReviewGrant {
|
|
29
33
|
role: string; reviewer: string; branch: string;
|
|
@@ -60,6 +60,14 @@ const REVIEW_GRANT_MARK = '🔎 Migration review grant';
|
|
|
60
60
|
const REVIEWER_ROLE = 'migration-reviewer';
|
|
61
61
|
const REVIEW_GRANT_RE = /^🔎 Migration review grant — role `([^`]*)` · reviewer `([^`]*)` · branch `([^`]*)` · head `([^`]*)` · host `([^`]*)` · (\S+)/;
|
|
62
62
|
const REVIEW_GRANT_TAIL = ' — bound to this HEAD: any new commit voids it; expires when this issue closes.';
|
|
63
|
+
/** #508 — the canonical tail of a grant whose record carries `migrations` (a content id): it binds
|
|
64
|
+
* what was reviewed, so a commit that leaves the migration files byte-identical keeps it. */
|
|
65
|
+
const REVIEW_GRANT_CONTENT_TAIL = ' — bound to the reviewed migration content: a change to any migration file voids it; expires when this issue closes.';
|
|
66
|
+
/** The tail a record of this shape gets by default — content-bound when it names a content id. */
|
|
67
|
+
function reviewGrantTail(record) {
|
|
68
|
+
return record && record.migrations !== undefined && record.migrations !== null && String(record.migrations) !== ''
|
|
69
|
+
? REVIEW_GRANT_CONTENT_TAIL : REVIEW_GRANT_TAIL;
|
|
70
|
+
}
|
|
63
71
|
/** The fenced block's info string — the record is found by it, never by position. */
|
|
64
72
|
const REVIEW_RECORD_FENCE = 'migration-review';
|
|
65
73
|
const REVIEW_RECORD_VERSION = '1';
|
|
@@ -67,6 +75,7 @@ const REVIEW_RECORD_VERSION = '1';
|
|
|
67
75
|
const SHA40_RE = /^[0-9a-f]{40}$/;
|
|
68
76
|
const REVIEWER_ID_RE = /^[A-Za-z0-9._@-]+$/;
|
|
69
77
|
const CONDITION_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
|
|
78
|
+
const SHA256_RE = /^[0-9a-f]{64}$/;
|
|
70
79
|
|
|
71
80
|
/** Every key a v1 record may carry, and what each accepts. `required: false` keys may be absent.
|
|
72
81
|
* Order here is the order `encodeReviewGrant` writes them in — part of the wire format. */
|
|
@@ -82,6 +91,9 @@ const REVIEW_RECORD_FIELDS = Object.freeze([
|
|
|
82
91
|
{ key: 'escalation-result', required: true, values: ['clear', 'escalated'] },
|
|
83
92
|
{ key: 'ci-roundtrip', required: true, values: ['pass', 'fail', 'pending'] },
|
|
84
93
|
{ key: 'ci-run', required: false, re: /^\S+$/, hint: 'a run id or URL, no spaces' },
|
|
94
|
+
// #508 — the content id of the migration files the review covered (migration-grant.js
|
|
95
|
+
// migrationContentId). Optional: a record without it is bound to `head` alone, as before.
|
|
96
|
+
{ key: 'migrations', required: false, re: SHA256_RE, hint: 'a 64-hex sha256 content id of the reviewed migration files' },
|
|
85
97
|
]);
|
|
86
98
|
|
|
87
99
|
/**
|
|
@@ -92,7 +104,7 @@ const REVIEW_RECORD_FIELDS = Object.freeze([
|
|
|
92
104
|
*/
|
|
93
105
|
function encodeReviewGrant({ role, reviewer, branch, head, host, at, tail, record } = {}) {
|
|
94
106
|
const marker = withTail(`${REVIEW_GRANT_MARK} — role \`${role}\` · reviewer \`${reviewer}\` · branch \`${branch}\``
|
|
95
|
-
+ ` · head \`${head}\` · host \`${host}\` · ${at}`, tail,
|
|
107
|
+
+ ` · head \`${head}\` · host \`${host}\` · ${at}`, tail, reviewGrantTail(record));
|
|
96
108
|
return `${marker}\n\n${fencedRecord(REVIEW_RECORD_FENCE, REVIEW_RECORD_FIELDS, record)}`;
|
|
97
109
|
}
|
|
98
110
|
|
|
@@ -111,8 +123,11 @@ function decodeReviewGrant(body) {
|
|
|
111
123
|
const line = nl === -1 ? text : text.slice(0, nl);
|
|
112
124
|
const t = line.slice(m[0].length);
|
|
113
125
|
const out = { role: m[1], reviewer: m[2], branch: m[3], head: m[4], host: m[5], at: m[6],
|
|
114
|
-
tail: t
|
|
115
|
-
|
|
126
|
+
tail: t, record: null, problems: [] };
|
|
127
|
+
readFencedRecord(text, REVIEW_RECORD_FENCE, out);
|
|
128
|
+
// The canonical tail depends on the record's shape (#508), so it is judged once the record is read.
|
|
129
|
+
if (t === reviewGrantTail(out.record)) out.tail = null;
|
|
130
|
+
return out;
|
|
116
131
|
}
|
|
117
132
|
|
|
118
133
|
/** Find the FIRST fenced block whose info string is exactly `fence` and read its `key: value`
|
|
@@ -244,6 +259,7 @@ module.exports = {
|
|
|
244
259
|
MIGRATION_GRANT_MARK, MIGRATION_REVOKE_MARK, MIGRATION_GRANT_RE, MIGRATION_REVOKE_RE,
|
|
245
260
|
encodeMigrationGrant, decodeMigrationGrant, encodeMigrationRevoke, decodeMigrationRevoke,
|
|
246
261
|
REVIEW_GRANT_MARK, REVIEW_GRANT_RE, REVIEWER_ROLE, REVIEW_RECORD_FENCE, REVIEW_RECORD_VERSION, REVIEW_RECORD_FIELDS,
|
|
262
|
+
REVIEW_GRANT_TAIL, REVIEW_GRANT_CONTENT_TAIL,
|
|
247
263
|
encodeReviewGrant, decodeReviewGrant,
|
|
248
264
|
CI_GRANT_MARK, CI_REVOKE_MARK, CI_GRANT_RE, CI_REVOKE_RE,
|
|
249
265
|
encodeCiGrant, decodeCiGrant, encodeCiRevoke, decodeCiRevoke,
|
|
@@ -45,6 +45,7 @@
|
|
|
45
45
|
// codec/grants.js (#498, epic #496). Re-exported below under the names this module always had.
|
|
46
46
|
// Mark design (distinct leading emoji, so neither regex can match the other mark's body) is
|
|
47
47
|
// documented there; the grant-revoke-mark-collision test still pins it here.
|
|
48
|
+
const crypto = require('crypto');
|
|
48
49
|
const codec = require('./codec/grants');
|
|
49
50
|
const GRANT_MARK = codec.MIGRATION_GRANT_MARK;
|
|
50
51
|
const REVOKE_MARK = codec.MIGRATION_REVOKE_MARK;
|
|
@@ -194,13 +195,15 @@ function evaluateIssue(record, branch, issueNum, labelName, opts) {
|
|
|
194
195
|
* read (the caller's job, not this function's — see tools/colab's shipMigrationGate).
|
|
195
196
|
*
|
|
196
197
|
* `ctx` (#401) — OPTIONAL, and absent means exactly the pre-#401 behaviour (human grants only,
|
|
197
|
-
* 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
|
|
198
199
|
* ship path shares (`--dry`, `--dry --json`, a real/auto-trunk ship, and batch — which reads
|
|
199
200
|
* through `--dry --json`) — so no path can accept a grant another refuses. Per issue:
|
|
200
201
|
* 1. a live human grant passes, unchanged — it wins where both roles exist;
|
|
201
202
|
* 2. otherwise a reviewer grant passes only when ALL of: P policy is `reviewer` · M a valid,
|
|
202
|
-
* passing, trusted, branch-bound reviewer marker + record · HEAD the
|
|
203
|
-
* `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).
|
|
204
207
|
* R is a THUNK, called at most once per set and only once some issue has cleared P, M and HEAD —
|
|
205
208
|
* so a no-migration, human-granted or already-failing ship pays for no CI read. A thunk returning
|
|
206
209
|
* anything but `{ ok: true }` (including `null`, a failed read) fails R closed.
|
|
@@ -238,23 +241,23 @@ function evaluateShipSet(issues, records, branch, labelName, ctx) {
|
|
|
238
241
|
reason: policy === 'reviewer' ? `${h.reason}, and no live reviewer grant either` : h.reason });
|
|
239
242
|
continue;
|
|
240
243
|
}
|
|
241
|
-
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 });
|
|
242
245
|
if (!r.ok) {
|
|
243
246
|
const failed = !r.checks.policy ? 'policy' : !r.checks.marker ? 'marker' : 'head';
|
|
244
247
|
missing.push({ issue: n, failed, reason: `reviewer grant [${SHIP_CONDITION_TAG[failed]}]: ${r.reason}` });
|
|
245
248
|
continue;
|
|
246
249
|
}
|
|
247
|
-
pending.push({ n, g: r.grant });
|
|
250
|
+
pending.push({ n, g: r.grant, via: r.via });
|
|
248
251
|
}
|
|
249
252
|
if (pending.length > 0) {
|
|
250
253
|
let rt = null;
|
|
251
254
|
try { rt = typeof ctx.roundtrip === 'function' ? ctx.roundtrip() : null; } catch (_) { rt = null; }
|
|
252
255
|
const ok = !!rt && rt.ok === true;
|
|
253
256
|
const why = rt && rt.reason ? rt.reason : 'the CI round-trip could not be read — an unread result is never a pass';
|
|
254
|
-
for (const { n, g } of pending) {
|
|
257
|
+
for (const { n, g, via } of pending) {
|
|
255
258
|
if (ok) {
|
|
256
|
-
granted.push({ issue: n, role: 'reviewer', reviewer: g.reviewer, head: g.head,
|
|
257
|
-
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 });
|
|
258
261
|
} else {
|
|
259
262
|
missing.push({ issue: n, failed: 'roundtrip',
|
|
260
263
|
reason: `reviewer grant [${SHIP_CONDITION_TAG.roundtrip}]: #${n}: ${why}` });
|
|
@@ -586,22 +589,76 @@ function liveGrantRecords(comments) {
|
|
|
586
589
|
}
|
|
587
590
|
|
|
588
591
|
/**
|
|
589
|
-
*
|
|
590
|
-
*
|
|
591
|
-
*
|
|
592
|
-
*
|
|
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.
|
|
593
600
|
*/
|
|
594
|
-
function
|
|
595
|
-
if (!
|
|
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 }.
|
|
641
|
+
*/
|
|
642
|
+
function grantHeadBinding(grant, branchHeadSha, contentId) {
|
|
643
|
+
if (!grant || grant.role === 'human' || grant.role === undefined) return { bound: false, ok: true, via: null, reason: '' };
|
|
596
644
|
const want = String(grant.head || '').toLowerCase();
|
|
597
645
|
const have = String(branchHeadSha || '').toLowerCase();
|
|
598
646
|
if (!SHA40_RE.test(have)) {
|
|
599
|
-
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` };
|
|
600
657
|
}
|
|
601
|
-
if (
|
|
602
|
-
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` };
|
|
603
660
|
}
|
|
604
|
-
return { bound: true, ok: true, reason: '' };
|
|
661
|
+
return { bound: true, ok: true, via: 'content', reason: '' };
|
|
605
662
|
}
|
|
606
663
|
|
|
607
664
|
/** `migration-grant:` values, in project.yml (#398). Absent = human, today's behaviour. */
|
|
@@ -630,7 +687,8 @@ function parseGrantPolicy(doc) {
|
|
|
630
687
|
|
|
631
688
|
/**
|
|
632
689
|
* The reviewer-grant verdict for one issue — P, M and HEAD of the ship rule; evaluateShipSet()
|
|
633
|
-
* (#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
|
|
634
692
|
* `policy` is parseGrantPolicy(...).policy. Checks, cheapest/most-fundamental first, each with its
|
|
635
693
|
* own reason: read failed · not open · no label · policy not `reviewer` · no live reviewer grant ·
|
|
636
694
|
* branch mismatch · untrusted author · record invalid · record not passing · HEAD binding.
|
|
@@ -658,10 +716,10 @@ function evaluateReviewerGrant(record, ctx) {
|
|
|
658
716
|
if (!g.valid) return no(`#${issue}'s reviewer grant has an invalid review record: ${(g.problems || []).join('; ') || 'unreadable'}`, g);
|
|
659
717
|
if (!g.passing) return no(`#${issue}'s review record does not pass: ${reviewRecordFailure(g.record)}`, g);
|
|
660
718
|
checks.marker = true;
|
|
661
|
-
const hb = grantHeadBinding(g, c.headSha);
|
|
719
|
+
const hb = grantHeadBinding(g, c.headSha, c.contentId);
|
|
662
720
|
if (!hb.ok) return no(`#${issue}: ${hb.reason}`, g);
|
|
663
721
|
checks.head = true;
|
|
664
|
-
return { issue, ok: true, grant: g, reason: '', checks };
|
|
722
|
+
return { issue, ok: true, grant: g, via: hb.via, reason: '', checks };
|
|
665
723
|
}
|
|
666
724
|
|
|
667
725
|
module.exports = {
|
|
@@ -674,6 +732,8 @@ module.exports = {
|
|
|
674
732
|
REVIEW_RECORD_FENCE, REVIEW_RECORD_FIELDS,
|
|
675
733
|
validateReviewRecord, reviewRecordFailure, reviewGrantCommentBody, parseReviewGrant,
|
|
676
734
|
liveGrantRecords, grantHeadBinding, evaluateReviewerGrant,
|
|
735
|
+
// #508 — bind to the reviewed migration content, not the HEAD
|
|
736
|
+
migrationContentId, migrationEntriesFromLsTree,
|
|
677
737
|
// #398 — repo policy
|
|
678
738
|
GRANT_POLICIES, parseGrantPolicy,
|
|
679
739
|
// #401 — ship honours a reviewer grant
|