@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.
- 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 +13790 -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 +521 -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,156 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* #345 — is a change DOCUMENTATION ONLY? The one mechanical input to the docs-only exception to
|
|
4
|
+
* `colab ship`'s autonomy gate (CONVENTIONS.md §2, "Autonomy — the docs-only exception").
|
|
5
|
+
*
|
|
6
|
+
* On a repo that does not declare `autonomy: auto-trunk`, an agent may still complete Phase B for a
|
|
7
|
+
* change this module classifies docs-only. The judgement is COMPUTED FROM GIT, never asserted by the
|
|
8
|
+
* caller. Nothing here takes a list, a flag, an env var or a project.yml field. The allowlist and the
|
|
9
|
+
* exclusions below are constants, so widening them is a handbook change reviewed in a commit.
|
|
10
|
+
*
|
|
11
|
+
* Every doubt resolves to "not docs-only": an empty diff, a git read that failed, a binary, a
|
|
12
|
+
* symlink, a submodule pointer. A false "no" costs a human click. A false "yes" merges code nobody
|
|
13
|
+
* approved.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
/** Extensions that count as documentation. Compared exactly (`README.MD` does not match). */
|
|
17
|
+
const DOC_EXTENSIONS = Object.freeze(['.md', '.mdx', '.txt']);
|
|
18
|
+
/** A path under this top-level directory counts as documentation whatever its extension. */
|
|
19
|
+
const DOCS_DIR = 'docs/';
|
|
20
|
+
/** Rules and agent instructions: never documentation, at any depth, even though they are `.md`. */
|
|
21
|
+
const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
|
|
22
|
+
/** Config directories: nothing under them is documentation, at any depth. */
|
|
23
|
+
const NEVER_DIRS = Object.freeze(['.claude', '.github', '.githooks']);
|
|
24
|
+
|
|
25
|
+
const MODE_SYMLINK = '120000';
|
|
26
|
+
const MODE_GITLINK = '160000';
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Classify ONE path by name alone. Returns `null` when the path is documentation, else the reason it
|
|
30
|
+
* is not.
|
|
31
|
+
*/
|
|
32
|
+
function pathReason(p) {
|
|
33
|
+
const segs = String(p).split('/');
|
|
34
|
+
const base = segs[segs.length - 1];
|
|
35
|
+
if (NEVER_BASENAMES.includes(base)) return `${base} is agent rules, not documentation`;
|
|
36
|
+
const dir = segs.slice(0, -1).find((s) => NEVER_DIRS.includes(s));
|
|
37
|
+
if (dir) return `under ${dir}/ (config)`;
|
|
38
|
+
if (String(p).startsWith(DOCS_DIR)) return null;
|
|
39
|
+
const dot = base.lastIndexOf('.');
|
|
40
|
+
const ext = dot > 0 ? base.slice(dot) : '';
|
|
41
|
+
if (DOC_EXTENSIONS.includes(ext)) return null;
|
|
42
|
+
return `not ${DOC_EXTENSIONS.join('/')} and not under ${DOCS_DIR}`;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Classify a set of changed entries. `entries`: `[{ path, oldMode, newMode, binary }]`, one per path
|
|
47
|
+
* per side. A rename arrives as a deletion plus an addition, so both names are judged.
|
|
48
|
+
*
|
|
49
|
+
* Returns `{ docsOnly, files, offenders: [{ path, reason }], reason }`. `files` counts distinct paths.
|
|
50
|
+
* `reason` is one line for a human, set on both outcomes.
|
|
51
|
+
*/
|
|
52
|
+
function classify(entries) {
|
|
53
|
+
const paths = new Map();
|
|
54
|
+
for (const e of entries || []) {
|
|
55
|
+
const why = [];
|
|
56
|
+
const nameWhy = pathReason(e.path);
|
|
57
|
+
if (nameWhy) why.push(nameWhy);
|
|
58
|
+
if (e.oldMode === MODE_SYMLINK || e.newMode === MODE_SYMLINK) why.push('symlink change');
|
|
59
|
+
if (e.oldMode === MODE_GITLINK || e.newMode === MODE_GITLINK) why.push('submodule change');
|
|
60
|
+
if (e.binary) why.push('binary change');
|
|
61
|
+
const prev = paths.get(e.path) || [];
|
|
62
|
+
paths.set(e.path, [...new Set([...prev, ...why])]);
|
|
63
|
+
}
|
|
64
|
+
const files = paths.size;
|
|
65
|
+
if (files === 0) return { docsOnly: false, files: 0, offenders: [], reason: 'empty diff — nothing to call documentation' };
|
|
66
|
+
const offenders = [...paths.entries()].filter(([, why]) => why.length)
|
|
67
|
+
.map(([p, why]) => ({ path: p, reason: why.join(', ') }));
|
|
68
|
+
if (offenders.length) {
|
|
69
|
+
const shown = offenders.slice(0, 3).map((o) => `${o.path} (${o.reason})`).join('; ');
|
|
70
|
+
const more = offenders.length > 3 ? `; +${offenders.length - 3} more` : '';
|
|
71
|
+
return { docsOnly: false, files, offenders, reason: `${offenders.length} of ${files} file(s) not documentation: ${shown}${more}` };
|
|
72
|
+
}
|
|
73
|
+
return { docsOnly: true, files, offenders: [], reason: `docs-only (${files} files)` };
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Parse `git diff --raw -z --no-renames --no-abbrev` output into
|
|
78
|
+
* `[{ path, oldMode, newMode, oldSha, newSha, status }]`. The sha/status fields are additive
|
|
79
|
+
* (#297): the cure rule's manifest check (tools/lib/cure-diff.js) reads each side's blob by sha, so
|
|
80
|
+
* it reuses this parser rather than growing a second one that could disagree with it.
|
|
81
|
+
*/
|
|
82
|
+
function parseRaw(stdout) {
|
|
83
|
+
const parts = String(stdout || '').split('\0');
|
|
84
|
+
const out = [];
|
|
85
|
+
for (let i = 0; i < parts.length; i++) {
|
|
86
|
+
const head = parts[i].replace(/^\n+/, '');
|
|
87
|
+
if (!head.startsWith(':')) continue;
|
|
88
|
+
const [oldMode, newMode, oldSha, newSha, status] = head.slice(1).split(' ');
|
|
89
|
+
const p = parts[i + 1];
|
|
90
|
+
if (p) out.push({ path: p, oldMode, newMode, oldSha, newSha, status });
|
|
91
|
+
i++;
|
|
92
|
+
}
|
|
93
|
+
return out;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Parse `git diff --numstat -z --no-renames` output into the set of paths git calls binary. */
|
|
97
|
+
function parseBinary(stdout) {
|
|
98
|
+
const bin = new Set();
|
|
99
|
+
for (const rec of String(stdout || '').split('\0')) {
|
|
100
|
+
const m = /^\n*(-|\d+)\t(-|\d+)\t(.+)$/s.exec(rec);
|
|
101
|
+
if (m && m[1] === '-' && m[2] === '-') bin.add(m[3]);
|
|
102
|
+
}
|
|
103
|
+
return bin;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* Read the entries one git diff invocation produces. `range` is passed through to `git diff`
|
|
108
|
+
* (`a...b`) or `git diff-tree` (`<sha>`), selected by `cmd`. Returns an entry array, or `null` when
|
|
109
|
+
* either read failed — which the caller must treat as not docs-only.
|
|
110
|
+
*/
|
|
111
|
+
function readEntries(git, repo, cmd, range) {
|
|
112
|
+
const common = cmd === 'diff-tree'
|
|
113
|
+
? ['diff-tree', '-r', '-z', '--no-renames', '--no-commit-id', '--root', '-m']
|
|
114
|
+
: ['diff', '-z', '--no-renames'];
|
|
115
|
+
const raw = git.git([...common, '--raw', '--no-abbrev', ...range], repo);
|
|
116
|
+
const num = git.git([...common, '--numstat', ...range], repo);
|
|
117
|
+
if (!raw.ok || !num.ok) return null;
|
|
118
|
+
const binary = parseBinary(num.stdout);
|
|
119
|
+
return parseRaw(raw.stdout).map((e) => ({ ...e, binary: binary.has(e.path) }));
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* The branch shape: what `branch` changes relative to its merge base with `base` — the same three-dot
|
|
124
|
+
* diff the squash would land.
|
|
125
|
+
*/
|
|
126
|
+
function branchChanges(git, repo, base, branch) {
|
|
127
|
+
const entries = readEntries(git, repo, 'diff', [`${base}...${branch}`, '--']);
|
|
128
|
+
if (!entries) return { docsOnly: false, files: 0, offenders: [], reason: `could not read the diff ${base}...${branch}` };
|
|
129
|
+
return classify(entries);
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* The trunk-direct shape (#302 has no branch): every commit on `trunk` committed at or after `since`
|
|
134
|
+
* (the unit's earliest claim), by ANYONE. That over-includes other sessions' commits on purpose.
|
|
135
|
+
* Nothing mechanical ties a trunk commit to a session, and the error must lean toward refusing. No
|
|
136
|
+
* `since`, or no commits in the window, is refused like an empty diff.
|
|
137
|
+
*/
|
|
138
|
+
function directChanges(git, repo, trunk, since) {
|
|
139
|
+
if (!since) return { docsOnly: false, files: 0, offenders: [], reason: 'the claim records no creation time to bound the unit' };
|
|
140
|
+
const revs = git.git(['rev-list', `--since=${since}`, trunk], repo);
|
|
141
|
+
if (!revs.ok) return { docsOnly: false, files: 0, offenders: [], reason: `could not list ${trunk} commits since ${since}` };
|
|
142
|
+
const shas = revs.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
|
|
143
|
+
const entries = [];
|
|
144
|
+
for (const sha of shas) {
|
|
145
|
+
const e = readEntries(git, repo, 'diff-tree', [sha]);
|
|
146
|
+
if (!e) return { docsOnly: false, files: 0, offenders: [], reason: `could not read commit ${sha.slice(0, 7)}` };
|
|
147
|
+
entries.push(...e);
|
|
148
|
+
}
|
|
149
|
+
const verdict = classify(entries);
|
|
150
|
+
return { ...verdict, commits: shas.length };
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
module.exports = {
|
|
154
|
+
DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS,
|
|
155
|
+
pathReason, classify, parseRaw, parseBinary, branchChanges, directChanges,
|
|
156
|
+
};
|
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* exposure-shape.js — #207: the ONE shared representation of the exposure mechanism contract
|
|
4
|
+
* (CONVENTIONS.md §2, "Exposure"), consumed by both halves that used to hand-encode it
|
|
5
|
+
* separately:
|
|
6
|
+
*
|
|
7
|
+
* - the VALIDATOR (`audit/audit.mjs`'s exposure-voiced block, #144) — given a descriptor that
|
|
8
|
+
* already declares an exposure, report EVERY mechanism violation it finds.
|
|
9
|
+
* - the CONSTRUCTOR (`tools/lib/adopt.js`'s `EXPOSURE_SHAPE`, #199) — given a shape a repo is
|
|
10
|
+
* actually in, decide whether DECLARING a given exposure is supported at all, stopping at
|
|
11
|
+
* the first reason it is not.
|
|
12
|
+
*
|
|
13
|
+
* Before this file, those were ~130 lines of fail/warn closures (audit) and a ~100-line table of
|
|
14
|
+
* ok/reason closures (adopt) — the exact duplication this handbook's own anti-pattern list warns
|
|
15
|
+
* about, guarded only by `tools/lib/adopt-audit-agreement.test.js`'s matrix (now folded into this
|
|
16
|
+
* module's own test file, see the note there for why the agreement test was retired rather than
|
|
17
|
+
* kept alongside a single source).
|
|
18
|
+
*
|
|
19
|
+
* `evaluateExposure(exposure, ctx)` returns an ORDERED array of entries — empty means the shape
|
|
20
|
+
* cleanly supports this exposure. Two entry shapes:
|
|
21
|
+
*
|
|
22
|
+
* { kind: 'fail', message } a ready-to-report violation; both sides treat it as one.
|
|
23
|
+
* { kind: 'runbook', why, message } deploy runs outside CI and needs a `runbook:` — `why` is
|
|
24
|
+
* the file-aware checkRunbook() label the VALIDATOR uses
|
|
25
|
+
* (it can read the repo and tell "missing" from "unreadable
|
|
26
|
+
* via the API"); `message` is the generic text the
|
|
27
|
+
* CONSTRUCTOR uses when it only has a boolean
|
|
28
|
+
* (`ctx.hasRunbook`) to go on. Whether this entry actually
|
|
29
|
+
* BLOCKS depends on the caller, which is why it is not
|
|
30
|
+
* folded into `kind: 'fail'`: only the caller knows whether
|
|
31
|
+
* the runbook requirement is currently satisfied.
|
|
32
|
+
*
|
|
33
|
+
* `self` always returns `[]` — CONVENTIONS.md §2: self's consumer set is a subset of the room's,
|
|
34
|
+
* no mechanism rule applies to it at all, not even trunk shape.
|
|
35
|
+
*
|
|
36
|
+
* MULTIPLE entries may fire for one bad shape (e.g. `deploy: push-main` with the wrong trunk is
|
|
37
|
+
* two independent problems) — this mirrors the original, un-refactored audit block exactly,
|
|
38
|
+
* which was a sequence of independent `if`s, never an early return. The VALIDATOR reports every
|
|
39
|
+
* entry; the CONSTRUCTOR reads only the first, which is why entries are pushed in the same order
|
|
40
|
+
* `EXPOSURE_SHAPE`'s old early-return checks ran in (push-main, then none/null, then an
|
|
41
|
+
* off-enum catch-all, then the runbook/workflow branch, then trunk) — order is otherwise
|
|
42
|
+
* unobservable from the validator side, since it reports the whole set regardless of order.
|
|
43
|
+
*
|
|
44
|
+
* The off-enum "catch-all" fail in the `released`-with-production shape is DEAD CODE on the
|
|
45
|
+
* validator side by construction: `deploy` is already validated as one of `tag`/`manual`/
|
|
46
|
+
* `push-main`/`none`/null by an earlier, unconditional check in `audit/audit.mjs` (before the
|
|
47
|
+
* axis dispatch even runs) and, on the constructor side, by `tools/colab`'s own `--deploy`
|
|
48
|
+
* flag validation before `exposureShapeVerdict` is ever called for a NEWLY PROPOSED value. It is
|
|
49
|
+
* kept because `exposureShapeVerdict` can also be asked about an EXISTING, already-committed
|
|
50
|
+
* `deploy:` that was never re-validated (a hand-edited `project.yml`) — removing it would let a
|
|
51
|
+
* hand-typo'd deploy value read as cleanly declarable.
|
|
52
|
+
*
|
|
53
|
+
* Context shape both sides build (identically named, audit.mjs and adopt.js each computing the
|
|
54
|
+
* booleans from their own sources — a real git checkout for one, a `git status`-aware `io` for
|
|
55
|
+
* the other):
|
|
56
|
+
* { trunk, hasProduction, deploy, hasDeployWorkflow, hasRunbook, deployWorkflowNames? }
|
|
57
|
+
* `deployWorkflowNames` is OPTIONAL and cosmetic only (the `none` violation names which
|
|
58
|
+
* workflow(s) contradict it) — omitting it (as adopt.js's ctx does) only drops the parenthetical
|
|
59
|
+
* from the message, never changes which entries fire.
|
|
60
|
+
*/
|
|
61
|
+
|
|
62
|
+
function evaluateExposure(exposure, ctx) {
|
|
63
|
+
switch (exposure) {
|
|
64
|
+
case 'self':
|
|
65
|
+
return [];
|
|
66
|
+
case 'none':
|
|
67
|
+
return evaluateNone(ctx);
|
|
68
|
+
case 'live':
|
|
69
|
+
return evaluateLive(ctx);
|
|
70
|
+
case 'released':
|
|
71
|
+
return ctx.hasProduction ? evaluateReleasedWithProduction(ctx) : evaluateReleasedNoProduction(ctx);
|
|
72
|
+
default:
|
|
73
|
+
return [];
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function evaluateNone(ctx) {
|
|
78
|
+
const out = [];
|
|
79
|
+
if (ctx.trunk !== 'main') {
|
|
80
|
+
out.push({
|
|
81
|
+
kind: 'fail',
|
|
82
|
+
message: `exposure: none requires trunk "main", found ${JSON.stringify(ctx.trunk)} — nothing `
|
|
83
|
+
+ 'consumes this repo, so there is no release branch to speak of',
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
if (ctx.hasDeployWorkflow) {
|
|
87
|
+
const names = Array.isArray(ctx.deployWorkflowNames) && ctx.deployWorkflowNames.length
|
|
88
|
+
? ` (${ctx.deployWorkflowNames.join(', ')})` : '';
|
|
89
|
+
out.push({
|
|
90
|
+
kind: 'fail',
|
|
91
|
+
message: `exposure: none but a deploy workflow exists${names} — nothing is supposed to `
|
|
92
|
+
+ 'consume this repo, yet something is wired to deploy it',
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
return out;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function evaluateLive(ctx) {
|
|
99
|
+
const out = [];
|
|
100
|
+
// #205: validates the two-branch SPLIT, not the spelling — trunk must be declared and
|
|
101
|
+
// distinct from "main" (the release branch the promotion deploys to), never required to
|
|
102
|
+
// literally be "dev". "dev" is the default project.schema.md's `trunk` section and the
|
|
103
|
+
// templates propose; a repo naming its trunk something else is conforming, not exempted.
|
|
104
|
+
if (!ctx.trunk || ctx.trunk === 'main') {
|
|
105
|
+
out.push({
|
|
106
|
+
kind: 'fail',
|
|
107
|
+
message: `exposure: live requires trunk to be a branch distinct from "main", found ${JSON.stringify(ctx.trunk)} `
|
|
108
|
+
+ '— the promotion is the deploy, and trunk (dev by default) is where sessions land before it ships',
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
if (!ctx.hasProduction) {
|
|
112
|
+
out.push({ kind: 'fail', message: 'exposure: live but production is null — the promotion ships straight to users, so a live URL must be set' });
|
|
113
|
+
}
|
|
114
|
+
if (ctx.deploy !== 'push-main') {
|
|
115
|
+
out.push({
|
|
116
|
+
kind: 'fail',
|
|
117
|
+
message: `exposure: live requires deploy: push-main, found ${JSON.stringify(ctx.deploy)} `
|
|
118
|
+
+ '— the promotion itself IS the deploy',
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
if (!ctx.hasDeployWorkflow) {
|
|
122
|
+
out.push({
|
|
123
|
+
kind: 'fail',
|
|
124
|
+
message: 'exposure: live but no .github/workflows/deploy-*.yml — the promotion needs a '
|
|
125
|
+
+ 'committed path to production (no runbook: escape hatch here — live means the '
|
|
126
|
+
+ 'promotion itself deploys)',
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
return out;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
function evaluateReleasedNoProduction(ctx) {
|
|
133
|
+
const out = [];
|
|
134
|
+
if (ctx.trunk !== 'main') {
|
|
135
|
+
out.push({
|
|
136
|
+
kind: 'fail',
|
|
137
|
+
message: `exposure: released with production: null requires trunk "main", found `
|
|
138
|
+
+ `${JSON.stringify(ctx.trunk)} — nothing is live, so there is no release branch to speak of`,
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
if (ctx.deploy !== null && ctx.deploy !== undefined && ctx.deploy !== 'none') {
|
|
142
|
+
out.push({
|
|
143
|
+
kind: 'fail',
|
|
144
|
+
message: `exposure: released with production: null and deploy: ${JSON.stringify(ctx.deploy)} `
|
|
145
|
+
+ 'is contradictory — nothing is live to deploy to; use deploy: none, or set production if something IS live',
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
return out;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
function evaluateReleasedWithProduction(ctx) {
|
|
152
|
+
const out = [];
|
|
153
|
+
|
|
154
|
+
if (ctx.deploy === 'push-main') {
|
|
155
|
+
out.push({
|
|
156
|
+
kind: 'fail',
|
|
157
|
+
message: 'exposure: released with deploy: push-main — released means a deliberate release '
|
|
158
|
+
+ 'artifact gates production, and here every push to main reaches users with no such '
|
|
159
|
+
+ 'gate. Options include: declare exposure: live instead (that IS this shape), migrate '
|
|
160
|
+
+ 'the pipeline to a tag trigger (deploy: tag), or — if shipping really is run by hand '
|
|
161
|
+
+ '— deploy: manual plus runbook: naming the committed procedure.',
|
|
162
|
+
});
|
|
163
|
+
}
|
|
164
|
+
if (ctx.deploy === 'none' || ctx.deploy === null || ctx.deploy === undefined) {
|
|
165
|
+
out.push({ kind: 'fail', message: 'exposure: released with a live production URL but deploy: none is contradictory — use "tag" or "manual"' });
|
|
166
|
+
}
|
|
167
|
+
// Dead code on the validator side — see the file banner. Kept for the constructor, asked about
|
|
168
|
+
// an EXISTING, never-re-validated `deploy:` value.
|
|
169
|
+
if (ctx.deploy !== 'tag' && ctx.deploy !== 'manual' && ctx.deploy !== 'push-main'
|
|
170
|
+
&& ctx.deploy !== 'none' && ctx.deploy !== null && ctx.deploy !== undefined) {
|
|
171
|
+
out.push({
|
|
172
|
+
kind: 'fail',
|
|
173
|
+
message: `deploy is ${JSON.stringify(ctx.deploy)} — exposure: released with a live production URL needs deploy: tag or deploy: manual`,
|
|
174
|
+
});
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
// The runbook/no-workflow branch is MUTUALLY EXCLUSIVE with itself (never both), same as the
|
|
178
|
+
// original audit if/else-if chain, but independent of every other entry above and below it.
|
|
179
|
+
const externalTagDeploy = ctx.deploy === 'tag' && !ctx.hasDeployWorkflow;
|
|
180
|
+
if (ctx.deploy === 'manual' || externalTagDeploy) {
|
|
181
|
+
const why = ctx.deploy === 'manual'
|
|
182
|
+
? 'exposure: released, deploy: manual'
|
|
183
|
+
: 'exposure: released, deploy: tag deployed outside CI (an external GitOps poller)';
|
|
184
|
+
out.push({ kind: 'runbook', why, message: `${why} requires runbook: — name the committed doc that describes how production is reached` });
|
|
185
|
+
} else if (!ctx.hasDeployWorkflow) {
|
|
186
|
+
out.push({
|
|
187
|
+
kind: 'fail',
|
|
188
|
+
message: 'exposure: released but no .github/workflows/deploy-*.yml — the path to production '
|
|
189
|
+
+ 'is not in the repo (use deploy: manual + runbook: if it ships by hand, or deploy: tag '
|
|
190
|
+
+ '+ runbook: when a GitOps poller deploys the tag from outside CI)',
|
|
191
|
+
});
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
if (ctx.trunk !== 'dev' && !(ctx.deploy === 'tag' && ctx.trunk === 'main')) {
|
|
195
|
+
out.push({
|
|
196
|
+
kind: 'fail',
|
|
197
|
+
message: ctx.deploy === 'tag'
|
|
198
|
+
? `exposure: released with deploy: tag requires trunk "dev" or "main", found ${JSON.stringify(ctx.trunk)}`
|
|
199
|
+
: `exposure: released requires trunk "dev", found ${JSON.stringify(ctx.trunk)} — only a `
|
|
200
|
+
+ 'tag-gated release (deploy: tag) may run a single trunk "main"',
|
|
201
|
+
});
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
return out;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
module.exports = { evaluateExposure };
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/gate.js — the optional `gate:` block in .github/project.yml (#410).
|
|
4
|
+
*
|
|
5
|
+
* The ruling it encodes: local is a fast smoke check, branch CI is the one authoritative gate.
|
|
6
|
+
* On a shared, loaded workstation a full local suite ran 6–10 min and flaked on timeouts, while the
|
|
7
|
+
* same suite finished in 2–7 min on a clean CI runner — and #403's hermetic rule doubled every local
|
|
8
|
+
* run. So a repo may declare
|
|
9
|
+
*
|
|
10
|
+
* gate:
|
|
11
|
+
* smoke: npm run smoke # the fast local check code-wrap A3 runs once
|
|
12
|
+
* authoritative: ci # the verdict is branch CI at the pushed head sha
|
|
13
|
+
*
|
|
14
|
+
* and code-wrap / code-ship then read branch CI instead of re-running the suite locally. Absent (or
|
|
15
|
+
* `authoritative: local`) = today's behaviour exactly: the local full gate plus `colab gate-hermetic`.
|
|
16
|
+
*
|
|
17
|
+
* `authoritative: ci` only takes effect where branch CI can actually arrive: `gateMode` returns
|
|
18
|
+
* `ci` only when a workflow fires on a feature-branch push. A repo whose CI runs on PRs and trunk
|
|
19
|
+
* pushes alone keeps the local gate however it is declared — the audit warns about that shape.
|
|
20
|
+
*
|
|
21
|
+
* Pure: objects in, objects out. The audit and the skills read through this one module.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
const AUTHORITATIVE = ['ci', 'local'];
|
|
25
|
+
const KEYS = ['smoke', 'authoritative'];
|
|
26
|
+
// A branch name no repo would ever cut, shaped like a conforming feature branch — the probe the
|
|
27
|
+
// audit feeds to workflowsFiringOnBranchPush to ask "does a push to an ordinary session branch
|
|
28
|
+
// trigger any workflow?".
|
|
29
|
+
const PROBE_REF = 'feat/gate-probe-0';
|
|
30
|
+
|
|
31
|
+
function absent() {
|
|
32
|
+
return { declared: false, valid: true, smoke: null, authoritative: 'local', reason: 'gate absent — the local full gate (plus the hermetic run) is the verdict' };
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function invalid(reason) {
|
|
36
|
+
return { declared: true, valid: false, smoke: null, authoritative: 'local', reason: `${reason} — read as absent, so the local full gate stays the verdict` };
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* `gate:` → `{ declared, valid, smoke, authoritative, reason }`. Any defect is read in the STRICTER
|
|
41
|
+
* direction (local full gate) while the audit fails the value — a declaration nobody can trust is
|
|
42
|
+
* not an answer.
|
|
43
|
+
*/
|
|
44
|
+
function parseGate(doc) {
|
|
45
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'gate');
|
|
46
|
+
if (!has || doc.gate === null || doc.gate === undefined) return absent();
|
|
47
|
+
const g = doc.gate;
|
|
48
|
+
if (typeof g === 'string' && g.trim().startsWith('{')) {
|
|
49
|
+
return invalid('gate: is written as an inline {…} map, which project.yml does not parse — write it as a block (gate:\\n smoke: <cmd>\\n authoritative: ci)');
|
|
50
|
+
}
|
|
51
|
+
if (typeof g !== 'object' || Array.isArray(g)) {
|
|
52
|
+
return invalid(`gate is ${JSON.stringify(g)} — it must be a block with smoke: <command> and optional authoritative: ci|local`);
|
|
53
|
+
}
|
|
54
|
+
const unknown = Object.keys(g).filter((k) => !KEYS.includes(k));
|
|
55
|
+
if (unknown.length) return invalid(`gate has unknown key${unknown.length === 1 ? '' : 's'} ${unknown.join(', ')} — only smoke and authoritative are defined`);
|
|
56
|
+
if (typeof g.smoke !== 'string' || !g.smoke.trim()) {
|
|
57
|
+
return invalid('gate.smoke is missing or empty — it names the fast local check code-wrap A3 runs');
|
|
58
|
+
}
|
|
59
|
+
const auth = g.authoritative === undefined || g.authoritative === null ? 'local' : g.authoritative;
|
|
60
|
+
if (!AUTHORITATIVE.includes(auth)) {
|
|
61
|
+
return invalid(`gate.authoritative is ${JSON.stringify(auth)} — the defined values are ci and local`);
|
|
62
|
+
}
|
|
63
|
+
return {
|
|
64
|
+
declared: true, valid: true, smoke: g.smoke.trim(), authoritative: auth,
|
|
65
|
+
reason: auth === 'ci'
|
|
66
|
+
? 'gate: authoritative ci — local runs the smoke check once; branch CI at the pushed head is the verdict'
|
|
67
|
+
: 'gate: authoritative local — the local full gate (plus the hermetic run) is the verdict; smoke is the iteration check',
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Which verdict the skills read: `'ci'` only when `authoritative: ci` is validly declared AND a
|
|
73
|
+
* workflow fires on a feature-branch push (`branchCiFires`). Everything else is `'local'`.
|
|
74
|
+
*/
|
|
75
|
+
function gateMode({ gate, branchCiFires }) {
|
|
76
|
+
const g = gate || absent();
|
|
77
|
+
return g.valid && g.authoritative === 'ci' && branchCiFires ? 'ci' : 'local';
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
module.exports = { parseGate, gateMode, PROBE_REF, AUTHORITATIVE };
|