@intellectual-frontiers/libraries 0.4.1 → 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 (49) hide show
  1. package/dist/affected.d.ts +1 -1
  2. package/dist/dev.js +1 -1
  3. package/dist/imports/nist-sp-800-53.auto.prov.ttl +22 -0
  4. package/dist/imports/schema-org.auto.prov.ttl +22 -0
  5. package/dist/install-bun.js +1 -1
  6. package/dist/libraries.d.ts +34 -2
  7. package/dist/libraries.js +70 -9
  8. package/dist/license/PolyForm-Noncommercial-1.0.0.md +73 -0
  9. package/dist/link.d.ts +1 -1
  10. package/dist/link.js +4 -4
  11. package/dist/metapackages.d.ts +62 -0
  12. package/dist/metapackages.js +190 -0
  13. package/dist/mod.d.ts +1 -1
  14. package/dist/mod.js +1 -1
  15. package/dist/pack-library.d.ts +7 -0
  16. package/dist/pack-library.js +31 -56
  17. package/dist/pack-metapackage.d.ts +22 -0
  18. package/dist/pack-metapackage.js +147 -0
  19. package/dist/pins.d.ts +1 -1
  20. package/dist/pins.js +1 -1
  21. package/dist/readme.d.ts +13 -1
  22. package/dist/readme.js +42 -4
  23. package/dist/releasing.d.ts +8 -1
  24. package/dist/releasing.js +44 -14
  25. package/dist/workflows/definitions.d.ts +2 -2
  26. package/dist/workflows/definitions.js +31 -113
  27. package/dist/workflows/model.d.ts +2 -0
  28. package/dist/workflows/render.js +2 -0
  29. package/dist/workflows/schema/github-workflow.schema.json +2290 -0
  30. package/package.json +28 -13
  31. package/src/affected.ts +1 -1
  32. package/src/dev.ts +1 -1
  33. package/src/imports/nist-sp-800-53.auto.prov.ttl +22 -0
  34. package/src/imports/schema-org.auto.prov.ttl +22 -0
  35. package/src/install-bun.ts +1 -1
  36. package/src/libraries.ts +88 -8
  37. package/src/license/PolyForm-Noncommercial-1.0.0.md +73 -0
  38. package/src/link.ts +4 -4
  39. package/src/metapackages.ts +206 -0
  40. package/src/mod.ts +1 -1
  41. package/src/pack-library.ts +37 -53
  42. package/src/pack-metapackage.ts +137 -0
  43. package/src/pins.ts +1 -1
  44. package/src/readme.ts +46 -4
  45. package/src/releasing.ts +47 -16
  46. package/src/workflows/definitions.ts +34 -131
  47. package/src/workflows/model.ts +2 -0
  48. package/src/workflows/render.ts +1 -0
  49. package/src/workflows/schema/github-workflow.schema.json +2290 -0
@@ -1,5 +1,5 @@
1
1
  /**
2
- * The package of a library of commons (commons 0032-lifting-libraries FR-005, FR-013): the library's sources compiled by the TypeScript 7 compiler into ECMAScript modules and their declarations, the
2
+ * The package of a library of commons (commons 0032-libraries-by-concern FR-005, FR-013): the library's sources compiled by the TypeScript 7 compiler into ECMAScript modules and their declarations, the
3
3
  * `package.json` that is published (each `exports` entry naming its `types`, the source for Bun and the compiled file for everything else), and the tarball. The same inspection that the packer makes before it
4
4
  * packs is `inspectPackage`, which a test runs again on the tarball it unpacks.
5
5
  *
@@ -37,7 +37,6 @@ export type Findings = readonly string[];
37
37
 
38
38
  type Json = Readonly<Record<string, unknown>>;
39
39
 
40
- const obj = (v: unknown): Json => (isObject(v) ? v : {});
41
40
  const isObject = (v: unknown): v is Json => typeof v === "object" && v !== null && !Array.isArray(v);
42
41
  const text = (v: unknown): string => (typeof v === "string" ? v : "");
43
42
  /** A text file copied: every file of a package is text. */
