@intellectual-frontiers/libraries 0.1.1 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/generate-ontology.d.ts +2 -0
- package/dist/generate-ontology.js +33 -1
- package/dist/libraries.d.ts +5 -0
- package/dist/libraries.js +18 -3
- package/dist/oscal-register.d.ts +2 -1
- package/dist/oscal-register.js +112 -88
- package/dist/workflows/definitions.js +5 -0
- package/package.json +4 -4
- package/src/generate-ontology.ts +34 -1
- package/src/libraries.ts +22 -2
- package/src/oscal-register.ts +139 -117
- package/src/workflows/definitions.ts +8 -0
|
@@ -13,6 +13,8 @@ export declare const IFCCM: OntologyPublication;
|
|
|
13
13
|
export declare const IFQS: OntologyPublication;
|
|
14
14
|
/** The ontology of Intellectual Frontiers Releases (commons 0026-works-versioning), as it is published. */
|
|
15
15
|
export declare const IFR: OntologyPublication;
|
|
16
|
+
/** The ontology of Kanon (commons 0033-kanon), as it is published. */
|
|
17
|
+
export declare const KANON: OntologyPublication;
|
|
16
18
|
/** The ontologies of commons that are published, each from its own typed modules: Mizan's, then the ones its specifications define. */
|
|
17
19
|
export declare const publications: readonly OntologyPublication[];
|
|
18
20
|
/** The exports of the ontology (0019-mizan-integrations FR-010): everything but its Turtle, by its path from commons' folder. */
|
|
@@ -19,6 +19,7 @@ import { Authority, bases, classes, Decision, files, integrationDirections, rung
|
|
|
19
19
|
import * as ifccmOntology from "@intellectual-frontiers/ontology/ifccm";
|
|
20
20
|
import * as ifrOntology from "@intellectual-frontiers/ontology/ifr";
|
|
21
21
|
import * as ifqsOntology from "@intellectual-frontiers/ontology/ifqs";
|
|
22
|
+
import * as kanonOntology from "@intellectual-frontiers/ontology/kanon";
|
|
22
23
|
import { formatRdfFinding, validate } from "@intellectual-frontiers/rdf";
|
|
23
24
|
import { stdio } from "@intellectual-frontiers/system";
|
|
24
25
|
import { exportDcat } from "@intellectual-frontiers/mizan/integrations/pure/export-dcat";
|
|
@@ -204,8 +205,39 @@ export const IFR = {
|
|
|
204
205
|
viewTitle: "Intellectual Frontiers Releases: the ontology",
|
|
205
206
|
license: CC0,
|
|
206
207
|
};
|
|
208
|
+
/** The ontology of Kanon (commons 0033-kanon), as it is published. */
|
|
209
|
+
export const KANON = {
|
|
210
|
+
name: "kanon",
|
|
211
|
+
ns: { prefix: "kanon", iri: kanonOntology.KANON.iri },
|
|
212
|
+
idNs: { prefix: "mzid", iri: MZID.iri },
|
|
213
|
+
curies: [
|
|
214
|
+
["kanon", kanonOntology.KANON.iri],
|
|
215
|
+
["mz", MZ.iri],
|
|
216
|
+
["xsd", "http://www.w3.org/2001/XMLSchema#"],
|
|
217
|
+
["rdfs", "http://www.w3.org/2000/01/rdf-schema#"],
|
|
218
|
+
["skos", "http://www.w3.org/2004/02/skos/core#"],
|
|
219
|
+
["dcterms", "http://purl.org/dc/terms/"],
|
|
220
|
+
["prov", "http://www.w3.org/ns/prov#"],
|
|
221
|
+
["sh", "http://www.w3.org/ns/shacl#"],
|
|
222
|
+
],
|
|
223
|
+
files: kanonOntology.files,
|
|
224
|
+
ontology: kanonOntology.kanonOntology,
|
|
225
|
+
classes: kanonOntology.classes,
|
|
226
|
+
properties: kanonOntology.properties,
|
|
227
|
+
terms: kanonOntology.terms,
|
|
228
|
+
schemas: [kanonOntology.Layer],
|
|
229
|
+
lists: listsOf("kanon", [["Layer", kanonOntology.layers]]),
|
|
230
|
+
source: "commons/ontology/src/kanon/*.ts",
|
|
231
|
+
run: RUN,
|
|
232
|
+
shapes: { prefix: "kanonsh", iri: "https://www.intellectualfrontiers.com/ontology/kanon-shapes#" },
|
|
233
|
+
schemasIri: "https://www.intellectualfrontiers.com/ontology/kanon-schemas",
|
|
234
|
+
sssomSetId: "https://www.intellectualfrontiers.com/ontology/kanon-mappings",
|
|
235
|
+
sssomCuries: { dcterms: "http://purl.org/dc/terms/", prov: "http://www.w3.org/ns/prov#", sh: "http://www.w3.org/ns/shacl#" },
|
|
236
|
+
viewTitle: "Kanon: the ontology",
|
|
237
|
+
license: CC0,
|
|
238
|
+
};
|
|
207
239
|
/** The ontologies of commons that are published, each from its own typed modules: Mizan's, then the ones its specifications define. */
|
|
208
|
-
export const publications = [MIZAN, IFCCM, IFQS, IFR];
|
|
240
|
+
export const publications = [MIZAN, IFCCM, IFQS, IFR, KANON];
|
|
209
241
|
/** Where the generated files are downloaded from: this repository's `commons/` folder on its default branch. */
|
|
210
242
|
const DOWNLOAD_BASE = "https://raw.githubusercontent.com/intellectual-frontiers/.github/main/commons/";
|
|
211
243
|
/** The exports of the ontology (0019-mizan-integrations FR-010): everything but its Turtle, by its path from commons' folder. */
|
package/dist/libraries.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type Result } from "@intellectual-frontiers/core";
|
|
2
|
+
import { type Table } from "@intellectual-frontiers/kanon";
|
|
2
3
|
import { type LevelKey } from "@intellectual-frontiers/mizan/levels";
|
|
3
4
|
/** The name of a library's manifest in its folder. */
|
|
4
5
|
export declare const LIBRARY_FILE = "library.ts";
|
|
@@ -27,7 +28,11 @@ export type Library = {
|
|
|
27
28
|
readonly summary?: string;
|
|
28
29
|
/** Where it is published: always `github` (the GitHub package registry of the organization), and `npm` as well where a decision about that package has made it so (FR-015 and FR-016). */
|
|
29
30
|
readonly distribution: readonly Registry[];
|
|
31
|
+
/** The table of its layers where it is built to Kanon (commons 0033-kanon FR-010); none where it is not. */
|
|
32
|
+
readonly kanon?: Table;
|
|
30
33
|
};
|
|
34
|
+
/** The lowest conformance level that requires a library to declare `kanon`; none yet (0033-kanon FR-014, OQ-1): a level asks for it by naming itself here. */
|
|
35
|
+
export declare const KANON_REQUIRED_FROM: LevelKey | undefined;
|
|
31
36
|
/** The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018). */
|
|
32
37
|
export declare const REGISTRIES: readonly ["github", "npm"];
|
|
33
38
|
export type Registry = (typeof REGISTRIES)[number];
|
package/dist/libraries.js
CHANGED
|
@@ -80,8 +80,9 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
|
|
|
80
80
|
* @module
|
|
81
81
|
*/
|
|
82
82
|
import process from "node:process";
|
|
83
|
-
import { array, describe, formatDecodeError, literal, object, string, err, ok, } from "@intellectual-frontiers/core";
|
|
83
|
+
import { array, describe, formatDecodeError, literal, object, unknownValue, string, err, ok, } from "@intellectual-frontiers/core";
|
|
84
84
|
import { exportedLiteral } from "@intellectual-frontiers/formats/ts-literal";
|
|
85
|
+
import { decodeTable } from "@intellectual-frontiers/kanon";
|
|
85
86
|
import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
86
87
|
import { stdio } from "@intellectual-frontiers/system";
|
|
87
88
|
import { spawn } from "@intellectual-frontiers/system/proc";
|
|
@@ -101,6 +102,8 @@ function bounds(spec) {
|
|
|
101
102
|
const to = spec.indexOf(`\n${END}\n`, from);
|
|
102
103
|
return from < 0 || to < 0 ? undefined : { from: from + 1, to: to + 1 };
|
|
103
104
|
}
|
|
105
|
+
/** The lowest conformance level that requires a library to declare `kanon`; none yet (0033-kanon FR-014, OQ-1): a level asks for it by naming itself here. */
|
|
106
|
+
export const KANON_REQUIRED_FROM = undefined;
|
|
104
107
|
/** The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018). */
|
|
105
108
|
export const REGISTRIES = ["github", "npm"];
|
|
106
109
|
/** Where a manifest that declares no distribution is published. */
|
|
@@ -119,8 +122,8 @@ const nameDecoder = (input, path = "$") => {
|
|
|
119
122
|
? r
|
|
120
123
|
: err({ kind: "decode", path, expected: "a name of lower-case letters, digits and hyphens", found: describe(input) });
|
|
121
124
|
};
|
|
122
|
-
const body = object({ name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) }, { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)) });
|
|
123
|
-
const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution"];
|
|
125
|
+
const body = object({ name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) }, { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue });
|
|
126
|
+
const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon"];
|
|
124
127
|
/** The manifest read from the text of its file: `export const library = { ... }` and no other export, read as data and never run (0027-commons-libraries FR-012). */
|
|
125
128
|
export function decodeLibrarySource(source) {
|
|
126
129
|
const exports = source.split("\n").filter((l) => /^export\s/.test(l));
|
|
@@ -145,6 +148,13 @@ export function decodeLibrarySource(source) {
|
|
|
145
148
|
return err("library.distribution lists each registry once and at least one (FR-015)");
|
|
146
149
|
if (!distribution.includes("github"))
|
|
147
150
|
return err("library.distribution includes github: a library is published to the GitHub package registry whatever else it is published to (FR-015, FR-016)");
|
|
151
|
+
let kanon;
|
|
152
|
+
if (v.kanon !== undefined) {
|
|
153
|
+
const t = decodeTable(v.kanon);
|
|
154
|
+
if (t.kind === "err")
|
|
155
|
+
return err(`library.${t.error} (0033-kanon FR-010)`);
|
|
156
|
+
kanon = t.value;
|
|
157
|
+
}
|
|
148
158
|
return ok({
|
|
149
159
|
name: v.name,
|
|
150
160
|
level: v.level ?? DEFAULT_LIBRARY_LEVEL,
|
|
@@ -154,6 +164,7 @@ export function decodeLibrarySource(source) {
|
|
|
154
164
|
exports: v.exports,
|
|
155
165
|
...(v.summary === undefined ? {} : { summary: v.summary }),
|
|
156
166
|
distribution,
|
|
167
|
+
...(kanon === undefined ? {} : { kanon }),
|
|
157
168
|
});
|
|
158
169
|
}
|
|
159
170
|
/** The manifests of `commons/*`, in the order of the folders' names: every folder that holds a `library.ts`. */
|
|
@@ -232,6 +243,10 @@ export function manifestFindings(repo) {
|
|
|
232
243
|
const verifyText = script === undefined ? "" : scriptText(`${dir}/package.json`, script);
|
|
233
244
|
if (rankOf(l.level) >= 1 && rankOf(l.level) < rankOf("L3") && !verifyText.includes(`--level ${l.level}`))
|
|
234
245
|
found.push(`commons/${f.dir}: the manifest declares ${l.level} and the verify script does not run the Mizan check with --level ${l.level} (0028-conformance-levels FR-013)`);
|
|
246
|
+
if (l.kanon !== undefined && !verifyText.includes("kanon/src/check.ts"))
|
|
247
|
+
found.push(`commons/${f.dir}: the manifest declares kanon and the verify script does not run the check of the table (bun ../kanon/src/check.ts) (0033-kanon FR-014)`);
|
|
248
|
+
if (KANON_REQUIRED_FROM !== undefined && rankOf(l.level) >= rankOf(KANON_REQUIRED_FROM) && l.kanon === undefined)
|
|
249
|
+
found.push(`commons/${f.dir}: the manifest declares ${l.level}, which requires kanon, and declares none (0033-kanon FR-014)`);
|
|
235
250
|
}
|
|
236
251
|
return found;
|
|
237
252
|
}
|
package/dist/oscal-register.d.ts
CHANGED
|
@@ -48,7 +48,8 @@ export type RegisterDocuments = {
|
|
|
48
48
|
};
|
|
49
49
|
/**
|
|
50
50
|
* 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
|
|
51
|
-
* and `input.enforcement` is not read (FR-043); the same bytes come for the same register wherever its file is.
|
|
51
|
+
* 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:
|
|
52
|
+
* the register's own vocabulary (a mechanism, a proof, a waiver) is Mizan's.
|
|
52
53
|
*/
|
|
53
54
|
export declare function registerDocuments(input: RegisterInput, register?: RegisterOptions): Promise<RegisterDocuments>;
|
|
54
55
|
/** 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/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) {
|
|
@@ -121,6 +121,11 @@ export const LIBRARY_CI = {
|
|
|
121
121
|
nodeTests: 'node --test "suite/**/*.test.ts"',
|
|
122
122
|
systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
|
|
123
123
|
},
|
|
124
|
+
kanon: {
|
|
125
|
+
comment: lines("Kanon, the pattern of a library built in three layers (commons 0033-kanon): its own `verify` (the compiler, the specification checker, the trace check, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
|
|
126
|
+
nodeTests: 'node --test "suite/**/*.test.ts"',
|
|
127
|
+
systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
|
|
128
|
+
},
|
|
124
129
|
telemetry: {
|
|
125
130
|
comment: lines("Telemetry, OpenTelemetry-native signals as one typed library, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
|
|
126
131
|
nodeTests: 'node --test "suite/**/*.test.ts"',
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@intellectual-frontiers/libraries",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "The libraries of a repository of commons as code: the manifest of a library and the check that it and its folder agree, which libraries a change affects, the typed workflows of GitHub Actions and their generator, the pinned Bun, the packer that builds, inspects and packs a library for npm with its declarations, and the commands that hold a whole repository to Mizan (check, change control, versions, the register and the ontologies).",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -101,11 +101,11 @@
|
|
|
101
101
|
"@intellectual-frontiers/crypto": "0.1.4",
|
|
102
102
|
"@intellectual-frontiers/formats": "0.1.4",
|
|
103
103
|
"@intellectual-frontiers/githost": "0.1.2",
|
|
104
|
-
"@intellectual-frontiers/
|
|
104
|
+
"@intellectual-frontiers/kanon": "0.1.0",
|
|
105
105
|
"@intellectual-frontiers/mizan": "0.1.1",
|
|
106
106
|
"@intellectual-frontiers/net": "0.1.5",
|
|
107
|
-
"@intellectual-frontiers/ontology": "0.
|
|
108
|
-
"@intellectual-frontiers/quality": "0.
|
|
107
|
+
"@intellectual-frontiers/ontology": "0.2.0",
|
|
108
|
+
"@intellectual-frontiers/quality": "0.2.0",
|
|
109
109
|
"@intellectual-frontiers/rdf": "0.1.4",
|
|
110
110
|
"@intellectual-frontiers/system": "0.1.6",
|
|
111
111
|
"@intellectual-frontiers/terminal": "0.1.6"
|
package/src/generate-ontology.ts
CHANGED
|
@@ -37,6 +37,7 @@ import {
|
|
|
37
37
|
import * as ifccmOntology from "@intellectual-frontiers/ontology/ifccm";
|
|
38
38
|
import * as ifrOntology from "@intellectual-frontiers/ontology/ifr";
|
|
39
39
|
import * as ifqsOntology from "@intellectual-frontiers/ontology/ifqs";
|
|
40
|
+
import * as kanonOntology from "@intellectual-frontiers/ontology/kanon";
|
|
40
41
|
import { formatRdfFinding, type OntologyFile, validate } from "@intellectual-frontiers/rdf";
|
|
41
42
|
import { stdio } from "@intellectual-frontiers/system";
|
|
42
43
|
import { exportDcat } from "@intellectual-frontiers/mizan/integrations/pure/export-dcat";
|
|
@@ -241,8 +242,40 @@ export const IFR: OntologyPublication = {
|
|
|
241
242
|
license: CC0,
|
|
242
243
|
};
|
|
243
244
|
|
|
245
|
+
/** The ontology of Kanon (commons 0033-kanon), as it is published. */
|
|
246
|
+
export const KANON: OntologyPublication = {
|
|
247
|
+
name: "kanon",
|
|
248
|
+
ns: { prefix: "kanon", iri: kanonOntology.KANON.iri },
|
|
249
|
+
idNs: { prefix: "mzid", iri: MZID.iri },
|
|
250
|
+
curies: [
|
|
251
|
+
["kanon", kanonOntology.KANON.iri],
|
|
252
|
+
["mz", MZ.iri],
|
|
253
|
+
["xsd", "http://www.w3.org/2001/XMLSchema#"],
|
|
254
|
+
["rdfs", "http://www.w3.org/2000/01/rdf-schema#"],
|
|
255
|
+
["skos", "http://www.w3.org/2004/02/skos/core#"],
|
|
256
|
+
["dcterms", "http://purl.org/dc/terms/"],
|
|
257
|
+
["prov", "http://www.w3.org/ns/prov#"],
|
|
258
|
+
["sh", "http://www.w3.org/ns/shacl#"],
|
|
259
|
+
],
|
|
260
|
+
files: kanonOntology.files,
|
|
261
|
+
ontology: kanonOntology.kanonOntology,
|
|
262
|
+
classes: kanonOntology.classes,
|
|
263
|
+
properties: kanonOntology.properties,
|
|
264
|
+
terms: kanonOntology.terms,
|
|
265
|
+
schemas: [kanonOntology.Layer],
|
|
266
|
+
lists: listsOf("kanon", [["Layer", kanonOntology.layers]]),
|
|
267
|
+
source: "commons/ontology/src/kanon/*.ts",
|
|
268
|
+
run: RUN,
|
|
269
|
+
shapes: { prefix: "kanonsh", iri: "https://www.intellectualfrontiers.com/ontology/kanon-shapes#" },
|
|
270
|
+
schemasIri: "https://www.intellectualfrontiers.com/ontology/kanon-schemas",
|
|
271
|
+
sssomSetId: "https://www.intellectualfrontiers.com/ontology/kanon-mappings",
|
|
272
|
+
sssomCuries: { dcterms: "http://purl.org/dc/terms/", prov: "http://www.w3.org/ns/prov#", sh: "http://www.w3.org/ns/shacl#" },
|
|
273
|
+
viewTitle: "Kanon: the ontology",
|
|
274
|
+
license: CC0,
|
|
275
|
+
};
|
|
276
|
+
|
|
244
277
|
/** The ontologies of commons that are published, each from its own typed modules: Mizan's, then the ones its specifications define. */
|
|
245
|
-
export const publications: readonly OntologyPublication[] = [MIZAN, IFCCM, IFQS, IFR];
|
|
278
|
+
export const publications: readonly OntologyPublication[] = [MIZAN, IFCCM, IFQS, IFR, KANON];
|
|
246
279
|
|
|
247
280
|
/** Where the generated files are downloaded from: this repository's `commons/` folder on its default branch. */
|
|
248
281
|
const DOWNLOAD_BASE = "https://raw.githubusercontent.com/intellectual-frontiers/.github/main/commons/";
|
package/src/libraries.ts
CHANGED
|
@@ -35,12 +35,14 @@ import {
|
|
|
35
35
|
formatDecodeError,
|
|
36
36
|
literal,
|
|
37
37
|
object,
|
|
38
|
+
unknownValue,
|
|
38
39
|
string,
|
|
39
40
|
err,
|
|
40
41
|
ok,
|
|
41
42
|
type Result,
|
|
42
43
|
} from "@intellectual-frontiers/core";
|
|
43
44
|
import { exportedLiteral } from "@intellectual-frontiers/formats/ts-literal";
|
|
45
|
+
import { decodeTable, type Table } from "@intellectual-frontiers/kanon";
|
|
44
46
|
import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
45
47
|
import { stdio } from "@intellectual-frontiers/system";
|
|
46
48
|
import { spawn } from "@intellectual-frontiers/system/proc";
|
|
@@ -82,8 +84,13 @@ export type Library = {
|
|
|
82
84
|
readonly summary?: string;
|
|
83
85
|
/** Where it is published: always `github` (the GitHub package registry of the organization), and `npm` as well where a decision about that package has made it so (FR-015 and FR-016). */
|
|
84
86
|
readonly distribution: readonly Registry[];
|
|
87
|
+
/** The table of its layers where it is built to Kanon (commons 0033-kanon FR-010); none where it is not. */
|
|
88
|
+
readonly kanon?: Table;
|
|
85
89
|
};
|
|
86
90
|
|
|
91
|
+
/** The lowest conformance level that requires a library to declare `kanon`; none yet (0033-kanon FR-014, OQ-1): a level asks for it by naming itself here. */
|
|
92
|
+
export const KANON_REQUIRED_FROM: LevelKey | undefined = undefined;
|
|
93
|
+
|
|
87
94
|
/** The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018). */
|
|
88
95
|
export const REGISTRIES = ["github", "npm"] as const;
|
|
89
96
|
export type Registry = (typeof REGISTRIES)[number];
|
|
@@ -104,9 +111,9 @@ const nameDecoder: Decoder<string> = (input, path = "$") => {
|
|
|
104
111
|
};
|
|
105
112
|
const body = object(
|
|
106
113
|
{ name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) },
|
|
107
|
-
{ level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)) },
|
|
114
|
+
{ level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue },
|
|
108
115
|
);
|
|
109
|
-
const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution"] as const;
|
|
116
|
+
const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon"] as const;
|
|
110
117
|
|
|
111
118
|
/** The manifest read from the text of its file: `export const library = { ... }` and no other export, read as data and never run (0027-commons-libraries FR-012). */
|
|
112
119
|
export function decodeLibrarySource(source: string): Result<Library, string> {
|
|
@@ -130,6 +137,12 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
|
|
|
130
137
|
return err(
|
|
131
138
|
"library.distribution includes github: a library is published to the GitHub package registry whatever else it is published to (FR-015, FR-016)",
|
|
132
139
|
);
|
|
140
|
+
let kanon: Table | undefined;
|
|
141
|
+
if (v.kanon !== undefined) {
|
|
142
|
+
const t = decodeTable(v.kanon);
|
|
143
|
+
if (t.kind === "err") return err(`library.${t.error} (0033-kanon FR-010)`);
|
|
144
|
+
kanon = t.value;
|
|
145
|
+
}
|
|
133
146
|
return ok({
|
|
134
147
|
name: v.name,
|
|
135
148
|
level: v.level ?? DEFAULT_LIBRARY_LEVEL,
|
|
@@ -139,6 +152,7 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
|
|
|
139
152
|
exports: v.exports,
|
|
140
153
|
...(v.summary === undefined ? {} : { summary: v.summary }),
|
|
141
154
|
distribution,
|
|
155
|
+
...(kanon === undefined ? {} : { kanon }),
|
|
142
156
|
});
|
|
143
157
|
}
|
|
144
158
|
|
|
@@ -231,6 +245,12 @@ export function manifestFindings(repo: string): readonly string[] {
|
|
|
231
245
|
found.push(
|
|
232
246
|
`commons/${f.dir}: the manifest declares ${l.level} and the verify script does not run the Mizan check with --level ${l.level} (0028-conformance-levels FR-013)`,
|
|
233
247
|
);
|
|
248
|
+
if (l.kanon !== undefined && !verifyText.includes("kanon/src/check.ts"))
|
|
249
|
+
found.push(
|
|
250
|
+
`commons/${f.dir}: the manifest declares kanon and the verify script does not run the check of the table (bun ../kanon/src/check.ts) (0033-kanon FR-014)`,
|
|
251
|
+
);
|
|
252
|
+
if (KANON_REQUIRED_FROM !== undefined && rankOf(l.level) >= rankOf(KANON_REQUIRED_FROM) && l.kanon === undefined)
|
|
253
|
+
found.push(`commons/${f.dir}: the manifest declares ${l.level}, which requires kanon, and declares none (0033-kanon FR-014)`);
|
|
234
254
|
}
|
|
235
255
|
return found;
|
|
236
256
|
}
|
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. */
|
|
@@ -195,6 +195,14 @@ export const LIBRARY_CI: Readonly<Record<string, LibraryCi>> = {
|
|
|
195
195
|
nodeTests: 'node --test "suite/**/*.test.ts"',
|
|
196
196
|
systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
|
|
197
197
|
},
|
|
198
|
+
kanon: {
|
|
199
|
+
comment: lines(
|
|
200
|
+
"Kanon, the pattern of a library built in three layers (commons 0033-kanon): its own `verify` (the compiler, the specification checker, the trace check, its tests and the",
|
|
201
|
+
"packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.",
|
|
202
|
+
).trimEnd(),
|
|
203
|
+
nodeTests: 'node --test "suite/**/*.test.ts"',
|
|
204
|
+
systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
|
|
205
|
+
},
|
|
198
206
|
telemetry: {
|
|
199
207
|
comment: lines(
|
|
200
208
|
"Telemetry, OpenTelemetry-native signals as one typed library, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the",
|