@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.10

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.
Files changed (94) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +310 -3
  3. package/README.vi.md +280 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13790 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +259 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify.js +188 -0
  63. package/tools/lib/npm-publish-guard.js +242 -0
  64. package/tools/lib/orphan-worktree.js +127 -0
  65. package/tools/lib/owner-branch.js +182 -0
  66. package/tools/lib/place.js +782 -0
  67. package/tools/lib/ports.js +167 -0
  68. package/tools/lib/procs.js +185 -0
  69. package/tools/lib/readiness.js +240 -0
  70. package/tools/lib/records.js +185 -0
  71. package/tools/lib/refs-brake.js +95 -0
  72. package/tools/lib/release-channel.js +99 -0
  73. package/tools/lib/release-cut.js +822 -0
  74. package/tools/lib/release-finalize.js +521 -0
  75. package/tools/lib/release-policy.js +358 -0
  76. package/tools/lib/release-tag.js +225 -0
  77. package/tools/lib/ship-batch.js +277 -0
  78. package/tools/lib/ship-roles.js +71 -0
  79. package/tools/lib/ship-target-sync.js +181 -0
  80. package/tools/lib/shipguard.js +317 -0
  81. package/tools/lib/shipped-branch.js +56 -0
  82. package/tools/lib/solo.js +213 -0
  83. package/tools/lib/squash.js +515 -0
  84. package/tools/lib/stale-base.js +70 -0
  85. package/tools/lib/stamp.js +740 -0
  86. package/tools/lib/state.js +262 -0
  87. package/tools/lib/teardown.js +83 -0
  88. package/tools/lib/trust-humans.js +104 -0
  89. package/tools/lib/util.js +98 -0
  90. package/tools/lib/wake.js +188 -0
  91. package/tools/lib/workflow-triggers.js +273 -0
  92. package/tools/lib/writes-authority.js +237 -0
  93. package/tools/lib/yaml.js +101 -0
  94. package/bin/cli.js +0 -3
