@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.
Files changed (64) hide show
  1. package/LICENSE +75 -21
  2. package/dist/affected.d.ts +1 -1
  3. package/dist/dev.d.ts +2 -0
  4. package/dist/dev.js +14 -2
  5. package/dist/family.js +1 -0
  6. package/dist/generate-ontology.js +4 -0
  7. package/dist/imports/nist-sp-800-53.auto.prov.ttl +22 -0
  8. package/dist/imports/schema-org.auto.prov.ttl +22 -0
  9. package/dist/install-bun.js +19 -14
  10. package/dist/libraries.d.ts +39 -2
  11. package/dist/libraries.js +80 -9
  12. package/dist/license/PolyForm-Noncommercial-1.0.0.md +73 -0
  13. package/dist/license/standard.d.ts +46 -0
  14. package/dist/license/standard.js +43 -0
  15. package/dist/license/third-party.d.ts +25 -0
  16. package/dist/license/third-party.js +71 -0
  17. package/dist/license.d.ts +61 -0
  18. package/dist/license.js +204 -0
  19. package/dist/link.d.ts +1 -1
  20. package/dist/link.js +4 -4
  21. package/dist/metapackages.d.ts +62 -0
  22. package/dist/metapackages.js +190 -0
  23. package/dist/mod.d.ts +1 -1
  24. package/dist/mod.js +1 -1
  25. package/dist/pack-library.d.ts +9 -0
  26. package/dist/pack-library.js +46 -58
  27. package/dist/pack-metapackage.d.ts +22 -0
  28. package/dist/pack-metapackage.js +147 -0
  29. package/dist/pins.d.ts +34 -7
  30. package/dist/pins.js +36 -9
  31. package/dist/readme.d.ts +71 -0
  32. package/dist/readme.js +310 -0
  33. package/dist/releasing.d.ts +8 -1
  34. package/dist/releasing.js +44 -14
  35. package/dist/workflows/definitions.d.ts +2 -2
  36. package/dist/workflows/definitions.js +32 -114
  37. package/dist/workflows/model.d.ts +6 -0
  38. package/dist/workflows/render.js +2 -0
  39. package/dist/workflows/schema/github-workflow.schema.json +2290 -0
  40. package/package.json +39 -14
  41. package/src/affected.ts +1 -1
  42. package/src/dev.ts +13 -2
  43. package/src/family.ts +1 -0
  44. package/src/generate-ontology.ts +4 -0
  45. package/src/imports/nist-sp-800-53.auto.prov.ttl +22 -0
  46. package/src/imports/schema-org.auto.prov.ttl +22 -0
  47. package/src/install-bun.ts +16 -13
  48. package/src/libraries.ts +100 -8
  49. package/src/license/PolyForm-Noncommercial-1.0.0.md +73 -0
  50. package/src/license/standard.ts +67 -0
  51. package/src/license/third-party.ts +87 -0
  52. package/src/license.ts +222 -0
  53. package/src/link.ts +4 -4
  54. package/src/metapackages.ts +206 -0
  55. package/src/mod.ts +1 -1
  56. package/src/pack-library.ts +52 -55
  57. package/src/pack-metapackage.ts +137 -0
  58. package/src/pins.ts +55 -10
  59. package/src/readme.ts +320 -0
  60. package/src/releasing.ts +47 -16
  61. package/src/workflows/definitions.ts +36 -133
  62. package/src/workflows/model.ts +6 -0
  63. package/src/workflows/render.ts +1 -0
  64. 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/ts`, `commons/docs`) is a Git dependency and is not released here.
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
- if (typeof slug !== "string" || typeof version !== "string" || typeof folder !== "string" || typeof tag !== "string" || typeof publish !== "boolean")
234
- return err(`${RECORD_PATH}: an entry lacks its slug, version, folder, tag or publish`);
235
- out.push({ slug, version, folder, tag, publish });
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 = (slug: string, version: string, folder: string) => Promise<Drift>;
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 (slug, version, folder) => {
343
+ return async (name, version, folder) => {
317
344
  try {
318
- const meta = await fetch(`https://registry.npmjs.org/@intellectual-frontiers%2F${slug}/${version}`, { signal: AbortSignal.timeout(30_000) });
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(slug, l.version, l.folder);
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
- const imports = inputsOf(repo, l.name).imports.flatMap((n) => {
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(`@intellectual-frontiers/${e.slug}`, e.version)) npm = "present";
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 @intellectual-frontiers/${e.slug} or publish it by hand): ${tail(`${r.stderr}${r.stdout}`)}`);
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(`@intellectual-frontiers/${e.slug}`, e.version, auth)) return ok(undefined);
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]);