@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.1
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/README.md +243 -213
- package/README.vi.md +246 -186
- package/audit/audit.mjs +193 -10
- package/package.json +6 -1
- package/templates/README.md +30 -2
- package/templates/ci-laravel.yml +102 -21
- package/templates/ci-node.yml +61 -3
- package/templates/ci-python.yml +52 -3
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +368 -0
- package/templates/deploy-container.yml +219 -0
- package/templates/dist-refs.yml +6 -0
- package/templates/docs-lint.mjs +1 -1
- package/templates/npx-launcher.mjs +118 -20
- package/templates/npx-service.mjs +828 -0
- package/templates/release-auto.yml +341 -32
- package/tools/colab +1691 -254
- package/tools/lib/adopt.js +373 -14
- package/tools/lib/branch-name.js +29 -1
- package/tools/lib/ci-cure.js +522 -31
- package/tools/lib/ci-grant.js +289 -22
- package/tools/lib/ci-wait.js +203 -0
- package/tools/lib/claim-comments.js +13 -64
- package/tools/lib/claim-identity.js +4 -7
- package/tools/lib/codec/claim.d.ts +41 -0
- package/tools/lib/codec/claim.js +151 -0
- package/tools/lib/codec/decision.d.ts +29 -0
- package/tools/lib/codec/decision.js +81 -0
- package/tools/lib/codec/grants.d.ts +82 -0
- package/tools/lib/codec/grants.js +268 -0
- package/tools/lib/codec/hold.d.ts +26 -0
- package/tools/lib/codec/hold.js +152 -0
- package/tools/lib/codec/index.d.ts +21 -0
- package/tools/lib/codec/index.js +32 -0
- package/tools/lib/codec/labels.d.ts +65 -0
- package/tools/lib/codec/labels.js +716 -0
- package/tools/lib/codec/markers.d.ts +35 -0
- package/tools/lib/codec/markers.js +138 -0
- package/tools/lib/codec/release.d.ts +17 -0
- package/tools/lib/codec/release.js +69 -0
- package/tools/lib/codec/samples.json +762 -0
- package/tools/lib/codeowners.js +68 -4
- package/tools/lib/container-close.js +38 -0
- package/tools/lib/cure-diff.js +198 -9
- package/tools/lib/decision-record.js +15 -39
- package/tools/lib/docs-only.js +15 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/git.js +303 -42
- package/tools/lib/group-labels.js +65 -0
- package/tools/lib/install-check.js +14 -8
- package/tools/lib/install-route.js +139 -0
- package/tools/lib/instruction-file.js +1 -0
- package/tools/lib/labels.js +22 -647
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/migration-grant.js +206 -104
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-cut.js +199 -25
- package/tools/lib/release-finalize.js +111 -23
- package/tools/lib/release-policy.js +130 -22
- package/tools/lib/release-runner.js +125 -0
- package/tools/lib/release-tag.js +3 -1
- package/tools/lib/scratch-dirs.js +106 -0
- package/tools/lib/ship-batch.js +36 -1
- package/tools/lib/stamp.js +7 -0
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +64 -0
- package/tools/lib/tree-green.js +88 -0
- package/tools/lib/util.js +17 -1
- package/tools/lib/verify-runs.js +104 -0
- package/tools/lib/wake.js +8 -90
- package/tools/lib/workflow-triggers.js +48 -0
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
// Types for tools/lib/codec/markers.js (#499) — see index.d.ts.
|
|
2
|
+
|
|
3
|
+
export type MarkerForm = 'comment' | 'line';
|
|
4
|
+
|
|
5
|
+
// ── parent ───────────────────────────────────────────────────────────────────────────────────
|
|
6
|
+
|
|
7
|
+
export const PARENT_COMMENT_RE: RegExp;
|
|
8
|
+
export const PARENT_LINE_RE: RegExp;
|
|
9
|
+
export interface ParentRef {
|
|
10
|
+
/** `owner/repo` for a cross-repo parent, null for the same repo. */
|
|
11
|
+
repo: string | null;
|
|
12
|
+
number: number;
|
|
13
|
+
}
|
|
14
|
+
export function encodeParentRef(ref?: { repo?: string | null; number: number }): string;
|
|
15
|
+
export function decodeParentRef(ref: string | null | undefined): ParentRef | null;
|
|
16
|
+
export function encodeParent(p?: { repo?: string | null; number: number; form?: MarkerForm }): string;
|
|
17
|
+
export function decodeParent(marker: string | null | undefined): (ParentRef & { form: MarkerForm }) | null;
|
|
18
|
+
/** The comment form wins; `conflict` = more than one distinct parent declared. */
|
|
19
|
+
export function readParent(body: string | null | undefined): (ParentRef & { form: MarkerForm; conflict: boolean }) | null;
|
|
20
|
+
export function encodeParentBlock(ref?: { repo?: string | null; number: number }): string;
|
|
21
|
+
|
|
22
|
+
// ── close reason ─────────────────────────────────────────────────────────────────────────────
|
|
23
|
+
|
|
24
|
+
export type CloseReason = 'completed' | 'not-planned';
|
|
25
|
+
export const CLOSE_REASONS: ReadonlyArray<CloseReason>;
|
|
26
|
+
export const CLOSE_REASON_COMMENT_RE: RegExp;
|
|
27
|
+
export const CLOSE_REASON_LINE_RE: RegExp;
|
|
28
|
+
export function encodeCloseReason(c?: { reason: CloseReason; form?: MarkerForm }): string;
|
|
29
|
+
export function decodeCloseReason(marker: string | null | undefined): { reason: CloseReason; form: MarkerForm } | null;
|
|
30
|
+
export function encodeCloseReasonBlock(reason: CloseReason): string;
|
|
31
|
+
/** Null unless `state` is closed; then the newest comment carrying a valid marker decides. */
|
|
32
|
+
export function readCloseReason(item?: {
|
|
33
|
+
state?: string;
|
|
34
|
+
comments?: Array<{ body?: string | null; createdAt?: string }>;
|
|
35
|
+
}): CloseReason | null;
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* CODEC (#499, epic #496): two markers for trackers that LACK a native field this toolkit relies
|
|
4
|
+
* on — a parent/child relation (native sub-issues) and a close reason (completed vs not planned).
|
|
5
|
+
* Pure and synchronous. No writer uses them yet: they are designed from documented tracker
|
|
6
|
+
* capabilities, so an adapter for such a tracker has one agreed spelling to write and read.
|
|
7
|
+
*
|
|
8
|
+
* PARENT. Written into the CHILD's body, in two forms:
|
|
9
|
+
* comment `<!-- colab:parent issue=<ref> -->` invisible, the machine-readable form
|
|
10
|
+
* line `Parent: <ref>` visible fallback, at the start of a line, for a
|
|
11
|
+
* tracker (or an editor) that strips HTML comments
|
|
12
|
+
* `<ref>` is `#<n>` (same repo) or `<owner>/<repo>#<n>`. An adapter writes both; a reader prefers
|
|
13
|
+
* the comment and falls back to the line (`readParent`).
|
|
14
|
+
*
|
|
15
|
+
* A parent is NEVER encoded as a dependency edge ("child blocks epic"): the conventions forbid an
|
|
16
|
+
* edge pointing at an epic (CONVENTIONS.md §5, *Epics*) — readiness would read every epic as
|
|
17
|
+
* blocked by its own children, which is the wrong question. Containment and dependency stay two
|
|
18
|
+
* different facts, on two different wires.
|
|
19
|
+
*
|
|
20
|
+
* CLOSE REASON. Also two forms, carried by a COMMENT posted when the item is closed:
|
|
21
|
+
* comment `<!-- colab:close-reason reason=<completed|not-planned> -->`
|
|
22
|
+
* line `Close reason: <completed|not-planned>`
|
|
23
|
+
* It is read for CLOSED items only (`readCloseReason`): on an open item — closed once, then
|
|
24
|
+
* reopened — an old marker describes a close that no longer stands, so it reads as nothing. The
|
|
25
|
+
* newest marker wins, so close → reopen → close reads the last close.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
// ── parent ───────────────────────────────────────────────────────────────────────────────────
|
|
29
|
+
|
|
30
|
+
const PARENT_REF_RE = /^(?:([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+))?#([1-9][0-9]*)$/;
|
|
31
|
+
const PARENT_COMMENT_RE = /^<!-- colab:parent issue=(\S+) -->$/;
|
|
32
|
+
const PARENT_LINE_RE = /^Parent: (\S+)$/;
|
|
33
|
+
|
|
34
|
+
/** `{repo?, number}` → `#N` / `owner/repo#N`. */
|
|
35
|
+
function encodeParentRef({ repo, number } = {}) { return `${repo || ''}#${number}`; }
|
|
36
|
+
/** `#N` / `owner/repo#N` → `{repo, number}` (`repo` null for same-repo), or null. */
|
|
37
|
+
function decodeParentRef(ref) {
|
|
38
|
+
const m = PARENT_REF_RE.exec(String(ref == null ? '' : ref));
|
|
39
|
+
return m ? { repo: m[1] || null, number: Number(m[2]) } : null;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** `{repo?, number, form: 'comment'|'line'}` → the marker. */
|
|
43
|
+
function encodeParent({ repo, number, form = 'comment' } = {}) {
|
|
44
|
+
const ref = encodeParentRef({ repo, number });
|
|
45
|
+
if (form === 'comment') return `<!-- colab:parent issue=${ref} -->`;
|
|
46
|
+
if (form === 'line') return `Parent: ${ref}`;
|
|
47
|
+
throw new TypeError(`encodeParent: unknown form ${JSON.stringify(form)}`);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** ONE marker (comment or line, whole) → `{repo, number, form}`, or null. */
|
|
51
|
+
function decodeParent(marker) {
|
|
52
|
+
const s = String(marker == null ? '' : marker).trim();
|
|
53
|
+
for (const [form, re] of [['comment', PARENT_COMMENT_RE], ['line', PARENT_LINE_RE]]) {
|
|
54
|
+
const m = re.exec(s);
|
|
55
|
+
if (!m) continue;
|
|
56
|
+
const ref = decodeParentRef(m[1]);
|
|
57
|
+
return ref ? { ...ref, form } : null;
|
|
58
|
+
}
|
|
59
|
+
return null;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The parent a child's BODY declares → `{repo, number, form, conflict}`, or null. Each line is
|
|
64
|
+
* tried as a marker (a line form counts only at the start of a line; an indented one is quoted
|
|
65
|
+
* text). The comment form wins over the line form; `conflict` is true when the body carries more
|
|
66
|
+
* than one distinct parent, which a reader should report rather than silently pick.
|
|
67
|
+
*/
|
|
68
|
+
function readParent(body) {
|
|
69
|
+
const found = [];
|
|
70
|
+
for (const line of String(body == null ? '' : body).replace(/\r\n/g, '\n').split('\n')) {
|
|
71
|
+
if (/^\s/.test(line)) continue;
|
|
72
|
+
const p = decodeParent(line);
|
|
73
|
+
if (p) found.push(p);
|
|
74
|
+
}
|
|
75
|
+
if (!found.length) return null;
|
|
76
|
+
const pick = found.find((p) => p.form === 'comment') || found[0];
|
|
77
|
+
const key = (p) => `${p.repo || ''}#${p.number}`;
|
|
78
|
+
return { ...pick, conflict: new Set(found.map(key)).size > 1 };
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The child-body block an adapter writes: the comment, then the visible line. */
|
|
82
|
+
function encodeParentBlock({ repo, number } = {}) {
|
|
83
|
+
return `${encodeParent({ repo, number, form: 'comment' })}\n${encodeParent({ repo, number, form: 'line' })}`;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
// ── close reason ─────────────────────────────────────────────────────────────────────────────
|
|
87
|
+
|
|
88
|
+
const CLOSE_REASONS = Object.freeze(['completed', 'not-planned']);
|
|
89
|
+
const CLOSE_REASON_COMMENT_RE = /^<!-- colab:close-reason reason=(\S+) -->$/;
|
|
90
|
+
const CLOSE_REASON_LINE_RE = /^Close reason: (\S+)$/;
|
|
91
|
+
|
|
92
|
+
/** `{reason, form: 'comment'|'line'}` → the marker. Throws on a reason outside the closed set. */
|
|
93
|
+
function encodeCloseReason({ reason, form = 'comment' } = {}) {
|
|
94
|
+
if (!CLOSE_REASONS.includes(reason)) throw new TypeError(`encodeCloseReason: unknown reason ${JSON.stringify(reason)}`);
|
|
95
|
+
if (form === 'comment') return `<!-- colab:close-reason reason=${reason} -->`;
|
|
96
|
+
if (form === 'line') return `Close reason: ${reason}`;
|
|
97
|
+
throw new TypeError(`encodeCloseReason: unknown form ${JSON.stringify(form)}`);
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** ONE marker (whole) → `{reason, form}`, or null — including for a reason outside the closed set. */
|
|
101
|
+
function decodeCloseReason(marker) {
|
|
102
|
+
const s = String(marker == null ? '' : marker).trim();
|
|
103
|
+
for (const [form, re] of [['comment', CLOSE_REASON_COMMENT_RE], ['line', CLOSE_REASON_LINE_RE]]) {
|
|
104
|
+
const m = re.exec(s);
|
|
105
|
+
if (m) return CLOSE_REASONS.includes(m[1]) ? { reason: m[1], form } : null;
|
|
106
|
+
}
|
|
107
|
+
return null;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** The close-reason block an adapter posts: the comment, then the visible line. */
|
|
111
|
+
function encodeCloseReasonBlock(reason) {
|
|
112
|
+
return `${encodeCloseReason({ reason, form: 'comment' })}\n${encodeCloseReason({ reason, form: 'line' })}`;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* The close reason of an item → `'completed' | 'not-planned'`, or null. `state` is the item's state
|
|
117
|
+
* now; anything but `closed` (case-insensitive) reads null whatever the comments say. Otherwise the
|
|
118
|
+
* NEWEST comment (by `createdAt`) carrying a valid marker on one of its lines decides; within one
|
|
119
|
+
* comment the comment form wins over the line form.
|
|
120
|
+
*/
|
|
121
|
+
function readCloseReason({ state, comments } = {}) {
|
|
122
|
+
if (String(state || '').toLowerCase() !== 'closed') return null;
|
|
123
|
+
const sorted = [...(Array.isArray(comments) ? comments : [])]
|
|
124
|
+
.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
|
|
125
|
+
for (const c of sorted) {
|
|
126
|
+
const found = String((c && c.body) || '').replace(/\r\n/g, '\n').split('\n')
|
|
127
|
+
.filter((l) => !/^\s/.test(l)).map(decodeCloseReason).filter(Boolean);
|
|
128
|
+
if (found.length) return (found.find((f) => f.form === 'comment') || found[0]).reason;
|
|
129
|
+
}
|
|
130
|
+
return null;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
module.exports = {
|
|
134
|
+
PARENT_COMMENT_RE, PARENT_LINE_RE,
|
|
135
|
+
encodeParentRef, decodeParentRef, encodeParent, decodeParent, readParent, encodeParentBlock,
|
|
136
|
+
CLOSE_REASONS, CLOSE_REASON_COMMENT_RE, CLOSE_REASON_LINE_RE,
|
|
137
|
+
encodeCloseReason, decodeCloseReason, encodeCloseReasonBlock, readCloseReason,
|
|
138
|
+
};
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
// Types for tools/lib/codec/release.js (#498) — see index.d.ts.
|
|
2
|
+
|
|
3
|
+
export const VERSION_RE: RegExp;
|
|
4
|
+
export const TRACKING_MARKER_RE: RegExp;
|
|
5
|
+
export const RELEASE_EVENT_RE: RegExp;
|
|
6
|
+
|
|
7
|
+
export function encodeTrackingMarker(version: string): string;
|
|
8
|
+
/** The canonical `vX.Y.Z` a body's tracking marker declares, or null. */
|
|
9
|
+
export function decodeTrackingMarker(body: string | null | undefined): string | null;
|
|
10
|
+
|
|
11
|
+
/** Keys are written in the object's own order — part of the wire format. */
|
|
12
|
+
export function encodeReleaseEvent(fields: Record<string, string | number>): string;
|
|
13
|
+
export function decodeReleaseEvent(marker: string | null | undefined): Record<string, string> | null;
|
|
14
|
+
|
|
15
|
+
export function encodeReleasedComment(c?: { version: string; sha: string }): string;
|
|
16
|
+
/** `sha` is the 7-character form the comment carries. */
|
|
17
|
+
export function decodeReleasedComment(body: string | null | undefined): { version: string; sha: string } | null;
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* CODEC (#498, epic #496): the RELEASE-RUNG markers `colab release finalize` writes to a tracker
|
|
4
|
+
* (CONVENTIONS.md §6, *The release rung*), as encode/decode pairs. Pure and synchronous.
|
|
5
|
+
*
|
|
6
|
+
* tracking marker — `<!-- colab:release version=vX.Y.Z -->`, the first line of a tracking
|
|
7
|
+
* issue's body. Only the marker identifies the version, never the title.
|
|
8
|
+
* event marker — `<!-- colab:release-event k=v … -->`, one per thing announced on the
|
|
9
|
+
* tracking issue, keys in the order written. Its exact presence is what makes
|
|
10
|
+
* a re-run post nothing twice, so key order is part of the wire format.
|
|
11
|
+
* released comment — the event marker `released=vX.Y.Z` plus one visible line, posted once on
|
|
12
|
+
* each issue a release carried.
|
|
13
|
+
*
|
|
14
|
+
* Deciding which candidate, which period, and whether to finalize stays in
|
|
15
|
+
* tools/lib/release-finalize.js, which re-exports these under the names it always had.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
|
|
19
|
+
const TRACKING_MARKER_RE = /<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
|
|
20
|
+
const RELEASE_EVENT_RE = /^<!-- colab:release-event((?: [^\s=]+=\S*)+) -->$/;
|
|
21
|
+
const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nReleased in \*\*(\S+)\*\* \(`([^`]*)`\)\.$/;
|
|
22
|
+
|
|
23
|
+
/** `vX.Y.Z` → the tracking marker. */
|
|
24
|
+
function encodeTrackingMarker(version) { return `<!-- colab:release version=${version} -->`; }
|
|
25
|
+
|
|
26
|
+
/** The version a body's tracking marker declares, or null — a marker naming a non-canonical
|
|
27
|
+
* version (a leading zero) declares nothing. */
|
|
28
|
+
function decodeTrackingMarker(body) {
|
|
29
|
+
const m = TRACKING_MARKER_RE.exec(String(body || ''));
|
|
30
|
+
return m && VERSION_RE.test(m[1]) ? m[1] : null;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** `{k: v, …}` → `<!-- colab:release-event k=v … -->`, keys in the order given. */
|
|
34
|
+
function encodeReleaseEvent(fields) {
|
|
35
|
+
return `<!-- colab:release-event ${Object.entries(fields).map(([k, v]) => `${k}=${v}`).join(' ')} -->`;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** An event marker (the whole string) → its fields as strings, in written order; null if not one. */
|
|
39
|
+
function decodeReleaseEvent(marker) {
|
|
40
|
+
const m = RELEASE_EVENT_RE.exec(String(marker == null ? '' : marker).trim());
|
|
41
|
+
if (!m) return null;
|
|
42
|
+
const out = {};
|
|
43
|
+
for (const pair of m[1].trim().split(' ')) {
|
|
44
|
+
const i = pair.indexOf('=');
|
|
45
|
+
const k = pair.slice(0, i);
|
|
46
|
+
if (Object.prototype.hasOwnProperty.call(out, k)) return null; // a repeated key cannot round-trip
|
|
47
|
+
out[k] = pair.slice(i + 1);
|
|
48
|
+
}
|
|
49
|
+
return out;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** `{version, sha}` → the "released in" comment; `sha` is shortened to 7 characters. */
|
|
53
|
+
function encodeReleasedComment({ version, sha } = {}) {
|
|
54
|
+
return `${encodeReleaseEvent({ released: version })}\nReleased in **${version}** (\`${String(sha || '').slice(0, 7)}\`).`;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** A "released in" comment → `{version, sha}` (sha as written, 7 characters), or null. */
|
|
58
|
+
function decodeReleasedComment(body) {
|
|
59
|
+
const m = RELEASED_COMMENT_RE.exec(String(body == null ? '' : body).replace(/\r\n/g, '\n').trim());
|
|
60
|
+
if (!m || m[1] !== m[2]) return null;
|
|
61
|
+
return { version: m[1], sha: m[3] };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
module.exports = {
|
|
65
|
+
VERSION_RE, TRACKING_MARKER_RE, RELEASE_EVENT_RE,
|
|
66
|
+
encodeTrackingMarker, decodeTrackingMarker,
|
|
67
|
+
encodeReleaseEvent, decodeReleaseEvent,
|
|
68
|
+
encodeReleasedComment, decodeReleasedComment,
|
|
69
|
+
};
|