@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.
Files changed (63) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +8 -2
  3. package/dist/affected.d.ts +28 -0
  4. package/dist/affected.js +250 -0
  5. package/dist/changes.d.ts +27 -0
  6. package/dist/changes.js +470 -0
  7. package/dist/check.d.ts +15 -0
  8. package/dist/check.js +198 -0
  9. package/dist/generate-ontology.d.ts +37 -0
  10. package/dist/generate-ontology.js +293 -0
  11. package/dist/generate-workflows.d.ts +12 -0
  12. package/dist/generate-workflows.js +102 -0
  13. package/dist/imports/nist-sp-800-53.import.d.ts +33 -0
  14. package/dist/imports/nist-sp-800-53.import.js +34 -0
  15. package/dist/imports/schema-org.import.d.ts +33 -0
  16. package/dist/imports/schema-org.import.js +31 -0
  17. package/dist/install-bun.d.ts +1 -0
  18. package/dist/install-bun.js +58 -0
  19. package/dist/libraries.d.ts +79 -0
  20. package/dist/libraries.js +386 -0
  21. package/dist/mod.d.ts +16 -0
  22. package/dist/mod.js +16 -0
  23. package/dist/newer.d.ts +27 -0
  24. package/dist/newer.js +147 -0
  25. package/dist/oscal-register.d.ts +65 -0
  26. package/dist/oscal-register.js +344 -0
  27. package/dist/pack-library.d.ts +47 -0
  28. package/dist/pack-library.js +498 -0
  29. package/dist/pins.d.ts +15 -0
  30. package/dist/pins.js +29 -0
  31. package/dist/publish-ontology.d.ts +160 -0
  32. package/dist/publish-ontology.js +227 -0
  33. package/dist/versions.d.ts +26 -0
  34. package/dist/versions.js +556 -0
  35. package/dist/workflows/definitions.d.ts +65 -0
  36. package/dist/workflows/definitions.js +619 -0
  37. package/dist/workflows/mod.d.ts +10 -0
  38. package/dist/workflows/mod.js +10 -0
  39. package/dist/workflows/model.d.ts +143 -0
  40. package/dist/workflows/model.js +81 -0
  41. package/dist/workflows/render.d.ts +9 -0
  42. package/dist/workflows/render.js +179 -0
  43. package/package.json +129 -4
  44. package/src/affected.ts +265 -0
  45. package/src/changes.ts +546 -0
  46. package/src/check.ts +223 -0
  47. package/src/generate-ontology.ts +350 -0
  48. package/src/generate-workflows.ts +103 -0
  49. package/src/imports/nist-sp-800-53.import.ts +36 -0
  50. package/src/imports/schema-org.import.ts +31 -0
  51. package/src/install-bun.ts +53 -0
  52. package/src/libraries.ts +385 -0
  53. package/src/mod.ts +16 -0
  54. package/src/newer.ts +154 -0
  55. package/src/oscal-register.ts +443 -0
  56. package/src/pack-library.ts +522 -0
  57. package/src/pins.ts +30 -0
  58. package/src/publish-ontology.ts +354 -0
  59. package/src/versions.ts +594 -0
  60. package/src/workflows/definitions.ts +855 -0
  61. package/src/workflows/mod.ts +30 -0
  62. package/src/workflows/model.ts +187 -0
  63. package/src/workflows/render.ts +176 -0