@@ -152,7 +151,7 @@ export function inspectPackage(stage: string): Findings {
152
151
  for (const s of specifiersOf(readTextFileSync(join(stage, d)))) {
153
152
  const pkg = packageOf(s);
154
153
  if (pkg === undefined) continue;
155
- if (pkg === `${SCOPE}/commons`) found.push(`${d} imports ${s}: the package ${pkg} is not on npm`);
154
+ if (pkg === `${SCOPE}/commons`) found.push(`${d} imports ${s}: the package ${pkg} is a metapackage with no code: import the library that holds what is used`);
156
155
  else if (pkg !== name && !declared.has(pkg)) found.push(`${d} imports ${pkg}, which is not a dependency of ${name}`);
157
156
  }
158
157
  }
@@ -169,7 +168,7 @@ export function inspectPackage(stage: string): Findings {
169
168
  for (const s of specifiersOf(source)) {
170
169
  const pkg = packageOf(s);
171
170
  if (pkg === undefined) continue;
172
- if (pkg === `${SCOPE}/commons`) found.push(`${f} imports ${s}: the package ${pkg} is not on npm`);
171
+ if (pkg === `${SCOPE}/commons`) found.push(`${f} imports ${s}: the package ${pkg} is a metapackage with no code: import the library that holds what is used`);
173
172
  else if (pkg !== name && !declared.has(pkg)) found.push(`${f} imports ${pkg}, which is not a dependency of ${name}`);
174
173
  }
175
174
  }
