@intellectual-frontiers/libraries 0.4.0 → 0.5.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.
- package/LICENSE +75 -21
- package/dist/affected.d.ts +1 -1
- package/dist/dev.d.ts +2 -0
- package/dist/dev.js +14 -2
- package/dist/family.js +1 -0
- package/dist/generate-ontology.js +4 -0
- package/dist/imports/nist-sp-800-53.auto.prov.ttl +22 -0
- package/dist/imports/schema-org.auto.prov.ttl +22 -0
- package/dist/install-bun.js +19 -14
- package/dist/libraries.d.ts +39 -2
- package/dist/libraries.js +80 -9
- package/dist/license/PolyForm-Noncommercial-1.0.0.md +73 -0
- 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 +1 -1
- package/dist/link.js +4 -4
- package/dist/metapackages.d.ts +62 -0
- package/dist/metapackages.js +190 -0
- package/dist/mod.d.ts +1 -1
- package/dist/mod.js +1 -1
- package/dist/pack-library.d.ts +9 -0
- package/dist/pack-library.js +46 -58
- package/dist/pack-metapackage.d.ts +22 -0
- package/dist/pack-metapackage.js +147 -0
- package/dist/pins.d.ts +34 -7
- package/dist/pins.js +36 -9
- package/dist/readme.d.ts +71 -0
- package/dist/readme.js +310 -0
- package/dist/releasing.d.ts +8 -1
- package/dist/releasing.js +44 -14
- package/dist/workflows/definitions.d.ts +2 -2
- package/dist/workflows/definitions.js +32 -114
- package/dist/workflows/model.d.ts +6 -0
- package/dist/workflows/render.js +2 -0
- package/dist/workflows/schema/github-workflow.schema.json +2290 -0
- package/package.json +39 -14
- package/src/affected.ts +1 -1
- package/src/dev.ts +13 -2
- package/src/family.ts +1 -0
- package/src/generate-ontology.ts +4 -0
- package/src/imports/nist-sp-800-53.auto.prov.ttl +22 -0
- package/src/imports/schema-org.auto.prov.ttl +22 -0
- package/src/install-bun.ts +16 -13
- package/src/libraries.ts +100 -8
- package/src/license/PolyForm-Noncommercial-1.0.0.md +73 -0
- 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 +4 -4
- package/src/metapackages.ts +206 -0
- package/src/mod.ts +1 -1
- package/src/pack-library.ts +52 -55
- package/src/pack-metapackage.ts +137 -0
- package/src/pins.ts +55 -10
- package/src/readme.ts +320 -0
- package/src/releasing.ts +47 -16
- package/src/workflows/definitions.ts +36 -133
- package/src/workflows/model.ts +6 -0
- package/src/workflows/render.ts +1 -0
- package/src/workflows/schema/github-workflow.schema.json +2290 -0
package/src/readme.ts
ADDED
|
@@ -0,0 +1,320 @@
|
|
|
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, type Brand, err, ok, refine, type Result, string } from "@intellectual-frontiers/core";
|
|
30
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
31
|
+
import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
32
|
+
import { type Library, type Registry, readLibraries } from "./libraries.ts";
|
|
33
|
+
|
|
34
|
+
/** The marker that opens the generated table. */
|
|
35
|
+
export const BEGIN = "<!-- libraries-map:begin -->";
|
|
36
|
+
/** The marker that closes the generated table. */
|
|
37
|
+
export const END = "<!-- libraries-map:end -->";
|
|
38
|
+
|
|
39
|
+
/** What a library is for in the whole: a closed union. */
|
|
40
|
+
export const ROLES = ["foundation", "pattern", "program", "standard"] as const;
|
|
41
|
+
/** A role a reader of the README may be in, as the generated library map names them. */
|
|
42
|
+
export type Role = (typeof ROLES)[number];
|
|
43
|
+
|
|
44
|
+
/** The heading of a role in the table. */
|
|
45
|
+
export const ROLE_TITLE: Readonly<Record<Role, string>> = {
|
|
46
|
+
foundation: "Foundation",
|
|
47
|
+
pattern: "Pattern",
|
|
48
|
+
program: "Program",
|
|
49
|
+
standard: "Standard",
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
/** A library's name (its folder), made only by {@link parseLibraryName}. */
|
|
53
|
+
export type LibraryName = Brand<string, "library name">;
|
|
54
|
+
const nameDecoder = refine(string, "library name", (t) => /^[a-z][a-z0-9-]*$/.test(t));
|
|
55
|
+
|
|
56
|
+
/** A library name from text, or why the text is not one. */
|
|
57
|
+
export function parseLibraryName(text: string): Result<LibraryName, string> {
|
|
58
|
+
const r = nameDecoder(text, "name");
|
|
59
|
+
return r.kind === "ok" ? ok(r.value) : err(`${JSON.stringify(text)} is not a library name`);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** The role of each library, by name. A new library is classified here, or the check names it. */
|
|
63
|
+
export const ROLE_OF: ReadonlyMap<string, Role> = new Map<string, Role>([
|
|
64
|
+
["core", "foundation"],
|
|
65
|
+
["crypto", "foundation"],
|
|
66
|
+
["formats", "foundation"],
|
|
67
|
+
["githost", "foundation"],
|
|
68
|
+
["lint", "foundation"],
|
|
69
|
+
["net", "foundation"],
|
|
70
|
+
["rdf", "foundation"],
|
|
71
|
+
["system", "foundation"],
|
|
72
|
+
["telemetry", "foundation"],
|
|
73
|
+
["terminal", "foundation"],
|
|
74
|
+
["test", "foundation"],
|
|
75
|
+
["headless", "pattern"],
|
|
76
|
+
["kanon", "pattern"],
|
|
77
|
+
["archon", "program"],
|
|
78
|
+
["toolchain", "program"],
|
|
79
|
+
["archon-dialect-native-pinned", "program"],
|
|
80
|
+
["package-managers", "program"],
|
|
81
|
+
["archon-dialect-apt", "program"],
|
|
82
|
+
["archon-dialect-homebrew", "program"],
|
|
83
|
+
["archon-dialect-mise", "program"],
|
|
84
|
+
["archon-dialect-winget", "program"],
|
|
85
|
+
["archon-tool", "program"],
|
|
86
|
+
["estate", "program"],
|
|
87
|
+
["data", "program"],
|
|
88
|
+
["docs", "program"],
|
|
89
|
+
["ergonex", "program"],
|
|
90
|
+
["grc", "program"],
|
|
91
|
+
["integrations", "program"],
|
|
92
|
+
["integrations-github", "program"],
|
|
93
|
+
["libraries", "program"],
|
|
94
|
+
["repoctl", "program"],
|
|
95
|
+
["integrations-fhir", "standard"],
|
|
96
|
+
["integrations-x12", "standard"],
|
|
97
|
+
["mizan", "standard"],
|
|
98
|
+
["ontology", "standard"],
|
|
99
|
+
["quality", "standard"],
|
|
100
|
+
]);
|
|
101
|
+
|
|
102
|
+
const roleRank = (r: Role): number => {
|
|
103
|
+
switch (r) {
|
|
104
|
+
case "foundation":
|
|
105
|
+
return 0;
|
|
106
|
+
case "pattern":
|
|
107
|
+
return 1;
|
|
108
|
+
case "program":
|
|
109
|
+
return 2;
|
|
110
|
+
case "standard":
|
|
111
|
+
return 3;
|
|
112
|
+
default:
|
|
113
|
+
return absurd(r);
|
|
114
|
+
}
|
|
115
|
+
};
|
|
116
|
+
|
|
117
|
+
/** One row of the table. */
|
|
118
|
+
export type Row = {
|
|
119
|
+
readonly name: LibraryName;
|
|
120
|
+
readonly role: Role;
|
|
121
|
+
readonly purpose: string;
|
|
122
|
+
readonly shape: string;
|
|
123
|
+
readonly level: string;
|
|
124
|
+
readonly distribution: readonly Registry[];
|
|
125
|
+
readonly published: boolean;
|
|
126
|
+
/** Why the library is held out of the release, where it is. */
|
|
127
|
+
readonly held: string | undefined;
|
|
128
|
+
};
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* The `summary` of an `about.ts`, read as data: the double-quoted string literals after `summary:`, joined by `+`, and nothing run.
|
|
132
|
+
* An error where the file has no summary or it is not literals.
|
|
133
|
+
*/
|
|
134
|
+
export function summaryOf(source: string): Result<string, string> {
|
|
135
|
+
const m = /\bsummary:\s*/.exec(source);
|
|
136
|
+
if (m === null) return err("it has no summary");
|
|
137
|
+
let at = m.index + m[0].length;
|
|
138
|
+
const parts: string[] = [];
|
|
139
|
+
for (;;) {
|
|
140
|
+
const lit = /^"(?:[^"\\\n]|\\.)*"/.exec(source.slice(at));
|
|
141
|
+
if (lit === null) return err("its summary is not a string literal");
|
|
142
|
+
try {
|
|
143
|
+
const v: unknown = JSON.parse(lit[0]);
|
|
144
|
+
if (typeof v !== "string") return err("its summary is not a string literal");
|
|
145
|
+
parts.push(v);
|
|
146
|
+
} catch {
|
|
147
|
+
return err("its summary is not a string literal");
|
|
148
|
+
}
|
|
149
|
+
at += lit[0].length;
|
|
150
|
+
const plus = /^\s*\+\s*/.exec(source.slice(at));
|
|
151
|
+
if (plus === null) break;
|
|
152
|
+
at += plus[0].length;
|
|
153
|
+
}
|
|
154
|
+
return ok(parts.join(""));
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** 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. */
|
|
158
|
+
export function firstSentence(text: string): string {
|
|
159
|
+
let depth = 0;
|
|
160
|
+
let tick = false;
|
|
161
|
+
for (let i = 0; i < text.length; i++) {
|
|
162
|
+
const c = text.charAt(i);
|
|
163
|
+
if (c === "`") tick = !tick;
|
|
164
|
+
else if (tick) continue;
|
|
165
|
+
else if (c === "(") depth++;
|
|
166
|
+
else if (c === ")") depth = Math.max(0, depth - 1);
|
|
167
|
+
else if (c === "." && depth === 0 && (i + 1 === text.length || /\s/.test(text.charAt(i + 1)))) return text.slice(0, i);
|
|
168
|
+
}
|
|
169
|
+
return text.trim();
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* 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
|
|
174
|
+
* outside parentheses and backticks and at least 25 characters in; the whole sentence where it has no such place.
|
|
175
|
+
*/
|
|
176
|
+
export function firstClause(text: string): string {
|
|
177
|
+
const sentence = firstSentence(text).replace(/\s+/g, " ").trim();
|
|
178
|
+
if (sentence.length <= 110) return sentence;
|
|
179
|
+
let depth = 0;
|
|
180
|
+
let tick = false;
|
|
181
|
+
for (let i = 0; i < sentence.length; i++) {
|
|
182
|
+
const c = sentence.charAt(i);
|
|
183
|
+
if (c === "`") tick = !tick;
|
|
184
|
+
else if (tick) continue;
|
|
185
|
+
else if (c === "(") depth++;
|
|
186
|
+
else if (c === ")") depth = Math.max(0, depth - 1);
|
|
187
|
+
else if (depth === 0 && i >= 25 && (c === ":" || c === ";" || c === ",")) return sentence.slice(0, i);
|
|
188
|
+
}
|
|
189
|
+
return sentence;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** The Kanon shape of a library: what its manifest declares, in words, or a dash where it declares no table. */
|
|
193
|
+
export function shapeOf(l: Library): string {
|
|
194
|
+
const t = l.kanon;
|
|
195
|
+
if (t === undefined) return "-";
|
|
196
|
+
const parts = ["layers", ...(t.instances.length > 0 ? ["instances"] : []), ...(t.plugins.length > 0 ? ["plugins"] : []), ...(t.extends === undefined ? [] : ["extension"])];
|
|
197
|
+
return parts.join(", ");
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/** A row of the table for a library and its summary, or why there is none. */
|
|
201
|
+
export function rowOf(l: Library, summary: string): Result<Row, string> {
|
|
202
|
+
const name = parseLibraryName(l.name);
|
|
203
|
+
if (name.kind === "err") return name;
|
|
204
|
+
const role = ROLE_OF.get(l.name);
|
|
205
|
+
if (role === undefined) 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`);
|
|
206
|
+
return ok({
|
|
207
|
+
name: name.value,
|
|
208
|
+
role,
|
|
209
|
+
purpose: firstClause(summary).replace(/\|/g, "\\|"),
|
|
210
|
+
shape: shapeOf(l),
|
|
211
|
+
level: l.level,
|
|
212
|
+
distribution: l.distribution,
|
|
213
|
+
published: l.held === undefined && l.distribution.includes("npm"),
|
|
214
|
+
held: l.held,
|
|
215
|
+
});
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
const REGISTRY_TITLE: Readonly<Record<Registry, string>> = { github: "GitHub", npm: "npm" };
|
|
219
|
+
|
|
220
|
+
/** The table, as Markdown, for the rows given: sorted by role, then by name. */
|
|
221
|
+
export function tableOf(rows: readonly Row[]): string {
|
|
222
|
+
const sorted = [...rows].sort((a, b) => roleRank(a.role) - roleRank(b.role) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
|
|
223
|
+
const head = ["| Library | Role | What it is | Kanon | Level | Published to |", "| --- | --- | --- | --- | --- | --- |"];
|
|
224
|
+
const body = sorted.map((r) => {
|
|
225
|
+
const pkg = `@intellectual-frontiers/${r.name}`;
|
|
226
|
+
const href = r.published ? `https://www.npmjs.com/package/${pkg}` : `commons/${r.name}`;
|
|
227
|
+
return `| [\`${pkg}\`](${href}) | ${ROLE_TITLE[r.role]} | ${r.purpose} | ${r.shape} | ${r.level} | ${r.held === undefined ? r.distribution.map((d) => REGISTRY_TITLE[d]).join(", ") : "held"} |`;
|
|
228
|
+
});
|
|
229
|
+
return [...head, ...body].join("\n");
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** The rows of a repository, and what is wrong with reading them. */
|
|
233
|
+
export function rowsOf(repo: string): { readonly rows: readonly Row[]; readonly problems: readonly string[] } {
|
|
234
|
+
const root = repo.replace(/[\\/]$/, "");
|
|
235
|
+
const rows: Row[] = [];
|
|
236
|
+
const problems: string[] = [];
|
|
237
|
+
for (const f of readLibraries(root)) {
|
|
238
|
+
if ("problem" in f) {
|
|
239
|
+
problems.push(`commons/${f.dir}/library.ts: ${f.problem}`);
|
|
240
|
+
continue;
|
|
241
|
+
}
|
|
242
|
+
if (f.library.bundle !== undefined) continue; // a metapackage has no about.ts and is listed by {@link bundlesOf}
|
|
243
|
+
const file = `${root}/commons/${f.dir}/about.ts`;
|
|
244
|
+
if (!existsSync(file)) {
|
|
245
|
+
problems.push(`commons/${f.dir}/about.ts is missing: the table takes its purpose from the summary there`);
|
|
246
|
+
continue;
|
|
247
|
+
}
|
|
248
|
+
const s = summaryOf(readTextFileSync(file));
|
|
249
|
+
if (s.kind === "err") {
|
|
250
|
+
problems.push(`commons/${f.dir}/about.ts: ${s.error}`);
|
|
251
|
+
continue;
|
|
252
|
+
}
|
|
253
|
+
const r = rowOf(f.library, s.value);
|
|
254
|
+
if (r.kind === "err") problems.push(r.error);
|
|
255
|
+
else rows.push(r.value);
|
|
256
|
+
}
|
|
257
|
+
return { rows, problems };
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/** One row of the table of the metapackages: the package and what it is. */
|
|
261
|
+
export type BundleRow = { readonly name: string; readonly purpose: string };
|
|
262
|
+
|
|
263
|
+
/** The rows of the metapackages of a repository, in the order of their folders' names: each the package and the first clause of the summary its manifest gives. */
|
|
264
|
+
export function bundlesOf(repo: string): readonly BundleRow[] {
|
|
265
|
+
const rows: BundleRow[] = [];
|
|
266
|
+
for (const f of readLibraries(repo.replace(/[\\/]$/, ""))) {
|
|
267
|
+
if ("problem" in f || f.library.bundle === undefined) continue;
|
|
268
|
+
rows.push({ name: f.library.name, purpose: firstClause(f.library.summary ?? "").replace(/\|/g, "\\|") });
|
|
269
|
+
}
|
|
270
|
+
return rows;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/** The table of the metapackages, as Markdown, with the sentence that introduces it; nothing where a repository has none. */
|
|
274
|
+
export function bundlesTableOf(rows: readonly BundleRow[]): string {
|
|
275
|
+
if (rows.length === 0) return "";
|
|
276
|
+
const body = rows.map((r) => `| [\`@intellectual-frontiers/${r.name}\`](https://www.npmjs.com/package/@intellectual-frontiers/${r.name}) | ${r.purpose} |`);
|
|
277
|
+
return [
|
|
278
|
+
"Metapackages: no code of their own, each depends on a set of the libraries above at exact versions (commons 0036-distribution). Install one of them, or a library.",
|
|
279
|
+
"",
|
|
280
|
+
"| Metapackage | What it holds |",
|
|
281
|
+
"| --- | --- |",
|
|
282
|
+
...body,
|
|
283
|
+
].join("\n");
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/** 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. */
|
|
287
|
+
export function withTable(readme: string, table: string): Result<string, string> {
|
|
288
|
+
const from = readme.indexOf(`\n${BEGIN}\n`);
|
|
289
|
+
const to = readme.indexOf(`\n${END}\n`, from);
|
|
290
|
+
if (from < 0 || to < 0) return err(`README.md has no ${BEGIN} and ${END}, each on a line of its own, around the table of the libraries`);
|
|
291
|
+
return ok(`${readme.slice(0, from + 1 + BEGIN.length)}\n\n${table}\n\n${readme.slice(to + 1)}`);
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/** The result of a run: whether README.md is stale, and the problems found. With `write`, the file is written where it is stale. */
|
|
295
|
+
export function synchronize(repo: string, write: boolean): { readonly stale: boolean; readonly problems: readonly string[] } {
|
|
296
|
+
const root = repo.replace(/[\\/]$/, "");
|
|
297
|
+
const file = `${root}/README.md`;
|
|
298
|
+
const { rows, problems } = rowsOf(root);
|
|
299
|
+
if (!existsSync(file)) return { stale: false, problems: [...problems, "README.md is missing"] };
|
|
300
|
+
const text = readTextFileSync(file).replace(/\r\n/g, "\n");
|
|
301
|
+
const bundles = bundlesTableOf(bundlesOf(root));
|
|
302
|
+
const made = withTable(text, bundles === "" ? tableOf(rows) : `${tableOf(rows)}\n\n${bundles}`);
|
|
303
|
+
if (made.kind === "err") return { stale: false, problems: [...problems, made.error] };
|
|
304
|
+
const stale = made.value !== text;
|
|
305
|
+
if (stale && write && problems.length === 0) writeTextFileSync(file, made.value);
|
|
306
|
+
return { stale, problems };
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
/** The command line: 0, or 1 where a problem was found or, with `--check`, README.md is not what the manifests make. */
|
|
310
|
+
export function main(argv: readonly string[]): number {
|
|
311
|
+
const at = argv.indexOf("--repo");
|
|
312
|
+
const repo = at >= 0 ? (argv[at + 1] ?? ".") : ".";
|
|
313
|
+
const check = argv.includes("--check");
|
|
314
|
+
const r = synchronize(repo, !check);
|
|
315
|
+
for (const p of r.problems) stdio.stderr.writeSync(`${p}\n`);
|
|
316
|
+
if (r.stale) stdio.stderr.writeSync(check ? "README.md is not what the manifests make; run: bun commons/libraries/src/readme.ts\n" : "wrote README.md\n");
|
|
317
|
+
return r.problems.length > 0 || (check && r.stale) ? 1 : 0;
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
if (import.meta.main) process.exitCode = main(process.argv.slice(2));
|
package/src/releasing.ts
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
*
|
|
17
17
|
* @limits
|
|
18
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/
|
|
19
|
+
* (`commons/docs`) is not released here.
|
|
20
20
|
*
|
|
21
21
|
* @example
|
|
22
22
|
* ```ts
|
|
@@ -47,6 +47,8 @@ import { compareVersions, greaterImpact, type Impact, nextSemVer, parseVersion }
|
|
|
47
47
|
import { scopeOf, workFolders } from "@intellectual-frontiers/mizan/versions/works";
|
|
48
48
|
import { inputsOf } from "./affected.ts";
|
|
49
49
|
import { exportsLine } from "./plan.ts";
|
|
50
|
+
import { decodeLibrarySource, LIBRARY_FILE, publishedPackage, type VersionConstant } from "./libraries.ts";
|
|
51
|
+
import { membersOf } from "./metapackages.ts";
|
|
50
52
|
import { everyLibrary } from "./affected.ts";
|
|
51
53
|
|
|
52
54
|
/** The record of the release, from the repository's root. */
|
|
@@ -56,6 +58,8 @@ export const RECORD_PATH = "commons/generated/release.auto.json";
|
|
|
56
58
|
export type Facts = {
|
|
57
59
|
readonly slug: Slug;
|
|
58
60
|
readonly folder: string;
|
|
61
|
+
/** The package the library publishes: `@intellectual-frontiers/<slug>`, or the one its manifest names in `publishes` (commons 0036-distribution FR-009). */
|
|
62
|
+
readonly package: string;
|
|
59
63
|
readonly version: string;
|
|
60
64
|
/** The libraries (by slug) whose package its own sources import. */
|
|
61
65
|
readonly imports: readonly Slug[];
|
|
@@ -90,6 +94,7 @@ export type Decision =
|
|
|
90
94
|
export type Step = {
|
|
91
95
|
readonly slug: Slug;
|
|
92
96
|
readonly folder: string;
|
|
97
|
+
readonly package: string;
|
|
93
98
|
readonly from: string;
|
|
94
99
|
readonly to: string;
|
|
95
100
|
readonly tag: string;
|
|
@@ -195,7 +200,7 @@ export function planRelease(facts: readonly Facts[], raise: ReadonlyMap<string,
|
|
|
195
200
|
const d = decided.get(slug);
|
|
196
201
|
if (f === undefined || d === undefined || d.kind === "unchanged") continue;
|
|
197
202
|
const to = d.kind === "as-is" ? f.version : d.to;
|
|
198
|
-
steps.push({ slug, folder: f.folder, from: f.version, to, tag: tagOf(slug, to), publish: f.publish, decision: d });
|
|
203
|
+
steps.push({ slug, folder: f.folder, package: f.package, from: f.version, to, tag: tagOf(slug, to), publish: f.publish, decision: d });
|
|
199
204
|
}
|
|
200
205
|
return ok({ steps, unchanged: facts.filter((f) => decided.get(f.slug)?.kind === "unchanged").map((f) => f.slug) });
|
|
201
206
|
}
|
|
@@ -208,12 +213,12 @@ function compare(a: string, b: string): number | undefined {
|
|
|
208
213
|
|
|
209
214
|
/** The record the workflow reads, as the bytes of its file: the steps that publish or tag, in order. */
|
|
210
215
|
export function recordText(plan: Plan): string {
|
|
211
|
-
const releases = plan.steps.map((s) => ({ slug: s.slug, version: s.to, folder: s.folder, tag: s.tag, publish: s.publish }));
|
|
216
|
+
const releases = plan.steps.map((s) => ({ slug: s.slug, package: s.package, version: s.to, folder: s.folder, tag: s.tag, publish: s.publish }));
|
|
212
217
|
return `${JSON.stringify({ generated: "bun commons/libraries/src/releasing.ts apply; do not edit (commons 0001-libraries FR-014)", releases }, null, 2)}\n`;
|
|
213
218
|
}
|
|
214
219
|
|
|
215
220
|
/** One entry of the record, as the workflow reads it. */
|
|
216
|
-
export type Entry = { readonly slug: string; readonly version: string; readonly folder: string; readonly tag: string; readonly publish: boolean };
|
|
221
|
+
export type Entry = { readonly slug: string; readonly package: string; readonly version: string; readonly folder: string; readonly tag: string; readonly publish: boolean };
|
|
217
222
|
|
|
218
223
|
/** The entries of a record's text, or why it is not one. */
|
|
219
224
|
export function readRecord(text: string): Result<readonly Entry[], string> {
|
|
@@ -230,9 +235,10 @@ export function readRecord(text: string): Result<readonly Entry[], string> {
|
|
|
230
235
|
if (typeof e !== "object" || e === null) return err(`${RECORD_PATH}: an entry is not an object`);
|
|
231
236
|
const o = Object.fromEntries(Object.entries(e));
|
|
232
237
|
const { slug, version, folder, tag, publish } = o;
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
238
|
+
const pkg = o["package"];
|
|
239
|
+
if (typeof slug !== "string" || typeof pkg !== "string" || typeof version !== "string" || typeof folder !== "string" || typeof tag !== "string" || typeof publish !== "boolean")
|
|
240
|
+
return err(`${RECORD_PATH}: an entry lacks its slug, package, version, folder, tag or publish`);
|
|
241
|
+
out.push({ slug, package: pkg, version, folder, tag, publish });
|
|
236
242
|
}
|
|
237
243
|
return ok(out);
|
|
238
244
|
}
|
|
@@ -269,9 +275,30 @@ export function writeVersion(repo: string, step: Step): Result<readonly string[]
|
|
|
269
275
|
writeTextFileSync(at, changed);
|
|
270
276
|
files.push(file);
|
|
271
277
|
}
|
|
278
|
+
const manifest = decodeLibrarySource(readTextFileSync(join(repo, step.folder, LIBRARY_FILE)));
|
|
279
|
+
if (manifest.kind === "err") return err(`${step.folder}/${LIBRARY_FILE}: ${manifest.error}`);
|
|
280
|
+
for (const c of manifest.value.versionConstants ?? []) {
|
|
281
|
+
const done = writeConstant(repo, step, c);
|
|
282
|
+
if (done.kind === "err") return done;
|
|
283
|
+
files.push(done.value);
|
|
284
|
+
}
|
|
272
285
|
return ok(files);
|
|
273
286
|
}
|
|
274
287
|
|
|
288
|
+
/** Escapes the characters of a name that a regular expression reads as syntax. */
|
|
289
|
+
const quoted = (name: string): string => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
290
|
+
|
|
291
|
+
/** Writes the new version into a constant of the library's sources that holds it (`export const NAME = "1.2.3"`); the file's path from the root, or the problem where the file or the constant is not there. */
|
|
292
|
+
export function writeConstant(repo: string, step: Step, c: VersionConstant): Result<string, string> {
|
|
293
|
+
const path = `${step.folder}/${c.file}`;
|
|
294
|
+
const at = join(repo, path);
|
|
295
|
+
if (!existsSync(at)) return err(`${path} is missing: the manifest names it as holding the version in ${c.name}`);
|
|
296
|
+
const changed = set(readTextFileSync(at), new RegExp(`(\\b${quoted(c.name)}\\b[^=\\n]*=\\s*)"[^"]*"`), `$1"${step.to}"`);
|
|
297
|
+
if (changed === undefined) return err(`${path} does not say ${c.name} = "<version>"`);
|
|
298
|
+
writeTextFileSync(at, changed);
|
|
299
|
+
return ok(path);
|
|
300
|
+
}
|
|
301
|
+
|
|
275
302
|
/** 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`. */
|
|
276
303
|
export type Tarball = { readonly hashes: ReadonlyMap<string, string>; readonly packageJson: string };
|
|
277
304
|
|
|
@@ -309,13 +336,13 @@ export function driftOf(published: Tarball, local: { readonly hash: (path: strin
|
|
|
309
336
|
}
|
|
310
337
|
|
|
311
338
|
/** Compares a library's version with what npm holds of it. */
|
|
312
|
-
export type Registry = (
|
|
339
|
+
export type Registry = (pkg: string, version: string, folder: string) => Promise<Drift>;
|
|
313
340
|
|
|
314
341
|
/** 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. */
|
|
315
342
|
export function realRegistry(repo: string): Registry {
|
|
316
|
-
return async (
|
|
343
|
+
return async (name, version, folder) => {
|
|
317
344
|
try {
|
|
318
|
-
const meta = await fetch(`https://registry.npmjs.org
|
|
345
|
+
const meta = await fetch(`https://registry.npmjs.org/${name.replace("/", "%2F")}/${version}`, { signal: AbortSignal.timeout(30_000) });
|
|
319
346
|
if (meta.status === 404) return "absent";
|
|
320
347
|
if (!meta.ok) return "unknown";
|
|
321
348
|
const json: unknown = await meta.json();
|
|
@@ -348,7 +375,7 @@ export async function factsOf(repo: string, registry: Registry = realRegistry(re
|
|
|
348
375
|
const head = await resolveCommit(repo, "HEAD");
|
|
349
376
|
if (head.kind === "err") return err(formatGitError(head.error));
|
|
350
377
|
const folders = workFolders(tree.value.paths);
|
|
351
|
-
const libs = everyLibrary(repo);
|
|
378
|
+
const libs = everyLibrary(repo).filter((l) => l.held === undefined);
|
|
352
379
|
const slugs = new Map<string, Slug>();
|
|
353
380
|
for (const l of libs) {
|
|
354
381
|
const s = slugOf(l.name);
|
|
@@ -386,7 +413,7 @@ export async function factsOf(repo: string, registry: Registry = realRegistry(re
|
|
|
386
413
|
let drift: Drift = "unknown";
|
|
387
414
|
let sinceVersion = { changed: false, impact: "patch" as Impact };
|
|
388
415
|
if (ahead) {
|
|
389
|
-
if (l.distribution.includes("npm")) drift = await registry(
|
|
416
|
+
if (l.distribution.includes("npm")) drift = await registry(publishedPackage(l), l.version, l.folder);
|
|
390
417
|
const raisedAt = await run(["git", "-C", repo, "log", "-1", "--format=%H", '-G"version"', "--", `${l.folder}/package.json`]);
|
|
391
418
|
const commit = raisedAt.code === 0 ? raisedAt.stdout.trim() : "";
|
|
392
419
|
if (commit !== "") {
|
|
@@ -400,13 +427,16 @@ export async function factsOf(repo: string, registry: Registry = realRegistry(re
|
|
|
400
427
|
};
|
|
401
428
|
}
|
|
402
429
|
}
|
|
403
|
-
|
|
430
|
+
// a metapackage has no code to import: it depends on each member of its set, which is what raises it where a member is raised (0036-distribution FR-008)
|
|
431
|
+
const members = l.bundle === undefined ? undefined : membersOf(l.bundle, libs);
|
|
432
|
+
const imports = (members?.kind === "ok" ? members.value.map((m) => m.library) : inputsOf(repo, l.name).imports).flatMap((n) => {
|
|
404
433
|
const s = slugs.get(n);
|
|
405
434
|
return s === undefined ? [] : [s];
|
|
406
435
|
});
|
|
407
436
|
out.push({
|
|
408
437
|
slug,
|
|
409
438
|
folder: l.folder,
|
|
439
|
+
package: publishedPackage(l),
|
|
410
440
|
version: l.version,
|
|
411
441
|
imports,
|
|
412
442
|
last: last === undefined ? undefined : { version: last.version, tag: last.tag },
|
|
@@ -423,6 +453,7 @@ export async function factsOf(repo: string, registry: Registry = realRegistry(re
|
|
|
423
453
|
/** 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`. */
|
|
424
454
|
export const GENERATORS: readonly (readonly string[])[] = [
|
|
425
455
|
["commons/libraries/src/libraries.ts"],
|
|
456
|
+
["commons/libraries/src/pack-metapackage.ts"],
|
|
426
457
|
["commons/tools/generate-packaging.ts"],
|
|
427
458
|
["commons/libraries/src/generate-ontology.ts"],
|
|
428
459
|
["commons/libraries/src/generate-workflows.ts"],
|
|
@@ -527,7 +558,7 @@ export async function publishAll(entries: readonly Entry[], tools: Tools): Promi
|
|
|
527
558
|
let npm: Outcome["npm"] = "not-published";
|
|
528
559
|
let registry: Outcome["registry"] = "not-published";
|
|
529
560
|
if (e.publish) {
|
|
530
|
-
if (await tools.onNpm(
|
|
561
|
+
if (await tools.onNpm(e.package, e.version)) npm = "present";
|
|
531
562
|
else {
|
|
532
563
|
const sent = await tools.npm(e);
|
|
533
564
|
npm = sent.kind === "ok" ? "published" : "failed";
|
|
@@ -589,11 +620,11 @@ export function realTools(dir: string): Tools {
|
|
|
589
620
|
});
|
|
590
621
|
return r.code === 0
|
|
591
622
|
? ok(undefined)
|
|
592
|
-
: 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
|
|
623
|
+
: 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 ${e.package} or publish it by hand): ${tail(`${r.stderr}${r.stdout}`)}`);
|
|
593
624
|
},
|
|
594
625
|
github: async (e) => {
|
|
595
626
|
const auth = [`--registry=https://npm.pkg.github.com`, `--//npm.pkg.github.com/:_authToken=${github}`];
|
|
596
|
-
if (await view(
|
|
627
|
+
if (await view(e.package, e.version, auth)) return ok(undefined);
|
|
597
628
|
const f = tarball(e.slug);
|
|
598
629
|
if (f === undefined) return err(`${e.slug}: no tarball was built for it`);
|
|
599
630
|
const r = await run(["npm", "publish", join(dir, `package-${e.slug}`, f), ...auth]);
|