COMPONENT_FILEconstconst COMPONENT_FILE: "mizan-register.auto.oscal.json"The file of the component definition, from the folder it is written in.
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 review rows) as an OSCAL component-definition, each requirement an implemented-requirement, and the proofs the tests name (proves([...]), // Proves:) as OSCAL assessment-results.
bun commons/libraries/src/oscal-register.ts write commons/generated/mizan-register.auto.oscal.json and mizan-register-results.auto.oscal.json bun commons/libraries/src/oscal-register.ts --check write nothing; exit 1 naming each file that is not what the folder makes --root DIR the folder (default commons/spec-kit) --repo DIR the repository the tests are searched in (default commons' repository) --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) --tests A,B the folders of tests, from the repository (default tests,commons) --out DIR where the files go (default commons/generated) --label TEXT the name the documents give the folder (default Intellectual Frontiers commons)
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 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 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 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 proves a requirement and its note, stays in enforcement.tsv, so that no proof is written twice.
import { registerRows } from "./oscal-register.ts";
registerRows({
label: "x",
specs: [{ slug: "0001-x", spec: "**Status:** Active\n- **FR-001**: It MUST work.\n" }],
reviewed: new Map(),
enforcement: "0001-x FR-001\tcheck\trepo: bun test\tproved\n",
tests: [{ path: "tests/x.test.ts", text: 'proves(["0001-x FR-001"], "it works", () => {});' }],
}).map((r) => [r.requirement, r.mechanism, r.files]); // [["0001-x FR-001", "check", ["tests/x.test.ts"]]]Spec: 0001-libraries FR-008
COMPONENT_FILEconstconst COMPONENT_FILE: "mizan-register.auto.oscal.json"The file of the component definition, from the folder it is written in.
registerDocumentsfunctionfunction registerDocuments(input: RegisterInput, register?: RegisterOptions): Promise<RegisterDocuments>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 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: the register's own vocabulary (a mechanism, a proof, a waiver) is Mizan's.
registerRowsfunctionfunction registerRows(input: RegisterInput): readonly RegisterRow[]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).
RESULTS_FILEconstconst RESULTS_FILE: "mizan-register-results.auto.oscal.json"The file of the assessment results, from the folder it is written in.
RegisterInputtypetype RegisterInput = {
/** The name the documents give the folder. */
readonly label: string;
readonly specs: readonly SpecText[];
/** The text of a specification's `reviewed.tsv`, by its slug. */
readonly reviewed: ReadonlyMap<string, string>;
readonly enforcement: string;
readonly tests: readonly SourceFile[];
};What the register is made from: the specifications, the text of each reviewed.tsv, the text of enforcement.tsv and the tests.
RegisterRowtypeno test imports ittype RegisterRow = {
/** The requirement, `NNNN-slug FR-nnn`. */
readonly requirement: string;
readonly spec: stri… (719 characters)type RegisterRow = {
/** The requirement, `NNNN-slug FR-nnn`. */
readonly requirement: string;
readonly spec: string;
readonly id: string;
/** The OSCAL `control-id`, `spec-<slug>.<fr>` in lower case. */
readonly controlId: string;
/** The first sentence of the requirement, cut to 160 characters. */
readonly title: string;
/** The status of its specification (Draft, Active, ...), or `unknown`. */
readonly status: string;
readonly mechanism: Mechanism;
/** Who enforces it, as `enforcement.tsv` says (`-` for none, `reviewed.tsv` for a row of that file). */
readonly by: string;
readonly note: string;
/** The test files that prove it, sorted. */
readonly files: readonly string[];
};A requirement as the register holds it.
Mechanismtypeno test imports ittype Mechanism = "check" | "gate" | "review" | "none";What the register says enforces a requirement (0003-mizan FR-005): a check, a gate, a person's review, or nothing.
controlIdOffunctionfunction controlIdOf(spec: string, id: string): stringThe OSCAL control-id of a requirement: a token that starts with a letter (spec-0003-mizan.fr-011).
RegisterDocumentstypeno test imports ittype RegisterDocuments = { readonly componentDefinition: string; readonly assessmentResults: string };The two documents, as the text of their files.
RegisterOptionstypeno test imports ittype RegisterOptions = {
/** 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. */
readonly enforcement?: string;
};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.
readRegisterInputfunctionno test imports itfunction readRegisterInput(root: string, repo: string, testFolders: readonly string[], label: string, options?: RegisterOptions): Promise<RegisterInput>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 <root>/enforcement.tsv unless options.enforcement names another file (0003-mizan FR-043).