@intellectual-frontiers/libraries 0.2.1 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/LICENSE +75 -21
  2. package/dist/affected.d.ts +15 -2
  3. package/dist/affected.js +51 -20
  4. package/dist/dev.d.ts +83 -0
  5. package/dist/dev.js +359 -0
  6. package/dist/family.d.ts +58 -0
  7. package/dist/family.js +125 -0
  8. package/dist/generate-ontology.js +4 -0
  9. package/dist/generate-workflows.js +2 -10
  10. package/dist/install-bun.js +19 -14
  11. package/dist/libraries.d.ts +8 -0
  12. package/dist/libraries.js +24 -3
  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 +12 -0
  20. package/dist/link.js +98 -0
  21. package/dist/pack-library.d.ts +2 -0
  22. package/dist/pack-library.js +21 -3
  23. package/dist/pins.d.ts +34 -7
  24. package/dist/pins.js +36 -9
  25. package/dist/plan.d.ts +28 -0
  26. package/dist/plan.js +135 -0
  27. package/dist/readme.d.ts +59 -0
  28. package/dist/readme.js +272 -0
  29. package/dist/releasing.d.ts +176 -0
  30. package/dist/releasing.js +680 -0
  31. package/dist/versions.js +4 -7
  32. package/dist/workflows/definitions.d.ts +33 -30
  33. package/dist/workflows/definitions.js +201 -278
  34. package/dist/workflows/model.d.ts +19 -3
  35. package/dist/workflows/render.js +10 -2
  36. package/package.json +44 -14
  37. package/src/affected.ts +56 -17
  38. package/src/dev.ts +379 -0
  39. package/src/family.ts +144 -0
  40. package/src/generate-ontology.ts +4 -0
  41. package/src/generate-workflows.ts +3 -11
  42. package/src/install-bun.ts +16 -13
  43. package/src/libraries.ts +27 -3
  44. package/src/license/standard.ts +67 -0
  45. package/src/license/third-party.ts +87 -0
  46. package/src/license.ts +222 -0
  47. package/src/link.ts +97 -0
  48. package/src/pack-library.ts +21 -3
  49. package/src/pins.ts +55 -10
  50. package/src/plan.ts +143 -0
  51. package/src/readme.ts +278 -0
  52. package/src/releasing.ts +735 -0
  53. package/src/versions.ts +3 -7
  54. package/src/workflows/definitions.ts +262 -397
  55. package/src/workflows/model.ts +15 -3
  56. package/src/workflows/render.ts +10 -2
