@futurelastic/colab-handbook 1.14.0-rc.1 → 1.14.0-rc.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/audit/audit.mjs +133 -48
- package/package.json +1 -1
- package/templates/instruction-files.yml +5 -0
- package/templates/release-auto.yml +16 -3
- package/tools/colab +434 -160
- package/tools/lib/adopt.js +1 -1
- package/tools/lib/audit-cache.js +277 -0
- package/tools/lib/ci-cure.js +10 -1
- package/tools/lib/cure-diff.js +27 -1
- package/tools/lib/git.js +6 -1
- package/tools/lib/grant-policy.js +133 -0
- package/tools/lib/instruction-file.js +26 -0
- package/tools/lib/instruction-gate.js +31 -2
- package/tools/lib/migration-grant.js +4 -4
- package/tools/lib/owner-policy.js +14 -37
- package/tools/lib/release-cut.js +127 -10
- package/tools/lib/ship-batch.js +71 -2
- package/tools/lib/ship-handoff.js +39 -1
- package/tools/lib/workflow-triggers.js +57 -0
package/audit/audit.mjs
CHANGED
|
@@ -41,6 +41,19 @@
|
|
|
41
41
|
// # (colab batch-stats --json) — see "Batch history" below
|
|
42
42
|
// node audit.mjs --base <rev> # the instruction-file ratchet's base for LOCAL repos
|
|
43
43
|
// # (default origin/<trunk>) — see checkInstructionFileShape
|
|
44
|
+
// node audit.mjs --offline # local checks only: no GitHub read at all — see "Remote cache"
|
|
45
|
+
// node audit.mjs --fresh # ignore the cache TTL: re-ask GitHub (still conditional)
|
|
46
|
+
// node audit.mjs --cache-ttl <secs> # how long a cached GitHub read is served unasked
|
|
47
|
+
// # (default 600; env COLAB_AUDIT_CACHE_TTL; 0 = always ask)
|
|
48
|
+
//
|
|
49
|
+
// Remote cache (#593): the GitHub reads (repository metadata, labels, and a slug target's files,
|
|
50
|
+
// branches and tags) are cached across runs, one file per repo under COLAB_AUDIT_CACHE_DIR, else
|
|
51
|
+
// ${COLAB_HOME:-~/.colab}/cache/audit when that home already exists (the audit never creates it).
|
|
52
|
+
// Within the TTL a read costs no request; past it each page is re-asked with If-None-Match, and a
|
|
53
|
+
// 304 costs no quota. A rate limit or no response serves the cached copy, marked stale. --json
|
|
54
|
+
// states per repo where its remote facts came from (`remote`). --offline is the cheap frequent
|
|
55
|
+
// pass: local checks only, remote-only (slug) entries skipped, and it refuses --identity,
|
|
56
|
+
// --batch-history and --fresh, which all need the network.
|
|
44
57
|
//
|
|
45
58
|
// Identity (--identity): metadata never passes through git, so the pre-commit identity scan
|
|
46
59
|
// (templates/pre-commit-identity) structurally cannot see it, and it is the first thing a
|
|
@@ -107,11 +120,13 @@ const ownerBranchLib = require("../tools/lib/owner-branch.js");
|
|
|
107
120
|
const npmGuard = require("../tools/lib/npm-publish-guard.js");
|
|
108
121
|
const installRoute = require("../tools/lib/install-route.js");
|
|
109
122
|
const releaseRunner = require("../tools/lib/release-runner.js"); // #453
|
|
110
|
-
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
|
|
123
|
+
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
|
|
111
124
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
112
125
|
const ciProfile = require("../tools/lib/ci-profile.js"); // #559
|
|
113
126
|
const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
|
|
114
127
|
const batchHistory = require("../tools/lib/batch-history.js"); // #556
|
|
128
|
+
// #593: every GitHub REST read goes through one on-disk, per-repo cache (ETag + TTL) — see the module.
|
|
129
|
+
const auditCache = require("../tools/lib/audit-cache.js");
|
|
115
130
|
// #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
|
|
116
131
|
// validates the `migrations:` declaration against it and reports a `*/migrations/` dir it misses.
|
|
117
132
|
const migrationPaths = require("../tools/lib/migration-paths.js");
|
|
@@ -155,13 +170,20 @@ const COLAB_HOME = process.env.COLAB_HOME || join(homedir(), ".colab");
|
|
|
155
170
|
|
|
156
171
|
function parseArgs(argv) {
|
|
157
172
|
// config === null means "resolve from the precedence chain"; a string means explicit.
|
|
158
|
-
const opts = { config: null, locals: [], slugs: [], json: false, quiet: false, help: false, identity: false, batchHistory: false };
|
|
173
|
+
const opts = { config: null, locals: [], slugs: [], json: false, quiet: false, help: false, identity: false, batchHistory: false, offline: false, fresh: false, cacheTtl: null };
|
|
159
174
|
for (let i = 0; i < argv.length; i++) {
|
|
160
175
|
const a = argv[i];
|
|
161
176
|
if (a === "--json") opts.json = true;
|
|
162
177
|
else if (a === "--quiet" || a === "-q") opts.quiet = true;
|
|
163
178
|
else if (a === "--identity") opts.identity = true;
|
|
164
179
|
else if (a === "--batch-history") opts.batchHistory = true;
|
|
180
|
+
else if (a === "--offline" || a === "--no-remote") opts.offline = true;
|
|
181
|
+
else if (a === "--fresh") opts.fresh = true;
|
|
182
|
+
else if (a === "--cache-ttl") {
|
|
183
|
+
const p = argv[++i];
|
|
184
|
+
if (p === undefined) die("--cache-ttl needs a number of seconds");
|
|
185
|
+
opts.cacheTtl = p;
|
|
186
|
+
}
|
|
165
187
|
else if (a === "--base") {
|
|
166
188
|
const p = argv[++i];
|
|
167
189
|
if (!p) die("--base needs a rev");
|
|
@@ -515,31 +537,30 @@ function runGh(args) {
|
|
|
515
537
|
}
|
|
516
538
|
|
|
517
539
|
// A slug is fetched read-only through the API — nothing is cloned, nothing is written
|
|
518
|
-
// into anyone's working tree.
|
|
540
|
+
// into anyone's working tree. Every REST read below goes through `remoteCache` (#593), set up
|
|
541
|
+
// once per run in runAudit; the `--jq` filters these used to pass are applied here in JS,
|
|
542
|
+
// because a cached page is the raw API body.
|
|
543
|
+
let remoteCache = auditCache.create({ dir: null, ttlSeconds: 0 });
|
|
544
|
+
|
|
519
545
|
function readRemoteFile(slug, path) {
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
} catch {
|
|
523
|
-
return null;
|
|
524
|
-
}
|
|
546
|
+
const r = remoteCache.get(slug, `repos/${slug}/contents/${path}`, { accept: "application/vnd.github.raw" });
|
|
547
|
+
return r.status === "ok" ? r.text : null;
|
|
525
548
|
}
|
|
526
549
|
|
|
527
550
|
function listRemoteDir(slug, path) {
|
|
551
|
+
const r = remoteCache.get(slug, `repos/${slug}/contents/${path}`);
|
|
552
|
+
if (r.status !== "ok") return [];
|
|
528
553
|
try {
|
|
529
|
-
const
|
|
530
|
-
return
|
|
554
|
+
const arr = JSON.parse(r.text);
|
|
555
|
+
return Array.isArray(arr) ? arr.map((e) => String(e.name || "").trim()).filter(Boolean) : [];
|
|
531
556
|
} catch {
|
|
532
557
|
return [];
|
|
533
558
|
}
|
|
534
559
|
}
|
|
535
560
|
|
|
536
561
|
function listRemoteBranches(slug) {
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
return out.split("\n").map((s) => s.trim()).filter(Boolean);
|
|
540
|
-
} catch {
|
|
541
|
-
return null; // null = could not determine, distinct from "no branches"
|
|
542
|
-
}
|
|
562
|
+
const r = remoteCache.get(slug, `repos/${slug}/branches`, { paginate: true });
|
|
563
|
+
return r.status === "ok" ? r.items.map((b) => String(b.name)) : null; // null = could not determine, distinct from "no branches"
|
|
543
564
|
}
|
|
544
565
|
|
|
545
566
|
// Same null/[] contract as listRemoteBranches: null = could not determine (no remote, no
|
|
@@ -547,33 +568,22 @@ function listRemoteBranches(slug) {
|
|
|
547
568
|
// falsifiers (#137) — a version-shaped tag is evidence against a declared "nothing consumes
|
|
548
569
|
// this" claim, whether the source is local or remote.
|
|
549
570
|
function listRemoteTags(slug) {
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
return out.split("\n").map((s) => s.trim()).filter(Boolean);
|
|
553
|
-
} catch {
|
|
554
|
-
return null;
|
|
555
|
-
}
|
|
571
|
+
const r = remoteCache.get(slug, `repos/${slug}/tags`, { paginate: true });
|
|
572
|
+
return r.status === "ok" ? r.items.map((t) => String(t.name)) : null;
|
|
556
573
|
}
|
|
557
574
|
|
|
558
575
|
// Labels live on GitHub, not in the working tree, so this is the audit's one check that
|
|
559
576
|
// needs the tracker. `null` means "could not determine" — no remote, no auth, gh absent,
|
|
560
|
-
// API error — and the caller stays SILENT on it rather than warning: unlike branches
|
|
577
|
+
// API error, --offline — and the caller stays SILENT on it rather than warning: unlike branches
|
|
561
578
|
// (every git repo has them), labels are a GitHub-only concept and a remote-less or
|
|
562
579
|
// offline audit legitimately cannot see them. A warn per offline repo would be noise,
|
|
563
580
|
// and we cannot assert a label is missing when we could not read the set at all.
|
|
564
|
-
// Each entry is { name, description } (#364)
|
|
565
|
-
//
|
|
566
|
-
// null: a half-read set would report the unread half as "missing".
|
|
581
|
+
// Each entry is { name, description } (#364). Any page that does not parse makes the whole
|
|
582
|
+
// read null: a half-read set would report the unread half as "missing".
|
|
567
583
|
function listRemoteLabels(slug) {
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
const l = JSON.parse(line);
|
|
572
|
-
return { name: String(l.name), description: typeof l.description === "string" ? l.description : "" };
|
|
573
|
-
});
|
|
574
|
-
} catch {
|
|
575
|
-
return null;
|
|
576
|
-
}
|
|
584
|
+
const r = remoteCache.get(slug, `repos/${slug}/labels`, { paginate: true });
|
|
585
|
+
if (r.status !== "ok") return null;
|
|
586
|
+
return r.items.map((l) => ({ name: String(l.name), description: typeof l.description === "string" ? l.description : "" }));
|
|
577
587
|
}
|
|
578
588
|
|
|
579
589
|
// The repository's own METADATA — name, description, homepage, topics, visibility — which
|
|
@@ -596,6 +606,7 @@ function listRemoteLabels(slug) {
|
|
|
596
606
|
// One issue's state, labels and comments (#441 — a release.final-grant's decision issue), or null
|
|
597
607
|
// when it could not be read. null is never "no decision": the caller fails closed on it.
|
|
598
608
|
function readRemoteIssue(slug, num) {
|
|
609
|
+
if (remoteCache.offline) return null; // --offline: no tracker read (the caller skips the check)
|
|
599
610
|
try {
|
|
600
611
|
return JSON.parse(runGh(["issue", "view", String(num), "--repo", slug, "--json", "state,labels,comments"]));
|
|
601
612
|
} catch {
|
|
@@ -609,11 +620,11 @@ const remoteMetadataCache = new Map();
|
|
|
609
620
|
function readRemoteMetadata(slug) {
|
|
610
621
|
if (remoteMetadataCache.has(slug)) return remoteMetadataCache.get(slug);
|
|
611
622
|
let r;
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
r = { status: "unreadable" };
|
|
623
|
+
const got = remoteCache.get(slug, `repos/${slug}`);
|
|
624
|
+
if (got.status === "offline") r = { status: "offline" };
|
|
625
|
+
else if (got.status !== "ok") r = { status: "unreadable" };
|
|
626
|
+
else {
|
|
627
|
+
try { r = { status: "ok", data: JSON.parse(got.text) }; } catch { r = { status: "unreadable" }; }
|
|
617
628
|
}
|
|
618
629
|
remoteMetadataCache.set(slug, r);
|
|
619
630
|
return r;
|
|
@@ -1123,6 +1134,16 @@ function renderDuration(age, minDays = DURATION_MIN_DAYS) {
|
|
|
1123
1134
|
}
|
|
1124
1135
|
|
|
1125
1136
|
function auditRepo(target, ctx) {
|
|
1137
|
+
remoteCache.begin();
|
|
1138
|
+
const info = auditRepoInner(target, ctx);
|
|
1139
|
+
// #593: where this repo's remote facts came from — cache, revalidated (304), fetched, stale —
|
|
1140
|
+
// and how old the oldest is. Absent when the repo made no GitHub read at all.
|
|
1141
|
+
const remote = remoteCache.summary();
|
|
1142
|
+
if (remote) info.remote = remote;
|
|
1143
|
+
return info;
|
|
1144
|
+
}
|
|
1145
|
+
|
|
1146
|
+
function auditRepoInner(target, ctx) {
|
|
1126
1147
|
const src = makeSource(target);
|
|
1127
1148
|
// #522: the branch list is read by the single-trunk rule (tier B / exposure none|released) AND the
|
|
1128
1149
|
// trunk-exists check below — one read, so a remote target costs one API listing, not three.
|
|
@@ -1401,11 +1422,11 @@ function auditRepo(target, ctx) {
|
|
|
1401
1422
|
{
|
|
1402
1423
|
const pol = migrationGrant.parseGrantPolicy(cfg);
|
|
1403
1424
|
info.migrationGrant = pol.policy;
|
|
1404
|
-
// #
|
|
1405
|
-
//
|
|
1425
|
+
// #598: an undeclared key is not "human, full stop" — the machine-level value (the gating
|
|
1426
|
+
// machine's colab config) may apply, and this audit cannot know which machine gates. So the
|
|
1406
1427
|
// source is reported: `repo` (declared here, final) or `undeclared` (repo-local default human,
|
|
1407
|
-
//
|
|
1408
|
-
//
|
|
1428
|
+
// machine level unread). The round-trip warning below stays on a DECLARED reviewer only: for a
|
|
1429
|
+
// machine-level reviewer the mint itself refuses without the job, which is where it surfaces.
|
|
1409
1430
|
info.migrationGrantSource = pol.declared ? "repo" : "undeclared";
|
|
1410
1431
|
if (!pol.valid) fail(pol.reason);
|
|
1411
1432
|
// #494: R needs a live `Migration round-trip…` job. Without one every reviewer grant fails R
|
|
@@ -1464,6 +1485,18 @@ function auditRepo(target, ctx) {
|
|
|
1464
1485
|
if (!tr.valid) fail(tr.reason);
|
|
1465
1486
|
}
|
|
1466
1487
|
|
|
1488
|
+
// ---- instruction-files (#602) ---------------------------------------------
|
|
1489
|
+
// `instruction-files: upstream` — a fork whose CLAUDE.md/AGENTS.md belong to the upstream it
|
|
1490
|
+
// tracks; the instruction-file shape is then not judged (checkInstructionFileShape below, and
|
|
1491
|
+
// the shared gate the hook and the CI workflow run). tools/lib/instruction-file.js
|
|
1492
|
+
// parseInstructionFiles is the one reading. An invalid value fails: it reads as absent (judged —
|
|
1493
|
+
// the stricter direction), so the declaration silently does nothing.
|
|
1494
|
+
{
|
|
1495
|
+
const ifl = instructionFile.parseInstructionFiles(cfg);
|
|
1496
|
+
info.instructionFiles = ifl.declared ? ifl.value : null;
|
|
1497
|
+
if (!ifl.valid) fail(ifl.reason);
|
|
1498
|
+
}
|
|
1499
|
+
|
|
1467
1500
|
// ---- ci-docs-skip (#570) ----------------------------------------------------
|
|
1468
1501
|
// Opts the CI templates' guard into docs-only mode: a change whose every path is documentation
|
|
1469
1502
|
// (tools/lib/docs-only.js, the rule colab ship applies), from a green base, skips the suite.
|
|
@@ -1572,7 +1605,11 @@ function auditRepo(target, ctx) {
|
|
|
1572
1605
|
// not been reopened. Unreadable fails closed: an automatic production deploy nobody can
|
|
1573
1606
|
// trace to a human's choice is exactly what the grant exists to rule out.
|
|
1574
1607
|
const grant = rel.effective.finalGrant;
|
|
1575
|
-
if (grant) {
|
|
1608
|
+
if (grant && ctx.offline) {
|
|
1609
|
+
// #593: --offline reads no tracker. Recorded, not judged — the run header says once that
|
|
1610
|
+
// remote facts were not read, so this row is never mistaken for a verified grant.
|
|
1611
|
+
info.releaseFinalGrant = { issue: grant.issue, ok: null, checked: false, reason: "--offline" };
|
|
1612
|
+
} else if (grant) {
|
|
1576
1613
|
const v = releasePolicy.finalGrantVerdict(src.issue ? src.issue(grant.issue) : null, { issue: grant.issue, trust: trustHumansLib.parseTrustHumans(cfg) });
|
|
1577
1614
|
info.releaseFinalGrant = { issue: grant.issue, ok: v.ok, ruledBy: v.ruledBy };
|
|
1578
1615
|
if (!v.ok) {
|
|
@@ -1791,7 +1828,10 @@ function auditRepo(target, ctx) {
|
|
|
1791
1828
|
checkInstructionFileBlocks(src, warn, { self: isSelf });
|
|
1792
1829
|
// #419: and prose left in CLAUDE.md / no AGENTS.md at all — same posture, same reason.
|
|
1793
1830
|
// #588: and the same finding FAILS where the instruction-file ratchet trips (local repos only).
|
|
1794
|
-
checkInstructionFileShape(src, warn, fail, { base: ctx.base, trunk: cfg?.trunk ?? null });
|
|
1831
|
+
checkInstructionFileShape(src, warn, fail, { base: ctx.base, trunk: cfg?.trunk ?? null, upstreamOwned: instructionFile.parseInstructionFiles(cfg).exempt });
|
|
1832
|
+
// #599: a caller of the reusable instruction-files workflow narrowed off session branches, or not
|
|
1833
|
+
// dispatchable, defeats the ratchet's point (fail on the branch) and the cure rule's way out.
|
|
1834
|
+
checkInstructionFilesCaller(src, workflows, cfg?.trunk ?? null, warn);
|
|
1795
1835
|
|
|
1796
1836
|
// ---- markdown anchor links resolve (#158) --------------------------------
|
|
1797
1837
|
// Unconditional, same posture as checkClaudeMdSize above: general markdown hygiene,
|
|
@@ -2706,7 +2746,12 @@ function instructionRatchet(src, opts) {
|
|
|
2706
2746
|
return r;
|
|
2707
2747
|
}
|
|
2708
2748
|
|
|
2749
|
+
//
|
|
2750
|
+
// #602: a fork declaring `instruction-files: upstream` is not judged at all — neither the ratchet's
|
|
2751
|
+
// failure nor the two warnings: its CLAUDE.md/AGENTS.md are the upstream's (CONVENTIONS.md §9, *A
|
|
2752
|
+
// fork of an upstream*), and the --json `instructionFiles` field says why nothing was reported.
|
|
2709
2753
|
function checkInstructionFileShape(src, warn, fail = warn, opts = {}) {
|
|
2754
|
+
if (opts.upstreamOwned) return;
|
|
2710
2755
|
const ratchet = instructionRatchet(src, opts);
|
|
2711
2756
|
if (ratchet && !ratchet.ok) warn(`instruction-file ratchet not evaluated: ${ratchet.error} (#588)`);
|
|
2712
2757
|
if (ratchet && ratchet.ok && ratchet.fail) {
|
|
@@ -2756,6 +2801,13 @@ function checkInstructionFileShape(src, warn, fail = warn, opts = {}) {
|
|
|
2756
2801
|
// caller is `deploy: manual` (a human runs it) or `deploy: tag` deployed OUTSIDE CI (a GitOps
|
|
2757
2802
|
// poller runs it). Both share the same invariant: the deploy runs off no in-repo workflow, so the
|
|
2758
2803
|
// path to production must be WRITTEN DOWN or nobody but its author can ship it.
|
|
2804
|
+
// ---- the instruction-files caller's trigger (#599) ---------------------------
|
|
2805
|
+
// The logic lives in tools/lib/workflow-triggers.js beside the other trigger readers. WARN, never
|
|
2806
|
+
// fail: the caller is a copy the repo owns, and handbook-sync's trigger graft is the fix.
|
|
2807
|
+
function checkInstructionFilesCaller(src, workflows, trunk, warn) {
|
|
2808
|
+
for (const f of instructionFilesCallerFindings({ readFile: (p) => src.readFile(p), workflows, trunk })) warn(f.text);
|
|
2809
|
+
}
|
|
2810
|
+
|
|
2759
2811
|
// ---- a deploy trigger that fires on a pre-release tag (#332) ---------------
|
|
2760
2812
|
// The logic lives in tools/lib/workflow-triggers.js (#338) so `colab release cut` refuses on the
|
|
2761
2813
|
// same finding; this maps its severity onto the audit's fail/warn.
|
|
@@ -2890,6 +2942,9 @@ function checkPrivateNpm(src, workflows, fail, warn) {
|
|
|
2890
2942
|
const assetSurface = npmGuard.releaseAssetUploads(workflows, reader.readFile).length > 0;
|
|
2891
2943
|
if (!npmSurface && !assetSurface) return;
|
|
2892
2944
|
const meta = src.metadata ? src.metadata() : { status: "unreadable" };
|
|
2945
|
+
// #593: --offline reads no visibility by request; the run header already says so once, and a
|
|
2946
|
+
// "could not be read" advisory on every offline pass would mark every such repo non-clean.
|
|
2947
|
+
if (meta.status === "offline") return;
|
|
2893
2948
|
let visibility = null;
|
|
2894
2949
|
if (meta.status === "ok" && meta.data) {
|
|
2895
2950
|
visibility = meta.data.visibility || (meta.data.private === true ? "private" : meta.data.private === false ? "public" : null);
|
|
@@ -3241,6 +3296,10 @@ function report(results, opts, ctx) {
|
|
|
3241
3296
|
? { scanned: true, vocabulary: ctx.identity.path, source: ctx.identity.source, terms: ctx.identity.count }
|
|
3242
3297
|
: { scanned: false, reason: "not requested (--identity)" },
|
|
3243
3298
|
batchHistory: ctx.batchHistory ? { read: true } : { read: false, reason: "not requested (--batch-history)" },
|
|
3299
|
+
// #593: whether GitHub was read at all this run, and the cache it was read through.
|
|
3300
|
+
remote: ctx.offline
|
|
3301
|
+
? { read: false, reason: "--offline" }
|
|
3302
|
+
: { read: true, cache: ctx.cache.dir, persistent: !!ctx.cache.dir, ttlSeconds: ctx.cache.ttlSeconds, fresh: ctx.cache.fresh },
|
|
3244
3303
|
results,
|
|
3245
3304
|
}, null, 2));
|
|
3246
3305
|
return;
|
|
@@ -3262,6 +3321,10 @@ function report(results, opts, ctx) {
|
|
|
3262
3321
|
console.log(ctx.batchHistory
|
|
3263
3322
|
? "batch: batch landing history read per local repo (colab batch-stats); advisories only against declared thresholds"
|
|
3264
3323
|
: "batch: batch landing history NOT read (pass --batch-history)");
|
|
3324
|
+
// #593: same once-per-run statement for the remote reads.
|
|
3325
|
+
console.log(ctx.offline
|
|
3326
|
+
? "remote: GitHub NOT read (--offline) — labels, visibility and grants unchecked; remote-only entries skipped"
|
|
3327
|
+
: `remote: GitHub read through ${ctx.cache.dir ? `the cache at ${ctx.cache.dir}` : "an in-memory cache (no colab home to persist it)"}, TTL ${ctx.cache.ttlSeconds}s${ctx.cache.fresh ? ", --fresh" : ""}`);
|
|
3265
3328
|
console.log("");
|
|
3266
3329
|
|
|
3267
3330
|
const shown = opts.quiet ? results.filter((r) => !r.clean) : results;
|
|
@@ -3277,7 +3340,8 @@ function report(results, opts, ctx) {
|
|
|
3277
3340
|
// The handbook's own row says WHY it carries no stamp findings. Without this it
|
|
3278
3341
|
// would read as clean-by-luck, which is indistinguishable from a check that
|
|
3279
3342
|
// quietly stopped working.
|
|
3280
|
-
if (r.
|
|
3343
|
+
if (r.skipped === "offline") lines.push("– skipped (--offline: a remote-only entry has nothing local to check)");
|
|
3344
|
+
else if (r.self) lines.push("⌂ handbook source — every rule applies except its own stamps (it has nothing to copy from)");
|
|
3281
3345
|
else if (r.adoption === "local") lines.push(`⌂ adopted locally, not committed — descriptor hidden by .git/info/exclude; a repo the fleet does not own (CONVENTIONS.md §9)${r.clean ? " ✓" : ""}`);
|
|
3282
3346
|
else if (r.clean) lines.push("✓");
|
|
3283
3347
|
r.findings.forEach((f) => lines.push(`${f.level === "fail" ? "⚠" : "·"} ${f.text}`));
|
|
@@ -3294,8 +3358,9 @@ function report(results, opts, ctx) {
|
|
|
3294
3358
|
|
|
3295
3359
|
const failed = results.filter((r) => !r.ok).length;
|
|
3296
3360
|
const warned = results.filter((r) => r.ok && !r.clean).length;
|
|
3361
|
+
const skipped = results.filter((r) => r.skipped).length;
|
|
3297
3362
|
console.log("");
|
|
3298
|
-
console.log(`${results.length} repo(s): ${results.length - failed - warned} clean, ${warned} with advisories, ${failed} with problems.`);
|
|
3363
|
+
console.log(`${results.length} repo(s): ${results.length - failed - warned - skipped} clean, ${warned} with advisories, ${failed} with problems${skipped ? `, ${skipped} skipped` : ""}.`);
|
|
3299
3364
|
}
|
|
3300
3365
|
|
|
3301
3366
|
/**
|
|
@@ -3343,13 +3408,33 @@ function runAudit(opts) {
|
|
|
3343
3408
|
const targets = loadTargets(opts);
|
|
3344
3409
|
if (!targets.length) die("nothing to audit — add entries to the repo list or pass --local <path>");
|
|
3345
3410
|
|
|
3411
|
+
if (opts.offline) {
|
|
3412
|
+
// Each of these is a read of the network the operator asked for; an offline run that quietly
|
|
3413
|
+
// skipped it would report clean over a check that never ran.
|
|
3414
|
+
if (opts.identity) die("--offline and --identity conflict: the identity scan reads repository metadata from GitHub");
|
|
3415
|
+
if (opts.batchHistory) die("--offline and --batch-history conflict: batch history reads CI runs from GitHub");
|
|
3416
|
+
if (opts.fresh) die("--offline and --fresh conflict: --fresh asks GitHub, --offline never does");
|
|
3417
|
+
}
|
|
3418
|
+
const ttlSeconds = auditCache.resolveTtlSeconds(opts.cacheTtl);
|
|
3419
|
+
if (ttlSeconds === null) die(`--cache-ttl / COLAB_AUDIT_CACHE_TTL must be a whole number of seconds (got "${opts.cacheTtl ?? process.env.COLAB_AUDIT_CACHE_TTL}")`);
|
|
3420
|
+
remoteCache = auditCache.create({
|
|
3421
|
+
dir: auditCache.resolveDir(process.env, COLAB_HOME), ttlSeconds, fresh: opts.fresh, offline: opts.offline,
|
|
3422
|
+
});
|
|
3423
|
+
|
|
3346
3424
|
const ctx = { handbook: handbookInfo(HANDBOOK_ROOT), templateNames: templateNames(HANDBOOK_ROOT) };
|
|
3425
|
+
ctx.offline = !!opts.offline;
|
|
3426
|
+
ctx.cache = { dir: remoteCache.dir, ttlSeconds, fresh: !!opts.fresh };
|
|
3347
3427
|
ctx.identity = opts.identity ? loadIdentityVocabulary() : null;
|
|
3348
3428
|
ctx.batchHistory = !!opts.batchHistory;
|
|
3349
3429
|
ctx.base = opts.base || null;
|
|
3350
3430
|
|
|
3351
3431
|
const results = [];
|
|
3352
3432
|
for (const t of targets) {
|
|
3433
|
+
if (ctx.offline && t.kind !== "local") {
|
|
3434
|
+
// A slug target has nothing local to check: every fact about it is a GitHub read.
|
|
3435
|
+
results.push({ repo: t.label, kind: t.kind, tier: null, ok: true, clean: true, skipped: "offline", remote: { mode: "offline" }, findings: [] });
|
|
3436
|
+
continue;
|
|
3437
|
+
}
|
|
3353
3438
|
try {
|
|
3354
3439
|
results.push(auditRepo(t, ctx));
|
|
3355
3440
|
} catch (err) {
|
package/package.json
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
# Copy to .github/workflows/instruction-files.yml — CLAUDE.md must be @AGENTS.md + tool blocks (#588).
|
|
2
2
|
name: instruction-files
|
|
3
3
|
on:
|
|
4
|
+
# Keep `push:` UNFILTERED (#599). The ratchet is meant to fail on the session branch that breaks
|
|
5
|
+
# it, before trunk; narrowed to `branches: [main]`, it first fails ON trunk, and the cure branch's
|
|
6
|
+
# push run cannot prove the job (#297). The audit reports a narrowed copy.
|
|
4
7
|
push:
|
|
5
8
|
pull_request:
|
|
9
|
+
# Lets `colab ship` prove a red job on a cure branch by dispatch (#510), with no human ci-grant.
|
|
10
|
+
workflow_dispatch:
|
|
6
11
|
jobs:
|
|
7
12
|
instruction-files:
|
|
8
13
|
uses: futurelastic/colab-handbook/.github/workflows/instruction-files.yml@main
|
|
@@ -29,11 +29,14 @@
|
|
|
29
29
|
# comment above that job
|
|
30
30
|
# the cut tagged a FINAL — route deploy + health check (job `deploy`, #446) — see
|
|
31
31
|
# deploy-tag-fast only "DEPLOYING IN THIS RUN" below
|
|
32
|
+
# the cut tagged a FINAL — route published like any tag (Release marked latest, npm
|
|
33
|
+
# library-fast (#590) `latest`); nothing deploys — see "A LIBRARY" below
|
|
32
34
|
#
|
|
33
35
|
# Every decision — whether a candidate is owed, which bump, whether the test period
|
|
34
36
|
# elapsed clean, whether the final is automatic on this repo at all — is the colab CLI's,
|
|
35
37
|
# read from .github/project.yml's release rung. This file only schedules it and publishes
|
|
36
|
-
# what it tagged. Where the rung leaves candidates off, every run is a recorded refusal
|
|
38
|
+
# what it tagged. Where the rung leaves candidates off, every run is a recorded refusal — save on
|
|
39
|
+
# route library-fast, where the cut is the final (below).
|
|
37
40
|
#
|
|
38
41
|
# WHERE IT FITS. `colab release cut` tags origin/main — release tags land on `main` on every
|
|
39
42
|
# trunk shape — so the same file, unchanged, fits two kinds of repo:
|
|
@@ -94,6 +97,14 @@
|
|
|
94
97
|
# run still concludes on the `release` job. EDIT: on this route, a cron more frequent than daily
|
|
95
98
|
# tags a head that release.final-spacing held back sooner.
|
|
96
99
|
#
|
|
100
|
+
# A LIBRARY — THE CUT IS THE FINAL (library-fast, #590). On a repo with no production that declares
|
|
101
|
+
# `release.route: library-fast`, `colab release cut --auto` tags the FINAL vX.Y.Z on a green main
|
|
102
|
+
# head once a first final exists (the first is a human's tag) — no candidate, no test period. With
|
|
103
|
+
# `release.version-source: manifest` (the route's default) the version is the manifest's: a merge
|
|
104
|
+
# that bumps package.json releases it, a merge that does not is a no-op. This run publishes the
|
|
105
|
+
# final itself — the Release step marks it latest, the npm job publishes it to `latest` — because a
|
|
106
|
+
# publish-on-tag workflow would not fire for a tag this job pushes. The deploy job stays skipped.
|
|
107
|
+
#
|
|
97
108
|
# DRY RUN ON A FIX BRANCH (#474). This workflow never runs on a branch by itself, so a fix to it
|
|
98
109
|
# (a moved runner label, a HANDBOOK_REF naming a missing branch) had no run to prove it, and the
|
|
99
110
|
# cure rule (CONVENTIONS.md §4) could only refuse it — a human ci-grant was the one door. Dispatch
|
|
@@ -475,8 +486,10 @@ jobs:
|
|
|
475
486
|
echo "tag=$TAG" >> "$GITHUB_OUTPUT"
|
|
476
487
|
echo "Cut $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
477
488
|
# #446: on route deploy-tag-fast the cut IS the final, and the deploy job deploys it in
|
|
478
|
-
# this run (a tag pushed with GITHUB_TOKEN starts no `push: tags` workflow).
|
|
479
|
-
|
|
489
|
+
# this run (a tag pushed with GITHUB_TOKEN starts no `push: tags` workflow). #590: route
|
|
490
|
+
# library-fast cuts a final too, with `deploy: null` — it is published below (Release, npm)
|
|
491
|
+
# and never handed to the deploy job, so key on the deploy facts, not on `final`.
|
|
492
|
+
if [ "$(jq -r '.final == true and .deploy != null' "$OUT")" = "true" ]; then
|
|
480
493
|
echo "final=$TAG" >> "$GITHUB_OUTPUT"
|
|
481
494
|
echo "health-url=$(jq -r '.deploy.healthUrl // ""' "$OUT")" >> "$GITHUB_OUTPUT"
|
|
482
495
|
fi
|