@intellectual-frontiers/libraries 0.1.1 → 0.4.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.
@@ -7,6 +7,10 @@ export type Inputs = {
7
7
  readonly dependsOn: readonly string[];
8
8
  /** Every file of another folder that it reads, from the repository's root, in order. */
9
9
  readonly files: readonly string[];
10
+ /** The libraries whose package its sources import by name: what its types and its tests read, which its scripts do not add. */
11
+ readonly imports: readonly string[];
12
+ /** The paths its types and its tests read: its folder and what its imports reach (no tool its scripts run, no workflow). */
13
+ readonly codePaths: readonly string[];
10
14
  };
11
15
  /** The folders whose change is every library's change: the tools that check a library and the action that installs Bun. */
12
16
  export declare const SHARED: readonly ["commons/tools/**", ".github/actions/**"];
@@ -14,11 +18,20 @@ export declare const SHARED: readonly ["commons/tools/**", ".github/actions/**"]
14
18
  export declare function inputsOf(repo: string, name: string): Inputs;
15
19
  /** 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. */
16
20
  export declare function matches(paths: readonly string[], file: string): boolean;
21
+ /** Every library of the repository, with its folder. */
22
+ export declare function everyLibrary(repo: string): readonly (Library & {
23
+ readonly folder: string;
24
+ })[];
25
+ /**
26
+ * 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
27
+ * packages its sources import, which is what the development loop runs).
28
+ */
29
+ export type Reach = "verify" | "code";
17
30
  /** 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. */
