@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,470 @@
1
+ /**
2
+ * The `changes` check of Intellectual Frontiers Capabilities Configuration Management (commons 0020-ifccm): every commit of a range names the change request it serves, a closing word is
3
+ * `Closes` and only on the commit that finishes a capability, a departure from a specification has a Decision, a relaxed declaration is found, and each requirement can be followed from its issue
4
+ * to the run that proved it.
5
+ *
6
+ * bun commons/libraries/src/changes.ts --range origin/main..HEAD judge the commits of the range (offline: no network)
7
+ * bun commons/libraries/src/changes.ts --range A..B --strict also ask the Git host for each change request the commits name
8
+ * bun commons/libraries/src/changes.ts --declaration FILE read the harness's record (declaration, decisions, roles) from FILE (`ifccm.declaration.ts` by default)
9
+ * bun commons/libraries/src/changes.ts --capabilities FILE --document FILE [--check]
10
+ * write the view of capabilities by rung into the document, or with --check fail where it differs
11
+ * bun commons/libraries/src/changes.ts --trace ISSUE_BODY_FILE [--runs RECORD] [--specs DIR]
12
+ * follow each requirement of a `Done when` from its term to the run, and say where the chain ends
13
+ * bun commons/libraries/src/changes.ts --capability-trace --range A..B [--issues FILE] [--terms FILE|commons] [--rungs FILE] [--runs RECORD] [--specs DIR] [--format text|json] [--output FILE]
14
+ * offline: from the commits' `Refs`/`Closes #N` lines, the specifications' requirements, the ontology's `mz:definedBy`, the `Spec:`/`Proves:` lines
15
+ * and a quality record, the chain of each requirement of each capability (terms, code, tests) on each rung, as a table or as JSON;
16
+ * with --document FILE [--check] the view of capabilities by rung is made from the commits and written between its markers
17
+ * other flags: --repo DIR (the repository, the working folder by default), --today YYYY-MM-DD, --baseline FILE (`changes.baseline.txt` of the repository by default), --write-baseline
18
+ *
19
+ * Exit status: 0 clean, 1 findings (or a stale baseline line, or a chain that breaks, or a view that differs), 2 usage, 3 environment (no `git`, not a repository, a file that cannot be read).
20
+ * A strict rule that could not ask the host is `not_run` with its reason on standard error and is never reported as passed (0020-ifccm FR-030). The host's client is given to `run`, never made
21
+ * here: whoever wires the adapters passes it.
22
+ *
23
+ * Spec: 0001-libraries FR-008
24
+ *
25
+ * @module
26
+ */
27
+ import process from "node:process";
28
+ import { formatBaseline, judge, parseBaseline, passes, report } from "@intellectual-frontiers/mizan/trace";
29
+ import { readRecord } from "@intellectual-frontiers/quality/test-report";
30
+ import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
31
+ import { formatGitError } from "@intellectual-frontiers/system/git";
32
+ import { cwd } from "@intellectual-frontiers/system/proc";
33
+ import { join, relative, resolve } from "@intellectual-frontiers/system/path";
34
+ import { stdio } from "@intellectual-frontiers/system";
35
+ import { capabilityTrace, NO_RUNG, parseIssues, traceOutput, } from "@intellectual-frontiers/mizan/changes/capability-trace";
36
+ import { decodeViewRecord, formatViewError, spliceView, viewIsCurrent, viewOf, } from "@intellectual-frontiers/mizan/changes/capability-view";
37
+ import { dayOf, decodeHarnessRecord, formatRecordError, phaseOf, relaxations, } from "@intellectual-frontiers/mizan/changes/declaration";
38
+ import { declarationHistory, readRange, readRangeFacts } from "@intellectual-frontiers/mizan/changes/git-log";
39
+ import { readTermsFile } from "@intellectual-frontiers/mizan/changes/terms-file";
40
+ import { doneWhenRequirements, parseIssueBody } from "@intellectual-frontiers/mizan/changes/issue-body";
41
+ import { CHANGES_RULES, commitFindings, declarationFindings, relaxationFindings, ruleCases, STRICT_RULES, strictFindings, } from "@intellectual-frontiers/mizan/changes/rules";
42
+ import { askHost, NO_CLIENT } from "@intellectual-frontiers/mizan/changes/strict";
43
+ import { traceLines, traceOf, firstBreak } from "@intellectual-frontiers/mizan/changes/trace";
44
+ import { readSpecTexts } from "@intellectual-frontiers/mizan/spec-files";
45
+ import { packagingTerms } from "@intellectual-frontiers/ontology/audit";
46
+ import * as ifccmOntology from "@intellectual-frontiers/ontology/ifccm";
47
+ import * as ifqsOntology from "@intellectual-frontiers/ontology/ifqs";
48
+ import { terms } from "@intellectual-frontiers/ontology/mizan";
49
+ /** The rules that need no range of commits: the declaration's own, and its history. */
50
+ const WITHOUT_RANGE = ["changes/declaration", "changes/gate-relaxed"];
51
+ /** The default name of a harness's record, in the repository's top folder. */
52
+ export const RECORD_FILE = "ifccm.declaration.ts";
53
+ /** The default name of the baseline of the check's findings, in the repository's top folder. */
54
+ export const BASELINE_FILE = "changes.baseline.txt";
55
+ const COMMENTS = [
56
+ "The findings of the changes check (commons 0020-ifccm FR-011) held while the harness has not declared production.",
57
+ "A new finding fails the check, and so does a line below that no longer occurs: when you fix one, delete its line.",
58
+ "Never add a line to make a check pass. A finding in the gate phase is never held by this file.",
59
+ ];
60
+ const VALUE_FLAGS = [
61
+ "--repo",
62
+ "--range",
63
+ "--declaration",
64
+ "--today",
65
+ "--baseline",
66
+ "--capabilities",
67
+ "--document",
68
+ "--trace",
69
+ "--runs",
70
+ "--specs",
71
+ "--issues",
72
+ "--terms",
73
+ "--rungs",
74
+ "--format",
75
+ "--output",
76
+ ];
77
+ const SWITCH_FLAGS = ["--strict", "--check", "--write-baseline", "--capability-trace"];
78
+ /** The flags of a command line, or the sentence that says what is wrong with it. */
79
+ function parseFlags(argv) {
80
+ const values = new Map();
81
+ const switches = new Set();
82
+ for (let i = 0; i < argv.length; i++) {
83
+ const a = argv[i] ?? "";
84
+ const eq = a.indexOf("=");
85
+ const name = eq > 0 ? a.slice(0, eq) : a;
86
+ if (SWITCH_FLAGS.some((f) => f === name) && eq < 0)
87
+ switches.add(name);
88
+ else if (VALUE_FLAGS.some((f) => f === name)) {
89
+ const value = eq > 0 ? a.slice(eq + 1) : argv[++i];
90
+ if (value === undefined || value === "")
91
+ return `${name} needs a value`;
92
+ values.set(name, value);
93
+ }
94
+ else
95
+ return `unknown argument ${a}`;
96
+ }
97
+ return { values, switches };
98
+ }
99
+ /** Every `.ts` file under a folder (skipping `node_modules`, `.git` and `.claude`), as `{ path (relative, with /), text }`. */
100
+ function sourcesUnder(root) {
101
+ const out = [];
102
+ const walk = (dir) => {
103
+ for (const e of readDirSync(dir)) {
104
+ if (e.name === "node_modules" || e.name === ".git" || e.name === ".claude")
105
+ continue;
106
+ const p = join(dir, e.name);
107
+ if (e.isDirectory)
108
+ walk(p);
109
+ else if (e.name.endsWith(".ts"))
110
+ out.push({ path: relative(root, p).replaceAll("\\", "/"), text: readTextFileSync(p) });
111
+ }
112
+ };
113
+ walk(root);
114
+ return out;
115
+ }
116
+ /** The citations of requirements by the terms of commons' own ontologies (`mz:definedBy`), for the chain's third stage (`--terms commons`, and the default of `--trace`). */
117
+ function termCitations() {
118
+ return [...terms, ...packagingTerms, ...ifccmOntology.terms, ...ifqsOntology.terms].map((t) => ({
119
+ term: t.values.termIri,
120
+ cites: t.values.definedBy ?? [],
121
+ file: "commons/ontology",
122
+ }));
123
+ }
124
+ /** The ontology's citations a command line names: commons' own where `--terms commons` (and, for `--trace`, where none is named), else the file's. */
125
+ async function termsOf(named, repo, log, fallback = "commons") {
126
+ if (named === undefined)
127
+ return fallback === "commons" ? termCitations() : [];
128
+ if (named === "commons")
129
+ return termCitations();
130
+ const r = await readTermsFile(resolve(repo, named));
131
+ if (r.kind === "err") {
132
+ log(`changes: --terms: ${r.error}\n`);
133
+ return 3;
134
+ }
135
+ return r.value;
136
+ }
137
+ /** The view's capabilities made from a trace: a number, a title, the rungs its files are on and its last commit; the rungs and runs are the record's. */
138
+ function viewOfTrace(t, record) {
139
+ const capabilities = t.capabilities.map((c) => ({
140
+ id: c.number,
141
+ title: c.title ?? `#${c.number}`,
142
+ touchesRung: c.rungs.filter((r) => r !== NO_RUNG),
143
+ lastRevision: c.commits[c.commits.length - 1] ?? "",
144
+ }));
145
+ return { rungs: record.rungs, capabilities, runs: record.runs };
146
+ }
147
+ /** The offline trace of a range: its commits, specifications, terms, files, runs, change requests and rungs read, or the exit code and the reason it could not be. */
148
+ async function offlineTrace(repo, value, log) {
149
+ const read = await readRangeFacts(repo, value("--range") ?? "");
150
+ if (read.kind === "err") {
151
+ log(`changes: ${formatGitError(read.error)}\n`);
152
+ return 3;
153
+ }
154
+ const exists = (name) => {
155
+ const f = value(name);
156
+ if (f === undefined)
157
+ return undefined;
158
+ const path = resolve(repo, f);
159
+ if (existsSync(path))
160
+ return path;
161
+ log(`changes: ${name} ${path} does not exist\n`);
162
+ return "";
163
+ };
164
+ let issues = [];
165
+ const issuesFile = exists("--issues");
166
+ if (issuesFile === "")
167
+ return 3;
168
+ if (issuesFile !== undefined) {
169
+ const r = parseIssues(readTextFileSync(issuesFile));
170
+ if (r.kind === "err") {
171
+ log(`changes: ${issuesFile}: ${r.error}\n`);
172
+ return 3;
173
+ }
174
+ issues = r.value;
175
+ }
176
+ let record = { rungs: [], capabilities: [], runs: [] };
177
+ const rungsFile = exists("--rungs") ?? exists("--capabilities");
178
+ if (rungsFile === "")
179
+ return 3;
180
+ if (rungsFile !== undefined) {
181
+ const r = decodeViewRecord(readTextFileSync(rungsFile), false);
182
+ if (r.kind === "err") {
183
+ log(`changes: ${rungsFile}: ${r.error}\n`);
184
+ return 3;
185
+ }
186
+ record = r.value;
187
+ }
188
+ let cases = [];
189
+ const runsFile = exists("--runs");
190
+ if (runsFile === "")
191
+ return 3;
192
+ if (runsFile !== undefined) {
193
+ const rec = readRecord(readTextFileSync(runsFile));
194
+ if (rec.kind === "err") {
195
+ log(`changes: ${runsFile} is not a test record\n`);
196
+ return 3;
197
+ }
198
+ cases = rec.value.tests.map((t) => ({ requirements: t.requirements, outcome: t.outcome }));
199
+ }
200
+ const terms = await termsOf(value("--terms"), repo, log, "none");
201
+ if (typeof terms === "number")
202
+ return terms;
203
+ const specsRoot = value("--specs") !== undefined
204
+ ? resolve(repo, value("--specs") ?? "")
205
+ : existsSync(join(repo, "specs"))
206
+ ? repo
207
+ : join(repo, "commons", "spec-kit");
208
+ const files = sourcesUnder(repo);
209
+ const rungs = record.rungs;
210
+ const result = capabilityTrace({
211
+ commits: read.value,
212
+ issues,
213
+ specs: readSpecTexts(specsRoot).map((s) => ({ slug: s.slug, spec: s.spec })),
214
+ terms,
215
+ sources: files.filter((f) => !f.path.endsWith(".test.ts")),
216
+ tests: files.filter((f) => f.path.endsWith(".test.ts")),
217
+ cases,
218
+ rungs: rungs.map((r) => ({ id: r.id, label: r.label, homes: r.homes ?? [] })),
219
+ specPath: (slug) => relative(repo, join(specsRoot, "specs", slug, "spec.md")).replaceAll("\\", "/"),
220
+ });
221
+ return { result, record };
222
+ }
223
+ /** Run the command; the exit status (0 clean, 1 findings, 2 usage, 3 environment). */
224
+ export async function run(argv, deps = {}, now = () => new Date().toISOString().slice(0, 10)) {
225
+ const out = deps.out ?? ((t) => void stdio.stdout.writeSync(t));
226
+ const log = deps.err ?? ((t) => void stdio.stderr.writeSync(t));
227
+ const flags = parseFlags(argv);
228
+ if (typeof flags === "string") {
229
+ log(`changes: ${flags}\nusage: changes.ts [--range A..B] [--strict] [--declaration FILE] [--check] [--capabilities FILE --document FILE] [--trace BODY] [--capability-trace --range A..B [--issues FILE] [--terms FILE] [--rungs FILE] [--runs RECORD] [--format text|json] [--output FILE]] [--repo DIR] [--today DAY] [--baseline FILE] [--write-baseline]\n`);
230
+ return 2;
231
+ }
232
+ const value = (name) => flags.values.get(name);
233
+ const has = (name) => flags.switches.has(name);
234
+ const repo = resolve(value("--repo") ?? cwd());
235
+ const today = value("--today") ?? now();
236
+ if (dayOf(today) === undefined) {
237
+ log(`changes: --today ${today} is not a day (YYYY-MM-DD)\n`);
238
+ return 2;
239
+ }
240
+ if (has("--strict") && value("--range") === undefined) {
241
+ log("changes: --strict asks the host about the commits of a range: give --range\n");
242
+ return 2;
243
+ }
244
+ const offline = has("--capability-trace");
245
+ if (offline && value("--range") === undefined) {
246
+ log("changes: --capability-trace reads the commits of a range: give --range\n");
247
+ return 2;
248
+ }
249
+ if (has("--check") && ((value("--capabilities") === undefined && !offline) || value("--document") === undefined)) {
250
+ log("changes: --check needs --capabilities FILE and --document FILE (or --capability-trace and --document FILE)\n");
251
+ return 2;
252
+ }
253
+ const asked = value("--format") ?? "text";
254
+ if (asked !== "text" && asked !== "json") {
255
+ log(`changes: --format ${asked} is not text or json\n`);
256
+ return 2;
257
+ }
258
+ const format = asked;
259
+ // the harness's record
260
+ const recordPath = value("--declaration") !== undefined ? resolve(repo, value("--declaration") ?? "") : join(repo, RECORD_FILE);
261
+ let record = { declaration: undefined, decisions: [], roles: {} };
262
+ if (existsSync(recordPath)) {
263
+ const r = decodeHarnessRecord(readTextFileSync(recordPath));
264
+ if (r.kind === "err") {
265
+ log(`changes: ${recordPath}: ${formatRecordError(r.error)}\n`);
266
+ return 3;
267
+ }
268
+ record = r.value;
269
+ }
270
+ else if (value("--declaration") !== undefined) {
271
+ log(`changes: ${recordPath} does not exist\n`);
272
+ return 3;
273
+ }
274
+ const phase = phaseOf(record.declaration, today);
275
+ const recordName = relative(repo, recordPath).replaceAll("\\", "/");
276
+ const findings = [...declarationFindings(record.declaration, recordName)];
277
+ let notRun;
278
+ let failed = false;
279
+ // the declaration's history: a day moved later or a domain dropped
280
+ if (existsSync(recordPath) && existsSync(join(repo, ".git"))) {
281
+ const history = await declarationHistory(repo, recordName);
282
+ if (history.kind === "err") {
283
+ log(`changes: ${formatGitError(history.error)}\n`);
284
+ return 3;
285
+ }
286
+ findings.push(...relaxationFindings(relaxations(history.value), record.decisions, phase, recordName));
287
+ }
288
+ // the commits of a range
289
+ const range = value("--range");
290
+ if (range !== undefined) {
291
+ const read = await readRange(repo, range);
292
+ if (read.kind === "err") {
293
+ log(`changes: ${formatGitError(read.error)}\n`);
294
+ return 3;
295
+ }
296
+ const commits = read.value;
297
+ findings.push(...commitFindings(commits, {
298
+ phase,
299
+ ...(record.declaration === undefined ? {} : { declaration: record.declaration }),
300
+ decisions: record.decisions,
301
+ roles: record.roles,
302
+ }));
303
+ if (has("--strict")) {
304
+ const home = deps.home;
305
+ const asked = home === undefined && deps.client !== undefined
306
+ ? { answers: new Map(), notRun: "the repository's reference on the host was not given" }
307
+ : home === undefined
308
+ ? { answers: new Map(), notRun: NO_CLIENT }
309
+ : await askHost(deps.client, home, commits);
310
+ notRun = asked.notRun;
311
+ findings.push(...strictFindings(commits, asked.answers, phase));
312
+ }
313
+ }
314
+ // each rule's result, for the record of the run (FR-031): a rule that was not run is never a pass
315
+ if (deps.onRules !== undefined) {
316
+ const strict = has("--strict");
317
+ deps.onRules(CHANGES_RULES.map((rule) => {
318
+ const why = range === undefined && !WITHOUT_RANGE.includes(rule)
319
+ ? "no --range was given, so no commit was judged"
320
+ : STRICT_RULES.includes(rule)
321
+ ? !strict
322
+ ? "--strict was not given, so the host was not asked"
323
+ : notRun
324
+ : undefined;
325
+ if (why !== undefined)
326
+ return { id: rule, findings: [], notRun: why };
327
+ return {
328
+ id: rule,
329
+ findings: findings.filter((f) => f.rule === rule).map((f) => ({ file: f.file, line: f.line, message: f.message })),
330
+ };
331
+ }));
332
+ }
333
+ // judgement against the baseline: a warning is held by it, a finding in the gate phase never is
334
+ const baselineFile = value("--baseline") !== undefined ? resolve(repo, value("--baseline") ?? "") : join(repo, BASELINE_FILE);
335
+ const warned = findings.filter((f) => f.severity === "warn");
336
+ const gated = findings.filter((f) => f.severity === "gate");
337
+ if (has("--write-baseline")) {
338
+ writeTextFileSync(baselineFile, formatBaseline(warned, COMMENTS));
339
+ out(`wrote ${baselineFile}: ${new Set(warned.map((f) => f.key)).size} findings\n`);
340
+ }
341
+ else if (range !== undefined || findings.length > 0) {
342
+ const held = existsSync(baselineFile) ? parseBaseline(readTextFileSync(baselineFile)) : [];
343
+ // a baseline line is stale only where this run could have found it: without a range no commit is judged
344
+ const judged = judge(warned, range === undefined ? [] : held);
345
+ const verdict = { ...judged, fresh: [...judged.fresh, ...gated] };
346
+ const lines = report(verdict, `changes (${phase})`, relative(repo, baselineFile).replaceAll("\\", "/"));
347
+ log(`${lines.join("\n")}\n`);
348
+ if (!passes(verdict))
349
+ failed = true;
350
+ }
351
+ if (has("--strict") && notRun !== undefined)
352
+ for (const c of ruleCases(findings, notRun))
353
+ if (c.outcome === "not_run")
354
+ log(`${c.rule}: not_run: ${c.reason}\n`);
355
+ // the capabilities and their chains, from the commits and the files alone (0020-ifccm FR-035 to FR-038)
356
+ let traced;
357
+ if (offline) {
358
+ const made = await offlineTrace(repo, value, log);
359
+ if (typeof made === "number")
360
+ return made;
361
+ traced = made;
362
+ const text = traceOutput(made.result, format);
363
+ const to = value("--output");
364
+ if (to === undefined)
365
+ out(text);
366
+ else {
367
+ writeTextFileSync(resolve(repo, to), text);
368
+ out(`${to}: the trace of ${made.result.capabilities.length} capabilities is written\n`);
369
+ }
370
+ // a capability that says Closes is whole: each of its requirements is linked to its run (an open capability is in progress)
371
+ if (made.result.capabilities.some((c) => c.closed && c.requirements.some((r) => r.endsAt !== undefined)))
372
+ failed = true;
373
+ }
374
+ // the view of capabilities by rung
375
+ const capabilities = value("--capabilities");
376
+ const document = value("--document");
377
+ if (document !== undefined && (capabilities !== undefined || traced !== undefined)) {
378
+ const docFile = resolve(repo, document);
379
+ let record;
380
+ if (traced !== undefined)
381
+ record = viewOfTrace(traced.result, traced.record);
382
+ else {
383
+ const file = resolve(repo, capabilities ?? "");
384
+ if (!existsSync(file) || !existsSync(docFile)) {
385
+ log(`changes: ${existsSync(file) ? docFile : file} does not exist\n`);
386
+ return 3;
387
+ }
388
+ const view = decodeViewRecord(readTextFileSync(file));
389
+ if (view.kind === "err") {
390
+ log(`changes: ${file}: ${view.error}\n`);
391
+ return 3;
392
+ }
393
+ record = view.value;
394
+ }
395
+ if (!existsSync(docFile)) {
396
+ log(`changes: ${docFile} does not exist\n`);
397
+ return 3;
398
+ }
399
+ const text = viewOf(record.rungs, record.capabilities, record.runs);
400
+ const current = readTextFileSync(docFile).replaceAll("\r\n", "\n");
401
+ if (has("--check")) {
402
+ const same = viewIsCurrent(current, text);
403
+ if (same.kind === "err") {
404
+ log(`changes: ${docFile}: ${formatViewError(same.error)}\n`);
405
+ return 3;
406
+ }
407
+ if (!same.value) {
408
+ log(`${document}: the view of capabilities by rung differs from what is generated; run changes.ts ${traced === undefined ? `--capabilities ${capabilities}` : "--capability-trace"} --document ${document}\n`);
409
+ failed = true;
410
+ }
411
+ }
412
+ else {
413
+ const next = spliceView(current, text);
414
+ if (next.kind === "err") {
415
+ log(`changes: ${docFile}: ${formatViewError(next.error)}\n`);
416
+ return 3;
417
+ }
418
+ if (next.value !== current)
419
+ writeTextFileSync(docFile, next.value);
420
+ out(`${document}: the view of capabilities by rung is written\n`);
421
+ }
422
+ }
423
+ // the chain of a change request's requirements
424
+ const body = value("--trace");
425
+ if (body !== undefined) {
426
+ const file = resolve(repo, body);
427
+ if (!existsSync(file)) {
428
+ log(`changes: ${file} does not exist\n`);
429
+ return 3;
430
+ }
431
+ const wanted = doneWhenRequirements(parseIssueBody(readTextFileSync(file)));
432
+ const specsRoot = value("--specs") !== undefined
433
+ ? resolve(repo, value("--specs") ?? "")
434
+ : existsSync(join(repo, "specs"))
435
+ ? repo
436
+ : join(repo, "commons", "spec-kit");
437
+ const sources = sourcesUnder(repo);
438
+ let cases = [];
439
+ const runs = value("--runs");
440
+ if (runs !== undefined) {
441
+ const rf = resolve(repo, runs);
442
+ if (!existsSync(rf)) {
443
+ log(`changes: ${rf} does not exist\n`);
444
+ return 3;
445
+ }
446
+ const rec = readRecord(readTextFileSync(rf));
447
+ if (rec.kind === "err") {
448
+ log(`changes: ${rf} is not a test record\n`);
449
+ return 3;
450
+ }
451
+ cases = rec.value.tests.map((t) => ({ requirements: t.requirements, outcome: t.outcome }));
452
+ }
453
+ const citations = await termsOf(value("--terms"), repo, log);
454
+ if (typeof citations === "number")
455
+ return citations;
456
+ const traces = wanted.map((r) => traceOf(r, {
457
+ specs: readSpecTexts(specsRoot).map((s) => ({ slug: s.slug, spec: s.spec })),
458
+ terms: citations,
459
+ sources: sources.filter((s) => !s.path.endsWith(".test.ts")),
460
+ tests: sources.filter((s) => s.path.endsWith(".test.ts")),
461
+ cases,
462
+ }));
463
+ out(`${traceLines(traces).join("\n")}${traces.length === 0 ? "the Done when section names no requirement\n" : "\n"}`);
464
+ if (traces.length === 0 || traces.some((t) => firstBreak(t) !== undefined))
465
+ failed = true;
466
+ }
467
+ return failed ? 1 : 0;
468
+ }
469
+ if (import.meta.main)
470
+ process.exitCode = await run(process.argv.slice(2));
@@ -0,0 +1,15 @@
1
+ import { terms } from "@intellectual-frontiers/ontology/mizan";
2
+ import { type RulePlugin } from "@intellectual-frontiers/mizan/rules";
3
+ import { BASELINE_COMMENTS, readSpecTexts } from "@intellectual-frontiers/mizan/spec-files";
4
+ import type { TermRecord } from "@intellectual-frontiers/mizan/standards";
5
+ export { BASELINE_COMMENTS, readSpecTexts };
6
+ /** The records of an audit of terms as the rules read them: each term of a vocabulary and the basis it rests on (0018-standards-first FR-003 to FR-005). */
7
+ export declare function termRecordsOf(audit: readonly (typeof terms)[number][]): readonly TermRecord[];
8
+ /** Mizan's own terms and the packaging ontology's as the rules read them. */
9
+ export declare function mizanTermRecords(): readonly TermRecord[];
10
+ /** The deprecated terms of commons' own ontologies, by CURIE, with what replaces each (0018-standards-first): a specification that names one is found. */
11
+ export declare function deprecatedTerms(): ReadonlyMap<string, string>;
12
+ /** The command line. Returns the exit status: 0, or 1 where a finding is new or a baseline line is stale. */
13
+ export declare function main(argv: readonly string[], plugins?: readonly RulePlugin[], today?: string): number;
14
+ /** The command, with `--all` (0028-conformance-levels FR-012): the check, and then the `verify` of every library a manifest declares, each named with its status. Returns the exit status. */
15
+ export declare function run(argv: readonly string[]): Promise<number>;