@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.
- package/dist/affected.d.ts +15 -2
- package/dist/affected.js +51 -20
- package/dist/dev.d.ts +81 -0
- package/dist/dev.js +347 -0
- package/dist/family.d.ts +58 -0
- package/dist/family.js +124 -0
- package/dist/generate-ontology.d.ts +2 -0
- package/dist/generate-ontology.js +33 -1
- package/dist/generate-workflows.js +2 -10
- package/dist/libraries.d.ts +8 -0
- package/dist/libraries.js +30 -4
- package/dist/link.d.ts +12 -0
- package/dist/link.js +98 -0
- package/dist/oscal-register.d.ts +2 -1
- package/dist/oscal-register.js +112 -88
- package/dist/pack-library.js +6 -1
- package/dist/plan.d.ts +28 -0
- package/dist/plan.js +135 -0
- package/dist/releasing.d.ts +176 -0
- package/dist/releasing.js +680 -0
- package/dist/versions.js +4 -7
- package/dist/workflows/definitions.d.ts +33 -30
- package/dist/workflows/definitions.js +200 -272
- package/dist/workflows/model.d.ts +15 -3
- package/dist/workflows/render.js +10 -2
- package/package.json +24 -4
- package/src/affected.ts +56 -17
- package/src/dev.ts +368 -0
- package/src/family.ts +143 -0
- package/src/generate-ontology.ts +34 -1
- package/src/generate-workflows.ts +3 -11
- package/src/libraries.ts +35 -3
- package/src/link.ts +97 -0
- package/src/oscal-register.ts +139 -117
- package/src/pack-library.ts +6 -1
- package/src/plan.ts +143 -0
- package/src/releasing.ts +735 -0
- package/src/versions.ts +3 -7
- package/src/workflows/definitions.ts +260 -387
- package/src/workflows/model.ts +11 -3
- package/src/workflows/render.ts +10 -2
package/src/oscal-register.ts
CHANGED
|
@@ -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
|
|
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
|
|
94
|
+
const NO_CLOCK = "1970-01-01T00:00:00.000Z";
|
|
112
95
|
|
|
113
|
-
/**
|
|
114
|
-
|
|
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
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
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
|
|
228
|
-
async function
|
|
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(
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
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
|
-
|
|
258
|
-
status,
|
|
259
|
-
outcome:
|
|
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
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
const
|
|
285
|
-
const
|
|
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
|
-
|
|
258
|
+
"last-modified": NO_CLOCK,
|
|
259
|
+
version,
|
|
260
|
+
"oscal-version": OSCAL_VERSION,
|
|
292
261
|
});
|
|
293
|
-
const
|
|
294
|
-
|
|
295
|
-
{
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
description: `${
|
|
299
|
-
|
|
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
|
|
304
|
-
const inner = definition["component-definition"];
|
|
305
|
-
const withMechanism: OscalComponentDefinition = {
|
|
271
|
+
const componentDefinition = {
|
|
306
272
|
"component-definition": {
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
:
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
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
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
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
|
-
|
|
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. */
|
package/src/pack-library.ts
CHANGED
|
@@ -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));
|