package/src/newer.ts ADDED
@@ -0,0 +1,154 @@
1
+ /**
2
+ * Report the standards whose newest version is not the one pinned (commons 0018-standards-first FR-006, FR-014, FR-017).
3
+ *
4
+ * bun commons/libraries/src/newer.ts read commons/libraries/src/imports/*.import.ts, fetch each `latest` source and hold the findings against commons/spec-kit/mizan.newer.baseline.txt
5
+ * bun commons/libraries/src/newer.ts --imports DIR read the manifests of DIR
6
+ * bun commons/libraries/src/newer.ts --root DIR hold the findings against DIR/mizan.newer.baseline.txt (DIR holds `mizan.baseline.txt` too, as for `check.ts`)
7
+ * bun commons/libraries/src/newer.ts --write-baseline write the baseline from today's findings (to start it, or to shrink it: never to add a line to pass)
8
+ *
9
+ * A manifest of an import (0019-mizan-integrations FR-014) may name, beside its versioned `source`, a `latest` source: an URL that always serves the newest version of the
10
+ * standard (schema.org's `.../version/latest/...`, a repository's latest tag). This command fetches each one and gives one finding, `mizan/standard-newer`, where the SHA-256 of
11
+ * what it serves differs from the pin. It is opt-in and the only part of Mizan that needs the network: `check.ts` and `import.ts --check` never do, so the network never fails the offline
12
+ * check. Its exit status is 0 (nothing new), 1 (a finding the baseline does not hold, or a baseline line that no longer occurs) or 2 (a `latest` source that cannot be fetched, or a
13
+ * manifest that cannot be read, named with its reason).
14
+ *
15
+ * @limits
16
+ * It compares bytes, not versions: a source that changes its prefixes or its date changes the hash, and a person reads the difference. It reads the manifests of one folder.
17
+ *
18
+ * @example
19
+ * ```ts
20
+ * import { staleFindings } from "./newer.ts";
21
+ * staleFindings([{ file: "imports/x.import.ts", id: "x", version: "1", pin: "a".repeat(64), latest: "https://example.org/latest", sha256: "b".repeat(64) }]).length; // 1
22
+ * ```
23
+ *
24
+ * Spec: 0001-libraries FR-008
25
+ *
26
+ * @module
27
+ */
28
+ import process from "node:process";
29
+ import { fileURLToPath, pathToFileURL } from "node:url";
30
+ import { err, ok, type Result } from "@intellectual-frontiers/core";
31
+ import { sha256 } from "@intellectual-frontiers/crypto/sha256";
32
+ import { formatBaseline, judge, parseBaseline, passes, report } from "@intellectual-frontiers/mizan/trace";
33
+ import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
34
+ import { stdio } from "@intellectual-frontiers/system";
35
+ import { resolve } from "@intellectual-frontiers/system/path";
36
+ import { decodeManifest, isUrl } from "@intellectual-frontiers/mizan/integrations/host/import";
37
+ import type { MizanFinding } from "@intellectual-frontiers/mizan/rules";
38
+
39
+ /** A manifest that names a `latest` source: its file, the standard it pins (id, version, SHA-256) and the URL that always serves the newest. */
40
+ export type LatestManifest = {
41
+ readonly file: string;
42
+ readonly id: string;
43
+ readonly version: string;
44
+ readonly pin: string;
45
+ readonly latest: string;
46
+ };
47
+
48
+ /** A manifest with the SHA-256 of what its `latest` source serves. */
49
+ export type Fetched = LatestManifest & { readonly sha256: string };
50
+
51
+ const isRecord = (x: unknown): x is Readonly<Record<string, unknown>> => typeof x === "object" && x !== null && !Array.isArray(x);
52
+
53
+ /** The comment lines a baseline of this command begins with. */
54
+ export const NEWER_BASELINE_COMMENTS = [
55
+ "The standards whose latest source served other bytes than the pin when each was first held (commons 0018-standards-first FR-017).",
56
+ "A new finding fails the check, and so does a line below that no longer occurs: when you repin an import, delete its line.",
57
+ "Never add a line to make a check pass.",
58
+ ] as const;
59
+
60
+ /** The findings: one sentence for each manifest whose `latest` source serves other bytes than the pin (0018-standards-first FR-014). */
61
+ export function staleFindings(fetched: readonly Fetched[]): readonly MizanFinding[] {
62
+ return fetched.flatMap((f) =>
63
+ f.sha256 === f.pin
64
+ ? []
65
+ : [
66
+ {
67
+ file: f.file,
68
+ line: 1,
69
+ rule: "mizan/standard-newer" as const,
70
+ message: `${f.id} is pinned at version ${f.version} (SHA-256 ${f.pin}), and ${f.latest} now serves SHA-256 ${f.sha256}, so a newer version of the standard may be out`,
71
+ key: `mizan/standard-newer ${f.file} ${f.id} ${f.sha256}`,
72
+ },
73
+ ],
74
+ );
75
+ }
76
+
77
+ /** The manifests of a folder (`NAME.import.ts`, in the order of their names) that name a `latest` source, and a sentence for each that cannot be read. */
78
+ export async function readLatestManifests(
79
+ dir: string,
80
+ ): Promise<{ readonly manifests: readonly LatestManifest[]; readonly problems: readonly string[] }> {
81
+ const manifests: LatestManifest[] = [];
82
+ const problems: string[] = [];
83
+ const base = resolve(dir);
84
+ const folder = base.split(/[\\/]/).pop() ?? "imports";
85
+ if (!existsSync(base)) return { manifests, problems: [`${dir}: no such folder`] };
86
+ const names = readDirSync(base)
87
+ .filter((e) => e.isFile && e.name.endsWith(".import.ts"))
88
+ .map((e) => e.name)
89
+ .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
90
+ for (const name of names) {
91
+ const file = `${folder}/${name}`;
92
+ const loaded: unknown = await import(pathToFileURL(resolve(base, name)).href);
93
+ const raw = isRecord(loaded) ? loaded["manifest"] : undefined;
94
+ const m = decodeManifest(raw);
95
+ if (m.kind === "err") {
96
+ problems.push(`${file}: ${m.error}`);
97
+ continue;
98
+ }
99
+ const latest = isRecord(raw) ? raw["latest"] : undefined;
100
+ if (latest === undefined) continue;
101
+ if (typeof latest !== "string" || !isUrl(latest)) {
102
+ problems.push(`${file}: latest must be an https:// URL`);
103
+ continue;
104
+ }
105
+ manifests.push({ file, id: m.value.standard.id, version: m.value.standard.version, pin: m.value.standard.sha256, latest });
106
+ }
107
+ return { manifests, problems };
108
+ }
109
+
110
+ /** The SHA-256 of what a URL serves, with its line ends normalised as an import's are (0019-mizan-integrations FR-014), or the sentence that says why it could not be fetched. */
111
+ export async function latestHash(url: string): Promise<Result<string, string>> {
112
+ try {
113
+ const r = await fetch(url, { signal: AbortSignal.timeout(60_000) });
114
+ if (!r.ok) return err(`${url}: HTTP ${r.status}`);
115
+ return ok(await sha256((await r.text()).replaceAll("\r\n", "\n")));
116
+ } catch (e) {
117
+ return err(`${url}: ${e instanceof Error ? e.message : String(e)}`);
118
+ }
119
+ }
120
+
121
+ /** The command line. Returns the exit status: 0, 1 where a finding is new or a baseline line is stale, 2 where a source or a manifest cannot be read. */
122
+ export async function main(argv: readonly string[]): Promise<number> {
123
+ const arg = (name: string): string | undefined => {
124
+ const i = argv.indexOf(name);
125
+ return i >= 0 ? argv[i + 1] : undefined;
126
+ };
127
+ const imports = arg("--imports") ?? fileURLToPath(new URL("./imports", import.meta.url));
128
+ const root = (arg("--root") ?? fileURLToPath(new URL("../../spec-kit", import.meta.url))).replace(/[\\/]$/, "");
129
+ const baselineFile = `${root}/mizan.newer.baseline.txt`;
130
+ const { manifests, problems: unread } = await readLatestManifests(imports);
131
+ const problems = [...unread];
132
+ const fetched: Fetched[] = [];
133
+ for (const m of manifests) {
134
+ const h = await latestHash(m.latest);
135
+ if (h.kind === "err") problems.push(`${m.file}: ${h.error}`);
136
+ else fetched.push({ ...m, sha256: h.value });
137
+ }
138
+ const found = staleFindings(fetched);
139
+ if (argv.includes("--write-baseline")) {
140
+ if (problems.length === 0) {
141
+ writeTextFileSync(baselineFile, formatBaseline(found, NEWER_BASELINE_COMMENTS));
142
+ stdio.stdout.writeSync(`wrote ${baselineFile}: ${new Set(found.map((f) => f.key)).size} findings\n`);
143
+ return 0;
144
+ }
145
+ }
146
+ for (const p of problems) stdio.stderr.writeSync(`${p}\n`);
147
+ if (problems.length > 0) return 2;
148
+ const held = existsSync(baselineFile) ? parseBaseline(readTextFileSync(baselineFile)) : [];
149
+ const verdict = judge(found, held);
150
+ stdio.stderr.writeSync(`${report(verdict, "mizan-newer", baselineFile).join("\n")}\n`);
151
+ return passes(verdict) ? 0 : 1;
152
+ }
153
+
154
+ if (import.meta.main) process.exitCode = await main(process.argv.slice(2));
@@ -0,0 +1,443 @@
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 {
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
+ import { sha256 } from "@intellectual-frontiers/crypto/sha256";
60
+ import { type Cited, parseSpec, proofsOf, type SourceFile } from "@intellectual-frontiers/mizan/trace";
61
+ import { NAMESPACE_URL, uuidV5 } from "@intellectual-frontiers/crypto/uuid";
62
+ import { existsSync, mkdirSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
63
+ import { stdio } from "@intellectual-frontiers/system";
64
+ import { readSources } from "@intellectual-frontiers/mizan/host/trace";
65
+ import { sentenceOf, type SpecText } from "@intellectual-frontiers/mizan/rules";
66
+
67
+ /** What the register says enforces a requirement (0003-mizan FR-005): a check, a gate, a person's review, or nothing. */
68
+ export type Mechanism = "check" | "gate" | "review" | "none";
69
+
70
+ /** A requirement as the register holds it. */
71
+ export type RegisterRow = {
72
+ /** The requirement, `NNNN-slug FR-nnn`. */
73
+ readonly requirement: string;
74
+ readonly spec: string;
75
+ readonly id: string;
76
+ /** The OSCAL `control-id`, `spec-<slug>.<fr>` in lower case. */
77
+ readonly controlId: string;
78
+ /** The first sentence of the requirement, cut to 160 characters. */
79
+ readonly title: string;
80
+ /** The status of its specification (Draft, Active, ...), or `unknown`. */
81
+ readonly status: string;
82
+ readonly mechanism: Mechanism;
83
+ /** Who enforces it, as `enforcement.tsv` says (`-` for none, `reviewed.tsv` for a row of that file). */
84
+ readonly by: string;
85
+ readonly note: string;
86
+ /** The test files that prove it, sorted. */
87
+ readonly files: readonly string[];
88
+ };
89
+
90
+ /** What the register is made from: the specifications, the text of each `reviewed.tsv`, the text of `enforcement.tsv` and the tests. */
91
+ export type RegisterInput = {
92
+ /** The name the documents give the folder. */
93
+ readonly label: string;
94
+ readonly specs: readonly SpecText[];
95
+ /** The text of a specification's `reviewed.tsv`, by its slug. */
96
+ readonly reviewed: ReadonlyMap<string, string>;
97
+ readonly enforcement: string;
98
+ readonly tests: readonly SourceFile[];
99
+ };
100
+
101
+ /** The file of the component definition, from the folder it is written in. */
102
+ export const COMPONENT_FILE = "mizan-register.auto.oscal.json";
103
+
104
+ /** The file of the assessment results, from the folder it is written in. */
105
+ export const RESULTS_FILE = "mizan-register-results.auto.oscal.json";
106
+
107
+ /** The command that writes the files again. */
108
+ export const RUN = "bun commons/libraries/src/oscal-register.ts";
109
+
110
+ /** The instant the documents give as their `last-modified`: the register reads no clock (0003-mizan FR-022). */
111
+ const NO_CLOCK: Instant = instantOf("1970-01-01T00:00:00Z") ?? absurdInstant();
112
+
113
+ /** Never returns: the epoch is an instant, so `instantOf` has no reason to refuse it. */
114
+ function absurdInstant(): never {
115
+ throw new Error("1970-01-01T00:00:00Z is an instant");
116
+ }
117
+
118
+ const REGISTER_IRI = "https://www.intellectualfrontiers.com/ontology/mizan-register";
119
+ const isMechanism = (x: string): x is Mechanism => x === "check" || x === "gate" || x === "review" || x === "none";
120
+
121
+ const byText = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
122
+ const numberOf = (id: string): number => Number(/^FR-(\d+)/.exec(id)?.[1] ?? "NaN");
123
+
124
+ /** The OSCAL `control-id` of a requirement: a token that starts with a letter (`spec-0003-mizan.fr-011`). */
125
+ export function controlIdOf(spec: string, id: string): string {
126
+ return `spec-${spec}.${id.toLowerCase()}`;
127
+ }
128
+
129
+ /** The rows of `enforcement.tsv` by requirement: its four columns; comment lines, blank lines and the header are not rows. */
130
+ function enforcementRows(text: string): ReadonlyMap<string, { readonly mechanism: Mechanism; readonly by: string; readonly note: string }> {
131
+ const out = new Map<string, { readonly mechanism: Mechanism; readonly by: string; readonly note: string }>();
132
+ for (const line of text.replaceAll("\r\n", "\n").split("\n")) {
133
+ if (line.trim() === "" || line.startsWith("#")) continue;
134
+ const [req = "", mechanism = "", by = "", ...note] = line.split("\t");
135
+ if (req === "requirement" || !isMechanism(mechanism)) continue;
136
+ out.set(req.trim(), { mechanism, by: by.trim(), note: note.join("\t").trim() });
137
+ }
138
+ return out;
139
+ }
140
+
141
+ /** The rows of a `reviewed.tsv` as requirement ids and reasons (`slug FR-nnn<TAB>reason`), for the specification named `slug`. */
142
+ function reviewedRows(slug: string, text: string): ReadonlyMap<string, string> {
143
+ const out = new Map<string, string>();
144
+ for (const raw of text.replaceAll("\r\n", "\n").split("\n")) {
145
+ const line = raw.trim();
146
+ if (line === "" || line.startsWith("#")) continue;
147
+ const [req = "", ...reason] = line.split("\t");
148
+ const m = /^(\S+)\s+(FR-\d{3}[a-z]?)$/.exec(req.trim());
149
+ if (m?.[1] === slug && m[2] !== undefined) out.set(m[2], reason.join("\t").trim());
150
+ }
151
+ return out;
152
+ }
153
+
154
+ /** The ids of a specification's requirements that a citation names, ranges expanded; an id the specification lacks names nothing. */
155
+ function idsOf(have: readonly string[], c: Cited): readonly string[] {
156
+ if (c.kind === "one") return have.includes(c.id) ? [c.id] : [];
157
+ if (!have.includes(c.from) || !have.includes(c.to)) return [];
158
+ const [lo, hi] = [numberOf(c.from), numberOf(c.to)];
159
+ return have.filter((id) => numberOf(id) >= lo && numberOf(id) <= hi);
160
+ }
161
+
162
+ /** The first sentence of a requirement's text, white space collapsed and cut to 160 characters. */
163
+ function titleOf(sentence: string): string {
164
+ const one = sentence.replace(/\s+/g, " ").trim();
165
+ const end = one.search(/[.;:] /);
166
+ const first = end > 20 ? one.slice(0, end + 1) : one;
167
+ return first.length > 160 ? `${first.slice(0, 157)}...` : first;
168
+ }
169
+
170
+ /** 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). */
171
+ export function registerRows(input: RegisterInput): readonly RegisterRow[] {
172
+ const enforced = enforcementRows(input.enforcement);
173
+ const slugs = new Map(input.specs.map((s) => [s.slug, parseSpec(s.slug, s.spec).requirements.map((r) => r.id)]));
174
+ const proved = new Map<string, Set<string>>();
175
+ for (const t of [...input.tests].sort((a, b) => byText(a.path, b.path))) {
176
+ for (const p of proofsOf(t.text)) {
177
+ const have = slugs.get(p.spec);
178
+ if (have === undefined) continue;
179
+ for (const id of idsOf(have, p.requirement)) {
180
+ const key = `${p.spec} ${id}`;
181
+ const files = proved.get(key) ?? new Set<string>();
182
+ files.add(t.path);
183
+ proved.set(key, files);
184
+ }
185
+ }
186
+ }
187
+ return input.specs.flatMap((s) => {
188
+ const parsed = parseSpec(s.slug, s.spec);
189
+ const lines = s.spec.split("\n");
190
+ const reviewed = reviewedRows(s.slug, input.reviewed.get(s.slug) ?? "");
191
+ return parsed.requirements.map((r): RegisterRow => {
192
+ const requirement = `${s.slug} ${r.id}`;
193
+ const row = enforced.get(requirement);
194
+ const reason = reviewed.get(r.id);
195
+ const [mechanism, by, note]: [Mechanism, string, string] =
196
+ row !== undefined
197
+ ? [row.mechanism, row.by, row.note]
198
+ : reason !== undefined
199
+ ? ["review", "reviewed.tsv", reason]
200
+ : ["none", "-", "no row in enforcement.tsv"];
201
+ return {
202
+ requirement,
203
+ spec: s.slug,
204
+ id: r.id,
205
+ controlId: controlIdOf(s.slug, r.id),
206
+ title: titleOf(sentenceOf(lines, r.line - 1)),
207
+ status: parsed.status ?? "unknown",
208
+ mechanism,
209
+ by,
210
+ note,
211
+ files: [...(proved.get(requirement) ?? [])].sort(byText),
212
+ };
213
+ });
214
+ });
215
+ }
216
+
217
+ function summaryOf(row: RegisterRow, catalog: string): ControlSummary {
218
+ return {
219
+ id: row.requirement,
220
+ title: row.title,
221
+ implements: [{ catalog, id: row.controlId }],
222
+ severity: "info",
223
+ cadence: "on every commit",
224
+ };
225
+ }
226
+
227
+ /** What a requirement's finding says: a passing observation for each test file that proves it, else `accepted` where a person reviewed it, else a `gap`. */
228
+ async function findingsOf(row: RegisterRow, control: ControlSummary, tests: ReadonlyMap<string, string>): Promise<readonly Finding[]> {
229
+ const subject: SubjectRef = { kind: "specification", id: row.spec };
230
+ const base = { control, subject, severity: "info" as const, at: NO_CLOCK };
231
+ if (row.files.length > 0)
232
+ return Promise.all(
233
+ row.files.map(async (file): Promise<Finding> => ({
234
+ ...base,
235
+ status: "pass",
236
+ outcome: "pass",
237
+ title: `proved by ${file}`,
238
+ detail: `${row.requirement} is named by a proof in ${file}.`,
239
+ evidence: [await sha256(tests.get(file) ?? "")],
240
+ })),
241
+ );
242
+ if (row.mechanism === "review")
243
+ 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
+ },
253
+ ];
254
+ const status: Status = "gap";
255
+ return [
256
+ {
257
+ ...base,
258
+ status,
259
+ outcome: status,
260
+ title: "no test proves it",
261
+ 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
+ },
264
+ ];
265
+ }
266
+
267
+ /** The two documents, as the text of their files. */
268
+ export type RegisterDocuments = { readonly componentDefinition: string; readonly assessmentResults: string };
269
+
270
+ /**
271
+ * 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.
273
+ */
274
+ export async function registerDocuments(input: RegisterInput, register: RegisterOptions = {}): Promise<RegisterDocuments> {
275
+ const rows = registerRows(register.enforcement === undefined ? input : { ...input, enforcement: enforcementAt(register.enforcement) });
276
+ 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
+ const tests = new Map(input.tests.map((t) => [t.path, t.text]));
280
+ const version = (await sha256(JSON.stringify(rows.map((r) => [r.requirement, r.mechanism, r.by, r.note, r.title, r.files])))).slice(
281
+ 0,
282
+ 12,
283
+ );
284
+ const namespace = await uuidV5(NAMESPACE_URL, REGISTER_IRI);
285
+ const options = (what: string): OscalOptions => ({
286
+ namespace,
287
+ lastModified: NO_CLOCK,
288
+ version,
289
+ propNamespace: `${REGISTER_IRI}#`,
290
+ title: `Mizan register of ${input.label}: ${what} (generated by ${RUN}; do not edit)`,
291
+ controlId: (ref) => ref.id,
292
+ });
293
+ const definition = await componentDefinition(
294
+ controls,
295
+ {
296
+ id: input.label,
297
+ title: input.label,
298
+ description: `${input.label}, whose requirements are written in the specifications of its Mizan folder.`,
299
+ type: "software",
300
+ },
301
+ options("component definition"),
302
+ );
303
+ const byControl = new Map(rows.map((r) => [r.controlId, r]));
304
+ const inner = definition["component-definition"];
305
+ const withMechanism: OscalComponentDefinition = {
306
+ "component-definition": {
307
+ ...inner,
308
+ components: inner.components.map((c) => ({
309
+ ...c,
310
+ ...(c["control-implementations"] === undefined
311
+ ? {}
312
+ : {
313
+ "control-implementations": c["control-implementations"].map((ci) => ({
314
+ ...ci,
315
+ "implemented-requirements": ci["implemented-requirements"].map((ir) => {
316
+ const row = byControl.get(ir["control-id"]);
317
+ return row === undefined
318
+ ? ir
319
+ : {
320
+ ...ir,
321
+ props: [
322
+ ...ir.props,
323
+ { name: "mechanism", ns: `${REGISTER_IRI}#`, value: row.mechanism },
324
+ { name: "proofs", ns: `${REGISTER_IRI}#`, value: String(row.files.length) },
325
+ ],
326
+ };
327
+ }),
328
+ })),
329
+ }),
330
+ })),
331
+ },
332
+ };
333
+ const assessment: Assessment = {
334
+ pack: { id: input.label, title: `Mizan register of ${input.label}` },
335
+ at: NO_CLOCK,
336
+ controls,
337
+ subjects: [...new Set(rows.map((r) => r.spec))].sort(byText).map((id) => ({ kind: "specification", id })),
338
+ findings: (await Promise.all(pairs.map((p) => findingsOf(p.row, p.control, tests)))).flat(),
339
+ };
340
+ const results: OscalAssessmentResults = await assessmentResults(assessment, options("assessment results"));
341
+ return { componentDefinition: renderOscal(withMechanism), assessmentResults: renderOscal(results) };
342
+ }
343
+
344
+ /** 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. */
345
+ export type RegisterOptions = {
346
+ /** 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. */
347
+ readonly enforcement?: string;
348
+ };
349
+
350
+ /** The text of the register at an explicit path, with LF line ends; an error that names the file where it is not there. */
351
+ function enforcementAt(path: string): string {
352
+ if (!existsSync(path)) throw new Error(`the proof register ${path} does not exist`);
353
+ return readTextFileSync(path).replaceAll("\r\n", "\n");
354
+ }
355
+
356
+ /**
357
+ * 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
358
+ * `<root>/enforcement.tsv` unless `options.enforcement` names another file (0003-mizan FR-043).
359
+ */
360
+ export async function readRegisterInput(
361
+ root: string,
362
+ repo: string,
363
+ testFolders: readonly string[],
364
+ label: string,
365
+ options: RegisterOptions = {},
366
+ ): Promise<RegisterInput> {
367
+ const specs: SpecText[] = [];
368
+ const reviewed = new Map<string, string>();
369
+ const folder = `${root.replace(/[\\/]$/, "")}/specs`;
370
+ if (existsSync(folder))
371
+ for (const e of readDirSync(folder).sort((a, b) => byText(a.name, b.name))) {
372
+ if (!e.isDirectory || !existsSync(`${folder}/${e.name}/spec.md`)) continue;
373
+ specs.push({ slug: e.name, spec: readTextFileSync(`${folder}/${e.name}/spec.md`).replaceAll("\r\n", "\n") });
374
+ if (existsSync(`${folder}/${e.name}/reviewed.tsv`))
375
+ reviewed.set(e.name, readTextFileSync(`${folder}/${e.name}/reviewed.tsv`).replaceAll("\r\n", "\n"));
376
+ }
377
+ const enforcement = options.enforcement ?? `${root.replace(/[\\/]$/, "")}/enforcement.tsv`;
378
+ const tests = await readSources(
379
+ repo,
380
+ testFolders.filter((t) => existsSync(`${repo.replace(/[\\/]$/, "")}/${t}`)),
381
+ [".test.ts"],
382
+ );
383
+ return {
384
+ label,
385
+ specs,
386
+ reviewed,
387
+ enforcement:
388
+ options.enforcement !== undefined
389
+ ? enforcementAt(enforcement)
390
+ : existsSync(enforcement)
391
+ ? readTextFileSync(enforcement).replaceAll("\r\n", "\n")
392
+ : "",
393
+ tests: [...tests].map((t) => ({ ...t, text: t.text.replaceAll("\r\n", "\n") })).sort((a, b) => byText(a.path, b.path)),
394
+ };
395
+ }
396
+
397
+ /** The command line. Returns the exit status: 0, or 1 with `--check` where a file is not what the folder makes. */
398
+ export async function main(argv: readonly string[]): Promise<number> {
399
+ const arg = (name: string): string | undefined => {
400
+ const i = argv.indexOf(name);
401
+ return i >= 0 ? argv[i + 1] : undefined;
402
+ };
403
+ const commons = fileURLToPath(new URL("../..", import.meta.url)).replace(/[\\/]$/, "");
404
+ const root = arg("--root") ?? `${commons}/spec-kit`;
405
+ const register = arg("--register") ?? root;
406
+ const enforcement =
407
+ arg("--enforcement") ?? (arg("--register") === undefined ? undefined : `${register.replace(/[\\/]$/, "")}/enforcement.tsv`);
408
+ const repo = arg("--repo") ?? fileURLToPath(new URL("../../..", import.meta.url)).replace(/[\\/]$/, "");
409
+ const out = (arg("--out") ?? `${commons}/generated`).replace(/[\\/]$/, "");
410
+ const tests = (arg("--tests") ?? "tests,commons").split(",");
411
+ if (enforcement !== undefined && !existsSync(enforcement)) {
412
+ stdio.stderr.writeSync(`oscal-register: the proof register ${enforcement} does not exist\n`);
413
+ return 2;
414
+ }
415
+ const made = await registerDocuments(
416
+ await readRegisterInput(
417
+ root,
418
+ repo,
419
+ tests,
420
+ arg("--label") ?? "Intellectual Frontiers commons",
421
+ enforcement === undefined ? {} : { enforcement },
422
+ ),
423
+ );
424
+ const files: readonly (readonly [string, string])[] = [
425
+ [COMPONENT_FILE, made.componentDefinition],
426
+ [RESULTS_FILE, made.assessmentResults],
427
+ ];
428
+ if (argv.includes("--check")) {
429
+ const stale = files.filter(
430
+ ([name, text]) => !existsSync(`${out}/${name}`) || readTextFileSync(`${out}/${name}`).replaceAll("\r\n", "\n") !== text,
431
+ );
432
+ for (const [name] of stale) stdio.stderr.writeSync(`${out}/${name} is not what the folder makes; run: ${RUN}\n`);
433
+ return stale.length > 0 ? 1 : 0;
434
+ }
435
+ mkdirSync(out, { recursive: true });
436
+ for (const [name, text] of files) {
437
+ writeTextFileSync(`${out}/${name}`, text);
438
+ stdio.stdout.writeSync(`wrote ${out}/${name}\n`);
439
+ }
440
+ return 0;
441
+ }
442
+
443
+ if (import.meta.main) process.exitCode = await main(process.argv.slice(2));