package/dist/link.js ADDED
@@ -0,0 +1,98 @@
1
+ /**
2
+ * The links of the libraries (commons 0001-libraries FR-011): every package of commons linked under `commons/node_modules/@intellectual-frontiers`, so that a library imports another by its package name and reads the checkout's
3
+ * source. It is the first command of every script that imports a library of commons (`dev:check`, `release`, the plan of CI), and it imports none: a fresh checkout has no link yet, and the command that makes them cannot
4
+ * itself need one.
5
+ *
6
+ * bun commons/libraries/src/link.ts link what is not linked, from the repository above this folder (or --repo DIR)
7
+ *
8
+ * @remarks
9
+ * A folder of `commons/` whose `package.json` is named `@intellectual-frontiers/<name>` is linked as that name, and `commons/ts` as `@intellectual-frontiers/commons` (`commons/docs` bears the same name and is not linked). A link
10
+ * that is there is left as it is. Only the built-ins of Node are used, so it runs on Bun and on Node 26 before anything is installed.
11
+ *
12
+ * @limits
13
+ * It links and nothing else: the packages the root and a library install are `bun install`'s.
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * import { linksOf } from "./link.ts";
18
+ * linksOf(".").get("@intellectual-frontiers/commons"); // the path of commons/ts
19
+ * ```
20
+ *
21
+ * Spec: 0001-libraries FR-011
22
+ *
23
+ * @module
24
+ */
25
+ import { existsSync, mkdirSync, readdirSync, readFileSync, symlinkSync } from "node:fs";
26
+ import { dirname, join, resolve } from "node:path";
27
+ import process from "node:process";
28
+ import { fileURLToPath } from "node:url";
29
+ const SCOPE = "@intellectual-frontiers/";
30
+ const nameOf = (file) => {
31
+ try {
32
+ const x = JSON.parse(readFileSync(file, "utf8"));
33
+ return typeof x === "object" && x !== null && "name" in x && typeof x.name === "string" ? x.name : undefined;
34
+ }
35
+ catch {
36
+ return undefined;
37
+ }
38
+ };
39
+ /** The packages of commons by name and the folder of each; `commons/ts` comes first, so that it is the one that bears `@intellectual-frontiers/commons`. */
40
+ export function linksOf(repo) {
41
+ const links = new Map();
42
+ const dirs = readdirSync(join(repo, "commons"), { withFileTypes: true })
43
+ .filter((e) => e.isDirectory() && e.name !== "node_modules")
44
+ .map((e) => e.name)
45
+ .sort((a, b) => (a === "ts" ? -1 : b === "ts" ? 1 : a < b ? -1 : 1));
46
+ for (const d of dirs) {
47
+ const name = nameOf(join(repo, "commons", d, "package.json"));
48
+ if (name !== undefined && name.startsWith(SCOPE) && !links.has(name))
49
+ links.set(name, join(repo, "commons", d));
50
+ }
51
+ return links;
52
+ }
53
+ /** Links each package that is not linked yet, and gives how many it linked, or why it could not. */
54
+ export function linkAll(repo) {
55
+ try {
56
+ const scope = join(repo, "commons", "node_modules", "@intellectual-frontiers");
57
+ let made = 0;
58
+ for (const [name, dir] of linksOf(repo)) {
59
+ const at = join(scope, name.slice(SCOPE.length));
60
+ if (existsSync(at))
61
+ continue;
62
+ if (made === 0)
63
+ mkdirSync(scope, { recursive: true });
64
+ symlinkSync(dir, at, "junction");
65
+ made += 1;
66
+ }
67
+ return { made };
68
+ }
69
+ catch (e) {
70
+ return { problem: `the libraries could not be linked under commons/node_modules: ${e instanceof Error ? e.message : String(e)}` };
71
+ }
72
+ }
73
+ /** The repository above a folder: the nearest one that has `commons/libraries/library.ts`. */
74
+ export function rootAbove(from) {
75
+ for (let d = resolve(from);; d = dirname(d)) {
76
+ if (existsSync(join(d, "commons", "libraries", "library.ts")))
77
+ return d;
78
+ if (dirname(d) === d)
79
+ return undefined;
80
+ }
81
+ }
82
+ /** The command line: 0, or 1 where it could not link. */
83
+ export function main(argv) {
84
+ const at = argv.indexOf("--repo");
85
+ const repo = at >= 0 ? resolve(argv[at + 1] ?? ".") : rootAbove(dirname(fileURLToPath(import.meta.url)));
86
+ if (repo === undefined) {
87
+ process.stderr.write("link: no repository with commons/libraries here; give --repo DIR\n");
88
+ return 1;
89
+ }
90
+ const r = linkAll(repo);
91
+ if ("problem" in r) {
92
+ process.stderr.write(`link: ${r.problem}\n`);
93
+ return 1;
94
+ }
95
+ return 0;
96
+ }
97
+ if (import.meta.main)
98
+ process.exitCode = main(process.argv.slice(2));
@@ -20,12 +20,14 @@ export declare function inspectPackage(stage: string): Findings;
20
20
  export declare function rewriteDeclarationSpecifiers(source: string): string;
21
21
  /** The tarball's name for a package: `@scope/name` at a version is `scope-name-version.tgz`. */
22
22
  export declare const tarballName: (name: string, version: string) => string;
