@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/dist/oscal-register.js
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,11 +39,9 @@
|
|
|
39
39
|
*/
|
|
40
40
|
import process from "node:process";
|
|
41
41
|
import { fileURLToPath } from "node:url";
|
|
42
|
-
import { assessmentResults, componentDefinition, renderOscal, } from "@intellectual-frontiers/grc/oscal";
|
|
43
|
-
import { instantOf, } from "@intellectual-frontiers/grc/grc";
|
|
44
42
|
import { sha256 } from "@intellectual-frontiers/crypto/sha256";
|
|
45
43
|
import { parseSpec, proofsOf } from "@intellectual-frontiers/mizan/trace";
|
|
46
|
-
import { NAMESPACE_URL, uuidV5 } from "@intellectual-frontiers/crypto/uuid";
|
|
44
|
+
import { NAMESPACE_URL, uuidV5, uuidV5Of } from "@intellectual-frontiers/crypto/uuid";
|
|
47
45
|
import { existsSync, mkdirSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
48
46
|
import { stdio } from "@intellectual-frontiers/system";
|
|
49
47
|
import { readSources } from "@intellectual-frontiers/mizan/host/trace";
|
|
@@ -55,11 +53,9 @@ export const RESULTS_FILE = "mizan-register-results.auto.oscal.json";
|
|
|
55
53
|
/** The command that writes the files again. */
|
|
56
54
|
export const RUN = "bun commons/libraries/src/oscal-register.ts";
|
|
57
55
|
/** The instant the documents give as their `last-modified`: the register reads no clock (0003-mizan FR-022). */
|
|
58
|
-
const NO_CLOCK =
|
|
59
|
-
/**
|
|
60
|
-
|
|
61
|
-
throw new Error("1970-01-01T00:00:00Z is an instant");
|
|
62
|
-
}
|
|
56
|
+
const NO_CLOCK = "1970-01-01T00:00:00.000Z";
|
|
57
|
+
/** The version of OSCAL the documents are written as. */
|
|
58
|
+
const OSCAL_VERSION = "1.2.3";
|
|
63
59
|
const REGISTER_IRI = "https://www.intellectualfrontiers.com/ontology/mizan-register";
|
|
64
60
|
const isMechanism = (x) => x === "check" || x === "gate" || x === "review" || x === "none";
|
|
65
61
|
const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
|
|
@@ -157,117 +153,145 @@ export function registerRows(input) {
|
|
|
157
153
|
});
|
|
158
154
|
});
|
|
159
155
|
}
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
id: row.requirement,
|
|
163
|
-
title: row.title,
|
|
164
|
-
implements: [{ catalog, id: row.controlId }],
|
|
165
|
-
severity: "info",
|
|
166
|
-
cadence: "on every commit",
|
|
167
|
-
};
|
|
168
|
-
}
|
|
169
|
-
/** 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`. */
|
|
170
|
-
async function findingsOf(row, control, tests) {
|
|
171
|
-
const subject = { kind: "specification", id: row.spec };
|
|
172
|
-
const base = { control, subject, severity: "info", at: NO_CLOCK };
|
|
156
|
+
/** 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`. */
|
|
157
|
+
async function observationsOf(row, tests) {
|
|
173
158
|
if (row.files.length > 0)
|
|
174
159
|
return Promise.all(row.files.map(async (file) => ({
|
|
175
|
-
|
|
160
|
+
row,
|
|
176
161
|
status: "pass",
|
|
177
162
|
outcome: "pass",
|
|
178
163
|
title: `proved by ${file}`,
|
|
179
164
|
detail: `${row.requirement} is named by a proof in ${file}.`,
|
|
180
|
-
evidence:
|
|
165
|
+
evidence: await sha256(tests.get(file) ?? ""),
|
|
181
166
|
})));
|
|
182
167
|
if (row.mechanism === "review")
|
|
183
168
|
return [
|
|
184
|
-
{
|
|
185
|
-
...base,
|
|
186
|
-
status: "warn",
|
|
187
|
-
outcome: "accepted",
|
|
188
|
-
waiver: row.by,
|
|
189
|
-
title: "reviewed by a person",
|
|
190
|
-
detail: `${row.requirement} has no test; a person reviews it (${row.by}): ${row.note}`,
|
|
191
|
-
evidence: [],
|
|
192
|
-
},
|
|
169
|
+
{ 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}` },
|
|
193
170
|
];
|
|
194
|
-
const status = "gap";
|
|
195
171
|
return [
|
|
196
172
|
{
|
|
197
|
-
|
|
198
|
-
status,
|
|
199
|
-
outcome:
|
|
173
|
+
row,
|
|
174
|
+
status: "gap",
|
|
175
|
+
outcome: "gap",
|
|
200
176
|
title: "no test proves it",
|
|
201
177
|
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}`,
|
|
202
|
-
evidence: [],
|
|
203
178
|
},
|
|
204
179
|
];
|
|
205
180
|
}
|
|
206
181
|
/**
|
|
207
182
|
* 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
|
|
208
|
-
* and `input.enforcement` is not read (FR-043); the same bytes come for the same register wherever its file is.
|
|
183
|
+
* 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:
|
|
184
|
+
* the register's own vocabulary (a mechanism, a proof, a waiver) is Mizan's.
|
|
209
185
|
*/
|
|
210
186
|
export async function registerDocuments(input, register = {}) {
|
|
211
187
|
const rows = registerRows(register.enforcement === undefined ? input : { ...input, enforcement: enforcementAt(register.enforcement) });
|
|
212
188
|
const catalog = "the specifications of its Mizan folder";
|
|
213
|
-
const pairs = rows.map((row) => ({ row, control: summaryOf(row, catalog) }));
|
|
214
|
-
const controls = pairs.map((p) => p.control);
|
|
215
189
|
const tests = new Map(input.tests.map((t) => [t.path, t.text]));
|
|
216
190
|
const version = (await sha256(JSON.stringify(rows.map((r) => [r.requirement, r.mechanism, r.by, r.note, r.title, r.files])))).slice(0, 12);
|
|
217
191
|
const namespace = await uuidV5(NAMESPACE_URL, REGISTER_IRI);
|
|
218
|
-
const
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
propNamespace: `${REGISTER_IRI}#`,
|
|
192
|
+
const id = (...parts) => uuidV5Of(namespace, parts);
|
|
193
|
+
const ns = `${REGISTER_IRI}#`;
|
|
194
|
+
const prop = (name, value) => ({ name, ns, value });
|
|
195
|
+
const metadata = (what) => ({
|
|
223
196
|
title: `Mizan register of ${input.label}: ${what} (generated by ${RUN}; do not edit)`,
|
|
224
|
-
|
|
197
|
+
"last-modified": NO_CLOCK,
|
|
198
|
+
version,
|
|
199
|
+
"oscal-version": OSCAL_VERSION,
|
|
225
200
|
});
|
|
226
|
-
const
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
const
|
|
234
|
-
const withMechanism = {
|
|
201
|
+
const catalogId = await id("catalog", input.label);
|
|
202
|
+
const implemented = await Promise.all(rows.map(async (row) => ({
|
|
203
|
+
uuid: await id("implemented-requirement", input.label, row.controlId),
|
|
204
|
+
"control-id": row.controlId,
|
|
205
|
+
description: `${row.requirement} (${row.title})`,
|
|
206
|
+
props: [prop("control", row.requirement), prop("mechanism", row.mechanism), prop("proofs", String(row.files.length))],
|
|
207
|
+
})));
|
|
208
|
+
const componentDefinition = {
|
|
235
209
|
"component-definition": {
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
:
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
};
|
|
256
|
-
}),
|
|
257
|
-
})),
|
|
258
|
-
}),
|
|
259
|
-
})),
|
|
210
|
+
uuid: await id("component-definition", input.label),
|
|
211
|
+
metadata: metadata("component definition"),
|
|
212
|
+
components: [
|
|
213
|
+
{
|
|
214
|
+
uuid: await id("component", input.label),
|
|
215
|
+
type: "software",
|
|
216
|
+
title: input.label,
|
|
217
|
+
description: `${input.label}, whose requirements are written in ${catalog}.`,
|
|
218
|
+
"control-implementations": [
|
|
219
|
+
{
|
|
220
|
+
uuid: await id("control-implementation", input.label),
|
|
221
|
+
source: `#${catalogId}`,
|
|
222
|
+
description: `The controls of ${catalog} that ${input.label} implements.`,
|
|
223
|
+
"implemented-requirements": implemented,
|
|
224
|
+
},
|
|
225
|
+
],
|
|
226
|
+
},
|
|
227
|
+
],
|
|
228
|
+
"back-matter": { resources: [{ uuid: catalogId, title: `The controls of ${catalog}` }] },
|
|
260
229
|
},
|
|
261
230
|
};
|
|
262
|
-
const
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
231
|
+
const specs = [...new Set(rows.map((r) => r.spec))].sort(byText);
|
|
232
|
+
const inventory = await Promise.all(specs.map(async (spec) => ({
|
|
233
|
+
uuid: await id("inventory-item", input.label, spec),
|
|
234
|
+
description: `specification ${spec}`,
|
|
235
|
+
props: [{ name: "asset-id", value: spec }, prop("subject-kind", "specification")],
|
|
236
|
+
})));
|
|
237
|
+
const inventoryOf = new Map(specs.map((spec, i) => [spec, inventory[i]?.uuid ?? ""]));
|
|
238
|
+
const observed = (await Promise.all(rows.map((row) => observationsOf(row, tests)))).flat();
|
|
239
|
+
const observations = await Promise.all(observed.map(async (o, i) => {
|
|
240
|
+
const title = `${o.row.requirement} on specification ${o.row.spec}: ${o.title}`;
|
|
241
|
+
return {
|
|
242
|
+
uuid: await id("observation", input.label, String(i), title),
|
|
243
|
+
title,
|
|
244
|
+
description: o.detail,
|
|
245
|
+
props: [
|
|
246
|
+
prop("control", o.row.requirement),
|
|
247
|
+
prop("outcome", o.outcome),
|
|
248
|
+
prop("status", o.status),
|
|
249
|
+
prop("severity", "info"),
|
|
250
|
+
...(o.waiver === undefined ? [] : [prop("waiver", o.waiver)]),
|
|
251
|
+
],
|
|
252
|
+
methods: ["TEST"],
|
|
253
|
+
types: ["finding"],
|
|
254
|
+
subjects: [{ "subject-uuid": inventoryOf.get(o.row.spec) ?? "", type: "inventory-item", title: `specification ${o.row.spec}` }],
|
|
255
|
+
...(o.evidence === undefined
|
|
256
|
+
? {}
|
|
257
|
+
: { "relevant-evidence": [{ description: `evidence of SHA-256 ${o.evidence}`, props: [prop("sha256", o.evidence)] }] }),
|
|
258
|
+
collected: NO_CLOCK,
|
|
259
|
+
};
|
|
260
|
+
}));
|
|
261
|
+
const findings = await Promise.all(rows.map(async (row) => {
|
|
262
|
+
const own = observed.flatMap((o, i) => (o.row === row ? [{ o, uuid: observations[i]?.uuid ?? "" }] : []));
|
|
263
|
+
const outcome = own.some((x) => x.o.outcome === "gap") ? "gap" : own.some((x) => x.o.outcome === "accepted") ? "accepted" : "pass";
|
|
264
|
+
return {
|
|
265
|
+
uuid: await id("finding", input.label, row.controlId),
|
|
266
|
+
title: row.controlId,
|
|
267
|
+
description: `${row.controlId}: ${outcome}, by ${row.requirement}.`,
|
|
268
|
+
props: [prop("outcome", outcome), prop("control", row.requirement)],
|
|
269
|
+
target: { type: "objective-id", "target-id": row.controlId, status: { state: outcome === "gap" ? "not-satisfied" : "satisfied" } },
|
|
270
|
+
"related-observations": own.map((x) => ({ "observation-uuid": x.uuid })),
|
|
271
|
+
};
|
|
272
|
+
}));
|
|
273
|
+
const plan = await id("assessment-plan", input.label);
|
|
274
|
+
const assessmentResults = {
|
|
275
|
+
"assessment-results": {
|
|
276
|
+
uuid: await id("assessment-results", input.label),
|
|
277
|
+
metadata: metadata("assessment results"),
|
|
278
|
+
"import-ap": { href: `#${plan}` },
|
|
279
|
+
results: [
|
|
280
|
+
{
|
|
281
|
+
uuid: await id("result", input.label),
|
|
282
|
+
title: `Mizan register of ${input.label} as of ${NO_CLOCK}`,
|
|
283
|
+
description: `The findings of Mizan register of ${input.label}, assessed at ${NO_CLOCK}.`,
|
|
284
|
+
start: NO_CLOCK,
|
|
285
|
+
"local-definitions": { "inventory-items": inventory },
|
|
286
|
+
"reviewed-controls": { "control-selections": [{ "include-controls": rows.map((r) => ({ "control-id": r.controlId })) }] },
|
|
287
|
+
observations,
|
|
288
|
+
findings,
|
|
289
|
+
},
|
|
290
|
+
],
|
|
291
|
+
"back-matter": { resources: [{ uuid: plan, title: `The assessment plan of Mizan register of ${input.label}` }] },
|
|
292
|
+
},
|
|
268
293
|
};
|
|
269
|
-
|
|
270
|
-
return { componentDefinition: renderOscal(withMechanism), assessmentResults: renderOscal(results) };
|
|
294
|
+
return { componentDefinition: `${JSON.stringify(componentDefinition, null, 2)}\n`, assessmentResults: `${JSON.stringify(assessmentResults, null, 2)}\n` };
|
|
271
295
|
}
|
|
272
296
|
/** The text of the register at an explicit path, with LF line ends; an error that names the file where it is not there. */
|
|
273
297
|
function enforcementAt(path) {
|
package/dist/pack-library.js
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
|
/** The scope of the packages of commons. */
|
|
30
30
|
export const SCOPE = "@intellectual-frontiers";
|
|
31
31
|
const obj = (v) => (isObject(v) ? v : {});
|
|
@@ -488,6 +488,11 @@ export async function packLibrary(root, options = {}) {
|
|
|
488
488
|
}
|
|
489
489
|
/** The command line of a library's `tools/pack.ts`: pack, print what was found (or the tarball) and the exit status. */
|
|
490
490
|
export async function main(root, argv, options = {}) {
|
|
491
|
+
// 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
|
|
492
|
+
if (argv.includes("--check") && (env.get("IFC_SKIP_PACK") ?? "") !== "") {
|
|
493
|
+
console.log("pack check skipped: the exports of this library did not change in this push (IFC_SKIP_PACK); the release packs it");
|
|
494
|
+
return 0;
|
|
495
|
+
}
|
|
491
496
|
const r = await packLibrary(root, options);
|
|
492
497
|
for (const f of r.findings)
|
|
493
498
|
console.error(f);
|
package/dist/plan.d.ts
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { type Cell } from "./workflows/definitions.js";
|
|
2
|
+
/** A library as the plan reads it. */
|
|
3
|
+
export type Planned = {
|
|
4
|
+
readonly name: string;
|
|
5
|
+
readonly folder: string;
|
|
6
|
+
readonly verify: string;
|
|
7
|
+
};
|
|
8
|
+
/** The cells of a job: what `strategy.matrix` reads as `{"include": [...]}`. */
|
|
9
|
+
export type Include = {
|
|
10
|
+
readonly include: readonly Cell[];
|
|
11
|
+
};
|
|
12
|
+
/** What CI runs for a change: the cells on Linux, and the cells on the other systems. */
|
|
13
|
+
export type Plan = {
|
|
14
|
+
readonly linux: Include;
|
|
15
|
+
readonly systems: Include;
|
|
16
|
+
};
|
|
17
|
+
/** The plan for these libraries: a cell on Linux for each, and one on each system its record names, in the order of the libraries; the packing is checked in the cells of the libraries named in `packs`. */
|
|
18
|
+
export declare function planOf(libs: readonly Planned[], packs?: ReadonlySet<string>): Plan;
|
|
19
|
+
/** The exports of a package.json as one line, the keys in order, so that two of them are the same where the entries are. */
|
|
20
|
+
export declare function exportsLine(packageJson: string): string;
|
|
21
|
+
/**
|
|
22
|
+
* The libraries whose packing a push checks (FR-013): those that changed their `exports` since the base (a new library included), and every library where the packer itself changed. Git that cannot say gives every library.
|
|
23
|
+
*/
|
|
24
|
+
export declare function packsFor(repo: string, base: string, libs: readonly Planned[]): Promise<ReadonlySet<string>>;
|
|
25
|
+
/** The outputs of a step that a workflow reads: the matrices as one line of JSON each and whether each has a cell. */
|
|
26
|
+
export declare function outputsOf(p: Plan): string;
|
|
27
|
+
/** The command line. Returns the exit status: 0, or 2 for a command line that does not fit. */
|
|
28
|
+
export declare function main(argv: readonly string[]): Promise<number>;
|
package/dist/plan.js
ADDED
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The plan of CI (commons 0001-libraries FR-012): the libraries a push or a pull request affects, and for each the cells that the one workflow `ci` runs, so that a change proves what it touches and nothing else.
|
|
3
|
+
*
|
|
4
|
+
* bun commons/libraries/src/plan.ts --base origin/main the plan for what changed since the merge base with origin/main, as JSON
|
|
5
|
+
* bun commons/libraries/src/plan.ts --all every library
|
|
6
|
+
* bun commons/libraries/src/plan.ts --files a.ts,b/c.ts the libraries these files affect
|
|
7
|
+
* bun commons/libraries/src/plan.ts --base REF --github-output "$GITHUB_OUTPUT" the same, written as the outputs of a step: has-linux, linux, has-systems, systems
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* The libraries are those of `affected.ts` (the same code the development loop and every check read), with the reach of `verify`: what a library's `verify` reads, and what depends on it. Each library has a cell on Linux; a
|
|
11
|
+
* library whose record of CI (`LIBRARY_CI`) names Windows or macOS has a cell on each of them too, because it has code of its own for them. A matrix with no cell is not written as a matrix (a workflow cannot run
|
|
12
|
+
* one): `has-linux` and `has-systems` say whether there is one.
|
|
13
|
+
*
|
|
14
|
+
* @limits
|
|
15
|
+
* It decides nothing about a version, a tag or a release; those are the release's. It cannot say what changed where Git cannot: it plans every library then, and says why.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* ```ts
|
|
19
|
+
* import { planOf } from "./plan.ts";
|
|
20
|
+
* planOf([{ name: "net", folder: "commons/net", verify: "bun run verify" }]).systems.include.map((c) => c.os); // ["windows-latest", "macos-latest"]
|
|
21
|
+
* ```
|
|
22
|
+
*
|
|
23
|
+
* Spec: 0001-libraries FR-012
|
|
24
|
+
*
|
|
25
|
+
* @module
|
|
26
|
+
*/
|
|
27
|
+
import process from "node:process";
|
|
28
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
29
|
+
import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
30
|
+
import { join } from "@intellectual-frontiers/system/path";
|
|
31
|
+
import { run } from "@intellectual-frontiers/system/proc";
|
|
32
|
+
import { flag, formatUsageError, helpText, many, parseArgs, value } from "@intellectual-frontiers/terminal/args";
|
|
33
|
+
import { affectedBy, changedSince, everyLibrary } from "./affected.js";
|
|
34
|
+
import { cellOf, LIBRARY_CI } from "./workflows/definitions.js";
|
|
35
|
+
/** The plan for these libraries: a cell on Linux for each, and one on each system its record names, in the order of the libraries; the packing is checked in the cells of the libraries named in `packs`. */
|
|
36
|
+
export function planOf(libs, packs = new Set()) {
|
|
37
|
+
return {
|
|
38
|
+
linux: { include: libs.map((l) => cellOf(l, undefined, packs.has(l.name))) },
|
|
39
|
+
systems: { include: libs.flatMap((l) => (LIBRARY_CI[l.name]?.systems ?? []).map((os) => cellOf(l, os, packs.has(l.name)))) },
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
/** The exports of a package.json as one line, the keys in order, so that two of them are the same where the entries are. */
|
|
43
|
+
export function exportsLine(packageJson) {
|
|
44
|
+
try {
|
|
45
|
+
const x = JSON.parse(packageJson);
|
|
46
|
+
const e = typeof x === "object" && x !== null && "exports" in x ? x.exports : undefined;
|
|
47
|
+
const sorted = (v) => typeof v === "object" && v !== null && !Array.isArray(v)
|
|
48
|
+
? Object.fromEntries(Object.entries(v)
|
|
49
|
+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
|
|
50
|
+
.map(([k, n]) => [k, sorted(n)]))
|
|
51
|
+
: v;
|
|
52
|
+
return JSON.stringify(sorted(e ?? null));
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
return "unreadable";
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* The libraries whose packing a push checks (FR-013): those that changed their `exports` since the base (a new library included), and every library where the packer itself changed. Git that cannot say gives every library.
|
|
60
|
+
*/
|
|
61
|
+
export async function packsFor(repo, base, libs) {
|
|
62
|
+
const all = new Set(libs.map((l) => l.name));
|
|
63
|
+
const mb = await run(["git", "-C", repo, "merge-base", base, "HEAD"]);
|
|
64
|
+
if (mb.code !== 0)
|
|
65
|
+
return all;
|
|
66
|
+
const packer = await run(["git", "-C", repo, "diff", "--name-only", mb.stdout.trim(), "--", "commons/libraries/src/pack-library.ts"]);
|
|
67
|
+
if (packer.code !== 0 || packer.stdout.trim() !== "")
|
|
68
|
+
return all;
|
|
69
|
+
const out = new Set();
|
|
70
|
+
for (const l of libs) {
|
|
71
|
+
const before = await run(["git", "-C", repo, "show", `${mb.stdout.trim()}:${l.folder}/package.json`]);
|
|
72
|
+
const now = join(repo, l.folder, "package.json");
|
|
73
|
+
if (before.code !== 0 || !existsSync(now) || exportsLine(before.stdout) !== exportsLine(readTextFileSync(now)))
|
|
74
|
+
out.add(l.name);
|
|
75
|
+
}
|
|
76
|
+
return out;
|
|
77
|
+
}
|
|
78
|
+
/** The outputs of a step that a workflow reads: the matrices as one line of JSON each and whether each has a cell. */
|
|
79
|
+
export function outputsOf(p) {
|
|
80
|
+
return [
|
|
81
|
+
`has-linux=${p.linux.include.length > 0}`,
|
|
82
|
+
`linux=${JSON.stringify(p.linux)}`,
|
|
83
|
+
`has-systems=${p.systems.include.length > 0}`,
|
|
84
|
+
`systems=${JSON.stringify(p.systems)}`,
|
|
85
|
+
].join("\n");
|
|
86
|
+
}
|
|
87
|
+
const OPTIONS = {
|
|
88
|
+
base: value({ help: "The revision the change starts at (the merge base with it is compared with the head).", valueName: "REF" }),
|
|
89
|
+
files: many({ help: "A file that changed (from the repository's root); the libraries it affects. Repeat or separate with commas.", valueName: "FILE" }),
|
|
90
|
+
all: flag({ help: "Every library." }),
|
|
91
|
+
repo: value({ help: "The repository (the working folder by default).", valueName: "DIR", default: "." }),
|
|
92
|
+
githubOutput: value({ help: "Append the outputs to this file, as a step's `$GITHUB_OUTPUT` is read.", valueName: "FILE" }),
|
|
93
|
+
};
|
|
94
|
+
/** The command line. Returns the exit status: 0, or 2 for a command line that does not fit. */
|
|
95
|
+
export async function main(argv) {
|
|
96
|
+
const parsed = parseArgs(argv, OPTIONS);
|
|
97
|
+
if (parsed.kind === "err") {
|
|
98
|
+
stdio.stderr.writeSync(`${formatUsageError(parsed.error, "plan")}\n`);
|
|
99
|
+
return 2;
|
|
100
|
+
}
|
|
101
|
+
if (parsed.value.kind === "help") {
|
|
102
|
+
stdio.stdout.writeSync(`${helpText("plan", "The libraries a change affects and the cells CI runs for them.", OPTIONS)}\n`);
|
|
103
|
+
return 0;
|
|
104
|
+
}
|
|
105
|
+
const o = parsed.value.options;
|
|
106
|
+
const files = (o.files ?? []).flatMap((f) => f.split(",")).filter((f) => f !== "");
|
|
107
|
+
let libs;
|
|
108
|
+
let packs = new Set();
|
|
109
|
+
if (o.all) {
|
|
110
|
+
libs = everyLibrary(o.repo);
|
|
111
|
+
packs = new Set(libs.map((l) => l.name));
|
|
112
|
+
}
|
|
113
|
+
else if (files.length > 0)
|
|
114
|
+
libs = affectedBy(o.repo, files);
|
|
115
|
+
else if (o.base !== undefined) {
|
|
116
|
+
const changed = await changedSince(o.repo, o.base);
|
|
117
|
+
if (changed === undefined)
|
|
118
|
+
stdio.stderr.writeSync(`plan: git cannot say what changed since ${o.base}; every library is planned\n`);
|
|
119
|
+
libs = changed === undefined ? everyLibrary(o.repo) : affectedBy(o.repo, changed);
|
|
120
|
+
packs = changed === undefined ? new Set(libs.map((l) => l.name)) : await packsFor(o.repo, o.base, libs);
|
|
121
|
+
}
|
|
122
|
+
else {
|
|
123
|
+
stdio.stderr.writeSync("plan: give --base REF, --files a,b or --all\n");
|
|
124
|
+
return 2;
|
|
125
|
+
}
|
|
126
|
+
const plan = planOf(libs, packs);
|
|
127
|
+
if (o.githubOutput === undefined)
|
|
128
|
+
stdio.stdout.writeSync(`${JSON.stringify(plan)}\n`);
|
|
129
|
+
else
|
|
130
|
+
writeTextFileSync(o.githubOutput, `${outputsOf(plan)}\n`, { append: true });
|
|
131
|
+
stdio.stderr.writeSync(`plan: ${libs.length} libraries: ${libs.map((l) => l.name).join(", ") || "none"}\n`);
|
|
132
|
+
return 0;
|
|
133
|
+
}
|
|
134
|
+
if (import.meta.main)
|
|
135
|
+
process.exitCode = await main(process.argv.slice(2));
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
2
|
+
import { type Look } from "@intellectual-frontiers/system/tty";
|
|
3
|
+
import { type Slug } from "@intellectual-frontiers/mizan/versions/record";
|
|
4
|
+
import { type Impact } from "@intellectual-frontiers/mizan/versions/scheme";
|
|
5
|
+
/** The record of the release, from the repository's root. */
|
|
6
|
+
export declare const RECORD_PATH = "commons/generated/release.auto.json";
|
|
7
|
+
/** What the plan knows of a library: its version, what it imports, the last tag of it, whether its files changed since, and the impact the commits since state. */
|
|
8
|
+
export type Facts = {
|
|
9
|
+
readonly slug: Slug;
|
|
10
|
+
readonly folder: string;
|
|
11
|
+
readonly version: string;
|
|
12
|
+
/** The libraries (by slug) whose package its own sources import. */
|
|
13
|
+
readonly imports: readonly Slug[];
|
|
14
|
+
/** The greatest tag of the library by Semantic Version precedence, where it has one. */
|
|
15
|
+
readonly last: {
|
|
16
|
+
readonly version: string;
|
|
17
|
+
readonly tag: string;
|
|
18
|
+
} | undefined;
|
|
19
|
+
/** Whether a file of the library changed since `last`; false where there is none. */
|
|
20
|
+
readonly changed: boolean;
|
|
21
|
+
/** The greatest impact the commits since `last` state, a patch where none does. */
|
|
22
|
+
readonly impact: Impact;
|
|
23
|
+
/** Whether the release sends it to a registry: a library that names npm. */
|
|
24
|
+
readonly publish: boolean;
|
|
25
|
+
/** For a version that is not tagged or is ahead of its tag: what npm holds of this version, compared with the files of the library. */
|
|
26
|
+
readonly registry: Drift;
|
|
27
|
+
/** Whether a file of the library changed since the last commit that raised its version, and the impact the commits since state (a patch where none does): the fallback where npm cannot be compared. */
|
|
28
|
+
readonly sinceVersion: {
|
|
29
|
+
readonly changed: boolean;
|
|
30
|
+
readonly impact: Impact;
|
|
31
|
+
};
|
|
32
|
+
};
|
|
33
|
+
/** What npm holds of a version, against the files of the library: not there, there and the same, there and different, or not known (offline, or the registry did not say). */
|
|
34
|
+
export type Drift = "absent" | "same" | "differs" | "unknown";
|
|
35
|
+
/** Why a library is raised. */
|
|
36
|
+
export type Why = "changed" | "differs-from-npm" | "changed-since-version" | "manual";
|
|
37
|
+
/** What the release does to one library. */
|
|
38
|
+
export type Decision = {
|
|
39
|
+
readonly kind: "unchanged";
|
|
40
|
+
} | {
|
|
41
|
+
readonly kind: "as-is";
|
|
42
|
+
readonly why: "no-tag" | "ahead-of-tag";
|
|
43
|
+
readonly npm: Drift;
|
|
44
|
+
} | {
|
|
45
|
+
readonly kind: "raised";
|
|
46
|
+
readonly to: string;
|
|
47
|
+
readonly impact: Impact;
|
|
48
|
+
readonly why: Why;
|
|
49
|
+
} | {
|
|
50
|
+
readonly kind: "dependent";
|
|
51
|
+
readonly to: string;
|
|
52
|
+
readonly because: readonly Slug[];
|
|
53
|
+
};
|
|
54
|
+
/** One step of a release: a library, its version before and after, and what is done to it. */
|
|
55
|
+
export type Step = {
|
|
56
|
+
readonly slug: Slug;
|
|
57
|
+
readonly folder: string;
|
|
58
|
+
readonly from: string;
|
|
59
|
+
readonly to: string;
|
|
60
|
+
readonly tag: string;
|
|
61
|
+
readonly publish: boolean;
|
|
62
|
+
readonly decision: Exclude<Decision, {
|
|
63
|
+
readonly kind: "unchanged";
|
|
64
|
+
}>;
|
|
65
|
+
};
|
|
66
|
+
/** The plan: every step in the order of the imports, and the libraries that are left alone. */
|
|
67
|
+
export type Plan = {
|
|
68
|
+
readonly steps: readonly Step[];
|
|
69
|
+
readonly unchanged: readonly Slug[];
|
|
70
|
+
};
|
|
71
|
+
/** The text of a decision, in a sentence. */
|
|
72
|
+
export declare function describe(d: Decision, from: string): string;
|
|
73
|
+
/**
|
|
74
|
+
* The plan of a release from the facts of the libraries (FR-013): a library with no tag, or ahead of its last tag, is released as it is; one that is tagged at its version and changed is raised by its impact; one that is tagged,
|
|
75
|
+
* unchanged and imports a library that is raised, directly or through another, is raised by a patch; the rest are left alone. A library whose version is below its last tag is an error, and so is a cycle of imports.
|
|
76
|
+
*/
|
|
77
|
+
export declare function planRelease(facts: readonly Facts[], raise?: ReadonlyMap<string, Impact | undefined>): Result<Plan, string>;
|
|
78
|
+
/** The record the workflow reads, as the bytes of its file: the steps that publish or tag, in order. */
|
|
79
|
+
export declare function recordText(plan: Plan): string;
|
|
80
|
+
/** One entry of the record, as the workflow reads it. */
|
|
81
|
+
export type Entry = {
|
|
82
|
+
readonly slug: string;
|
|
83
|
+
readonly version: string;
|
|
84
|
+
readonly folder: string;
|
|
85
|
+
readonly tag: string;
|
|
86
|
+
readonly publish: boolean;
|
|
87
|
+
};
|
|
88
|
+
/** The entries of a record's text, or why it is not one. */
|
|
89
|
+
export declare function readRecord(text: string): Result<readonly Entry[], string>;
|
|
90
|
+
/** What the workflow builds and publishes: the entries whose tag is not there yet, as the cells of a matrix and the sequence to publish in, as the outputs of a step. */
|
|
91
|
+
export declare function matrixOutputs(entries: readonly Entry[], tagged: ReadonlySet<string>): string;
|
|
92
|
+
/** Writes a library's new version into its record, its manifest and its package, each where it says the version; the problem where one does not. */
|
|
93
|
+
export declare function writeVersion(repo: string, step: Step): Result<readonly string[], string>;
|
|
94
|
+
/** What a tarball holds that the comparison reads: the SHA-256 of each file by its path (without the folder `package/`), and the text of its `package.json`. */
|
|
95
|
+
export type Tarball = {
|
|
96
|
+
readonly hashes: ReadonlyMap<string, string>;
|
|
97
|
+
readonly packageJson: string;
|
|
98
|
+
};
|
|
99
|
+
/** The files of a gzipped tar, as a registry serves it: each regular file's path and SHA-256. A header it cannot read ends the list there. */
|
|
100
|
+
export declare function tarballOf(gz: Uint8Array): Tarball;
|
|
101
|
+
/**
|
|
102
|
+
* Whether the files of a library are those of the version npm holds (FR-013): the sources the package carries (`src/`, each by its SHA-256 against the library's own file) and the keys of its `exports` (the packer rewrites the rest of
|
|
103
|
+
* `package.json`, and the compiled files are the compiler's). A source that is missing here, or other, or an entry of `exports` that was added or removed, is a difference.
|
|
104
|
+
*/
|
|
105
|
+
export declare function driftOf(published: Tarball, local: {
|
|
106
|
+
readonly hash: (path: string) => string | undefined;
|
|
107
|
+
readonly packageJson: string;
|
|
108
|
+
}): "same" | "differs";
|
|
109
|
+
/** Compares a library's version with what npm holds of it. */
|
|
110
|
+
export type Registry = (slug: string, version: string, folder: string) => Promise<Drift>;
|
|
111
|
+
/** The registry of npm itself, read over HTTPS: the metadata of the version, its tarball, and the library's files under `repo`; anything that goes wrong is `unknown`, never a guess. */
|
|
112
|
+
export declare function realRegistry(repo: string): Registry;
|
|
113
|
+
/** What the host gives the plan: the facts of the libraries from the tags and the tree. */
|
|
114
|
+
export declare function factsOf(repo: string, registry?: Registry): Promise<Result<readonly Facts[], string>>;
|
|
115
|
+
/** The commands that make the generated files, in the order they are made: the section of the libraries first, the register last. Each is run once, by `apply`. */
|
|
116
|
+
export declare const GENERATORS: readonly (readonly string[])[];
|
|
117
|
+
/** The tests that pack every library, install it into a consumer and type-check against it (the heavy proof a release asks for and a push does not). */
|
|
118
|
+
export declare const PACKAGE_TESTS: readonly string[];
|
|
119
|
+
/** What `apply` runs besides the planner: the generators and the tests, which a test of this module replaces. */
|
|
120
|
+
export type Host = {
|
|
121
|
+
readonly generate: (repo: string, command: readonly string[]) => Promise<Result<void, string>>;
|
|
122
|
+
readonly prove: (repo: string) => Promise<Result<void, string>>;
|
|
123
|
+
};
|
|
124
|
+
/** The real host: each command run with Bun from the repository's root. */
|
|
125
|
+
export declare const REAL: Host;
|
|
126
|
+
/** What `apply` did: the files written, in order. */
|
|
127
|
+
export type Applied = {
|
|
128
|
+
readonly plan: Plan;
|
|
129
|
+
readonly written: readonly string[];
|
|
130
|
+
};
|
|
131
|
+
/** Makes the release (FR-014): raises the versions of the plan, makes the generated files once, runs the tests that pack unless asked not to, and writes the record. */
|
|
132
|
+
export declare function applyRelease(repo: string, host: Host, options: {
|
|
133
|
+
readonly tests: boolean;
|
|
134
|
+
readonly raise?: ReadonlyMap<string, Impact | undefined>;
|
|
135
|
+
readonly registry?: Registry;
|
|
136
|
+
}): Promise<Result<Applied, string>>;
|
|
137
|
+
/** The lines the plan prints: one for each library that is released, and the libraries left alone. */
|
|
138
|
+
export declare function planLines(look: Look, plan: Plan): readonly string[];
|
|
139
|
+
/** What the publication needs from the world, so that its order and its rules are a pure function of what these say. */
|
|
140
|
+
export type Tools = {
|
|
141
|
+
/** Whether the version is on npm (asked again after a pause where it is not, because a version put there by hand may take a while to show). */
|
|
142
|
+
readonly onNpm: (name: string, version: string) => Promise<boolean>;
|
|
143
|
+
/** Sends the package to npm; the reason where it cannot (no trusted publisher and no token, or npm refused). */
|
|
144
|
+
readonly npm: (e: Entry) => Promise<Result<void, string>>;
|
|
145
|
+
/** Sends the package to the GitHub package registry, unless it is there. */
|
|
146
|
+
readonly github: (e: Entry) => Promise<Result<void, string>>;
|
|
147
|
+
/** Makes the tag at the commit that runs, or finds it there. */
|
|
148
|
+
readonly tag: (tag: string) => Promise<Result<"made" | "there", string>>;
|
|
149
|
+
};
|
|
150
|
+
/** What happened to one release: the state of its publication, and of its tag. */
|
|
151
|
+
export type Outcome = {
|
|
152
|
+
readonly slug: string;
|
|
153
|
+
readonly tag: string;
|
|
154
|
+
readonly npm: "present" | "published" | "failed" | "not-published";
|
|
155
|
+
readonly registry: "done" | "failed" | "not-published";
|
|
156
|
+
readonly tagged: "made" | "there" | "withheld" | "failed";
|
|
157
|
+
readonly reasons: readonly string[];
|
|
158
|
+
};
|
|
159
|
+
/**
|
|
160
|
+
* Publishes and tags the releases in order (FR-015), each by itself: a version that is on npm is not sent again and is tagged; one that is not is sent, and where nothing can send it (no trusted publisher, no token) it is
|
|
161
|
+
* reported and its tag withheld, and the others go on; a release that is only tagged (a library that names no npm) is tagged. A tag that is there is kept. The failures are in the outcomes, never thrown.
|
|
162
|
+
*/
|
|
163
|
+
export declare function publishAll(entries: readonly Entry[], tools: Tools): Promise<readonly Outcome[]>;
|
|
164
|
+
/** The lines that say how each release went, and whether the run is a failure: one failure anywhere fails it, after every release was tried. */
|
|
165
|
+
export declare function outcomeLines(outcomes: readonly Outcome[]): {
|
|
166
|
+
readonly lines: readonly string[];
|
|
167
|
+
readonly failed: boolean;
|
|
168
|
+
};
|
|
169
|
+
/** The tools of a run of the release workflow: npm and the GitHub CLI, the tarballs under `dir` (one folder for each library, `package-<slug>`), and the environment's credentials. */
|
|
170
|
+
export declare function realTools(dir: string): Tools;
|
|
171
|
+
/** What `--raise` says: each library by its name, with the impact after an `=` where one is given. */
|
|
172
|
+
export declare function raiseOf(words: readonly string[]): Result<ReadonlyMap<string, Impact | undefined>, string>;
|
|
173
|
+
/** The registry that is not asked (`--offline`). */
|
|
174
|
+
export declare const offlineRegistry: Registry;
|
|
175
|
+
/** The command line. Returns the exit status: 0, 1 where a plan or a step failed, 2 for a command line that does not fit. */
|
|
176
|
+
export declare function main(argv: readonly string[], host?: Host): Promise<number>;
|