@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/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@intellectual-frontiers/libraries",
3
- "version": "0.2.1",
3
+ "version": "0.4.1",
4
4
  "description": "The libraries of a repository of commons as code: the manifest of a library and the check that it and its folder agree, which libraries a change affects, the typed workflows of GitHub Actions and their generator, the pinned Bun, the packer that builds, inspects and packs a library for npm with its declarations, and the commands that hold a whole repository to Mizan (check, change control, versions, the register and the ontologies).",
5
- "license": "MIT",
5
+ "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "type": "module",
7
7
  "engines": {
8
8
  "node": ">=26"
@@ -30,6 +30,11 @@
30
30
  "bun": "./src/check.ts",
31
31
  "default": "./dist/check.js"
32
32
  },
33
+ "./dev": {
34
+ "types": "./dist/dev.d.ts",
35
+ "bun": "./src/dev.ts",
36
+ "default": "./dist/dev.js"
37
+ },
33
38
  "./generate-ontology": {
34
39
  "types": "./dist/generate-ontology.d.ts",
35
40
  "bun": "./src/generate-ontology.ts",
@@ -45,6 +50,16 @@
45
50
  "bun": "./src/libraries.ts",
46
51
  "default": "./dist/libraries.js"
47
52
  },
53
+ "./license": {
54
+ "types": "./dist/license.d.ts",
55
+ "bun": "./src/license.ts",
56
+ "default": "./dist/license.js"
57
+ },
58
+ "./link": {
59
+ "types": "./dist/link.d.ts",
60
+ "bun": "./src/link.ts",
61
+ "default": "./dist/link.js"
62
+ },
48
63
  "./newer": {
49
64
  "types": "./dist/newer.d.ts",
50
65
  "bun": "./src/newer.ts",
@@ -65,11 +80,26 @@
65
80
  "bun": "./src/pins.ts",
66
81
  "default": "./dist/pins.js"
67
82
  },
83
+ "./releasing": {
84
+ "types": "./dist/releasing.d.ts",
85
+ "bun": "./src/releasing.ts",
86
+ "default": "./dist/releasing.js"
87
+ },
88
+ "./plan": {
89
+ "types": "./dist/plan.d.ts",
90
+ "bun": "./src/plan.ts",
91
+ "default": "./dist/plan.js"
92
+ },
68
93
  "./publish-ontology": {
69
94
  "types": "./dist/publish-ontology.d.ts",
70
95
  "bun": "./src/publish-ontology.ts",
71
96
  "default": "./dist/publish-ontology.js"
72
97
  },
98
+ "./readme": {
99
+ "types": "./dist/readme.d.ts",
100
+ "bun": "./src/readme.ts",
101
+ "default": "./dist/readme.js"
102
+ },
73
103
  "./versions": {
74
104
  "types": "./dist/versions.d.ts",
75
105
  "bun": "./src/versions.ts",
@@ -97,18 +127,18 @@
97
127
  }
98
128
  },
99
129
  "dependencies": {
100
- "@intellectual-frontiers/core": "0.1.4",
101
- "@intellectual-frontiers/crypto": "0.1.4",
102
- "@intellectual-frontiers/formats": "0.1.4",
103
- "@intellectual-frontiers/githost": "0.1.2",
104
- "@intellectual-frontiers/kanon": "0.1.0",
105
- "@intellectual-frontiers/mizan": "0.1.1",
106
- "@intellectual-frontiers/net": "0.1.5",
107
- "@intellectual-frontiers/ontology": "0.2.0",
108
- "@intellectual-frontiers/quality": "0.2.0",
109
- "@intellectual-frontiers/rdf": "0.1.4",
110
- "@intellectual-frontiers/system": "0.1.6",
111
- "@intellectual-frontiers/terminal": "0.1.6"
130
+ "@intellectual-frontiers/core": "0.1.5",
131
+ "@intellectual-frontiers/crypto": "0.1.5",
132
+ "@intellectual-frontiers/formats": "0.1.5",
133
+ "@intellectual-frontiers/githost": "0.1.3",
134
+ "@intellectual-frontiers/kanon": "0.2.1",
135
+ "@intellectual-frontiers/mizan": "0.1.2",
136
+ "@intellectual-frontiers/net": "0.1.6",
137
+ "@intellectual-frontiers/ontology": "0.3.1",
138
+ "@intellectual-frontiers/quality": "0.2.1",
139
+ "@intellectual-frontiers/rdf": "0.1.5",
140
+ "@intellectual-frontiers/system": "0.1.7",
141
+ "@intellectual-frontiers/terminal": "0.1.7"
112
142
  },
