@intellectual-frontiers/libraries 0.2.1 → 0.4.0

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.
@@ -0,0 +1,680 @@
1
+ /**
2
+ * The release (commons 0001-libraries FR-013 to FR-015, 0026-works-versioning FR-022): versions grow here, at the release, and not on every push. One command plans what a release does and makes it, and writes the record
3
+ * that the one release workflow reads.
4
+ *
5
+ * bun commons/libraries/src/releasing.ts plan what a release would do, from the tags and the working tree; writes nothing (the default command)
6
+ * bun commons/libraries/src/releasing.ts apply raise the versions the plan says, make the generated files once, run the tests that pack, install and type-check every library, write the record
7
+ * bun commons/libraries/src/releasing.ts matrix --github-output F what the release workflow builds and publishes, from the record, leaving out what is tagged (written as the outputs of a step)
8
+ * other flags: --repo DIR, and for apply --no-tests (leave out the tests that pack: for trying the command, never for a release)
9
+ *
10
+ * @remarks
11
+ * A library is released at the version its manifest has, and its version is raised here and nowhere else: a library whose files changed since its last tag (its folder, and the paths its record adds) is raised by the greatest `Impact:`
12
+ * of the commits since that tag (a patch where none states one), and a library that imports a library that is raised is raised by at least a patch, and so on up the imports. A library whose version is not tagged yet is released as it is,
13
+ * whatever the tags say of earlier versions: a library that has never been tagged (the first release of it, or a backlog that was never tagged), or whose manifest is ahead of its last tag (a version raised by hand). A library whose
14
+ * version is tagged and whose files did not change is left alone. The order of the release is the order of the imports, a library after the libraries it imports. The record, `commons/generated/release.auto.json`, lists what the release
15
+ * workflow publishes and tags, in that order; it says nothing of a day or a person, so the same state gives the same bytes. Nothing here publishes, tags or commits: the workflow publishes and tags, and a person commits what `apply` made.
16
+ *
17
+ * @limits
18
+ * The plan reads the tags of this repository, so a clone without its tags plans a first release of everything. It cannot know what a registry holds: the workflow asks it, and skips a version that is there. A work that is not a library
19
+ * (`commons/ts`, `commons/docs`) is a Git dependency and is not released here.
20
+ *
21
+ * @example
22
+ * ```ts
23
+ * import { planRelease } from "./release.ts";
24
+ * // a library whose version is tagged and whose files changed is raised; one that imports it is raised by a patch
25
+ * ```
26
+ *
27
+ * Spec: 0001-libraries FR-013
28
+ *
29
+ * @module
30
+ */
31
+ import { createHash } from "node:crypto";
32
+ import process from "node:process";
33
+ import { gunzipSync } from "node:zlib";
34
+ import { absurd, err, ok, order } from "@intellectual-frontiers/core";
35
+ import { stdio } from "@intellectual-frontiers/system";
36
+ import { existsSync, mkdirSync, readDirSync, readFileSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
37
+ import { join, resolve } from "@intellectual-frontiers/system/path";
38
+ import { env, run } from "@intellectual-frontiers/system/proc";
39
+ import { currentLook } from "@intellectual-frontiers/system/tty";
40
+ import { flag, formatUsageError, helpText, many, parseArgs, value } from "@intellectual-frontiers/terminal/args";
41
+ import { label, paint } from "@intellectual-frontiers/terminal/palette";
42
+ import { formatGitError } from "@intellectual-frontiers/system/git";
43
+ import { changedBetween, commitsSince, readTags, readWorkingTree, resolveCommit } from "@intellectual-frontiers/mizan/versions/git";
44
+ import { impactOfCommits } from "@intellectual-frontiers/mizan/versions/notes";
45
+ import { decodeReleaseSource, releaseSource, slugOf, withVersion } from "@intellectual-frontiers/mizan/versions/record";
46
+ import { compareVersions, greaterImpact, nextSemVer, parseVersion } from "@intellectual-frontiers/mizan/versions/scheme";
47
+ import { scopeOf, workFolders } from "@intellectual-frontiers/mizan/versions/works";
48
+ import { inputsOf } from "./affected.js";
49
+ import { exportsLine } from "./plan.js";
50
+ import { everyLibrary } from "./affected.js";
51
+ /** The record of the release, from the repository's root. */
52
+ export const RECORD_PATH = "commons/generated/release.auto.json";
53
+ const tagOf = (slug, version) => `${slug}-v${version}`;
54
+ /** The text of a decision, in a sentence. */
55
+ export function describe(d, from) {
56
+ switch (d.kind) {
57
+ case "unchanged":
58
+ return "left alone: tagged, and no file changed since";
59
+ case "as-is": {
60
+ const because = d.why === "no-tag" ? "it has no tag yet" : "its version is ahead of its last tag";
61
+ const npm = d.npm === "absent"
62
+ ? "it is not on npm, so it is published"
63
+ : d.npm === "same"
64
+ ? "npm has this version with the same files, so it is only tagged"
65
+ : d.npm === "differs"
66
+ ? "npm has this version with other files"
67
+ : "npm was not compared, and no file changed since its version was raised";
68
+ return `released as it is (${from}): ${because}; ${npm}`;
69
+ }
70
+ case "raised":
71
+ return `raised to ${d.to} (${d.impact}): ${d.why === "changed"
72
+ ? "files changed since its last tag"
73
+ : d.why === "differs-from-npm"
74
+ ? "its files differ from the version npm holds, which stays as published"
75
+ : d.why === "changed-since-version"
76
+ ? "npm was not compared, and files changed since its version was raised"
77
+ : "asked for (--raise)"}`;
78
+ case "dependent":
79
+ return `raised to ${d.to} (patch): it imports ${d.because.join(", ")}, which ${d.because.length === 1 ? "is" : "are"} raised`;
80
+ default:
81
+ return absurd(d);
82
+ }
83
+ }
84
+ /**
85
+ * The plan of a release from the facts of the libraries (FR-013): a library with no tag, or ahead of its last tag, is released as it is; one that is tagged at its version and changed is raised by its impact; one that is tagged,
86
+ * unchanged and imports a library that is raised, directly or through another, is raised by a patch; the rest are left alone. A library whose version is below its last tag is an error, and so is a cycle of imports.
87
+ */
88
+ export function planRelease(facts, raise = new Map()) {
89
+ const by = new Map(facts.map((f) => [f.slug, f]));
90
+ const unknown = [...raise.keys()].filter((k) => !by.has(k));
91
+ if (unknown.length > 0)
92
+ return err(`--raise names ${unknown.join(", ")}, which ${unknown.length === 1 ? "is" : "are"} no library (they are: ${facts.map((f) => f.slug).join(", ")})`);
93
+ const decided = new Map();
94
+ const raised = (f, impact, why) => {
95
+ const to = nextSemVer(f.version, impact);
96
+ return to.kind === "err" ? err(`${f.slug}: ${to.error}`) : ok({ kind: "raised", to: to.value, impact, why });
97
+ };
98
+ for (const f of facts) {
99
+ let candidate = f.last === undefined;
100
+ if (f.last !== undefined) {
101
+ const c = compare(f.version, f.last.version);
102
+ if (c === undefined)
103
+ return err(`${f.slug}: the version ${f.version} or the tag ${f.last.tag} is not a Semantic Version`);
104
+ if (c < 0)
105
+ return err(`${f.slug}: the version ${f.version} is below its last tag ${f.last.tag}: a version never goes back`);
106
+ candidate = c > 0;
107
+ }
108
+ const asked = raise.has(f.slug);
109
+ let d;
110
+ if (asked)
111
+ d = raised(f, raise.get(f.slug) ?? f.sinceVersion.impact, "manual");
112
+ else if (candidate) {
113
+ // a version that has no tag, or is ahead of its tag, may be on npm already with other files: it is then raised, and not released as it is
114
+ if (f.registry === "differs")
115
+ d = raised(f, f.sinceVersion.impact, "differs-from-npm");
116
+ else if (f.registry === "unknown" && f.sinceVersion.changed)
117
+ d = raised(f, f.sinceVersion.impact, "changed-since-version");
118
+ else
119
+ d = ok({ kind: "as-is", why: f.last === undefined ? "no-tag" : "ahead-of-tag", npm: f.registry });
120
+ }
121
+ else
122
+ d = f.changed ? raised(f, f.impact, "changed") : ok({ kind: "unchanged" });
123
+ if (d.kind === "err")
124
+ return d;
125
+ decided.set(f.slug, d.value);
126
+ }
127
+ // a library that imports a raised library is raised by a patch, and so on up the imports
128
+ for (let grew = true; grew;) {
129
+ grew = false;
130
+ for (const f of facts) {
131
+ if (decided.get(f.slug)?.kind !== "unchanged")
132
+ continue;
133
+ const because = f.imports.filter((i) => {
134
+ const k = decided.get(i)?.kind;
135
+ return k === "raised" || k === "dependent";
136
+ });
137
+ if (because.length === 0)
138
+ continue;
139
+ const to = nextSemVer(f.version, "patch");
140
+ if (to.kind === "err")
141
+ return err(`${f.slug}: ${to.error}`);
142
+ decided.set(f.slug, { kind: "dependent", to: to.value, because });
143
+ grew = true;
144
+ }
145
+ }
146
+ const releasing = facts.filter((f) => decided.get(f.slug)?.kind !== "unchanged");
147
+ const graph = new Map(releasing.map((f) => [f.slug, f.imports.filter((i) => by.has(i))]));
148
+ const sorted = order(graph);
149
+ if (sorted.kind === "err")
150
+ return err(`the libraries import each other in a cycle: ${sorted.error.nodes.join(" -> ")}`);
151
+ const steps = [];
152
+ for (const slug of sorted.value) {
153
+ const f = by.get(slug);
154
+ const d = decided.get(slug);
155
+ if (f === undefined || d === undefined || d.kind === "unchanged")
156
+ continue;
157
+ const to = d.kind === "as-is" ? f.version : d.to;
158
+ steps.push({ slug, folder: f.folder, from: f.version, to, tag: tagOf(slug, to), publish: f.publish, decision: d });
159
+ }
160
+ return ok({ steps, unchanged: facts.filter((f) => decided.get(f.slug)?.kind === "unchanged").map((f) => f.slug) });
161
+ }
162
+ function compare(a, b) {
163
+ const x = parseVersion("SemVer", a);
164
+ const y = parseVersion("SemVer", b);
165
+ return x.kind === "ok" && y.kind === "ok" ? compareVersions(x.value, y.value) : undefined;
166
+ }
167
+ /** The record the workflow reads, as the bytes of its file: the steps that publish or tag, in order. */
168
+ export function recordText(plan) {
169
+ const releases = plan.steps.map((s) => ({ slug: s.slug, version: s.to, folder: s.folder, tag: s.tag, publish: s.publish }));
170
+ return `${JSON.stringify({ generated: "bun commons/libraries/src/releasing.ts apply; do not edit (commons 0001-libraries FR-014)", releases }, null, 2)}\n`;
171
+ }
172
+ /** The entries of a record's text, or why it is not one. */
173
+ export function readRecord(text) {
174
+ let json;
175
+ try {
176
+ json = JSON.parse(text);
177
+ }
178
+ catch {
179
+ return err(`${RECORD_PATH} is not JSON`);
180
+ }
181
+ const list = typeof json === "object" && json !== null && "releases" in json ? json.releases : undefined;
182
+ if (!Array.isArray(list))
183
+ return err(`${RECORD_PATH} has no list of releases`);
184
+ const out = [];
185
+ for (const e of list) {
186
+ if (typeof e !== "object" || e === null)
187
+ return err(`${RECORD_PATH}: an entry is not an object`);
188
+ const o = Object.fromEntries(Object.entries(e));
189
+ const { slug, version, folder, tag, publish } = o;
190
+ if (typeof slug !== "string" || typeof version !== "string" || typeof folder !== "string" || typeof tag !== "string" || typeof publish !== "boolean")
191
+ return err(`${RECORD_PATH}: an entry lacks its slug, version, folder, tag or publish`);
192
+ out.push({ slug, version, folder, tag, publish });
193
+ }
194
+ return ok(out);
195
+ }
196
+ /** What the workflow builds and publishes: the entries whose tag is not there yet, as the cells of a matrix and the sequence to publish in, as the outputs of a step. */
197
+ export function matrixOutputs(entries, tagged) {
198
+ const todo = entries.filter((e) => !tagged.has(e.tag));
199
+ const build = { include: todo.filter((e) => e.publish).map((e) => ({ slug: e.slug, folder: e.folder, version: e.version, tag: e.tag })) };
200
+ const sequence = todo.map((e) => ({ slug: e.slug, version: e.version, tag: e.tag, publish: e.publish }));
201
+ return [`has-build=${build.include.length > 0 || sequence.length > 0}`, `build=${JSON.stringify(build)}`, `sequence=${JSON.stringify(sequence)}`].join("\n");
202
+ }
203
+ const set = (text, pattern, to) => (pattern.test(text) ? text.replace(pattern, to) : undefined);
204
+ /** Writes a library's new version into its record, its manifest and its package, each where it says the version; the problem where one does not. */
205
+ export function writeVersion(repo, step) {
206
+ const files = [];
207
+ const record = join(repo, step.folder, "release.ts");
208
+ // a library that has no record of its own (it is not a work of the register yet) has its version in its manifest and its package alone
209
+ if (existsSync(record)) {
210
+ const decoded = decodeReleaseSource(readTextFileSync(record));
211
+ if (decoded.kind === "err")
212
+ return err(`${step.folder}/release.ts does not decode`);
213
+ writeTextFileSync(record, releaseSource(withVersion(decoded.value, step.to)));
214
+ files.push(`${step.folder}/release.ts`);
215
+ }
216
+ for (const [file, pattern, to] of [
217
+ [`${step.folder}/library.ts`, /(\bversion"?:\s*)"[^"]*"/, `$1"${step.to}"`],
218
+ [`${step.folder}/package.json`, /("version":\s*)"[^"]*"/, `$1"${step.to}"`],
219
+ ]) {
220
+ const at = join(repo, file);
221
+ if (!existsSync(at))
222
+ return err(`${file} is missing`);
223
+ const changed = set(readTextFileSync(at), pattern, to);
224
+ if (changed === undefined)
225
+ return err(`${file} does not say its version`);
226
+ writeTextFileSync(at, changed);
227
+ files.push(file);
228
+ }
229
+ return ok(files);
230
+ }
231
+ /** The files of a gzipped tar, as a registry serves it: each regular file's path and SHA-256. A header it cannot read ends the list there. */
232
+ export function tarballOf(gz) {
233
+ const bytes = gunzipSync(gz);
234
+ const text = (from, to) => new TextDecoder().decode(bytes.subarray(from, to)).replace(/\0.*$/s, "");
235
+ const hashes = new Map();
236
+ let packageJson = "";
237
+ for (let at = 0; at + 512 <= bytes.length;) {
238
+ const name = text(at, at + 100);
239
+ if (name === "")
240
+ break;
241
+ const size = Number.parseInt(text(at + 124, at + 136).trim() || "0", 8);
242
+ const type = text(at + 156, at + 157);
243
+ const prefix = text(at + 345, at + 500);
244
+ const body = bytes.subarray(at + 512, at + 512 + size);
245
+ if (type === "0" || type === "") {
246
+ const path = (prefix === "" ? name : `${prefix}/${name}`).replace(/^package\//, "");
247
+ hashes.set(path, createHash("sha256").update(body).digest("hex"));
248
+ if (path === "package.json")
249
+ packageJson = new TextDecoder().decode(body);
250
+ }
251
+ at += 512 + Math.ceil(size / 512) * 512;
252
+ }
253
+ return { hashes, packageJson };
254
+ }
255
+ /**
256
+ * Whether the files of a library are those of the version npm holds (FR-013): the sources the package carries (`src/`, each by its SHA-256 against the library's own file) and the keys of its `exports` (the packer rewrites the rest of
257
+ * `package.json`, and the compiled files are the compiler's). A source that is missing here, or other, or an entry of `exports` that was added or removed, is a difference.
258
+ */
259
+ export function driftOf(published, local) {
260
+ if (exportsLine(published.packageJson) !== exportsLine(local.packageJson))
261
+ return "differs";
262
+ for (const [path, sha] of published.hashes)
263
+ if (path.startsWith("src/") && local.hash(path) !== sha)
264
+ return "differs";
265
+ return "same";
266
+ }
267
+ /** The registry of npm itself, read over HTTPS: the metadata of the version, its tarball, and the library's files under `repo`; anything that goes wrong is `unknown`, never a guess. */
268
+ export function realRegistry(repo) {
269
+ return async (slug, version, folder) => {
270
+ try {
271
+ const meta = await fetch(`https://registry.npmjs.org/@intellectual-frontiers%2F${slug}/${version}`, { signal: AbortSignal.timeout(30_000) });
272
+ if (meta.status === 404)
273
+ return "absent";
274
+ if (!meta.ok)
275
+ return "unknown";
276
+ const json = await meta.json();
277
+ const dist = typeof json === "object" && json !== null && "dist" in json ? json.dist : undefined;
278
+ const url = typeof dist === "object" && dist !== null && "tarball" in dist ? dist.tarball : undefined;
279
+ if (typeof url !== "string")
280
+ return "unknown";
281
+ const tgz = await fetch(url, { signal: AbortSignal.timeout(60_000) });
282
+ if (!tgz.ok)
283
+ return "unknown";
284
+ const published = tarballOf(new Uint8Array(await tgz.arrayBuffer()));
285
+ const pkg = join(repo, folder, "package.json");
286
+ return driftOf(published, {
287
+ hash: (path) => {
288
+ const f = join(repo, folder, path);
289
+ return existsSync(f) ? createHash("sha256").update(readFileSync(f)).digest("hex") : undefined;
290
+ },
291
+ packageJson: existsSync(pkg) ? readTextFileSync(pkg) : "",
292
+ });
293
+ }
294
+ catch {
295
+ return "unknown";
296
+ }
297
+ };
298
+ }
299
+ /** What the host gives the plan: the facts of the libraries from the tags and the tree. */
300
+ export async function factsOf(repo, registry = realRegistry(repo)) {
301
+ const tree = await readWorkingTree(repo);
302
+ if (tree.kind === "err")
303
+ return err(formatGitError(tree.error));
304
+ const tags = await readTags(repo);
305
+ if (tags.kind === "err")
306
+ return err(formatGitError(tags.error));
307
+ const head = await resolveCommit(repo, "HEAD");
308
+ if (head.kind === "err")
309
+ return err(formatGitError(head.error));
310
+ const folders = workFolders(tree.value.paths);
311
+ const libs = everyLibrary(repo);
312
+ const slugs = new Map();
313
+ for (const l of libs) {
314
+ const s = slugOf(l.name);
315
+ if (s !== undefined)
316
+ slugs.set(l.name, s);
317
+ }
318
+ const out = [];
319
+ for (const l of libs) {
320
+ const slug = slugs.get(l.name);
321
+ const text = tree.value.records.get(l.folder);
322
+ const record = text === undefined ? undefined : decodeReleaseSource(text);
323
+ if (slug === undefined)
324
+ return err(`${l.name} is not a slug`);
325
+ if (record?.kind === "err")
326
+ return err(`${l.folder}/release.ts does not decode`);
327
+ let last;
328
+ for (const t of tags.value) {
329
+ if (!t.name.startsWith(`${slug}-v`))
330
+ continue;
331
+ const version = t.name.slice(slug.length + 2);
332
+ const v = parseVersion("SemVer", version);
333
+ if (v.kind === "err")
334
+ continue;
335
+ const best = last === undefined ? undefined : parseVersion("SemVer", last.version);
336
+ if (last === undefined || (best?.kind === "ok" && compareVersions(v.value, best.value) === 1))
337
+ last = { version, tag: t.name, commit: t.commit };
338
+ }
339
+ const inScope = scopeOf(l.folder, folders, record?.value.exclude ?? [], record?.value.paths ?? []);
340
+ let changed = false;
341
+ let impact = "patch";
342
+ if (last !== undefined) {
343
+ const files = await changedBetween(repo, last.commit, head.value);
344
+ if (files.kind === "err")
345
+ return err(formatGitError(files.error));
346
+ changed = files.value.some(inScope);
347
+ const commits = await commitsSince(repo, last.commit);
348
+ if (commits.kind === "err")
349
+ return err(formatGitError(commits.error));
350
+ impact = impactOfCommits(commits.value.filter((c) => c.files.some(inScope))) ?? "patch";
351
+ }
352
+ // a version with no tag, or ahead of its tag, may be on npm already: what npm holds of it is compared, and where it cannot be, the files since the version was raised say
353
+ const ahead = last === undefined || (compare(l.version, last.version) ?? 0) > 0;
354
+ let drift = "unknown";
355
+ let sinceVersion = { changed: false, impact: "patch" };
356
+ if (ahead) {
357
+ if (l.distribution.includes("npm"))
358
+ drift = await registry(slug, l.version, l.folder);
359
+ const raisedAt = await run(["git", "-C", repo, "log", "-1", "--format=%H", '-G"version"', "--", `${l.folder}/package.json`]);
360
+ const commit = raisedAt.code === 0 ? raisedAt.stdout.trim() : "";
361
+ if (commit !== "") {
362
+ const files = await changedBetween(repo, commit, head.value);
363
+ const commits = await commitsSince(repo, commit);
364
+ if (files.kind === "err")
365
+ return err(formatGitError(files.error));
366
+ if (commits.kind === "err")
367
+ return err(formatGitError(commits.error));
368
+ sinceVersion = {
369
+ changed: files.value.some(inScope),
370
+ impact: greaterImpact("patch", impactOfCommits(commits.value.filter((c) => c.files.some(inScope))) ?? "patch"),
371
+ };
372
+ }
373
+ }
374
+ const imports = inputsOf(repo, l.name).imports.flatMap((n) => {
375
+ const s = slugs.get(n);
376
+ return s === undefined ? [] : [s];
377
+ });
378
+ out.push({
379
+ slug,
380
+ folder: l.folder,
381
+ version: l.version,
382
+ imports,
383
+ last: last === undefined ? undefined : { version: last.version, tag: last.tag },
384
+ changed,
385
+ impact: greaterImpact("patch", impact),
386
+ publish: l.distribution.includes("npm"),
387
+ registry: drift,
388
+ sinceVersion,
389
+ });
390
+ }
391
+ return ok(out);
392
+ }
393
+ /** The commands that make the generated files, in the order they are made: the section of the libraries first, the register last. Each is run once, by `apply`. */
394
+ export const GENERATORS = [
395
+ ["commons/libraries/src/libraries.ts"],
396
+ ["commons/tools/generate-packaging.ts"],
397
+ ["commons/libraries/src/generate-ontology.ts"],
398
+ ["commons/libraries/src/generate-workflows.ts"],
399
+ ["commons/libraries/src/oscal-register.ts"],
400
+ ];
401
+ /** The tests that pack every library, install it into a consumer and type-check against it (the heavy proof a release asks for and a push does not). */
402
+ export const PACKAGE_TESTS = ["bun", "test", "./tests/release/"];
403
+ /** The real host: each command run with Bun from the repository's root. */
404
+ export const REAL = {
405
+ generate: async (repo, command) => {
406
+ const r = await run(["bun", ...command], { cwd: repo });
407
+ return r.code === 0 ? ok(undefined) : err(`${command.join(" ")} ended with ${r.code}: ${`${r.stdout}${r.stderr}`.trim().split("\n").slice(-8).join("\n")}`);
408
+ },
409
+ prove: async (repo) => {
410
+ const r = await run(PACKAGE_TESTS, { cwd: repo });
411
+ return r.code === 0 ? ok(undefined) : err(`${PACKAGE_TESTS.join(" ")} ended with ${r.code}:\n${`${r.stdout}${r.stderr}`.trim().split("\n").slice(-30).join("\n")}`);
412
+ },
413
+ };
414
+ /** Makes the release (FR-014): raises the versions of the plan, makes the generated files once, runs the tests that pack unless asked not to, and writes the record. */
415
+ export async function applyRelease(repo, host, options) {
416
+ const facts = await factsOf(repo, options.registry);
417
+ if (facts.kind === "err")
418
+ return facts;
419
+ const planned = planRelease(facts.value, options.raise);
420
+ if (planned.kind === "err")
421
+ return planned;
422
+ const written = [];
423
+ for (const step of planned.value.steps) {
424
+ if (step.decision.kind === "as-is")
425
+ continue;
426
+ const w = writeVersion(repo, step);
427
+ if (w.kind === "err")
428
+ return w;
429
+ written.push(...w.value);
430
+ }
431
+ for (const g of GENERATORS) {
432
+ const r = await host.generate(repo, g);
433
+ if (r.kind === "err")
434
+ return r;
435
+ }
436
+ if (options.tests) {
437
+ const proved = await host.prove(repo);
438
+ if (proved.kind === "err")
439
+ return proved;
440
+ }
441
+ mkdirSync(join(repo, RECORD_PATH, ".."), { recursive: true });
442
+ writeTextFileSync(join(repo, RECORD_PATH), recordText(planned.value));
443
+ written.push(RECORD_PATH);
444
+ return ok({ plan: planned.value, written });
445
+ }
446
+ /** The lines the plan prints: one for each library that is released, and the libraries left alone. */
447
+ export function planLines(look, plan) {
448
+ if (plan.steps.length === 0)
449
+ return [`${label("skipped", "nothing to release: every library is tagged at its version and unchanged", look)}`];
450
+ const out = plan.steps.map((s) => `${label("action", `${s.slug} ${s.from === s.to ? s.to : `${s.from} -> ${s.to}`}${s.publish ? "" : " (tag only)"}`, look)} ${paint("dim", describe(s.decision, s.from), look)}`);
451
+ if (plan.unchanged.length > 0)
452
+ out.push(`${paint("dim", `left alone (${plan.unchanged.length}): ${plan.unchanged.join(", ")}`, look)}`);
453
+ return out;
454
+ }
455
+ /**
456
+ * Publishes and tags the releases in order (FR-015), each by itself: a version that is on npm is not sent again and is tagged; one that is not is sent, and where nothing can send it (no trusted publisher, no token) it is
457
+ * reported and its tag withheld, and the others go on; a release that is only tagged (a library that names no npm) is tagged. A tag that is there is kept. The failures are in the outcomes, never thrown.
458
+ */
459
+ export async function publishAll(entries, tools) {
460
+ const out = [];
461
+ for (const e of entries) {
462
+ const reasons = [];
463
+ let npm = "not-published";
464
+ let registry = "not-published";
465
+ if (e.publish) {
466
+ if (await tools.onNpm(`@intellectual-frontiers/${e.slug}`, e.version))
467
+ npm = "present";
468
+ else {
469
+ const sent = await tools.npm(e);
470
+ npm = sent.kind === "ok" ? "published" : "failed";
471
+ if (sent.kind === "err")
472
+ reasons.push(sent.error);
473
+ }
474
+ if (npm !== "failed") {
475
+ const sent = await tools.github(e);
476
+ registry = sent.kind === "ok" ? "done" : "failed";
477
+ if (sent.kind === "err")
478
+ reasons.push(sent.error);
479
+ }
480
+ }
481
+ let tagged = "withheld";
482
+ if (npm !== "failed" && registry !== "failed") {
483
+ const made = await tools.tag(e.tag);
484
+ tagged = made.kind === "ok" ? made.value : "failed";
485
+ if (made.kind === "err")
486
+ reasons.push(made.error);
487
+ }
488
+ out.push({ slug: e.slug, tag: e.tag, npm, registry, tagged, reasons });
489
+ }
490
+ return out;
491
+ }
492
+ /** The lines that say how each release went, and whether the run is a failure: one failure anywhere fails it, after every release was tried. */
493
+ export function outcomeLines(outcomes) {
494
+ const lines = outcomes.map((o) => {
495
+ const npm = o.npm === "present" ? "on npm already" : o.npm === "published" ? "published to npm" : o.npm === "failed" ? "NOT on npm" : "no npm";
496
+ const tag = o.tagged === "made" ? `tagged ${o.tag}` : o.tagged === "there" ? `${o.tag} was there` : o.tagged === "withheld" ? `${o.tag} withheld` : `${o.tag} not made`;
497
+ return `${o.slug}: ${npm}; ${tag}${o.reasons.length > 0 ? ` (${o.reasons.join("; ")})` : ""}`;
498
+ });
499
+ return { lines, failed: outcomes.some((o) => o.npm === "failed" || o.registry === "failed" || o.tagged === "failed" || o.tagged === "withheld") };
500
+ }
501
+ const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
502
+ const tail = (t) => t.trim().split("\n").slice(-3).join(" ");
503
+ /** The tools of a run of the release workflow: npm and the GitHub CLI, the tarballs under `dir` (one folder for each library, `package-<slug>`), and the environment's credentials. */
504
+ export function realTools(dir) {
505
+ const token = env.get("NPM_TOKEN") ?? "";
506
+ const github = env.get("GITHUB_TOKEN") ?? "";
507
+ const tarball = (slug) => {
508
+ const d = join(dir, `package-${slug}`);
509
+ return existsSync(d) ? readDirSync(d).find((f) => f.name.endsWith(".tgz"))?.name : undefined;
510
+ };
511
+ const view = async (name, version, extra = []) => (await run(["npm", "view", `${name}@${version}`, "version", ...extra])).code === 0;
512
+ return {
513
+ onNpm: async (name, version) => {
514
+ for (let i = 0; i < 3; i++) {
515
+ if (await view(name, version))
516
+ return true;
517
+ if (i < 2)
518
+ await sleep(10_000);
519
+ }
520
+ return false;
521
+ },
522
+ npm: async (e) => {
523
+ const f = tarball(e.slug);
524
+ if (f === undefined)
525
+ return err(`${e.slug}: no tarball was built for it`);
526
+ const r = await run(["npm", "publish", join(dir, `package-${e.slug}`, f), "--access", "public", "--provenance"], {
527
+ env: token === "" ? {} : { NODE_AUTH_TOKEN: token },
528
+ });
529
+ return r.code === 0
530
+ ? ok(undefined)
531
+ : err(`${e.slug} ${e.version} is not on npm and could not be published (${token === "" ? "no INFRO_NPMJS_TOKEN, so trusted publishing was tried" : "with INFRO_NPMJS_TOKEN"}; configure a trusted publisher for @intellectual-frontiers/${e.slug} or publish it by hand): ${tail(`${r.stderr}${r.stdout}`)}`);
532
+ },
533
+ github: async (e) => {
534
+ const auth = [`--registry=https://npm.pkg.github.com`, `--//npm.pkg.github.com/:_authToken=${github}`];
535
+ if (await view(`@intellectual-frontiers/${e.slug}`, e.version, auth))
536
+ return ok(undefined);
537
+ const f = tarball(e.slug);
538
+ if (f === undefined)
539
+ return err(`${e.slug}: no tarball was built for it`);
540
+ const r = await run(["npm", "publish", join(dir, `package-${e.slug}`, f), ...auth]);
541
+ return r.code === 0 ? ok(undefined) : err(`${e.slug} ${e.version} could not be published to the GitHub package registry: ${tail(`${r.stderr}${r.stdout}`)}`);
542
+ },
543
+ tag: async (tag) => {
544
+ const repo = env.get("GITHUB_REPOSITORY") ?? "";
545
+ if ((await run(["gh", "api", `repos/${repo}/git/ref/tags/${tag}`])).code === 0)
546
+ return ok("there");
547
+ const made = await run(["gh", "api", `repos/${repo}/git/refs`, "-f", `ref=refs/tags/${tag}`, "-f", `sha=${env.get("GITHUB_SHA") ?? ""}`]);
548
+ return made.code === 0 ? ok("made") : err(`the tag ${tag} could not be made: ${tail(`${made.stderr}${made.stdout}`)}`);
549
+ },
550
+ };
551
+ }
552
+ /** What `--raise` says: each library by its name, with the impact after an `=` where one is given. */
553
+ export function raiseOf(words) {
554
+ const out = new Map();
555
+ for (const w of words.flatMap((x) => x.split(",")).filter((x) => x !== "")) {
556
+ const [name = "", impact] = w.split("=");
557
+ if (name === "")
558
+ return err(`--raise ${w}: no library`);
559
+ if (impact === undefined)
560
+ out.set(name, undefined);
561
+ else if (impact === "major" || impact === "minor" || impact === "patch")
562
+ out.set(name, impact);
563
+ else
564
+ return err(`--raise ${w}: the impact is major, minor or patch`);
565
+ }
566
+ return ok(out);
567
+ }
568
+ /** The registry that is not asked (`--offline`). */
569
+ export const offlineRegistry = () => Promise.resolve("unknown");
570
+ const COMMANDS = ["plan", "apply", "matrix", "publish"];
571
+ const isCommand = (t) => COMMANDS.includes(t);
572
+ const OPTIONS = {
573
+ repo: value({ help: "The repository (the working folder by default).", valueName: "DIR", default: "." }),
574
+ tests: flag({ help: "Run the tests that pack, install and type-check every library (on by default; apply only).", negatable: true, default: true }),
575
+ githubOutput: value({ help: "Append the outputs to this file, as a step's `$GITHUB_OUTPUT` is read (matrix only).", valueName: "FILE" }),
576
+ raise: many({ help: "Raise a library whatever its state says: NAME, or NAME=major|minor|patch (the impact of its commits, or a patch, where none is given). Repeat, or separate with commas.", valueName: "NAME[=IMPACT]" }),
577
+ offline: flag({ help: "Do not ask npm what it holds: a version with no tag is then raised only where its files changed since it was raised." }),
578
+ dir: value({ help: "Where the tarballs are, a folder `package-<slug>` for each library (publish only).", valueName: "DIR", default: "package" }),
579
+ };
580
+ const WORDS = [{ name: "COMMAND", help: "plan, apply or matrix (plan by default).", arity: "optional" }];
581
+ /** The command line. Returns the exit status: 0, 1 where a plan or a step failed, 2 for a command line that does not fit. */
582
+ export async function main(argv, host = REAL) {
583
+ const parsed = parseArgs(argv, OPTIONS, WORDS);
584
+ if (parsed.kind === "err") {
585
+ stdio.stderr.writeSync(`${formatUsageError(parsed.error, "release")}\n`);
586
+ return 2;
587
+ }
588
+ if (parsed.value.kind === "help") {
589
+ stdio.stdout.writeSync(`${helpText("release", "Plan, make and read a release: versions grow here, at the release.", OPTIONS, WORDS)}\n`);
590
+ return 0;
591
+ }
592
+ const word = parsed.value.positionals[0] ?? "plan";
593
+ if (!isCommand(word)) {
594
+ stdio.stderr.writeSync(`release: ${word} is not a command (${COMMANDS.join(", ")})\n`);
595
+ return 2;
596
+ }
597
+ const repo = resolve(parsed.value.options.repo);
598
+ const look = currentLook("stdout");
599
+ const say = (t) => void stdio.stdout.writeSync(`${t}\n`);
600
+ switch (word) {
601
+ case "plan": {
602
+ const raise = raiseOf(parsed.value.options.raise ?? []);
603
+ if (raise.kind === "err") {
604
+ stdio.stderr.writeSync(`release: ${raise.error}\n`);
605
+ return 2;
606
+ }
607
+ const facts = await factsOf(repo, parsed.value.options.offline ? offlineRegistry : realRegistry(repo));
608
+ const planned = facts.kind === "err" ? facts : planRelease(facts.value, raise.value);
609
+ if (planned.kind === "err") {
610
+ stdio.stderr.writeSync(`release: ${planned.error}\n`);
611
+ return 1;
612
+ }
613
+ for (const l of planLines(look, planned.value))
614
+ say(l);
615
+ return 0;
616
+ }
617
+ case "apply": {
618
+ const raise = raiseOf(parsed.value.options.raise ?? []);
619
+ if (raise.kind === "err") {
620
+ stdio.stderr.writeSync(`release: ${raise.error}\n`);
621
+ return 2;
622
+ }
623
+ const done = await applyRelease(repo, host, {
624
+ tests: parsed.value.options.tests,
625
+ raise: raise.value,
626
+ registry: parsed.value.options.offline ? offlineRegistry : realRegistry(repo),
627
+ });
628
+ if (done.kind === "err") {
629
+ stdio.stderr.writeSync(`release: ${done.error}\n`);
630
+ return 1;
631
+ }
632
+ for (const l of planLines(look, done.value.plan))
633
+ say(l);
634
+ say(`${label("done", `${done.value.written.length} files written; commit them, push to main, then run the workflow release`, look)}`);
635
+ return 0;
636
+ }
637
+ case "matrix": {
638
+ const file = join(repo, RECORD_PATH);
639
+ const entries = existsSync(file) ? readRecord(readTextFileSync(file)) : err(`${RECORD_PATH} is missing: run release apply`);
640
+ if (entries.kind === "err") {
641
+ stdio.stderr.writeSync(`release: ${entries.error}\n`);
642
+ return 1;
643
+ }
644
+ const tags = await readTags(repo);
645
+ if (tags.kind === "err") {
646
+ stdio.stderr.writeSync(`release: ${formatGitError(tags.error)}\n`);
647
+ return 1;
648
+ }
649
+ const text = matrixOutputs(entries.value, new Set(tags.value.map((t) => t.name)));
650
+ const out = parsed.value.options.githubOutput;
651
+ if (out === undefined)
652
+ say(text);
653
+ else
654
+ writeTextFileSync(out, `${text}\n`, { append: true });
655
+ return 0;
656
+ }
657
+ case "publish": {
658
+ const file = join(repo, RECORD_PATH);
659
+ const entries = existsSync(file) ? readRecord(readTextFileSync(file)) : err(`${RECORD_PATH} is missing: run release apply`);
660
+ const tags = await readTags(repo);
661
+ if (entries.kind === "err") {
662
+ stdio.stderr.writeSync(`release: ${entries.error}\n`);
663
+ return 1;
664
+ }
665
+ if (tags.kind === "err") {
666
+ stdio.stderr.writeSync(`release: ${formatGitError(tags.error)}\n`);
667
+ return 1;
668
+ }
669
+ const tagged = new Set(tags.value.map((t) => t.name));
670
+ const report = outcomeLines(await publishAll(entries.value.filter((e) => !tagged.has(e.tag)), realTools(resolve(repo, parsed.value.options.dir))));
671
+ for (const l of report.lines)
672
+ say(l);
673
+ return report.failed ? 1 : 0;
674
+ }
675
+ default:
676
+ return absurd(word);
677
+ }
678
+ }
679
+ if (import.meta.main)
680
+ process.exitCode = await main(process.argv.slice(2));