@@ -189,24 +188,24 @@ export function rewriteDeclarationSpecifiers(source: string): string {
189
188
  export const tarballName = (name: string, version: string): string => `${name.replace(/^@/, "").replace("/", "-")}-${version}.tgz`;
190
189
 
191
190
  /** The version of a library of commons, from its `package.json`, and whether it is published to npm (its manifest names that). */
192
- function libraryOf(commons: string, name: string): { readonly version: string; readonly npm: boolean } | undefined {
191
+ function libraryOf(commons: string, name: string): { readonly version: string; readonly npm: boolean; readonly held: boolean } | undefined {
193
192
  const pkg = join(commons, name, "package.json");
194
193
  if (!existsSync(pkg)) return undefined;
195
194
  const lib = join(commons, name, "library.ts");
196
- const npm = existsSync(lib) && /distribution:\s*\[[^\]]*"npm"/.test(readTextFileSync(lib));
197
- return { version: text((JSON.parse(readTextFileSync(pkg)) as Json)["version"]), npm };
195
+ const source = existsSync(lib) ? readTextFileSync(lib) : "";
196
+ const npm = /distribution:\s*\[[^\]]*"npm"/.test(source);
197
+ const held = /\bheld:\s*"/.test(source);
198
+ return { version: text((JSON.parse(readTextFileSync(pkg)) as Json)["version"]), npm, held };
198
199
  }
199
200
 
200
201
  /**
201
- * The declarations of a bundle: from the entries' declarations in the compiler's output, every declaration reached by a relative import is published, and so is every declaration that a package of commons that is not
202
- * on npm (`@intellectual-frontiers/commons/ts/...`) gives to them, vendored under `dist/vendor/` with the specifiers that name it rewritten to relative ones. It is the way for a package to publish its API while what
203
- * its types are made of is still lifted out of `commons/ts` a library at a time (commons 0032-lifting-libraries); a library that has been lifted is a dependency and is not vendored.
202
+ * The declarations of a bundle: from the entries' declarations in the compiler's output, every declaration reached by a relative import is published, those of a file outside the library's own `src/` under `dist/vendor/`
203
+ * with the specifiers that name it rewritten to relative ones. A library of commons that a bundle uses is a dependency and is not vendored.
204
204
  */
205
205
  function vendorDeclarations(
206
206
  outRoot: string,
207
207
  lib: string,
208
208
  entries: readonly string[],
209
- commonsPkg: { readonly folder: string; readonly exports: ReadonlyMap<string, string> },
210
209
  stageDist: string,
211
210
  ): Findings {
212
211
  const found: string[] = [];
@@ -228,26 +227,10 @@ function vendorDeclarations(
228
227
  placed.set(file, dest);
229
228
  for (const s of specifiersOf(readTextFileSync(file))) {
230
229
  if (s.startsWith(".")) todo.push(join(dirname(file), s.replace(/\.(?:js|ts|mjs)$/, "") + ".d.ts"));
231
- else if (s.startsWith(`${SCOPE}/commons/`)) {
232
- const target = commonsPkg.exports.get(`./${s.slice(`${SCOPE}/commons/`.length)}`);
233
- if (target === undefined) found.push(`${dest} imports ${s}, which the exports of commons do not name`);
234
- else todo.push(join(outRoot, commonsPkg.folder, target.replace(/^\.\//, "").replace(/\.ts$/, "") + ".d.ts"));
235
- }
236
230
  }
237
231
  }
238
232
  for (const [file, dest] of placed) {
239
233
  let source = rewriteDeclarationSpecifiers(readTextFileSync(file));
240
- source = source.replace(
241
- new RegExp(`((?:from\\s+|import\\(\\s*|import\\s+)["'])${SCOPE}/commons/([^"']+)(["'])`, "g"),
242
- (whole, pre: string, sub: string, post: string) => {
243
- const target = commonsPkg.exports.get(`./${sub}`);
244
- if (target === undefined) return whole;
245
- const there = place(join(outRoot, commonsPkg.folder, target.replace(/^\.\//, "").replace(/\.ts$/, "") + ".d.ts"));
246
- let rel = toPosix(relative(dirname(dest), there)).replace(/\.d\.ts$/, ".js");
247
- if (!rel.startsWith(".")) rel = `./${rel}`;
248
- return `${pre}${rel}${post}`;
249
- },
250
- );
251
234
  // a relative import that leaves the library's own tree (a type the compiler named by its path in commons) goes to where that declaration was placed
252
235
  source = source.replace(
253
236
  /((?:from\s+|import\(\s*|import\s+)["'])(\.[^"']+)(["'])/g,
@@ -267,23 +250,11 @@ function vendorDeclarations(
267
250
  return found;
268
251
  }
269
252
 
270
- /** The compiler's `paths` for the packages of commons that are not on npm: each entry of `commons/ts/package.json` (`./ts/kernel`) names the source that the specifier `@intellectual-frontiers/commons/ts/kernel` is. */
271
- function commonsPaths(commons: string, dist: string): Record<string, readonly string[]> {
272
- const file = join(commons, "ts", "package.json");
273
- const out: Record<string, readonly string[]> = {};
274
- if (!existsSync(file)) return out;
275
- for (const [k, v] of Object.entries(obj(obj(JSON.parse(readTextFileSync(file)) as unknown)["exports"]))) {
276
- if (typeof v === "string" && v.endsWith(".ts"))
277
- out[`${SCOPE}/commons/${k.replace(/^\.\//, "")}`] = [toPosix(relative(dist, join(commons, "ts", v)))];
278
- }
279
- return out;
280
- }
281
-
282
253
  /** What packing a library made: the staging folder, the tarball, the findings and the manifest. */
283
254
  export type Packed = { readonly stage: string; readonly tarball: string | undefined; readonly findings: Findings; readonly manifest: Json };
284
255
 
285
256
  /** What a package adds to the common form. */
286
- /** Whether a declaration of the package names a `node:` module: a package whose types name Node's needs `@types/node` where it is type-checked (a peer dependency, FR-013 of 0032-lifting-libraries). */
257
+ /** Whether a declaration of the package names a `node:` module: a package whose types name Node's needs `@types/node` where it is type-checked (a peer dependency, FR-013 of 0032-libraries-by-concern). */
287
258
  function namesNodeTypes(folder: string): boolean {
288
259
  if (!existsSync(folder)) return false;
289
260
  for (const e of readDirSync(folder)) {
@@ -299,6 +270,13 @@ function namesNodeTypes(folder: string): boolean {
299
270
  export type PackOptions = {
300
271
  /** Types the compiler is given (`["node"]` for a library that names Node's). */
301
272
  readonly types?: readonly string[];
273
+ /**
274
+ * Commands of a package that is not a bundle: each command's name and the module, in `src/`, whose `main(argv)` gives the exit status; the package gets a one-line launcher for each (`<command>.mjs`, which Node and Bun run), made
275
+ * from the compiled module. The files under `src/` that are not TypeScript (a stylesheet a module reads beside itself) are published beside the sources and beside the compiled modules.
276
+ */
277
+ readonly launchers?: Readonly<Record<string, string>>;
278
+ /** Packages the published package may use where they are installed beside it and does not need (loaded by name at run time): written as optional peer dependencies, name and range. */
279
+ readonly optionalPeers?: Readonly<Record<string, string>>;
302
280
  /** A bundled package: the code of each entry and of each command is one file (`bun build`), and only the declarations the entries reach are published. */
303
281
  readonly bundle?: {
304
282
  /** The commands: their name, and the source that is the command's entry from the library's folder. */
@@ -331,7 +309,7 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
331
309
  if (existsSync(dist)) removeSync(dist, { recursive: true });
332
310
  mkdirSync(stage, { recursive: true });
333
311
  // the compiler's configuration for this build: the base of commons, emitting modules and declarations of src/ and nothing else
334
- const base = relative(dist, join(commons, "ts", "tsconfig.json"));
312
+ const base = relative(dist, join(commons, "tsconfig.base.json"));
335
313
  writeTextFileSync(
336
314
  join(dist, "tsconfig.build.json"),
337
315
  JSON.stringify(
@@ -347,8 +325,6 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
347
325
  skipLibCheck: true,
348
326
  // another library of commons is read where the package manager linked it (under node_modules), so that a declaration names it by its package and its entry and never by the path of its sources
349
327
  preserveSymlinks: true,
350
- // a bundle's declarations are made from the sources of the packages of commons that are not on npm, which the compiler emits only when it reads them as sources and not through node_modules
351
- ...(bundle === undefined ? {} : { paths: commonsPaths(commons, dist) }),
352
328
  },
353
329
  include: [toPosix(relative(dist, join(root, "src"))) + "/**/*.ts"],
354
330
  },
@@ -372,12 +348,6 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
372
348
  else if (f.endsWith(".js")) copyFileSync(join(out, f), target);
373
349
  }
374
350
  } else {
375
- const commonsPkgFile = join(commons, "ts", "package.json");
376
- const commonsExports = new Map<string, string>();
377
- if (existsSync(commonsPkgFile)) {
378
- const declared = obj(obj(JSON.parse(readTextFileSync(commonsPkgFile)) as unknown)["exports"]);
379
- for (const [k, v] of Object.entries(declared)) if (typeof v === "string") commonsExports.set(k, v);
380
- }
381
351
  const entryFiles = Object.values(ownExports).map((e) =>
382
352
  join(out, (targetsOf(e)["default"] ?? text(e)).replace(/^\.\/src\//, "").replace(/\.ts$/, "") + ".d.ts"),
383
353
  );
@@ -386,7 +356,6 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
386
356
  join(dist, "out"),
387
357
  basename(resolve(root)),
388
358
  entryFiles,
389
- { folder: "ts", exports: commonsExports },
390
359
  join(stage, "dist"),
391
360
  ),
392
361
  );
@@ -394,10 +363,15 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
394
363
  // the sources, for the `bun` condition (a bundle has no source to offer: what it imports is not on npm)
395
364
  if (bundle === undefined) {
396
365
  for (const f of filesUnder(join(root, "src"))) {
397
- if (!f.endsWith(".ts")) continue;
398
366
  const target = join(stage, "src", f);
399
367
  mkdirSync(dirname(target), { recursive: true });
400
368
  copyFileSync(join(root, "src", f), target);
369
+ if (!f.endsWith(".ts")) {
370
+ // a file that is not TypeScript is read beside the module that reads it, from the sources and from the compiled modules alike
371
+ const compiled = join(stage, "dist", f);
372
+ mkdirSync(dirname(compiled), { recursive: true });
373
+ copyFileSync(join(root, "src", f), compiled);
374
+ }
401
375
  }
402
376
  }
403
377
  // the entries: each names its declarations, its source (Bun) and its compiled file
@@ -421,6 +395,13 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
421
395
  }
422
396
  // the commands of a bundle: one file each, with the line that runs it under Node
423
397
  const binOut: Record<string, string> = {};
398
+ for (const [cmd, source] of Object.entries(options.launchers ?? {})) {
399
+ const rel = toPosix(source).replace(/^\.?\/?(src\/)?/, "").replace(/\.ts$/, "");
400
+ const file = join(stage, `${cmd}.mjs`);
401
+ await writeTextFile(file, `#!/usr/bin/env node\nimport { main } from "./dist/${rel}.js";\n\nprocess.exit(await main(process.argv.slice(2)));\n`);
402
+ await chmod(file, 0o755);
403
+ binOut[cmd] = `./${cmd}.mjs`;
404
+ }
424
405
  for (const [cmd, source] of Object.entries(bundle?.bin ?? {})) {
425
406
  const file = join(stage, `${cmd}.mjs`);
426
407
  const bundled = await run([bun, "build", join(root, source), "--target=node", "--format=esm", "--outfile", file], { cwd: root });
@@ -458,7 +439,7 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
458
439
  if (pkg.startsWith(`${SCOPE}/`) && pkg !== `${SCOPE}/commons`) {
459
440
  const lib = libraryOf(commons, pkg.slice(SCOPE.length + 1));
460
441
  if (lib === undefined) findings.push(`${file} imports ${pkg}, which is no library of commons`);
461
- else if (!lib.npm) findings.push(`${file} imports ${pkg}, which is not published to npm`);
442
+ else if (!lib.npm && !(libraryOf(commons, short)?.held === true && lib.held)) findings.push(`${file} imports ${pkg}, which is not published to npm`);
462
443
  else dependencies[pkg] = lib.version;
463
444
  } else if (pkg !== `${SCOPE}/commons`) {
464
445
  const v = declaredDeps[pkg];
@@ -483,7 +464,10 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
483
464
  ...(Object.keys(dependencies).length === 0
484
465
  ? {}
485
466
  : { dependencies: Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => (a < b ? -1 : 1))) }),
486
- ...(namesNodeTypes(join(stage, "dist")) ? { peerDependencies: { "@types/node": ">=26" } } : {}),
467
+ ...(namesNodeTypes(join(stage, "dist")) || options.optionalPeers !== undefined
468
+ ? { peerDependencies: { ...(namesNodeTypes(join(stage, "dist")) ? { "@types/node": ">=26" } : {}), ...(options.optionalPeers ?? {}) } }
469
+ : {}),
470
+ ...(options.optionalPeers === undefined ? {} : { peerDependenciesMeta: Object.fromEntries(Object.keys(options.optionalPeers).map((n) => [n, { optional: true }])) }),
487
471
  files: [
488
472
  ...(Object.keys(exportsOut).length === 0 ? [] : ["dist"]),
489
473
  ...(bundle === undefined ? ["src"] : []),
@@ -0,0 +1,137 @@
1
+ /**
2
+ * The generator and the packer of the metapackages (commons 0036-distribution FR-007, FR-008): the file of each set that records its exact dependencies, and the tarball of its package.
3
+ *
4
+ * bun commons/libraries/src/pack-metapackage.ts write the file `dependencies.auto.json` of every metapackage again from the manifests
5
+ * bun commons/libraries/src/pack-metapackage.ts --check write nothing and exit 1 where a file is not what the manifests make
6
+ * bun tools/pack.ts [--check] (in the folder of a metapackage) stage, inspect and pack its package
7
+ * other flags: --repo DIR (the repository, the working folder by default)
8
+ *
9
+ * @remarks
10
+ * A metapackage is a folder `commons/<set>/` whose manifest names `bundle`; the folder holds the manifest, a private `package.json`, the `LICENSE` and `tools/pack.ts`, and nothing that is code. Its members come from the manifests
11
+ * ({@link membersOf}) and are written to `dependencies.auto.json` in its folder, so that a change of the set is a change of the folder, which the release sees. The packer writes the staged package (`package.json` with the
12
+ * exact dependencies, an empty `index.js` and its declaration, the README, the `LICENSE`), inspects it with the same inspection as every library's and packs it with `bun pm pack`.
13
+ *
14
+ * @limits
15
+ * It writes the files named above and runs `bun pm pack`; it asks no registry.
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * import { synchronize } from "./pack-metapackage.ts";
20
+ * synchronize(".", false).problems; // []
21
+ * ```
22
+ *
23
+ * Spec: 0001-libraries FR-023
24
+ *
25
+ * @module
26
+ */
27
+ import process from "node:process";
28
+ import { err, ok, type Result } from "@intellectual-frontiers/core";
29
+ import { stdio } from "@intellectual-frontiers/system";
30
+ import { existsSync, mkdirSync, readTextFileSync, removeSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
31
+ import { join, resolve } from "@intellectual-frontiers/system/path";
32
+ import { env, run, which } from "@intellectual-frontiers/system/proc";
33
+ import { decodeLibrarySource, type Library, LIBRARY_FILE, readLibraries } from "./libraries.ts";
34
+ import { licenseOf } from "./license.ts";
35
+ import { ENTRY_DTS, ENTRY_JS, membersOf, publishedManifest, readmeOf, readSetFile, SET_FILE, setFileText } from "./metapackages.ts";
36
+ import { inspectPackage, tarballName } from "./pack-library.ts";
37
+
38
+ /** The metapackages of a repository: the libraries whose manifest names a set. */
39
+ export function metapackagesOf(repo: string): readonly (Library & { readonly bundle: NonNullable<Library["bundle"]> })[] {
40
+ return readLibraries(repo).flatMap((f) => {
41
+ if (!("library" in f)) return [];
42
+ const l = f.library;
43
+ return l.bundle === undefined ? [] : [{ ...l, bundle: l.bundle }];
44
+ });
45
+ }
46
+
47
+ /** The files that are not what the manifests make (from the repository's root), and what is wrong with reading them; with `write`, the files are written. */
48
+ export function synchronize(repo: string, write: boolean): { readonly stale: readonly string[]; readonly problems: readonly string[] } {
49
+ const root = repo.replace(/[\\/]$/, "");
50
+ const libraries = readLibraries(root).flatMap((f) => ("library" in f ? [f.library] : []));
51
+ const stale: string[] = [];
52
+ const problems: string[] = [];
53
+ for (const m of metapackagesOf(root)) {
54
+ const members = membersOf(m.bundle, libraries);
55
+ if (members.kind === "err") {
56
+ problems.push(members.error);
57
+ continue;
58
+ }
59
+ const path = `commons/${m.name}/${SET_FILE}`;
60
+ const file = join(root, path);
61
+ const want = setFileText(m.bundle, members.value);
62
+ if (existsSync(file) && readTextFileSync(file) === want) continue;
63
+ stale.push(path);
64
+ if (write) writeTextFileSync(file, want);
65
+ }
66
+ return { stale, problems };
67
+ }
68
+
69
+ /** What packing a metapackage gave: the staged folder, the tarball where nothing was wrong, and what was wrong. */
70
+ export type PackedSet = { readonly stage: string; readonly tarball: string | undefined; readonly findings: readonly string[] };
71
+
72
+ /** The manifest of the metapackage at `root`, or why it is none. */
73
+ function manifestAt(root: string): Result<Library, string> {
74
+ const file = join(root, LIBRARY_FILE);
75
+ if (!existsSync(file)) return err(`${file} is missing`);
76
+ const r = decodeLibrarySource(readTextFileSync(file));
77
+ if (r.kind === "err") return err(r.error);
78
+ return r.value.bundle === undefined ? err(`${file} names no bundle: it is not a metapackage`) : ok(r.value);
79
+ }
80
+
81
+ /** Stages, inspects and packs the metapackage in the folder `root` (`commons/<set>/`). */
82
+ export async function packMetapackage(root: string): Promise<PackedSet> {
83
+ const own = manifestAt(root);
84
+ const dist = join(root, "dist");
85
+ const stage = join(dist, "package");
86
+ if (own.kind === "err") return { stage, tarball: undefined, findings: [own.error] };
87
+ const l = own.value;
88
+ const bundle = l.bundle;
89
+ if (bundle === undefined) return { stage, tarball: undefined, findings: [`${l.name} names no bundle`] };
90
+ const setFile = join(root, SET_FILE);
91
+ if (!existsSync(setFile)) return { stage, tarball: undefined, findings: [`${SET_FILE} is missing: run bun commons/libraries/src/pack-metapackage.ts`] };
92
+ const deps = readSetFile(readTextFileSync(setFile));
93
+ if (deps.kind === "err") return { stage, tarball: undefined, findings: [deps.error] };
94
+ if (existsSync(dist)) removeSync(dist, { recursive: true });
95
+ mkdirSync(stage, { recursive: true });
96
+ const members = Object.entries(deps.value).map(([pkg, version]) => ({ library: pkg.slice(pkg.indexOf("/") + 1), package: pkg, version }));
97
+ const manifest = publishedManifest(bundle, l.version, deps.value, licenseOf(l));
98
+ writeTextFileSync(join(stage, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
99
+ writeTextFileSync(join(stage, "index.js"), ENTRY_JS);
100
+ writeTextFileSync(join(stage, "index.d.ts"), ENTRY_DTS);
101
+ writeTextFileSync(join(stage, "README.md"), readmeOf(bundle, members));
102
+ const findings: string[] = [];
103
+ if (existsSync(join(root, "LICENSE"))) writeTextFileSync(join(stage, "LICENSE"), readTextFileSync(join(root, "LICENSE")));
104
+ else findings.push(`commons/${l.name} has no LICENSE; run: bun commons/libraries/src/license.ts`);
105
+ if (Object.keys(deps.value).length === 0) findings.push(`${l.name}: the set has no member`);
106
+ findings.push(...inspectPackage(stage));
107
+ if (findings.length > 0) return { stage, tarball: undefined, findings };
108
+ const packed = await run([which("bun") ?? "bun", "pm", "pack", "--destination", dist], { cwd: stage });
109
+ if (packed.code !== 0) return { stage, tarball: undefined, findings: [`bun pm pack stopped: ${packed.stderr || packed.stdout}`.trim()] };
110
+ return { stage, tarball: join(dist, tarballName(`@intellectual-frontiers/${bundle}`, l.version)), findings: [] };
111
+ }
112
+
113
+ /** The command line of a metapackage's `tools/pack.ts`: pack, print what was found (or the tarball) and the exit status. */
114
+ export async function main(root: string, argv: readonly string[]): Promise<number> {
115
+ if (argv.includes("--check") && (env.get("IFC_SKIP_PACK") ?? "") !== "") {
116
+ stdio.stdout.writeSync("pack check skipped: the set did not change in this push (IFC_SKIP_PACK); the release packs it\n");
117
+ return 0;
118
+ }
119
+ const r = await packMetapackage(root);
120
+ for (const f of r.findings) stdio.stderr.writeSync(`${f}\n`);
121
+ if (r.tarball === undefined) return 1;
122
+ stdio.stdout.writeSync(`${argv.includes("--check") ? `packed ${r.tarball}: nothing wrong` : r.tarball}\n`);
123
+ return 0;
124
+ }
125
+
126
+ /** The command line of the generator: 0, or 1 where a file is not what the manifests make (with `--check`) or a manifest is wrong. */
127
+ export function generate(argv: readonly string[]): number {
128
+ const at = argv.indexOf("--repo");
129
+ const repo = at >= 0 ? resolve(argv[at + 1] ?? ".") : resolve(".");
130
+ const check = argv.includes("--check");
131
+ const r = synchronize(repo, !check);
132
+ for (const p of r.problems) stdio.stderr.writeSync(`${p}\n`);
133
+ for (const s of r.stale) stdio.stderr.writeSync(check ? `${s} is not what the manifests make; run: bun commons/libraries/src/pack-metapackage.ts\n` : `wrote ${s}\n`);
134
+ return r.problems.length > 0 || (check && r.stale.length > 0) ? 1 : 0;
135
+ }
136
+
137
+ if (import.meta.main) process.exitCode = generate(process.argv.slice(2));
package/src/pins.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Commons' pins as the tools read them (commons 0005-typescript-runtime FR-026, 0002-packaging FR-019): the `KEY=value` lines of `pins.auto.env`, the suffix of a platform's
2
+ * Commons' pins as the tools read them (commons 0005-typescript-practice FR-026, 0002-packaging FR-019): the `KEY=value` lines of `pins.auto.env`, the suffix of a platform's
3
3
  * variables, and the download of a pin on a platform (its version, address, SHA-256, format and folder), all taken from the file and written nowhere else.
4
4
  *
5
5
  * Spec: 0001-libraries FR-006
package/src/readme.ts CHANGED
@@ -31,8 +31,9 @@ import { stdio } from "@intellectual-frontiers/system";
31
31
  import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
32
32
  import { type Library, type Registry, readLibraries } from "./libraries.ts";
33
33
 
34
- /** The marker that opens the generated table, and the one that closes it. */
34
+ /** The marker that opens the generated table. */
35
35
  export const BEGIN = "<!-- libraries-map:begin -->";
36
+ /** The marker that closes the generated table. */
36
37
  export const END = "<!-- libraries-map:end -->";
37
38
 
38
39
  /** What a library is for in the whole: a closed union. */
@@ -75,12 +76,22 @@ export const ROLE_OF: ReadonlyMap<string, Role> = new Map<string, Role>([
75
76
  ["kanon", "pattern"],
76
77
  ["archon", "program"],
77
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"],
78
87
  ["data", "program"],
88
+ ["docs", "program"],
79
89
  ["ergonex", "program"],
80
90
  ["grc", "program"],
81
91
  ["integrations", "program"],
82
92
  ["integrations-github", "program"],
83
93
  ["libraries", "program"],
94
+ ["repoctl", "program"],
84
95
  ["integrations-fhir", "standard"],
85
96
  ["integrations-x12", "standard"],
86
97
  ["mizan", "standard"],
@@ -112,6 +123,8 @@ export type Row = {
112
123
  readonly level: string;
113
124
  readonly distribution: readonly Registry[];
114
125
  readonly published: boolean;
126
+ /** Why the library is held out of the release, where it is. */
127
+ readonly held: string | undefined;
115
128
  };
116
129
 
117
130
  /**
@@ -197,7 +210,8 @@ export function rowOf(l: Library, summary: string): Result<Row, string> {
197
210
  shape: shapeOf(l),
198
211
  level: l.level,
199
212
  distribution: l.distribution,
200
- published: l.distribution.includes("npm"),
213
+ published: l.held === undefined && l.distribution.includes("npm"),
214
+ held: l.held,
201
215
  });
202
216
  }
203
217
 
@@ -210,7 +224,7 @@ export function tableOf(rows: readonly Row[]): string {
210
224
  const body = sorted.map((r) => {
211
225
  const pkg = `@intellectual-frontiers/${r.name}`;
212
226
  const href = r.published ? `https://www.npmjs.com/package/${pkg}` : `commons/${r.name}`;
213
- return `| [\`${pkg}\`](${href}) | ${ROLE_TITLE[r.role]} | ${r.purpose} | ${r.shape} | ${r.level} | ${r.distribution.map((d) => REGISTRY_TITLE[d]).join(", ")} |`;
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"} |`;
214
228
  });
215
229
  return [...head, ...body].join("\n");
216
230
  }
@@ -225,6 +239,7 @@ export function rowsOf(repo: string): { readonly rows: readonly Row[]; readonly
225
239
  problems.push(`commons/${f.dir}/library.ts: ${f.problem}`);
226
240
  continue;
227
241
  }
242
+ if (f.library.bundle !== undefined) continue; // a metapackage has no about.ts and is listed by {@link bundlesOf}
228
243
  const file = `${root}/commons/${f.dir}/about.ts`;
229
244
  if (!existsSync(file)) {
230
245
  problems.push(`commons/${f.dir}/about.ts is missing: the table takes its purpose from the summary there`);
@@ -242,6 +257,32 @@ export function rowsOf(repo: string): { readonly rows: readonly Row[]; readonly
242
257
  return { rows, problems };
243
258
  }
244
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
+
245
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. */
246
287
  export function withTable(readme: string, table: string): Result<string, string> {
247
288
  const from = readme.indexOf(`\n${BEGIN}\n`);
@@ -257,7 +298,8 @@ export function synchronize(repo: string, write: boolean): { readonly stale: boo
257
298
  const { rows, problems } = rowsOf(root);
258
299
  if (!existsSync(file)) return { stale: false, problems: [...problems, "README.md is missing"] };
259
300
  const text = readTextFileSync(file).replace(/\r\n/g, "\n");
260
- const made = withTable(text, tableOf(rows));
301
+ const bundles = bundlesTableOf(bundlesOf(root));
302
+ const made = withTable(text, bundles === "" ? tableOf(rows) : `${tableOf(rows)}\n\n${bundles}`);
261
303
  if (made.kind === "err") return { stale: false, problems: [...problems, made.error] };
262
304
  const stale = made.value !== text;
263
305
  if (stale && write && problems.length === 0) writeTextFileSync(file, made.value);