@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 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
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.38"
30
+ "version": "1.12.0-rc.40"
31
31
  }
@@ -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 };