@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.9
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/LICENSE +21 -0
- package/README.md +310 -3
- package/README.vi.md +280 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13785 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +481 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
|
@@ -0,0 +1,740 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* Stamp + drift logic, shared by `audit/audit.mjs` (report) and `colab update` (report + refresh).
|
|
4
|
+
*
|
|
5
|
+
* Copy-and-own means nothing is pushed to an adopter: a copied artifact carries a STAMP naming
|
|
6
|
+
* the template and the handbook version it came from, and drift is discovered by comparing that
|
|
7
|
+
* stamp against the handbook's own git history. Both tools must read stamps identically — a
|
|
8
|
+
* second implementation that disagreed about what "behind" means is exactly the two-places-drift
|
|
9
|
+
* disease this handbook exists to kill, so the reading lives here once.
|
|
10
|
+
*
|
|
11
|
+
* CommonJS on purpose: `tools/colab` is CJS, `audit/audit.mjs` is ESM. CJS is the format both can
|
|
12
|
+
* consume (the audit pulls it in through `createRequire`); the reverse is not true from a
|
|
13
|
+
* synchronous CLI.
|
|
14
|
+
*
|
|
15
|
+
* Every function takes the handbook root explicitly rather than resolving it — the two callers
|
|
16
|
+
* locate the handbook differently (the audit honours COLAB_HANDBOOK; the CLI walks up from its
|
|
17
|
+
* own file), and a module that guessed would be wrong for one of them.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
const { execFileSync } = require('child_process');
|
|
21
|
+
const releaseTag = require('./release-tag.js');
|
|
22
|
+
|
|
23
|
+
// The artifact kinds that carry a stamp. Workflow copies are WHOLE-FILE copies, so a pristine one
|
|
24
|
+
// can be regenerated byte-for-byte. The CLAUDE block is a fragment pasted into a larger file whose
|
|
25
|
+
// placeholders the adopter fills in — see CLAUDE_BLOCK below.
|
|
26
|
+
const CLAUDE_BLOCK_TEMPLATE = 'templates/repo-CLAUDE-block.md';
|
|
27
|
+
|
|
28
|
+
// The FROZEN CLI copy: `install.sh --tools` copies `tools/colab` + `tools/lib/` into
|
|
29
|
+
// `<COLAB_HOME>/bin/` and writes the stamp beside it, so a long-lived process never resolves the
|
|
30
|
+
// CLI through a working tree. The symlink install (`~/.local/bin/colab`) is deliberately the
|
|
31
|
+
// opposite — a human session should follow whatever branch the handbook clone has checked out —
|
|
32
|
+
// but an always-on service must not change behaviour because somebody checked out an unrelated
|
|
33
|
+
// branch. Refreshing the frozen copy is therefore an act (re-run install.sh), never a side effect.
|
|
34
|
+
//
|
|
35
|
+
// The stamp is a SIDECAR file rather than a line prepended into the script: `colab` is executable
|
|
36
|
+
// with a shebang on line 1, and the sidecar keeps the copied bytes identical to the source.
|
|
37
|
+
// It uses the ordinary workflow stamp convention (`# colab-handbook: <name> @ <version>`) and is
|
|
38
|
+
// read with parseWorkflowStamp, so there is one stamp format on the machine, not two.
|
|
39
|
+
const FROZEN_STAMP_NAME = 'colab-bin';
|
|
40
|
+
const FROZEN_STAMP_FILE = 'STAMP';
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* The handbook version at/after which #144's authority-flip advisory activates: a `warn`,
|
|
44
|
+
* on a repo whose axis of record is a LEGACY `tier` read (no `exposure` declared), noting
|
|
45
|
+
* that `tier` is now read as legacy rather than authoritative. Dormant below this version,
|
|
46
|
+
* mirroring the `hb.untagged` precedent `compareStamp` already uses (deactivated while there
|
|
47
|
+
* is no real version line to compare against) — the re-keying itself is NOT gated by it (it
|
|
48
|
+
* is designed to be output-identical on every descriptor without `exposure` regardless of
|
|
49
|
+
* handbook version; only this one new warn is).
|
|
50
|
+
*
|
|
51
|
+
* No tag exists past the axis commits yet (#200, a human act, still pending) — the handbook
|
|
52
|
+
* is expected to cut a MINOR tag containing #144 next (keeping `v1.x`, so the fleet gets a
|
|
53
|
+
* clean baseline first), and only a LATER, separate major bump would ever reach this
|
|
54
|
+
* constant. Comparison uses `cmpSemver`, so a same-or-later `v2.x.y` also arms it.
|
|
55
|
+
*/
|
|
56
|
+
const AUTHORITY_FLIP_VERSION = 'v2.0.0';
|
|
57
|
+
// What the frozen copy is made of, as repo-relative paths — the same role `templateFiles()` plays
|
|
58
|
+
// for a template, and fed to the same `git log <stamp>..HEAD -- <paths>` question.
|
|
59
|
+
// Every path install.sh's freeze_cli COPIES belongs here: a source it copies but this list omits can
|
|
60
|
+
// change without ever marking a frozen copy behind. tools/package.json was exactly that gap (#341) —
|
|
61
|
+
// an `engines` bump shipped to no machine. tools/lib/install-sh.test.js holds the two lists together.
|
|
62
|
+
const FROZEN_SOURCES = ['tools/colab', 'tools/lib', 'tools/package.json'];
|
|
63
|
+
|
|
64
|
+
// ---------------------------------------------------------------------------
|
|
65
|
+
// git access to the handbook checkout
|
|
66
|
+
// ---------------------------------------------------------------------------
|
|
67
|
+
|
|
68
|
+
function gitIn(root, args) {
|
|
69
|
+
try {
|
|
70
|
+
return {
|
|
71
|
+
ok: true,
|
|
72
|
+
out: execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(),
|
|
73
|
+
};
|
|
74
|
+
} catch (_) {
|
|
75
|
+
return { ok: false, out: '' };
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** `version` of `<root>/package.json` when this root is a published package (not a git checkout), else null. */
|
|
80
|
+
function packageVersion(root) {
|
|
81
|
+
try {
|
|
82
|
+
const j = JSON.parse(require('fs').readFileSync(require('path').join(root, 'package.json'), 'utf8'));
|
|
83
|
+
return typeof j.version === 'string' && /^\d+\.\d+\.\d+$/.test(j.version) ? j.version : null;
|
|
84
|
+
} catch (_) {
|
|
85
|
+
return null;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** The npm name this CLI publishes under — must equal the root package.json's `name` (a test pins it). */
|
|
90
|
+
const PACKAGE_NAME = '@futurelastic/colab-handbook';
|
|
91
|
+
|
|
92
|
+
/** True when `root` is its own git checkout — the toplevel git finds IS `root`, not an enclosing repo. */
|
|
93
|
+
function ownsGit(root) {
|
|
94
|
+
const top = gitIn(root, ['rev-parse', '--show-toplevel']);
|
|
95
|
+
return top.ok && realPath(top.out) === realPath(require('path').resolve(root));
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* `{ root, version }` when `root` is THIS CLI installed from the npm registry, else null (#444).
|
|
100
|
+
*
|
|
101
|
+
* Three conditions, all required:
|
|
102
|
+
* - no git of its own (an enclosing repo does not count — see handbookInfo);
|
|
103
|
+
* - `<root>/package.json` names this package, so an unrelated package.json never qualifies;
|
|
104
|
+
* - `root` sits under a `node_modules/` directory. Without this, a handbook working tree that is
|
|
105
|
+
* file-synced to another machine with its `.git` deliberately left behind would pass the first
|
|
106
|
+
* two and be reported as a registry install. npx, `npm i` and `npm i -g` all install there.
|
|
107
|
+
*
|
|
108
|
+
* `version` is package.json's verbatim — a candidate's `1.12.0-rc.8` included. That is the point:
|
|
109
|
+
* this answers "which build is running", where handbookInfo answers "what may I stamp with", and a
|
|
110
|
+
* candidate is never the latter (#334) — so its stricter packageVersion is right for it, wrong here.
|
|
111
|
+
*/
|
|
112
|
+
function npmPackageInfo(root) {
|
|
113
|
+
const p = require('path');
|
|
114
|
+
if (!p.resolve(root).split(p.sep).includes('node_modules')) return null;
|
|
115
|
+
let j;
|
|
116
|
+
try {
|
|
117
|
+
j = JSON.parse(require('fs').readFileSync(p.join(root, 'package.json'), 'utf8'));
|
|
118
|
+
} catch (_) {
|
|
119
|
+
return null;
|
|
120
|
+
}
|
|
121
|
+
if (!j || j.name !== PACKAGE_NAME || typeof j.version !== 'string' || !j.version) return null;
|
|
122
|
+
if (ownsGit(root)) return null;
|
|
123
|
+
return { root, version: j.version };
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* The handbook's own identity: { root, hasGit, untagged, version }.
|
|
128
|
+
* Before the first tag exists the version is 'v0' and `untagged` is true, which DEACTIVATES stamp
|
|
129
|
+
* comparison in both callers — there is no real version line to compare against, and inventing one
|
|
130
|
+
* would mark every adopter stale against a version that never shipped.
|
|
131
|
+
*
|
|
132
|
+
* `git -C <root> rev-parse --show-toplevel` does not fail when `root` itself has no `.git` — it
|
|
133
|
+
* walks UP and answers about the nearest ENCLOSING repository. So a root that is not itself a repo
|
|
134
|
+
* still returns `ok`, and treating success alone as "hasGit: true" reports the wrong repo's tags
|
|
135
|
+
* with no error and no advisory (root is a subdirectory that legitimately has no `.git` of its own
|
|
136
|
+
* — e.g. working trees file-synced between machines while git metadata deliberately is not, nested
|
|
137
|
+
* inside a parent that IS a repo). The fix is the comparison this function was missing: the
|
|
138
|
+
* toplevel git actually found must equal `root` itself, not merely exist. realPath both sides —
|
|
139
|
+
* `--show-toplevel` resolves symlinks, so a symlinked root would otherwise never match its own
|
|
140
|
+
* unresolved spelling (same reasoning as `realPath` above, applied here for the same failure mode).
|
|
141
|
+
*/
|
|
142
|
+
function handbookInfo(root) {
|
|
143
|
+
const top = gitIn(root, ['rev-parse', '--show-toplevel']);
|
|
144
|
+
if (!top.ok || realPath(top.out) !== realPath(require('path').resolve(root))) {
|
|
145
|
+
// An npm install (#431) has no git of its own: the registry copy's version is its package.json,
|
|
146
|
+
// which the publish job stamps from the release tag. Without this a copy installed from the
|
|
147
|
+
// registry would stamp every adopter's files `v0`.
|
|
148
|
+
const pkgVersion = packageVersion(root);
|
|
149
|
+
if (pkgVersion) return { root, hasGit: false, untagged: false, version: `v${pkgVersion}` };
|
|
150
|
+
return { root, hasGit: false, untagged: true, version: 'v0' };
|
|
151
|
+
}
|
|
152
|
+
// Pre-release tags are not a version (#334): a candidate must never become what adopters are
|
|
153
|
+
// compared against or stamped with. Only candidates, no final yet, reads as untagged.
|
|
154
|
+
const tag = releaseTag.latestReleaseTag(root);
|
|
155
|
+
if (!tag) return { root, hasGit: true, untagged: true, version: 'v0' };
|
|
156
|
+
return { root, hasGit: true, untagged: false, version: tag };
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* What to stamp a frozen copy WITH: { version, tag, exact, untagged }.
|
|
161
|
+
*
|
|
162
|
+
* A frozen copy is bytes taken from a working tree, and when that tree is ahead of the last tag no
|
|
163
|
+
* version honestly describes it. Stamping the bare tag overstates what the copy contains — it
|
|
164
|
+
* silently claims to be a release it is newer than. So `version` is `git describe --tags` (pre-release
|
|
165
|
+
* tags excluded — release-tag.js, #334), which
|
|
166
|
+
* is the bare tag when HEAD sits exactly on one (`v1.6.1`, the common case, unchanged) and the long
|
|
167
|
+
* form when it does not (`v1.6.1-14-gc8436c6`).
|
|
168
|
+
*
|
|
169
|
+
* The long form is not a cosmetic label — it is chosen because it stays correct everywhere the
|
|
170
|
+
* stamp is already consumed, with no second format on the machine:
|
|
171
|
+
* - parseWorkflowStamp's version pattern accepts it;
|
|
172
|
+
* - cmpSemver reads it as its tag (trailing junk parses to 0), so it never trips the "stamp is
|
|
173
|
+
* NEWER than the handbook" branch against its own tag;
|
|
174
|
+
* - `git rev-parse` resolves it, so classifyFrozen can use it as a lower bound directly — which
|
|
175
|
+
* makes the comparison EXACT rather than merely honest: a copy frozen mid-cycle is measured
|
|
176
|
+
* from the commit it was actually taken from, so the next release marks it behind only for the
|
|
177
|
+
* commits it genuinely lacks.
|
|
178
|
+
*
|
|
179
|
+
* Dirty trees are deliberately NOT described (`--dirty` would produce a ref nothing can resolve,
|
|
180
|
+
* turning every such copy into `n-a` with misleading "fetch tags" advice). Uncommitted work in a
|
|
181
|
+
* frozen copy stays outside this model.
|
|
182
|
+
*/
|
|
183
|
+
function freezeVersion(root) {
|
|
184
|
+
const hb = handbookInfo(root);
|
|
185
|
+
if (hb.untagged || !hb.hasGit) return { version: 'v0', tag: 'v0', exact: false, untagged: true };
|
|
186
|
+
// Long form measured from the last FINAL tag (#334) — a tree sitting on `v1.3.0-rc.1` stamps
|
|
187
|
+
// `v1.2.0-N-g<sha>`, never the candidate.
|
|
188
|
+
const d = gitIn(root, releaseTag.describeArgs({ abbrev: null }));
|
|
189
|
+
const version = d.ok && d.out ? d.out : hb.version;
|
|
190
|
+
return { version, tag: hb.version, exact: version === hb.version, untagged: false };
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* The handbook's shared git directory — the one identity that survives worktrees. Every worktree
|
|
195
|
+
* of a repo reports the SAME `--git-common-dir`, while their working-tree paths all differ.
|
|
196
|
+
*/
|
|
197
|
+
function gitCommonDir(root) {
|
|
198
|
+
const r = gitIn(root, ['rev-parse', '--git-common-dir']);
|
|
199
|
+
if (!r.ok || !r.out) return null;
|
|
200
|
+
return realPath(require('path').resolve(root, r.out));
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* Resolve symlinks before comparing paths, falling back to the input when the path does not exist.
|
|
205
|
+
*
|
|
206
|
+
* Not optional pedantry: git answers `--git-common-dir` RELATIVELY from a main checkout (`.git`)
|
|
207
|
+
* but ABSOLUTELY, and already symlink-resolved, from a worktree. So the two sides of the comparison
|
|
208
|
+
* arrive in different forms, and any handbook checkout reached through a symlinked path (`/tmp` on
|
|
209
|
+
* macOS, a symlinked home, a network mount) produced two different strings for one directory —
|
|
210
|
+
* making the repo fail to recognise itself.
|
|
211
|
+
*/
|
|
212
|
+
function realPath(p) {
|
|
213
|
+
try { return require('fs').realpathSync(p); } catch (_) { return p; }
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Is `repoPath` the handbook itself? Both tools must answer this identically, so it is answered
|
|
218
|
+
* ONCE, here — the same reason stamp reading lives here.
|
|
219
|
+
*
|
|
220
|
+
* NOT a path-string comparison, and that is the whole point. `colab update` used to test
|
|
221
|
+
* `abs === handbookRoot`, which silently answers "no" whenever the CLI runs from a git WORKTREE of
|
|
222
|
+
* the handbook: the CLI locates its root by walking up from its own file (giving the worktree),
|
|
223
|
+
* while the fleet registry names the main checkout. Same repo, two spellings, and the handbook was
|
|
224
|
+
* audited as its own consumer — reported `unstamped`, with advice to stamp its own CLAUDE.md as a
|
|
225
|
+
* copy of a version of itself. Comparing git common dirs is immune to that: worktree, symlink or
|
|
226
|
+
* a differently-spelled path all resolve to one identity.
|
|
227
|
+
*
|
|
228
|
+
* Remote (owner/name) targets are out of scope: recognising "self" through the API would need the
|
|
229
|
+
* name match this deliberately avoids.
|
|
230
|
+
*/
|
|
231
|
+
function isHandbookItself(repoPath, handbookRoot) {
|
|
232
|
+
const { resolve } = require('path');
|
|
233
|
+
if (!repoPath || !handbookRoot) return false;
|
|
234
|
+
const root = realPath(resolve(repoPath));
|
|
235
|
+
if (root === realPath(resolve(handbookRoot))) return true;
|
|
236
|
+
const a = gitCommonDir(root);
|
|
237
|
+
const b = gitCommonDir(handbookRoot);
|
|
238
|
+
return a !== null && b !== null && a === b;
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/** Template stems present in the handbook (e.g. "ci-node", "ci-laravel", "release-tag"). */
|
|
242
|
+
function templateNames(root) {
|
|
243
|
+
const { readdirSync } = require('fs');
|
|
244
|
+
const { join } = require('path');
|
|
245
|
+
try {
|
|
246
|
+
return new Set(
|
|
247
|
+
readdirSync(join(root, 'templates'))
|
|
248
|
+
.filter((f) => /\.ya?ml$/.test(f))
|
|
249
|
+
.map((f) => f.replace(/\.ya?ml$/, '')),
|
|
250
|
+
);
|
|
251
|
+
} catch (_) {
|
|
252
|
+
return new Set();
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/** Both spellings a template file may use, as repo-relative paths for `git log`/`git show`. */
|
|
257
|
+
function templateFiles(name) {
|
|
258
|
+
return [`templates/${name}.yml`, `templates/${name}.yaml`];
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
// The trailer key a handbook editor writes on a commit to declare — at edit time, never
|
|
262
|
+
// inferred afterward — that a template change carries no rule content (#272). One key,
|
|
263
|
+
// one truthy spelling; keep this narrow so a reader never has to guess what counts.
|
|
264
|
+
const RULE_NEUTRAL_TRAILER = 'Rule-Neutral';
|
|
265
|
+
const RULE_NEUTRAL_TRUE = /^(yes|true)$/i;
|
|
266
|
+
|
|
267
|
+
/**
|
|
268
|
+
* Is every commit that touched `files` in `sinceRef..untilRef` marked with the
|
|
269
|
+
* Rule-Neutral trailer? Empty range (nothing changed) reads as false — callers only ask
|
|
270
|
+
* this after confirming `changed`, and "no commits" is not the same claim as "all
|
|
271
|
+
* commits declared neutral".
|
|
272
|
+
*
|
|
273
|
+
* Uses `\x1f`/`\x1e` as field/record separators, not the trailer text itself, because
|
|
274
|
+
* `%(trailers:valueonly)` renders empty for a commit with no trailer — a plain newline
|
|
275
|
+
* join cannot tell "no trailer" apart from "trailer, empty value" from the commit count.
|
|
276
|
+
*/
|
|
277
|
+
function allCommitsRuleNeutral(root, files, sinceRef, untilRef) {
|
|
278
|
+
const fmt = `%H\x1f%(trailers:key=${RULE_NEUTRAL_TRAILER},valueonly,separator=%x2C)\x1e`;
|
|
279
|
+
const r = gitIn(root, ['log', `--format=${fmt}`, `${sinceRef}..${untilRef}`, '--', ...files]);
|
|
280
|
+
if (!r.ok || !r.out) return false;
|
|
281
|
+
const records = r.out.split('\x1e').map((s) => s.trim()).filter(Boolean);
|
|
282
|
+
if (records.length === 0) return false;
|
|
283
|
+
return records.every((rec) => {
|
|
284
|
+
const value = rec.split('\x1f')[1] || '';
|
|
285
|
+
return RULE_NEUTRAL_TRUE.test(value.trim());
|
|
286
|
+
});
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* Did any of the given files change between the stamped version and `untilRef` (default HEAD)?
|
|
291
|
+
* Returns { verifiable, changed, ruleNeutral }. verifiable=false when either ref does not
|
|
292
|
+
* resolve in this checkout (a tag we do not have) — reported, never guessed. `ruleNeutral` is
|
|
293
|
+
* only ever true alongside `changed: true` — see `allCommitsRuleNeutral` above (#272): a
|
|
294
|
+
* template stays a hard fail unless EVERY commit since the stamp was deliberately declared
|
|
295
|
+
* rule-neutral by whoever wrote it, never by comparing before/after content here.
|
|
296
|
+
*
|
|
297
|
+
* This is the check that keeps releases quiet: comparing version STRINGS would mark every adopter
|
|
298
|
+
* stale on every handbook release, including releases that touched nothing they copied.
|
|
299
|
+
*
|
|
300
|
+
* `untilRef` exists because the two callers are asking about different UNITS. A template copy is
|
|
301
|
+
* compared against HEAD: the adopter refreshes from the working tree, so the working tree is the
|
|
302
|
+
* thing they can actually get. The frozen CLI copy is compared against the latest TAG — see
|
|
303
|
+
* classifyFrozen for why measuring it to HEAD made every maintainer's machine permanently stale.
|
|
304
|
+
*/
|
|
305
|
+
function templateChangedSince(root, files, sinceRef, untilRef = 'HEAD') {
|
|
306
|
+
const resolves = (ref) => gitIn(root, ['rev-parse', '--verify', '--quiet', ref + '^{commit}']).ok;
|
|
307
|
+
if (!resolves(sinceRef) || !resolves(untilRef)) return { verifiable: false, changed: false, ruleNeutral: false };
|
|
308
|
+
const log = gitIn(root, ['log', '--oneline', `${sinceRef}..${untilRef}`, '--', ...files]);
|
|
309
|
+
const changed = log.ok && log.out.length > 0;
|
|
310
|
+
const ruleNeutral = changed && allCommitsRuleNeutral(root, files, sinceRef, untilRef);
|
|
311
|
+
return { verifiable: true, changed, ruleNeutral };
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
/**
|
|
315
|
+
* A template's content AS OF a given ref (`git show <ref>:templates/<name>.yml`), or null.
|
|
316
|
+
* Divergence detection stands entirely on this: to know whether a copy was hand-edited you must
|
|
317
|
+
* compare it against what it was copied FROM, not against what the template has since become.
|
|
318
|
+
* Comparing against the current template would call every out-of-date copy "hand-edited".
|
|
319
|
+
*/
|
|
320
|
+
function templateAt(root, ref, name) {
|
|
321
|
+
for (const f of templateFiles(name)) {
|
|
322
|
+
const r = gitIn(root, ['show', `${ref}:${f}`]);
|
|
323
|
+
if (r.ok) return r.out;
|
|
324
|
+
}
|
|
325
|
+
return null;
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
// The descriptor axes that entered the model after the original tier/trunk/deploy/production/
|
|
329
|
+
// stack fields — each one is a heading in project.schema.md, added the commit it landed.
|
|
330
|
+
const AXES = ['room', 'exposure', 'writes', 'channels'];
|
|
331
|
+
|
|
332
|
+
/**
|
|
333
|
+
* Which of AXES did NOT yet exist in project.schema.md as of `ref` — i.e. which axes this
|
|
334
|
+
* repo's marker predates, if its CLAUDE stamp names `ref` as the handbook version it was last
|
|
335
|
+
* synced against. Reuses the same stamp-comparison shape as templateChangedSince/templateAt:
|
|
336
|
+
* read the schema doc's content AT THAT REF, never at HEAD, because "predates" is a question
|
|
337
|
+
* about what existed at adoption time, not about what the handbook has since become.
|
|
338
|
+
*
|
|
339
|
+
* `verifiable: false` — same posture as an unresolvable stamp elsewhere in this module — means
|
|
340
|
+
* the ref cannot be read at all (an unfetched tag, a version string that isn't a real ref). The
|
|
341
|
+
* caller must stay SILENT in that case, not guess; a repo whose stamp names a ref this checkout
|
|
342
|
+
* cannot resolve is exactly the "look, don't assume" case the rest of the fleet already treats
|
|
343
|
+
* as unknown rather than as broken.
|
|
344
|
+
*
|
|
345
|
+
* A ref that resolves but predates project.schema.md entirely (the file did not exist yet) is
|
|
346
|
+
* read as "every axis is missing" — `git show` fails per-heading-check below, which already
|
|
347
|
+
* degrades to "not found" correctly with no extra branch.
|
|
348
|
+
*/
|
|
349
|
+
function axesPredating(root, ref) {
|
|
350
|
+
const resolves = gitIn(root, ['rev-parse', '--verify', '--quiet', ref + '^{commit}']).ok;
|
|
351
|
+
if (!resolves) return { verifiable: false, axes: [] };
|
|
352
|
+
const schema = gitIn(root, ['show', `${ref}:project.schema.md`]);
|
|
353
|
+
const text = schema.ok ? schema.out : '';
|
|
354
|
+
const missing = AXES.filter((axis) => !new RegExp('^###\\s+`' + axis + '`', 'm').test(text));
|
|
355
|
+
return { verifiable: true, axes: missing };
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
// The ruling's own landed vocabulary (project.schema.md, "writes — optional", and
|
|
359
|
+
// CONVENTIONS.md, "Writes"), used as the boundary marker below rather than a hand-picked
|
|
360
|
+
// version number. Distinct from a structural heading (what AXES/axesPredating match) because
|
|
361
|
+
// the `writes` heading itself did not change — only what is written under it did.
|
|
362
|
+
const WRITES_VETO_MARKER = 'two-state VETO';
|
|
363
|
+
|
|
364
|
+
/**
|
|
365
|
+
* #239: did a repo's marker already tell it what ⚖ #233 changed about `writes:`? Same
|
|
366
|
+
* stamp-comparison shape as axesPredating one function above — read project.schema.md AS OF
|
|
367
|
+
* the repo's OWN stamped ref, never at HEAD, because this asks what a sync at THAT time could
|
|
368
|
+
* have told the repo, not what the handbook has since become.
|
|
369
|
+
*
|
|
370
|
+
* Deliberately gated on the ruling's own arrival (`WRITES_VETO_MARKER`'s presence at `ref`),
|
|
371
|
+
* not a version threshold: unlike `AUTHORITY_FLIP_VERSION` near the top of this file — which
|
|
372
|
+
* exists BECAUSE that advisory wanted to wait for a later, separate major bump — #239's own
|
|
373
|
+
* text says this must not be deferred past the very next tag that carries #237. Reading for
|
|
374
|
+
* the change's own landed text sidesteps having to invent a version number for a tag nobody
|
|
375
|
+
* has cut yet (who tags follows CONVENTIONS §6's release rung).
|
|
376
|
+
*
|
|
377
|
+
* `verifiable: false` on the same terms as axesPredating: an unresolvable ref means stay
|
|
378
|
+
* silent, never guess.
|
|
379
|
+
*/
|
|
380
|
+
function writesRulingKnownAt(root, ref) {
|
|
381
|
+
const resolves = gitIn(root, ['rev-parse', '--verify', '--quiet', ref + '^{commit}']).ok;
|
|
382
|
+
if (!resolves) return { verifiable: false, known: false };
|
|
383
|
+
const schema = gitIn(root, ['show', `${ref}:project.schema.md`]);
|
|
384
|
+
const text = schema.ok ? schema.out : '';
|
|
385
|
+
return { verifiable: true, known: text.includes(WRITES_VETO_MARKER) };
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
// ---------------------------------------------------------------------------
|
|
389
|
+
// stamps
|
|
390
|
+
// ---------------------------------------------------------------------------
|
|
391
|
+
|
|
392
|
+
/**
|
|
393
|
+
* Which comment syntax a stamp line should use, chosen by the copied file's language — not a
|
|
394
|
+
* single fixed spelling. `#` works for YAML and shell (the original, and still the default for
|
|
395
|
+
* backward compatibility). A `.mjs`/`.js` copy cannot use it: a bare `#` on any line but a `#!`
|
|
396
|
+
* shebang is a JS syntax error (outside a class body, where it means something else entirely), so
|
|
397
|
+
* a stamped JS file needs `//` or it would break the very file it is stamping (#252).
|
|
398
|
+
*/
|
|
399
|
+
function stampCommentPrefix(ext) {
|
|
400
|
+
return ext === 'mjs' || ext === 'js' ? '//' : '#';
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
/** The canonical workflow stamp line. `colab template` writes it; `colab update` rewrites it.
|
|
404
|
+
* `commentPrefix` defaults to `#` (unchanged behaviour for every existing *.yml caller) — pass
|
|
405
|
+
* the value from `stampCommentPrefix(ext)` for a non-YAML template. */
|
|
406
|
+
function stampLine(name, version, commentPrefix = '#') {
|
|
407
|
+
return `${commentPrefix} colab-handbook: ${name} @ ${version}\n`;
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
/**
|
|
411
|
+
* Insert a stamp line into a copied template's body.
|
|
412
|
+
*
|
|
413
|
+
* A `*.yml` copy has always taken the stamp prepended at the very top (line 1) — unchanged here.
|
|
414
|
+
* A copy that opens with a `#!` shebang cannot take that: prepending anything above line 1 breaks
|
|
415
|
+
* the shebang, which is exactly the gap `templates/README.md`'s Hooks section documents (#252).
|
|
416
|
+
* So a shebang file gets the stamp on its SECOND line instead — after the first `\n`, shebang
|
|
417
|
+
* intact on line 1 — and everything else is prepended as before.
|
|
418
|
+
*/
|
|
419
|
+
function insertStamp(body, line) {
|
|
420
|
+
if (body.startsWith('#!')) {
|
|
421
|
+
const nl = body.indexOf('\n');
|
|
422
|
+
if (nl === -1) return body + '\n' + line; // shebang with no trailing newline — still safe
|
|
423
|
+
return body.slice(0, nl + 1) + line + body.slice(nl + 1);
|
|
424
|
+
}
|
|
425
|
+
return line + body;
|
|
426
|
+
}
|
|
427
|
+
|
|
428
|
+
/** Workflow stamp: `# colab-handbook: <name> @ <version>` or, for a shebang/JS copy, the same
|
|
429
|
+
* shape with `//` (see stampCommentPrefix) — either prefix is accepted wherever it appears in the
|
|
430
|
+
* file, not just on line 1, so a second-line stamp reads back identically to a first-line one. */
|
|
431
|
+
function parseWorkflowStamp(text) {
|
|
432
|
+
if (!text) return null;
|
|
433
|
+
const m = text.match(/(?:#|\/\/)\s*colab-handbook:\s*([A-Za-z0-9._-]+)\s*@\s*(v?[0-9][0-9A-Za-z.\-+]*)/);
|
|
434
|
+
return m ? { name: m[1], version: m[2] } : null;
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
/** CLAUDE-block stamp: `<!-- colab-handbook @ <version> -->`. */
|
|
438
|
+
function parseClaudeStamp(text) {
|
|
439
|
+
if (!text) return null;
|
|
440
|
+
const m = text.match(/<!--\s*colab-handbook\s*@\s*(v?[0-9][0-9A-Za-z.\-+]*)\s*-->/);
|
|
441
|
+
return m ? { version: m[1] } : null;
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
/**
|
|
445
|
+
* Content fingerprints that mark a workflow as a handbook derivative even when someone renamed the
|
|
446
|
+
* file or dropped the stamp.
|
|
447
|
+
*
|
|
448
|
+
* THE ADMISSION TEST, and it is the whole design: *could this string appear in a file nobody copied
|
|
449
|
+
* from us?* If yes, it is not a fingerprint — it is the STACK'S VOCABULARY, and matching on it
|
|
450
|
+
* accuses every repo that happens to use that stack. We shipped two such strings and both misfired
|
|
451
|
+
* on real repos:
|
|
452
|
+
*
|
|
453
|
+
* - `wayfinder:generate` — a framework command, not our text. ANY workflow doing build-time
|
|
454
|
+
* codegen on that framework contains it, whatever its origin. It flagged three hand-written
|
|
455
|
+
* deploy workflows that had never been near a template.
|
|
456
|
+
* - `gitleaks/gitleaks/releases/download` — the upstream release URL. It identifies gitleaks,
|
|
457
|
+
* not us. Two hand-written CI files on this fleet contain it (including this handbook's own),
|
|
458
|
+
* copied from each other rather than from `templates/`.
|
|
459
|
+
*
|
|
460
|
+
* What survives is text WE COINED: the step names in our templates. No upstream tool, framework or
|
|
461
|
+
* generator emits "Resolve toolchain versions"; a file containing it was typed by us or copied from
|
|
462
|
+
* something that was. Each entry is therefore matched as a STEP NAME (`- name: <marker>`), not as a
|
|
463
|
+
* loose substring — so prose that merely mentions the phrase (a comment, a README, this file) does
|
|
464
|
+
* not trip it.
|
|
465
|
+
*
|
|
466
|
+
* `template` attributes the evidence, which is what lets the advice name a real template instead of
|
|
467
|
+
* a `<name>` placeholder the reader has to guess. `null` means the marker is shared by several
|
|
468
|
+
* templates: it still proves derivation, but not FROM WHICH — and the advice must then say so
|
|
469
|
+
* rather than pick one.
|
|
470
|
+
*
|
|
471
|
+
* Precise on purpose: better to miss an unstamped copy than to nag a file we cannot attribute.
|
|
472
|
+
*/
|
|
473
|
+
const WORKFLOW_FINGERPRINTS = [
|
|
474
|
+
// Header lines — verbatim template prose, and self-attributing.
|
|
475
|
+
{ marker: 'CI (Node) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-node' },
|
|
476
|
+
{ marker: 'CI (Laravel) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-laravel' },
|
|
477
|
+
{ marker: 'CI (Python) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-python' },
|
|
478
|
+
{ marker: 'Release (tag) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'release-tag' },
|
|
479
|
+
{ marker: 'Release (auto) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'release-auto' },
|
|
480
|
+
{ marker: 'Deploy (SSH/rsync to shared hosting) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'deploy-xserver' },
|
|
481
|
+
{ marker: 'Branch name — TEMPLATE. Copy me into your repo', kind: 'text', template: 'branch-name' },
|
|
482
|
+
// The header convention itself, unattributed: this catches a copy of any template ADDED LATER
|
|
483
|
+
// without anyone remembering to extend this list — provided the new template keeps the house
|
|
484
|
+
// header. A template that omits it is invisible here, which is worth knowing when writing one.
|
|
485
|
+
{ marker: '— TEMPLATE. Copy me into your repo', kind: 'text', template: null },
|
|
486
|
+
// Step names we coined, one per template.
|
|
487
|
+
{ marker: 'Resolve Node version', kind: 'step', template: 'ci-node' },
|
|
488
|
+
{ marker: 'Detect optional scripts', kind: 'step', template: 'ci-node' },
|
|
489
|
+
{ marker: 'Resolve toolchain versions', kind: 'step', template: 'ci-laravel' },
|
|
490
|
+
{ marker: 'Prepare throwaway env for build-time codegen (wayfinder)', kind: 'step', template: 'ci-laravel' },
|
|
491
|
+
{ marker: 'Resolve Python version', kind: 'step', template: 'ci-python' },
|
|
492
|
+
{ marker: 'Detect optional tooling', kind: 'step', template: 'ci-python' },
|
|
493
|
+
{ marker: 'Build grouped release summary', kind: 'step', template: 'release-tag' },
|
|
494
|
+
{ marker: 'Resolve tag and previous tag', kind: 'step', template: 'release-tag' },
|
|
495
|
+
// release-auto (#425): its two decision steps. The publish step's name is deliberately not a
|
|
496
|
+
// marker — "Publish GitHub Release" is release-tag's too, and would attribute a copy to both.
|
|
497
|
+
{ marker: 'Cut a candidate (colab release cut --auto)', kind: 'step', template: 'release-auto' },
|
|
498
|
+
{ marker: 'Finalize the newest clean candidate (colab release finalize --auto)', kind: 'step', template: 'release-auto' },
|
|
499
|
+
// deploy-xserver. These two were CHOSEN to differ from the step names in the hand-written deploy
|
|
500
|
+
// workflows this template was derived from ("Setup Node", "Smoke test (…)"), which is the same
|
|
501
|
+
// admission test as above read from the other end: those files must keep classifying as
|
|
502
|
+
// `unrelated`, and a marker they happen to contain would reclassify them as copies and invite an
|
|
503
|
+
// overwrite. Verified against all three before being added here.
|
|
504
|
+
{ marker: 'Resolve deploy toolchain', kind: 'step', template: 'deploy-xserver' },
|
|
505
|
+
{ marker: 'Verify the deployed site answers', kind: 'step', template: 'deploy-xserver' },
|
|
506
|
+
// branch-name (#348): its one step.
|
|
507
|
+
{ marker: 'Check branch name (CONVENTIONS §4)', kind: 'step', template: 'branch-name' },
|
|
508
|
+
// Shared by all three ci-* templates: proves derivation, cannot say from which. Note the exact
|
|
509
|
+
// parenthetical — hand-written installers on this fleet say "(pinned binary)", which is why the
|
|
510
|
+
// step NAME discriminates where the URL inside the step does not.
|
|
511
|
+
{ marker: 'Install gitleaks (pinned release binary)', kind: 'step', template: null },
|
|
512
|
+
];
|
|
513
|
+
|
|
514
|
+
function reEscape(s) {
|
|
515
|
+
return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
/** Does one fingerprint match? Step markers must appear as an actual `- name:` step, not as prose. */
|
|
519
|
+
function fingerprintHits(text, fp) {
|
|
520
|
+
if (fp.kind === 'text') return text.includes(fp.marker);
|
|
521
|
+
return new RegExp(`^\\s*-\\s*name:\\s*["']?${reEscape(fp.marker)}["']?\\s*$`, 'm').test(text);
|
|
522
|
+
}
|
|
523
|
+
|
|
524
|
+
/**
|
|
525
|
+
* Where did an UNSTAMPED workflow come from? Returns { origin, template, evidence }:
|
|
526
|
+
*
|
|
527
|
+
* derived content evidence says it is a handbook copy. `template` names it when the evidence
|
|
528
|
+
* attributes one, else null (derivation proven, source not).
|
|
529
|
+
* name-only the FILENAME matches a template but the content carries none of it. This is the
|
|
530
|
+
* dangerous case, and it is why a name match is no longer sufficient on its own: the
|
|
531
|
+
* moment `templates/<x>.yml` is added for some `x` that repos already have as their
|
|
532
|
+
* own hand-written workflow, a name-only match would advise `--force` and OVERWRITE
|
|
533
|
+
* a file that never came from us. A shared name is a coincidence, not a lineage.
|
|
534
|
+
* none neither. Somebody's own workflow — say nothing about it, ever.
|
|
535
|
+
*/
|
|
536
|
+
function workflowProvenance(text, stem, tmplNames) {
|
|
537
|
+
const hits = text ? WORKFLOW_FINGERPRINTS.filter((fp) => fingerprintHits(text, fp)) : [];
|
|
538
|
+
if (hits.length) {
|
|
539
|
+
const named = [...new Set(hits.map((h) => h.template).filter(Boolean))];
|
|
540
|
+
// One attributed template wins; several (or none) fall back to the filename, and only if that
|
|
541
|
+
// is a real template name. Never guess.
|
|
542
|
+
const template = named.length === 1 ? named[0] : (tmplNames.has(stem) ? stem : null);
|
|
543
|
+
// Cite only the most specific form of each match: the generic header rule always fires
|
|
544
|
+
// alongside the attributed one, and quoting both back at the reader reads like two findings.
|
|
545
|
+
const markers = hits.map((h) => h.marker);
|
|
546
|
+
const evidence = markers.filter((m) => !markers.some((o) => o !== m && o.includes(m)));
|
|
547
|
+
return { origin: 'derived', template, evidence };
|
|
548
|
+
}
|
|
549
|
+
if (tmplNames.has(stem)) return { origin: 'name-only', template: stem, evidence: [] };
|
|
550
|
+
return { origin: 'none', template: null, evidence: [] };
|
|
551
|
+
}
|
|
552
|
+
|
|
553
|
+
/**
|
|
554
|
+
* The single source of the advice both tools print, so the two can never drift apart on the one
|
|
555
|
+
* thing that matters here: whether to suggest asserting provenance.
|
|
556
|
+
* Returns null when there is nothing honest to say.
|
|
557
|
+
*/
|
|
558
|
+
function unstampedFinding(prov) {
|
|
559
|
+
if (prov.origin === 'derived') {
|
|
560
|
+
const why = `matched handbook template text (${prov.evidence.map((e) => `"${e}"`).join(', ')})`;
|
|
561
|
+
const how = prov.template
|
|
562
|
+
? `re-copy deliberately with \`colab template ${prov.template} --force\``
|
|
563
|
+
: 'identify which template it came from before re-copying — the evidence proves it is a copy but not of which template';
|
|
564
|
+
return {
|
|
565
|
+
state: 'unstamped',
|
|
566
|
+
reason: `${why} but carries no stamp — lineage unknown, so replacing it could destroy unknown edits; ${how}`,
|
|
567
|
+
};
|
|
568
|
+
}
|
|
569
|
+
if (prov.origin === 'name-only') {
|
|
570
|
+
return {
|
|
571
|
+
state: 'unrelated',
|
|
572
|
+
reason: `shares a name with templates/${prov.template} but contains none of that template's text — treated as this repo's own file. A matching NAME is not lineage: do NOT \`colab template ${prov.template} --force\`, it would overwrite work that never came from here.`,
|
|
573
|
+
};
|
|
574
|
+
}
|
|
575
|
+
return null;
|
|
576
|
+
}
|
|
577
|
+
|
|
578
|
+
/** Boolean view, kept for callers that only ask "is this ours?". A shared NAME alone is not. */
|
|
579
|
+
function looksLikeHandbookWorkflow(text, stem, tmplNames) {
|
|
580
|
+
return workflowProvenance(text, stem, tmplNames).origin === 'derived';
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
/** A CLAUDE.md that pasted the conventions block (this line is unique to the block template). */
|
|
584
|
+
function looksLikeHandbookClaude(text) {
|
|
585
|
+
return !!text && /follows the \[?colab-handbook/i.test(text);
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
// ---------------------------------------------------------------------------
|
|
589
|
+
// version comparison
|
|
590
|
+
// ---------------------------------------------------------------------------
|
|
591
|
+
|
|
592
|
+
/** Element-wise numeric compare; missing components count as 0. */
|
|
593
|
+
function cmpParts(a, b) {
|
|
594
|
+
const n = Math.max(a.length, b.length);
|
|
595
|
+
for (let i = 0; i < n; i++) {
|
|
596
|
+
const x = a[i] ?? 0;
|
|
597
|
+
const y = b[i] ?? 0;
|
|
598
|
+
if (x !== y) return x < y ? -1 : 1;
|
|
599
|
+
}
|
|
600
|
+
return 0;
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
/** vX.Y.Z comparison. Non-numeric junk sorts as 0 so a malformed stamp never throws. */
|
|
604
|
+
function cmpSemver(a, b) {
|
|
605
|
+
const norm = (s) => String(s).replace(/^v/i, '').split('.').map((n) => parseInt(n, 10) || 0);
|
|
606
|
+
return cmpParts(norm(a), norm(b));
|
|
607
|
+
}
|
|
608
|
+
|
|
609
|
+
// ---------------------------------------------------------------------------
|
|
610
|
+
// classification — the heart of `colab update`
|
|
611
|
+
// ---------------------------------------------------------------------------
|
|
612
|
+
|
|
613
|
+
// Compare tolerantly at the edges only: line endings and trailing blank lines are noise no adopter
|
|
614
|
+
// chose. Anything else counts as a real edit — under-reporting divergence here would let the tool
|
|
615
|
+
// overwrite someone's work, which is the one outcome it must never produce.
|
|
616
|
+
function sameContent(a, b) {
|
|
617
|
+
const norm = (s) => String(s).replace(/\r\n/g, '\n').replace(/\s+$/, '');
|
|
618
|
+
return norm(a) === norm(b);
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
/**
|
|
622
|
+
* Classify one stamped artifact. Returns { state, reason, from, to }.
|
|
623
|
+
*
|
|
624
|
+
* current the stamp is the handbook's version, OR the template genuinely has not changed
|
|
625
|
+
* since that stamp. Nothing to do.
|
|
626
|
+
* behind the stamp is older AND the template changed in between AND the local copy is
|
|
627
|
+
* still pristine as of its own stamp — so it can be regenerated safely.
|
|
628
|
+
* diverged the local copy does not match the template AS OF ITS OWN STAMP: someone edited it.
|
|
629
|
+
* Copy-and-own makes that legitimate (§7), so it is reported and never written.
|
|
630
|
+
* unstamped lineage unknown — handled by the caller, which can see it has no stamp at all.
|
|
631
|
+
* n-a cannot be assessed, with a stated reason (unknown template, a stamp from a version
|
|
632
|
+
* not in this checkout, a stamp newer than the handbook). Never silent.
|
|
633
|
+
*
|
|
634
|
+
* `comparable: false` (the CLAUDE block) means the artifact's pristine form cannot be reconstructed,
|
|
635
|
+
* so divergence is undecidable and the classification stops at current/behind.
|
|
636
|
+
*/
|
|
637
|
+
function classifyStamped(opts) {
|
|
638
|
+
const { root, hb, templateName, stampVersion, localText, comparable = true, tmplNames } = opts;
|
|
639
|
+
|
|
640
|
+
if (hb.untagged || !hb.hasGit) {
|
|
641
|
+
return { state: 'n-a', reason: 'handbook is untagged — stamp comparison inactive', from: stampVersion, to: hb.version };
|
|
642
|
+
}
|
|
643
|
+
if (templateName !== null && !tmplNames.has(templateName)) {
|
|
644
|
+
return { state: 'n-a', reason: `names unknown template "${templateName}" — not in the handbook's templates/`, from: stampVersion, to: hb.version };
|
|
645
|
+
}
|
|
646
|
+
if (cmpSemver(stampVersion, hb.version) > 0) {
|
|
647
|
+
return { state: 'n-a', reason: `stamp is NEWER than handbook ${hb.version} — clock skew or a hand-edited stamp`, from: stampVersion, to: hb.version };
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
const files = templateName === null ? [CLAUDE_BLOCK_TEMPLATE] : templateFiles(templateName);
|
|
651
|
+
const { verifiable, changed } = templateChangedSince(root, files, stampVersion);
|
|
652
|
+
if (!verifiable) {
|
|
653
|
+
return { state: 'n-a', reason: `stamped @ ${stampVersion}, a version not in this handbook checkout — fetch tags, or re-copy`, from: stampVersion, to: hb.version };
|
|
654
|
+
}
|
|
655
|
+
if (!changed) {
|
|
656
|
+
const why = cmpSemver(stampVersion, hb.version) === 0
|
|
657
|
+
? 'stamped at the current handbook version'
|
|
658
|
+
: `template unchanged since ${stampVersion}`;
|
|
659
|
+
return { state: 'current', reason: why, from: stampVersion, to: hb.version };
|
|
660
|
+
}
|
|
661
|
+
|
|
662
|
+
// The template moved. Whether we may refresh depends on whether the copy is still pristine.
|
|
663
|
+
if (!comparable) {
|
|
664
|
+
return { state: 'behind', reason: 'template changed since this stamp', from: stampVersion, to: hb.version };
|
|
665
|
+
}
|
|
666
|
+
const pristine = templateAt(root, stampVersion, templateName);
|
|
667
|
+
if (pristine === null) {
|
|
668
|
+
return { state: 'n-a', reason: `cannot read templates/${templateName} at ${stampVersion} — cannot tell pristine from edited`, from: stampVersion, to: hb.version };
|
|
669
|
+
}
|
|
670
|
+
const expected = stampLine(templateName, stampVersion) + pristine;
|
|
671
|
+
if (sameContent(localText, expected)) {
|
|
672
|
+
return { state: 'behind', reason: 'pristine copy, template changed since this stamp', from: stampVersion, to: hb.version };
|
|
673
|
+
}
|
|
674
|
+
return { state: 'diverged', reason: `hand-edited since it was copied @ ${stampVersion} — copy-and-own, review by hand`, from: stampVersion, to: hb.version };
|
|
675
|
+
}
|
|
676
|
+
|
|
677
|
+
/**
|
|
678
|
+
* Classify the frozen CLI copy: { state, reason, from, to }, with state one of
|
|
679
|
+
* current / behind / n-a.
|
|
680
|
+
*
|
|
681
|
+
* Answered by `git log`, not by comparing version strings — so a handbook release that touched no
|
|
682
|
+
* CLI code does not tell every machine its frozen copy is stale.
|
|
683
|
+
*
|
|
684
|
+
* The upper bound is the latest TAG, not HEAD, and that is the whole difference from a template
|
|
685
|
+
* copy. A stamp records a version, so measuring it to HEAD compares two different units: any
|
|
686
|
+
* unreleased commit under FROZEN_SOURCES marked every machine `behind` until the next tag. That
|
|
687
|
+
* re-coupled precisely what freezing decouples — `behind` was computed against the working tree,
|
|
688
|
+
* and its advertised remedy (`install.sh --tools`) copies FROM the working tree, so on a machine
|
|
689
|
+
* where the handbook is being developed the tool continuously advised services to adopt untagged
|
|
690
|
+
* code. It also misreported worst for maintainers (HEAD ahead of the tag is their resting state)
|
|
691
|
+
* and best for pure consumers, and `colab update`'s exit code rides on it, so anything scripting
|
|
692
|
+
* it flapped red for the whole window between a CLI commit and the next tag.
|
|
693
|
+
*
|
|
694
|
+
* `behind` therefore means: a RELEASED CLI change exists that this machine lacks. True regardless
|
|
695
|
+
* of what the local checkout happens to be doing.
|
|
696
|
+
*
|
|
697
|
+
* No `diverged` state, and that is the one real difference from a template copy. A template is
|
|
698
|
+
* copy-and-own: the adopter is entitled to edit it, so an edit must be detected and protected. The
|
|
699
|
+
* frozen CLI is a CACHE of this repo's own tool — nobody owns it, install.sh overwrites it wholesale
|
|
700
|
+
* on every run, and a hand-edited one is a machine to fix, not an edit to preserve.
|
|
701
|
+
*/
|
|
702
|
+
function classifyFrozen(opts) {
|
|
703
|
+
const { root, hb, stampVersion } = opts;
|
|
704
|
+
|
|
705
|
+
if (hb.untagged || !hb.hasGit) {
|
|
706
|
+
return { state: 'n-a', reason: 'handbook is untagged — stamp comparison inactive', from: stampVersion || null, to: hb.version };
|
|
707
|
+
}
|
|
708
|
+
if (!stampVersion) {
|
|
709
|
+
return { state: 'n-a', reason: `no ${FROZEN_STAMP_FILE} beside the frozen copy — lineage unknown, re-run install.sh --tools`, from: null, to: hb.version };
|
|
710
|
+
}
|
|
711
|
+
if (cmpSemver(stampVersion, hb.version) > 0) {
|
|
712
|
+
return { state: 'n-a', reason: `stamp is NEWER than handbook ${hb.version} — this machine froze from a checkout ahead of here`, from: stampVersion, to: hb.version };
|
|
713
|
+
}
|
|
714
|
+
|
|
715
|
+
const { verifiable, changed } = templateChangedSince(root, FROZEN_SOURCES, stampVersion, hb.version);
|
|
716
|
+
if (!verifiable) {
|
|
717
|
+
return { state: 'n-a', reason: `stamped @ ${stampVersion}, a version not in this handbook checkout — fetch tags, or re-freeze`, from: stampVersion, to: hb.version };
|
|
718
|
+
}
|
|
719
|
+
if (!changed) {
|
|
720
|
+
const why = cmpSemver(stampVersion, hb.version) === 0
|
|
721
|
+
? 'frozen at the current handbook version'
|
|
722
|
+
: `no released CLI change since ${stampVersion}`;
|
|
723
|
+
return { state: 'current', reason: why, from: stampVersion, to: hb.version };
|
|
724
|
+
}
|
|
725
|
+
return { state: 'behind', reason: `${hb.version} changed the CLI since ${stampVersion} — re-run install.sh --tools to re-freeze`, from: stampVersion, to: hb.version };
|
|
726
|
+
}
|
|
727
|
+
|
|
728
|
+
module.exports = {
|
|
729
|
+
CLAUDE_BLOCK_TEMPLATE, WORKFLOW_FINGERPRINTS,
|
|
730
|
+
FROZEN_STAMP_NAME, FROZEN_STAMP_FILE, FROZEN_SOURCES, classifyFrozen,
|
|
731
|
+
AUTHORITY_FLIP_VERSION,
|
|
732
|
+
gitIn, gitCommonDir, isHandbookItself,
|
|
733
|
+
handbookInfo, PACKAGE_NAME, npmPackageInfo, freezeVersion, templateNames, templateFiles, templateChangedSince, templateAt,
|
|
734
|
+
AXES, axesPredating,
|
|
735
|
+
WRITES_VETO_MARKER, writesRulingKnownAt,
|
|
736
|
+
stampLine, stampCommentPrefix, insertStamp, parseWorkflowStamp, parseClaudeStamp,
|
|
737
|
+
fingerprintHits, workflowProvenance, unstampedFinding,
|
|
738
|
+
looksLikeHandbookWorkflow, looksLikeHandbookClaude,
|
|
739
|
+
cmpParts, cmpSemver, sameContent, classifyStamped,
|
|
740
|
+
};
|