@intellectual-frontiers/libraries 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/affected.d.ts +28 -0
- package/dist/affected.js +250 -0
- package/dist/changes.d.ts +27 -0
- package/dist/changes.js +470 -0
- package/dist/check.d.ts +15 -0
- package/dist/check.js +198 -0
- package/dist/generate-ontology.d.ts +37 -0
- package/dist/generate-ontology.js +293 -0
- package/dist/generate-workflows.d.ts +12 -0
- package/dist/generate-workflows.js +102 -0
- package/dist/imports/nist-sp-800-53.import.d.ts +33 -0
- package/dist/imports/nist-sp-800-53.import.js +34 -0
- package/dist/imports/schema-org.import.d.ts +33 -0
- package/dist/imports/schema-org.import.js +31 -0
- package/dist/install-bun.d.ts +1 -0
- package/dist/install-bun.js +58 -0
- package/dist/libraries.d.ts +79 -0
- package/dist/libraries.js +386 -0
- package/dist/mod.d.ts +16 -0
- package/dist/mod.js +16 -0
- package/dist/newer.d.ts +27 -0
- package/dist/newer.js +147 -0
- package/dist/oscal-register.d.ts +65 -0
- package/dist/oscal-register.js +344 -0
- package/dist/pack-library.d.ts +47 -0
- package/dist/pack-library.js +498 -0
- package/dist/pins.d.ts +15 -0
- package/dist/pins.js +29 -0
- package/dist/publish-ontology.d.ts +160 -0
- package/dist/publish-ontology.js +227 -0
- package/dist/versions.d.ts +26 -0
- package/dist/versions.js +556 -0
- package/dist/workflows/definitions.d.ts +65 -0
- package/dist/workflows/definitions.js +619 -0
- package/dist/workflows/mod.d.ts +10 -0
- package/dist/workflows/mod.js +10 -0
- package/dist/workflows/model.d.ts +143 -0
- package/dist/workflows/model.js +81 -0
- package/dist/workflows/render.d.ts +9 -0
- package/dist/workflows/render.js +179 -0
- package/package.json +129 -4
- package/src/affected.ts +265 -0
- package/src/changes.ts +546 -0
- package/src/check.ts +223 -0
- package/src/generate-ontology.ts +350 -0
- package/src/generate-workflows.ts +103 -0
- package/src/imports/nist-sp-800-53.import.ts +36 -0
- package/src/imports/schema-org.import.ts +31 -0
- package/src/install-bun.ts +53 -0
- package/src/libraries.ts +385 -0
- package/src/mod.ts +16 -0
- package/src/newer.ts +154 -0
- package/src/oscal-register.ts +443 -0
- package/src/pack-library.ts +522 -0
- package/src/pins.ts +30 -0
- package/src/publish-ontology.ts +354 -0
- package/src/versions.ts +594 -0
- package/src/workflows/definitions.ts +855 -0
- package/src/workflows/mod.ts +30 -0
- package/src/workflows/model.ts +187 -0
- package/src/workflows/render.ts +176 -0
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { type SourceFile } from "@intellectual-frontiers/mizan/trace";
|
|
2
|
+
import { type SpecText } from "@intellectual-frontiers/mizan/rules";
|
|
3
|
+
/** What the register says enforces a requirement (0003-mizan FR-005): a check, a gate, a person's review, or nothing. */
|
|
4
|
+
export type Mechanism = "check" | "gate" | "review" | "none";
|
|
5
|
+
/** A requirement as the register holds it. */
|
|
6
|
+
export type RegisterRow = {
|
|
7
|
+
/** The requirement, `NNNN-slug FR-nnn`. */
|
|
8
|
+
readonly requirement: string;
|
|
9
|
+
readonly spec: string;
|
|
10
|
+
readonly id: string;
|
|
11
|
+
/** The OSCAL `control-id`, `spec-<slug>.<fr>` in lower case. */
|
|
12
|
+
readonly controlId: string;
|
|
13
|
+
/** The first sentence of the requirement, cut to 160 characters. */
|
|
14
|
+
readonly title: string;
|
|
15
|
+
/** The status of its specification (Draft, Active, ...), or `unknown`. */
|
|
16
|
+
readonly status: string;
|
|
17
|
+
readonly mechanism: Mechanism;
|
|
18
|
+
/** Who enforces it, as `enforcement.tsv` says (`-` for none, `reviewed.tsv` for a row of that file). */
|
|
19
|
+
readonly by: string;
|
|
20
|
+
readonly note: string;
|
|
21
|
+
/** The test files that prove it, sorted. */
|
|
22
|
+
readonly files: readonly string[];
|
|
23
|
+
};
|
|
24
|
+
/** What the register is made from: the specifications, the text of each `reviewed.tsv`, the text of `enforcement.tsv` and the tests. */
|
|
25
|
+
export type RegisterInput = {
|
|
26
|
+
/** The name the documents give the folder. */
|
|
27
|
+
readonly label: string;
|
|
28
|
+
readonly specs: readonly SpecText[];
|
|
29
|
+
/** The text of a specification's `reviewed.tsv`, by its slug. */
|
|
30
|
+
readonly reviewed: ReadonlyMap<string, string>;
|
|
31
|
+
readonly enforcement: string;
|
|
32
|
+
readonly tests: readonly SourceFile[];
|
|
33
|
+
};
|
|
34
|
+
/** The file of the component definition, from the folder it is written in. */
|
|
35
|
+
export declare const COMPONENT_FILE = "mizan-register.auto.oscal.json";
|
|
36
|
+
/** The file of the assessment results, from the folder it is written in. */
|
|
37
|
+
export declare const RESULTS_FILE = "mizan-register-results.auto.oscal.json";
|
|
38
|
+
/** The command that writes the files again. */
|
|
39
|
+
export declare const RUN = "bun commons/libraries/src/oscal-register.ts";
|
|
40
|
+
/** The OSCAL `control-id` of a requirement: a token that starts with a letter (`spec-0003-mizan.fr-011`). */
|
|
41
|
+
export declare function controlIdOf(spec: string, id: string): string;
|
|
42
|
+
/** The register's rows: every requirement of every specification in the order of the specifications, with what enforces it and the test files that prove it (0003-mizan FR-021). */
|
|
43
|
+
export declare function registerRows(input: RegisterInput): readonly RegisterRow[];
|
|
44
|
+
/** The two documents, as the text of their files. */
|
|
45
|
+
export type RegisterDocuments = {
|
|
46
|
+
readonly componentDefinition: string;
|
|
47
|
+
readonly assessmentResults: string;
|
|
48
|
+
};
|
|
49
|
+
/**
|
|
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.
|
|
52
|
+
*/
|
|
53
|
+
export declare function registerDocuments(input: RegisterInput, register?: RegisterOptions): Promise<RegisterDocuments>;
|
|
54
|
+
/** 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. */
|
|
55
|
+
export type RegisterOptions = {
|
|
56
|
+
/** The path of the proof register's file, where it is not `<root>/enforcement.tsv`. A file that is not there is an error, not an empty register. */
|
|
57
|
+
readonly enforcement?: string;
|
|
58
|
+
};
|
|
59
|
+
/**
|
|
60
|
+
* The specifications of a folder, the text of each `reviewed.tsv`, and the proof register, read from disk, with the tests of the given folders of a repository (by path from it). The register is
|
|
61
|
+
* `<root>/enforcement.tsv` unless `options.enforcement` names another file (0003-mizan FR-043).
|
|
62
|
+
*/
|
|
63
|
+
export declare function readRegisterInput(root: string, repo: string, testFolders: readonly string[], label: string, options?: RegisterOptions): Promise<RegisterInput>;
|
|
64
|
+
/** The command line. Returns the exit status: 0, or 1 with `--check` where a file is not what the folder makes. */
|
|
65
|
+
export declare function main(argv: readonly string[]): Promise<number>;
|
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The proof register of a Mizan folder as OSCAL (commons 0003-mizan FR-011, FR-016, FR-021 to FR-023): its `enforcement.tsv` (and the `reviewed.tsv` of a specification, read as
|
|
3
|
+
* `review` rows) as an OSCAL `component-definition`, each requirement an `implemented-requirement`, and the proofs the tests name (`proves([...])`, `// Proves:`) as OSCAL
|
|
4
|
+
* `assessment-results`.
|
|
5
|
+
*
|
|
6
|
+
* bun commons/libraries/src/oscal-register.ts write commons/generated/mizan-register.auto.oscal.json and mizan-register-results.auto.oscal.json
|
|
7
|
+
* bun commons/libraries/src/oscal-register.ts --check write nothing; exit 1 naming each file that is not what the folder makes
|
|
8
|
+
* --root DIR the folder (default commons/spec-kit) --repo DIR the repository the tests are searched in (default commons' repository)
|
|
9
|
+
* --register DIR the folder of `enforcement.tsv` (default: the folder of --root) --enforcement FILE the register's file itself (default: enforcement.tsv of the register folder)
|
|
10
|
+
* --tests A,B the folders of tests, from the repository (default tests,commons) --out DIR where the files go (default commons/generated)
|
|
11
|
+
* --label TEXT the name the documents give the folder (default `Intellectual Frontiers commons`)
|
|
12
|
+
*
|
|
13
|
+
* @remarks
|
|
14
|
+
* The two documents are written by the kernel's OSCAL writers (`kernel/oscal.ts`, OSCAL 1.2.3), so that the same bytes come for the same folder: every `uuid` is a version 5 UUID of a
|
|
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
|
+
* 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
|
+
* 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
|
|
18
|
+
* proves a requirement and its note, stays in `enforcement.tsv`, so that no proof is written twice.
|
|
19
|
+
*
|
|
20
|
+
* @limits
|
|
21
|
+
* It reads which tests name a requirement, never whether they pass (that is the test run's evidence, 0008-test-evidence), and it counts a proof wherever a `proves(` call or a
|
|
22
|
+
* `// Proves:` line is, a fixture string included, as the trace check does. It does not write a POA&M: a `gap` is a finding of the results.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```ts
|
|
26
|
+
* import { registerRows } from "./oscal-register.ts";
|
|
27
|
+
* registerRows({
|
|
28
|
+
* label: "x",
|
|
29
|
+
* specs: [{ slug: "0001-x", spec: "**Status:** Active\n- **FR-001**: It MUST work.\n" }],
|
|
30
|
+
* reviewed: new Map(),
|
|
31
|
+
* enforcement: "0001-x FR-001\tcheck\trepo: bun test\tproved\n",
|
|
32
|
+
* tests: [{ path: "tests/x.test.ts", text: 'proves(["0001-x FR-001"], "it works", () => {});' }],
|
|
33
|
+
* }).map((r) => [r.requirement, r.mechanism, r.files]); // [["0001-x FR-001", "check", ["tests/x.test.ts"]]]
|
|
34
|
+
* ```
|
|
35
|
+
*
|
|
36
|
+
* Spec: 0001-libraries FR-008
|
|
37
|
+
*
|
|
38
|
+
* @module
|
|
39
|
+
*/
|
|
40
|
+
import process from "node:process";
|
|
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
|
+
import { sha256 } from "@intellectual-frontiers/crypto/sha256";
|
|
45
|
+
import { parseSpec, proofsOf } from "@intellectual-frontiers/mizan/trace";
|
|
46
|
+
import { NAMESPACE_URL, uuidV5 } from "@intellectual-frontiers/crypto/uuid";
|
|
47
|
+
import { existsSync, mkdirSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
48
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
49
|
+
import { readSources } from "@intellectual-frontiers/mizan/host/trace";
|
|
50
|
+
import { sentenceOf } from "@intellectual-frontiers/mizan/rules";
|
|
51
|
+
/** The file of the component definition, from the folder it is written in. */
|
|
52
|
+
export const COMPONENT_FILE = "mizan-register.auto.oscal.json";
|
|
53
|
+
/** The file of the assessment results, from the folder it is written in. */
|
|
54
|
+
export const RESULTS_FILE = "mizan-register-results.auto.oscal.json";
|
|
55
|
+
/** The command that writes the files again. */
|
|
56
|
+
export const RUN = "bun commons/libraries/src/oscal-register.ts";
|
|
57
|
+
/** The instant the documents give as their `last-modified`: the register reads no clock (0003-mizan FR-022). */
|
|
58
|
+
const NO_CLOCK = instantOf("1970-01-01T00:00:00Z") ?? absurdInstant();
|
|
59
|
+
/** Never returns: the epoch is an instant, so `instantOf` has no reason to refuse it. */
|
|
60
|
+
function absurdInstant() {
|
|
61
|
+
throw new Error("1970-01-01T00:00:00Z is an instant");
|
|
62
|
+
}
|
|
63
|
+
const REGISTER_IRI = "https://www.intellectualfrontiers.com/ontology/mizan-register";
|
|
64
|
+
const isMechanism = (x) => x === "check" || x === "gate" || x === "review" || x === "none";
|
|
65
|
+
const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
|
|
66
|
+
const numberOf = (id) => Number(/^FR-(\d+)/.exec(id)?.[1] ?? "NaN");
|
|
67
|
+
/** The OSCAL `control-id` of a requirement: a token that starts with a letter (`spec-0003-mizan.fr-011`). */
|
|
68
|
+
export function controlIdOf(spec, id) {
|
|
69
|
+
return `spec-${spec}.${id.toLowerCase()}`;
|
|
70
|
+
}
|
|
71
|
+
/** The rows of `enforcement.tsv` by requirement: its four columns; comment lines, blank lines and the header are not rows. */
|
|
72
|
+
function enforcementRows(text) {
|
|
73
|
+
const out = new Map();
|
|
74
|
+
for (const line of text.replaceAll("\r\n", "\n").split("\n")) {
|
|
75
|
+
if (line.trim() === "" || line.startsWith("#"))
|
|
76
|
+
continue;
|
|
77
|
+
const [req = "", mechanism = "", by = "", ...note] = line.split("\t");
|
|
78
|
+
if (req === "requirement" || !isMechanism(mechanism))
|
|
79
|
+
continue;
|
|
80
|
+
out.set(req.trim(), { mechanism, by: by.trim(), note: note.join("\t").trim() });
|
|
81
|
+
}
|
|
82
|
+
return out;
|
|
83
|
+
}
|
|
84
|
+
/** The rows of a `reviewed.tsv` as requirement ids and reasons (`slug FR-nnn<TAB>reason`), for the specification named `slug`. */
|
|
85
|
+
function reviewedRows(slug, text) {
|
|
86
|
+
const out = new Map();
|
|
87
|
+
for (const raw of text.replaceAll("\r\n", "\n").split("\n")) {
|
|
88
|
+
const line = raw.trim();
|
|
89
|
+
if (line === "" || line.startsWith("#"))
|
|
90
|
+
continue;
|
|
91
|
+
const [req = "", ...reason] = line.split("\t");
|
|
92
|
+
const m = /^(\S+)\s+(FR-\d{3}[a-z]?)$/.exec(req.trim());
|
|
93
|
+
if (m?.[1] === slug && m[2] !== undefined)
|
|
94
|
+
out.set(m[2], reason.join("\t").trim());
|
|
95
|
+
}
|
|
96
|
+
return out;
|
|
97
|
+
}
|
|
98
|
+
/** The ids of a specification's requirements that a citation names, ranges expanded; an id the specification lacks names nothing. */
|
|
99
|
+
function idsOf(have, c) {
|
|
100
|
+
if (c.kind === "one")
|
|
101
|
+
return have.includes(c.id) ? [c.id] : [];
|
|
102
|
+
if (!have.includes(c.from) || !have.includes(c.to))
|
|
103
|
+
return [];
|
|
104
|
+
const [lo, hi] = [numberOf(c.from), numberOf(c.to)];
|
|
105
|
+
return have.filter((id) => numberOf(id) >= lo && numberOf(id) <= hi);
|
|
106
|
+
}
|
|
107
|
+
/** The first sentence of a requirement's text, white space collapsed and cut to 160 characters. */
|
|
108
|
+
function titleOf(sentence) {
|
|
109
|
+
const one = sentence.replace(/\s+/g, " ").trim();
|
|
110
|
+
const end = one.search(/[.;:] /);
|
|
111
|
+
const first = end > 20 ? one.slice(0, end + 1) : one;
|
|
112
|
+
return first.length > 160 ? `${first.slice(0, 157)}...` : first;
|
|
113
|
+
}
|
|
114
|
+
/** The register's rows: every requirement of every specification in the order of the specifications, with what enforces it and the test files that prove it (0003-mizan FR-021). */
|
|
115
|
+
export function registerRows(input) {
|
|
116
|
+
const enforced = enforcementRows(input.enforcement);
|
|
117
|
+
const slugs = new Map(input.specs.map((s) => [s.slug, parseSpec(s.slug, s.spec).requirements.map((r) => r.id)]));
|
|
118
|
+
const proved = new Map();
|
|
119
|
+
for (const t of [...input.tests].sort((a, b) => byText(a.path, b.path))) {
|
|
120
|
+
for (const p of proofsOf(t.text)) {
|
|
121
|
+
const have = slugs.get(p.spec);
|
|
122
|
+
if (have === undefined)
|
|
123
|
+
continue;
|
|
124
|
+
for (const id of idsOf(have, p.requirement)) {
|
|
125
|
+
const key = `${p.spec} ${id}`;
|
|
126
|
+
const files = proved.get(key) ?? new Set();
|
|
127
|
+
files.add(t.path);
|
|
128
|
+
proved.set(key, files);
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
return input.specs.flatMap((s) => {
|
|
133
|
+
const parsed = parseSpec(s.slug, s.spec);
|
|
134
|
+
const lines = s.spec.split("\n");
|
|
135
|
+
const reviewed = reviewedRows(s.slug, input.reviewed.get(s.slug) ?? "");
|
|
136
|
+
return parsed.requirements.map((r) => {
|
|
137
|
+
const requirement = `${s.slug} ${r.id}`;
|
|
138
|
+
const row = enforced.get(requirement);
|
|
139
|
+
const reason = reviewed.get(r.id);
|
|
140
|
+
const [mechanism, by, note] = row !== undefined
|
|
141
|
+
? [row.mechanism, row.by, row.note]
|
|
142
|
+
: reason !== undefined
|
|
143
|
+
? ["review", "reviewed.tsv", reason]
|
|
144
|
+
: ["none", "-", "no row in enforcement.tsv"];
|
|
145
|
+
return {
|
|
146
|
+
requirement,
|
|
147
|
+
spec: s.slug,
|
|
148
|
+
id: r.id,
|
|
149
|
+
controlId: controlIdOf(s.slug, r.id),
|
|
150
|
+
title: titleOf(sentenceOf(lines, r.line - 1)),
|
|
151
|
+
status: parsed.status ?? "unknown",
|
|
152
|
+
mechanism,
|
|
153
|
+
by,
|
|
154
|
+
note,
|
|
155
|
+
files: [...(proved.get(requirement) ?? [])].sort(byText),
|
|
156
|
+
};
|
|
157
|
+
});
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
function summaryOf(row, catalog) {
|
|
161
|
+
return {
|
|
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 };
|
|
173
|
+
if (row.files.length > 0)
|
|
174
|
+
return Promise.all(row.files.map(async (file) => ({
|
|
175
|
+
...base,
|
|
176
|
+
status: "pass",
|
|
177
|
+
outcome: "pass",
|
|
178
|
+
title: `proved by ${file}`,
|
|
179
|
+
detail: `${row.requirement} is named by a proof in ${file}.`,
|
|
180
|
+
evidence: [await sha256(tests.get(file) ?? "")],
|
|
181
|
+
})));
|
|
182
|
+
if (row.mechanism === "review")
|
|
183
|
+
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
|
+
},
|
|
193
|
+
];
|
|
194
|
+
const status = "gap";
|
|
195
|
+
return [
|
|
196
|
+
{
|
|
197
|
+
...base,
|
|
198
|
+
status,
|
|
199
|
+
outcome: status,
|
|
200
|
+
title: "no test proves it",
|
|
201
|
+
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
|
+
},
|
|
204
|
+
];
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* 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.
|
|
209
|
+
*/
|
|
210
|
+
export async function registerDocuments(input, register = {}) {
|
|
211
|
+
const rows = registerRows(register.enforcement === undefined ? input : { ...input, enforcement: enforcementAt(register.enforcement) });
|
|
212
|
+
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
|
+
const tests = new Map(input.tests.map((t) => [t.path, t.text]));
|
|
216
|
+
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
|
+
const namespace = await uuidV5(NAMESPACE_URL, REGISTER_IRI);
|
|
218
|
+
const options = (what) => ({
|
|
219
|
+
namespace,
|
|
220
|
+
lastModified: NO_CLOCK,
|
|
221
|
+
version,
|
|
222
|
+
propNamespace: `${REGISTER_IRI}#`,
|
|
223
|
+
title: `Mizan register of ${input.label}: ${what} (generated by ${RUN}; do not edit)`,
|
|
224
|
+
controlId: (ref) => ref.id,
|
|
225
|
+
});
|
|
226
|
+
const definition = await componentDefinition(controls, {
|
|
227
|
+
id: input.label,
|
|
228
|
+
title: input.label,
|
|
229
|
+
description: `${input.label}, whose requirements are written in the specifications of its Mizan folder.`,
|
|
230
|
+
type: "software",
|
|
231
|
+
}, options("component definition"));
|
|
232
|
+
const byControl = new Map(rows.map((r) => [r.controlId, r]));
|
|
233
|
+
const inner = definition["component-definition"];
|
|
234
|
+
const withMechanism = {
|
|
235
|
+
"component-definition": {
|
|
236
|
+
...inner,
|
|
237
|
+
components: inner.components.map((c) => ({
|
|
238
|
+
...c,
|
|
239
|
+
...(c["control-implementations"] === undefined
|
|
240
|
+
? {}
|
|
241
|
+
: {
|
|
242
|
+
"control-implementations": c["control-implementations"].map((ci) => ({
|
|
243
|
+
...ci,
|
|
244
|
+
"implemented-requirements": ci["implemented-requirements"].map((ir) => {
|
|
245
|
+
const row = byControl.get(ir["control-id"]);
|
|
246
|
+
return row === undefined
|
|
247
|
+
? ir
|
|
248
|
+
: {
|
|
249
|
+
...ir,
|
|
250
|
+
props: [
|
|
251
|
+
...ir.props,
|
|
252
|
+
{ name: "mechanism", ns: `${REGISTER_IRI}#`, value: row.mechanism },
|
|
253
|
+
{ name: "proofs", ns: `${REGISTER_IRI}#`, value: String(row.files.length) },
|
|
254
|
+
],
|
|
255
|
+
};
|
|
256
|
+
}),
|
|
257
|
+
})),
|
|
258
|
+
}),
|
|
259
|
+
})),
|
|
260
|
+
},
|
|
261
|
+
};
|
|
262
|
+
const assessment = {
|
|
263
|
+
pack: { id: input.label, title: `Mizan register of ${input.label}` },
|
|
264
|
+
at: NO_CLOCK,
|
|
265
|
+
controls,
|
|
266
|
+
subjects: [...new Set(rows.map((r) => r.spec))].sort(byText).map((id) => ({ kind: "specification", id })),
|
|
267
|
+
findings: (await Promise.all(pairs.map((p) => findingsOf(p.row, p.control, tests)))).flat(),
|
|
268
|
+
};
|
|
269
|
+
const results = await assessmentResults(assessment, options("assessment results"));
|
|
270
|
+
return { componentDefinition: renderOscal(withMechanism), assessmentResults: renderOscal(results) };
|
|
271
|
+
}
|
|
272
|
+
/** 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
|
+
function enforcementAt(path) {
|
|
274
|
+
if (!existsSync(path))
|
|
275
|
+
throw new Error(`the proof register ${path} does not exist`);
|
|
276
|
+
return readTextFileSync(path).replaceAll("\r\n", "\n");
|
|
277
|
+
}
|
|
278
|
+
/**
|
|
279
|
+
* The specifications of a folder, the text of each `reviewed.tsv`, and the proof register, read from disk, with the tests of the given folders of a repository (by path from it). The register is
|
|
280
|
+
* `<root>/enforcement.tsv` unless `options.enforcement` names another file (0003-mizan FR-043).
|
|
281
|
+
*/
|
|
282
|
+
export async function readRegisterInput(root, repo, testFolders, label, options = {}) {
|
|
283
|
+
const specs = [];
|
|
284
|
+
const reviewed = new Map();
|
|
285
|
+
const folder = `${root.replace(/[\\/]$/, "")}/specs`;
|
|
286
|
+
if (existsSync(folder))
|
|
287
|
+
for (const e of readDirSync(folder).sort((a, b) => byText(a.name, b.name))) {
|
|
288
|
+
if (!e.isDirectory || !existsSync(`${folder}/${e.name}/spec.md`))
|
|
289
|
+
continue;
|
|
290
|
+
specs.push({ slug: e.name, spec: readTextFileSync(`${folder}/${e.name}/spec.md`).replaceAll("\r\n", "\n") });
|
|
291
|
+
if (existsSync(`${folder}/${e.name}/reviewed.tsv`))
|
|
292
|
+
reviewed.set(e.name, readTextFileSync(`${folder}/${e.name}/reviewed.tsv`).replaceAll("\r\n", "\n"));
|
|
293
|
+
}
|
|
294
|
+
const enforcement = options.enforcement ?? `${root.replace(/[\\/]$/, "")}/enforcement.tsv`;
|
|
295
|
+
const tests = await readSources(repo, testFolders.filter((t) => existsSync(`${repo.replace(/[\\/]$/, "")}/${t}`)), [".test.ts"]);
|
|
296
|
+
return {
|
|
297
|
+
label,
|
|
298
|
+
specs,
|
|
299
|
+
reviewed,
|
|
300
|
+
enforcement: options.enforcement !== undefined
|
|
301
|
+
? enforcementAt(enforcement)
|
|
302
|
+
: existsSync(enforcement)
|
|
303
|
+
? readTextFileSync(enforcement).replaceAll("\r\n", "\n")
|
|
304
|
+
: "",
|
|
305
|
+
tests: [...tests].map((t) => ({ ...t, text: t.text.replaceAll("\r\n", "\n") })).sort((a, b) => byText(a.path, b.path)),
|
|
306
|
+
};
|
|
307
|
+
}
|
|
308
|
+
/** The command line. Returns the exit status: 0, or 1 with `--check` where a file is not what the folder makes. */
|
|
309
|
+
export async function main(argv) {
|
|
310
|
+
const arg = (name) => {
|
|
311
|
+
const i = argv.indexOf(name);
|
|
312
|
+
return i >= 0 ? argv[i + 1] : undefined;
|
|
313
|
+
};
|
|
314
|
+
const commons = fileURLToPath(new URL("../..", import.meta.url)).replace(/[\\/]$/, "");
|
|
315
|
+
const root = arg("--root") ?? `${commons}/spec-kit`;
|
|
316
|
+
const register = arg("--register") ?? root;
|
|
317
|
+
const enforcement = arg("--enforcement") ?? (arg("--register") === undefined ? undefined : `${register.replace(/[\\/]$/, "")}/enforcement.tsv`);
|
|
318
|
+
const repo = arg("--repo") ?? fileURLToPath(new URL("../../..", import.meta.url)).replace(/[\\/]$/, "");
|
|
319
|
+
const out = (arg("--out") ?? `${commons}/generated`).replace(/[\\/]$/, "");
|
|
320
|
+
const tests = (arg("--tests") ?? "tests,commons").split(",");
|
|
321
|
+
if (enforcement !== undefined && !existsSync(enforcement)) {
|
|
322
|
+
stdio.stderr.writeSync(`oscal-register: the proof register ${enforcement} does not exist\n`);
|
|
323
|
+
return 2;
|
|
324
|
+
}
|
|
325
|
+
const made = await registerDocuments(await readRegisterInput(root, repo, tests, arg("--label") ?? "Intellectual Frontiers commons", enforcement === undefined ? {} : { enforcement }));
|
|
326
|
+
const files = [
|
|
327
|
+
[COMPONENT_FILE, made.componentDefinition],
|
|
328
|
+
[RESULTS_FILE, made.assessmentResults],
|
|
329
|
+
];
|
|
330
|
+
if (argv.includes("--check")) {
|
|
331
|
+
const stale = files.filter(([name, text]) => !existsSync(`${out}/${name}`) || readTextFileSync(`${out}/${name}`).replaceAll("\r\n", "\n") !== text);
|
|
332
|
+
for (const [name] of stale)
|
|
333
|
+
stdio.stderr.writeSync(`${out}/${name} is not what the folder makes; run: ${RUN}\n`);
|
|
334
|
+
return stale.length > 0 ? 1 : 0;
|
|
335
|
+
}
|
|
336
|
+
mkdirSync(out, { recursive: true });
|
|
337
|
+
for (const [name, text] of files) {
|
|
338
|
+
writeTextFileSync(`${out}/${name}`, text);
|
|
339
|
+
stdio.stdout.writeSync(`wrote ${out}/${name}\n`);
|
|
340
|
+
}
|
|
341
|
+
return 0;
|
|
342
|
+
}
|
|
343
|
+
if (import.meta.main)
|
|
344
|
+
process.exitCode = await main(process.argv.slice(2));
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/** The scope of the packages of commons. */
|
|
2
|
+
export declare const SCOPE = "@intellectual-frontiers";
|
|
3
|
+
/** What is wrong with a package, one sentence each. */
|
|
4
|
+
export type Findings = readonly string[];
|
|
5
|
+
type Json = Readonly<Record<string, unknown>>;
|
|
6
|
+
/** The files under a folder, from the folder, in order (`node_modules` is not looked into). */
|
|
7
|
+
export declare function filesUnder(root: string, dir?: string): readonly string[];
|
|
8
|
+
/** The specifiers a source names, outside its documentation blocks. */
|
|
9
|
+
export declare const specifiersOf: (source: string) => readonly string[];
|
|
10
|
+
/** The package a bare specifier names (`@scope/name/sub` is `@scope/name`), or undefined for a relative path, a `node:` builtin or a `data:` URL. */
|
|
11
|
+
export declare function packageOf(specifier: string): string | undefined;
|
|
12
|
+
/** The declarations that the entries of a package reach, by relative imports from the `types` of each entry, and what is wrong on the way (a declaration that is not there). */
|
|
13
|
+
export declare function reachableDeclarations(stage: string, manifest: Json): {
|
|
14
|
+
readonly reached: ReadonlySet<string>;
|
|
15
|
+
readonly findings: Findings;
|
|
16
|
+
};
|
|
17
|
+
/** What is wrong with the package staged in a folder (the files of the tarball, `package/` unpacked): see the remarks of this module. */
|
|
18
|
+
export declare function inspectPackage(stage: string): Findings;
|
|
19
|
+
/** Writes the declarations with `.js` in the place of `.ts` in their relative specifiers. */
|
|
20
|
+
export declare function rewriteDeclarationSpecifiers(source: string): string;
|
|
21
|
+
/** The tarball's name for a package: `@scope/name` at a version is `scope-name-version.tgz`. */
|
|
22
|
+
export declare const tarballName: (name: string, version: string) => string;
|
|
23
|
+
export type Packed = {
|
|
24
|
+
readonly stage: string;
|
|
25
|
+
readonly tarball: string | undefined;
|
|
26
|
+
readonly findings: Findings;
|
|
27
|
+
readonly manifest: Json;
|
|
28
|
+
};
|
|
29
|
+
export type PackOptions = {
|
|
30
|
+
/** Types the compiler is given (`["node"]` for a library that names Node's). */
|
|
31
|
+
readonly types?: readonly string[];
|
|
32
|
+
/** A bundled package: the code of each entry and of each command is one file (`bun build`), and only the declarations the entries reach are published. */
|
|
33
|
+
readonly bundle?: {
|
|
34
|
+
/** The commands: their name, and the source that is the command's entry from the library's folder. */
|
|
35
|
+
readonly bin?: Readonly<Record<string, string>>;
|
|
36
|
+
/** The README that is published, where it is more than the common one. */
|
|
37
|
+
readonly readme?: string;
|
|
38
|
+
readonly keywords?: readonly string[];
|
|
39
|
+
/** Files of the library's folder that are published beside the others (`CREDITS.md`). */
|
|
40
|
+
readonly extraFiles?: readonly string[];
|
|
41
|
+
};
|
|
42
|
+
};
|
|
43
|
+
/** Builds and stages the package of the library at `root` (a folder `commons/<name>/` with a `package.json` and sources in `src/`), inspects it and, where nothing is wrong, packs it. */
|
|
44
|
+
export declare function packLibrary(root: string, options?: PackOptions): Promise<Packed>;
|
|
45
|
+
/** The command line of a library's `tools/pack.ts`: pack, print what was found (or the tarball) and the exit status. */
|
|
46
|
+
export declare function main(root: string, argv: readonly string[], options?: PackOptions): Promise<number>;
|
|
47
|
+
export {};
|