@starci/hfs 4.7.39 → 4.7.40
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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 4.7.40 - 2026-10-26
|
|
4
|
+
- Fixed: the next release is derived within the candidate's own tag family, so legacy tags of other families no longer outrank the runtime line (`release cut` and the release-definition guard).
|
|
5
|
+
|
|
3
6
|
## 4.7.39 - 2026-10-26
|
|
4
7
|
- Added: R258 follows the active cron schedule and accepts a declared outbox (`sides.be.queueOutbox`), and the optional slot `app.scripts.integration` carries integration scripts.
|
|
5
8
|
- Fixed: the lite scaffold templates, barrels and dev README follow the lite scaffold end-to-end fixes.
|
package/package.json
CHANGED
|
@@ -91,14 +91,14 @@ pins:
|
|
|
91
91
|
source: packages/test-world/package.json
|
|
92
92
|
why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
|
|
93
93
|
'@starci/cli':
|
|
94
|
-
version: 1.7.
|
|
94
|
+
version: 1.7.40
|
|
95
95
|
group: starci
|
|
96
96
|
install: registry
|
|
97
97
|
side: both
|
|
98
98
|
source: packages/cli/package.json
|
|
99
99
|
why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
|
|
100
100
|
'@starci/hfs':
|
|
101
|
-
version: 4.7.
|
|
101
|
+
version: 4.7.40
|
|
102
102
|
group: starci
|
|
103
103
|
install: registry
|
|
104
104
|
side: both
|
|
@@ -1,204 +1,204 @@
|
|
|
1
|
-
// release-definition.mjs - what makes a commit of the runtime repository a RELEASE commit, the one definition shared by the
|
|
2
|
-
// pre-push hook (scripts/guards/release-push-gate.mjs) and the release cut (scripts/supervisor/release-cut.mjs). The remote
|
|
3
|
-
// main of the runtime moves exactly when a release is cut, so a push of main or of a v* tag is judged against this list:
|
|
4
|
-
// RELEASE_VERSION_UNCHANGED package.json `version` at the pushed commit differs from the version at the remote main's head
|
|
5
|
-
// RELEASE_VERSION_NOT_NEXT that version is the next release after the highest v* tag (scripts/lib/release-version.mjs, owner ruling release-waves):
|
|
6
|
-
// the next wave alpha.N.M+1 of its line or the next line alpha.N+1, never the legacy -fix form
|
|
7
|
-
// RELEASE_TAG_VERSION the release tag is v<version> of the pushed commit
|
|
8
|
-
// RELEASE_CHANGELOG_SECTION CHANGELOG.md holds `## [<version>] - <date>` (a dated heading) with no unfinished marker (R222)
|
|
9
|
-
// RELEASE_TAG_MISSING an ANNOTATED tag v<version> points at the pushed commit
|
|
10
|
-
// RELEASE_RECEIPT_MISSING the L4 record of exactly this commit (scripts/guards/release-record.mjs, written by the cut) names this tag
|
|
11
|
-
// RELEASE_RECEIPT_INCOMPLETE that record holds a green row for each of RECEIPT_STEPS (the package clean-test, the scaffold e2e and the checks) (RAN on this commit or reused from another with the identical input digest, the record's `reusedFrom` names it; owner ruling speed-flow, 2026-10-25)
|
|
12
|
-
// RELEASE_SUITE_MODE the record says `suite: ci` (the Linux parity delegated to CI) while the checked-out config says `local`, or it lists no delegated linux-parity: a record never claims the mode by
|
|
13
|
-
// itself (scripts/guards/release-suite-mode.mjs); both modes ask for the same root rows, the runtime has no spec suite to delegate (owner ruling no-runtime-specs)
|
|
14
|
-
// Each finding names what is missing and the command that produces it. Pure over the git reads; no bypass.
|
|
15
|
-
import { catFile } from '../api/git/cat-file.mjs';
|
|
16
|
-
import { revParseQuery } from '../api/git/rev-parse-query.mjs';
|
|
17
|
-
import { show } from '../api/git/show.mjs';
|
|
18
|
-
import { tag as gitTag } from '../api/git/tag.mjs';
|
|
19
|
-
import { mergeBaseQuery } from '../api/git/merge-base-query.mjs';
|
|
20
|
-
import { pathKey, realPath } from '../lib/path-key.mjs';
|
|
21
|
-
import { changelogSection, releaseNotesFindings } from '../hfs/runtime-rules/release-notes.mjs';
|
|
22
|
-
import { nextReleases, releaseVersionRefusal, taggedVersions } from '../lib/release-version.mjs';
|
|
23
|
-
import { readL4Record } from './release-record.mjs';
|
|
24
|
-
import { suiteModeOf } from './release-suite-mode.mjs';
|
|
25
|
-
|
|
26
|
-
/** The rows the L4 record must hold green, run on the commit or reused from an identical-digest row of another, in either suite mode: the package clean-test, the scaffold e2e and the checks (the runtime's real tests). */
|
|
27
|
-
export const RECEIPT_STEPS = Object.freeze(['npm run test:packages', 'npm run test:e2e', 'npm run check']);
|
|
28
|
-
const CUT_COMMAND = (tag) => `starci release cut --tag ${tag}`;
|
|
29
|
-
const REGEX_SPECIALS = /[.*+?^$()|[\]{}\\]/g;
|
|
30
|
-
const HEADING_HEAD = String.raw`^## \[`;
|
|
31
|
-
const DATED_HEADING_TAIL = String.raw`\] — \d{4}-\d{2}-\d{2}\s*$`;
|
|
32
|
-
const DATED_HEADING = (version) => new RegExp([HEADING_HEAD, version.replaceAll(REGEX_SPECIALS, String.raw`\$&`), DATED_HEADING_TAIL].join(''), 'mu');
|
|
33
|
-
|
|
34
|
-
const finding = (code, missing, fix) => ({ code, missing, fix });
|
|
35
|
-
const gitText = (verb, args, cwd) => {
|
|
36
|
-
const r = verb(args, { cwd, timeout: 60_000 });
|
|
37
|
-
return r.status === 0 ? String(r.stdout ?? '') : null;
|
|
38
|
-
};
|
|
39
|
-
|
|
40
|
-
/** The package.json version of `commit`, or null when the commit or its manifest cannot be read. */
|
|
41
|
-
export function versionAt(cwd, commit) {
|
|
42
|
-
const text = gitText(show, [`${commit}:package.json`], cwd);
|
|
43
|
-
try { return text === null ? null : JSON.parse(text).version ?? null; } catch { return null; }
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
const releaseUnknown = (why) => ({ ok: false, status: 'unknown', why });
|
|
47
|
-
const ineligibleRelease = (explicit, why) => explicit ? releaseUnknown(why) : { ok: true, candidate: null };
|
|
48
|
-
|
|
49
|
-
/** A runtime Git root's nearest annotated, manifest-bound release; enclosing application history is inapplicable. */
|
|
50
|
-
export function releaseTagOf({ repo, tag = null, excludeHead = false }) {
|
|
51
|
-
const history = runtimeGitHistory(repo);
|
|
52
|
-
if (!history.ok) return history;
|
|
53
|
-
const listed = tag === null ? gitText(gitTag, ['--merged', 'HEAD', '--list', 'v*'], repo) : tag;
|
|
54
|
-
if (listed === null) return releaseUnknown('release tags are unreadable');
|
|
55
|
-
const candidates = [];
|
|
56
|
-
for (const named of listed.split(/\r?\n/).filter(Boolean)) {
|
|
57
|
-
const result = releaseCandidate({ repo, named, current: history.head, explicit: tag !== null, excludeHead });
|
|
58
|
-
if (!result.ok) return result;
|
|
59
|
-
if (result.candidate) candidates.push(result.candidate);
|
|
60
|
-
}
|
|
61
|
-
return nearestRelease(repo, candidates);
|
|
62
|
-
}
|
|
63
|
-
|
|
64
|
-
/** Runtime history exists only at its own Git top-level with a readable HEAD and full ancestry. */
|
|
65
|
-
function runtimeGitHistory(repo) {
|
|
66
|
-
const top = revParseQuery(['--show-toplevel'], { cwd: repo });
|
|
67
|
-
if (top.status !== 0) {
|
|
68
|
-
if (/not a git repository/i.test(String(top.stderr ?? ''))) return { ok: false, status: 'no-repository', why: 'release history requires a Git repository' };
|
|
69
|
-
return releaseUnknown('release repository identity is unreadable');
|
|
70
|
-
}
|
|
71
|
-
const gitRoot = String(top.stdout ?? '').trim();
|
|
72
|
-
if (!gitRoot) return releaseUnknown('release repository root is unreadable');
|
|
73
|
-
if (pathKey(realPath(gitRoot)) !== pathKey(realPath(repo))) return { ok: false, status: 'no-runtime-repository', why: 'the runtime copy is inside an enclosing Git repository; its history belongs to that repository' };
|
|
74
|
-
const head = gitText(revParseQuery, ['HEAD'], repo)?.trim();
|
|
75
|
-
if (!head) return releaseUnknown('release history HEAD is unreadable');
|
|
76
|
-
if (gitText(revParseQuery, ['--is-shallow-repository'], repo)?.trim() !== 'false') return releaseUnknown('release history is shallow or unreadable; fetch complete release history');
|
|
77
|
-
return { ok: true, head };
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
/** A candidate binds annotation, peeled commit, manifest spelling and ancestry; default discovery omits ineligible tags. */
|
|
81
|
-
function releaseCandidate({ repo, named, current, explicit, excludeHead }) {
|
|
82
|
-
const kind = gitText(catFile, ['-t', `refs/tags/${named}`], repo)?.trim();
|
|
83
|
-
const head = gitText(revParseQuery, [`refs/tags/${named}^{commit}`], repo)?.trim();
|
|
84
|
-
if (!kind || !head) return releaseUnknown(`release tag ${named} is unreadable`);
|
|
85
|
-
if (kind !== 'tag') return ineligibleRelease(explicit, `release tag ${named} is not annotated`);
|
|
86
|
-
const version = versionAt(repo, head);
|
|
87
|
-
if (!version) return releaseUnknown(`release manifest of ${named} is unreadable`);
|
|
88
|
-
if (named !== `v${version}`) return ineligibleRelease(explicit, `release tag ${named} differs from its manifest version ${version}`);
|
|
89
|
-
const reachable = releaseAncestor(repo, head, current);
|
|
90
|
-
if (reachable === null) return releaseUnknown(`release ancestry of ${named} is unreadable`);
|
|
91
|
-
if (!reachable) return ineligibleRelease(explicit, `release tag ${named} is not merged in HEAD`);
|
|
92
|
-
if (excludeHead && head === current) return { ok: true, candidate: null };
|
|
93
|
-
return { ok: true, candidate: { tag: named, head } };
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
/** Only one unsuperseded release ancestor proves a boundary; incomparable releases hold. */
|
|
97
|
-
function nearestRelease(repo, candidates) {
|
|
98
|
-
if (!candidates.length) return releaseUnknown('no eligible annotated, manifest-bound release tag is merged in HEAD');
|
|
99
|
-
const nearest = [];
|
|
100
|
-
for (const candidate of candidates) {
|
|
101
|
-
const superseded = candidateSuperseded(repo, candidate, candidates);
|
|
102
|
-
if (superseded === null) return releaseUnknown('release ancestry between tags is unreadable');
|
|
103
|
-
if (!superseded) nearest.push(candidate);
|
|
104
|
-
}
|
|
105
|
-
if (nearest.length !== 1) return releaseUnknown(`release history is ambiguous: ${nearest.map((entry) => entry.tag).join(', ')}`);
|
|
106
|
-
return { ok: true, ...nearest[0] };
|
|
107
|
-
}
|
|
108
|
-
|
|
109
|
-
/** A release loses its boundary only to a proven descendant release, never to a date or version sort. */
|
|
110
|
-
function candidateSuperseded(repo, candidate, candidates) {
|
|
111
|
-
for (const other of candidates) {
|
|
112
|
-
if (candidate.head === other.head) continue;
|
|
113
|
-
const older = releaseAncestor(repo, candidate.head, other.head);
|
|
114
|
-
if (older === null) return null;
|
|
115
|
-
if (older) return true;
|
|
116
|
-
}
|
|
117
|
-
return false;
|
|
118
|
-
}
|
|
119
|
-
|
|
120
|
-
/** Missing Git proof is distinct from a proven non-ancestor. */
|
|
121
|
-
function releaseAncestor(repo, before, after) {
|
|
122
|
-
const result = mergeBaseQuery(['--is-ancestor', before, after], { cwd: repo });
|
|
123
|
-
if (result.status === 0) return true;
|
|
124
|
-
if (result.status === 1) return false;
|
|
125
|
-
return null;
|
|
126
|
-
}
|
|
127
|
-
|
|
128
|
-
/** The next releases named from the released versions, for a fix text: "v<wave> or v<line>". */
|
|
129
|
-
const nextNamed = (released) => {
|
|
130
|
-
const next = nextReleases(released);
|
|
131
|
-
return next ? `v${next.wave} or v${next.line}` : 'v<new version>';
|
|
132
|
-
};
|
|
133
|
-
|
|
134
|
-
function versionFindings({ cwd, remoteCommit, version, released }) {
|
|
135
|
-
if (!remoteCommit) return [];
|
|
136
|
-
const remoteVersion = versionAt(cwd, remoteCommit);
|
|
137
|
-
if (remoteVersion === null) return [finding('RELEASE_REMOTE_HEAD_UNKNOWN', `the remote main head ${remoteCommit.slice(0, 9)} is not in this repository, so its version cannot be compared`, 'git fetch origin main')];
|
|
138
|
-
if (remoteVersion === version) return [finding('RELEASE_VERSION_UNCHANGED', `package.json version ${version} is the version the remote main already carries`, `set package.json version to the next release, move the CHANGELOG section to it, commit, then ${CUT_COMMAND(nextNamed(released))}`)];
|
|
139
|
-
return [];
|
|
140
|
-
}
|
|
141
|
-
|
|
142
|
-
/** The version must be the next release after the highest v* tag other than its own: a wave alpha.N.M is counted, never guessed. */
|
|
143
|
-
function nextReleaseFindings({ version, released }) {
|
|
144
|
-
if (released === null) return [finding('RELEASE_VERSION_NOT_NEXT', 'the v* tags are unreadable, so the next release cannot be derived', 'git fetch --tags')];
|
|
145
|
-
const refusal = releaseVersionRefusal(version, released);
|
|
146
|
-
return refusal ? [finding('RELEASE_VERSION_NOT_NEXT', refusal, `set package.json version to the next release, move the CHANGELOG section to it, commit, then ${CUT_COMMAND(nextNamed(released.filter((entry) => entry !== version)))}`)] : [];
|
|
147
|
-
}
|
|
148
|
-
|
|
149
|
-
function changelogFindings({ cwd, commit, version, tag }) {
|
|
150
|
-
const changelog = gitText(show, [`${commit}:CHANGELOG.md`], cwd);
|
|
151
|
-
if (changelog === null) return [finding('RELEASE_CHANGELOG_SECTION', 'CHANGELOG.md is not readable at the pushed commit', 'restore CHANGELOG.md')];
|
|
152
|
-
const notes = releaseNotesFindings({ tags: [tag], changelog });
|
|
153
|
-
if (notes.length) return notes.map((n) => finding('RELEASE_CHANGELOG_SECTION', n.message, 'finish the CHANGELOG section of the release (no in-preparation mark, no open marker), commit'));
|
|
154
|
-
if (!changelogSection(changelog, version).found || !DATED_HEADING(version).test(changelog)) return [finding('RELEASE_CHANGELOG_SECTION', `CHANGELOG.md has no dated heading "## [${version}] — YYYY-MM-DD"`, `date the heading of the ${version} section, commit`)];
|
|
155
|
-
return [];
|
|
156
|
-
}
|
|
157
|
-
|
|
158
|
-
function tagFindings({ cwd, commit, tag }) {
|
|
159
|
-
const kind = gitText(catFile, ['-t', `refs/tags/${tag}`], cwd)?.trim();
|
|
160
|
-
const target = gitText(revParseQuery, [`refs/tags/${tag}^{commit}`], cwd)?.trim();
|
|
161
|
-
if (kind === 'tag' && target === commit) return [];
|
|
162
|
-
return [finding('RELEASE_TAG_MISSING', `no annotated tag ${tag} points at ${commit.slice(0, 9)}`, CUT_COMMAND(tag))];
|
|
163
|
-
}
|
|
164
|
-
|
|
165
|
-
/** The finding of a record that claims the delegated mode without the checked-out config saying so (or without naming the delegated linux-parity row), else null. */
|
|
166
|
-
function suiteModeFinding({ record, cwd, commit, tag }) {
|
|
167
|
-
if (record.suite !== 'ci') return null;
|
|
168
|
-
if (suiteModeOf(cwd) !== 'ci') return finding('RELEASE_SUITE_MODE', `the release record of ${commit.slice(0, 9)} says suite: ci, but this checkout's config.yaml release.suite is not ci: a record does not choose the mode`, `set release.suite: ci in config.yaml (the owner's choice), or ${CUT_COMMAND(tag)} under suite: local`);
|
|
169
|
-
if (!(record.delegated ?? []).some((row) => row?.name === 'linux-parity')) return finding('RELEASE_SUITE_MODE', `the suite: ci record of ${commit.slice(0, 9)} does not list linux-parity as delegated`, CUT_COMMAND(tag));
|
|
170
|
-
return null;
|
|
171
|
-
}
|
|
172
|
-
|
|
173
|
-
function receiptFindings({ cwd, commit, tag }) {
|
|
174
|
-
const record = readL4Record({ repo: cwd, head: commit, tag });
|
|
175
|
-
if (!record) return [finding('RELEASE_RECEIPT_MISSING', `no release record for exactly ${commit.slice(0, 9)} and ${tag}: the package clean-test, the scaffold e2e and the check did not run green on this commit`, CUT_COMMAND(tag))];
|
|
176
|
-
const mode = suiteModeFinding({ record, cwd, commit, tag });
|
|
177
|
-
if (mode) return [mode];
|
|
178
|
-
// A row reused from another commit (reusedFrom) counts: the cut reuses a row only when its input digest is identical (owner ruling speed-flow, 2026-10-25), and the record names the commit it came from.
|
|
179
|
-
const green = new Set((record.logs ?? []).filter((row) => row?.ok === true).map((row) => row.name));
|
|
180
|
-
const absent = RECEIPT_STEPS.filter((name) => !green.has(name));
|
|
181
|
-
return absent.length ? [finding('RELEASE_RECEIPT_INCOMPLETE', `the release record of ${commit.slice(0, 9)} has no green row for: ${absent.join(', ')}`, CUT_COMMAND(tag))] : [];
|
|
182
|
-
}
|
|
183
|
-
|
|
184
|
-
/**
|
|
185
|
-
* The findings that keep `commit` from being a release commit of the repository at `cwd`: [{code, missing, fix}], [] when it is one.
|
|
186
|
-
* `remoteCommit` is the remote main's head being replaced (null for a tag push or a first push); `tag` the release tag (default v<version>);
|
|
187
|
-
* `needTag` / `needReceipt` are false only for the cut's early look, before it has created the tag and run the suite.
|
|
188
|
-
*/
|
|
189
|
-
export function releaseFindings({ cwd, commit, remoteCommit = null, tag = null, needTag = true, needReceipt = true }) {
|
|
190
|
-
const version = versionAt(cwd, commit);
|
|
191
|
-
if (!version) return [finding('RELEASE_VERSION_UNREADABLE', `package.json at ${commit.slice(0, 9)} has no readable version`, 'restore package.json')];
|
|
192
|
-
const expected = `v${version}`;
|
|
193
|
-
const named = tag ?? expected;
|
|
194
|
-
if (named !== expected) return [finding('RELEASE_TAG_VERSION', `the tag ${named} is not v${version}, the version of ${commit.slice(0, 9)}`, `tag v${version}, or set package.json version to ${named.replace(/^v/, '')}`)];
|
|
195
|
-
const listed = gitText(gitTag, ['--list', 'v*'], cwd);
|
|
196
|
-
const released = listed === null ? null : taggedVersions(listed);
|
|
197
|
-
return [
|
|
198
|
-
...versionFindings({ cwd, remoteCommit, version, released: released ?? [] }),
|
|
199
|
-
...nextReleaseFindings({ version, released }),
|
|
200
|
-
...changelogFindings({ cwd, commit, version, tag: named }),
|
|
201
|
-
...(needTag ? tagFindings({ cwd, commit, tag: named }) : []),
|
|
202
|
-
...(needReceipt ? receiptFindings({ cwd, commit, tag: named }) : []),
|
|
203
|
-
];
|
|
204
|
-
}
|
|
1
|
+
// release-definition.mjs - what makes a commit of the runtime repository a RELEASE commit, the one definition shared by the
|
|
2
|
+
// pre-push hook (scripts/guards/release-push-gate.mjs) and the release cut (scripts/supervisor/release-cut.mjs). The remote
|
|
3
|
+
// main of the runtime moves exactly when a release is cut, so a push of main or of a v* tag is judged against this list:
|
|
4
|
+
// RELEASE_VERSION_UNCHANGED package.json `version` at the pushed commit differs from the version at the remote main's head
|
|
5
|
+
// RELEASE_VERSION_NOT_NEXT that version is the next release after the highest v* tag (scripts/lib/release-version.mjs, owner ruling release-waves):
|
|
6
|
+
// the next wave alpha.N.M+1 of its line or the next line alpha.N+1, never the legacy -fix form
|
|
7
|
+
// RELEASE_TAG_VERSION the release tag is v<version> of the pushed commit
|
|
8
|
+
// RELEASE_CHANGELOG_SECTION CHANGELOG.md holds `## [<version>] - <date>` (a dated heading) with no unfinished marker (R222)
|
|
9
|
+
// RELEASE_TAG_MISSING an ANNOTATED tag v<version> points at the pushed commit
|
|
10
|
+
// RELEASE_RECEIPT_MISSING the L4 record of exactly this commit (scripts/guards/release-record.mjs, written by the cut) names this tag
|
|
11
|
+
// RELEASE_RECEIPT_INCOMPLETE that record holds a green row for each of RECEIPT_STEPS (the package clean-test, the scaffold e2e and the checks) (RAN on this commit or reused from another with the identical input digest, the record's `reusedFrom` names it; owner ruling speed-flow, 2026-10-25)
|
|
12
|
+
// RELEASE_SUITE_MODE the record says `suite: ci` (the Linux parity delegated to CI) while the checked-out config says `local`, or it lists no delegated linux-parity: a record never claims the mode by
|
|
13
|
+
// itself (scripts/guards/release-suite-mode.mjs); both modes ask for the same root rows, the runtime has no spec suite to delegate (owner ruling no-runtime-specs)
|
|
14
|
+
// Each finding names what is missing and the command that produces it. Pure over the git reads; no bypass.
|
|
15
|
+
import { catFile } from '../api/git/cat-file.mjs';
|
|
16
|
+
import { revParseQuery } from '../api/git/rev-parse-query.mjs';
|
|
17
|
+
import { show } from '../api/git/show.mjs';
|
|
18
|
+
import { tag as gitTag } from '../api/git/tag.mjs';
|
|
19
|
+
import { mergeBaseQuery } from '../api/git/merge-base-query.mjs';
|
|
20
|
+
import { pathKey, realPath } from '../lib/path-key.mjs';
|
|
21
|
+
import { changelogSection, releaseNotesFindings } from '../hfs/runtime-rules/release-notes.mjs';
|
|
22
|
+
import { nextReleases, releaseVersionRefusal, taggedVersions } from '../lib/release-version.mjs';
|
|
23
|
+
import { readL4Record } from './release-record.mjs';
|
|
24
|
+
import { suiteModeOf } from './release-suite-mode.mjs';
|
|
25
|
+
|
|
26
|
+
/** The rows the L4 record must hold green, run on the commit or reused from an identical-digest row of another, in either suite mode: the package clean-test, the scaffold e2e and the checks (the runtime's real tests). */
|
|
27
|
+
export const RECEIPT_STEPS = Object.freeze(['npm run test:packages', 'npm run test:e2e', 'npm run check']);
|
|
28
|
+
const CUT_COMMAND = (tag) => `starci release cut --tag ${tag}`;
|
|
29
|
+
const REGEX_SPECIALS = /[.*+?^$()|[\]{}\\]/g;
|
|
30
|
+
const HEADING_HEAD = String.raw`^## \[`;
|
|
31
|
+
const DATED_HEADING_TAIL = String.raw`\] — \d{4}-\d{2}-\d{2}\s*$`;
|
|
32
|
+
const DATED_HEADING = (version) => new RegExp([HEADING_HEAD, version.replaceAll(REGEX_SPECIALS, String.raw`\$&`), DATED_HEADING_TAIL].join(''), 'mu');
|
|
33
|
+
|
|
34
|
+
const finding = (code, missing, fix) => ({ code, missing, fix });
|
|
35
|
+
const gitText = (verb, args, cwd) => {
|
|
36
|
+
const r = verb(args, { cwd, timeout: 60_000 });
|
|
37
|
+
return r.status === 0 ? String(r.stdout ?? '') : null;
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
/** The package.json version of `commit`, or null when the commit or its manifest cannot be read. */
|
|
41
|
+
export function versionAt(cwd, commit) {
|
|
42
|
+
const text = gitText(show, [`${commit}:package.json`], cwd);
|
|
43
|
+
try { return text === null ? null : JSON.parse(text).version ?? null; } catch { return null; }
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const releaseUnknown = (why) => ({ ok: false, status: 'unknown', why });
|
|
47
|
+
const ineligibleRelease = (explicit, why) => explicit ? releaseUnknown(why) : { ok: true, candidate: null };
|
|
48
|
+
|
|
49
|
+
/** A runtime Git root's nearest annotated, manifest-bound release; enclosing application history is inapplicable. */
|
|
50
|
+
export function releaseTagOf({ repo, tag = null, excludeHead = false }) {
|
|
51
|
+
const history = runtimeGitHistory(repo);
|
|
52
|
+
if (!history.ok) return history;
|
|
53
|
+
const listed = tag === null ? gitText(gitTag, ['--merged', 'HEAD', '--list', 'v*'], repo) : tag;
|
|
54
|
+
if (listed === null) return releaseUnknown('release tags are unreadable');
|
|
55
|
+
const candidates = [];
|
|
56
|
+
for (const named of listed.split(/\r?\n/).filter(Boolean)) {
|
|
57
|
+
const result = releaseCandidate({ repo, named, current: history.head, explicit: tag !== null, excludeHead });
|
|
58
|
+
if (!result.ok) return result;
|
|
59
|
+
if (result.candidate) candidates.push(result.candidate);
|
|
60
|
+
}
|
|
61
|
+
return nearestRelease(repo, candidates);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Runtime history exists only at its own Git top-level with a readable HEAD and full ancestry. */
|
|
65
|
+
function runtimeGitHistory(repo) {
|
|
66
|
+
const top = revParseQuery(['--show-toplevel'], { cwd: repo });
|
|
67
|
+
if (top.status !== 0) {
|
|
68
|
+
if (/not a git repository/i.test(String(top.stderr ?? ''))) return { ok: false, status: 'no-repository', why: 'release history requires a Git repository' };
|
|
69
|
+
return releaseUnknown('release repository identity is unreadable');
|
|
70
|
+
}
|
|
71
|
+
const gitRoot = String(top.stdout ?? '').trim();
|
|
72
|
+
if (!gitRoot) return releaseUnknown('release repository root is unreadable');
|
|
73
|
+
if (pathKey(realPath(gitRoot)) !== pathKey(realPath(repo))) return { ok: false, status: 'no-runtime-repository', why: 'the runtime copy is inside an enclosing Git repository; its history belongs to that repository' };
|
|
74
|
+
const head = gitText(revParseQuery, ['HEAD'], repo)?.trim();
|
|
75
|
+
if (!head) return releaseUnknown('release history HEAD is unreadable');
|
|
76
|
+
if (gitText(revParseQuery, ['--is-shallow-repository'], repo)?.trim() !== 'false') return releaseUnknown('release history is shallow or unreadable; fetch complete release history');
|
|
77
|
+
return { ok: true, head };
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** A candidate binds annotation, peeled commit, manifest spelling and ancestry; default discovery omits ineligible tags. */
|
|
81
|
+
function releaseCandidate({ repo, named, current, explicit, excludeHead }) {
|
|
82
|
+
const kind = gitText(catFile, ['-t', `refs/tags/${named}`], repo)?.trim();
|
|
83
|
+
const head = gitText(revParseQuery, [`refs/tags/${named}^{commit}`], repo)?.trim();
|
|
84
|
+
if (!kind || !head) return releaseUnknown(`release tag ${named} is unreadable`);
|
|
85
|
+
if (kind !== 'tag') return ineligibleRelease(explicit, `release tag ${named} is not annotated`);
|
|
86
|
+
const version = versionAt(repo, head);
|
|
87
|
+
if (!version) return releaseUnknown(`release manifest of ${named} is unreadable`);
|
|
88
|
+
if (named !== `v${version}`) return ineligibleRelease(explicit, `release tag ${named} differs from its manifest version ${version}`);
|
|
89
|
+
const reachable = releaseAncestor(repo, head, current);
|
|
90
|
+
if (reachable === null) return releaseUnknown(`release ancestry of ${named} is unreadable`);
|
|
91
|
+
if (!reachable) return ineligibleRelease(explicit, `release tag ${named} is not merged in HEAD`);
|
|
92
|
+
if (excludeHead && head === current) return { ok: true, candidate: null };
|
|
93
|
+
return { ok: true, candidate: { tag: named, head } };
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Only one unsuperseded release ancestor proves a boundary; incomparable releases hold. */
|
|
97
|
+
function nearestRelease(repo, candidates) {
|
|
98
|
+
if (!candidates.length) return releaseUnknown('no eligible annotated, manifest-bound release tag is merged in HEAD');
|
|
99
|
+
const nearest = [];
|
|
100
|
+
for (const candidate of candidates) {
|
|
101
|
+
const superseded = candidateSuperseded(repo, candidate, candidates);
|
|
102
|
+
if (superseded === null) return releaseUnknown('release ancestry between tags is unreadable');
|
|
103
|
+
if (!superseded) nearest.push(candidate);
|
|
104
|
+
}
|
|
105
|
+
if (nearest.length !== 1) return releaseUnknown(`release history is ambiguous: ${nearest.map((entry) => entry.tag).join(', ')}`);
|
|
106
|
+
return { ok: true, ...nearest[0] };
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** A release loses its boundary only to a proven descendant release, never to a date or version sort. */
|
|
110
|
+
function candidateSuperseded(repo, candidate, candidates) {
|
|
111
|
+
for (const other of candidates) {
|
|
112
|
+
if (candidate.head === other.head) continue;
|
|
113
|
+
const older = releaseAncestor(repo, candidate.head, other.head);
|
|
114
|
+
if (older === null) return null;
|
|
115
|
+
if (older) return true;
|
|
116
|
+
}
|
|
117
|
+
return false;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** Missing Git proof is distinct from a proven non-ancestor. */
|
|
121
|
+
function releaseAncestor(repo, before, after) {
|
|
122
|
+
const result = mergeBaseQuery(['--is-ancestor', before, after], { cwd: repo });
|
|
123
|
+
if (result.status === 0) return true;
|
|
124
|
+
if (result.status === 1) return false;
|
|
125
|
+
return null;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** The next releases named from the released versions, for a fix text: "v<wave> or v<line>". */
|
|
129
|
+
const nextNamed = (released, version = null) => {
|
|
130
|
+
const next = nextReleases(released, version);
|
|
131
|
+
return next ? `v${next.wave} or v${next.line}` : 'v<new version>';
|
|
132
|
+
};
|
|
133
|
+
|
|
134
|
+
function versionFindings({ cwd, remoteCommit, version, released }) {
|
|
135
|
+
if (!remoteCommit) return [];
|
|
136
|
+
const remoteVersion = versionAt(cwd, remoteCommit);
|
|
137
|
+
if (remoteVersion === null) return [finding('RELEASE_REMOTE_HEAD_UNKNOWN', `the remote main head ${remoteCommit.slice(0, 9)} is not in this repository, so its version cannot be compared`, 'git fetch origin main')];
|
|
138
|
+
if (remoteVersion === version) return [finding('RELEASE_VERSION_UNCHANGED', `package.json version ${version} is the version the remote main already carries`, `set package.json version to the next release, move the CHANGELOG section to it, commit, then ${CUT_COMMAND(nextNamed(released, version))}`)];
|
|
139
|
+
return [];
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** The version must be the next release after the highest v* tag other than its own: a wave alpha.N.M is counted, never guessed. */
|
|
143
|
+
function nextReleaseFindings({ version, released }) {
|
|
144
|
+
if (released === null) return [finding('RELEASE_VERSION_NOT_NEXT', 'the v* tags are unreadable, so the next release cannot be derived', 'git fetch --tags')];
|
|
145
|
+
const refusal = releaseVersionRefusal(version, released);
|
|
146
|
+
return refusal ? [finding('RELEASE_VERSION_NOT_NEXT', refusal, `set package.json version to the next release, move the CHANGELOG section to it, commit, then ${CUT_COMMAND(nextNamed(released.filter((entry) => entry !== version), version))}`)] : [];
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
function changelogFindings({ cwd, commit, version, tag }) {
|
|
150
|
+
const changelog = gitText(show, [`${commit}:CHANGELOG.md`], cwd);
|
|
151
|
+
if (changelog === null) return [finding('RELEASE_CHANGELOG_SECTION', 'CHANGELOG.md is not readable at the pushed commit', 'restore CHANGELOG.md')];
|
|
152
|
+
const notes = releaseNotesFindings({ tags: [tag], changelog });
|
|
153
|
+
if (notes.length) return notes.map((n) => finding('RELEASE_CHANGELOG_SECTION', n.message, 'finish the CHANGELOG section of the release (no in-preparation mark, no open marker), commit'));
|
|
154
|
+
if (!changelogSection(changelog, version).found || !DATED_HEADING(version).test(changelog)) return [finding('RELEASE_CHANGELOG_SECTION', `CHANGELOG.md has no dated heading "## [${version}] — YYYY-MM-DD"`, `date the heading of the ${version} section, commit`)];
|
|
155
|
+
return [];
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
function tagFindings({ cwd, commit, tag }) {
|
|
159
|
+
const kind = gitText(catFile, ['-t', `refs/tags/${tag}`], cwd)?.trim();
|
|
160
|
+
const target = gitText(revParseQuery, [`refs/tags/${tag}^{commit}`], cwd)?.trim();
|
|
161
|
+
if (kind === 'tag' && target === commit) return [];
|
|
162
|
+
return [finding('RELEASE_TAG_MISSING', `no annotated tag ${tag} points at ${commit.slice(0, 9)}`, CUT_COMMAND(tag))];
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** The finding of a record that claims the delegated mode without the checked-out config saying so (or without naming the delegated linux-parity row), else null. */
|
|
166
|
+
function suiteModeFinding({ record, cwd, commit, tag }) {
|
|
167
|
+
if (record.suite !== 'ci') return null;
|
|
168
|
+
if (suiteModeOf(cwd) !== 'ci') return finding('RELEASE_SUITE_MODE', `the release record of ${commit.slice(0, 9)} says suite: ci, but this checkout's config.yaml release.suite is not ci: a record does not choose the mode`, `set release.suite: ci in config.yaml (the owner's choice), or ${CUT_COMMAND(tag)} under suite: local`);
|
|
169
|
+
if (!(record.delegated ?? []).some((row) => row?.name === 'linux-parity')) return finding('RELEASE_SUITE_MODE', `the suite: ci record of ${commit.slice(0, 9)} does not list linux-parity as delegated`, CUT_COMMAND(tag));
|
|
170
|
+
return null;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
function receiptFindings({ cwd, commit, tag }) {
|
|
174
|
+
const record = readL4Record({ repo: cwd, head: commit, tag });
|
|
175
|
+
if (!record) return [finding('RELEASE_RECEIPT_MISSING', `no release record for exactly ${commit.slice(0, 9)} and ${tag}: the package clean-test, the scaffold e2e and the check did not run green on this commit`, CUT_COMMAND(tag))];
|
|
176
|
+
const mode = suiteModeFinding({ record, cwd, commit, tag });
|
|
177
|
+
if (mode) return [mode];
|
|
178
|
+
// A row reused from another commit (reusedFrom) counts: the cut reuses a row only when its input digest is identical (owner ruling speed-flow, 2026-10-25), and the record names the commit it came from.
|
|
179
|
+
const green = new Set((record.logs ?? []).filter((row) => row?.ok === true).map((row) => row.name));
|
|
180
|
+
const absent = RECEIPT_STEPS.filter((name) => !green.has(name));
|
|
181
|
+
return absent.length ? [finding('RELEASE_RECEIPT_INCOMPLETE', `the release record of ${commit.slice(0, 9)} has no green row for: ${absent.join(', ')}`, CUT_COMMAND(tag))] : [];
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* The findings that keep `commit` from being a release commit of the repository at `cwd`: [{code, missing, fix}], [] when it is one.
|
|
186
|
+
* `remoteCommit` is the remote main's head being replaced (null for a tag push or a first push); `tag` the release tag (default v<version>);
|
|
187
|
+
* `needTag` / `needReceipt` are false only for the cut's early look, before it has created the tag and run the suite.
|
|
188
|
+
*/
|
|
189
|
+
export function releaseFindings({ cwd, commit, remoteCommit = null, tag = null, needTag = true, needReceipt = true }) {
|
|
190
|
+
const version = versionAt(cwd, commit);
|
|
191
|
+
if (!version) return [finding('RELEASE_VERSION_UNREADABLE', `package.json at ${commit.slice(0, 9)} has no readable version`, 'restore package.json')];
|
|
192
|
+
const expected = `v${version}`;
|
|
193
|
+
const named = tag ?? expected;
|
|
194
|
+
if (named !== expected) return [finding('RELEASE_TAG_VERSION', `the tag ${named} is not v${version}, the version of ${commit.slice(0, 9)}`, `tag v${version}, or set package.json version to ${named.replace(/^v/, '')}`)];
|
|
195
|
+
const listed = gitText(gitTag, ['--list', 'v*'], cwd);
|
|
196
|
+
const released = listed === null ? null : taggedVersions(listed);
|
|
197
|
+
return [
|
|
198
|
+
...versionFindings({ cwd, remoteCommit, version, released: released ?? [] }),
|
|
199
|
+
...nextReleaseFindings({ version, released }),
|
|
200
|
+
...changelogFindings({ cwd, commit, version, tag: named }),
|
|
201
|
+
...(needTag ? tagFindings({ cwd, commit, tag: named }) : []),
|
|
202
|
+
...(needReceipt ? receiptFindings({ cwd, commit, tag: named }) : []),
|
|
203
|
+
];
|
|
204
|
+
}
|
|
@@ -1,119 +1,134 @@
|
|
|
1
|
-
// release-version.mjs - the one reading of a release version (owner ruling release-waves). A prerelease `<label>.N` opens the release
|
|
2
|
-
// line N and `<label>.N.M` is the M-th release after it, a wave or a fix alike, so alpha.31 < alpha.31.1 < alpha.31.2 < alpha.32 in
|
|
3
|
-
// SemVer order. The next release is derived from the highest one already released, never guessed. The legacy `<label>.N-fix.K` still
|
|
4
|
-
// reads as release K after `<label>.N` and is never produced again. Pure: the callers read the tags and the registry.
|
|
5
|
-
|
|
6
|
-
const NUMERIC = /^(?:0|[1-9]\d*)$/;
|
|
7
|
-
const POSITIVE = /^[1-9]\d*$/;
|
|
8
|
-
const IDENTIFIERS = /^[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/;
|
|
9
|
-
const LEGACY_FIX = '-fix.';
|
|
10
|
-
|
|
11
|
-
/** {base, wave, legacy}: the release a version counts its waves from, and its wave M (0 for the release that opens the line). */
|
|
12
|
-
export function waveOf(version) {
|
|
13
|
-
const text = String(version ?? '').split('+')[0];
|
|
14
|
-
const fix = text.lastIndexOf(LEGACY_FIX);
|
|
15
|
-
const legacyWave = fix > 0 ? text.slice(fix + LEGACY_FIX.length) : '';
|
|
16
|
-
if (POSITIVE.test(legacyWave)) return { base: text.slice(0, fix), wave: Number(legacyWave), legacy: true };
|
|
17
|
-
const ids = text.split('.');
|
|
18
|
-
const counted = ids.length > 3 && POSITIVE.test(ids.at(-1)) && (text.includes('-') ? NUMERIC.test(ids.at(-2)) : ids.length === 4);
|
|
19
|
-
return counted ? { base: ids.slice(0, -1).join('.'), wave: Number(ids.at(-1)), legacy: false } : { base: text, wave: 0, legacy: false };
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
/** Parsed SemVer identifiers {core, pre} of `version`; an unreadable version throws. */
|
|
23
|
-
export function versionParts(version) {
|
|
24
|
-
const parts = typeof version === 'string' ? version.split('+') : [];
|
|
25
|
-
if (!parts.length || parts.length > 2 || (parts.length === 2 && !IDENTIFIERS.test(parts[1]))) throw new Error(`unreadable release version ${version}`);
|
|
26
|
-
const boundary = parts[0].indexOf('-');
|
|
27
|
-
const core = (boundary < 0 ? parts[0] : parts[0].slice(0, boundary)).split('.');
|
|
28
|
-
const prerelease = boundary < 0 ? null : parts[0].slice(boundary + 1);
|
|
29
|
-
if (core.length !== 3 || core.some((part) => !NUMERIC.test(part)) || (prerelease !== null && !IDENTIFIERS.test(prerelease))) throw new Error(`unreadable release version ${version}`);
|
|
30
|
-
const pre = prerelease?.split('.') ?? [];
|
|
31
|
-
if (pre.some((part) => /^0\d+$/.test(part))) throw new Error(`invalid numeric prerelease identifier in ${version}`);
|
|
32
|
-
return { core: core.map(BigInt), pre };
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
const readable = (version) => {
|
|
36
|
-
try {
|
|
37
|
-
versionParts(version);
|
|
38
|
-
return true;
|
|
39
|
-
} catch {
|
|
40
|
-
return false;
|
|
41
|
-
}
|
|
42
|
-
};
|
|
43
|
-
|
|
44
|
-
/** The SemVer spelling a version is ordered by: a legacy `-fix.K` orders as wave K of its line. */
|
|
45
|
-
const ordered = (version) => {
|
|
46
|
-
const { base, wave, legacy } = waveOf(version);
|
|
47
|
-
return legacy ? `${base}.${wave}` : version;
|
|
48
|
-
};
|
|
49
|
-
|
|
50
|
-
const compareIdentifier = (a, b) => {
|
|
51
|
-
const numericA = /^\d+$/.test(a), numericB = /^\d+$/.test(b);
|
|
52
|
-
if (numericA && numericB) return BigInt(a) < BigInt(b) ? -1 : Number(BigInt(a) > BigInt(b));
|
|
53
|
-
if (numericA !== numericB) return numericA ? -1 : 1;
|
|
54
|
-
return a < b ? -1 : Number(a > b);
|
|
55
|
-
};
|
|
56
|
-
|
|
57
|
-
/** SemVer precedence, numeric prerelease identifiers included; build metadata has no precedence. */
|
|
58
|
-
export function compareVersions(a, b) {
|
|
59
|
-
const left = versionParts(ordered(a)), right = versionParts(ordered(b));
|
|
60
|
-
for (const i of left.core.keys()) {
|
|
61
|
-
if (left.core[i] !== right.core[i]) return left.core[i] < right.core[i] ? -1 : 1;
|
|
62
|
-
}
|
|
63
|
-
if (!left.pre.length || !right.pre.length) return Number(!left.pre.length) - Number(!right.pre.length);
|
|
64
|
-
for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i += 1) {
|
|
65
|
-
if (left.pre[i] === undefined) return -1;
|
|
66
|
-
if (right.pre[i] === undefined) return 1;
|
|
67
|
-
const compared = compareIdentifier(left.pre[i], right.pre[i]);
|
|
68
|
-
if (compared) return compared;
|
|
69
|
-
}
|
|
70
|
-
return 0;
|
|
71
|
-
}
|
|
72
|
-
|
|
73
|
-
/** The release line of `version`: a prerelease's core and the identifiers before its first number (every alpha.N and alpha.N.M share one), a stable release's major and minor. */
|
|
74
|
-
export function releaseLine(version) {
|
|
75
|
-
const { core, pre } = versionParts(ordered(version));
|
|
76
|
-
if (!pre.length) return `${core.slice(0, 2).join('.')}-stable`;
|
|
77
|
-
const first = pre.findIndex((id) => /^\d+$/.test(id));
|
|
78
|
-
return `${core.join('.')}-${(first < 0 ? pre : pre.slice(0, first)).join('.')}`;
|
|
79
|
-
}
|
|
80
|
-
|
|
81
|
-
/** {family, line} of a release that opens a line (`<x.y.z>-<label>.N`), or null for any other shape. */
|
|
82
|
-
function lineStart(base) {
|
|
83
|
-
if (!readable(base)) return null;
|
|
84
|
-
const { core, pre } = versionParts(base);
|
|
85
|
-
return pre.length === 2 && !/^\d+$/.test(pre[0]) && NUMERIC.test(pre[1]) ? { family: `${core.join('.')}-${pre[0]}`, line: Number(pre[1]) } : null;
|
|
86
|
-
}
|
|
87
|
-
|
|
88
|
-
/** The next wave after `version`: its base with M one past the highest wave of that base among `version` and `known`. */
|
|
89
|
-
export function nextWave(version, known = []) {
|
|
90
|
-
const { base } = waveOf(version);
|
|
91
|
-
const waves = [version, ...known].map(waveOf).filter((entry) => entry.base === base).map((entry) => entry.wave);
|
|
92
|
-
return `${base}.${Math.max(0, ...waves) + 1}`;
|
|
93
|
-
}
|
|
94
|
-
|
|
95
|
-
/**
|
|
96
|
-
export function
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
*
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
const
|
|
110
|
-
const
|
|
111
|
-
|
|
112
|
-
if (!
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
return
|
|
116
|
-
}
|
|
117
|
-
|
|
118
|
-
/**
|
|
119
|
-
|
|
1
|
+
// release-version.mjs - the one reading of a release version (owner ruling release-waves). A prerelease `<label>.N` opens the release
|
|
2
|
+
// line N and `<label>.N.M` is the M-th release after it, a wave or a fix alike, so alpha.31 < alpha.31.1 < alpha.31.2 < alpha.32 in
|
|
3
|
+
// SemVer order. The next release is derived from the highest one already released, never guessed. The legacy `<label>.N-fix.K` still
|
|
4
|
+
// reads as release K after `<label>.N` and is never produced again. Pure: the callers read the tags and the registry.
|
|
5
|
+
|
|
6
|
+
const NUMERIC = /^(?:0|[1-9]\d*)$/;
|
|
7
|
+
const POSITIVE = /^[1-9]\d*$/;
|
|
8
|
+
const IDENTIFIERS = /^[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/;
|
|
9
|
+
const LEGACY_FIX = '-fix.';
|
|
10
|
+
|
|
11
|
+
/** {base, wave, legacy}: the release a version counts its waves from, and its wave M (0 for the release that opens the line). */
|
|
12
|
+
export function waveOf(version) {
|
|
13
|
+
const text = String(version ?? '').split('+')[0];
|
|
14
|
+
const fix = text.lastIndexOf(LEGACY_FIX);
|
|
15
|
+
const legacyWave = fix > 0 ? text.slice(fix + LEGACY_FIX.length) : '';
|
|
16
|
+
if (POSITIVE.test(legacyWave)) return { base: text.slice(0, fix), wave: Number(legacyWave), legacy: true };
|
|
17
|
+
const ids = text.split('.');
|
|
18
|
+
const counted = ids.length > 3 && POSITIVE.test(ids.at(-1)) && (text.includes('-') ? NUMERIC.test(ids.at(-2)) : ids.length === 4);
|
|
19
|
+
return counted ? { base: ids.slice(0, -1).join('.'), wave: Number(ids.at(-1)), legacy: false } : { base: text, wave: 0, legacy: false };
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** Parsed SemVer identifiers {core, pre} of `version`; an unreadable version throws. */
|
|
23
|
+
export function versionParts(version) {
|
|
24
|
+
const parts = typeof version === 'string' ? version.split('+') : [];
|
|
25
|
+
if (!parts.length || parts.length > 2 || (parts.length === 2 && !IDENTIFIERS.test(parts[1]))) throw new Error(`unreadable release version ${version}`);
|
|
26
|
+
const boundary = parts[0].indexOf('-');
|
|
27
|
+
const core = (boundary < 0 ? parts[0] : parts[0].slice(0, boundary)).split('.');
|
|
28
|
+
const prerelease = boundary < 0 ? null : parts[0].slice(boundary + 1);
|
|
29
|
+
if (core.length !== 3 || core.some((part) => !NUMERIC.test(part)) || (prerelease !== null && !IDENTIFIERS.test(prerelease))) throw new Error(`unreadable release version ${version}`);
|
|
30
|
+
const pre = prerelease?.split('.') ?? [];
|
|
31
|
+
if (pre.some((part) => /^0\d+$/.test(part))) throw new Error(`invalid numeric prerelease identifier in ${version}`);
|
|
32
|
+
return { core: core.map(BigInt), pre };
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
const readable = (version) => {
|
|
36
|
+
try {
|
|
37
|
+
versionParts(version);
|
|
38
|
+
return true;
|
|
39
|
+
} catch {
|
|
40
|
+
return false;
|
|
41
|
+
}
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
/** The SemVer spelling a version is ordered by: a legacy `-fix.K` orders as wave K of its line. */
|
|
45
|
+
const ordered = (version) => {
|
|
46
|
+
const { base, wave, legacy } = waveOf(version);
|
|
47
|
+
return legacy ? `${base}.${wave}` : version;
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
const compareIdentifier = (a, b) => {
|
|
51
|
+
const numericA = /^\d+$/.test(a), numericB = /^\d+$/.test(b);
|
|
52
|
+
if (numericA && numericB) return BigInt(a) < BigInt(b) ? -1 : Number(BigInt(a) > BigInt(b));
|
|
53
|
+
if (numericA !== numericB) return numericA ? -1 : 1;
|
|
54
|
+
return a < b ? -1 : Number(a > b);
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
/** SemVer precedence, numeric prerelease identifiers included; build metadata has no precedence. */
|
|
58
|
+
export function compareVersions(a, b) {
|
|
59
|
+
const left = versionParts(ordered(a)), right = versionParts(ordered(b));
|
|
60
|
+
for (const i of left.core.keys()) {
|
|
61
|
+
if (left.core[i] !== right.core[i]) return left.core[i] < right.core[i] ? -1 : 1;
|
|
62
|
+
}
|
|
63
|
+
if (!left.pre.length || !right.pre.length) return Number(!left.pre.length) - Number(!right.pre.length);
|
|
64
|
+
for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i += 1) {
|
|
65
|
+
if (left.pre[i] === undefined) return -1;
|
|
66
|
+
if (right.pre[i] === undefined) return 1;
|
|
67
|
+
const compared = compareIdentifier(left.pre[i], right.pre[i]);
|
|
68
|
+
if (compared) return compared;
|
|
69
|
+
}
|
|
70
|
+
return 0;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** The release line of `version`: a prerelease's core and the identifiers before its first number (every alpha.N and alpha.N.M share one), a stable release's major and minor. */
|
|
74
|
+
export function releaseLine(version) {
|
|
75
|
+
const { core, pre } = versionParts(ordered(version));
|
|
76
|
+
if (!pre.length) return `${core.slice(0, 2).join('.')}-stable`;
|
|
77
|
+
const first = pre.findIndex((id) => /^\d+$/.test(id));
|
|
78
|
+
return `${core.join('.')}-${(first < 0 ? pre : pre.slice(0, first)).join('.')}`;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** {family, line} of a release that opens a line (`<x.y.z>-<label>.N`), or null for any other shape. */
|
|
82
|
+
function lineStart(base) {
|
|
83
|
+
if (!readable(base)) return null;
|
|
84
|
+
const { core, pre } = versionParts(base);
|
|
85
|
+
return pre.length === 2 && !/^\d+$/.test(pre[0]) && NUMERIC.test(pre[1]) ? { family: `${core.join('.')}-${pre[0]}`, line: Number(pre[1]) } : null;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** The next wave after `version`: its base with M one past the highest wave of that base among `version` and `known`. */
|
|
89
|
+
export function nextWave(version, known = []) {
|
|
90
|
+
const { base } = waveOf(version);
|
|
91
|
+
const waves = [version, ...known].map(waveOf).filter((entry) => entry.base === base).map((entry) => entry.wave);
|
|
92
|
+
return `${base}.${Math.max(0, ...waves) + 1}`;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** The family of a version: its core and label up to `-<label>` (`1.0.0-alpha`), or null for a stable or unlabelled version. */
|
|
96
|
+
export function familyOf(version) {
|
|
97
|
+
if (!readable(version)) return null;
|
|
98
|
+
const { core, pre } = versionParts(ordered(version));
|
|
99
|
+
return pre.length && !/^\d+$/.test(pre[0]) ? `${core.join('.')}-${pre[0]}` : null;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* What may follow the highest line-shaped release of `versions`: {highest, family, wave, line}, or null when none has that shape.
|
|
104
|
+
* With a `candidate`, a family that already has released tags is judged alone (another family's tags, such as legacy 2.0.1-alpha.N,
|
|
105
|
+
* never outrank the candidate's own line); a family without a tag falls back to the highest release overall.
|
|
106
|
+
*/
|
|
107
|
+
export function nextReleases(versions, candidate = null) {
|
|
108
|
+
const shaped = versions.filter((version) => readable(version) && lineStart(waveOf(version).base));
|
|
109
|
+
const family = candidate === null ? null : familyOf(candidate);
|
|
110
|
+
const own = family === null ? [] : shaped.filter((version) => lineStart(waveOf(version).base).family === family);
|
|
111
|
+
const pool = own.length ? own : shaped;
|
|
112
|
+
if (!pool.length) return null;
|
|
113
|
+
const highest = pool.reduce((top, version) => (compareVersions(version, top) > 0 ? version : top));
|
|
114
|
+
const start = lineStart(waveOf(highest).base);
|
|
115
|
+
return { highest, family: start.family, wave: nextWave(highest, pool), line: `${start.family}.${start.line + 1}` };
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Why `version` cannot be released after `released` (the versions already tagged), or null when it can: the next wave of the highest
|
|
120
|
+
* release of its own family, the first release of the next line, or (when its family has no tag) a later release of another label or
|
|
121
|
+
* core than the highest. The legacy `-fix` form is always refused.
|
|
122
|
+
*/
|
|
123
|
+
export function releaseVersionRefusal(version, released) {
|
|
124
|
+
const next = nextReleases(released.filter((entry) => entry !== version), version);
|
|
125
|
+
const named = next ? `; the next release is ${next.wave} (the next wave or fix after ${next.highest}) or ${next.line} (the next line)` : '';
|
|
126
|
+
if (waveOf(version).legacy) return `${version} is the legacy -fix form, which is read and never released again${named}`;
|
|
127
|
+
if (!next || version === next.wave || version === next.line) return null;
|
|
128
|
+
if (!readable(version)) return `${version} is not a SemVer version${named}`;
|
|
129
|
+
if (lineStart(waveOf(version).base)?.family !== next.family && compareVersions(version, next.highest) > 0) return null;
|
|
130
|
+
return `${version} does not follow ${next.highest}${named}`;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** The versions of the release tags `v<version>` in the output of `git tag --list`. */
|
|
134
|
+
export const taggedVersions = (listing) => String(listing ?? '').split(/\r?\n/).map((name) => name.trim()).filter((name) => /^v\d/.test(name)).map((name) => name.slice(1));
|