@intellectual-frontiers/libraries 0.2.1 → 0.4.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/LICENSE +75 -21
- package/dist/affected.d.ts +15 -2
- package/dist/affected.js +51 -20
- package/dist/dev.d.ts +83 -0
- package/dist/dev.js +359 -0
- package/dist/family.d.ts +58 -0
- package/dist/family.js +125 -0
- package/dist/generate-ontology.js +4 -0
- package/dist/generate-workflows.js +2 -10
- package/dist/install-bun.js +19 -14
- package/dist/libraries.d.ts +8 -0
- package/dist/libraries.js +24 -3
- package/dist/license/standard.d.ts +46 -0
- package/dist/license/standard.js +43 -0
- package/dist/license/third-party.d.ts +25 -0
- package/dist/license/third-party.js +71 -0
- package/dist/license.d.ts +61 -0
- package/dist/license.js +204 -0
- package/dist/link.d.ts +12 -0
- package/dist/link.js +98 -0
- package/dist/pack-library.d.ts +2 -0
- package/dist/pack-library.js +21 -3
- package/dist/pins.d.ts +34 -7
- package/dist/pins.js +36 -9
- package/dist/plan.d.ts +28 -0
- package/dist/plan.js +135 -0
- package/dist/readme.d.ts +59 -0
- package/dist/readme.js +272 -0
- package/dist/releasing.d.ts +176 -0
- package/dist/releasing.js +680 -0
- package/dist/versions.js +4 -7
- package/dist/workflows/definitions.d.ts +33 -30
- package/dist/workflows/definitions.js +201 -278
- package/dist/workflows/model.d.ts +19 -3
- package/dist/workflows/render.js +10 -2
- package/package.json +44 -14
- package/src/affected.ts +56 -17
- package/src/dev.ts +379 -0
- package/src/family.ts +144 -0
- package/src/generate-ontology.ts +4 -0
- package/src/generate-workflows.ts +3 -11
- package/src/install-bun.ts +16 -13
- package/src/libraries.ts +27 -3
- package/src/license/standard.ts +67 -0
- package/src/license/third-party.ts +87 -0
- package/src/license.ts +222 -0
- package/src/link.ts +97 -0
- package/src/pack-library.ts +21 -3
- package/src/pins.ts +55 -10
- package/src/plan.ts +143 -0
- package/src/readme.ts +278 -0
- package/src/releasing.ts +735 -0
- package/src/versions.ts +3 -7
- package/src/workflows/definitions.ts +262 -397
- package/src/workflows/model.ts +15 -3
- package/src/workflows/render.ts +10 -2
package/dist/readme.js
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The map of the libraries in the root `README.md`: the table between the markers `<!-- libraries-map:begin -->` and `<!-- libraries-map:end -->`, one row for each library of `commons/`, made from
|
|
3
|
+
* the manifests (`library.ts`) and the `summary` of each library's `about.ts`, so that the first page of the repository cannot name a library that is gone or miss one that is new.
|
|
4
|
+
*
|
|
5
|
+
* bun commons/libraries/src/readme.ts write the table again from the manifests
|
|
6
|
+
* bun commons/libraries/src/readme.ts --check write nothing and exit 1 where README.md is not what the manifests make
|
|
7
|
+
* other flags: --repo DIR (the repository, the working folder by default)
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* Both files are read as data and no library is run: the manifest by `readLibraries`, the summary of `about.ts` by reading the string literals that follow `summary:` (joined by `+`). A row has the library's package
|
|
11
|
+
* as a link (to npm where the library is published there, else to its folder), the first clause of the first sentence of its summary, its Kanon shape where the manifest declares a table (`layers`, and
|
|
12
|
+
* `instances` and `plugins` where it declares those), its conformance level and the registries it is published to. Rows are sorted by role, then by name; the role of a library is a closed union
|
|
13
|
+
* held in {@link ROLE_OF}, and a library with no entry there is a problem, never a row of no role. A version is not in the table: versions grow at the release, and a table that held them would be stale at every release.
|
|
14
|
+
*
|
|
15
|
+
* @limits
|
|
16
|
+
* It writes one file, README.md, and only between the markers; it does not judge the prose around them (the test of the README does).
|
|
17
|
+
*
|
|
18
|
+
* @example
|
|
19
|
+
* ```ts
|
|
20
|
+
* import { firstClause } from "./readme.ts";
|
|
21
|
+
* firstClause("Mizan, the IF Spec Profile, as code. The harness holds the rules."); // "Mizan, the IF Spec Profile, as code"
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* Spec: 0001-libraries FR-017
|
|
25
|
+
*
|
|
26
|
+
* @module
|
|
27
|
+
*/
|
|
28
|
+
import process from "node:process";
|
|
29
|
+
import { absurd, err, ok, refine, string } from "@intellectual-frontiers/core";
|
|
30
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
31
|
+
import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
32
|
+
import { readLibraries } from "./libraries.js";
|
|
33
|
+
/** The marker that opens the generated table, and the one that closes it. */
|
|
34
|
+
export const BEGIN = "<!-- libraries-map:begin -->";
|
|
35
|
+
export const END = "<!-- libraries-map:end -->";
|
|
36
|
+
/** What a library is for in the whole: a closed union. */
|
|
37
|
+
export const ROLES = ["foundation", "pattern", "program", "standard"];
|
|
38
|
+
/** The heading of a role in the table. */
|
|
39
|
+
export const ROLE_TITLE = {
|
|
40
|
+
foundation: "Foundation",
|
|
41
|
+
pattern: "Pattern",
|
|
42
|
+
program: "Program",
|
|
43
|
+
standard: "Standard",
|
|
44
|
+
};
|
|
45
|
+
const nameDecoder = refine(string, "library name", (t) => /^[a-z][a-z0-9-]*$/.test(t));
|
|
46
|
+
/** A library name from text, or why the text is not one. */
|
|
47
|
+
export function parseLibraryName(text) {
|
|
48
|
+
const r = nameDecoder(text, "name");
|
|
49
|
+
return r.kind === "ok" ? ok(r.value) : err(`${JSON.stringify(text)} is not a library name`);
|
|
50
|
+
}
|
|
51
|
+
/** The role of each library, by name. A new library is classified here, or the check names it. */
|
|
52
|
+
export const ROLE_OF = new Map([
|
|
53
|
+
["core", "foundation"],
|
|
54
|
+
["crypto", "foundation"],
|
|
55
|
+
["formats", "foundation"],
|
|
56
|
+
["githost", "foundation"],
|
|
57
|
+
["lint", "foundation"],
|
|
58
|
+
["net", "foundation"],
|
|
59
|
+
["rdf", "foundation"],
|
|
60
|
+
["system", "foundation"],
|
|
61
|
+
["telemetry", "foundation"],
|
|
62
|
+
["terminal", "foundation"],
|
|
63
|
+
["test", "foundation"],
|
|
64
|
+
["headless", "pattern"],
|
|
65
|
+
["kanon", "pattern"],
|
|
66
|
+
["archon", "program"],
|
|
67
|
+
["toolchain", "program"],
|
|
68
|
+
["data", "program"],
|
|
69
|
+
["ergonex", "program"],
|
|
70
|
+
["grc", "program"],
|
|
71
|
+
["integrations", "program"],
|
|
72
|
+
["integrations-github", "program"],
|
|
73
|
+
["libraries", "program"],
|
|
74
|
+
["integrations-fhir", "standard"],
|
|
75
|
+
["integrations-x12", "standard"],
|
|
76
|
+
["mizan", "standard"],
|
|
77
|
+
["ontology", "standard"],
|
|
78
|
+
["quality", "standard"],
|
|
79
|
+
]);
|
|
80
|
+
const roleRank = (r) => {
|
|
81
|
+
switch (r) {
|
|
82
|
+
case "foundation":
|
|
83
|
+
return 0;
|
|
84
|
+
case "pattern":
|
|
85
|
+
return 1;
|
|
86
|
+
case "program":
|
|
87
|
+
return 2;
|
|
88
|
+
case "standard":
|
|
89
|
+
return 3;
|
|
90
|
+
default:
|
|
91
|
+
return absurd(r);
|
|
92
|
+
}
|
|
93
|
+
};
|
|
94
|
+
/**
|
|
95
|
+
* The `summary` of an `about.ts`, read as data: the double-quoted string literals after `summary:`, joined by `+`, and nothing run.
|
|
96
|
+
* An error where the file has no summary or it is not literals.
|
|
97
|
+
*/
|
|
98
|
+
export function summaryOf(source) {
|
|
99
|
+
const m = /\bsummary:\s*/.exec(source);
|
|
100
|
+
if (m === null)
|
|
101
|
+
return err("it has no summary");
|
|
102
|
+
let at = m.index + m[0].length;
|
|
103
|
+
const parts = [];
|
|
104
|
+
for (;;) {
|
|
105
|
+
const lit = /^"(?:[^"\\\n]|\\.)*"/.exec(source.slice(at));
|
|
106
|
+
if (lit === null)
|
|
107
|
+
return err("its summary is not a string literal");
|
|
108
|
+
try {
|
|
109
|
+
const v = JSON.parse(lit[0]);
|
|
110
|
+
if (typeof v !== "string")
|
|
111
|
+
return err("its summary is not a string literal");
|
|
112
|
+
parts.push(v);
|
|
113
|
+
}
|
|
114
|
+
catch {
|
|
115
|
+
return err("its summary is not a string literal");
|
|
116
|
+
}
|
|
117
|
+
at += lit[0].length;
|
|
118
|
+
const plus = /^\s*\+\s*/.exec(source.slice(at));
|
|
119
|
+
if (plus === null)
|
|
120
|
+
break;
|
|
121
|
+
at += plus[0].length;
|
|
122
|
+
}
|
|
123
|
+
return ok(parts.join(""));
|
|
124
|
+
}
|
|
125
|
+
/** The first sentence of a text: up to the first full stop that is followed by a space or the end, outside parentheses and backticks. */
|
|
126
|
+
export function firstSentence(text) {
|
|
127
|
+
let depth = 0;
|
|
128
|
+
let tick = false;
|
|
129
|
+
for (let i = 0; i < text.length; i++) {
|
|
130
|
+
const c = text.charAt(i);
|
|
131
|
+
if (c === "`")
|
|
132
|
+
tick = !tick;
|
|
133
|
+
else if (tick)
|
|
134
|
+
continue;
|
|
135
|
+
else if (c === "(")
|
|
136
|
+
depth++;
|
|
137
|
+
else if (c === ")")
|
|
138
|
+
depth = Math.max(0, depth - 1);
|
|
139
|
+
else if (c === "." && depth === 0 && (i + 1 === text.length || /\s/.test(text.charAt(i + 1))))
|
|
140
|
+
return text.slice(0, i);
|
|
141
|
+
}
|
|
142
|
+
return text.trim();
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* The first clause of a text's first sentence: the sentence where it is short (110 characters or fewer), else the sentence cut at its first `:`, `;` or comma that is
|
|
146
|
+
* outside parentheses and backticks and at least 25 characters in; the whole sentence where it has no such place.
|
|
147
|
+
*/
|
|
148
|
+
export function firstClause(text) {
|
|
149
|
+
const sentence = firstSentence(text).replace(/\s+/g, " ").trim();
|
|
150
|
+
if (sentence.length <= 110)
|
|
151
|
+
return sentence;
|
|
152
|
+
let depth = 0;
|
|
153
|
+
let tick = false;
|
|
154
|
+
for (let i = 0; i < sentence.length; i++) {
|
|
155
|
+
const c = sentence.charAt(i);
|
|
156
|
+
if (c === "`")
|
|
157
|
+
tick = !tick;
|
|
158
|
+
else if (tick)
|
|
159
|
+
continue;
|
|
160
|
+
else if (c === "(")
|
|
161
|
+
depth++;
|
|
162
|
+
else if (c === ")")
|
|
163
|
+
depth = Math.max(0, depth - 1);
|
|
164
|
+
else if (depth === 0 && i >= 25 && (c === ":" || c === ";" || c === ","))
|
|
165
|
+
return sentence.slice(0, i);
|
|
166
|
+
}
|
|
167
|
+
return sentence;
|
|
168
|
+
}
|
|
169
|
+
/** The Kanon shape of a library: what its manifest declares, in words, or a dash where it declares no table. */
|
|
170
|
+
export function shapeOf(l) {
|
|
171
|
+
const t = l.kanon;
|
|
172
|
+
if (t === undefined)
|
|
173
|
+
return "-";
|
|
174
|
+
const parts = ["layers", ...(t.instances.length > 0 ? ["instances"] : []), ...(t.plugins.length > 0 ? ["plugins"] : []), ...(t.extends === undefined ? [] : ["extension"])];
|
|
175
|
+
return parts.join(", ");
|
|
176
|
+
}
|
|
177
|
+
/** A row of the table for a library and its summary, or why there is none. */
|
|
178
|
+
export function rowOf(l, summary) {
|
|
179
|
+
const name = parseLibraryName(l.name);
|
|
180
|
+
if (name.kind === "err")
|
|
181
|
+
return name;
|
|
182
|
+
const role = ROLE_OF.get(l.name);
|
|
183
|
+
if (role === undefined)
|
|
184
|
+
return err(`commons/${l.name} has no role in ROLE_OF (commons/libraries/src/readme.ts): say whether it is a foundation, a pattern, a program or a standard`);
|
|
185
|
+
return ok({
|
|
186
|
+
name: name.value,
|
|
187
|
+
role,
|
|
188
|
+
purpose: firstClause(summary).replace(/\|/g, "\\|"),
|
|
189
|
+
shape: shapeOf(l),
|
|
190
|
+
level: l.level,
|
|
191
|
+
distribution: l.distribution,
|
|
192
|
+
published: l.distribution.includes("npm"),
|
|
193
|
+
});
|
|
194
|
+
}
|
|
195
|
+
const REGISTRY_TITLE = { github: "GitHub", npm: "npm" };
|
|
196
|
+
/** The table, as Markdown, for the rows given: sorted by role, then by name. */
|
|
197
|
+
export function tableOf(rows) {
|
|
198
|
+
const sorted = [...rows].sort((a, b) => roleRank(a.role) - roleRank(b.role) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
|
|
199
|
+
const head = ["| Library | Role | What it is | Kanon | Level | Published to |", "| --- | --- | --- | --- | --- | --- |"];
|
|
200
|
+
const body = sorted.map((r) => {
|
|
201
|
+
const pkg = `@intellectual-frontiers/${r.name}`;
|
|
202
|
+
const href = r.published ? `https://www.npmjs.com/package/${pkg}` : `commons/${r.name}`;
|
|
203
|
+
return `| [\`${pkg}\`](${href}) | ${ROLE_TITLE[r.role]} | ${r.purpose} | ${r.shape} | ${r.level} | ${r.distribution.map((d) => REGISTRY_TITLE[d]).join(", ")} |`;
|
|
204
|
+
});
|
|
205
|
+
return [...head, ...body].join("\n");
|
|
206
|
+
}
|
|
207
|
+
/** The rows of a repository, and what is wrong with reading them. */
|
|
208
|
+
export function rowsOf(repo) {
|
|
209
|
+
const root = repo.replace(/[\\/]$/, "");
|
|
210
|
+
const rows = [];
|
|
211
|
+
const problems = [];
|
|
212
|
+
for (const f of readLibraries(root)) {
|
|
213
|
+
if ("problem" in f) {
|
|
214
|
+
problems.push(`commons/${f.dir}/library.ts: ${f.problem}`);
|
|
215
|
+
continue;
|
|
216
|
+
}
|
|
217
|
+
const file = `${root}/commons/${f.dir}/about.ts`;
|
|
218
|
+
if (!existsSync(file)) {
|
|
219
|
+
problems.push(`commons/${f.dir}/about.ts is missing: the table takes its purpose from the summary there`);
|
|
220
|
+
continue;
|
|
221
|
+
}
|
|
222
|
+
const s = summaryOf(readTextFileSync(file));
|
|
223
|
+
if (s.kind === "err") {
|
|
224
|
+
problems.push(`commons/${f.dir}/about.ts: ${s.error}`);
|
|
225
|
+
continue;
|
|
226
|
+
}
|
|
227
|
+
const r = rowOf(f.library, s.value);
|
|
228
|
+
if (r.kind === "err")
|
|
229
|
+
problems.push(r.error);
|
|
230
|
+
else
|
|
231
|
+
rows.push(r.value);
|
|
232
|
+
}
|
|
233
|
+
return { rows, problems };
|
|
234
|
+
}
|
|
235
|
+
/** The README made again from its text and the table: the text between the markers (on lines of their own) replaced; an error where the markers are missing. */
|
|
236
|
+
export function withTable(readme, table) {
|
|
237
|
+
const from = readme.indexOf(`\n${BEGIN}\n`);
|
|
238
|
+
const to = readme.indexOf(`\n${END}\n`, from);
|
|
239
|
+
if (from < 0 || to < 0)
|
|
240
|
+
return err(`README.md has no ${BEGIN} and ${END}, each on a line of its own, around the table of the libraries`);
|
|
241
|
+
return ok(`${readme.slice(0, from + 1 + BEGIN.length)}\n\n${table}\n\n${readme.slice(to + 1)}`);
|
|
242
|
+
}
|
|
243
|
+
/** The result of a run: whether README.md is stale, and the problems found. With `write`, the file is written where it is stale. */
|
|
244
|
+
export function synchronize(repo, write) {
|
|
245
|
+
const root = repo.replace(/[\\/]$/, "");
|
|
246
|
+
const file = `${root}/README.md`;
|
|
247
|
+
const { rows, problems } = rowsOf(root);
|
|
248
|
+
if (!existsSync(file))
|
|
249
|
+
return { stale: false, problems: [...problems, "README.md is missing"] };
|
|
250
|
+
const text = readTextFileSync(file).replace(/\r\n/g, "\n");
|
|
251
|
+
const made = withTable(text, tableOf(rows));
|
|
252
|
+
if (made.kind === "err")
|
|
253
|
+
return { stale: false, problems: [...problems, made.error] };
|
|
254
|
+
const stale = made.value !== text;
|
|
255
|
+
if (stale && write && problems.length === 0)
|
|
256
|
+
writeTextFileSync(file, made.value);
|
|
257
|
+
return { stale, problems };
|
|
258
|
+
}
|
|
259
|
+
/** The command line: 0, or 1 where a problem was found or, with `--check`, README.md is not what the manifests make. */
|
|
260
|
+
export function main(argv) {
|
|
261
|
+
const at = argv.indexOf("--repo");
|
|
262
|
+
const repo = at >= 0 ? (argv[at + 1] ?? ".") : ".";
|
|
263
|
+
const check = argv.includes("--check");
|
|
264
|
+
const r = synchronize(repo, !check);
|
|
265
|
+
for (const p of r.problems)
|
|
266
|
+
stdio.stderr.writeSync(`${p}\n`);
|
|
267
|
+
if (r.stale)
|
|
268
|
+
stdio.stderr.writeSync(check ? "README.md is not what the manifests make; run: bun commons/libraries/src/readme.ts\n" : "wrote README.md\n");
|
|
269
|
+
return r.problems.length > 0 || (check && r.stale) ? 1 : 0;
|
|
270
|
+
}
|
|
271
|
+
if (import.meta.main)
|
|
272
|
+
process.exitCode = main(process.argv.slice(2));
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
2
|
+
import { type Look } from "@intellectual-frontiers/system/tty";
|
|
3
|
+
import { type Slug } from "@intellectual-frontiers/mizan/versions/record";
|
|
4
|
+
import { type Impact } from "@intellectual-frontiers/mizan/versions/scheme";
|
|
5
|
+
/** The record of the release, from the repository's root. */
|
|
6
|
+
export declare const RECORD_PATH = "commons/generated/release.auto.json";
|
|
7
|
+
/** What the plan knows of a library: its version, what it imports, the last tag of it, whether its files changed since, and the impact the commits since state. */
|
|
8
|
+
export type Facts = {
|
|
9
|
+
readonly slug: Slug;
|
|
10
|
+
readonly folder: string;
|
|
11
|
+
readonly version: string;
|
|
12
|
+
/** The libraries (by slug) whose package its own sources import. */
|
|
13
|
+
readonly imports: readonly Slug[];
|
|
14
|
+
/** The greatest tag of the library by Semantic Version precedence, where it has one. */
|
|
15
|
+
readonly last: {
|
|
16
|
+
readonly version: string;
|
|
17
|
+
readonly tag: string;
|
|
18
|
+
} | undefined;
|
|
19
|
+
/** Whether a file of the library changed since `last`; false where there is none. */
|
|
20
|
+
readonly changed: boolean;
|
|
21
|
+
/** The greatest impact the commits since `last` state, a patch where none does. */
|
|
22
|
+
readonly impact: Impact;
|
|
23
|
+
/** Whether the release sends it to a registry: a library that names npm. */
|
|
24
|
+
readonly publish: boolean;
|
|
25
|
+
/** For a version that is not tagged or is ahead of its tag: what npm holds of this version, compared with the files of the library. */
|
|
26
|
+
readonly registry: Drift;
|
|
27
|
+
/** Whether a file of the library changed since the last commit that raised its version, and the impact the commits since state (a patch where none does): the fallback where npm cannot be compared. */
|
|
28
|
+
readonly sinceVersion: {
|
|
29
|
+
readonly changed: boolean;
|
|
30
|
+
readonly impact: Impact;
|
|
31
|
+
};
|
|
32
|
+
};
|
|
33
|
+
/** What npm holds of a version, against the files of the library: not there, there and the same, there and different, or not known (offline, or the registry did not say). */
|
|
34
|
+
export type Drift = "absent" | "same" | "differs" | "unknown";
|
|
35
|
+
/** Why a library is raised. */
|
|
36
|
+
export type Why = "changed" | "differs-from-npm" | "changed-since-version" | "manual";
|
|
37
|
+
/** What the release does to one library. */
|
|
38
|
+
export type Decision = {
|
|
39
|
+
readonly kind: "unchanged";
|
|
40
|
+
} | {
|
|
41
|
+
readonly kind: "as-is";
|
|
42
|
+
readonly why: "no-tag" | "ahead-of-tag";
|
|
43
|
+
readonly npm: Drift;
|
|
44
|
+
} | {
|
|
45
|
+
readonly kind: "raised";
|
|
46
|
+
readonly to: string;
|
|
47
|
+
readonly impact: Impact;
|
|
48
|
+
readonly why: Why;
|
|
49
|
+
} | {
|
|
50
|
+
readonly kind: "dependent";
|
|
51
|
+
readonly to: string;
|
|
52
|
+
readonly because: readonly Slug[];
|
|
53
|
+
};
|
|
54
|
+
/** One step of a release: a library, its version before and after, and what is done to it. */
|
|
55
|
+
export type Step = {
|
|
56
|
+
readonly slug: Slug;
|
|
57
|
+
readonly folder: string;
|
|
58
|
+
readonly from: string;
|
|
59
|
+
readonly to: string;
|
|
60
|
+
readonly tag: string;
|
|
61
|
+
readonly publish: boolean;
|
|
62
|
+
readonly decision: Exclude<Decision, {
|
|
63
|
+
readonly kind: "unchanged";
|
|
64
|
+
}>;
|
|
65
|
+
};
|
|
66
|
+
/** The plan: every step in the order of the imports, and the libraries that are left alone. */
|
|
67
|
+
export type Plan = {
|
|
68
|
+
readonly steps: readonly Step[];
|
|
69
|
+
readonly unchanged: readonly Slug[];
|
|
70
|
+
};
|
|
71
|
+
/** The text of a decision, in a sentence. */
|
|
72
|
+
export declare function describe(d: Decision, from: string): string;
|
|
73
|
+
/**
|
|
74
|
+
* 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,
|
|
75
|
+
* 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.
|
|
76
|
+
*/
|
|
77
|
+
export declare function planRelease(facts: readonly Facts[], raise?: ReadonlyMap<string, Impact | undefined>): Result<Plan, string>;
|
|
78
|
+
/** The record the workflow reads, as the bytes of its file: the steps that publish or tag, in order. */
|
|
79
|
+
export declare function recordText(plan: Plan): string;
|
|
80
|
+
/** One entry of the record, as the workflow reads it. */
|
|
81
|
+
export type Entry = {
|
|
82
|
+
readonly slug: string;
|
|
83
|
+
readonly version: string;
|
|
84
|
+
readonly folder: string;
|
|
85
|
+
readonly tag: string;
|
|
86
|
+
readonly publish: boolean;
|
|
87
|
+
};
|
|
88
|
+
/** The entries of a record's text, or why it is not one. */
|
|
89
|
+
export declare function readRecord(text: string): Result<readonly Entry[], string>;
|
|
90
|
+
/** 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. */
|
|
91
|
+
export declare function matrixOutputs(entries: readonly Entry[], tagged: ReadonlySet<string>): string;
|
|
92
|
+
/** 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. */
|
|
93
|
+
export declare function writeVersion(repo: string, step: Step): Result<readonly string[], string>;
|
|
94
|
+
/** What a tarball holds that the comparison reads: the SHA-256 of each file by its path (without the folder `package/`), and the text of its `package.json`. */
|
|
95
|
+
export type Tarball = {
|
|
96
|
+
readonly hashes: ReadonlyMap<string, string>;
|
|
97
|
+
readonly packageJson: string;
|
|
98
|
+
};
|
|
99
|
+
/** 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. */
|
|
100
|
+
export declare function tarballOf(gz: Uint8Array): Tarball;
|
|
101
|
+
/**
|
|
102
|
+
* 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
|
|
103
|
+
* `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.
|
|
104
|
+
*/
|
|
105
|
+
export declare function driftOf(published: Tarball, local: {
|
|
106
|
+
readonly hash: (path: string) => string | undefined;
|
|
107
|
+
readonly packageJson: string;
|
|
108
|
+
}): "same" | "differs";
|
|
109
|
+
/** Compares a library's version with what npm holds of it. */
|
|
110
|
+
export type Registry = (slug: string, version: string, folder: string) => Promise<Drift>;
|
|
111
|
+
/** 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. */
|
|
112
|
+
export declare function realRegistry(repo: string): Registry;
|
|
113
|
+
/** What the host gives the plan: the facts of the libraries from the tags and the tree. */
|
|
114
|
+
export declare function factsOf(repo: string, registry?: Registry): Promise<Result<readonly Facts[], string>>;
|
|
115
|
+
/** 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`. */
|
|
116
|
+
export declare const GENERATORS: readonly (readonly string[])[];
|
|
117
|
+
/** 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). */
|
|
118
|
+
export declare const PACKAGE_TESTS: readonly string[];
|
|
119
|
+
/** What `apply` runs besides the planner: the generators and the tests, which a test of this module replaces. */
|
|
120
|
+
export type Host = {
|
|
121
|
+
readonly generate: (repo: string, command: readonly string[]) => Promise<Result<void, string>>;
|
|
122
|
+
readonly prove: (repo: string) => Promise<Result<void, string>>;
|
|
123
|
+
};
|
|
124
|
+
/** The real host: each command run with Bun from the repository's root. */
|
|
125
|
+
export declare const REAL: Host;
|
|
126
|
+
/** What `apply` did: the files written, in order. */
|
|
127
|
+
export type Applied = {
|
|
128
|
+
readonly plan: Plan;
|
|
129
|
+
readonly written: readonly string[];
|
|
130
|
+
};
|
|
131
|
+
/** 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. */
|
|
132
|
+
export declare function applyRelease(repo: string, host: Host, options: {
|
|
133
|
+
readonly tests: boolean;
|
|
134
|
+
readonly raise?: ReadonlyMap<string, Impact | undefined>;
|
|
135
|
+
readonly registry?: Registry;
|
|
136
|
+
}): Promise<Result<Applied, string>>;
|
|
137
|
+
/** The lines the plan prints: one for each library that is released, and the libraries left alone. */
|
|
138
|
+
export declare function planLines(look: Look, plan: Plan): readonly string[];
|
|
139
|
+
/** What the publication needs from the world, so that its order and its rules are a pure function of what these say. */
|
|
140
|
+
export type Tools = {
|
|
141
|
+
/** Whether the version is on npm (asked again after a pause where it is not, because a version put there by hand may take a while to show). */
|
|
142
|
+
readonly onNpm: (name: string, version: string) => Promise<boolean>;
|
|
143
|
+
/** Sends the package to npm; the reason where it cannot (no trusted publisher and no token, or npm refused). */
|
|
144
|
+
readonly npm: (e: Entry) => Promise<Result<void, string>>;
|
|
145
|
+
/** Sends the package to the GitHub package registry, unless it is there. */
|
|
146
|
+
readonly github: (e: Entry) => Promise<Result<void, string>>;
|
|
147
|
+
/** Makes the tag at the commit that runs, or finds it there. */
|
|
148
|
+
readonly tag: (tag: string) => Promise<Result<"made" | "there", string>>;
|
|
149
|
+
};
|
|
150
|
+
/** What happened to one release: the state of its publication, and of its tag. */
|
|
151
|
+
export type Outcome = {
|
|
152
|
+
readonly slug: string;
|
|
153
|
+
readonly tag: string;
|
|
154
|
+
readonly npm: "present" | "published" | "failed" | "not-published";
|
|
155
|
+
readonly registry: "done" | "failed" | "not-published";
|
|
156
|
+
readonly tagged: "made" | "there" | "withheld" | "failed";
|
|
157
|
+
readonly reasons: readonly string[];
|
|
158
|
+
};
|
|
159
|
+
/**
|
|
160
|
+
* 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
|
|
161
|
+
* 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.
|
|
162
|
+
*/
|
|
163
|
+
export declare function publishAll(entries: readonly Entry[], tools: Tools): Promise<readonly Outcome[]>;
|
|
164
|
+
/** 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. */
|
|
165
|
+
export declare function outcomeLines(outcomes: readonly Outcome[]): {
|
|
166
|
+
readonly lines: readonly string[];
|
|
167
|
+
readonly failed: boolean;
|
|
168
|
+
};
|
|
169
|
+
/** 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. */
|
|
170
|
+
export declare function realTools(dir: string): Tools;
|
|
171
|
+
/** What `--raise` says: each library by its name, with the impact after an `=` where one is given. */
|
|
172
|
+
export declare function raiseOf(words: readonly string[]): Result<ReadonlyMap<string, Impact | undefined>, string>;
|
|
173
|
+
/** The registry that is not asked (`--offline`). */
|
|
174
|
+
export declare const offlineRegistry: Registry;
|
|
175
|
+
/** 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. */
|
|
176
|
+
export declare function main(argv: readonly string[], host?: Host): Promise<number>;
|