@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
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The import of the controls of NIST SP 800-53 Rev. 5.2.0 that Mizan's specifications cite (commons 0019-mizan-integrations FR-005, FR-006, FR-009, FR-014, 0018-standards-first FR-001):
3
+ * the OSCAL catalog NIST publishes, fetched from the versioned URL of its tagged release and held to the SHA-256 pinned here, so that the control identifiers a specification names
4
+ * are typed values that rest on bytes that cannot change unseen. Its provenance is `nist-sp-800-53.auto.prov.ttl` beside this file. Run
5
+ * `bun commons/mizan/src/integrations/host/import.ts commons/libraries/src/imports/nist-sp-800-53.import.ts` to write the module again, with `--check` to see whether it is current
6
+ * (offline; with `--fetch` it fetches the source and compares fully).
7
+ *
8
+ * The slice is the configuration management controls IFCCM cites (CM-2, CM-3, CM-4, CM-5, CM-9) and the ones the workspace and quality specifications cite (CM-6, CM-7, CM-8,
9
+ * CM-10, SA-10, SI-7, IA-5).
10
+ *
11
+ * Spec: 0001-libraries FR-009
12
+ *
13
+ * @module
14
+ */
15
+ export const manifest = {
16
+ standard: {
17
+ id: "nist-sp-800-53",
18
+ issuer: "National Institute of Standards and Technology",
19
+ name: "NIST SP 800-53 Rev. 5.2.0 (OSCAL catalog)",
20
+ version: "5.2.0",
21
+ location:
22
+ "https://raw.githubusercontent.com/usnistgov/oscal-content/f0de6d8d8c059d374f15e0ae07508d82e370fc1d/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json",
23
+ license: "Public domain (a work of the United States Government, 17 U.S.C. 105)",
24
+ redistributable: true,
25
+ sha256: "64ca6b4161de51ab6af098a7d101d326f14c95e1abf721396cd8a049e8115eeb",
26
+ },
27
+ source:
28
+ "https://raw.githubusercontent.com/usnistgov/oscal-content/f0de6d8d8c059d374f15e0ae07508d82e370fc1d/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json",
29
+ // the URL that always serves the newest release: only `newer.ts` reads it (0018-standards-first FR-014); an import never does (0019-mizan-integrations FR-014)
30
+ latest: "https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json",
31
+ format: "oscal-catalog",
32
+ slice: ["cm-2", "cm-3", "cm-4", "cm-5", "cm-6", "cm-7", "cm-8", "cm-9", "cm-10", "sa-10", "si-7", "ia-5"],
33
+ out: "../../../ontology/src/standards/nist-sp-800-53/controls.auto.ts",
34
+ provOut: "nist-sp-800-53.auto.prov.ttl",
35
+ rdfImport: "@intellectual-frontiers/rdf",
36
+ } as const;
@@ -0,0 +1,31 @@
1
+ /**
2
+ * The import of the slice of schema.org that the packaging ontology specializes (commons 0019-mizan-integrations FR-005, FR-006, FR-009, FR-014): its source is fetched from the
3
+ * versioned URL and held to the SHA-256 pinned here, so that what `schema.auto.ts` says rests on bytes that cannot change unseen, and its provenance is `schema-org.auto.prov.ttl`
4
+ * beside this file. Run `bun commons/mizan/src/integrations/host/import.ts commons/libraries/src/imports/schema-org.import.ts` to write the module again, with `--check` to see whether
5
+ * it is current (offline; with `--fetch` it fetches the source and compares fully).
6
+ *
7
+ * Spec: 0001-libraries FR-009
8
+ *
9
+ * @module
10
+ */
11
+ export const manifest = {
12
+ standard: {
13
+ id: "schema-org",
14
+ issuer: "Schema.org Community Group",
15
+ name: "schema.org",
16
+ version: "30.1",
17
+ location: "https://schema.org/version/30.1/schemaorg-current-https.ttl",
18
+ license: "CC-BY-SA-3.0",
19
+ redistributable: true,
20
+ sha256: "7f15ca89398c4f235f478a4b3b8d1f975d63c5a860b77c8a8fce01f791b7ae2f",
21
+ },
22
+ source: "https://schema.org/version/30.1/schemaorg-current-https.ttl",
23
+ // the URL that always serves the newest version: only `newer.ts` reads it (0018-standards-first FR-014); an import never does (0019-mizan-integrations FR-014)
24
+ latest: "https://schema.org/version/latest/schemaorg-current-https.ttl",
25
+ format: "turtle",
26
+ namespace: { prefix: "schema", iri: "https://schema.org/" },
27
+ slice: ["Action", "SoftwareApplication", "Thing", "name", "operatingSystem", "processorRequirements", "softwareVersion"],
28
+ out: "../../../ontology/src/supply-chain/packaging/schema.auto.ts",
29
+ provOut: "schema-org.auto.prov.ttl",
30
+ rdfImport: "@intellectual-frontiers/rdf",
31
+ } as const;
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Bun at the version commons pins (`BUN_VERSION` and its SHA-256 per platform in `commons/generated/pins.auto.env`, commons
3
+ * 0005-typescript-runtime FR-026), fetched from Bun's release with retries, kept only where its SHA-256 is the pinned one, unpacked by the
4
+ * kernel's own zip reader and put in a folder; nothing but IFC TypeScript itself, so it runs on Node 26 (or Bun) on Linux, macOS
5
+ * and Windows with no shell, no Python and no unzip. CI's `.github/actions/bun` runs it.
6
+ *
7
+ * `node commons/libraries/src/install-bun.ts <folder>` (the folder is required) prints the folder that holds `bun` (or `bun.exe`); with `GITHUB_PATH` set, it is also
8
+ * added there.
9
+ *
10
+ * Spec: 0001-libraries FR-006
11
+ *
12
+ * @module
13
+ */
14
+ import { formatArchiveError, unzip } from "@intellectual-frontiers/formats/archive";
15
+ import { sha256Of } from "@intellectual-frontiers/crypto/sha256";
16
+ import { chmod, ensureDir, readFile, readTextFile, writeFile, writeTextFile } from "@intellectual-frontiers/system/fs";
17
+ import { downloadVerified, Retries } from "@intellectual-frontiers/net/net";
18
+ import { dirname, fromFileUrl, join, resolve } from "@intellectual-frontiers/system/path";
19
+ import { args, build, env, exit } from "@intellectual-frontiers/system/proc";
20
+ import { bunTarget, readEnvFile } from "./pins.ts";
21
+
22
+ /** Stop with a message and status 1. */
23
+ function stop(message: string): never {
24
+ console.error(`install-bun: ${message}`);
25
+ return exit(1);
26
+ }
27
+
28
+ const ROOT = resolve(dirname(fromFileUrl(import.meta.url)), "..", "..", "..");
29
+ const given = args[0];
30
+ if (given === undefined) stop("give the folder to put Bun in");
31
+ const dest = resolve(given);
32
+ const pins = readEnvFile(await readTextFile(join(ROOT, "commons", "generated", "pins.auto.env")));
33
+ const platform = bunTarget(build.os, build.arch);
34
+ if (platform === undefined) stop(`Bun has no build for ${build.os} on ${build.arch}`);
35
+ const version = pins.get("BUN_VERSION");
36
+ const sum = sha256Of(pins.get(`BUN_SHA256_${platform.key}`) ?? "");
37
+ if (version === undefined || sum === undefined) stop(`commons pins no Bun for ${platform.key}`);
38
+ const retries = new Retries({ tries: 5, base: 2, cap: 30 }, (line) => console.error(line));
39
+ const url = `https://github.com/oven-sh/bun/releases/download/bun-v${version}/bun-${platform.target}.zip`;
40
+ const zip = await downloadVerified(retries, url, sum, join(dest, "cache"));
41
+ if (zip.kind === "err") stop(zip.error);
42
+ const files = await unzip(await readFile(zip.value));
43
+ if (files.kind === "err") stop(formatArchiveError(files.error));
44
+ const exe = build.os === "windows" ? "bun.exe" : "bun";
45
+ const bytes = files.value.get(`bun-${platform.target}/${exe}`);
46
+ if (bytes === undefined) stop(`the zip holds no bun-${platform.target}/${exe}`);
47
+ const bin = join(dest, `bun-${version}`);
48
+ await ensureDir(bin);
49
+ await writeFile(join(bin, exe), bytes);
50
+ await chmod(join(bin, exe), 0o755);
51
+ const githubPath = env.get("GITHUB_PATH");
52
+ if (githubPath !== undefined && githubPath !== "") await writeTextFile(githubPath, `${bin}\n`, { append: true });
53
+ console.log(bin);
@@ -0,0 +1,385 @@
1
+ /**
2
+ * The manifest of a library of commons (commons 0027-commons-libraries FR-011 to FR-014) and the requirements it makes: a library is a folder `commons/<name>/` that holds `library.ts`, an
3
+ * object literal read as data and never run, and this repository knows it from that file alone. The decoder of the manifest, the check that a manifest and its folder agree, and the generator of
4
+ * the section "The libraries" of 0027-commons-libraries and of its rows of `enforcement.tsv`.
5
+ *
6
+ * bun commons/libraries/src/libraries.ts write the section and the rows again from the manifests
7
+ * bun commons/libraries/src/libraries.ts --check write nothing and exit 1 where a file is not what the manifests make, or where a manifest and its folder disagree
8
+ * other flags: --repo DIR (the repository, the working folder by default)
9
+ *
10
+ * @remarks
11
+ * A manifest declares the library's `name` (its folder), its conformance `level` (`L1` where it declares none, 0028-conformance-levels), the path of its spec kit, its `verify` command, its
12
+ * `version`, its `exports` (the keys of the package's `exports`) and its `distribution` (the registries it is published to: `github`, the default, and `npm` as well where a decision about that package has made it so; FR-015 to FR-018). The section "The libraries" of the specification is between the markers `<!-- libraries:begin -->` and `<!-- libraries:end -->`,
13
+ * one requirement for each library numbered from FR-101, an id kept for the life of the library; the rows of those requirements are in `enforcement.tsv`. Adding a library is adding a folder with a manifest and
14
+ * running this command.
15
+ *
16
+ * @limits
17
+ * It reads files and writes two; it runs no library's `verify` (`check.ts --all` does, 0028-conformance-levels FR-012), and it does not read inside a library but its manifest, its package and the files that name its spec kit.
18
+ *
19
+ * @example
20
+ * ```ts
21
+ * import { decodeLibrarySource } from "./libraries.ts";
22
+ * const r = decodeLibrarySource('export const library = { name: "x", verify: "bun run verify", version: "0.1.0", exports: [] };');
23
+ * r.kind; // "ok"
24
+ * ```
25
+ *
26
+ * Spec: 0001-libraries FR-001
27
+ *
28
+ * @module
29
+ */
30
+ import process from "node:process";
31
+ import {
32
+ array,
33
+ type Decoder,
34
+ describe,
35
+ formatDecodeError,
36
+ literal,
37
+ object,
38
+ string,
39
+ err,
40
+ ok,
41
+ type Result,
42
+ } from "@intellectual-frontiers/core";
43
+ import { exportedLiteral } from "@intellectual-frontiers/formats/ts-literal";
44
+ import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
45
+ import { stdio } from "@intellectual-frontiers/system";
46
+ import { spawn } from "@intellectual-frontiers/system/proc";
47
+ import { DEFAULT_LIBRARY_LEVEL, LEVELS, type LevelKey, rankOf } from "@intellectual-frontiers/mizan/levels";
48
+
49
+ /** The name of a library's manifest in its folder. */
50
+ export const LIBRARY_FILE = "library.ts";
51
+
52
+ /** The specification that holds the requirements of the libraries, and the first number of the requirements it generates. */
53
+ export const LIBRARIES_SPEC = "0027-commons-libraries";
54
+ /** The first requirement number of the section "The libraries", which is generated (0027-commons-libraries FR-011). */
55
+ export const FIRST_GENERATED = 101;
56
+ /** The marker that opens the generated section, and the one that closes it. */
57
+ export const BEGIN = "<!-- libraries:begin -->";
58
+ export const END = "<!-- libraries:end -->";
59
+
60
+ /** Where the generated section begins and ends: the markers on lines of their own (a requirement may name them in its text). */
61
+ function bounds(spec: string): { readonly from: number; readonly to: number } | undefined {
62
+ const from = spec.indexOf(`\n${BEGIN}\n`);
63
+ const to = spec.indexOf(`\n${END}\n`, from);
64
+ return from < 0 || to < 0 ? undefined : { from: from + 1, to: to + 1 };
65
+ }
66
+
67
+ /** A library's manifest. */
68
+ export type Library = {
69
+ /** The folder's name, and the package's: `@intellectual-frontiers/<name>`. */
70
+ readonly name: string;
71
+ /** The conformance level the library is held to (`L1` where the manifest declares none). */
72
+ readonly level: LevelKey;
73
+ /** The path of its spec kit from its folder; none at L0. */
74
+ readonly specKit?: string;
75
+ /** The command that proves it, run from its folder with no argument. */
76
+ readonly verify: string;
77
+ /** Its version: the package's. */
78
+ readonly version: string;
79
+ /** The keys of the package's `exports`. */
80
+ readonly exports: readonly string[];
81
+ /** What it is, in a sentence, for the requirement made of it. */
82
+ readonly summary?: string;
83
+ /** 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
+ readonly distribution: readonly Registry[];
85
+ };
86
+
87
+ /** The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018). */
88
+ export const REGISTRIES = ["github", "npm"] as const;
89
+ export type Registry = (typeof REGISTRIES)[number];
90
+ /** Where a manifest that declares no distribution is published. */
91
+ export const DEFAULT_DISTRIBUTION: readonly Registry[] = ["github"];
92
+
93
+ const nonEmpty: Decoder<string> = (input, path = "$") => {
94
+ const r = string(input, path);
95
+ if (r.kind === "err") return r;
96
+ return r.value.trim() === "" ? err({ kind: "decode", path, expected: "a non-empty string", found: describe(input) }) : r;
97
+ };
98
+ const nameDecoder: Decoder<string> = (input, path = "$") => {
99
+ const r = string(input, path);
100
+ if (r.kind === "err") return r;
101
+ return /^[a-z][a-z0-9-]*$/.test(r.value)
102
+ ? r
103
+ : err({ kind: "decode", path, expected: "a name of lower-case letters, digits and hyphens", found: describe(input) });
104
+ };
105
+ const body = object(
106
+ { name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) },
107
+ { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)) },
108
+ );
109
+ const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution"] as const;
110
+
111
+ /** 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
+ export function decodeLibrarySource(source: string): Result<Library, string> {
113
+ const exports = source.split("\n").filter((l) => /^export\s/.test(l));
114
+ if (exports.length !== 1) return err(`a manifest exports only library, and this file has ${exports.length} exports`);
115
+ const lit = exportedLiteral(source, "library");
116
+ if (lit.kind === "err") return err(`the manifest is not a literal: ${lit.error.expected}`);
117
+ const input = lit.value;
118
+ if (typeof input === "object" && input !== null && !Array.isArray(input)) {
119
+ const known: readonly string[] = FIELDS;
120
+ const bad = Object.keys(input).find((k) => !known.includes(k));
121
+ if (bad !== undefined) return err(`library.${bad} is an unknown field (a manifest has ${FIELDS.join(", ")})`);
122
+ }
123
+ const r = body(input, "library");
124
+ if (r.kind === "err") return err(formatDecodeError(r.error));
125
+ const v = r.value;
126
+ const distribution = v.distribution ?? DEFAULT_DISTRIBUTION;
127
+ if (distribution.length === 0 || new Set(distribution).size !== distribution.length)
128
+ return err("library.distribution lists each registry once and at least one (FR-015)");
129
+ if (!distribution.includes("github"))
130
+ return err(
131
+ "library.distribution includes github: a library is published to the GitHub package registry whatever else it is published to (FR-015, FR-016)",
132
+ );
133
+ return ok({
134
+ name: v.name,
135
+ level: v.level ?? DEFAULT_LIBRARY_LEVEL,
136
+ ...(v.specKit === undefined ? {} : { specKit: v.specKit }),
137
+ verify: v.verify,
138
+ version: v.version,
139
+ exports: v.exports,
140
+ ...(v.summary === undefined ? {} : { summary: v.summary }),
141
+ distribution,
142
+ });
143
+ }
144
+
145
+ /** A library found in the folder of commons: its folder and what its manifest says, or why it cannot be read. */
146
+ export type Found = { readonly dir: string; readonly library: Library } | { readonly dir: string; readonly problem: string };
147
+
148
+ /** The manifests of `commons/*`, in the order of the folders' names: every folder that holds a `library.ts`. */
149
+ export function readLibraries(repo: string): readonly Found[] {
150
+ const commons = `${repo.replace(/[\\/]$/, "")}/commons`;
151
+ if (!existsSync(commons)) return [];
152
+ return readDirSync(commons)
153
+ .filter((e) => e.isDirectory && existsSync(`${commons}/${e.name}/${LIBRARY_FILE}`))
154
+ .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
155
+ .map((e): Found => {
156
+ const r = decodeLibrarySource(readTextFileSync(`${commons}/${e.name}/${LIBRARY_FILE}`));
157
+ return r.kind === "ok" ? { dir: e.name, library: r.value } : { dir: e.name, problem: r.error };
158
+ });
159
+ }
160
+
161
+ /** The keys of a package's `exports`, its name and version and the scripts it has, read from `package.json`. */
162
+ function packageOf(file: string): {
163
+ readonly name?: string;
164
+ readonly version?: string;
165
+ readonly exports: readonly string[];
166
+ readonly scripts: readonly string[];
167
+ } {
168
+ const raw: unknown = JSON.parse(readTextFileSync(file));
169
+ const o = typeof raw === "object" && raw !== null ? raw : {};
170
+ const field = (k: string): unknown => Object.entries(o).find(([n]) => n === k)?.[1];
171
+ const keys = (v: unknown): readonly string[] => (typeof v === "object" && v !== null ? Object.keys(v) : []);
172
+ const name = field("name");
173
+ const version = field("version");
174
+ return {
175
+ ...(typeof name === "string" ? { name } : {}),
176
+ ...(typeof version === "string" ? { version } : {}),
177
+ exports: keys(field("exports")),
178
+ scripts: keys(field("scripts")),
179
+ };
180
+ }
181
+
182
+ /** The script a verify command runs: `bun run verify` runs the script `verify`. */
183
+ function scriptOf(verify: string): string | undefined {
184
+ return /^bun run ([A-Za-z0-9:_-]+)$/.exec(verify)?.[1];
185
+ }
186
+
187
+ /**
188
+ * What is wrong where a manifest and its folder disagree (0027-commons-libraries FR-013), one sentence each: a folder with a spec kit and no manifest, a manifest that cannot be read, that names another
189
+ * folder, a level above L0 with no spec kit, a spec kit that is not there, a package of another name, a version that is not the package's, exports that are not the package's, and a verify that is no script of the package.
190
+ */
191
+ export function manifestFindings(repo: string): readonly string[] {
192
+ const root = repo.replace(/[\\/]$/, "");
193
+ const commons = `${root}/commons`;
194
+ const found: string[] = [];
195
+ const have = readLibraries(root);
196
+ for (const e of existsSync(commons) ? readDirSync(commons) : [])
197
+ if (e.isDirectory && existsSync(`${commons}/${e.name}/spec-kit`) && !have.some((l) => l.dir === e.name))
198
+ found.push(`commons/${e.name} has a spec kit and no ${LIBRARY_FILE}: a library declares itself (FR-012)`);
199
+ for (const f of have) {
200
+ const dir = `${commons}/${f.dir}`;
201
+ if ("problem" in f) {
202
+ found.push(`commons/${f.dir}/${LIBRARY_FILE}: ${f.problem} (FR-012)`);
203
+ continue;
204
+ }
205
+ const l = f.library;
206
+ if (l.name !== f.dir) found.push(`commons/${f.dir}/${LIBRARY_FILE} is named ${l.name}, and its folder is ${f.dir} (FR-013)`);
207
+ if (rankOf(l.level) >= 1 && l.specKit === undefined)
208
+ found.push(`commons/${f.dir}/${LIBRARY_FILE} declares ${l.level} and no spec kit, which a level above L0 asks (FR-013)`);
209
+ if (l.specKit !== undefined && !existsSync(`${dir}/${l.specKit}/registry.tsv`))
210
+ found.push(`commons/${f.dir}: the spec kit ${l.specKit} the manifest names has no registry.tsv (FR-013)`);
211
+ if (!existsSync(`${dir}/package.json`)) {
212
+ found.push(`commons/${f.dir}/package.json is missing (FR-013)`);
213
+ continue;
214
+ }
215
+ const pkg = packageOf(`${dir}/package.json`);
216
+ if (pkg.name !== `@intellectual-frontiers/${l.name}`)
217
+ found.push(`commons/${f.dir}/package.json is not named @intellectual-frontiers/${l.name} (FR-013)`);
218
+ if (pkg.version !== l.version)
219
+ found.push(`commons/${f.dir}: the manifest says version ${l.version} and the package says ${pkg.version ?? "none"} (FR-013)`);
220
+ const missing = l.exports.filter((x) => !pkg.exports.includes(x));
221
+ const extra = pkg.exports.filter((x) => !l.exports.includes(x));
222
+ if (missing.length > 0 || extra.length > 0)
223
+ found.push(
224
+ `commons/${f.dir}: the manifest and the package disagree on exports (${[...missing.map((x) => `${x} is not the package's`), ...extra.map((x) => `${x} is not the manifest's`)].join("; ")}) (FR-013)`,
225
+ );
226
+ const script = scriptOf(l.verify);
227
+ if (script === undefined || !pkg.scripts.includes(script))
228
+ found.push(`commons/${f.dir}: the verify command ${JSON.stringify(l.verify)} is not a script of the package (FR-013)`);
229
+ const verifyText = script === undefined ? "" : scriptText(`${dir}/package.json`, script);
230
+ if (rankOf(l.level) >= 1 && rankOf(l.level) < rankOf("L3") && !verifyText.includes(`--level ${l.level}`))
231
+ found.push(
232
+ `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
+ );
234
+ }
235
+ return found;
236
+ }
237
+
238
+ /** A field of a value read from JSON, `undefined` where the value is not an object or has no such field. */
239
+ function fieldOf(value: unknown, key: string): unknown {
240
+ return typeof value === "object" && value !== null ? Object.entries(value).find(([n]) => n === key)?.[1] : undefined;
241
+ }
242
+
243
+ function scriptText(file: string, script: string): string {
244
+ const raw: unknown = JSON.parse(readTextFileSync(file));
245
+ const text = fieldOf(fieldOf(raw, "scripts"), script);
246
+ return typeof text === "string" ? text : "";
247
+ }
248
+
249
+ /** The ontology's name for a level of a manifest: `mz:Registered`, `mz:Core`, `mz:Standards` or `mz:Governed`. */
250
+ const LEVEL_TERM: Readonly<Record<LevelKey, string>> = { L0: "mz:Registered", L1: "mz:Core", L2: "mz:Standards", L3: "mz:Governed" };
251
+
252
+ /** How a registry is named in the requirement of a library. */
253
+ const REGISTRY_NAME: Readonly<Record<Registry, string>> = { github: "the GitHub package registry", npm: "npm" };
254
+
255
+ const list = (items: readonly string[]): string => {
256
+ const quoted = items.map((i) => `\`${i}\``);
257
+ return quoted.length <= 1 ? (quoted[0] ?? "no exports") : `${quoted.slice(0, -1).join(", ")} and ${quoted[quoted.length - 1] ?? ""}`;
258
+ };
259
+
260
+ /** The requirement of a library, as the section "The libraries" holds it (FR-014): one line. */
261
+ export function requirementOf(id: string, l: Library): string {
262
+ const kit = l.specKit === undefined ? "" : `, its spec kit at \`commons/${l.name}/${l.specKit}\``;
263
+ const summary = l.summary === undefined ? "" : ` ${l.summary}`;
264
+ const where = l.distribution.map((r) => REGISTRY_NAME[r]).join(" and ");
265
+ return `- **${id}**: \`commons/${l.name}\` MUST be a library at conformance level ${l.level} (\`${LEVEL_TERM[l.level]}\`): the package \`@intellectual-frontiers/${l.name}\` at version \`${l.version}\`${kit}, exporting ${list(l.exports)}, published to ${where}, proved by \`cd commons/${l.name} && ${l.verify}\`.${summary}`;
266
+ }
267
+
268
+ /** The row of `enforcement.tsv` of a library's requirement. */
269
+ export function rowOf(id: string, l: Library): string {
270
+ const kit = l.specKit === undefined ? "its manifest" : "its compiler, specification checker, rules and tests";
271
+ return `${LIBRARIES_SPEC} ${id}\tcheck\t.github: cd commons/${l.name} && ${l.verify}\tcommons/${l.name}: the verify of the library (${kit}); the manifest ${LIBRARY_FILE} agrees with the folder and the package (commons-libraries.test.ts)`;
272
+ }
273
+
274
+ /** The ids the section already gives each library, by name, read from its text between the markers. */
275
+ export function idsIn(spec: string): ReadonlyMap<string, string> {
276
+ const out = new Map<string, string>();
277
+ const b = bounds(spec);
278
+ if (b === undefined) return out;
279
+ for (const line of spec.slice(b.from, b.to).split("\n")) {
280
+ const m = /^- \*\*(FR-\d+)\*\*: `commons\/([a-z][a-z0-9-]*)`/.exec(line);
281
+ if (m?.[1] !== undefined && m[2] !== undefined) out.set(m[2], m[1]);
282
+ }
283
+ return out;
284
+ }
285
+
286
+ /** The id each library has: the one it had, or the next number after the greatest. */
287
+ export function idsFor(libraries: readonly Library[], had: ReadonlyMap<string, string>): ReadonlyMap<string, string> {
288
+ const out = new Map<string, string>();
289
+ let next = Math.max(FIRST_GENERATED - 1, ...[...had.values()].map((id) => Number(id.slice(3)))) + 1;
290
+ for (const l of libraries) {
291
+ const id = had.get(l.name);
292
+ if (id !== undefined) out.set(l.name, id);
293
+ else out.set(l.name, `FR-${String(next++).padStart(3, "0")}`);
294
+ }
295
+ return out;
296
+ }
297
+
298
+ /** The text of the specification and of the register, made again from the libraries: nothing where the specification has no markers. */
299
+ export function generated(
300
+ spec: string,
301
+ enforcement: string,
302
+ libraries: readonly Library[],
303
+ ): Result<{ readonly spec: string; readonly enforcement: string }, string> {
304
+ const b = bounds(spec);
305
+ if (b === undefined)
306
+ return err(`${LIBRARIES_SPEC} has no ${BEGIN} and ${END}, each on a line of its own, around the section "The libraries"`);
307
+ const ids = idsFor(libraries, idsIn(spec));
308
+ // in the order of their numbers, which a library keeps for its life: a library added later is after those that were there, whatever its name
309
+ const byNumber = [...libraries].sort((a, b) => Number((ids.get(a.name) ?? "").slice(3)) - Number((ids.get(b.name) ?? "").slice(3)));
310
+ const lines = byNumber.map((l) => requirementOf(ids.get(l.name) ?? "", l));
311
+ const newSpec = `${spec.slice(0, b.from + BEGIN.length)}\n\n${lines.join("\n")}\n\n${spec.slice(b.to)}`;
312
+ const rows = byNumber.map((l) => rowOf(ids.get(l.name) ?? "", l));
313
+ const kept = enforcement.split("\n").filter((l) => l !== "" && !new RegExp(`^${LIBRARIES_SPEC} FR-(?:[1-9]\\d{2,})\\t`).test(l));
314
+ const last = kept.map((l, i) => (l.startsWith(`${LIBRARIES_SPEC} `) ? i : -1)).reduce((a, b) => Math.max(a, b), -1);
315
+ const at = last < 0 ? kept.length : last + 1;
316
+ return ok({ spec: newSpec, enforcement: `${[...kept.slice(0, at), ...rows, ...kept.slice(at)].join("\n")}\n` });
317
+ }
318
+
319
+ const SPEC_FILE = (repo: string): string => `${repo}/commons/spec-kit/specs/${LIBRARIES_SPEC}/spec.md`;
320
+ const ENFORCEMENT_FILE = (repo: string): string => `${repo}/commons/spec-kit/enforcement.tsv`;
321
+
322
+ /** The files that are not what the manifests make (relative to the repository), and what is wrong with the manifests; with `write`, the files are written. */
323
+ export function synchronize(repo: string, write: boolean): { readonly stale: readonly string[]; readonly problems: readonly string[] } {
324
+ const root = repo.replace(/[\\/]$/, "");
325
+ const have = readLibraries(root);
326
+ const problems = [
327
+ ...have.flatMap((f) => ("problem" in f ? [`commons/${f.dir}/${LIBRARY_FILE}: ${f.problem}`] : [])),
328
+ ...manifestFindings(root),
329
+ ];
330
+ const libraries = have.flatMap((f) => ("library" in f ? [f.library] : []));
331
+ const spec = readTextFileSync(SPEC_FILE(root)).replace(/\r\n/g, "\n"); // a Windows checkout may hold CRLF; the markers are found on lines of LF
332
+ const enforcement = readTextFileSync(ENFORCEMENT_FILE(root)).replace(/\r\n/g, "\n");
333
+ const made = generated(spec, enforcement, libraries);
334
+ if (made.kind === "err") return { stale: [], problems: [...problems, made.error] };
335
+ const stale: string[] = [];
336
+ if (made.value.spec !== spec) {
337
+ stale.push(`commons/spec-kit/specs/${LIBRARIES_SPEC}/spec.md`);
338
+ if (write) writeTextFileSync(SPEC_FILE(root), made.value.spec);
339
+ }
340
+ if (made.value.enforcement !== enforcement) {
341
+ stale.push("commons/spec-kit/enforcement.tsv");
342
+ if (write) writeTextFileSync(ENFORCEMENT_FILE(root), made.value.enforcement);
343
+ }
344
+ return { stale, problems };
345
+ }
346
+
347
+ /** The result of one library's `verify`. */
348
+ export type Verified = { readonly name: string; readonly code: number };
349
+
350
+ /** Runs the `verify` of every library a manifest declares, each from its own folder, and gives each status (0028-conformance-levels FR-012). */
351
+ export async function verifyAll(repo: string): Promise<readonly Verified[]> {
352
+ const root = repo.replace(/[\\/]$/, "");
353
+ const out: Verified[] = [];
354
+ for (const f of readLibraries(root)) {
355
+ if ("problem" in f) {
356
+ out.push({ name: f.dir, code: 1 });
357
+ continue;
358
+ }
359
+ stdio.stderr.writeSync(`verify ${f.dir}: ${f.library.verify}\n`);
360
+ const [cmd, ...args] = f.library.verify.split(" ");
361
+ try {
362
+ await using child = spawn([cmd ?? "", ...args], { cwd: `${root}/commons/${f.dir}` });
363
+ const status = await child.status;
364
+ out.push({ name: f.dir, code: status.code });
365
+ } catch (e) {
366
+ stdio.stderr.writeSync(`verify ${f.dir}: ${e instanceof Error ? e.message : String(e)}\n`);
367
+ out.push({ name: f.dir, code: 1 });
368
+ }
369
+ }
370
+ return out;
371
+ }
372
+
373
+ /** The command line. Returns the exit status: 0, or 1 where a file is not what the manifests make or a manifest and its folder disagree. */
374
+ export function main(argv: readonly string[]): number {
375
+ const at = argv.indexOf("--repo");
376
+ const repo = at >= 0 ? (argv[at + 1] ?? ".") : ".";
377
+ const check = argv.includes("--check");
378
+ const r = synchronize(repo, !check);
379
+ for (const p of r.problems) stdio.stderr.writeSync(`${p}\n`);
380
+ for (const s of r.stale)
381
+ stdio.stderr.writeSync(check ? `${s} is not what the manifests make; run: bun commons/libraries/src/libraries.ts\n` : `wrote ${s}\n`);
382
+ return r.problems.length > 0 || (check && r.stale.length > 0) ? 1 : 0;
383
+ }
384
+
385
+ if (import.meta.main) process.exitCode = main(process.argv.slice(2));
package/src/mod.ts ADDED
@@ -0,0 +1,16 @@
1
+ /**
2
+ * What of Mizan is still in this package (commons 0032-lifting-libraries): the commands that need the whole repository. `check.ts` holds a repository's spec kit and ontologies, `versions.ts` and
3
+ * `changes.ts` are the commands of the release check and the change-control check, `libraries.ts` reads the manifests of the libraries, `newer.ts` reports a standard newer than its pin, `generate-ontology.ts` writes the Turtle of the ontologies and
4
+ * `oscal-register.ts` the register of proofs as OSCAL. The harness, the rules, the levels, the integrations, the change-control and release rules as plugins, and the trace of requirements are the
5
+ * library `mizan` (`@intellectual-frontiers/mizan`), and the ontologies are the library `ontology` (`@intellectual-frontiers/ontology`).
6
+ *
7
+ * Spec: 0001-libraries FR-010
8
+ *
9
+ * @module
10
+ */
11
+ export { decodeLibrarySource, type Library, LIBRARY_FILE, manifestFindings, readLibraries, verifyAll } from "./libraries.ts";
12
+ export { termRecordsOf } from "./check.ts";
13
+ export { staleFindings, type Fetched, type LatestManifest } from "./newer.ts";
14
+ export { checkVersions, run as runVersions, type VersionsCheck } from "./versions.ts";
15
+ export { digestOf, findingsOf, RUN, TURTLE_PATH, turtleOf } from "./generate-ontology.ts";
16
+ export { COMPONENT_FILE, registerDocuments, registerRows, RESULTS_FILE, type RegisterInput, type RegisterRow } from "./oscal-register.ts";