23
+ /** What packing a library made: the staging folder, the tarball, the findings and the manifest. */
23
24
  export type Packed = {
24
25
  readonly stage: string;
25
26
  readonly tarball: string | undefined;
26
27
  readonly findings: Findings;
27
28
  readonly manifest: Json;
28
29
  };
30
+ /** What packing a library is told: its folder, where to stage it and whether to make the tarball. */
29
31
  export type PackOptions = {
30
32
  /** Types the compiler is given (`["node"]` for a library that names Node's). */
31
33
  readonly types?: readonly string[];
@@ -24,8 +24,10 @@
24
24
  */
25
25
  import { chmod, readTextFile, writeTextFile } from "@intellectual-frontiers/system/fs";
26
26
  import { existsSync, mkdirSync, readDirSync, readTextFileSync, removeSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
27
+ import { decodeLibrarySource, LIBRARY_FILE } from "./libraries.js";
28
+ import { COMMAND as LICENSE_COMMAND, licenseOf } from "./license.js";
27
29
  import { basename, dirname, join, relative, resolve, toPosix } from "@intellectual-frontiers/system/path";
28
- import { run, which } from "@intellectual-frontiers/system/proc";
30
+ import { env, run, which } from "@intellectual-frontiers/system/proc";
29
31
  /** The scope of the packages of commons. */
30
32
  export const SCOPE = "@intellectual-frontiers";
31
33
  const obj = (v) => (isObject(v) ? v : {});
@@ -285,6 +287,14 @@ function namesNodeTypes(folder) {
285
287
  }
286
288
  return false;
287
289
  }
290
+ /** The manifest of the library at `root`, where it has one that can be read. */
291
+ function manifestOf(root) {
292
+ const file = join(root, LIBRARY_FILE);
293
+ if (!existsSync(file))
294
+ return undefined;
295
+ const r = decodeLibrarySource(readTextFileSync(file));
296
+ return r.kind === "ok" ? r.value : undefined;
297
+ }
288
298
  /** Builds and stages the package of the library at `root` (a folder `commons/<name>/` with a `package.json` and sources in `src/`), inspects it and, where nothing is wrong, packs it. */
289
299
  export async function packLibrary(root, options = {}) {
290
300
  const own = JSON.parse(readTextFileSync(join(root, "package.json")));
@@ -438,7 +448,7 @@ export async function packLibrary(root, options = {}) {
438
448
  name,
439
449
  version: text(own["version"]),
440
450
  description: text(own["description"]),
441
- license: "MIT",
451
+ license: licenseOf(manifestOf(root)),
442
452
  type: "module",
443
453
  engines: { node: ">=26" },
444
454
  sideEffects: false,
@@ -477,7 +487,10 @@ export async function packLibrary(root, options = {}) {
477
487
  `Sources and specifications: https://github.com/intellectual-frontiers/.github/tree/main/commons/${short}`,
478
488
  "",
479
489
  ].join("\n"));
480
- copyFileSync(existsSync(join(root, "LICENSE")) ? join(root, "LICENSE") : join(commons, "ergonex", "LICENSE"), join(stage, "LICENSE"));
490
+ if (existsSync(join(root, "LICENSE")))
491
+ copyFileSync(join(root, "LICENSE"), join(stage, "LICENSE"));
492
+ else
493
+ findings.push(`commons/${short} has no LICENSE; run: ${LICENSE_COMMAND}`);
481
494
  findings.push(...inspectPackage(stage));
482
495
  if (findings.length > 0)
483
496
  return { stage, tarball: undefined, findings, manifest };
@@ -488,6 +501,11 @@ export async function packLibrary(root, options = {}) {
488
501
  }
489
502
  /** The command line of a library's `tools/pack.ts`: pack, print what was found (or the tarball) and the exit status. */
490
503
  export async function main(root, argv, options = {}) {
504
+ // the check inside `verify` is left out where CI says the exports did not change (`IFC_SKIP_PACK`); the packing for a publication is never skipped
505
+ if (argv.includes("--check") && (env.get("IFC_SKIP_PACK") ?? "") !== "") {
506
+ console.log("pack check skipped: the exports of this library did not change in this push (IFC_SKIP_PACK); the release packs it");
507
+ return 0;
508
+ }
491
509
  const r = await packLibrary(root, options);
492
510
  for (const f of r.findings)
493
511
  console.error(f);
package/dist/pins.d.ts CHANGED
@@ -1,15 +1,42 @@
1
1
  /**
2
- * Commons' pins as the tools read them (commons 0005-typescript-runtime FR-026): the `KEY=value` lines of `pins.auto.env`, and which of
3
- * Bun's release assets and pin keys belong to a platform.
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
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
6
6
  *
7
7
  * @module
8
8
  */
9
- /** The target name of Bun's release asset and the suffix of commons' pin key for a platform (by the names `proc.build` gives); undefined where Bun has no build. */
10
- export declare function bunTarget(os: string, arch: string): {
11
- readonly target: string;
12
- readonly key: string;
13
- } | undefined;
9
+ import { type Result } from "@intellectual-frontiers/core";
10
+ /** The suffix of commons' pin variables for a platform (by the names `proc.build` gives); undefined where commons pins no download for it. */
11
+ export declare function pinSuffix(os: string, arch: string): string | undefined;
14
12
  /** The `KEY=value` lines of an env file; comments and blank lines left out. */
15
13
  export declare function readEnvFile(text: string): ReadonlyMap<string, string>;
14
+ /** The formats of what a pinned address gives. */
15
+ export type PinFormat = "zip" | "tar" | "file";
16
+ /** What a download of a pin on a platform needs. */
17
+ export type PinDownload = {
18
+ readonly version: string;
19
+ readonly url: string;
20
+ readonly sha256: string;
21
+ readonly format: PinFormat;
22
+ /** The folder of the programs inside the unpacked artifact; empty for the root. */
23
+ readonly binPath: string;
24
+ };
25
+ /** Why a pin has no download on a platform. */
26
+ export type PinProblem = {
27
+ readonly kind: "no-version";
28
+ readonly key: string;
29
+ } | {
30
+ readonly kind: "not-pinned";
31
+ readonly key: string;
32
+ readonly suffix: string;
33
+ } | {
34
+ readonly kind: "bad-format";
35
+ readonly key: string;
36
+ readonly suffix: string;
37
+ readonly format: string;
38
+ };
39
+ /** The sentence a problem is told in. */
40
+ export declare function describePinProblem(p: PinProblem): string;
41
+ /** The download of the pin `key` (`BUN`) for the platform `suffix` (`X86_64`) as `pins.auto.env` states it, or why it has none. */
42
+ export declare function pinDownload(env: ReadonlyMap<string, string>, key: string, suffix: string): Result<PinDownload, PinProblem>;
package/dist/pins.js CHANGED
@@ -1,19 +1,20 @@
1
1
  /**
2
- * Commons' pins as the tools read them (commons 0005-typescript-runtime FR-026): the `KEY=value` lines of `pins.auto.env`, and which of
3
- * Bun's release assets and pin keys belong to a platform.
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
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
6
6
  *
7
7
  * @module
8
8
  */
9
- /** The target name of Bun's release asset and the suffix of commons' pin key for a platform (by the names `proc.build` gives); undefined where Bun has no build. */
10
- export function bunTarget(os, arch) {
9
+ import { err, ok } from "@intellectual-frontiers/core";
10
+ /** The suffix of commons' pin variables for a platform (by the names `proc.build` gives); undefined where commons pins no download for it. */
11
+ export function pinSuffix(os, arch) {
11
12
  const table = {
12
- "linux/x86_64": { target: "linux-x64", key: "X86_64" },
13
- "linux/aarch64": { target: "linux-aarch64", key: "AARCH64" },
14
- "darwin/x86_64": { target: "darwin-x64", key: "MACOS_X64" },
15
- "darwin/aarch64": { target: "darwin-aarch64", key: "MACOS_ARM64" },
16
- "windows/x86_64": { target: "windows-x64", key: "WINDOWS_X64" },
13
+ "linux/x86_64": "X86_64",
14
+ "linux/aarch64": "AARCH64",
15
+ "darwin/x86_64": "MACOS_X64",
16
+ "darwin/aarch64": "MACOS_ARM64",
17
+ "windows/x86_64": "WINDOWS_X64",
17
18
  };
18
19
  return Object.hasOwn(table, `${os}/${arch}`) ? table[`${os}/${arch}`] : undefined;
19
20
  }
@@ -27,3 +28,29 @@ export function readEnvFile(text) {
27
28
  }
28
29
  return out;
29
30
  }
31
+ /** The sentence a problem is told in. */
32
+ export function describePinProblem(p) {
33
+ switch (p.kind) {
34
+ case "no-version":
35
+ return `commons pins no ${p.key}`;
36
+ case "not-pinned":
37
+ return `commons pins no download of ${p.key} for ${p.suffix}`;
38
+ case "bad-format":
39
+ return `commons pins ${p.key} for ${p.suffix} as ${JSON.stringify(p.format)}, which is no format (zip, tar, file)`;
40
+ }
41
+ }
42
+ /** The download of the pin `key` (`BUN`) for the platform `suffix` (`X86_64`) as `pins.auto.env` states it, or why it has none. */
43
+ export function pinDownload(env, key, suffix) {
44
+ const version = env.get(`${key}_VERSION`);
45
+ if (version === undefined)
46
+ return err({ kind: "no-version", key });
47
+ const url = env.get(`${key}_URL_${suffix}`);
48
+ const sha256 = env.get(`${key}_SHA256_${suffix}`);
49
+ const format = env.get(`${key}_FORMAT_${suffix}`);
50
+ const binPath = env.get(`${key}_BINPATH_${suffix}`);
51
+ if (url === undefined || sha256 === undefined || format === undefined || binPath === undefined)
52
+ return err({ kind: "not-pinned", key, suffix });
53
+ if (format !== "zip" && format !== "tar" && format !== "file")
54
+ return err({ kind: "bad-format", key, suffix, format });
55
+ return ok({ version, url, sha256, format, binPath });
56
+ }
package/dist/plan.d.ts ADDED
@@ -0,0 +1,28 @@
1
+ import { type Cell } from "./workflows/definitions.js";
2
+ /** A library as the plan reads it. */
3
+ export type Planned = {
4
+ readonly name: string;
5
+ readonly folder: string;
6
+ readonly verify: string;
7
+ };
8
+ /** The cells of a job: what `strategy.matrix` reads as `{"include": [...]}`. */
9
+ export type Include = {
10
+ readonly include: readonly Cell[];
11
+ };
12
+ /** What CI runs for a change: the cells on Linux, and the cells on the other systems. */
13
+ export type Plan = {
14
+ readonly linux: Include;
15
+ readonly systems: Include;
16
+ };
17
+ /** The plan for these libraries: a cell on Linux for each, and one on each system its record names, in the order of the libraries; the packing is checked in the cells of the libraries named in `packs`. */
18
+ export declare function planOf(libs: readonly Planned[], packs?: ReadonlySet<string>): Plan;
19
+ /** The exports of a package.json as one line, the keys in order, so that two of them are the same where the entries are. */
20
+ export declare function exportsLine(packageJson: string): string;
21
+ /**
22
+ * The libraries whose packing a push checks (FR-013): those that changed their `exports` since the base (a new library included), and every library where the packer itself changed. Git that cannot say gives every library.
23
+ */
24
+ export declare function packsFor(repo: string, base: string, libs: readonly Planned[]): Promise<ReadonlySet<string>>;
25
+ /** The outputs of a step that a workflow reads: the matrices as one line of JSON each and whether each has a cell. */
26
+ export declare function outputsOf(p: Plan): string;
27
+ /** The command line. Returns the exit status: 0, or 2 for a command line that does not fit. */
28
+ export declare function main(argv: readonly string[]): Promise<number>;
package/dist/plan.js ADDED
@@ -0,0 +1,135 @@
1
+ /**
2
+ * The plan of CI (commons 0001-libraries FR-012): the libraries a push or a pull request affects, and for each the cells that the one workflow `ci` runs, so that a change proves what it touches and nothing else.
3
+ *
4
+ * bun commons/libraries/src/plan.ts --base origin/main the plan for what changed since the merge base with origin/main, as JSON
5
+ * bun commons/libraries/src/plan.ts --all every library
6
+ * bun commons/libraries/src/plan.ts --files a.ts,b/c.ts the libraries these files affect
7
+ * bun commons/libraries/src/plan.ts --base REF --github-output "$GITHUB_OUTPUT" the same, written as the outputs of a step: has-linux, linux, has-systems, systems
8
+ *
9
+ * @remarks
10
+ * The libraries are those of `affected.ts` (the same code the development loop and every check read), with the reach of `verify`: what a library's `verify` reads, and what depends on it. Each library has a cell on Linux; a
11
+ * library whose record of CI (`LIBRARY_CI`) names Windows or macOS has a cell on each of them too, because it has code of its own for them. A matrix with no cell is not written as a matrix (a workflow cannot run
12
+ * one): `has-linux` and `has-systems` say whether there is one.
13
+ *
14
+ * @limits
15
+ * It decides nothing about a version, a tag or a release; those are the release's. It cannot say what changed where Git cannot: it plans every library then, and says why.
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * import { planOf } from "./plan.ts";
20
+ * planOf([{ name: "net", folder: "commons/net", verify: "bun run verify" }]).systems.include.map((c) => c.os); // ["windows-latest", "macos-latest"]
21
+ * ```
22
+ *
23
+ * Spec: 0001-libraries FR-012
24
+ *
25
+ * @module
26
+ */
27
+ import process from "node:process";
28
+ import { stdio } from "@intellectual-frontiers/system";
29
+ import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
30
+ import { join } from "@intellectual-frontiers/system/path";
31
+ import { run } from "@intellectual-frontiers/system/proc";
32
+ import { flag, formatUsageError, helpText, many, parseArgs, value } from "@intellectual-frontiers/terminal/args";
33
+ import { affectedBy, changedSince, everyLibrary } from "./affected.js";
34
+ import { cellOf, LIBRARY_CI } from "./workflows/definitions.js";
35
+ /** The plan for these libraries: a cell on Linux for each, and one on each system its record names, in the order of the libraries; the packing is checked in the cells of the libraries named in `packs`. */
36
+ export function planOf(libs, packs = new Set()) {
37
+ return {
38
+ linux: { include: libs.map((l) => cellOf(l, undefined, packs.has(l.name))) },
39
+ systems: { include: libs.flatMap((l) => (LIBRARY_CI[l.name]?.systems ?? []).map((os) => cellOf(l, os, packs.has(l.name)))) },
40
+ };
41
+ }
42
+ /** The exports of a package.json as one line, the keys in order, so that two of them are the same where the entries are. */
43
+ export function exportsLine(packageJson) {
44
+ try {
45
+ const x = JSON.parse(packageJson);
46
+ const e = typeof x === "object" && x !== null && "exports" in x ? x.exports : undefined;
47
+ const sorted = (v) => typeof v === "object" && v !== null && !Array.isArray(v)
48
+ ? Object.fromEntries(Object.entries(v)
49
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
50
+ .map(([k, n]) => [k, sorted(n)]))
51
+ : v;
52
+ return JSON.stringify(sorted(e ?? null));
53
+ }
54
+ catch {
55
+ return "unreadable";
56
+ }
57
+ }
58
+ /**
59
+ * The libraries whose packing a push checks (FR-013): those that changed their `exports` since the base (a new library included), and every library where the packer itself changed. Git that cannot say gives every library.
60
+ */
61
+ export async function packsFor(repo, base, libs) {
62
+ const all = new Set(libs.map((l) => l.name));
63
+ const mb = await run(["git", "-C", repo, "merge-base", base, "HEAD"]);
64
+ if (mb.code !== 0)
65
+ return all;
66
+ const packer = await run(["git", "-C", repo, "diff", "--name-only", mb.stdout.trim(), "--", "commons/libraries/src/pack-library.ts"]);
67
+ if (packer.code !== 0 || packer.stdout.trim() !== "")
68
+ return all;
69
+ const out = new Set();
70
+ for (const l of libs) {
71
+ const before = await run(["git", "-C", repo, "show", `${mb.stdout.trim()}:${l.folder}/package.json`]);
72
+ const now = join(repo, l.folder, "package.json");
73
+ if (before.code !== 0 || !existsSync(now) || exportsLine(before.stdout) !== exportsLine(readTextFileSync(now)))
74
+ out.add(l.name);
75
+ }
76
+ return out;
77
+ }
78
+ /** The outputs of a step that a workflow reads: the matrices as one line of JSON each and whether each has a cell. */
79
+ export function outputsOf(p) {
80
+ return [
81
+ `has-linux=${p.linux.include.length > 0}`,
82
+ `linux=${JSON.stringify(p.linux)}`,
83
+ `has-systems=${p.systems.include.length > 0}`,
84
+ `systems=${JSON.stringify(p.systems)}`,
85
+ ].join("\n");
86
+ }
87
+ const OPTIONS = {
88
+ base: value({ help: "The revision the change starts at (the merge base with it is compared with the head).", valueName: "REF" }),
89
+ files: many({ help: "A file that changed (from the repository's root); the libraries it affects. Repeat or separate with commas.", valueName: "FILE" }),
90
+ all: flag({ help: "Every library." }),
91
+ repo: value({ help: "The repository (the working folder by default).", valueName: "DIR", default: "." }),
92
+ githubOutput: value({ help: "Append the outputs to this file, as a step's `$GITHUB_OUTPUT` is read.", valueName: "FILE" }),
93
+ };
94
+ /** The command line. Returns the exit status: 0, or 2 for a command line that does not fit. */
95
+ export async function main(argv) {
96
+ const parsed = parseArgs(argv, OPTIONS);
97
+ if (parsed.kind === "err") {
98
+ stdio.stderr.writeSync(`${formatUsageError(parsed.error, "plan")}\n`);
99
+ return 2;
100
+ }
101
+ if (parsed.value.kind === "help") {
102
+ stdio.stdout.writeSync(`${helpText("plan", "The libraries a change affects and the cells CI runs for them.", OPTIONS)}\n`);
103
+ return 0;
104
+ }
105
+ const o = parsed.value.options;
106
+ const files = (o.files ?? []).flatMap((f) => f.split(",")).filter((f) => f !== "");
107
+ let libs;
108
+ let packs = new Set();
109
+ if (o.all) {
110
+ libs = everyLibrary(o.repo);
111
+ packs = new Set(libs.map((l) => l.name));
112
+ }
113
+ else if (files.length > 0)
114
+ libs = affectedBy(o.repo, files);
115
+ else if (o.base !== undefined) {
116
+ const changed = await changedSince(o.repo, o.base);
117
+ if (changed === undefined)
118
+ stdio.stderr.writeSync(`plan: git cannot say what changed since ${o.base}; every library is planned\n`);
119
+ libs = changed === undefined ? everyLibrary(o.repo) : affectedBy(o.repo, changed);
120
+ packs = changed === undefined ? new Set(libs.map((l) => l.name)) : await packsFor(o.repo, o.base, libs);
121
+ }
122
+ else {
123
+ stdio.stderr.writeSync("plan: give --base REF, --files a,b or --all\n");
124
+ return 2;
125
+ }
126
+ const plan = planOf(libs, packs);
127
+ if (o.githubOutput === undefined)
128
+ stdio.stdout.writeSync(`${JSON.stringify(plan)}\n`);
129
+ else
130
+ writeTextFileSync(o.githubOutput, `${outputsOf(plan)}\n`, { append: true });
131
+ stdio.stderr.writeSync(`plan: ${libs.length} libraries: ${libs.map((l) => l.name).join(", ") || "none"}\n`);
132
+ return 0;
133
+ }
134
+ if (import.meta.main)
135
+ process.exitCode = await main(process.argv.slice(2));
@@ -0,0 +1,59 @@
1
+ import { type Brand, type Result } from "@intellectual-frontiers/core";
2
+ import { type Library, type Registry } from "./libraries.js";
3
+ /** The marker that opens the generated table, and the one that closes it. */
4
+ export declare const BEGIN = "<!-- libraries-map:begin -->";
5
+ export declare const END = "<!-- libraries-map:end -->";
6
+ /** What a library is for in the whole: a closed union. */
7
+ export declare const ROLES: readonly ["foundation", "pattern", "program", "standard"];
8
+ /** A role a reader of the README may be in, as the generated library map names them. */
9
+ export type Role = (typeof ROLES)[number];
10
+ /** The heading of a role in the table. */
11
+ export declare const ROLE_TITLE: Readonly<Record<Role, string>>;
12
+ /** A library's name (its folder), made only by {@link parseLibraryName}. */
13
+ export type LibraryName = Brand<string, "library name">;
14
+ /** A library name from text, or why the text is not one. */
15
+ export declare function parseLibraryName(text: string): Result<LibraryName, string>;
16
+ /** The role of each library, by name. A new library is classified here, or the check names it. */
17
+ export declare const ROLE_OF: ReadonlyMap<string, Role>;
18
+ /** One row of the table. */
19
+ export type Row = {
20
+ readonly name: LibraryName;
21
+ readonly role: Role;
22
+ readonly purpose: string;
23
+ readonly shape: string;
24
+ readonly level: string;
25
+ readonly distribution: readonly Registry[];
26
+ readonly published: boolean;
27
+ };
28
+ /**
29
+ * The `summary` of an `about.ts`, read as data: the double-quoted string literals after `summary:`, joined by `+`, and nothing run.
30
+ * An error where the file has no summary or it is not literals.
31
+ */
32
+ export declare function summaryOf(source: string): Result<string, string>;
33
+ /** 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. */
34
+ export declare function firstSentence(text: string): string;
35
+ /**
36
+ * 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
37
+ * outside parentheses and backticks and at least 25 characters in; the whole sentence where it has no such place.
38
+ */
39
+ export declare function firstClause(text: string): string;
40
+ /** The Kanon shape of a library: what its manifest declares, in words, or a dash where it declares no table. */
41
+ export declare function shapeOf(l: Library): string;
42
+ /** A row of the table for a library and its summary, or why there is none. */
43
+ export declare function rowOf(l: Library, summary: string): Result<Row, string>;
44
+ /** The table, as Markdown, for the rows given: sorted by role, then by name. */
45
+ export declare function tableOf(rows: readonly Row[]): string;
46
+ /** The rows of a repository, and what is wrong with reading them. */
47
+ export declare function rowsOf(repo: string): {
48
+ readonly rows: readonly Row[];
49
+ readonly problems: readonly string[];
50
+ };
51
+ /** 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. */
52
+ export declare function withTable(readme: string, table: string): Result<string, string>;
53
+ /** The result of a run: whether README.md is stale, and the problems found. With `write`, the file is written where it is stale. */
54
+ export declare function synchronize(repo: string, write: boolean): {
55
+ readonly stale: boolean;
56
+ readonly problems: readonly string[];
57
+ };
58
+ /** The command line: 0, or 1 where a problem was found or, with `--check`, README.md is not what the manifests make. */
59
+ export declare function main(argv: readonly string[]): number;