@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.
@@ -11,7 +11,7 @@
11
11
  * --label TEXT the name the documents give the folder (default `Intellectual Frontiers commons`)
12
12
  *
13
13
  * @remarks
14
- * The two documents are written by the kernel's OSCAL writers (`kernel/oscal.ts`, OSCAL 1.2.3), so that the same bytes come for the same folder: every `uuid` is a version 5 UUID of a
14
+ * The two documents are written here, as OSCAL 1.2.3, so that the same bytes come for the same folder: every `uuid` is a version 5 UUID of a
15
15
  * stable name, every list is in an order of its own, and no clock is read (`last-modified` is `1970-01-01T00:00:00Z`; the `version` is the first 12 characters of the SHA-256 of the
16
16
  * register's rows). A requirement's control id is `spec-<slug>.<fr>` in lower case. A requirement a test proves has one passing observation for each test file, with the SHA-256 of
17
17
  * the file as evidence; one that is only reviewed is `accepted` (it has no test); one that has no proof, whatever its row says, is a `gap`. What OSCAL does not say, the command that
@@ -39,26 +39,9 @@
39
39
  */
40
40
  import process from "node:process";
41
41
  import { fileURLToPath } from "node:url";
42
- import {
43
- assessmentResults,
44
- componentDefinition,
45
- type OscalAssessmentResults,
46
- type OscalComponentDefinition,
47
- type OscalOptions,
48
- renderOscal,
49
- } from "@intellectual-frontiers/grc/oscal";
50
- import {
51
- type Assessment,
52
- type ControlSummary,
53
- type Finding,
54
- type Instant,
55
- instantOf,
56
- type Status,
57
- type SubjectRef,
58
- } from "@intellectual-frontiers/grc/grc";
59
42
  import { sha256 } from "@intellectual-frontiers/crypto/sha256";
60
43
  import { type Cited, parseSpec, proofsOf, type SourceFile } from "@intellectual-frontiers/mizan/trace";
61
- import { NAMESPACE_URL, uuidV5 } from "@intellectual-frontiers/crypto/uuid";
44
+ import { NAMESPACE_URL, type Uuid, uuidV5, uuidV5Of } from "@intellectual-frontiers/crypto/uuid";
62
45
  import { existsSync, mkdirSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
63
46
  import { stdio } from "@intellectual-frontiers/system";
64
47
  import { readSources } from "@intellectual-frontiers/mizan/host/trace";
@@ -108,12 +91,10 @@ export const RESULTS_FILE = "mizan-register-results.auto.oscal.json";
108
91
  export const RUN = "bun commons/libraries/src/oscal-register.ts";
109
92
 
110
93
  /** The instant the documents give as their `last-modified`: the register reads no clock (0003-mizan FR-022). */
111
- const NO_CLOCK: Instant = instantOf("1970-01-01T00:00:00Z") ?? absurdInstant();
94
+ const NO_CLOCK = "1970-01-01T00:00:00.000Z";
112
95
 
113
- /** Never returns: the epoch is an instant, so `instantOf` has no reason to refuse it. */
114
- function absurdInstant(): never {
115
- throw new Error("1970-01-01T00:00:00Z is an instant");
116
- }
96
+ /** The version of OSCAL the documents are written as. */
97
+ const OSCAL_VERSION = "1.2.3";
117
98
 
118
99
  const REGISTER_IRI = "https://www.intellectualfrontiers.com/ontology/mizan-register";
119
100
  const isMechanism = (x: string): x is Mechanism => x === "check" || x === "gate" || x === "review" || x === "none";
@@ -214,52 +195,43 @@ export function registerRows(input: RegisterInput): readonly RegisterRow[] {
214
195
  });
215
196
  }
216
197
 
217
- function summaryOf(row: RegisterRow, catalog: string): ControlSummary {
218
- return {
219
- id: row.requirement,
220
- title: row.title,
221
- implements: [{ catalog, id: row.controlId }],
222
- severity: "info",
223
- cadence: "on every commit",
224
- };
225
- }
198
+ /** What one observation of the results says. */
199
+ type Observation = {
200
+ readonly row: RegisterRow;
201
+ readonly status: "pass" | "warn" | "gap";
202
+ readonly outcome: "pass" | "accepted" | "gap";
203
+ readonly title: string;
204
+ readonly detail: string;
205
+ readonly evidence?: string;
206
+ readonly waiver?: string;
207
+ };
226
208
 
