@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.11
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 +312 -3
- package/README.vi.md +281 -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 +13806 -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 +278 -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-endpoint.js +170 -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,237 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/writes-authority.js — the precedence ladder behind #208's `writes` split.
|
|
4
|
+
*
|
|
5
|
+
* Same shape as tools/lib/axis-authority.js's tier -> exposure ladder, deliberately: one
|
|
6
|
+
* frozen LEGACY map, one resolve function, a `source` tag naming which path answered. Not a
|
|
7
|
+
* new mechanism — the ruling on #208 asked for the EXISTING one, reused for a second axis,
|
|
8
|
+
* rather than a bespoke second way of reading a legacy value.
|
|
9
|
+
*
|
|
10
|
+
* Before this unit, `writes` had two declarable values — `isolated` (default) and `serial` —
|
|
11
|
+
* covering THREE coherent methods (CONVENTIONS.md §2, "Writes"): `serial` collapsed the
|
|
12
|
+
* trunk-direct and gated cells into one spelling, so a descriptor could not say which a repo
|
|
13
|
+
* actually ran, and a reader answering "may this repo be granted `autonomy: auto-trunk`?" had
|
|
14
|
+
* to piece the answer together from three separate passages (#208's measured defect). This
|
|
15
|
+
* module is the read side of the fix: given a declared `writes:` value, it says which of the
|
|
16
|
+
* three CURRENT methods is in force, and how it got there.
|
|
17
|
+
*
|
|
18
|
+
* `serial -> serial-direct` is the LEGACY resolution, and it is deliberately the one that
|
|
19
|
+
* changes nothing observable for a repo that has not opted into the split — the identical
|
|
20
|
+
* reasoning axis-authority.js gives for its own LEGACY map ("reproduces pre-#144 behaviour
|
|
21
|
+
* byte for byte"). It rested on two reasons; #224 retired the second, so the first now
|
|
22
|
+
* carries the resolution alone:
|
|
23
|
+
*
|
|
24
|
+
* - Every repo declaring bare `serial` today is solo-flow eligible
|
|
25
|
+
* (`soloEligibility`, tools/lib/solo.js) — including this handbook's own descriptor,
|
|
26
|
+
* whose comment states outright that `writes: serial` "is what lets solo flow's entry
|
|
27
|
+
* gate open here". Resolving the alias to `serial-gated` instead would silently revoke
|
|
28
|
+
* that for every such repo the moment this unit lands. Still true, and sufficient on
|
|
29
|
+
* its own.
|
|
30
|
+
* - RETIRED (#224): this used to also cite the constraint matrix's `auto-trunk` cell,
|
|
31
|
+
* which read `forbidden` for `serial-direct` and `allowed` for `serial-gated` —
|
|
32
|
+
* resolving toward `serial-gated` looked like it would move a repo into a cell nobody
|
|
33
|
+
* had re-examined. #224 corrected that cell to `allowed` for both methods
|
|
34
|
+
* (CONVENTIONS.md §2 "Writes"; project.schema.md "writes — optional"): `auto-trunk`
|
|
35
|
+
* was never actually gated on `serial-direct` vs `serial-gated`, only on whether a
|
|
36
|
+
* branch exists for `colab ship` to act on. Resolving toward `serial-gated` no longer
|
|
37
|
+
* changes a repo's `auto-trunk` posture at all, so this reason no longer applies — the
|
|
38
|
+
* first reason above is what protects the alias now.
|
|
39
|
+
*
|
|
40
|
+
* Reclassifying an EXISTING repo's descriptor to `serial-gated` stays a human's call, never
|
|
41
|
+
* inferred by this resolver — #208's migration note is explicit that reclassification is a
|
|
42
|
+
* per-repo decision, not an automatic one, and this module's job is only to answer "what does
|
|
43
|
+
* an unexamined `serial` mean today", not "what should it mean going forward".
|
|
44
|
+
*
|
|
45
|
+
* #237 (the ⚖ Decision on #233): the three-method reading above is RETIRED. `writes` no longer
|
|
46
|
+
* selects a write-conflict prevention method — it is a two-state VETO. `writes: isolated` means
|
|
47
|
+
* exactly one thing: no trunk-direct in this repo, human or not. Absence, and every other value
|
|
48
|
+
* (including both `serial-*` spellings and the `serial` alias), means COEXISTENCE: automated
|
|
49
|
+
* sessions work in worktrees, a human may take the trunk checkout and commit directly, and the
|
|
50
|
+
* two run side by side. `resolveWrites` below is UNCHANGED — it still parses the declared value
|
|
51
|
+
* and resolves the legacy alias, exactly as before — because nothing about that job is wrong,
|
|
52
|
+
* only what callers may DO with its answer. The three-method resolution it still performs is now
|
|
53
|
+
* inert either way: `serial-direct` and `serial-gated` both mean coexistence, so the alias
|
|
54
|
+
* question this file's banner spends 30 lines on ("does `serial` mean `serial-direct` or
|
|
55
|
+
* `serial-gated`?") no longer changes any repo's observable behaviour — both branches land on
|
|
56
|
+
* the same veto answer. See `trunkDirectVetoed` below for the one function that now decides
|
|
57
|
+
* anything.
|
|
58
|
+
*/
|
|
59
|
+
|
|
60
|
+
// The three current, declarable methods (CONVENTIONS.md §2, "Writes" — the four-row table).
|
|
61
|
+
// `isolated` is the schema default (omission = isolated); the other two are only meaningful
|
|
62
|
+
// when declared.
|
|
63
|
+
const WRITES_DECLARED = Object.freeze(['isolated', 'serial-direct', 'serial-gated']);
|
|
64
|
+
const WRITES_DECLARED_SET = new Set(WRITES_DECLARED);
|
|
65
|
+
|
|
66
|
+
// The one method the legacy spelling resolves to. See the file banner for why serial-direct,
|
|
67
|
+
// not serial-gated.
|
|
68
|
+
const WRITES_LEGACY = Object.freeze({ serial: 'serial-direct' });
|
|
69
|
+
|
|
70
|
+
// #283: the three spellings the WIZARD offers and `writesMode` (below) resolves TOWARD —
|
|
71
|
+
// replacing the retired 3-method vocabulary with names that describe what a repo PERMITS, not a
|
|
72
|
+
// mechanism it once selected. `direct` is new: declared, stored, and honestly reported today
|
|
73
|
+
// (deriveConsequences, --json, the wizard), but its RUNTIME is deferred — see CONVENTIONS.md
|
|
74
|
+
// §2, "writes: direct — declared today, runtime deferred (#283)". `trunkDirectVetoed` (below)
|
|
75
|
+
// is unaffected: only the exact string 'isolated' ever vetoes, under either vocabulary.
|
|
76
|
+
const WRITES_CURRENT = Object.freeze(['free', 'direct', 'isolated']);
|
|
77
|
+
const WRITES_CURRENT_SET = new Set(WRITES_CURRENT);
|
|
78
|
+
|
|
79
|
+
// The three pre-#283 spellings (#208's original 3-method split), ALL of which `writesMode` now
|
|
80
|
+
// folds toward `free` — distinct from `WRITES_LEGACY` above (the `serial` alias, which
|
|
81
|
+
// `resolveWrites` still parses toward `serial-direct`, unchanged): this is the wider set
|
|
82
|
+
// `writesMode` needs to recognise every spelling that predates this vocabulary, `serial`
|
|
83
|
+
// included, in one pass.
|
|
84
|
+
const WRITES_LEGACY_FREE = Object.freeze(['serial', 'serial-direct', 'serial-gated']);
|
|
85
|
+
const WRITES_LEGACY_FREE_SET = new Set(WRITES_LEGACY_FREE);
|
|
86
|
+
|
|
87
|
+
// Everything the audit accepts as a value (current vocabulary + every legacy spelling) — an
|
|
88
|
+
// enum check, not a resolution. `colab adopt --writes` also accepts this set, so an existing
|
|
89
|
+
// script or muscle-memory invocation using `--writes serial` (or `serial-direct`/`serial-gated`)
|
|
90
|
+
// keeps working, and `--writes direct` is now legal too (subject to `writesGateVerdict` in
|
|
91
|
+
// tools/lib/adopt.js).
|
|
92
|
+
const WRITES_ACCEPTED_SET = new Set([
|
|
93
|
+
...WRITES_DECLARED, ...Object.keys(WRITES_LEGACY), ...WRITES_CURRENT, ...WRITES_LEGACY_FREE,
|
|
94
|
+
]);
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Resolve a declared `writes:` value (possibly undefined/null/unrecognised) to one of the
|
|
98
|
+
* three current methods. Returns `{ value, source }`:
|
|
99
|
+
*
|
|
100
|
+
* { value: <one of WRITES_DECLARED>, source: 'declared' } — current vocabulary, as-is.
|
|
101
|
+
* { value: 'serial-direct', source: 'legacy' } — the `serial` alias.
|
|
102
|
+
* { value: 'isolated', source: 'default' } — omitted entirely.
|
|
103
|
+
* { value: 'isolated', source: 'unrecognised' } — some other string; fails
|
|
104
|
+
* closed to isolated, never
|
|
105
|
+
* toward a serial reading.
|
|
106
|
+
*
|
|
107
|
+
* DEPRECATED-INTERNAL as of #283: this resolver's OWN job (parse the `serial` alias toward
|
|
108
|
+
* `serial-direct`, report `source`) is unchanged and still correct — nothing here is wrong — but
|
|
109
|
+
* nothing outside `writes-authority.js` should read its 3-way `.value` as deciding anything any
|
|
110
|
+
* longer, for the identical trap `trunkDirectVetoed`'s docstring below has always warned about.
|
|
111
|
+
* `tools/lib/adopt.js`'s `deriveConsequences` reads `writesMode(raw)` instead, which is a TOTAL
|
|
112
|
+
* function onto exactly `free` / `direct` / `isolated` and cannot produce that trap in the first
|
|
113
|
+
* place. `resolveWrites` stays exported, unchanged, and fully tested for whatever legacy-alias
|
|
114
|
+
* bookkeeping still needs its 3-way parse — it is retired from being read as a method choice,
|
|
115
|
+
* not retired outright.
|
|
116
|
+
*/
|
|
117
|
+
function resolveWrites(raw) {
|
|
118
|
+
if (WRITES_DECLARED_SET.has(raw)) return { value: raw, source: 'declared' };
|
|
119
|
+
if (Object.prototype.hasOwnProperty.call(WRITES_LEGACY, raw)) {
|
|
120
|
+
return { value: WRITES_LEGACY[raw], source: 'legacy' };
|
|
121
|
+
}
|
|
122
|
+
return { value: 'isolated', source: raw === null || raw === undefined ? 'default' : 'unrecognised' };
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* #283: the TOTAL reading `deriveConsequences` uses instead of `resolveWrites` — maps EVERY
|
|
127
|
+
* possible input (undefined/null, any of the three current spellings, any of the three legacy
|
|
128
|
+
* spellings, or an unrecognised string) onto exactly one of `free` / `direct` / `isolated`, with
|
|
129
|
+
* a `source` naming which bucket it came from. "Total" is the point: there is no input this
|
|
130
|
+
* function fails to classify, which is what makes "writesResolved disagrees with trunkDirect"
|
|
131
|
+
* (#282) structurally unreachable — see `tools/lib/adopt.js`'s `deriveConsequences`.
|
|
132
|
+
*
|
|
133
|
+
* Fails toward `free` on anything unrecognised — the same posture `trunkDirectVetoed` already
|
|
134
|
+
* takes (only an exact, correctly-spelled `isolated` ever restricts anything); the audit's own
|
|
135
|
+
* enum check (`isAcceptedWritesValue`) is what catches a typo, not this function.
|
|
136
|
+
*
|
|
137
|
+
* { mode: 'free', source: 'default' } — undefined/null (the key is absent).
|
|
138
|
+
* { mode: 'free', source: 'legacy' } — one of WRITES_LEGACY_FREE.
|
|
139
|
+
* { mode: <one of WRITES_CURRENT>, source: 'declared' } — raw is exactly free/direct/isolated.
|
|
140
|
+
* { mode: 'free', source: 'unrecognised' } — anything else; fails closed to free,
|
|
141
|
+
* never toward isolated or direct.
|
|
142
|
+
*/
|
|
143
|
+
function writesMode(raw) {
|
|
144
|
+
if (raw === null || raw === undefined) return { mode: 'free', source: 'default' };
|
|
145
|
+
if (WRITES_CURRENT_SET.has(raw)) return { mode: raw, source: 'declared' };
|
|
146
|
+
if (WRITES_LEGACY_FREE_SET.has(raw)) return { mode: 'free', source: 'legacy' };
|
|
147
|
+
return { mode: 'free', source: 'unrecognised' };
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** Is `raw` a value the audit accepts — current vocabulary, the legacy alias, or omitted? */
|
|
151
|
+
function isAcceptedWritesValue(raw) {
|
|
152
|
+
return raw === null || raw === undefined || WRITES_ACCEPTED_SET.has(raw);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* #237: does this descriptor's `writes:` VETO trunk-direct? The one two-state reading that
|
|
157
|
+
* decides anything now (CONVENTIONS.md §2, "Writes"). `writes: isolated` vetoes trunk-direct
|
|
158
|
+
* for every session, human or not; absence and every other declared value (both `serial-*`
|
|
159
|
+
* spellings, the `serial` alias, and any unrecognised string) mean coexistence — no veto.
|
|
160
|
+
*
|
|
161
|
+
* Deliberately reads the RAW declared value, never `resolveWrites(raw).value` — that function's
|
|
162
|
+
* `value` reads `'isolated'` on BOTH `source: 'declared'` (a real `writes: isolated` line) AND
|
|
163
|
+
* `source: 'default'` (the key is simply absent). Testing `resolveWrites(raw).value ===
|
|
164
|
+
* 'isolated'` would therefore veto every repo with no `writes:` key at all — the exact opposite
|
|
165
|
+
* of the ruling ("Absence — and every other value — means coexistence"). Only an EXPLICIT,
|
|
166
|
+
* exactly-spelled `writes: isolated` vetoes; everything else, including a typo'd or unrecognised
|
|
167
|
+
* string, coexists (the audit's own enum check is what catches a typo — see
|
|
168
|
+
* `isAcceptedWritesValue` above — a silent non-veto here is not an unattended-write risk, because
|
|
169
|
+
* every path that non-veto opens still requires a human at the keyboard: `COLAB_HUMAN=1`).
|
|
170
|
+
*/
|
|
171
|
+
function trunkDirectVetoed(raw) {
|
|
172
|
+
return raw === 'isolated';
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* #239: the sync announcement for ⚖ #233 (CONVENTIONS.md §2, "Writes" — the four-row table).
|
|
177
|
+
* Four shapes, keyed on the RAW declared value exactly like `trunkDirectVetoed` (never the
|
|
178
|
+
* 3-way `resolveWrites` parse, for the identical trap that function's own docstring warns
|
|
179
|
+
* about — reading `.value` would call an absent key "isolated").
|
|
180
|
+
*
|
|
181
|
+
* This text is the ONE source for the announcement — the audit's sync-path warn quotes it
|
|
182
|
+
* verbatim (audit/audit.mjs, gated by tools/lib/stamp.js's `writesRulingKnownAt`), and it is
|
|
183
|
+
* meant to double as the "writes" bullet in whichever tag's release notes ship #237/⚖ #233 —
|
|
184
|
+
* written once, so the two copies cannot drift apart the way a hand-restated pair always does.
|
|
185
|
+
*/
|
|
186
|
+
function writesSyncAdvisory(raw) {
|
|
187
|
+
// #283: `free`/`direct` branches, added for totality now that `writesMode` widens the enum —
|
|
188
|
+
// near-dead code today, same as the four branches below: `writesRulingKnownAt` (stamp.js)
|
|
189
|
+
// gates this whole call site on a repo's stamp predating ⚖ #237, and no repo can predate #237
|
|
190
|
+
// while already declaring #283's vocabulary. Added for completeness, not reach.
|
|
191
|
+
if (raw === 'free') {
|
|
192
|
+
return 'writes: free is the ⚖ #233/#283 spelling of coexistence — identical to omitting the '
|
|
193
|
+
+ 'key, or to any of the legacy serial* spellings (CONVENTIONS.md §2, Writes)';
|
|
194
|
+
}
|
|
195
|
+
if (raw === 'direct') {
|
|
196
|
+
return 'writes: direct declares that an attended human may commit straight to trunk — the '
|
|
197
|
+
+ 'SAME runtime permission as free/absence today (declared, not yet enforced — #283); see '
|
|
198
|
+
+ 'CONVENTIONS.md §2, "writes: direct — declared today, runtime deferred (#283)"';
|
|
199
|
+
}
|
|
200
|
+
if (raw === 'isolated') {
|
|
201
|
+
return 'writes: isolated changed meaning under ⚖ #233 — it no longer describes a default, '
|
|
202
|
+
+ 'it now VETOES trunk-direct outright, human or not. If this repo runs many concurrent '
|
|
203
|
+
+ 'units and declared isolated only to describe that shape (not to forbid trunk-direct), '
|
|
204
|
+
+ 'confirm with the repo\'s owner whether the veto is actually intended (CONVENTIONS.md '
|
|
205
|
+
+ '§2, Writes)';
|
|
206
|
+
}
|
|
207
|
+
if (raw === 'serial-gated') {
|
|
208
|
+
return 'writes: serial-gated is inert under ⚖ #233 — coexistence is the default regardless. '
|
|
209
|
+
+ 'Its one real assertion, a pre-merge gate exists here, moved to the axis that owns '
|
|
210
|
+
+ 'gating: declare it there instead (a trunk-gating CI workflow, or branch protection), '
|
|
211
|
+
+ 'not via writes (CONVENTIONS.md §2, Writes)';
|
|
212
|
+
}
|
|
213
|
+
if (raw === 'serial' || raw === 'serial-direct') {
|
|
214
|
+
return `writes: ${raw} is inert under ⚖ #233 — identical to omitting the key; coexistence `
|
|
215
|
+
+ 'is the default regardless. The line may be removed (CONVENTIONS.md §2, Writes)';
|
|
216
|
+
}
|
|
217
|
+
// raw === null/undefined, or an unrecognised string — both coexist by the same reading
|
|
218
|
+
// trunkDirectVetoed gives them, so both get the "silent majority" message (#239's own name
|
|
219
|
+
// for this case: the only channel that reaches a repo declaring nothing).
|
|
220
|
+
return 'writes is undeclared — as of ⚖ #233 this now means COEXISTENCE: a worktree session '
|
|
221
|
+
+ 'and an attended human trunk-direct session (COLAB_HUMAN=1) may both write to this repo\'s '
|
|
222
|
+
+ 'trunk, side by side. If that is not intended, declare writes: isolated to veto trunk-direct '
|
|
223
|
+
+ 'outright (CONVENTIONS.md §2, Writes)';
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
module.exports = {
|
|
227
|
+
WRITES_DECLARED,
|
|
228
|
+
WRITES_LEGACY,
|
|
229
|
+
WRITES_CURRENT,
|
|
230
|
+
WRITES_LEGACY_FREE,
|
|
231
|
+
WRITES_ACCEPTED_SET,
|
|
232
|
+
resolveWrites,
|
|
233
|
+
writesMode,
|
|
234
|
+
isAcceptedWritesValue,
|
|
235
|
+
trunkDirectVetoed,
|
|
236
|
+
writesSyncAdvisory,
|
|
237
|
+
};
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* Minimal YAML subset parser — enough for `.github/project.yml`, no dependencies.
|
|
4
|
+
*
|
|
5
|
+
* Supported:
|
|
6
|
+
* key: value scalars: string, number, true/false, null/~, quoted strings
|
|
7
|
+
* key: [a, b, 3] inline (flow) sequences of scalars
|
|
8
|
+
* key: block sequences
|
|
9
|
+
* - a
|
|
10
|
+
* - b
|
|
11
|
+
* key: nested maps (indentation based)
|
|
12
|
+
* sub: value
|
|
13
|
+
* # comments, blank lines
|
|
14
|
+
*
|
|
15
|
+
* NOT supported (deliberately — keep it small and predictable):
|
|
16
|
+
* anchors/aliases, multi-line scalars (| >), flow maps {a: 1}, multi-doc (---),
|
|
17
|
+
* sequences of maps. If a project descriptor ever needs those, replace this
|
|
18
|
+
* with a real parser rather than growing this one.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
function parseScalar(raw) {
|
|
22
|
+
const s = raw.trim();
|
|
23
|
+
if (s === '') return '';
|
|
24
|
+
if ((s.startsWith('"') && s.endsWith('"') && s.length > 1) ||
|
|
25
|
+
(s.startsWith("'") && s.endsWith("'") && s.length > 1)) {
|
|
26
|
+
return s.slice(1, -1);
|
|
27
|
+
}
|
|
28
|
+
if (s === 'null' || s === '~') return null;
|
|
29
|
+
if (s === 'true' || s === 'yes') return true;
|
|
30
|
+
if (s === 'false' || s === 'no') return false;
|
|
31
|
+
if (/^-?\d+$/.test(s)) return parseInt(s, 10);
|
|
32
|
+
if (/^-?\d*\.\d+$/.test(s)) return parseFloat(s);
|
|
33
|
+
return s;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function parseFlowSeq(raw) {
|
|
37
|
+
const inner = raw.trim().slice(1, -1).trim();
|
|
38
|
+
if (inner === '') return [];
|
|
39
|
+
return inner.split(',').map((p) => parseScalar(p));
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// Strip a trailing ` # comment`, but not a `#` inside quotes.
|
|
43
|
+
function stripComment(line) {
|
|
44
|
+
let inS = false, inD = false;
|
|
45
|
+
for (let i = 0; i < line.length; i++) {
|
|
46
|
+
const c = line[i];
|
|
47
|
+
if (c === "'" && !inD) inS = !inS;
|
|
48
|
+
else if (c === '"' && !inS) inD = !inD;
|
|
49
|
+
else if (c === '#' && !inS && !inD && (i === 0 || /\s/.test(line[i - 1]))) {
|
|
50
|
+
return line.slice(0, i);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
return line;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function parse(text) {
|
|
57
|
+
const lines = [];
|
|
58
|
+
for (const rawLine of String(text).split(/\r?\n/)) {
|
|
59
|
+
const line = stripComment(rawLine).replace(/\s+$/, '');
|
|
60
|
+
if (line.trim() === '') continue;
|
|
61
|
+
lines.push({ indent: line.match(/^ */)[0].length, text: line.trim() });
|
|
62
|
+
}
|
|
63
|
+
let i = 0;
|
|
64
|
+
|
|
65
|
+
function parseBlock(indent) {
|
|
66
|
+
// Sequence?
|
|
67
|
+
if (i < lines.length && lines[i].indent === indent && lines[i].text.startsWith('- ')) {
|
|
68
|
+
const arr = [];
|
|
69
|
+
while (i < lines.length && lines[i].indent === indent && lines[i].text.startsWith('- ')) {
|
|
70
|
+
arr.push(parseScalar(lines[i].text.slice(2)));
|
|
71
|
+
i++;
|
|
72
|
+
}
|
|
73
|
+
return arr;
|
|
74
|
+
}
|
|
75
|
+
// Map
|
|
76
|
+
const obj = {};
|
|
77
|
+
while (i < lines.length && lines[i].indent >= indent) {
|
|
78
|
+
if (lines[i].indent > indent) { i++; continue; } // defensive: stray deeper line
|
|
79
|
+
const { text } = lines[i];
|
|
80
|
+
const m = text.match(/^([^:]+):\s*(.*)$/);
|
|
81
|
+
if (!m) { i++; continue; }
|
|
82
|
+
const key = m[1].trim();
|
|
83
|
+
const rest = m[2].trim();
|
|
84
|
+
i++;
|
|
85
|
+
if (rest === '') {
|
|
86
|
+
if (i < lines.length && lines[i].indent > indent) obj[key] = parseBlock(lines[i].indent);
|
|
87
|
+
else obj[key] = null;
|
|
88
|
+
} else if (rest.startsWith('[') && rest.endsWith(']')) {
|
|
89
|
+
obj[key] = parseFlowSeq(rest);
|
|
90
|
+
} else {
|
|
91
|
+
obj[key] = parseScalar(rest);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
return obj;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
if (lines.length === 0) return {};
|
|
98
|
+
return parseBlock(lines[0].indent);
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
module.exports = { parse };
|
package/bin/cli.js
DELETED