18
- export declare function affectedBy(repo: string, changed: readonly string[]): readonly (Library & {
31
+ export declare function affectedBy(repo: string, changed: readonly string[], reach?: Reach): readonly (Library & {
19
32
  readonly folder: string;
20
33
  })[];
21
- /** The files changed since the merge base of `base` and the head, tracked files of the working tree included; undefined where Git cannot say. */
34
+ /** 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. */
22
35
  export declare function changedSince(repo: string, base: string): Promise<readonly string[] | undefined>;
23
36
  /** The matrix a workflow reads: `{"include":[{"name","folder","verify"}]}`. */
24
37
  export declare function matrixOf(libs: readonly (Library & {
package/dist/affected.js CHANGED
@@ -134,8 +134,11 @@ export function inputsOf(repo, name) {
134
134
  const sources = sourcesUnder(root, folder);
135
135
  const texts = sources.map((f) => ({ f, text: readTextFileSync(join(root, f)) }));
136
136
  const entries = new Set();
137
+ const codeEntries = new Set();
137
138
  const whole = new Set();
139
+ const codeWhole = new Set();
138
140
  const dependsOn = new Set();
141
+ const imports = new Set();
139
142
  // a dependency by path: its folder, what the library's sources import from it, and the entries it maps them to
140
143
  for (const [dep, spec] of pkg?.dependencies ?? []) {
141
144
  const m = /^(?:link|file|workspace):(.+)$/.exec(spec);
@@ -146,18 +149,30 @@ export function inputsOf(repo, name) {
146
149
  continue;
147
150
  const depPkg = readPackage(join(root, dir));
148
151
  dependsOn.add(dir.split("/")[1] ?? dir);
149
- const imported = new Set();
150
- for (const { text } of texts)
151
- for (const s of specifiersOf(text))
152
- if (s === dep || s.startsWith(`${dep}/`))
153
- imported.add(s === dep ? "." : `.${s.slice(dep.length)}`);
154
- for (const key of imported) {
155
- const target = depPkg?.exports.get(key);
156
- if (target === undefined)
157
- whole.add(`${dir}/**`);
158
- else
159
- entries.add(posix(join(dir, target)));
160
- }
152
+ const importedBy = (own) => {
153
+ const found = new Set();
154
+ for (const { text } of own)
155
+ for (const s of specifiersOf(text))
156
+ if (s === dep || s.startsWith(`${dep}/`))
157
+ found.add(s === dep ? "." : `.${s.slice(dep.length)}`);
158
+ return found;
159
+ };
160
+ // 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
161
+ const imported = importedBy(texts);
162
+ const ownCode = importedBy(texts.filter((t) => t.f === `${folder}/about.ts` || t.f.startsWith(`${folder}/src/`)));
163
+ if (ownCode.size > 0 && existsSync(join(root, dir, "library.ts")))
164
+ imports.add(dir.split("/")[1] ?? dir);
165
+ for (const [keys, into, all] of [
166
+ [imported, entries, whole],
167
+ [ownCode, codeEntries, codeWhole],
168
+ ])
169
+ for (const key of keys) {
170
+ const target = depPkg?.exports.get(key);
171
+ if (target === undefined)
172
+ all.add(`${dir}/**`);
173
+ else
174
+ into.add(posix(join(dir, target)));
175
+ }
161
176
  }
162
177
  // a path to another folder in a script of the package: `bun ../libraries/src/check.ts`
163
178
  for (const script of pkg?.scripts ?? [])
@@ -167,28 +182,41 @@ export function inputsOf(repo, name) {
167
182
  entries.add(p);
168
183
  }
169
184
  const files = [...closure(root, [...entries])].filter((f) => !f.startsWith(`${folder}/`)).sort();
170
- const paths = [`${folder}/**`, ...new Set([...files.map(folderOf), ...whole, ...SHARED, `.github/workflows/${name}.auto.yml`])].sort();
185
+ const paths = [`${folder}/**`, ...new Set([...files.map(folderOf), ...whole, ...SHARED, ".github/workflows/ci.auto.yml"])].sort();
171
186
  for (const f of files) {
172
187
  const d = f.split("/")[1];
173
188
  if (d !== undefined && d !== name && existsSync(join(root, "commons", d, "library.ts")))
174
189
  dependsOn.add(d);
175
190
  }
176
- return { paths, dependsOn: [...dependsOn].sort(), files };
191
+ const codeFiles = [...closure(root, [...codeEntries])].filter((f) => !f.startsWith(`${folder}/`));
192
+ for (const f of codeFiles) {
193
+ const d = f.split("/")[1];
194
+ if (d !== undefined && d !== name && existsSync(join(root, "commons", d, "library.ts")))
195
+ imports.add(d);
196
+ }
197
+ const codePaths = [`${folder}/**`, ...new Set([...codeFiles.map(folderOf), ...codeWhole])].sort();
198
+ return { paths, dependsOn: [...dependsOn].sort(), files, imports: [...imports].sort(), codePaths };
177
199
  }
178
200
  /** 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. */
179
201
  export function matches(paths, file) {
180
202
  return paths.some((p) => (p.endsWith("/**") ? file.startsWith(p.slice(0, -2)) : p === file));
181
203
  }
204
+ /** Every library of the repository, with its folder. */
205
+ export function everyLibrary(repo) {
206
+ return readLibraries(repo).flatMap((f) => ("library" in f ? [{ ...f.library, folder: `commons/${f.dir}` }] : []));
207
+ }
182
208
  /** 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. */
183
- export function affectedBy(repo, changed) {
209
+ export function affectedBy(repo, changed, reach = "verify") {
184
210
  const root = repo.replace(/[\\/]$/, "");
185
211
  const libs = readLibraries(root).flatMap((f) => ("library" in f ? [f.library] : []));
186
212
  const inputs = new Map(libs.map((l) => [l.name, inputsOf(root, l.name)]));
187
- const hit = new Set(libs.filter((l) => changed.some((c) => matches(inputs.get(l.name)?.paths ?? [], c))).map((l) => l.name));
213
+ const pathsOf = (n) => (reach === "verify" ? inputs.get(n)?.paths : inputs.get(n)?.codePaths) ?? [];
214
+ const depsOf = (n) => (reach === "verify" ? inputs.get(n)?.dependsOn : inputs.get(n)?.imports) ?? [];
215
+ const hit = new Set(libs.filter((l) => changed.some((c) => matches(pathsOf(l.name), c))).map((l) => l.name));
188
216
  for (let grew = true; grew;) {
189
217
  grew = false;
190
218
  for (const l of libs) {
191
- if (!hit.has(l.name) && (inputs.get(l.name)?.dependsOn ?? []).some((d) => hit.has(d))) {
219
+ if (!hit.has(l.name) && depsOf(l.name).some((d) => hit.has(d))) {
192
220
  hit.add(l.name);
193
221
  grew = true;
194
222
  }
@@ -196,7 +224,7 @@ export function affectedBy(repo, changed) {
196
224
  }
197
225
  return libs.filter((l) => hit.has(l.name)).map((l) => ({ ...l, folder: `commons/${l.name}` }));
198
226
  }
199
- /** The files changed since the merge base of `base` and the head, tracked files of the working tree included; undefined where Git cannot say. */
227
+ /** 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. */
200
228
  export async function changedSince(repo, base) {
201
229
  const root = resolve(repo);
202
230
  try {
@@ -204,7 +232,10 @@ export async function changedSince(repo, base) {
204
232
  if (mb.code !== 0)
205
233
  return undefined;
206
234
  const d = await run(["git", "-C", root, "diff", "--name-only", mb.stdout.trim()]);
207
- return d.code === 0 ? d.stdout.split("\n").filter((l) => l !== "") : undefined;
235
+ const fresh = await run(["git", "-C", root, "ls-files", "--others", "--exclude-standard"]);
236
+ if (d.code !== 0 || fresh.code !== 0)
237
+ return undefined;
238
+ return [...new Set([...d.stdout.split("\n"), ...fresh.stdout.split("\n")])].filter((l) => l !== "");
208
239
  }
209
240
  catch {
210
241
  return undefined;
@@ -227,7 +258,7 @@ export async function main(argv) {
227
258
  stdio.stdout.writeSync(`${[...i.paths, ...i.files.map((f) => ` ${f}`)].join("\n")}\n`);
228
259
  return 0;
229
260
  }
230
- const everything = readLibraries(repo).flatMap((f) => ("library" in f ? [{ ...f.library, folder: `commons/${f.dir}` }] : []));
261
+ const everything = everyLibrary(repo);
231
262
  const files = arg("--files");
232
263
  const base = arg("--base");
233
264
  if (argv.includes("--all"))
package/dist/dev.d.ts ADDED
@@ -0,0 +1,81 @@
1
+ import { type Result } from "@intellectual-frontiers/core";
2
+ import { type Look } from "@intellectual-frontiers/system/tty";
3
+ import type { Library } from "./libraries.js";
4
+ /** What the loop is asked about: what changed since a revision, a list of files, named libraries or everything. */
5
+ export type Scope = {
6
+ readonly kind: "since";
7
+ readonly base: string;
8
+ } | {
9
+ readonly kind: "files";
10
+ readonly files: readonly string[];
11
+ } | {
12
+ readonly kind: "only";
13
+ readonly names: readonly string[];
14
+ } | {
15
+ readonly kind: "all";
16
+ };
17
+ /** A library of the repository with its folder, as `affected.ts` gives it. */
18
+ export type Lib = Library & {
19
+ readonly folder: string;
20
+ };
21
+ /** How one stage of the loop ended. */
22
+ export type Outcome = {
23
+ readonly kind: "passed";
24
+ readonly detail: string;
25
+ } | {
26
+ readonly kind: "failed";
27
+ readonly detail: string;
28
+ readonly output: readonly string[];
29
+ } | {
30
+ readonly kind: "skipped";
31
+ readonly detail: string;
32
+ };
33
+ /** The counts of one `bun test` run. */
34
+ export type Counts = {
35
+ readonly pass: number;
36
+ readonly skip: number;
37
+ readonly fail: number;
38
+ readonly files: number;
39
+ };
40
+ /** The counts in the end of what `bun test` printed, or undefined where it printed none. */
41
+ export declare function bunCounts(text: string): Counts | undefined;
42
+ /** The lines of `bun test`'s output that say what failed: the failing tests and the error lines above each, in order. */
43
+ export declare function failureLines(text: string): readonly string[];
44
+ /** The first lines of a compiler's output, so a long one does not bury the summary. */
45
+ export declare function head(lines: readonly string[], n: number): readonly string[];
46
+ /** The packages a library declares that neither are libraries of the repository nor are installed at the root: the ones it must install itself. */
47
+ export declare function ownPackages(pkg: Readonly<Record<string, unknown>>, shared: ReadonlySet<string>): readonly string[];
48
+ /** 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). */
49
+ export declare function linkLibraries(repo: string): Result<number, string>;
50
+ /** The revision a loop compares with where none is given: `origin/main`, else `main`, else `HEAD` (the working tree alone). */
51
+ export declare function defaultBase(repo: string): Promise<string>;
52
+ /** What a scope affects: the libraries and why, or why it cannot be said. */
53
+ export declare function affectedOf(repo: string, scope: Scope): Promise<Result<{
54
+ readonly libs: readonly Lib[];
55
+ readonly why: string;
56
+ }, string>>;
57
+ /** Runs `job` over `items`, at most `width` at a time, and gives the results in the order of the items. */
58
+ export declare function pool<T, R>(items: readonly T[], width: number, job: (item: T) => Promise<R>): Promise<readonly R[]>;
59
+ /** What the loop needs installed: the root's packages, the links, and the packages of a library that has its own. */
60
+ export declare function prepare(repo: string, libs: readonly Lib[]): Promise<Result<readonly string[], string>>;
61
+ /** TypeScript on the libraries, several at a time. */
62
+ export declare function typeCheck(repo: string, libs: readonly Lib[], width: number): Promise<Outcome>;
63
+ /** The sum of counts. */
64
+ export declare const addCounts: (a: Counts, b: Counts) => Counts;
65
+ /**
66
+ * 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
67
+ * 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.
68
+ */
69
+ export declare function runTests(repo: string, libs: readonly Lib[], width: number, bail: boolean): Promise<Outcome>;
70
+ /** The summary the loop prints: one line for what it looked at, one for each stage, and what failed under it. */
71
+ export declare function summaryLines(look: Look, what: {
72
+ readonly why: string;
73
+ readonly libs: readonly string[];
74
+ }, stages: readonly {
75
+ readonly name: string;
76
+ readonly outcome: Outcome;
77
+ }[], notes: readonly string[], took: string): readonly string[];
78
+ /** The root of the repository that holds `from`: the nearest folder above it that has `commons/libraries/library.ts`. */
79
+ export declare function repoRootOf(from: string): string | undefined;
80
+ /** 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. */
81
+ export declare function main(argv: readonly string[]): Promise<number>;
package/dist/dev.js ADDED
@@ -0,0 +1,347 @@
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, --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 } 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 } 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.js";
42
+ import { linkAll } from "./link.js";
43
+ /** The counts in the end of what `bun test` printed, or undefined where it printed none. */
44
+ export function bunCounts(text) {
45
+ const n = (word) => Number(new RegExp(`^\\s*(\\d+) ${word}\\s*$`, "m").exec(text)?.[1] ?? 0);
46
+ const ran = /^Ran \d+ tests? across (\d+) files?/m.exec(text);
47
+ return ran?.[1] === undefined ? undefined : { pass: n("pass"), skip: n("skip"), fail: n("fail"), files: Number(ran[1]) };
48
+ }
49
+ /** The lines of `bun test`'s output that say what failed: the failing tests and the error lines above each, in order. */
50
+ export function failureLines(text) {
51
+ const lines = text.split("\n");
52
+ const out = [];
53
+ lines.forEach((l, i) => {
54
+ if (!/^\(fail\)/.test(l) && !/^error:/.test(l))
55
+ return;
56
+ if (/^\(fail\)/.test(l))
57
+ out.push(l);
58
+ else {
59
+ out.push(l);
60
+ for (const next of lines.slice(i + 1, i + 6))
61
+ if (/^\s+at |^\s+\d+ \|/.test(next))
62
+ out.push(next);
63
+ }
64
+ });
65
+ return out.length > 0 ? out : lines.slice(-30);
66
+ }
67
+ /** The first lines of a compiler's output, so a long one does not bury the summary. */
68
+ export function head(lines, n) {
69
+ return lines.length <= n ? lines : [...lines.slice(0, n), `... and ${lines.length - n} more`];
70
+ }
71
+ /** The packages a library declares that neither are libraries of the repository nor are installed at the root: the ones it must install itself. */
72
+ export function ownPackages(pkg, shared) {
73
+ const out = new Set();
74
+ for (const field of ["dependencies", "devDependencies"]) {
75
+ const o = pkg[field];
76
+ if (typeof o !== "object" || o === null)
77
+ continue;
78
+ for (const [k, v] of Object.entries(o))
79
+ if (typeof v === "string" && !v.startsWith("link:") && !shared.has(k))
80
+ out.add(k);
81
+ }
82
+ return [...out].sort();
83
+ }
84
+ const readJson = (file) => {
85
+ try {
86
+ const x = JSON.parse(readTextFileSync(file));
87
+ return typeof x === "object" && x !== null && !Array.isArray(x) ? Object.fromEntries(Object.entries(x)) : {};
88
+ }
89
+ catch {
90
+ return {};
91
+ }
92
+ };
93
+ /** 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). */
94
+ export function linkLibraries(repo) {
95
+ const r = linkAll(repo);
96
+ return "problem" in r ? err(r.problem) : ok(r.made);
97
+ }
98
+ /** The revision a loop compares with where none is given: `origin/main`, else `main`, else `HEAD` (the working tree alone). */
99
+ export async function defaultBase(repo) {
100
+ for (const ref of ["origin/main", "main"]) {
101
+ const r = await run(["git", "-C", repo, "rev-parse", "--verify", "--quiet", ref]);
102
+ if (r.code === 0)
103
+ return ref;
104
+ }
105
+ return "HEAD";
106
+ }
107
+ /** What a scope affects: the libraries and why, or why it cannot be said. */
108
+ export async function affectedOf(repo, scope) {
109
+ switch (scope.kind) {
110
+ case "all":
111
+ return ok({ libs: everyLibrary(repo), why: "every library" });
112
+ case "files":
113
+ return ok({ libs: affectedBy(repo, scope.files, "code"), why: `${scope.files.length} named files` });
114
+ case "only": {
115
+ const all = everyLibrary(repo);
116
+ const unknown = scope.names.filter((n) => !all.some((l) => l.name === n));
117
+ if (unknown.length > 0)
118
+ return err(`no library named ${unknown.join(", ")} (they are: ${all.map((l) => l.name).join(", ")})`);
119
+ const roots = all.filter((l) => scope.names.includes(l.name)).flatMap((l) => `commons/${l.name}/library.ts`);
120
+ return ok({ libs: affectedBy(repo, roots, "code"), why: `${scope.names.join(", ")} and what imports them` });
121
+ }
122
+ case "since": {
123
+ const changed = await changedSince(repo, scope.base);
124
+ if (changed === undefined)
125
+ return ok({ libs: everyLibrary(repo), why: `git cannot say what changed since ${scope.base}` });
126
+ return ok({ libs: affectedBy(repo, changed, "code"), why: `${changed.length} files changed since ${scope.base}` });
127
+ }
128
+ default:
129
+ return absurd(scope);
130
+ }
131
+ }
132
+ /** The compiler's program for this system: the one the root installs. */
133
+ const tscOf = (repo) => join(repo, "node_modules", ".bin", build.os === "windows" ? "tsc.cmd" : "tsc");
134
+ /** Runs `job` over `items`, at most `width` at a time, and gives the results in the order of the items. */
135
+ export async function pool(items, width, job) {
136
+ const out = [];
137
+ const results = new Map();
138
+ let next = 0;
139
+ const worker = async () => {
140
+ for (let i = next++; i < items.length; i = next++) {
141
+ const item = items[i];
142
+ if (item !== undefined)
143
+ results.set(i, await job(item));
144
+ }
145
+ };
146
+ await Promise.all(Array.from({ length: Math.max(1, Math.min(width, items.length)) }, worker));
147
+ for (let i = 0; i < items.length; i++) {
148
+ const r = results.get(i);
149
+ if (r !== undefined)
150
+ out.push(r);
151
+ }
152
+ return out;
153
+ }
154
+ const seconds = (since) => `${((performance.now() - since) / 1000).toFixed(1)}s`;
155
+ const plural = (n, one, many_ = `${one}s`) => `${n} ${n === 1 ? one : many_}`;
156
+ /** What the loop needs installed: the root's packages, the links, and the packages of a library that has its own. */
157
+ export async function prepare(repo, libs) {
158
+ const said = [];
159
+ if (!existsSync(tscOf(repo))) {
160
+ const r = await run(["bun", "install", "--frozen-lockfile"], { cwd: repo });
161
+ if (r.code !== 0)
162
+ return err(`bun install at the root failed:\n${r.stderr.trim()}`);
163
+ said.push("installed the packages of the root");
164
+ }
165
+ const linked = linkLibraries(repo);
166
+ if (linked.kind === "err")
167
+ return linked;
168
+ if (linked.value > 0)
169
+ said.push(`linked ${plural(linked.value, "package")} under commons/node_modules`);
170
+ const rootPkg = readJson(join(repo, "package.json"));
171
+ const shared = new Set(["dependencies", "devDependencies"].flatMap((f) => {
172
+ const o = rootPkg[f];
173
+ return typeof o === "object" && o !== null ? Object.keys(o) : [];
174
+ }));
175
+ for (const l of libs) {
176
+ const own = ownPackages(readJson(join(repo, l.folder, "package.json")), shared);
177
+ if (own.length === 0 || existsSync(join(repo, l.folder, "node_modules")))
178
+ continue;
179
+ const r = await run(["bun", "install", "--frozen-lockfile"], { cwd: join(repo, l.folder) });
180
+ if (r.code !== 0)
181
+ return err(`bun install in ${l.folder} failed:\n${r.stderr.trim()}`);
182
+ said.push(`installed ${l.folder}'s own packages (${own.join(", ")})`);
183
+ }
184
+ return ok(said);
185
+ }
186
+ /** TypeScript on the libraries, several at a time. */
187
+ export async function typeCheck(repo, libs, width) {
188
+ const t0 = performance.now();
189
+ const checked = libs.filter((l) => existsSync(join(repo, l.folder, "tsconfig.json")));
190
+ const results = await pool(checked, width, async (l) => {
191
+ const r = await run([tscOf(repo), "-p", "tsconfig.json", "--pretty", "false"], { cwd: join(repo, l.folder) });
192
+ return { name: l.name, code: r.code, lines: `${r.stdout}${r.stderr}`.split("\n").filter((x) => x.trim() !== "") };
193
+ });
194
+ const bad = results.filter((r) => r.code !== 0);
195
+ if (bad.length === 0)
196
+ return { kind: "passed", detail: `${plural(checked.length, "library", "libraries")} in ${seconds(t0)}` };
197
+ return {
198
+ kind: "failed",
199
+ detail: `${bad.map((b) => b.name).join(", ")} in ${seconds(t0)}`,
200
+ output: bad.flatMap((b) => head(b.lines, 25).map((x) => `${b.name}: ${x}`)),
201
+ };
202
+ }
203
+ /** The sum of counts. */
204
+ export const addCounts = (a, b) => ({ pass: a.pass + b.pass, skip: a.skip + b.skip, fail: a.fail + b.fail, files: a.files + b.files });
205
+ /**
206
+ * 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
207
+ * 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.
208
+ */
209
+ export async function runTests(repo, libs, width, bail) {
210
+ const t0 = performance.now();
211
+ const files = (l) => readDirSync(join(repo, l.folder, "suite")).length;
212
+ const suites = libs.filter((l) => existsSync(join(repo, l.folder, "suite"))).sort((a, b) => files(b) - files(a));
213
+ if (suites.length === 0)
214
+ return { kind: "skipped", detail: "no library of these has a suite" };
215
+ const results = await pool(suites, width, async (l) => {
216
+ const r = await run(["bun", "test", ...(bail ? ["--bail"] : []), "suite/"], { cwd: join(repo, l.folder), env: { CI: "" } });
217
+ const text = `${r.stdout}\n${r.stderr}`;
218
+ return { name: l.name, code: r.code, counts: bunCounts(text), text };
219
+ });
220
+ const total = results.reduce((sum, r) => (r.counts === undefined ? sum : addCounts(sum, r.counts)), { pass: 0, skip: 0, fail: 0, files: 0 });
221
+ 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)}`;
222
+ const bad = results.filter((r) => r.code !== 0 || r.counts === undefined);
223
+ if (bad.length === 0)
224
+ return { kind: "passed", detail };
225
+ return {
226
+ kind: "failed",
227
+ detail,
228
+ output: bad.flatMap((r) => [
229
+ ...(r.counts === undefined ? [`${r.name}: bun test ended with ${r.code} and no summary`] : []),
230
+ ...head(failureLines(r.text), 40).map((l) => `${r.name}: ${l}`),
231
+ ]),
232
+ };
233
+ }
234
+ /** The summary the loop prints: one line for what it looked at, one for each stage, and what failed under it. */
235
+ export function summaryLines(look, what, stages, notes, took) {
236
+ const out = [];
237
+ out.push(`${paint("accent", "dev:check", look)} ${what.why}`);
238
+ for (const n of notes)
239
+ out.push(` ${label("hint", n, look)}`);
240
+ if (what.libs.length === 0)
241
+ out.push(` ${label("skipped", "nothing is affected: no library reads what changed", look)}`);
242
+ else
243
+ out.push(` ${paint("dim", "affected", look)} ${plural(what.libs.length, "library", "libraries")}: ${what.libs.join(", ")}`);
244
+ for (const s of stages) {
245
+ const o = s.outcome;
246
+ switch (o.kind) {
247
+ case "passed":
248
+ out.push(` ${label("done", `${s.name.padEnd(6)} ${o.detail}`, look)}`);
249
+ break;
250
+ case "skipped":
251
+ out.push(` ${label("skipped", `${s.name.padEnd(6)} ${o.detail}`, look)}`);
252
+ break;
253
+ case "failed":
254
+ out.push(` ${label("failed", `${s.name.padEnd(6)} ${o.detail}`, look)}`, ...o.output.map((l) => ` ${l}`));
255
+ break;
256
+ default:
257
+ return absurd(o);
258
+ }
259
+ }
260
+ if (stages.length === 0)
261
+ return out;
262
+ const failed = stages.some((s) => s.outcome.kind === "failed");
263
+ out.push(` ${failed ? label("failed", `not ready to push (${took})`, look) : label("done", `ready to push (${took})`, look)}`);
264
+ return out;
265
+ }
266
+ const OPTIONS = {
267
+ base: value({ help: "The revision to compare with (origin/main, else main, else HEAD).", valueName: "REF" }),
268
+ files: many({ help: "A file that changed (from the repository's root); the libraries it affects. Repeat or separate with commas.", valueName: "FILE" }),
269
+ only: many({ help: "A library, and what depends on it, whatever changed. Repeat or separate with commas.", valueName: "NAME" }),
270
+ all: flag({ help: "Every library." }),
271
+ list: flag({ help: "Say what is affected and run nothing." }),
272
+ types: flag({ help: "Type-check the libraries (on by default).", negatable: true, default: true }),
273
+ tests: flag({ help: "Run their tests (on by default).", negatable: true, default: true }),
274
+ bail: flag({ help: "Stop the tests at the first one that fails." }),
275
+ repo: value({ help: "The repository (the working folder, or the one above it that has commons/, by default).", valueName: "DIR" }),
276
+ };
277
+ const commas = (xs) => xs
278
+ .flatMap((x) => x.split(","))
279
+ .map((x) => x.trim())
280
+ .filter((x) => x !== "");
281
+ /** The root of the repository that holds `from`: the nearest folder above it that has `commons/libraries/library.ts`. */
282
+ export function repoRootOf(from) {
283
+ for (let d = resolve(from);; d = dirname(d)) {
284
+ if (existsSync(join(d, "commons", "libraries", "library.ts")))
285
+ return d;
286
+ if (dirname(d) === d)
287
+ return undefined;
288
+ }
289
+ }
290
+ /** 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. */
291
+ export async function main(argv) {
292
+ const parsed = parseArgs(argv, OPTIONS);
293
+ if (parsed.kind === "err") {
294
+ stdio.stderr.writeSync(`${formatUsageError(parsed.error, "dev:check")}\n`);
295
+ return 2;
296
+ }
297
+ if (parsed.value.kind === "help") {
298
+ stdio.stdout.writeSync(`${helpText("dev:check", "Type-check and test the libraries a change affects, and those that depend on them.", OPTIONS)}\n`);
299
+ return 0;
300
+ }
301
+ const o = parsed.value.options;
302
+ const repo = o.repo === undefined ? repoRootOf(process.cwd()) : resolve(o.repo);
303
+ if (repo === undefined) {
304
+ stdio.stderr.writeSync("dev:check: no repository with commons/libraries here or above; give --repo DIR\n");
305
+ return 2;
306
+ }
307
+ const look = currentLook("stdout");
308
+ const t0 = performance.now();
309
+ const files = commas(o.files ?? []);
310
+ const only = commas(o.only ?? []);
311
+ const scope = o.all
312
+ ? { kind: "all" }
313
+ : files.length > 0
314
+ ? { kind: "files", files }
315
+ : only.length > 0
316
+ ? { kind: "only", names: only }
317
+ : { kind: "since", base: o.base ?? (await defaultBase(repo)) };
318
+ const found = await affectedOf(repo, scope);
319
+ if (found.kind === "err") {
320
+ stdio.stderr.writeSync(`dev:check: ${found.error}\n`);
321
+ return 2;
322
+ }
323
+ const { libs, why } = found.value;
324
+ const names = libs.map((l) => l.name);
325
+ const stages = [];
326
+ let notes = [];
327
+ if (libs.length > 0 && !o.list) {
328
+ const ready = await prepare(repo, libs);
329
+ if (ready.kind === "err") {
330
+ stdio.stderr.writeSync(`dev:check: ${ready.error}\n`);
331
+ return 1;
332
+ }
333
+ notes = ready.value;
334
+ const cpus = Math.max(2, globalThis.navigator?.hardwareConcurrency ?? 4);
335
+ const width = Math.min(8, cpus);
336
+ const [types, tests] = await Promise.all([
337
+ o.types ? typeCheck(repo, libs, width) : Promise.resolve({ kind: "skipped", detail: "--no-types" }),
338
+ o.tests ? runTests(repo, libs, cpus, o.bail) : Promise.resolve({ kind: "skipped", detail: "--no-tests" }),
339
+ ]);
340
+ stages.push({ name: "types", outcome: types }, { name: "tests", outcome: tests });
341
+ }
342
+ for (const l of summaryLines(look, { why, libs: names }, stages, notes, seconds(t0)))
343
+ stdio.stdout.writeSync(`${l}\n`);
344
+ return stages.some((s) => s.outcome.kind === "failed") ? 1 : 0;
345
+ }
346
+ if (import.meta.main)
347
+ process.exitCode = await main(process.argv.slice(2));
@@ -0,0 +1,58 @@
1
+ /**
2
+ * The families of the libraries of commons and the names held for them (commons 0027-commons-libraries FR-023, FR-024; commons 0033-kanon FR-021, FR-024): what the `family` field of a manifest
3
+ * says, the reservations (names no library may take unless it is of the family they are held for), and the findings of the two sides of a family held together, the host's table and each member's
4
+ * manifest.
5
+ *
6
+ * @remarks
7
+ * Pure: it takes the libraries as data and returns one sentence for each finding. A library names its host and its role (`host`, `dialect` or `plugin`); the host's `kanon` table says what its
8
+ * dialects and plugins are and how their packages are named (`@intellectual-frontiers/kanon`: `family`, `instances`, `plugins`), so the name of a member is checked against the host's rule and
9
+ * never against a rule written here. A reservation is data: an exact name or a prefix, and the host that may hold it. It reserves a name without a folder, so that no empty library is created to hold one.
10
+ *
11
+ * Spec: 0001-libraries FR-016
12
+ *
13
+ * @module
14
+ */
15
+ import { type Result } from "@intellectual-frontiers/core";
16
+ import { type Table } from "@intellectual-frontiers/kanon";
17
+ /** The roles a library has in a family: a closed union. */
18
+ export declare const ROLES: readonly ["host", "dialect", "plugin"];
19
+ /** The role of a library in a family. */
20
+ export type Role = (typeof ROLES)[number];
21
+ /** What a manifest says of its family: the host's library name and its own role. */
22
+ export type LibraryFamily = {
23
+ readonly host: string;
24
+ readonly role: Role;
25
+ };
26
+ /** How a reservation holds names: one exact name, or every name that begins with a prefix. */
27
+ export type Match = {
28
+ readonly kind: "exact";
29
+ readonly name: string;
30
+ } | {
31
+ readonly kind: "prefix";
32
+ readonly prefix: string;
33
+ };
34
+ /** A held name: what it matches, the host whose family may use it and why it is held. */
35
+ export type Reservation = {
36
+ readonly match: Match;
37
+ readonly host: string;
38
+ readonly reason: string;
39
+ };
40
+ /** The names held, as data: the check reads them and no folder holds them. */
41
+ export declare const RESERVED: readonly Reservation[];
42
+ /** Whether a library name is one a match holds. */
43
+ export declare function matches(match: Match, name: string): boolean;
44
+ /** The family field of a manifest, from what it says: the host's name and the role, or why it is not one. */
45
+ export declare function decodeFamily(input: {
46
+ readonly host: string;
47
+ readonly role: Role;
48
+ }): Result<LibraryFamily, string>;
49
+ /** What the check reads of a library: its name, its family and its table. */
50
+ export type Entry = {
51
+ readonly name: string;
52
+ readonly family?: LibraryFamily;
53
+ readonly kanon?: Table;
54
+ };
55
+ /** The findings of the names held: a library whose name a reservation holds and that is not of the family the name is held for. */
56
+ export declare function reservationFindings(libraries: readonly Entry[], reserved?: readonly Reservation[]): readonly string[];
57
+ /** The findings of a family held together: each member's name against the host's rule, each declared member registered, and each registered member declared (0033-kanon FR-021). */
58
+ export declare function familyFindings(libraries: readonly Entry[]): readonly string[];