227
- /** What a requirement's finding says: a passing observation for each test file that proves it, else `accepted` where a person reviewed it, else a `gap`. */
228
- async function findingsOf(row: RegisterRow, control: ControlSummary, tests: ReadonlyMap<string, string>): Promise<readonly Finding[]> {
229
- const subject: SubjectRef = { kind: "specification", id: row.spec };
230
- const base = { control, subject, severity: "info" as const, at: NO_CLOCK };
209
+ /** What a requirement's observations say: a passing observation for each test file that proves it, else `accepted` where a person reviewed it, else a `gap`. */
210
+ async function observationsOf(row: RegisterRow, tests: ReadonlyMap<string, string>): Promise<readonly Observation[]> {
231
211
  if (row.files.length > 0)
232
212
  return Promise.all(
233
- row.files.map(async (file): Promise<Finding> => ({
234
- ...base,
235
- status: "pass",
236
- outcome: "pass",
237
- title: `proved by ${file}`,
238
- detail: `${row.requirement} is named by a proof in ${file}.`,
239
- evidence: [await sha256(tests.get(file) ?? "")],
240
- })),
213
+ row.files.map(
214
+ async (file): Promise<Observation> => ({
215
+ row,
216
+ status: "pass",
217
+ outcome: "pass",
218
+ title: `proved by ${file}`,
219
+ detail: `${row.requirement} is named by a proof in ${file}.`,
220
+ evidence: await sha256(tests.get(file) ?? ""),
221
+ }),
222
+ ),
241
223
  );
242
224
  if (row.mechanism === "review")
243
225
  return [
244
- {
245
- ...base,
246
- status: "warn",
247
- outcome: "accepted",
248
- waiver: row.by,
249
- title: "reviewed by a person",
250
- detail: `${row.requirement} has no test; a person reviews it (${row.by}): ${row.note}`,
251
- evidence: [],
252
- },
226
+ { row, status: "warn", outcome: "accepted", waiver: row.by, title: "reviewed by a person", detail: `${row.requirement} has no test; a person reviews it (${row.by}): ${row.note}` },
253
227
  ];
254
- const status: Status = "gap";
255
228
  return [
256
229
  {
257
- ...base,
258
- status,
259
- outcome: status,
230
+ row,
231
+ status: "gap",
232
+ outcome: "gap",
260
233
  title: "no test proves it",
261
234
  detail: `${row.requirement} is ${row.mechanism === "none" ? "not enforced" : `enforced by ${row.mechanism} (${row.by})`}, and no proof in the tests names it: ${row.note}`,
262
- evidence: [],
263
235
  },
264
236
  ];
265
237
  }
@@ -269,76 +241,126 @@ export type RegisterDocuments = { readonly componentDefinition: string; readonly
269
241
 
270
242
  /**
271
243
  * The register as OSCAL 1.2.3: the component definition and the assessment results, rendered (0003-mizan FR-021, FR-022). Where `register.enforcement` names a file, its text is the register
272
- * and `input.enforcement` is not read (FR-043); the same bytes come for the same register wherever its file is.
244
+ * and `input.enforcement` is not read (FR-043); the same bytes come for the same register wherever its file is. Both are written here, from the rows, and not by a library of exchange formats:
245
+ * the register's own vocabulary (a mechanism, a proof, a waiver) is Mizan's.
273
246
  */
274
247
  export async function registerDocuments(input: RegisterInput, register: RegisterOptions = {}): Promise<RegisterDocuments> {
275
248
  const rows = registerRows(register.enforcement === undefined ? input : { ...input, enforcement: enforcementAt(register.enforcement) });
276
249
  const catalog = "the specifications of its Mizan folder";
277
- const pairs = rows.map((row) => ({ row, control: summaryOf(row, catalog) }));
278
- const controls = pairs.map((p) => p.control);
279
250
  const tests = new Map(input.tests.map((t) => [t.path, t.text]));
280
- const version = (await sha256(JSON.stringify(rows.map((r) => [r.requirement, r.mechanism, r.by, r.note, r.title, r.files])))).slice(
281
- 0,
282
- 12,
283
- );
284
- const namespace = await uuidV5(NAMESPACE_URL, REGISTER_IRI);
285
- const options = (what: string): OscalOptions => ({
286
- namespace,
287
- lastModified: NO_CLOCK,
288
- version,
289
- propNamespace: `${REGISTER_IRI}#`,
251
+ const version = (await sha256(JSON.stringify(rows.map((r) => [r.requirement, r.mechanism, r.by, r.note, r.title, r.files])))).slice(0, 12);
252
+ const namespace: Uuid = await uuidV5(NAMESPACE_URL, REGISTER_IRI);
253
+ const id = (...parts: readonly string[]): Promise<string> => uuidV5Of(namespace, parts);
254
+ const ns = `${REGISTER_IRI}#`;
255
+ const prop = (name: string, value: string): { readonly name: string; readonly ns: string; readonly value: string } => ({ name, ns, value });
256
+ const metadata = (what: string): Record<string, string> => ({
290
257
  title: `Mizan register of ${input.label}: ${what} (generated by ${RUN}; do not edit)`,
291
- controlId: (ref) => ref.id,
258
+ "last-modified": NO_CLOCK,
259
+ version,
260
+ "oscal-version": OSCAL_VERSION,
292
261
  });
293
- const definition = await componentDefinition(
294
- controls,
295
- {
296
- id: input.label,
297
- title: input.label,
298
- description: `${input.label}, whose requirements are written in the specifications of its Mizan folder.`,
299
- type: "software",
300
- },
301
- options("component definition"),
262
+ const catalogId = await id("catalog", input.label);
263
+ const implemented = await Promise.all(
264
+ rows.map(async (row) => ({
265
+ uuid: await id("implemented-requirement", input.label, row.controlId),
266
+ "control-id": row.controlId,
267
+ description: `${row.requirement} (${row.title})`,
268
+ props: [prop("control", row.requirement), prop("mechanism", row.mechanism), prop("proofs", String(row.files.length))],
269
+ })),
302
270
  );
303
- const byControl = new Map(rows.map((r) => [r.controlId, r]));
304
- const inner = definition["component-definition"];
305
- const withMechanism: OscalComponentDefinition = {
271
+ const componentDefinition = {
306
272
  "component-definition": {
307
- ...inner,
308
- components: inner.components.map((c) => ({
309
- ...c,
310
- ...(c["control-implementations"] === undefined
311
- ? {}
312
- : {
313
- "control-implementations": c["control-implementations"].map((ci) => ({
314
- ...ci,
315
- "implemented-requirements": ci["implemented-requirements"].map((ir) => {
316
- const row = byControl.get(ir["control-id"]);
317
- return row === undefined
318
- ? ir
319
- : {
320
- ...ir,
321
- props: [
322
- ...ir.props,
323
- { name: "mechanism", ns: `${REGISTER_IRI}#`, value: row.mechanism },
324
- { name: "proofs", ns: `${REGISTER_IRI}#`, value: String(row.files.length) },
325
- ],
326
- };
327
- }),
328
- })),
329
- }),
330
- })),
273
+ uuid: await id("component-definition", input.label),
274
+ metadata: metadata("component definition"),
275
+ components: [
276
+ {
277
+ uuid: await id("component", input.label),
278
+ type: "software",
279
+ title: input.label,
280
+ description: `${input.label}, whose requirements are written in ${catalog}.`,
281
+ "control-implementations": [
282
+ {
283
+ uuid: await id("control-implementation", input.label),
284
+ source: `#${catalogId}`,
285
+ description: `The controls of ${catalog} that ${input.label} implements.`,
286
+ "implemented-requirements": implemented,
287
+ },
288
+ ],
289
+ },
290
+ ],
291
+ "back-matter": { resources: [{ uuid: catalogId, title: `The controls of ${catalog}` }] },
331
292
  },
332
293
  };
333
- const assessment: Assessment = {
334
- pack: { id: input.label, title: `Mizan register of ${input.label}` },
335
- at: NO_CLOCK,
336
- controls,
337
- subjects: [...new Set(rows.map((r) => r.spec))].sort(byText).map((id) => ({ kind: "specification", id })),
338
- findings: (await Promise.all(pairs.map((p) => findingsOf(p.row, p.control, tests)))).flat(),
294
+ const specs = [...new Set(rows.map((r) => r.spec))].sort(byText);
295
+ const inventory = await Promise.all(
296
+ specs.map(async (spec) => ({
297
+ uuid: await id("inventory-item", input.label, spec),
298
+ description: `specification ${spec}`,
299
+ props: [{ name: "asset-id", value: spec }, prop("subject-kind", "specification")],
300
+ })),
301
+ );
302
+ const inventoryOf = new Map(specs.map((spec, i) => [spec, inventory[i]?.uuid ?? ""]));
303
+ const observed = (await Promise.all(rows.map((row) => observationsOf(row, tests)))).flat();
304
+ const observations = await Promise.all(
305
+ observed.map(async (o, i) => {
306
+ const title = `${o.row.requirement} on specification ${o.row.spec}: ${o.title}`;
307
+ return {
308
+ uuid: await id("observation", input.label, String(i), title),
309
+ title,
310
+ description: o.detail,
311
+ props: [
312
+ prop("control", o.row.requirement),
313
+ prop("outcome", o.outcome),
314
+ prop("status", o.status),
315
+ prop("severity", "info"),
316
+ ...(o.waiver === undefined ? [] : [prop("waiver", o.waiver)]),
317
+ ],
318
+ methods: ["TEST"],
319
+ types: ["finding"],
320
+ subjects: [{ "subject-uuid": inventoryOf.get(o.row.spec) ?? "", type: "inventory-item", title: `specification ${o.row.spec}` }],
321
+ ...(o.evidence === undefined
322
+ ? {}
323
+ : { "relevant-evidence": [{ description: `evidence of SHA-256 ${o.evidence}`, props: [prop("sha256", o.evidence)] }] }),
324
+ collected: NO_CLOCK,
325
+ };
326
+ }),
327
+ );
328
+ const findings = await Promise.all(
329
+ rows.map(async (row) => {
330
+ const own = observed.flatMap((o, i) => (o.row === row ? [{ o, uuid: observations[i]?.uuid ?? "" }] : []));
331
+ const outcome = own.some((x) => x.o.outcome === "gap") ? "gap" : own.some((x) => x.o.outcome === "accepted") ? "accepted" : "pass";
332
+ return {
333
+ uuid: await id("finding", input.label, row.controlId),
334
+ title: row.controlId,
335
+ description: `${row.controlId}: ${outcome}, by ${row.requirement}.`,
336
+ props: [prop("outcome", outcome), prop("control", row.requirement)],
337
+ target: { type: "objective-id", "target-id": row.controlId, status: { state: outcome === "gap" ? "not-satisfied" : "satisfied" } },
338
+ "related-observations": own.map((x) => ({ "observation-uuid": x.uuid })),
339
+ };
340
+ }),
341
+ );
342
+ const plan = await id("assessment-plan", input.label);
343
+ const assessmentResults = {
344
+ "assessment-results": {
345
+ uuid: await id("assessment-results", input.label),
346
+ metadata: metadata("assessment results"),
347
+ "import-ap": { href: `#${plan}` },
348
+ results: [
349
+ {
350
+ uuid: await id("result", input.label),
351
+ title: `Mizan register of ${input.label} as of ${NO_CLOCK}`,
352
+ description: `The findings of Mizan register of ${input.label}, assessed at ${NO_CLOCK}.`,
353
+ start: NO_CLOCK,
354
+ "local-definitions": { "inventory-items": inventory },
355
+ "reviewed-controls": { "control-selections": [{ "include-controls": rows.map((r) => ({ "control-id": r.controlId })) }] },
356
+ observations,
357
+ findings,
358
+ },
359
+ ],
360
+ "back-matter": { resources: [{ uuid: plan, title: `The assessment plan of Mizan register of ${input.label}` }] },
361
+ },
339
362
  };
340
- const results: OscalAssessmentResults = await assessmentResults(assessment, options("assessment results"));
341
- return { componentDefinition: renderOscal(withMechanism), assessmentResults: renderOscal(results) };
363
+ return { componentDefinition: `${JSON.stringify(componentDefinition, null, 2)}\n`, assessmentResults: `${JSON.stringify(assessmentResults, null, 2)}\n` };
342
364
  }
343
365
 
344
366
  /** What the register may be told besides its folder (0003-mizan FR-043): where its `enforcement.tsv` is, where it is not `enforcement.tsv` of the folder. */
@@ -25,7 +25,7 @@
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
27
  import { basename, dirname, join, relative, resolve, toPosix } from "@intellectual-frontiers/system/path";
28
- import { run, which } from "@intellectual-frontiers/system/proc";
28
+ import { env, run, which } from "@intellectual-frontiers/system/proc";
29
29
 
30
30
  /** The scope of the packages of commons. */
31
31
  export const SCOPE = "@intellectual-frontiers";
@@ -514,6 +514,11 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
514
514
 
515
515
  /** The command line of a library's `tools/pack.ts`: pack, print what was found (or the tarball) and the exit status. */
516
516
  export async function main(root: string, argv: readonly string[], options: PackOptions = {}): Promise<number> {
517
+ // 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
518
+ if (argv.includes("--check") && (env.get("IFC_SKIP_PACK") ?? "") !== "") {
519
+ console.log("pack check skipped: the exports of this library did not change in this push (IFC_SKIP_PACK); the release packs it");
520
+ return 0;
521
+ }
517
522
  const r = await packLibrary(root, options);
518
523
  for (const f of r.findings) console.error(f);
519
524
  if (r.tarball === undefined) return 1;
package/src/plan.ts ADDED
@@ -0,0 +1,143 @@
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.ts";
34
+ import { type Cell, cellOf, LIBRARY_CI } from "./workflows/definitions.ts";
35
+
36
+ /** A library as the plan reads it. */
37
+ export type Planned = { readonly name: string; readonly folder: string; readonly verify: string };
38
+
39
+ /** The cells of a job: what `strategy.matrix` reads as `{"include": [...]}`. */
40
+ export type Include = { readonly include: readonly Cell[] };
41
+
42
+ /** What CI runs for a change: the cells on Linux, and the cells on the other systems. */
43
+ export type Plan = { readonly linux: Include; readonly systems: Include };
44
+
45
+ /** 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`. */
46
+ export function planOf(libs: readonly Planned[], packs: ReadonlySet<string> = new Set()): Plan {
47
+ return {
48
+ linux: { include: libs.map((l) => cellOf(l, undefined, packs.has(l.name))) },
49
+ systems: { include: libs.flatMap((l) => (LIBRARY_CI[l.name]?.systems ?? []).map((os) => cellOf(l, os, packs.has(l.name)))) },
50
+ };
51
+ }
52
+
53
+ /** 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. */
54
+ export function exportsLine(packageJson: string): string {
55
+ try {
56
+ const x: unknown = JSON.parse(packageJson);
57
+ const e = typeof x === "object" && x !== null && "exports" in x ? x.exports : undefined;
58
+ const sorted = (v: unknown): unknown =>
59
+ typeof v === "object" && v !== null && !Array.isArray(v)
60
+ ? Object.fromEntries(
61
+ Object.entries(v)
62
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
63
+ .map(([k, n]) => [k, sorted(n)]),
64
+ )
65
+ : v;
66
+ return JSON.stringify(sorted(e ?? null));
67
+ } catch {
68
+ return "unreadable";
69
+ }
70
+ }
71
+
72
+ /**
73
+ * 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.
74
+ */
75
+ export async function packsFor(repo: string, base: string, libs: readonly Planned[]): Promise<ReadonlySet<string>> {
76
+ const all = new Set(libs.map((l) => l.name));
77
+ const mb = await run(["git", "-C", repo, "merge-base", base, "HEAD"]);
78
+ if (mb.code !== 0) return all;
79
+ const packer = await run(["git", "-C", repo, "diff", "--name-only", mb.stdout.trim(), "--", "commons/libraries/src/pack-library.ts"]);
80
+ if (packer.code !== 0 || packer.stdout.trim() !== "") return all;
81
+ const out = new Set<string>();
82
+ for (const l of libs) {
83
+ const before = await run(["git", "-C", repo, "show", `${mb.stdout.trim()}:${l.folder}/package.json`]);
84
+ const now = join(repo, l.folder, "package.json");
85
+ if (before.code !== 0 || !existsSync(now) || exportsLine(before.stdout) !== exportsLine(readTextFileSync(now))) out.add(l.name);
86
+ }
87
+ return out;
88
+ }
89
+
90
+ /** The outputs of a step that a workflow reads: the matrices as one line of JSON each and whether each has a cell. */
91
+ export function outputsOf(p: Plan): string {
92
+ return [
93
+ `has-linux=${p.linux.include.length > 0}`,
94
+ `linux=${JSON.stringify(p.linux)}`,
95
+ `has-systems=${p.systems.include.length > 0}`,
96
+ `systems=${JSON.stringify(p.systems)}`,
97
+ ].join("\n");
98
+ }
99
+
100
+ const OPTIONS = {
101
+ base: value({ help: "The revision the change starts at (the merge base with it is compared with the head).", valueName: "REF" }),
102
+ files: many({ help: "A file that changed (from the repository's root); the libraries it affects. Repeat or separate with commas.", valueName: "FILE" }),
103
+ all: flag({ help: "Every library." }),
104
+ repo: value({ help: "The repository (the working folder by default).", valueName: "DIR", default: "." }),
105
+ githubOutput: value({ help: "Append the outputs to this file, as a step's `$GITHUB_OUTPUT` is read.", valueName: "FILE" }),
106
+ };
107
+
108
+ /** The command line. Returns the exit status: 0, or 2 for a command line that does not fit. */
109
+ export async function main(argv: readonly string[]): Promise<number> {
110
+ const parsed = parseArgs(argv, OPTIONS);
111
+ if (parsed.kind === "err") {
112
+ stdio.stderr.writeSync(`${formatUsageError(parsed.error, "plan")}\n`);
113
+ return 2;
114
+ }
115
+ if (parsed.value.kind === "help") {
116
+ stdio.stdout.writeSync(`${helpText("plan", "The libraries a change affects and the cells CI runs for them.", OPTIONS)}\n`);
117
+ return 0;
118
+ }
119
+ const o = parsed.value.options;
120
+ const files = (o.files ?? []).flatMap((f) => f.split(",")).filter((f) => f !== "");
121
+ let libs: readonly Planned[];
122
+ let packs: ReadonlySet<string> = new Set();
123
+ if (o.all) {
124
+ libs = everyLibrary(o.repo);
125
+ packs = new Set(libs.map((l) => l.name));
126
+ } else if (files.length > 0) libs = affectedBy(o.repo, files);
127
+ else if (o.base !== undefined) {
128
+ const changed = await changedSince(o.repo, o.base);
129
+ if (changed === undefined) stdio.stderr.writeSync(`plan: git cannot say what changed since ${o.base}; every library is planned\n`);
130
+ libs = changed === undefined ? everyLibrary(o.repo) : affectedBy(o.repo, changed);
131
+ packs = changed === undefined ? new Set(libs.map((l) => l.name)) : await packsFor(o.repo, o.base, libs);
132
+ } else {
133
+ stdio.stderr.writeSync("plan: give --base REF, --files a,b or --all\n");
134
+ return 2;
135
+ }
136
+ const plan = planOf(libs, packs);
137
+ if (o.githubOutput === undefined) stdio.stdout.writeSync(`${JSON.stringify(plan)}\n`);
138
+ else writeTextFileSync(o.githubOutput, `${outputsOf(plan)}\n`, { append: true });
139
+ stdio.stderr.writeSync(`plan: ${libs.length} libraries: ${libs.map((l) => l.name).join(", ") || "none"}\n`);
140
+ return 0;
141
+ }
142
+
143
+ if (import.meta.main) process.exitCode = await main(process.argv.slice(2));