113
143
  "files": [
114
144
  "dist",
package/src/affected.ts CHANGED
@@ -43,6 +43,10 @@ export type Inputs = {
43
43
  readonly dependsOn: readonly string[];
44
44
  /** Every file of another folder that it reads, from the repository's root, in order. */
45
45
  readonly files: readonly string[];
46
+ /** The libraries whose package its sources import by name: what its types and its tests read, which its scripts do not add. */
47
+ readonly imports: readonly string[];
48
+ /** The paths its types and its tests read: its folder and what its imports reach (no tool its scripts run, no workflow). */
49
+ readonly codePaths: readonly string[];
46
50
  };
47
51
 
48
52
  /** The folders whose change is every library's change: the tools that check a library and the action that installs Bun. */
@@ -149,8 +153,11 @@ export function inputsOf(repo: string, name: string): Inputs {
149
153
  const sources = sourcesUnder(root, folder);
150
154
  const texts = sources.map((f) => ({ f, text: readTextFileSync(join(root, f)) }));
151
155
  const entries = new Set<string>();
156
+ const codeEntries = new Set<string>();
152
157
  const whole = new Set<string>();
158
+ const codeWhole = new Set<string>();
153
159
  const dependsOn = new Set<string>();
160
+ const imports = new Set<string>();
154
161
  // a dependency by path: its folder, what the library's sources import from it, and the entries it maps them to
155
162
  for (const [dep, spec] of pkg?.dependencies ?? []) {
156
163
  const m = /^(?:link|file|workspace):(.+)$/.exec(spec);
@@ -159,15 +166,26 @@ export function inputsOf(repo: string, name: string): Inputs {
159
166
  if (dir.startsWith("..") || !existsSync(join(root, dir))) continue;
160
167
  const depPkg = readPackage(join(root, dir));
161
168
  dependsOn.add(dir.split("/")[1] ?? dir);
162
- const imported = new Set<string>();
163
- for (const { text } of texts)
164
- for (const s of specifiersOf(text))
165
- if (s === dep || s.startsWith(`${dep}/`)) imported.add(s === dep ? "." : `.${s.slice(dep.length)}`);
166
- for (const key of imported) {
167
- const target = depPkg?.exports.get(key);
168
- if (target === undefined) whole.add(`${dir}/**`);
169
- else entries.add(posix(join(dir, target)));
170
- }
169
+ const importedBy = (own: readonly { readonly f: string; readonly text: string }[]): ReadonlySet<string> => {
170
+ const found = new Set<string>();
171
+ for (const { text } of own)
172
+ for (const s of specifiersOf(text))
173
+ if (s === dep || s.startsWith(`${dep}/`)) found.add(s === dep ? "." : `.${s.slice(dep.length)}`);
174
+ return found;
175
+ };
176
+ // what its types and tests read is what its own code (`about.ts` and `src/`) imports; its suite and its tools also read the packages their scripts run
177
+ const imported = importedBy(texts);
178
+ const ownCode = importedBy(texts.filter((t) => t.f === `${folder}/about.ts` || t.f.startsWith(`${folder}/src/`)));
179
+ if (ownCode.size > 0 && existsSync(join(root, dir, "library.ts"))) imports.add(dir.split("/")[1] ?? dir);
180
+ for (const [keys, into, all] of [
181
+ [imported, entries, whole],
182
+ [ownCode, codeEntries, codeWhole],
183
+ ] as const)
184
+ for (const key of keys) {
185
+ const target = depPkg?.exports.get(key);
186
+ if (target === undefined) all.add(`${dir}/**`);
187
+ else into.add(posix(join(dir, target)));
188
+ }
171
189
  }
172
190
  // a path to another folder in a script of the package: `bun ../libraries/src/check.ts`
173
191
  for (const script of pkg?.scripts ?? [])
@@ -176,12 +194,18 @@ export function inputsOf(repo: string, name: string): Inputs {
176
194
  if (!p.startsWith("..") && existsSync(join(root, p)) && SOURCE.test(p)) entries.add(p);
177
195
  }
178
196
  const files = [...closure(root, [...entries])].filter((f) => !f.startsWith(`${folder}/`)).sort();
179
- const paths = [`${folder}/**`, ...new Set([...files.map(folderOf), ...whole, ...SHARED, `.github/workflows/${name}.auto.yml`])].sort();
197
+ const paths = [`${folder}/**`, ...new Set([...files.map(folderOf), ...whole, ...SHARED, ".github/workflows/ci.auto.yml"])].sort();
180
198
  for (const f of files) {
181
199
  const d = f.split("/")[1];
182
200
  if (d !== undefined && d !== name && existsSync(join(root, "commons", d, "library.ts"))) dependsOn.add(d);
183
201
  }
184
- return { paths, dependsOn: [...dependsOn].sort(), files };
202
+ const codeFiles = [...closure(root, [...codeEntries])].filter((f) => !f.startsWith(`${folder}/`));
203
+ for (const f of codeFiles) {
204
+ const d = f.split("/")[1];
205
+ if (d !== undefined && d !== name && existsSync(join(root, "commons", d, "library.ts"))) imports.add(d);
206
+ }
207
+ const codePaths = [`${folder}/**`, ...new Set([...codeFiles.map(folderOf), ...codeWhole])].sort();
208
+ return { paths, dependsOn: [...dependsOn].sort(), files, imports: [...imports].sort(), codePaths };
185
209
  }
186
210
 
187
211
  /** Whether a path of the repository is among the paths of an input: `dir/**` is the folder and what is under it, anything else the file. */
@@ -189,16 +213,29 @@ export function matches(paths: readonly string[], file: string): boolean {
189
213
  return paths.some((p) => (p.endsWith("/**") ? file.startsWith(p.slice(0, -2)) : p === file));
190
214
  }
191
215
 
216
+ /** Every library of the repository, with its folder. */
217
+ export function everyLibrary(repo: string): readonly (Library & { readonly folder: string })[] {
218
+ return readLibraries(repo).flatMap((f) => ("library" in f ? [{ ...f.library, folder: `commons/${f.dir}` }] : []));
219
+ }
220
+
221
+ /**
222
+ * What a change reaches: `verify`, everything the library's `verify` reads (its scripts' tools, the shared tools, its workflow: what CI runs), or `code`, what its types and its tests read (its folder and the
223
+ * packages its sources import, which is what the development loop runs).
224
+ */
225
+ export type Reach = "verify" | "code";
226
+
192
227
  /** The libraries that a list of changed files affects (FR-021): those with a changed file among their inputs, and those that depend on one of these, in order of their names. */
193
- export function affectedBy(repo: string, changed: readonly string[]): readonly (Library & { readonly folder: string })[] {
228
+ export function affectedBy(repo: string, changed: readonly string[], reach: Reach = "verify"): readonly (Library & { readonly folder: string })[] {
194
229
  const root = repo.replace(/[\\/]$/, "");
195
230
  const libs = readLibraries(root).flatMap((f) => ("library" in f ? [f.library] : []));
196
231
  const inputs = new Map(libs.map((l) => [l.name, inputsOf(root, l.name)]));
197
- const hit = new Set(libs.filter((l) => changed.some((c) => matches(inputs.get(l.name)?.paths ?? [], c))).map((l) => l.name));
232
+ const pathsOf = (n: string): readonly string[] => (reach === "verify" ? inputs.get(n)?.paths : inputs.get(n)?.codePaths) ?? [];
233
+ const depsOf = (n: string): readonly string[] => (reach === "verify" ? inputs.get(n)?.dependsOn : inputs.get(n)?.imports) ?? [];
234
+ const hit = new Set(libs.filter((l) => changed.some((c) => matches(pathsOf(l.name), c))).map((l) => l.name));
198
235
  for (let grew = true; grew;) {
199
236
  grew = false;
200
237
  for (const l of libs) {
201
- if (!hit.has(l.name) && (inputs.get(l.name)?.dependsOn ?? []).some((d) => hit.has(d))) {
238
+ if (!hit.has(l.name) && depsOf(l.name).some((d) => hit.has(d))) {
202
239
  hit.add(l.name);
203
240
  grew = true;
204
241
  }
@@ -207,14 +244,16 @@ export function affectedBy(repo: string, changed: readonly string[]): readonly (
207
244
  return libs.filter((l) => hit.has(l.name)).map((l) => ({ ...l, folder: `commons/${l.name}` }));
208
245
  }
209
246
 
210
- /** The files changed since the merge base of `base` and the head, tracked files of the working tree included; undefined where Git cannot say. */
247
+ /** The files changed since the merge base of `base` and the head, the working tree's tracked and new files included; undefined where Git cannot say. */
211
248
  export async function changedSince(repo: string, base: string): Promise<readonly string[] | undefined> {
212
249
  const root = resolve(repo);
213
250
  try {
214
251
  const mb = await run(["git", "-C", root, "merge-base", base, "HEAD"]);
215
252
  if (mb.code !== 0) return undefined;
216
253
  const d = await run(["git", "-C", root, "diff", "--name-only", mb.stdout.trim()]);
217
- return d.code === 0 ? d.stdout.split("\n").filter((l) => l !== "") : undefined;
254
+ const fresh = await run(["git", "-C", root, "ls-files", "--others", "--exclude-standard"]);
255
+ if (d.code !== 0 || fresh.code !== 0) return undefined;
256
+ return [...new Set([...d.stdout.split("\n"), ...fresh.stdout.split("\n")])].filter((l) => l !== "");
218
257
  } catch {
219
258
  return undefined;
220
259
  }
@@ -238,7 +277,7 @@ export async function main(argv: readonly string[]): Promise<number> {
238
277
  stdio.stdout.writeSync(`${[...i.paths, ...i.files.map((f) => ` ${f}`)].join("\n")}\n`);
239
278
  return 0;
240
279
  }
241
- const everything = readLibraries(repo).flatMap((f) => ("library" in f ? [{ ...f.library, folder: `commons/${f.dir}` }] : []));
280
+ const everything = everyLibrary(repo);
242
281
  const files = arg("--files");
243
282
  const base = arg("--base");
244
283
  if (argv.includes("--all")) stdio.stdout.writeSync(`${matrixOf(everything)}\n`);
package/src/dev.ts ADDED
@@ -0,0 +1,379 @@
1
+ /**
2
+ * The development loop (commons 0001-libraries FR-011, FR-012): the libraries a working tree changes, and the libraries that depend on them, type-checked and tested in parallel processes and no more than they need, with a calm summary. It is
3
+ * what a person or an agent runs between two edits; the release loop (the packing of every library, the register, the versions) is another command and is never part of this one.
4
+ *
5
+ * bun run dev:check the libraries affected since origin/main (and the files not yet committed), their types and their tests
6
+ * bun run dev:check --only system,net those libraries and their dependents, whatever changed
7
+ * bun run dev:check --files a.ts,b/c.ts the libraries these files affect (paths from the repository's root)
8
+ * bun run dev:check --all every library
9
+ * bun run dev:check --list say what is affected and run nothing
10
+ * other flags: --base REF (origin/main by default), --no-types, --no-tests, --no-license, --bail (stop at the first failing test), --repo DIR
11
+ *
12
+ * @remarks
13
+ * Nothing is installed per library. The repository's root installs the packages every library shares (`bun install`, once), the libraries are linked under `commons/node_modules` (a link for each folder whose package
14
+ * name is `@intellectual-frontiers/<folder>`, and `@intellectual-frontiers/commons` for `commons/ts`), so that a library that imports another by its package name reads the checkout's source, never a copy from a
15
+ * registry: the `exports` of each package are the sources. A library with a package of its own outside the shared set (a database driver) is installed in its folder, once. The affected libraries are those of
16
+ * `affected.ts` (the same code the workflow of CI runs); TypeScript 7 checks each library's own `tsconfig.json`, several at a time, and the tests of each run in a `bun test` process of its own, from its folder as `verify` runs them, several at a time.
17
+ *
18
+ * @limits
19
+ * It proves less than `bun run verify` of a library: no specification check, no trace, no packing, no Node 26, no other system than this one. CI runs those on the libraries a push affects.
20
+ * A change of a file that no library reads affects no library, and nothing is run.
21
+ *
22
+ * @example
23
+ * ```ts
24
+ * import { bunCounts } from "./dev.ts";
25
+ * bunCounts(" 913 pass\n 3 skip\n 0 fail\nRan 917 tests across 141 files. [55.88s]\n"); // { pass: 913, skip: 3, fail: 0, files: 141 }
26
+ * ```
27
+ *
28
+ * Spec: 0001-libraries FR-011
29
+ *
30
+ * @module
31
+ */
32
+ import process from "node:process";
33
+ import { absurd, err, ok, type Result } from "@intellectual-frontiers/core";
34
+ import { stdio } from "@intellectual-frontiers/system";
35
+ import { existsSync, readDirSync, readTextFileSync } from "@intellectual-frontiers/system/fs";
36
+ import { dirname, join, resolve } from "@intellectual-frontiers/system/path";
37
+ import { build, run } from "@intellectual-frontiers/system/proc";
38
+ import { currentLook, type Look } from "@intellectual-frontiers/system/tty";
39
+ import { flag, formatUsageError, helpText, many, parseArgs, value } from "@intellectual-frontiers/terminal/args";
40
+ import { label, paint } from "@intellectual-frontiers/terminal/palette";
41
+ import { affectedBy, changedSince, everyLibrary } from "./affected.ts";
42
+ import { linkAll } from "./link.ts";
43
+ import { judge as judgeLicense, sentence as licenseSentence } from "./license.ts";
44
+ import type { Library } from "./libraries.ts";
45
+
46
+ /** What the loop is asked about: what changed since a revision, a list of files, named libraries or everything. */
47
+ export type Scope =
48
+ | { readonly kind: "since"; readonly base: string }
49
+ | { readonly kind: "files"; readonly files: readonly string[] }
50
+ | { readonly kind: "only"; readonly names: readonly string[] }
51
+ | { readonly kind: "all" };
52
+
53
+ /** A library of the repository with its folder, as `affected.ts` gives it. */
54
+ export type Lib = Library & { readonly folder: string };
55
+
56
+ /** How one stage of the loop ended. */
57
+ export type Outcome =
58
+ | { readonly kind: "passed"; readonly detail: string }
59
+ | { readonly kind: "failed"; readonly detail: string; readonly output: readonly string[] }
60
+ | { readonly kind: "skipped"; readonly detail: string };
61
+
62
+ /** The counts of one `bun test` run. */
63
+ export type Counts = { readonly pass: number; readonly skip: number; readonly fail: number; readonly files: number };
64
+
65
+ /** The counts in the end of what `bun test` printed, or undefined where it printed none. */
66
+ export function bunCounts(text: string): Counts | undefined {
67
+ const n = (word: string): number => Number(new RegExp(`^\\s*(\\d+) ${word}\\s*$`, "m").exec(text)?.[1] ?? 0);
68
+ const ran = /^Ran \d+ tests? across (\d+) files?/m.exec(text);
69
+ return ran?.[1] === undefined ? undefined : { pass: n("pass"), skip: n("skip"), fail: n("fail"), files: Number(ran[1]) };
70
+ }
71
+
72
+ /** The lines of `bun test`'s output that say what failed: the failing tests and the error lines above each, in order. */
73
+ export function failureLines(text: string): readonly string[] {
74
+ const lines = text.split("\n");
75
+ const out: string[] = [];
76
+ lines.forEach((l, i) => {
77
+ if (!/^\(fail\)/.test(l) && !/^error:/.test(l)) return;
78
+ if (/^\(fail\)/.test(l)) out.push(l);
79
+ else {
80
+ out.push(l);
81
+ for (const next of lines.slice(i + 1, i + 6)) if (/^\s+at |^\s+\d+ \|/.test(next)) out.push(next);
82
+ }
83
+ });
84
+ return out.length > 0 ? out : lines.slice(-30);
85
+ }
86
+
87
+ /** The first lines of a compiler's output, so a long one does not bury the summary. */
88
+ export function head(lines: readonly string[], n: number): readonly string[] {
89
+ return lines.length <= n ? lines : [...lines.slice(0, n), `... and ${lines.length - n} more`];
90
+ }
91
+
92
+ /** The packages a library declares that neither are libraries of the repository nor are installed at the root: the ones it must install itself. */
93
+ export function ownPackages(pkg: Readonly<Record<string, unknown>>, shared: ReadonlySet<string>): readonly string[] {
94
+ const out = new Set<string>();
95
+ for (const field of ["dependencies", "devDependencies"]) {
96
+ const o = pkg[field];
97
+ if (typeof o !== "object" || o === null) continue;
98
+ for (const [k, v] of Object.entries(o)) if (typeof v === "string" && !v.startsWith("link:") && !shared.has(k)) out.add(k);
99
+ }
100
+ return [...out].sort();
101
+ }
102
+
103
+ const readJson = (file: string): Readonly<Record<string, unknown>> => {
104
+ try {
105
+ const x: unknown = JSON.parse(readTextFileSync(file));
106
+ return typeof x === "object" && x !== null && !Array.isArray(x) ? Object.fromEntries(Object.entries(x)) : {};
107
+ } catch {
108
+ return {};
109
+ }
110
+ };
111
+
112
+ /** Links the libraries under `commons/node_modules` where they are not linked yet (`link.ts`, which `bun run dev:check` runs before this command can import any of them). */
113
+ export function linkLibraries(repo: string): Result<number, string> {
114
+ const r = linkAll(repo);
115
+ return "problem" in r ? err(r.problem) : ok(r.made);
116
+ }
117
+
118
+ /** The revision a loop compares with where none is given: `origin/main`, else `main`, else `HEAD` (the working tree alone). */
119
+ export async function defaultBase(repo: string): Promise<string> {
120
+ for (const ref of ["origin/main", "main"]) {
121
+ const r = await run(["git", "-C", repo, "rev-parse", "--verify", "--quiet", ref]);
122
+ if (r.code === 0) return ref;
123
+ }
124
+ return "HEAD";
125
+ }
126
+
127
+ /** What a scope affects: the libraries and why, or why it cannot be said. */
128
+ export async function affectedOf(repo: string, scope: Scope): Promise<Result<{ readonly libs: readonly Lib[]; readonly why: string }, string>> {
129
+ switch (scope.kind) {
130
+ case "all":
131
+ return ok({ libs: everyLibrary(repo), why: "every library" });
132
+ case "files":
133
+ return ok({ libs: affectedBy(repo, scope.files, "code"), why: `${scope.files.length} named files` });
134
+ case "only": {
135
+ const all = everyLibrary(repo);
136
+ const unknown = scope.names.filter((n) => !all.some((l) => l.name === n));
137
+ if (unknown.length > 0) return err(`no library named ${unknown.join(", ")} (they are: ${all.map((l) => l.name).join(", ")})`);
138
+ const roots = all.filter((l) => scope.names.includes(l.name)).flatMap((l) => `commons/${l.name}/library.ts`);
139
+ return ok({ libs: affectedBy(repo, roots, "code"), why: `${scope.names.join(", ")} and what imports them` });
140
+ }
141
+ case "since": {
142
+ const changed = await changedSince(repo, scope.base);
143
+ if (changed === undefined) return ok({ libs: everyLibrary(repo), why: `git cannot say what changed since ${scope.base}` });
144
+ return ok({ libs: affectedBy(repo, changed, "code"), why: `${changed.length} files changed since ${scope.base}` });
145
+ }
146
+ default:
147
+ return absurd(scope);
148
+ }
149
+ }
150
+
151
+ /** The compiler's program for this system: the one the root installs. */
152
+ const tscOf = (repo: string): string => join(repo, "node_modules", ".bin", build.os === "windows" ? "tsc.cmd" : "tsc");
153
+
154
+ /** Runs `job` over `items`, at most `width` at a time, and gives the results in the order of the items. */
155
+ export async function pool<T, R>(items: readonly T[], width: number, job: (item: T) => Promise<R>): Promise<readonly R[]> {
156
+ const out: R[] = [];
157
+ const results = new Map<number, R>();
158
+ let next = 0;
159
+ const worker = async (): Promise<void> => {
160
+ for (let i = next++; i < items.length; i = next++) {
161
+ const item = items[i];
162
+ if (item !== undefined) results.set(i, await job(item));
163
+ }
164
+ };
165
+ await Promise.all(Array.from({ length: Math.max(1, Math.min(width, items.length)) }, worker));
166
+ for (let i = 0; i < items.length; i++) {
167
+ const r = results.get(i);
168
+ if (r !== undefined) out.push(r);
169
+ }
170
+ return out;
171
+ }
172
+
173
+ const seconds = (since: number): string => `${((performance.now() - since) / 1000).toFixed(1)}s`;
174
+ const plural = (n: number, one: string, many_ = `${one}s`): string => `${n} ${n === 1 ? one : many_}`;
175
+
176
+ /** What the loop needs installed: the root's packages, the links, and the packages of a library that has its own. */
177
+ export async function prepare(repo: string, libs: readonly Lib[]): Promise<Result<readonly string[], string>> {
178
+ const said: string[] = [];
179
+ if (!existsSync(tscOf(repo))) {
180
+ const r = await run(["bun", "install", "--frozen-lockfile"], { cwd: repo });
181
+ if (r.code !== 0) return err(`bun install at the root failed:\n${r.stderr.trim()}`);
182
+ said.push("installed the packages of the root");
183
+ }
184
+ const linked = linkLibraries(repo);
185
+ if (linked.kind === "err") return linked;
186
+ if (linked.value > 0) said.push(`linked ${plural(linked.value, "package")} under commons/node_modules`);
187
+ const rootPkg = readJson(join(repo, "package.json"));
188
+ const shared = new Set(
189
+ ["dependencies", "devDependencies"].flatMap((f) => {
190
+ const o = rootPkg[f];
191
+ return typeof o === "object" && o !== null ? Object.keys(o) : [];
192
+ }),
193
+ );
194
+ for (const l of libs) {
195
+ const own = ownPackages(readJson(join(repo, l.folder, "package.json")), shared);
196
+ if (own.length === 0 || existsSync(join(repo, l.folder, "node_modules"))) continue;
197
+ const r = await run(["bun", "install", "--frozen-lockfile"], { cwd: join(repo, l.folder) });
198
+ if (r.code !== 0) return err(`bun install in ${l.folder} failed:\n${r.stderr.trim()}`);
199
+ said.push(`installed ${l.folder}'s own packages (${own.join(", ")})`);
200
+ }
201
+ return ok(said);
202
+ }
203
+
204
+ /** TypeScript on the libraries, several at a time. */
205
+ export async function typeCheck(repo: string, libs: readonly Lib[], width: number): Promise<Outcome> {
206
+ const t0 = performance.now();
207
+ const checked = libs.filter((l) => existsSync(join(repo, l.folder, "tsconfig.json")));
208
+ const results = await pool(checked, width, async (l) => {
209
+ const r = await run([tscOf(repo), "-p", "tsconfig.json", "--pretty", "false"], { cwd: join(repo, l.folder) });
210
+ return { name: l.name, code: r.code, lines: `${r.stdout}${r.stderr}`.split("\n").filter((x) => x.trim() !== "") };
211
+ });
212
+ const bad = results.filter((r) => r.code !== 0);
213
+ if (bad.length === 0) return { kind: "passed", detail: `${plural(checked.length, "library", "libraries")} in ${seconds(t0)}` };
214
+ return {
215
+ kind: "failed",
216
+ detail: `${bad.map((b) => b.name).join(", ")} in ${seconds(t0)}`,
217
+ output: bad.flatMap((b) => head(b.lines, 25).map((x) => `${b.name}: ${x}`)),
218
+ };
219
+ }
220
+
221
+ /** The license of the repository and of each library, as the check of `license.ts` finds it: a library with no `LICENSE` fails here, and the sentence says the command that writes it. */
222
+ export async function licenseStage(repo: string): Promise<Outcome> {
223
+ const t0 = performance.now();
224
+ const { findings } = await judgeLicense(repo);
225
+ if (findings.length === 0) return { kind: "passed", detail: `every LICENSE is the official text in ${seconds(t0)}` };
226
+ return { kind: "failed", detail: plural(findings.length, "finding", "findings"), output: findings.map(licenseSentence) };
227
+ }
228
+
229
+ /** The sum of counts. */
230
+ export const addCounts = (a: Counts, b: Counts): Counts => ({ pass: a.pass + b.pass, skip: a.skip + b.skip, fail: a.fail + b.fail, files: a.files + b.files });
231
+
232
+ /**
233
+ * The tests of the libraries: one `bun test suite/` process for each library, from its folder as its `verify` runs it, several at a time and the largest suites first. One process for all of them would be fewer, but a
234
+ * test may set what is global to its process (the tracer of a process, a working folder), and what it sets must not reach the tests of another library.
235
+ */
236
+ export async function runTests(repo: string, libs: readonly Lib[], width: number, bail: boolean): Promise<Outcome> {
237
+ const t0 = performance.now();
238
+ const files = (l: Lib): number => readDirSync(join(repo, l.folder, "suite")).length;
239
+ const suites = libs.filter((l) => existsSync(join(repo, l.folder, "suite"))).sort((a, b) => files(b) - files(a));
240
+ if (suites.length === 0) return { kind: "skipped", detail: "no library of these has a suite" };
241
+ const results = await pool(suites, width, async (l) => {
242
+ const r = await run(["bun", "test", ...(bail ? ["--bail"] : []), "suite/"], { cwd: join(repo, l.folder), env: { CI: "" } });
243
+ const text = `${r.stdout}\n${r.stderr}`;
244
+ return { name: l.name, code: r.code, counts: bunCounts(text), text };
245
+ });
246
+ const total = results.reduce((sum, r) => (r.counts === undefined ? sum : addCounts(sum, r.counts)), { pass: 0, skip: 0, fail: 0, files: 0 });
247
+ const detail = `${total.pass} pass${total.skip > 0 ? `, ${total.skip} skipped` : ""}${total.fail > 0 ? `, ${total.fail} fail` : ""} in ${plural(total.files, "file")} of ${plural(suites.length, "library", "libraries")}, ${seconds(t0)}`;
248
+ const bad = results.filter((r) => r.code !== 0 || r.counts === undefined);
249
+ if (bad.length === 0) return { kind: "passed", detail };
250
+ return {
251
+ kind: "failed",
252
+ detail,
253
+ output: bad.flatMap((r) => [
254
+ ...(r.counts === undefined ? [`${r.name}: bun test ended with ${r.code} and no summary`] : []),
255
+ ...head(failureLines(r.text), 40).map((l) => `${r.name}: ${l}`),
256
+ ]),
257
+ };
258
+ }
259
+
260
+ /** The summary the loop prints: one line for what it looked at, one for each stage, and what failed under it. */
261
+ export function summaryLines(
262
+ look: Look,
263
+ what: { readonly why: string; readonly libs: readonly string[] },
264
+ stages: readonly { readonly name: string; readonly outcome: Outcome }[],
265
+ notes: readonly string[],
266
+ took: string,
267
+ ): readonly string[] {
268
+ const out: string[] = [];
269
+ out.push(`${paint("accent", "dev:check", look)} ${what.why}`);
270
+ for (const n of notes) out.push(` ${label("hint", n, look)}`);
271
+ if (what.libs.length === 0) out.push(` ${label("skipped", "nothing is affected: no library reads what changed", look)}`);
272
+ else out.push(` ${paint("dim", "affected", look)} ${plural(what.libs.length, "library", "libraries")}: ${what.libs.join(", ")}`);
273
+ for (const s of stages) {
274
+ const o = s.outcome;
275
+ switch (o.kind) {
276
+ case "passed":
277
+ out.push(` ${label("done", `${s.name.padEnd(6)} ${o.detail}`, look)}`);
278
+ break;
279
+ case "skipped":
280
+ out.push(` ${label("skipped", `${s.name.padEnd(6)} ${o.detail}`, look)}`);
281
+ break;
282
+ case "failed":
283
+ out.push(` ${label("failed", `${s.name.padEnd(6)} ${o.detail}`, look)}`, ...o.output.map((l) => ` ${l}`));
284
+ break;
285
+ default:
286
+ return absurd(o);
287
+ }
288
+ }
289
+ if (stages.length === 0) return out;
290
+ const failed = stages.some((s) => s.outcome.kind === "failed");
291
+ out.push(` ${failed ? label("failed", `not ready to push (${took})`, look) : label("done", `ready to push (${took})`, look)}`);
292
+ return out;
293
+ }
294
+
295
+ const OPTIONS = {
296
+ base: value({ help: "The revision to compare with (origin/main, else main, else HEAD).", valueName: "REF" }),
297
+ files: many({ help: "A file that changed (from the repository's root); the libraries it affects. Repeat or separate with commas.", valueName: "FILE" }),
298
+ only: many({ help: "A library, and what depends on it, whatever changed. Repeat or separate with commas.", valueName: "NAME" }),
299
+ all: flag({ help: "Every library." }),
300
+ list: flag({ help: "Say what is affected and run nothing." }),
301
+ types: flag({ help: "Type-check the libraries (on by default).", negatable: true, default: true }),
302
+ tests: flag({ help: "Run their tests (on by default).", negatable: true, default: true }),
303
+ license: flag({ help: "Check the license files of the repository (on by default).", negatable: true, default: true }),
304
+ bail: flag({ help: "Stop the tests at the first one that fails." }),
305
+ repo: value({ help: "The repository (the working folder, or the one above it that has commons/, by default).", valueName: "DIR" }),
306
+ };
307
+
308
+ const commas = (xs: readonly string[]): readonly string[] =>
309
+ xs
310
+ .flatMap((x) => x.split(","))
311
+ .map((x) => x.trim())
312
+ .filter((x) => x !== "");
313
+
314
+ /** The root of the repository that holds `from`: the nearest folder above it that has `commons/libraries/library.ts`. */
315
+ export function repoRootOf(from: string): string | undefined {
316
+ for (let d = resolve(from); ; d = dirname(d)) {
317
+ if (existsSync(join(d, "commons", "libraries", "library.ts"))) return d;
318
+ if (dirname(d) === d) return undefined;
319
+ }
320
+ }
321
+
322
+ /** The command line. Returns the exit status: 0 where what is affected passed, 1 where a stage failed, 2 for a command line that does not fit. */
323
+ export async function main(argv: readonly string[]): Promise<number> {
324
+ const parsed = parseArgs(argv, OPTIONS);
325
+ if (parsed.kind === "err") {
326
+ stdio.stderr.writeSync(`${formatUsageError(parsed.error, "dev:check")}\n`);
327
+ return 2;
328
+ }
329
+ if (parsed.value.kind === "help") {
330
+ stdio.stdout.writeSync(`${helpText("dev:check", "Type-check and test the libraries a change affects, and those that depend on them.", OPTIONS)}\n`);
331
+ return 0;
332
+ }
333
+ const o = parsed.value.options;
334
+ const repo = o.repo === undefined ? repoRootOf(process.cwd()) : resolve(o.repo);
335
+ if (repo === undefined) {
336
+ stdio.stderr.writeSync("dev:check: no repository with commons/libraries here or above; give --repo DIR\n");
337
+ return 2;
338
+ }
339
+ const look = currentLook("stdout");
340
+ const t0 = performance.now();
341
+ const files = commas(o.files ?? []);
342
+ const only = commas(o.only ?? []);
343
+ const scope: Scope = o.all
344
+ ? { kind: "all" }
345
+ : files.length > 0
346
+ ? { kind: "files", files }
347
+ : only.length > 0
348
+ ? { kind: "only", names: only }
349
+ : { kind: "since", base: o.base ?? (await defaultBase(repo)) };
350
+ const found = await affectedOf(repo, scope);
351
+ if (found.kind === "err") {
352
+ stdio.stderr.writeSync(`dev:check: ${found.error}\n`);
353
+ return 2;
354
+ }
355
+ const { libs, why } = found.value;
356
+ const names = libs.map((l) => l.name);
357
+ const stages: { readonly name: string; readonly outcome: Outcome }[] = [];
358
+ let notes: readonly string[] = [];
359
+ if (libs.length > 0 && !o.list) {
360
+ const ready = await prepare(repo, libs);
361
+ if (ready.kind === "err") {
362
+ stdio.stderr.writeSync(`dev:check: ${ready.error}\n`);
363
+ return 1;
364
+ }
365
+ notes = ready.value;
366
+ const cpus = Math.max(2, globalThis.navigator?.hardwareConcurrency ?? 4);
367
+ const width = Math.min(8, cpus);
368
+ const [types, tests] = await Promise.all([
369
+ o.types ? typeCheck(repo, libs, width) : Promise.resolve<Outcome>({ kind: "skipped", detail: "--no-types" }),
370
+ o.tests ? runTests(repo, libs, cpus, o.bail) : Promise.resolve<Outcome>({ kind: "skipped", detail: "--no-tests" }),
371
+ ]);
372
+ stages.push({ name: "types", outcome: types }, { name: "tests", outcome: tests });
373
+ }
374
+ if (!o.list && o.license) stages.push({ name: "license", outcome: await licenseStage(repo) });
375
+ for (const l of summaryLines(look, { why, libs: names }, stages, notes, seconds(t0))) stdio.stdout.writeSync(`${l}\n`);
376
+ return stages.some((s) => s.outcome.kind === "failed") ? 1 : 0;
377
+ }
378
+
379
+ if (import.meta.main) process.exitCode = await main(process.argv.slice(2));