@futurelastic/colab-handbook 1.12.0-rc.38 → 1.12.0-rc.40
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 +26 -0
- package/package.json +1 -1
- package/templates/release-auto.yml +20 -0
- package/tools/lib/install-route.js +139 -0
package/audit/audit.mjs
CHANGED
|
@@ -94,6 +94,7 @@ const releasePolicy = require("../tools/lib/release-policy.js");
|
|
|
94
94
|
// push-site guard in the CLI, so the audit and the tool can never disagree about what it means.
|
|
95
95
|
const ownerBranchLib = require("../tools/lib/owner-branch.js");
|
|
96
96
|
const npmGuard = require("../tools/lib/npm-publish-guard.js");
|
|
97
|
+
const installRoute = require("../tools/lib/install-route.js");
|
|
97
98
|
const releaseRunner = require("../tools/lib/release-runner.js"); // #453
|
|
98
99
|
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
|
|
99
100
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
@@ -1511,6 +1512,13 @@ function auditRepo(target, ctx) {
|
|
|
1511
1512
|
}
|
|
1512
1513
|
}
|
|
1513
1514
|
|
|
1515
|
+
// ---- distribution (#469) -----------------------------------------------------
|
|
1516
|
+
// Optional, raw, no default: absent means undeclared — nothing in a repository tells a tool
|
|
1517
|
+
// from a library, so only a declared value is ever checked (checkInstallRoute, below).
|
|
1518
|
+
if ("distribution" in cfg && !installRoute.VALID_DISTRIBUTION.has(cfg.distribution)) {
|
|
1519
|
+
fail(`distribution is ${JSON.stringify(cfg.distribution)}, expected "js" or "compiled" — omit the key if this repository distributes no tool`);
|
|
1520
|
+
}
|
|
1521
|
+
|
|
1514
1522
|
// ---- axis of record (#144) -----------------------------------------------
|
|
1515
1523
|
// Which key governs gate count: `exposure` when declared (it wins outright — see
|
|
1516
1524
|
// tools/lib/axis-authority.js for why this is a function, not a bijection, of `tier`),
|
|
@@ -1657,6 +1665,7 @@ function auditRepo(target, ctx) {
|
|
|
1657
1665
|
checkFastRouteDeploy(src, workflows, cfg, fail);
|
|
1658
1666
|
checkDeployContainer(src, workflows, cfg, warn);
|
|
1659
1667
|
checkPrivateNpm(src, workflows, fail, warn);
|
|
1668
|
+
checkInstallRoute(src, workflows, cfg, warn);
|
|
1660
1669
|
checkReleaseRunner(src, workflows, warn);
|
|
1661
1670
|
|
|
1662
1671
|
const runbook = cfg && "runbook" in cfg ? cfg.runbook : null;
|
|
@@ -2678,6 +2687,23 @@ function checkPrivateNpm(src, workflows, fail, warn) {
|
|
|
2678
2687
|
for (const f of all) (f.level === "fail" ? fail : warn)(f.text);
|
|
2679
2688
|
}
|
|
2680
2689
|
|
|
2690
|
+
// ---- a declared distributed tool has an install route (#469) -------------------
|
|
2691
|
+
// CONVENTIONS.md §6, Distribution. Runs only when project.yml declares `distribution: js|compiled`,
|
|
2692
|
+
// so an undeclared repository costs no read and no API call. Visibility from the GitHub API, same
|
|
2693
|
+
// derivation as checkPrivateNpm; unreadable → the module accepts either row's route. Advisory:
|
|
2694
|
+
// a publish step in a reusable workflow outside this repository is invisible to it.
|
|
2695
|
+
function checkInstallRoute(src, workflows, cfg, warn) {
|
|
2696
|
+
const distribution = cfg && "distribution" in cfg ? cfg.distribution : null;
|
|
2697
|
+
if (!installRoute.VALID_DISTRIBUTION.has(distribution)) return;
|
|
2698
|
+
const meta = src.metadata ? src.metadata() : { status: "unreadable" };
|
|
2699
|
+
let visibility = null;
|
|
2700
|
+
if (meta.status === "ok" && meta.data) {
|
|
2701
|
+
visibility = meta.data.visibility || (meta.data.private === true ? "private" : meta.data.private === false ? "public" : null);
|
|
2702
|
+
}
|
|
2703
|
+
const reader = { readFile: (p) => src.readFile(p), listDir: (p) => src.listDir(p), workflows };
|
|
2704
|
+
for (const f of installRoute.findings({ distribution, ...reader, visibility })) warn(f.text);
|
|
2705
|
+
}
|
|
2706
|
+
|
|
2681
2707
|
// ---- the release workflow runs on the repo's own runners when private (#453) -------------------
|
|
2682
2708
|
// A hosted job on a private repo is billed, and a billing refusal fails the release run at trunk's
|
|
2683
2709
|
// head — `colab ship` then reads trunk as red. Visibility from the GitHub API, read only when a
|
package/package.json
CHANGED
|
@@ -198,6 +198,9 @@ env:
|
|
|
198
198
|
# next the newest candidate (vX.Y.Z-rc.N) — the fast channel
|
|
199
199
|
# vX.Y.Z an exact version tag — frozen; moving it is a deliberate act, like re-copying
|
|
200
200
|
# a template
|
|
201
|
+
# A ref the handbook does not carry (e.g. `stable` before its first final, or on a mirror)
|
|
202
|
+
# falls back to the newest final tag new enough for this template, else `next`, with a warning —
|
|
203
|
+
# it never fails the run (#480).
|
|
201
204
|
HANDBOOK_REF: "stable"
|
|
202
205
|
HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
|
|
203
206
|
# A TRANSIENT UPSTREAM ERROR NEVER TURNS MAIN RED (#464). This run fires on every landing, and a
|
|
@@ -306,6 +309,23 @@ jobs:
|
|
|
306
309
|
run: |
|
|
307
310
|
set -euo pipefail
|
|
308
311
|
eval "$RETRY_TRANSIENT"
|
|
312
|
+
# A HANDBOOK_REF the handbook does not carry falls back instead of failing (#480): `stable`
|
|
313
|
+
# exists only once a final has been cut, and a fork or mirror may never have it. The
|
|
314
|
+
# fallback is the newest final vX.Y.Z tag at or above MIN_FINAL, else `next`, and it says
|
|
315
|
+
# so. MIN_FINAL is the first final carrying every CLI verb this template calls (`--auto`,
|
|
316
|
+
# #422–#425): an older final rejects them, and that is a red run too (#427). A ref that
|
|
317
|
+
# does exist is always used as written; a failed listing fails the step, never guesses.
|
|
318
|
+
MIN_FINAL="v1.12.0"
|
|
319
|
+
REFS="$(retry_transient git ls-remote --heads --tags "$HANDBOOK_REPO")"
|
|
320
|
+
if ! grep -Eq "[[:space:]]refs/(heads|tags)/${HANDBOOK_REF//./\\.}$" <<< "$REFS"; then
|
|
321
|
+
FALLBACK="next"
|
|
322
|
+
for t in $(sed -nE 's#^[0-9a-f]+[[:space:]]+refs/tags/(v[0-9]+\.[0-9]+\.[0-9]+)$#\1#p' <<< "$REFS" | sort -V); do
|
|
323
|
+
[ "$(printf '%s\n' "$MIN_FINAL" "$t" | sort -V | head -n 1)" = "$MIN_FINAL" ] && FALLBACK="$t"
|
|
324
|
+
done
|
|
325
|
+
echo "::warning::HANDBOOK_REF \"$HANDBOOK_REF\" is not a branch or tag of $HANDBOOK_REPO — using \"$FALLBACK\" (the newest final tag from $MIN_FINAL on, else next). Set HANDBOOK_REF to silence this."
|
|
326
|
+
echo "HANDBOOK_REF \`$HANDBOOK_REF\` does not exist upstream — fetched \`$FALLBACK\` instead (#480)." >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
|
|
327
|
+
HANDBOOK_REF="$FALLBACK"
|
|
328
|
+
fi
|
|
309
329
|
# A clone that died half-way leaves a directory a second clone refuses — start clean each try.
|
|
310
330
|
fetch_cli() { rm -rf "$RUNNER_TEMP/colab-handbook"; git clone --quiet --depth 1 --branch "$HANDBOOK_REF" "$HANDBOOK_REPO" "$RUNNER_TEMP/colab-handbook"; }
|
|
311
331
|
retry_transient fetch_cli
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* A declared distributed tool has an install route §6 recognises (#469).
|
|
4
|
+
*
|
|
5
|
+
* CONVENTIONS.md §6, *Distribution*: every distributed tool installs with `npx`, by one of four
|
|
6
|
+
* rows (public/private × JS/compiled). What the audit cannot measure is whether a repository
|
|
7
|
+
* ships a tool at all — a root `bin`, a build matrix or a release workflow is just as true of a
|
|
8
|
+
* library or an app nobody installs. So the signal is DECLARED, never inferred: a repository
|
|
9
|
+
* says `distribution: js | compiled` in `.github/project.yml`, and only then is its row's route
|
|
10
|
+
* checked. Undeclared → no finding and no IO, by construction (the admission test: markers
|
|
11
|
+
* identify our text, not a stack).
|
|
12
|
+
*
|
|
13
|
+
* Pure: takes a reader plus the repository's visibility (read from the GitHub API at the
|
|
14
|
+
* caller, never guessed) and returns findings.
|
|
15
|
+
*
|
|
16
|
+
* VALID_DISTRIBUTION -> Set of the declared values
|
|
17
|
+
* rootBin(readFile) -> true when the root package.json has a non-empty bin
|
|
18
|
+
* distRefsCallers(workflows, read) -> [{ wf, line, target }] in-repo routes to dist refs
|
|
19
|
+
* evidence(reader) -> per-row route evidence (what is present, what is missing)
|
|
20
|
+
* findings({ distribution, … }) -> [{ level, text }]
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
const npmGuard = require('./npm-publish-guard.js');
|
|
24
|
+
|
|
25
|
+
const VALID_DISTRIBUTION = new Set(['js', 'compiled']);
|
|
26
|
+
|
|
27
|
+
// The one string the dist-refs template writes that no other workflow has a reason to: the ref
|
|
28
|
+
// namespace its orphan commits are pushed to. Content, not file name — a renamed copy counts.
|
|
29
|
+
const DIST_REF = /refs\/tags\/dist\//;
|
|
30
|
+
const LOCAL_USES = /^\s*-?\s*uses:\s*['"]?\.\/\.github\/workflows\/([\w.-]+\.ya?ml)['"]?\s*$/;
|
|
31
|
+
|
|
32
|
+
function stripComment(line) {
|
|
33
|
+
return line.replace(/(^|\s)#.*$/, '');
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function parseJson(text) {
|
|
37
|
+
try { return JSON.parse(text); } catch (_) { return undefined; }
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function hasBin(pkg) {
|
|
41
|
+
if (!pkg || typeof pkg !== 'object') return false;
|
|
42
|
+
const b = pkg.bin;
|
|
43
|
+
if (typeof b === 'string') return b.trim() !== '';
|
|
44
|
+
return !!b && typeof b === 'object' && Object.keys(b).length > 0;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function rootBin(readFile) {
|
|
48
|
+
const text = readFile('package.json');
|
|
49
|
+
return text != null && hasBin(parseJson(text));
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function codeLines(text) {
|
|
53
|
+
return String(text || '').split('\n').map(stripComment);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function mentionsDistRef(text) {
|
|
57
|
+
return codeLines(text).some((l) => DIST_REF.test(l));
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function isReusable(text) {
|
|
61
|
+
return codeLines(text).some((l) => /^\s*workflow_call\s*:/.test(l) || /\bworkflow_call\b/.test(l) && /^\s*on\s*:/.test(l));
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* In-repo routes to dist refs: a workflow line `uses: ./.github/workflows/<f>` whose target
|
|
66
|
+
* pushes to refs/tags/dist/, or a non-reusable workflow that does so itself (inlined).
|
|
67
|
+
* A dist-refs copy that nothing calls is not a route.
|
|
68
|
+
*/
|
|
69
|
+
function distRefsCallers(workflows, readFile) {
|
|
70
|
+
const out = [];
|
|
71
|
+
for (const wf of workflows || []) {
|
|
72
|
+
const text = readFile(`.github/workflows/${wf}`);
|
|
73
|
+
if (!text) continue;
|
|
74
|
+
codeLines(text).forEach((line, i) => {
|
|
75
|
+
const m = line.match(LOCAL_USES);
|
|
76
|
+
if (!m) return;
|
|
77
|
+
if (mentionsDistRef(readFile(`.github/workflows/${m[1]}`))) out.push({ wf, line: i + 1, target: m[1] });
|
|
78
|
+
});
|
|
79
|
+
if (!isReusable(text) && mentionsDistRef(text)) out.push({ wf, line: null, target: wf });
|
|
80
|
+
}
|
|
81
|
+
return out;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** What each §6 row's route needs, and whether this repository has it. */
|
|
85
|
+
function evidence({ readFile, listDir, workflows }) {
|
|
86
|
+
const publishes = npmGuard.workflowPublishes(workflows, readFile).length > 0;
|
|
87
|
+
const ms = npmGuard.manifests(readFile, listDir).filter((m) => !m.unparsed && m.pkg && typeof m.pkg === 'object');
|
|
88
|
+
const publicBin = ms.some((m) => m.pkg.private !== true && hasBin(m.pkg));
|
|
89
|
+
const publicBinOptDeps = ms.some((m) => m.pkg.private !== true && hasBin(m.pkg)
|
|
90
|
+
&& m.pkg.optionalDependencies && typeof m.pkg.optionalDependencies === 'object'
|
|
91
|
+
&& Object.keys(m.pkg.optionalDependencies).length > 0);
|
|
92
|
+
const bin = rootBin(readFile);
|
|
93
|
+
const callers = distRefsCallers(workflows, readFile);
|
|
94
|
+
const missing = {
|
|
95
|
+
'js/public': [
|
|
96
|
+
...(publishes ? [] : ['no workflow step publishes to npm']),
|
|
97
|
+
...(publicBin ? [] : ['no non-private package.json has a bin']),
|
|
98
|
+
],
|
|
99
|
+
'js/private': bin ? [] : ['root package.json has no bin (the npx github: entry point)'],
|
|
100
|
+
'compiled/public': [
|
|
101
|
+
...(publishes ? [] : ['no workflow step publishes to npm']),
|
|
102
|
+
...(publicBinOptDeps ? [] : ['no non-private package.json has a bin and per-platform optionalDependencies']),
|
|
103
|
+
],
|
|
104
|
+
'compiled/private': [
|
|
105
|
+
...(bin ? [] : ['root package.json has no bin (the launcher, templates/npx-launcher.mjs)']),
|
|
106
|
+
...(callers.length ? [] : ['no workflow calls a dist-refs workflow (uses: ./.github/workflows/dist-refs.yml, templates/dist-refs.yml)']),
|
|
107
|
+
],
|
|
108
|
+
};
|
|
109
|
+
return { missing };
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
const RULE = 'every distributed tool installs with npx — public: an npm package; private: `npx github:<org>/<repo>#vX.Y.Z`, compiled binaries as dist refs (CONVENTIONS.md §6, Distribution, #469). A publish in a workflow outside this repository is not visible here';
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* @param distribution the raw declared value (undefined/null → not declared → [])
|
|
116
|
+
* @param visibility 'public' | 'private' | 'internal' | null (unknown)
|
|
117
|
+
* An invalid value is the caller's enum check, not reported here.
|
|
118
|
+
*/
|
|
119
|
+
function findings({ distribution, readFile, listDir, workflows, visibility }) {
|
|
120
|
+
if (distribution == null || !VALID_DISTRIBUTION.has(distribution)) return [];
|
|
121
|
+
const { missing } = evidence({ readFile, listDir, workflows });
|
|
122
|
+
const pub = missing[`${distribution}/public`];
|
|
123
|
+
const priv = missing[`${distribution}/private`];
|
|
124
|
+
if (visibility === 'public') {
|
|
125
|
+
if (!pub.length) return [];
|
|
126
|
+
return [{ level: 'warn', text: `distribution: ${distribution}, but no install route §6 recognises — public repository: ${pub.join('; ')} — ${RULE}` }];
|
|
127
|
+
}
|
|
128
|
+
if (visibility === 'private' || visibility === 'internal') {
|
|
129
|
+
if (!priv.length) return [];
|
|
130
|
+
return [{ level: 'warn', text: `distribution: ${distribution}, but no install route §6 recognises — ${visibility} repository: ${priv.join('; ')} — ${RULE}` }];
|
|
131
|
+
}
|
|
132
|
+
if (!pub.length || !priv.length) return [];
|
|
133
|
+
return [{
|
|
134
|
+
level: 'warn',
|
|
135
|
+
text: `distribution: ${distribution}, but no install route §6 recognises — repository visibility could not be read, and neither row's route was found (public: ${pub.join('; ')}; private: ${priv.join('; ')}) — ${RULE}`,
|
|
136
|
+
}];
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
module.exports = { VALID_DISTRIBUTION, rootBin, distRefsCallers, evidence, findings };
|