@futurelastic/colab-handbook 1.12.0-rc.38 → 1.12.0-rc.39
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/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
|
@@ -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 };
|