@@ -0,0 +1,120 @@
1
+ 'use strict';
2
+ /**
3
+ * Spent `group:<key>` label classification (#85) — the pure half.
4
+ *
5
+ * `colab ship`'s B4 teardown (#82) deletes a group label the moment the branch it shipped
6
+ * closed the group's last member. That is the right trigger for anything shipped from now
7
+ * on, and it is deliberately narrow: it can only ever consider labels carried by the issues
8
+ * THAT branch closed. Two populations therefore escape it permanently —
9
+ *
10
+ * 1. groups whose members all closed BEFORE the teardown feature existed, and
11
+ * 2. groups closed by any route other than `ship` (a hand merge, a bulk close, a transfer).
12
+ *
13
+ * Nothing revisits either, because the only trigger is a ship and these groups have no
14
+ * unshipped members left to trigger one. This module is the back-fill's decision layer: it
15
+ * takes a label and its membership and returns a verdict, with no I/O of its own so the
16
+ * rules can be pinned by tests rather than exercised against a live tracker.
17
+ *
18
+ * FOUR VERDICTS, and the boundaries between them are the whole point:
19
+ *
20
+ * spent >=1 member, none open. The label bound a real group and that group is
21
+ * finished. Safe to delete — this is exactly B4's condition, reached late.
22
+ * empty 0 members. Semantically spent (it binds nothing, and a label binds issues
23
+ * only at grouping time) but NOT safe to delete — see the note below.
24
+ * mid-flight >=1 open member. A group part-closed is the NORMAL state of a group being
25
+ * worked. Reporting it would be reporting rot that is not rot, and a doctor
26
+ * that cries wolf is a doctor people stop reading. Never reported.
27
+ * unknown membership could not be read. Never deleted, never counted clean — a failed
28
+ * lookup must not read as "no members" (the same contract ghIssueListByLabel
29
+ * states for its own null return).
30
+ *
31
+ * WHY `empty` IS REPORTED BUT NEVER AUTO-PRUNED. Two different histories produce a label
32
+ * with no members, and GitHub cannot tell them apart: (a) every member was deleted or
33
+ * transferred away — genuinely spent, and (b) a triage session created the label seconds ago
34
+ * and has not applied it to its members yet — genuinely LIVE. The GitHub labels API exposes
35
+ * no creation timestamp, so there is no age by which to separate them; a `--prune` that
36
+ * deleted case (b) would break a grouping while it was being formed, and the session doing
37
+ * the forming would get no error — its later `--add-label` would simply recreate a label
38
+ * stripped of the description that carried the group's rationale. Deleting is destructive and
39
+ * unrecoverable-in-kind; leaving it costs one line of doctor output. So `empty` is surfaced
40
+ * for a human and never acted on. This is the question #85 asked to have decided; this is the
41
+ * answer, and the asymmetry of the two error costs is the reason for it.
42
+ */
43
+
44
+ const { isGroupLabel, groupLabelNames } = require('./labels.js');
45
+
46
+ /**
47
+ * Is this member record open? Tolerant of shape (`gh` returns 'OPEN'/'CLOSED', but a caller
48
+ * may hand us a bare string) and DELIBERATELY conservative about anything it does not
49
+ * recognise: an unrecognised state counts as OPEN, which keeps the label alive.
50
+ *
51
+ * The bias is not arbitrary. The two ways to be wrong here are not symmetric — a false
52
+ * "open" leaves a spent label on the tracker until the next run (cosmetic, self-correcting),
53
+ * while a false "closed" is what makes a live group label deletable, and a deleted label
54
+ * cannot be restored with the members it bound. Fail toward keeping.
55
+ */
56
+ function isOpenMember(m) {
57
+ const raw = m && typeof m === 'object' ? m.state : m;
58
+ if (raw === undefined || raw === null) return true; // no state field → cannot prove closed
59
+ return String(raw).toUpperCase() !== 'CLOSED';
60
+ }
61
+
62
+ /**
63
+ * Classify ONE group label from its membership.
64
+ *
65
+ * @param {string} name the label, e.g. `group:import-fixes`
66
+ * @param {Array|null} members every issue carrying it, in ANY state, as returned by
67
+ * ghIssueListByLabel(repo, name, 'all', ['number','state']).
68
+ * null means the lookup FAILED — not that there are none.
69
+ * @returns {{name:string, verdict:string, total:number, open:number, members:number[]}}
70
+ */
71
+ function classifyGroupLabel(name, members) {
72
+ if (!isGroupLabel(name)) {
73
+ // The bare prefix ("group:" with no key) names no group; isGroupLabel already guards it.
74
+ // Anything else handed here is a caller bug, and answering 'unknown' keeps it undeletable.
75
+ return { name, verdict: 'unknown', total: 0, open: 0, members: [] };
76
+ }
77
+ if (members === null || members === undefined) {
78
+ return { name, verdict: 'unknown', total: 0, open: 0, members: [] };
79
+ }
80
+ const list = Array.isArray(members) ? members : [];
81
+ const open = list.filter(isOpenMember).length;
82
+ const nums = list
83
+ .map((m) => (m && typeof m === 'object' ? m.number : m))
84
+ .filter((n) => n !== undefined && n !== null);
85
+ if (list.length === 0) return { name, verdict: 'empty', total: 0, open: 0, members: [] };
86
+ if (open === 0) return { name, verdict: 'spent', total: list.length, open: 0, members: nums };
87
+ return { name, verdict: 'mid-flight', total: list.length, open, members: nums };
88
+ }
89
+
90
+ /**
91
+ * Classify every group label on a repo.
92
+ *
93
+ * @param {Array|null} allLabels every label name defined on the tracker (ghListLabels), or
94
+ * null on failure — which yields [] rather than a guess.
95
+ * @param {(name:string)=>Array|null} lookupMembers membership for one label. Injected so
96
+ * this stays pure and the tests need no network.
97
+ * @returns {Array} one verdict per group label, in the order the tracker listed them.
98
+ */
99
+ function classifyGroupLabels(allLabels, lookupMembers) {
100
+ if (!allLabels) return [];
101
+ return groupLabelNames(allLabels).map((name) => classifyGroupLabel(name, lookupMembers(name)));
102
+ }
103
+
104
+ /** The labels a `--prune` may delete: `spent` only. Never `empty`, never `unknown`. */
105
+ function deletableLabels(verdicts) {
106
+ return (verdicts || []).filter((v) => v && v.verdict === 'spent');
107
+ }
108
+
109
+ /**
110
+ * What a human should be shown: everything except `mid-flight`, which is a healthy state and
111
+ * must not be reported as rot. Keeps the reporting rule in one place so the CLI cannot drift
112
+ * from the tests.
113
+ */
114
+ function reportableLabels(verdicts) {
115
+ return (verdicts || []).filter((v) => v && v.verdict !== 'mid-flight');
116
+ }
117
+
118
+ module.exports = {
119
+ isOpenMember, classifyGroupLabel, classifyGroupLabels, deletableLabels, reportableLabels,
120
+ };
@@ -0,0 +1,193 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/hermetic.js — the hermetic second test run behind `colab gate-hermetic` (#403).
4
+ *
5
+ * The failure it exists for: a test read live state from its author's machine — the user's home
6
+ * config and a local fleet daemon. Green in every local wrap, red on every CI runner, and the red
7
+ * trunk then blocked the repo's sweep. The lesson was written down in prose; the same class came
8
+ * back two days later. So code-wrap A3 now runs the TEST STEP a second time with the machine
9
+ * taken away — a fresh empty HOME, daemon/dashboard/fleet URLs and every token unset, network
10
+ * off where the platform allows it — and the gate is green only when BOTH runs are.
11
+ *
12
+ * Everything here is pure (strings/objects in, strings/objects out) except `probeNetworkIsolation`,
13
+ * which takes an injectable `run` so tests never depend on the host's sandbox tooling.
14
+ */
15
+
16
+ // ---- the key: `live-env:` in .github/project.yml --------------------------------------------
17
+
18
+ /**
19
+ * `live-env:` → `{ declared, skip, valid, value, reason }`. Only `none` ("this repo's tests read
20
+ * no live environment") skips the hermetic run. Absent = run it. Any other value is invalid and
21
+ * read in the STRICTER direction — the run still happens — while the audit fails the value.
22
+ */
23
+ function parseLiveEnv(doc) {
24
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'live-env');
25
+ if (!has || doc['live-env'] === null || doc['live-env'] === undefined) {
26
+ return { declared: false, skip: false, valid: true, value: null, reason: 'live-env absent — the hermetic run is required' };
27
+ }
28
+ const v = doc['live-env'];
29
+ if (v === 'none') {
30
+ return { declared: true, skip: true, valid: true, value: 'none', reason: 'live-env: none declared — this repo states its tests read no live environment' };
31
+ }
32
+ return {
33
+ declared: true, skip: false, valid: false, value: v,
34
+ reason: `live-env is ${JSON.stringify(v)} — the only defined value is "none"; read as absent, so the hermetic run still happens`,
35
+ };
36
+ }
37
+
38
+ // ---- the environment ------------------------------------------------------------------------
39
+
40
+ // A variable is stripped when its NAME says it points at something outside the test process: a
41
+ // service address, a credential, a socket, a proxy — or a known agent/dashboard/daemon runtime.
42
+ // Deliberately by name shape, not by a closed list of our own services: the next daemon a test
43
+ // quietly depends on will not be on any list, but it will almost certainly be `SOMETHING_URL`.
44
+ const STRIP_SUFFIX = /(_URL|_URI|_ENDPOINT|_ADDR|_ADDRESS|_HOST|_PORT|_TOKEN|_SECRET|_KEY|_KEY_ID|_PASSWORD|_PASS|_CREDENTIALS|_SOCK|_SOCKET)$/i;
45
+ const STRIP_PREFIX = /^(COLAB_|CLAUDE|ANTHROPIC_|AWS_|GH_|GITHUB_TOKEN)/i;
46
+ const STRIP_SUBSTRING = /(DASHBOARD|DAEMON|FLEET)/i;
47
+ const STRIP_EXACT = new Set(['http_proxy', 'https_proxy', 'all_proxy', 'no_proxy', 'ftp_proxy', 'ZDOTDIR']);
48
+ // Stripped from BOTH runs: a leaked node test-runner context makes `node --test` skip every test
49
+ // and still exit 0 (the handbook's own CI documents this as #154) — a fail-open, not a live read.
50
+ const TEST_RUNNER_LEAKS = ['NODE_TEST_CONTEXT', 'NODE_TEST_WORKER_ID'];
51
+ // HOME-derived locations re-pointed INTO the fresh home, so nothing reaches the real one through them.
52
+ const XDG_DIRS = { XDG_CONFIG_HOME: '.config', XDG_DATA_HOME: '.local/share', XDG_CACHE_HOME: '.cache', XDG_STATE_HOME: '.local/state' };
53
+
54
+ function shouldStrip(name) {
55
+ if (name === 'HOME' || name === 'PATH') return false;
56
+ if (STRIP_EXACT.has(name) || STRIP_EXACT.has(name.toLowerCase())) return true;
57
+ return STRIP_SUFFIX.test(name) || STRIP_PREFIX.test(name) || STRIP_SUBSTRING.test(name);
58
+ }
59
+
60
+ /** The normal run's env: the caller's own, minus only the test-runner leaks. */
61
+ function normalEnv(env) {
62
+ const out = { ...env };
63
+ for (const k of TEST_RUNNER_LEAKS) delete out[k];
64
+ return out;
65
+ }
66
+
67
+ /**
68
+ * The hermetic run's env → `{ env, stripped, kept }`. `home` is the fresh directory the caller
69
+ * created. `keep` names variables the caller explicitly passes through anyway — every one is
70
+ * echoed in the verdict, so a pass-through is visible, never silent.
71
+ */
72
+ function hermeticEnv(env, home, keep = []) {
73
+ const keepSet = new Set(keep);
74
+ const out = {};
75
+ const stripped = [];
76
+ const kept = [];
77
+ for (const [k, v] of Object.entries(env)) {
78
+ if (TEST_RUNNER_LEAKS.includes(k)) continue;
79
+ if (keepSet.has(k)) { out[k] = v; if (shouldStrip(k)) kept.push(k); continue; }
80
+ if (k in XDG_DIRS) continue; // re-pointed below
81
+ if (shouldStrip(k)) { stripped.push(k); continue; }
82
+ out[k] = v;
83
+ }
84
+ out.HOME = home;
85
+ for (const [k, rel] of Object.entries(XDG_DIRS)) if (!keepSet.has(k)) out[k] = `${home}/${rel}`;
86
+ return { env: out, stripped: stripped.sort(), kept: kept.sort() };
87
+ }
88
+
89
+ // ---- the network ----------------------------------------------------------------------------
90
+
91
+ // macOS: deny every outbound IP connection except loopback. Loopback stays open on purpose — a
92
+ // suite that starts its own server on 127.0.0.1 and talks to it is hermetic, and blocking it would
93
+ // report a live-environment dependency that is not one. The cost is stated in the verdict line:
94
+ // a test with a HARD-CODED loopback daemon URL is not caught by the network half; it is caught
95
+ // only when the URL arrives through HOME or an env var, which is the shape measured so far.
96
+ //
97
+ // A sandboxed process may not exec a setuid binary, and on macOS `/bin/ps` (and `top`) IS setuid —
98
+ // so a suite that proves process ancestry through `ps` went red under the sandbox for a reason that
99
+ // has nothing to do with the network or the home directory (measured on this repo's own suite:
100
+ // three ancestry-anchor tests). Those two read the process table and nothing else, so they are let
101
+ // out of the sandbox by exact path; every other setuid binary stays refused.
102
+ const DARWIN_PROFILE = '(version 1)(allow default)(deny network-outbound (remote ip))(allow network-outbound (remote ip "localhost:*"))'
103
+ + '(allow process-exec (literal "/bin/ps") (with no-sandbox))(allow process-exec (literal "/usr/bin/top") (with no-sandbox))';
104
+ // Linux: a fresh user+network namespace has only a DOWN loopback. Bring it up, then exec the
105
+ // command; the probe below refuses isolation when lo cannot come up, for the same reason as above.
106
+ const LINUX_WRAPPER = 'ip link set lo up && exec "$@"';
107
+
108
+ /**
109
+ * Decide how (and whether) the hermetic run is cut off from the network. `run(cmd, args)` returns
110
+ * `{ status }` and is injected, so the decision is testable without the host's tooling.
111
+ * → `{ isolated, prefix: [argv...], note }` — `note` is printed in the verdict, always.
112
+ */
113
+ function probeNetworkIsolation({ platform, run, mode = 'auto' }) {
114
+ if (mode === 'on') return { isolated: false, prefix: [], note: 'network: left on (--net on)' };
115
+ if (platform === 'darwin') {
116
+ const p = run('/usr/bin/sandbox-exec', ['-p', DARWIN_PROFILE, '/usr/bin/true']);
117
+ if (p && p.status === 0) {
118
+ return { isolated: true, prefix: ['/usr/bin/sandbox-exec', '-p', DARWIN_PROFILE], note: 'network: off via sandbox-exec (outbound IP denied, loopback allowed)' };
119
+ }
120
+ return { isolated: false, prefix: [], note: 'network: NOT isolated — sandbox-exec unavailable or refused here (already sandboxed?); HOME + env strip still applied' };
121
+ }
122
+ if (platform === 'linux') {
123
+ const p = run('unshare', ['--user', '--map-root-user', '--net', 'sh', '-c', LINUX_WRAPPER, 'sh', 'true']);
124
+ if (p && p.status === 0) {
125
+ return { isolated: true, prefix: ['unshare', '--user', '--map-root-user', '--net', 'sh', '-c', LINUX_WRAPPER, 'sh'], note: 'network: off via unshare --net (fresh namespace, loopback up)' };
126
+ }
127
+ return { isolated: false, prefix: [], note: 'network: NOT isolated — unprivileged network namespaces unavailable here (or no `ip` to raise loopback); HOME + env strip still applied' };
128
+ }
129
+ return { isolated: false, prefix: [], note: `network: NOT isolated — no sandbox known for platform "${platform}"; HOME + env strip still applied` };
130
+ }
131
+
132
+ // ---- reading the output ---------------------------------------------------------------------
133
+
134
+ // One line format per common runner — the names are what the verdict must carry, not the transcript.
135
+ const FAILURE_PATTERNS = [
136
+ /^\s*not ok \d+ - (.+?)(?:\s+#\s.*)?$/, // TAP (node --test --test-reporter=tap, prove, …)
137
+ /^\s*✖ (.+?)(?: \(\d[\d.]*m?s\))?$/, // node --test spec reporter
138
+ /^\s*(?:FAIL|✕|×)\s+(.+)$/, // jest / vitest
139
+ /^FAILED (\S+)/, // pytest -ra summary
140
+ /^\d+\) (\S+::\S+)/, // phpunit
141
+ /^--- FAIL: (\S+)/, // go test
142
+ ];
143
+
144
+ /** Failing test names from a run's combined output, de-duplicated, capped at `max`. */
145
+ function parseFailures(output, max = 20) {
146
+ const seen = new Set();
147
+ const names = [];
148
+ for (const line of String(output || '').split('\n')) {
149
+ for (const re of FAILURE_PATTERNS) {
150
+ const m = re.exec(line);
151
+ if (m) {
152
+ const n = m[1].trim();
153
+ // node's spec reporter repeats every failure in a trailing summary; TAP nests parents.
154
+ if (n && !seen.has(n) && !/^failing tests:?$/i.test(n)) { seen.add(n); names.push(n); }
155
+ break;
156
+ }
157
+ }
158
+ if (names.length >= max) break;
159
+ }
160
+ return names;
161
+ }
162
+
163
+ /** Last `n` non-empty lines — the fallback when no runner pattern named a failure. */
164
+ function tail(output, n = 15) {
165
+ return String(output || '').split('\n').filter((l) => l.trim() !== '').slice(-n);
166
+ }
167
+
168
+ // ---- the verdict ----------------------------------------------------------------------------
169
+
170
+ /**
171
+ * → `'green' | 'red' | 'live-env' | 'skipped'`.
172
+ * skipped — `live-env: none` declared; the normal run alone decides (and must still be green)
173
+ * red — the NORMAL run is red: an ordinary failing gate, hermetic run not attempted
174
+ * live-env — normal green, hermetic red: the tests pass only with this machine's environment
175
+ * green — both green
176
+ */
177
+ function classify({ skipped, normalOk, hermeticOk }) {
178
+ if (!normalOk) return 'red';
179
+ if (skipped) return 'skipped';
180
+ return hermeticOk ? 'green' : 'live-env';
181
+ }
182
+
183
+ const VERDICT_TEXT = {
184
+ green: 'both runs passed',
185
+ skipped: 'counts as green — hermetic run skipped because trunk declares live-env: none',
186
+ red: 'the normal test run fails; fix that first — the hermetic run was not attempted',
187
+ 'live-env': 'live-environment dependency: green on this machine, red with the machine taken away. It will be red on CI. Not green.',
188
+ };
189
+
190
+ module.exports = {
191
+ parseLiveEnv, shouldStrip, normalEnv, hermeticEnv, probeNetworkIsolation, parseFailures, tail,
192
+ classify, VERDICT_TEXT, DARWIN_PROFILE, LINUX_WRAPPER, TEST_RUNNER_LEAKS,
193
+ };
@@ -0,0 +1,187 @@
1
+ 'use strict';
2
+ /**
3
+ * The identity vocabulary: where it comes from, how it parses, how a string is matched
4
+ * against it, and how a match is reported without republishing what it matched.
5
+ *
6
+ * WHY THIS MODULE EXISTS SEPARATELY FROM THE HOOK. #228 has two scanners, and they cannot be
7
+ * one program. The pre-commit scan (`templates/pre-commit-identity`) is a template: it is
8
+ * copied into repos that have no Node, no `tools/lib/`, and no relationship to this checkout
9
+ * beyond a file somebody once copied — so it must be self-contained POSIX `sh`, exactly like
10
+ * `templates/pre-push-guard`. The metadata scan runs inside `audit/audit.mjs`, which sweeps
11
+ * many repos across owners and already speaks `gh`. Two runtimes, forced by the delivery
12
+ * model, not by preference.
13
+ *
14
+ * This repo's standing objection to two implementations of one rule is answered the only
15
+ * honest way available: the SEMANTICS live here, and `tools/lib/identity.test.js` runs a
16
+ * conformance table through BOTH — the shell script in file mode and the functions below —
17
+ * asserting they reach the same verdict on the same vocabulary. If a future session changes
18
+ * a matching rule in one, that test fails until the other moves too.
19
+ *
20
+ * ⚠ Nothing here ever holds a real vocabulary. Every function takes one by path or by text
21
+ * supplied by the caller; a list of the strings an organisation considers sensitive is a
22
+ * precise index of what to look for, so it lives outside every repo (CONVENTIONS.md §9).
23
+ *
24
+ * CommonJS, and in tools/lib/ rather than audit/, for the reason every shared reading in
25
+ * this directory carries: `install.sh` freezes `tools/colab` + `tools/lib/` and nothing under
26
+ * `audit/`, and the audit consumes CJS through `createRequire`.
27
+ */
28
+
29
+ const fs = require('fs');
30
+ const path = require('path');
31
+ const os = require('os');
32
+
33
+ /** A term shorter than this matches nearly everything; it is a mistake, not a term. */
34
+ const MIN_TERM_LENGTH = 3;
35
+
36
+ /** The machine-wide default file name, alongside the (equally private) fleet registry. */
37
+ const DEFAULT_VOCABULARY_NAME = 'identity-vocabulary';
38
+
39
+ /**
40
+ * Where the vocabulary comes from, first hit wins:
41
+ * 1. COLAB_IDENTITY_VOCAB explicit, per invocation
42
+ * 2. git config colab.identityVocabulary explicit, per clone — caller supplies the
43
+ * value, since only a single-repo caller has
44
+ * one repo to read it from. The audit sweeps
45
+ * many repos at once and passes null here on
46
+ * purpose: a per-repo setting cannot answer a
47
+ * fleet-wide question, and silently using the
48
+ * first repo's would be worse than not asking.
49
+ * 3. ${COLAB_HOME:-~/.colab}/identity-vocabulary the machine-wide default
50
+ *
51
+ * Returns { path, source, explicit }. `explicit` drives the fail direction: an explicitly
52
+ * configured vocabulary that cannot be read is a check that was configured and did not run
53
+ * (refuse), while an absent default is a machine that has none configured (say so, carry on).
54
+ * Never touches the filesystem — resolution and existence are separate questions.
55
+ */
56
+ function resolveVocabularyPath({ env = process.env, gitConfig = null, home = os.homedir() } = {}) {
57
+ const fromEnv = (env.COLAB_IDENTITY_VOCAB || '').trim();
58
+ if (fromEnv) return { path: expandTilde(fromEnv, home), source: 'COLAB_IDENTITY_VOCAB', explicit: true };
59
+
60
+ const fromGit = (gitConfig || '').trim();
61
+ if (fromGit) return { path: expandTilde(fromGit, home), source: 'git config colab.identityVocabulary', explicit: true };
62
+
63
+ const colabHome = (env.COLAB_HOME || '').trim() || path.join(home, '.colab');
64
+ return { path: path.join(colabHome, DEFAULT_VOCABULARY_NAME), source: 'default', explicit: false };
65
+ }
66
+
67
+ // `~` is not expanded inside an environment variable or a git config value.
68
+ function expandTilde(p, home) {
69
+ if (p === '~') return home;
70
+ if (p.startsWith('~/')) return path.join(home, p.slice(2));
71
+ return p;
72
+ }
73
+
74
+ /**
75
+ * Parse vocabulary text into { terms, problems }.
76
+ *
77
+ * One term per line. Surrounding whitespace is ignored. A line whose first non-space
78
+ * character is `#` is a comment, and so is a blank line — comments are WHOLE-LINE only, so a
79
+ * `#` inside a term is part of the term. A leading `re:` marks an extended regular
80
+ * expression; anything else is a fixed string.
81
+ *
82
+ * `entry` is the 1-based LINE NUMBER in the operator's file, not an index into `terms`:
83
+ * every message about a term names it that way, and the operator owns that file, so a line
84
+ * number is the one identifier that is both actionable for them and meaningless to anyone
85
+ * reading a log over their shoulder.
86
+ *
87
+ * A problem is not a term that failed to match — it is a term that cannot be applied at all
88
+ * (too short, or an invalid regex). Callers must treat problems as "this check did not run".
89
+ */
90
+ function parseVocabulary(text) {
91
+ const terms = [];
92
+ const problems = [];
93
+ const lines = String(text == null ? '' : text).split('\n');
94
+
95
+ lines.forEach((raw, i) => {
96
+ const entry = i + 1;
97
+ let line = raw.replace(/\r$/, '').trim();
98
+ if (line === '' || line.startsWith('#')) return;
99
+
100
+ let kind = 'fixed';
101
+ if (line.slice(0, 3) === 're:') {
102
+ kind = 'regex';
103
+ line = line.slice(3).replace(/^[ \t]+/, '');
104
+ }
105
+ if (line === '') return;
106
+ line = line.replace(/\t/g, ' '); // tab separates the fields of the hook's own record format
107
+
108
+ if (line.length < MIN_TERM_LENGTH) {
109
+ problems.push({ entry, message: `entry ${entry} is only ${line.length} character(s) — too short to be a term (minimum ${MIN_TERM_LENGTH})` });
110
+ return;
111
+ }
112
+ if (kind === 'regex') {
113
+ try {
114
+ // Lower-cased, matched against a lower-cased subject — the same shape the shell
115
+ // scanner uses (awk has no case-insensitive flag, so both sides are folded instead).
116
+ new RegExp(line.toLowerCase());
117
+ } catch (_) {
118
+ problems.push({ entry, message: `entry ${entry} is not a valid regular expression` });
119
+ return;
120
+ }
121
+ }
122
+ terms.push({ entry, kind, value: line, chars: line.length });
123
+ });
124
+
125
+ return { terms, problems };
126
+ }
127
+
128
+ /** Read + parse a vocabulary file. Returns null when the file cannot be read at all. */
129
+ function loadVocabulary(file) {
130
+ let text;
131
+ try {
132
+ text = fs.readFileSync(file, 'utf8');
133
+ } catch (_) {
134
+ return null;
135
+ }
136
+ return parseVocabulary(text);
137
+ }
138
+
139
+ /**
140
+ * Match `records` — [{ location, text }] — against `terms`. Case-insensitive and by
141
+ * SUBSTRING for a fixed term, deliberately: a hostname or a handle appears inside URLs,
142
+ * paths and identifiers with no word boundary near it, and over-blocking has a one-command
143
+ * override while under-blocking has none.
144
+ *
145
+ * Returns [{ entry, kind, chars, location, value }] — `value` is carried so a caller that has
146
+ * been asked to unredact can, and so that nothing else has to go back to the vocabulary.
147
+ */
148
+ function scan(records, terms) {
149
+ const hits = [];
150
+ for (const rec of records) {
151
+ const text = String(rec.text == null ? '' : rec.text).toLowerCase();
152
+ if (!text) continue;
153
+ for (const t of terms) {
154
+ const matched = t.kind === 'regex'
155
+ ? new RegExp(t.value.toLowerCase()).test(text)
156
+ : text.includes(t.value.toLowerCase());
157
+ if (matched) hits.push({ entry: t.entry, kind: t.kind, chars: t.chars, location: rec.location, value: t.value });
158
+ }
159
+ }
160
+ // By entry, then by location — stable output for a report that a human diffs between runs.
161
+ hits.sort((a, b) => (a.entry - b.entry) || String(a.location).localeCompare(String(b.location)));
162
+ return hits;
163
+ }
164
+
165
+ /**
166
+ * One line about a hit, REDACTED unless explicitly told otherwise.
167
+ *
168
+ * The matched text is the thing that must not be published; a report, a terminal and a CI log
169
+ * are all places it would then live, and the audit's --json output is routinely pasted
170
+ * elsewhere. The entry number plus the length is enough for the person who owns the
171
+ * vocabulary and useless to anybody else.
172
+ */
173
+ function describeHit(hit, { show = false } = {}) {
174
+ return show
175
+ ? `${hit.location} — vocabulary entry ${hit.entry}: ${hit.value}`
176
+ : `${hit.location} — vocabulary entry ${hit.entry} (${hit.chars} chars, redacted)`;
177
+ }
178
+
179
+ module.exports = {
180
+ MIN_TERM_LENGTH,
181
+ DEFAULT_VOCABULARY_NAME,
182
+ resolveVocabularyPath,
183
+ parseVocabulary,
184
+ loadVocabulary,
185
+ scan,
186
+ describeHit,
187
+ };