@intellectual-frontiers/libraries 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/affected.d.ts +28 -0
- package/dist/affected.js +250 -0
- package/dist/changes.d.ts +27 -0
- package/dist/changes.js +470 -0
- package/dist/check.d.ts +15 -0
- package/dist/check.js +198 -0
- package/dist/generate-ontology.d.ts +37 -0
- package/dist/generate-ontology.js +293 -0
- package/dist/generate-workflows.d.ts +12 -0
- package/dist/generate-workflows.js +102 -0
- package/dist/imports/nist-sp-800-53.import.d.ts +33 -0
- package/dist/imports/nist-sp-800-53.import.js +34 -0
- package/dist/imports/schema-org.import.d.ts +33 -0
- package/dist/imports/schema-org.import.js +31 -0
- package/dist/install-bun.d.ts +1 -0
- package/dist/install-bun.js +58 -0
- package/dist/libraries.d.ts +79 -0
- package/dist/libraries.js +386 -0
- package/dist/mod.d.ts +16 -0
- package/dist/mod.js +16 -0
- package/dist/newer.d.ts +27 -0
- package/dist/newer.js +147 -0
- package/dist/oscal-register.d.ts +65 -0
- package/dist/oscal-register.js +344 -0
- package/dist/pack-library.d.ts +47 -0
- package/dist/pack-library.js +498 -0
- package/dist/pins.d.ts +15 -0
- package/dist/pins.js +29 -0
- package/dist/publish-ontology.d.ts +160 -0
- package/dist/publish-ontology.js +227 -0
- package/dist/versions.d.ts +26 -0
- package/dist/versions.js +556 -0
- package/dist/workflows/definitions.d.ts +65 -0
- package/dist/workflows/definitions.js +619 -0
- package/dist/workflows/mod.d.ts +10 -0
- package/dist/workflows/mod.js +10 -0
- package/dist/workflows/model.d.ts +143 -0
- package/dist/workflows/model.js +81 -0
- package/dist/workflows/render.d.ts +9 -0
- package/dist/workflows/render.js +179 -0
- package/package.json +129 -4
- package/src/affected.ts +265 -0
- package/src/changes.ts +546 -0
- package/src/check.ts +223 -0
- package/src/generate-ontology.ts +350 -0
- package/src/generate-workflows.ts +103 -0
- package/src/imports/nist-sp-800-53.import.ts +36 -0
- package/src/imports/schema-org.import.ts +31 -0
- package/src/install-bun.ts +53 -0
- package/src/libraries.ts +385 -0
- package/src/mod.ts +16 -0
- package/src/newer.ts +154 -0
- package/src/oscal-register.ts +443 -0
- package/src/pack-library.ts +522 -0
- package/src/pins.ts +30 -0
- package/src/publish-ontology.ts +354 -0
- package/src/versions.ts +594 -0
- package/src/workflows/definitions.ts +855 -0
- package/src/workflows/mod.ts +30 -0
- package/src/workflows/model.ts +187 -0
- package/src/workflows/render.ts +176 -0
package/src/changes.ts
ADDED
|
@@ -0,0 +1,546 @@
|
|
|
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 type { GitHostClient, RepoRef } from "@intellectual-frontiers/githost/types";
|
|
29
|
+
import { formatBaseline, judge, parseBaseline, passes, report } from "@intellectual-frontiers/mizan/trace";
|
|
30
|
+
import { readRecord } from "@intellectual-frontiers/quality/test-report";
|
|
31
|
+
import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
32
|
+
import { formatGitError } from "@intellectual-frontiers/system/git";
|
|
33
|
+
import { cwd } from "@intellectual-frontiers/system/proc";
|
|
34
|
+
import { join, relative, resolve } from "@intellectual-frontiers/system/path";
|
|
35
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
36
|
+
import {
|
|
37
|
+
capabilityTrace,
|
|
38
|
+
type CapabilityTraceResult,
|
|
39
|
+
type IssueFact,
|
|
40
|
+
NO_RUNG,
|
|
41
|
+
parseIssues,
|
|
42
|
+
traceOutput,
|
|
43
|
+
type TraceFormat,
|
|
44
|
+
} from "@intellectual-frontiers/mizan/changes/capability-trace";
|
|
45
|
+
import {
|
|
46
|
+
type CapabilityRecord,
|
|
47
|
+
decodeViewRecord,
|
|
48
|
+
formatViewError,
|
|
49
|
+
type RungRecord,
|
|
50
|
+
spliceView,
|
|
51
|
+
viewIsCurrent,
|
|
52
|
+
viewOf,
|
|
53
|
+
type ViewRecord,
|
|
54
|
+
} from "@intellectual-frontiers/mizan/changes/capability-view";
|
|
55
|
+
import {
|
|
56
|
+
dayOf,
|
|
57
|
+
decodeHarnessRecord,
|
|
58
|
+
formatRecordError,
|
|
59
|
+
type HarnessRecord,
|
|
60
|
+
phaseOf,
|
|
61
|
+
relaxations,
|
|
62
|
+
} from "@intellectual-frontiers/mizan/changes/declaration";
|
|
63
|
+
import { declarationHistory, readRange, readRangeFacts } from "@intellectual-frontiers/mizan/changes/git-log";
|
|
64
|
+
import { readTermsFile } from "@intellectual-frontiers/mizan/changes/terms-file";
|
|
65
|
+
import { doneWhenRequirements, parseIssueBody } from "@intellectual-frontiers/mizan/changes/issue-body";
|
|
66
|
+
import {
|
|
67
|
+
CHANGES_RULES,
|
|
68
|
+
type ChangesFinding,
|
|
69
|
+
commitFindings,
|
|
70
|
+
declarationFindings,
|
|
71
|
+
relaxationFindings,
|
|
72
|
+
ruleCases,
|
|
73
|
+
STRICT_RULES,
|
|
74
|
+
strictFindings,
|
|
75
|
+
} from "@intellectual-frontiers/mizan/changes/rules";
|
|
76
|
+
import { askHost, NO_CLIENT } from "@intellectual-frontiers/mizan/changes/strict";
|
|
77
|
+
import { type RunCase, traceLines, traceOf, firstBreak } from "@intellectual-frontiers/mizan/changes/trace";
|
|
78
|
+
import type { OntologyCitation } from "@intellectual-frontiers/mizan/trace";
|
|
79
|
+
import { readSpecTexts } from "@intellectual-frontiers/mizan/spec-files";
|
|
80
|
+
import { packagingTerms } from "@intellectual-frontiers/ontology/audit";
|
|
81
|
+
import * as ifccmOntology from "@intellectual-frontiers/ontology/ifccm";
|
|
82
|
+
import * as ifqsOntology from "@intellectual-frontiers/ontology/ifqs";
|
|
83
|
+
import { terms } from "@intellectual-frontiers/ontology/mizan";
|
|
84
|
+
|
|
85
|
+
/** One rule's result in a run of the check (0020-ifccm FR-031): its findings, or the reason it did not run. Its shape is the quality system's `CheckRule`, so a caller keeps it as a record without this file knowing the quality system. */
|
|
86
|
+
export type RuleResult = {
|
|
87
|
+
readonly id: string;
|
|
88
|
+
readonly findings: readonly { readonly file: string; readonly line?: number; readonly message: string }[];
|
|
89
|
+
readonly notRun?: string;
|
|
90
|
+
};
|
|
91
|
+
|
|
92
|
+
/** The rules that need no range of commits: the declaration's own, and its history. */
|
|
93
|
+
const WITHOUT_RANGE: readonly string[] = ["changes/declaration", "changes/gate-relaxed"];
|
|
94
|
+
|
|
95
|
+
/** What the command is given besides its arguments: the host's client and the repository it serves, which the command never makes, and where it writes. */
|
|
96
|
+
export type Deps = {
|
|
97
|
+
/** Called once with each rule's result where the check judged commits or a declaration (0020-ifccm FR-031), so that the caller can keep it as a record. */
|
|
98
|
+
readonly onRules?: (rules: readonly RuleResult[]) => void;
|
|
99
|
+
readonly client?: GitHostClient;
|
|
100
|
+
/** The repository on the host that the commits belong to; a reference `#N` is asked of it. */
|
|
101
|
+
readonly home?: RepoRef;
|
|
102
|
+
readonly out?: (text: string) => void;
|
|
103
|
+
readonly err?: (text: string) => void;
|
|
104
|
+
};
|
|
105
|
+
|
|
106
|
+
/** The default name of a harness's record, in the repository's top folder. */
|
|
107
|
+
export const RECORD_FILE = "ifccm.declaration.ts";
|
|
108
|
+
|
|
109
|
+
/** The default name of the baseline of the check's findings, in the repository's top folder. */
|
|
110
|
+
export const BASELINE_FILE = "changes.baseline.txt";
|
|
111
|
+
|
|
112
|
+
const COMMENTS = [
|
|
113
|
+
"The findings of the changes check (commons 0020-ifccm FR-011) held while the harness has not declared production.",
|
|
114
|
+
"A new finding fails the check, and so does a line below that no longer occurs: when you fix one, delete its line.",
|
|
115
|
+
"Never add a line to make a check pass. A finding in the gate phase is never held by this file.",
|
|
116
|
+
] as const;
|
|
117
|
+
|
|
118
|
+
type Flags = {
|
|
119
|
+
readonly values: ReadonlyMap<string, string>;
|
|
120
|
+
readonly switches: ReadonlySet<string>;
|
|
121
|
+
};
|
|
122
|
+
|
|
123
|
+
const VALUE_FLAGS = [
|
|
124
|
+
"--repo",
|
|
125
|
+
"--range",
|
|
126
|
+
"--declaration",
|
|
127
|
+
"--today",
|
|
128
|
+
"--baseline",
|
|
129
|
+
"--capabilities",
|
|
130
|
+
"--document",
|
|
131
|
+
"--trace",
|
|
132
|
+
"--runs",
|
|
133
|
+
"--specs",
|
|
134
|
+
"--issues",
|
|
135
|
+
"--terms",
|
|
136
|
+
"--rungs",
|
|
137
|
+
"--format",
|
|
138
|
+
"--output",
|
|
139
|
+
] as const;
|
|
140
|
+
const SWITCH_FLAGS = ["--strict", "--check", "--write-baseline", "--capability-trace"] as const;
|
|
141
|
+
|
|
142
|
+
/** The flags of a command line, or the sentence that says what is wrong with it. */
|
|
143
|
+
function parseFlags(argv: readonly string[]): Flags | string {
|
|
144
|
+
const values = new Map<string, string>();
|
|
145
|
+
const switches = new Set<string>();
|
|
146
|
+
for (let i = 0; i < argv.length; i++) {
|
|
147
|
+
const a = argv[i] ?? "";
|
|
148
|
+
const eq = a.indexOf("=");
|
|
149
|
+
const name = eq > 0 ? a.slice(0, eq) : a;
|
|
150
|
+
if (SWITCH_FLAGS.some((f) => f === name) && eq < 0) switches.add(name);
|
|
151
|
+
else if (VALUE_FLAGS.some((f) => f === name)) {
|
|
152
|
+
const value = eq > 0 ? a.slice(eq + 1) : argv[++i];
|
|
153
|
+
if (value === undefined || value === "") return `${name} needs a value`;
|
|
154
|
+
values.set(name, value);
|
|
155
|
+
} else return `unknown argument ${a}`;
|
|
156
|
+
}
|
|
157
|
+
return { values, switches };
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** Every `.ts` file under a folder (skipping `node_modules`, `.git` and `.claude`), as `{ path (relative, with /), text }`. */
|
|
161
|
+
function sourcesUnder(root: string): readonly { readonly path: string; readonly text: string }[] {
|
|
162
|
+
const out: { readonly path: string; readonly text: string }[] = [];
|
|
163
|
+
const walk = (dir: string): void => {
|
|
164
|
+
for (const e of readDirSync(dir)) {
|
|
165
|
+
if (e.name === "node_modules" || e.name === ".git" || e.name === ".claude") continue;
|
|
166
|
+
const p = join(dir, e.name);
|
|
167
|
+
if (e.isDirectory) walk(p);
|
|
168
|
+
else if (e.name.endsWith(".ts")) out.push({ path: relative(root, p).replaceAll("\\", "/"), text: readTextFileSync(p) });
|
|
169
|
+
}
|
|
170
|
+
};
|
|
171
|
+
walk(root);
|
|
172
|
+
return out;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** 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`). */
|
|
176
|
+
function termCitations(): readonly { readonly term: string; readonly cites: readonly string[]; readonly file: string }[] {
|
|
177
|
+
return [...terms, ...packagingTerms, ...ifccmOntology.terms, ...ifqsOntology.terms].map((t) => ({
|
|
178
|
+
term: t.values.termIri,
|
|
179
|
+
cites: t.values.definedBy ?? [],
|
|
180
|
+
file: "commons/ontology",
|
|
181
|
+
}));
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/** The ontology's citations a command line names: commons' own where `--terms commons` (and, for `--trace`, where none is named), else the file's. */
|
|
185
|
+
async function termsOf(
|
|
186
|
+
named: string | undefined,
|
|
187
|
+
repo: string,
|
|
188
|
+
log: (t: string) => void,
|
|
189
|
+
fallback: "commons" | "none" = "commons",
|
|
190
|
+
): Promise<readonly OntologyCitation[] | number> {
|
|
191
|
+
if (named === undefined) return fallback === "commons" ? termCitations() : [];
|
|
192
|
+
if (named === "commons") return termCitations();
|
|
193
|
+
const r = await readTermsFile(resolve(repo, named));
|
|
194
|
+
if (r.kind === "err") {
|
|
195
|
+
log(`changes: --terms: ${r.error}\n`);
|
|
196
|
+
return 3;
|
|
197
|
+
}
|
|
198
|
+
return r.value;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** 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. */
|
|
202
|
+
function viewOfTrace(t: CapabilityTraceResult, record: ViewRecord): ViewRecord {
|
|
203
|
+
const capabilities: readonly CapabilityRecord[] = t.capabilities.map((c) => ({
|
|
204
|
+
id: c.number,
|
|
205
|
+
title: c.title ?? `#${c.number}`,
|
|
206
|
+
touchesRung: c.rungs.filter((r) => r !== NO_RUNG),
|
|
207
|
+
lastRevision: c.commits[c.commits.length - 1] ?? "",
|
|
208
|
+
}));
|
|
209
|
+
return { rungs: record.rungs, capabilities, runs: record.runs };
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** 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. */
|
|
213
|
+
async function offlineTrace(
|
|
214
|
+
repo: string,
|
|
215
|
+
value: (name: string) => string | undefined,
|
|
216
|
+
log: (t: string) => void,
|
|
217
|
+
): Promise<{ readonly result: CapabilityTraceResult; readonly record: ViewRecord } | number> {
|
|
218
|
+
const read = await readRangeFacts(repo, value("--range") ?? "");
|
|
219
|
+
if (read.kind === "err") {
|
|
220
|
+
log(`changes: ${formatGitError(read.error)}\n`);
|
|
221
|
+
return 3;
|
|
222
|
+
}
|
|
223
|
+
const exists = (name: string): string | undefined => {
|
|
224
|
+
const f = value(name);
|
|
225
|
+
if (f === undefined) return undefined;
|
|
226
|
+
const path = resolve(repo, f);
|
|
227
|
+
if (existsSync(path)) return path;
|
|
228
|
+
log(`changes: ${name} ${path} does not exist\n`);
|
|
229
|
+
return "";
|
|
230
|
+
};
|
|
231
|
+
let issues: readonly IssueFact[] = [];
|
|
232
|
+
const issuesFile = exists("--issues");
|
|
233
|
+
if (issuesFile === "") return 3;
|
|
234
|
+
if (issuesFile !== undefined) {
|
|
235
|
+
const r = parseIssues(readTextFileSync(issuesFile));
|
|
236
|
+
if (r.kind === "err") {
|
|
237
|
+
log(`changes: ${issuesFile}: ${r.error}\n`);
|
|
238
|
+
return 3;
|
|
239
|
+
}
|
|
240
|
+
issues = r.value;
|
|
241
|
+
}
|
|
242
|
+
let record: ViewRecord = { rungs: [], capabilities: [], runs: [] };
|
|
243
|
+
const rungsFile = exists("--rungs") ?? exists("--capabilities");
|
|
244
|
+
if (rungsFile === "") return 3;
|
|
245
|
+
if (rungsFile !== undefined) {
|
|
246
|
+
const r = decodeViewRecord(readTextFileSync(rungsFile), false);
|
|
247
|
+
if (r.kind === "err") {
|
|
248
|
+
log(`changes: ${rungsFile}: ${r.error}\n`);
|
|
249
|
+
return 3;
|
|
250
|
+
}
|
|
251
|
+
record = r.value;
|
|
252
|
+
}
|
|
253
|
+
let cases: readonly RunCase[] = [];
|
|
254
|
+
const runsFile = exists("--runs");
|
|
255
|
+
if (runsFile === "") return 3;
|
|
256
|
+
if (runsFile !== undefined) {
|
|
257
|
+
const rec = readRecord(readTextFileSync(runsFile));
|
|
258
|
+
if (rec.kind === "err") {
|
|
259
|
+
log(`changes: ${runsFile} is not a test record\n`);
|
|
260
|
+
return 3;
|
|
261
|
+
}
|
|
262
|
+
cases = rec.value.tests.map((t) => ({ requirements: t.requirements, outcome: t.outcome }));
|
|
263
|
+
}
|
|
264
|
+
const terms = await termsOf(value("--terms"), repo, log, "none");
|
|
265
|
+
if (typeof terms === "number") return terms;
|
|
266
|
+
const specsRoot =
|
|
267
|
+
value("--specs") !== undefined
|
|
268
|
+
? resolve(repo, value("--specs") ?? "")
|
|
269
|
+
: existsSync(join(repo, "specs"))
|
|
270
|
+
? repo
|
|
271
|
+
: join(repo, "commons", "spec-kit");
|
|
272
|
+
const files = sourcesUnder(repo);
|
|
273
|
+
const rungs: readonly RungRecord[] = record.rungs;
|
|
274
|
+
const result = capabilityTrace({
|
|
275
|
+
commits: read.value,
|
|
276
|
+
issues,
|
|
277
|
+
specs: readSpecTexts(specsRoot).map((s) => ({ slug: s.slug, spec: s.spec })),
|
|
278
|
+
terms,
|
|
279
|
+
sources: files.filter((f) => !f.path.endsWith(".test.ts")),
|
|
280
|
+
tests: files.filter((f) => f.path.endsWith(".test.ts")),
|
|
281
|
+
cases,
|
|
282
|
+
rungs: rungs.map((r) => ({ id: r.id, label: r.label, homes: r.homes ?? [] })),
|
|
283
|
+
specPath: (slug) => relative(repo, join(specsRoot, "specs", slug, "spec.md")).replaceAll("\\", "/"),
|
|
284
|
+
});
|
|
285
|
+
return { result, record };
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/** Run the command; the exit status (0 clean, 1 findings, 2 usage, 3 environment). */
|
|
289
|
+
export async function run(
|
|
290
|
+
argv: readonly string[],
|
|
291
|
+
deps: Deps = {},
|
|
292
|
+
now: () => string = () => new Date().toISOString().slice(0, 10),
|
|
293
|
+
): Promise<number> {
|
|
294
|
+
const out = deps.out ?? ((t: string): void => void stdio.stdout.writeSync(t));
|
|
295
|
+
const log = deps.err ?? ((t: string): void => void stdio.stderr.writeSync(t));
|
|
296
|
+
const flags = parseFlags(argv);
|
|
297
|
+
if (typeof flags === "string") {
|
|
298
|
+
log(
|
|
299
|
+
`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`,
|
|
300
|
+
);
|
|
301
|
+
return 2;
|
|
302
|
+
}
|
|
303
|
+
const value = (name: string): string | undefined => flags.values.get(name);
|
|
304
|
+
const has = (name: string): boolean => flags.switches.has(name);
|
|
305
|
+
const repo = resolve(value("--repo") ?? cwd());
|
|
306
|
+
const today = value("--today") ?? now();
|
|
307
|
+
if (dayOf(today) === undefined) {
|
|
308
|
+
log(`changes: --today ${today} is not a day (YYYY-MM-DD)\n`);
|
|
309
|
+
return 2;
|
|
310
|
+
}
|
|
311
|
+
if (has("--strict") && value("--range") === undefined) {
|
|
312
|
+
log("changes: --strict asks the host about the commits of a range: give --range\n");
|
|
313
|
+
return 2;
|
|
314
|
+
}
|
|
315
|
+
const offline = has("--capability-trace");
|
|
316
|
+
if (offline && value("--range") === undefined) {
|
|
317
|
+
log("changes: --capability-trace reads the commits of a range: give --range\n");
|
|
318
|
+
return 2;
|
|
319
|
+
}
|
|
320
|
+
if (has("--check") && ((value("--capabilities") === undefined && !offline) || value("--document") === undefined)) {
|
|
321
|
+
log("changes: --check needs --capabilities FILE and --document FILE (or --capability-trace and --document FILE)\n");
|
|
322
|
+
return 2;
|
|
323
|
+
}
|
|
324
|
+
const asked = value("--format") ?? "text";
|
|
325
|
+
if (asked !== "text" && asked !== "json") {
|
|
326
|
+
log(`changes: --format ${asked} is not text or json\n`);
|
|
327
|
+
return 2;
|
|
328
|
+
}
|
|
329
|
+
const format: TraceFormat = asked;
|
|
330
|
+
|
|
331
|
+
// the harness's record
|
|
332
|
+
const recordPath = value("--declaration") !== undefined ? resolve(repo, value("--declaration") ?? "") : join(repo, RECORD_FILE);
|
|
333
|
+
let record: HarnessRecord = { declaration: undefined, decisions: [], roles: {} };
|
|
334
|
+
if (existsSync(recordPath)) {
|
|
335
|
+
const r = decodeHarnessRecord(readTextFileSync(recordPath));
|
|
336
|
+
if (r.kind === "err") {
|
|
337
|
+
log(`changes: ${recordPath}: ${formatRecordError(r.error)}\n`);
|
|
338
|
+
return 3;
|
|
339
|
+
}
|
|
340
|
+
record = r.value;
|
|
341
|
+
} else if (value("--declaration") !== undefined) {
|
|
342
|
+
log(`changes: ${recordPath} does not exist\n`);
|
|
343
|
+
return 3;
|
|
344
|
+
}
|
|
345
|
+
const phase = phaseOf(record.declaration, today);
|
|
346
|
+
const recordName = relative(repo, recordPath).replaceAll("\\", "/");
|
|
347
|
+
const findings: ChangesFinding[] = [...declarationFindings(record.declaration, recordName)];
|
|
348
|
+
let notRun: string | undefined;
|
|
349
|
+
let failed = false;
|
|
350
|
+
|
|
351
|
+
// the declaration's history: a day moved later or a domain dropped
|
|
352
|
+
if (existsSync(recordPath) && existsSync(join(repo, ".git"))) {
|
|
353
|
+
const history = await declarationHistory(repo, recordName);
|
|
354
|
+
if (history.kind === "err") {
|
|
355
|
+
log(`changes: ${formatGitError(history.error)}\n`);
|
|
356
|
+
return 3;
|
|
357
|
+
}
|
|
358
|
+
findings.push(...relaxationFindings(relaxations(history.value), record.decisions, phase, recordName));
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
// the commits of a range
|
|
362
|
+
const range = value("--range");
|
|
363
|
+
if (range !== undefined) {
|
|
364
|
+
const read = await readRange(repo, range);
|
|
365
|
+
if (read.kind === "err") {
|
|
366
|
+
log(`changes: ${formatGitError(read.error)}\n`);
|
|
367
|
+
return 3;
|
|
368
|
+
}
|
|
369
|
+
const commits = read.value;
|
|
370
|
+
findings.push(
|
|
371
|
+
...commitFindings(commits, {
|
|
372
|
+
phase,
|
|
373
|
+
...(record.declaration === undefined ? {} : { declaration: record.declaration }),
|
|
374
|
+
decisions: record.decisions,
|
|
375
|
+
roles: record.roles,
|
|
376
|
+
}),
|
|
377
|
+
);
|
|
378
|
+
if (has("--strict")) {
|
|
379
|
+
const home = deps.home;
|
|
380
|
+
const asked =
|
|
381
|
+
home === undefined && deps.client !== undefined
|
|
382
|
+
? { answers: new Map(), notRun: "the repository's reference on the host was not given" }
|
|
383
|
+
: home === undefined
|
|
384
|
+
? { answers: new Map(), notRun: NO_CLIENT }
|
|
385
|
+
: await askHost(deps.client, home, commits);
|
|
386
|
+
notRun = asked.notRun;
|
|
387
|
+
findings.push(...strictFindings(commits, asked.answers, phase));
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
// each rule's result, for the record of the run (FR-031): a rule that was not run is never a pass
|
|
392
|
+
if (deps.onRules !== undefined) {
|
|
393
|
+
const strict = has("--strict");
|
|
394
|
+
deps.onRules(
|
|
395
|
+
CHANGES_RULES.map((rule): RuleResult => {
|
|
396
|
+
const why =
|
|
397
|
+
range === undefined && !WITHOUT_RANGE.includes(rule)
|
|
398
|
+
? "no --range was given, so no commit was judged"
|
|
399
|
+
: STRICT_RULES.includes(rule)
|
|
400
|
+
? !strict
|
|
401
|
+
? "--strict was not given, so the host was not asked"
|
|
402
|
+
: notRun
|
|
403
|
+
: undefined;
|
|
404
|
+
if (why !== undefined) return { id: rule, findings: [], notRun: why };
|
|
405
|
+
return {
|
|
406
|
+
id: rule,
|
|
407
|
+
findings: findings.filter((f) => f.rule === rule).map((f) => ({ file: f.file, line: f.line, message: f.message })),
|
|
408
|
+
};
|
|
409
|
+
}),
|
|
410
|
+
);
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
// judgement against the baseline: a warning is held by it, a finding in the gate phase never is
|
|
414
|
+
const baselineFile = value("--baseline") !== undefined ? resolve(repo, value("--baseline") ?? "") : join(repo, BASELINE_FILE);
|
|
415
|
+
const warned = findings.filter((f) => f.severity === "warn");
|
|
416
|
+
const gated = findings.filter((f) => f.severity === "gate");
|
|
417
|
+
if (has("--write-baseline")) {
|
|
418
|
+
writeTextFileSync(baselineFile, formatBaseline(warned, COMMENTS));
|
|
419
|
+
out(`wrote ${baselineFile}: ${new Set(warned.map((f) => f.key)).size} findings\n`);
|
|
420
|
+
} else if (range !== undefined || findings.length > 0) {
|
|
421
|
+
const held = existsSync(baselineFile) ? parseBaseline(readTextFileSync(baselineFile)) : [];
|
|
422
|
+
// a baseline line is stale only where this run could have found it: without a range no commit is judged
|
|
423
|
+
const judged = judge(warned, range === undefined ? [] : held);
|
|
424
|
+
const verdict = { ...judged, fresh: [...judged.fresh, ...gated] };
|
|
425
|
+
const lines = report(verdict, `changes (${phase})`, relative(repo, baselineFile).replaceAll("\\", "/"));
|
|
426
|
+
log(`${lines.join("\n")}\n`);
|
|
427
|
+
if (!passes(verdict)) failed = true;
|
|
428
|
+
}
|
|
429
|
+
if (has("--strict") && notRun !== undefined)
|
|
430
|
+
for (const c of ruleCases(findings, notRun)) if (c.outcome === "not_run") log(`${c.rule}: not_run: ${c.reason}\n`);
|
|
431
|
+
|
|
432
|
+
// the capabilities and their chains, from the commits and the files alone (0020-ifccm FR-035 to FR-038)
|
|
433
|
+
let traced: { readonly result: CapabilityTraceResult; readonly record: ViewRecord } | undefined;
|
|
434
|
+
if (offline) {
|
|
435
|
+
const made = await offlineTrace(repo, value, log);
|
|
436
|
+
if (typeof made === "number") return made;
|
|
437
|
+
traced = made;
|
|
438
|
+
const text = traceOutput(made.result, format);
|
|
439
|
+
const to = value("--output");
|
|
440
|
+
if (to === undefined) out(text);
|
|
441
|
+
else {
|
|
442
|
+
writeTextFileSync(resolve(repo, to), text);
|
|
443
|
+
out(`${to}: the trace of ${made.result.capabilities.length} capabilities is written\n`);
|
|
444
|
+
}
|
|
445
|
+
// a capability that says Closes is whole: each of its requirements is linked to its run (an open capability is in progress)
|
|
446
|
+
if (made.result.capabilities.some((c) => c.closed && c.requirements.some((r) => r.endsAt !== undefined))) failed = true;
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
// the view of capabilities by rung
|
|
450
|
+
const capabilities = value("--capabilities");
|
|
451
|
+
const document = value("--document");
|
|
452
|
+
if (document !== undefined && (capabilities !== undefined || traced !== undefined)) {
|
|
453
|
+
const docFile = resolve(repo, document);
|
|
454
|
+
let record: ViewRecord;
|
|
455
|
+
if (traced !== undefined) record = viewOfTrace(traced.result, traced.record);
|
|
456
|
+
else {
|
|
457
|
+
const file = resolve(repo, capabilities ?? "");
|
|
458
|
+
if (!existsSync(file) || !existsSync(docFile)) {
|
|
459
|
+
log(`changes: ${existsSync(file) ? docFile : file} does not exist\n`);
|
|
460
|
+
return 3;
|
|
461
|
+
}
|
|
462
|
+
const view = decodeViewRecord(readTextFileSync(file));
|
|
463
|
+
if (view.kind === "err") {
|
|
464
|
+
log(`changes: ${file}: ${view.error}\n`);
|
|
465
|
+
return 3;
|
|
466
|
+
}
|
|
467
|
+
record = view.value;
|
|
468
|
+
}
|
|
469
|
+
if (!existsSync(docFile)) {
|
|
470
|
+
log(`changes: ${docFile} does not exist\n`);
|
|
471
|
+
return 3;
|
|
472
|
+
}
|
|
473
|
+
const text = viewOf(record.rungs, record.capabilities, record.runs);
|
|
474
|
+
const current = readTextFileSync(docFile).replaceAll("\r\n", "\n");
|
|
475
|
+
if (has("--check")) {
|
|
476
|
+
const same = viewIsCurrent(current, text);
|
|
477
|
+
if (same.kind === "err") {
|
|
478
|
+
log(`changes: ${docFile}: ${formatViewError(same.error)}\n`);
|
|
479
|
+
return 3;
|
|
480
|
+
}
|
|
481
|
+
if (!same.value) {
|
|
482
|
+
log(
|
|
483
|
+
`${document}: the view of capabilities by rung differs from what is generated; run changes.ts ${traced === undefined ? `--capabilities ${capabilities}` : "--capability-trace"} --document ${document}\n`,
|
|
484
|
+
);
|
|
485
|
+
failed = true;
|
|
486
|
+
}
|
|
487
|
+
} else {
|
|
488
|
+
const next = spliceView(current, text);
|
|
489
|
+
if (next.kind === "err") {
|
|
490
|
+
log(`changes: ${docFile}: ${formatViewError(next.error)}\n`);
|
|
491
|
+
return 3;
|
|
492
|
+
}
|
|
493
|
+
if (next.value !== current) writeTextFileSync(docFile, next.value);
|
|
494
|
+
out(`${document}: the view of capabilities by rung is written\n`);
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
// the chain of a change request's requirements
|
|
499
|
+
const body = value("--trace");
|
|
500
|
+
if (body !== undefined) {
|
|
501
|
+
const file = resolve(repo, body);
|
|
502
|
+
if (!existsSync(file)) {
|
|
503
|
+
log(`changes: ${file} does not exist\n`);
|
|
504
|
+
return 3;
|
|
505
|
+
}
|
|
506
|
+
const wanted = doneWhenRequirements(parseIssueBody(readTextFileSync(file)));
|
|
507
|
+
const specsRoot =
|
|
508
|
+
value("--specs") !== undefined
|
|
509
|
+
? resolve(repo, value("--specs") ?? "")
|
|
510
|
+
: existsSync(join(repo, "specs"))
|
|
511
|
+
? repo
|
|
512
|
+
: join(repo, "commons", "spec-kit");
|
|
513
|
+
const sources = sourcesUnder(repo);
|
|
514
|
+
let cases: readonly RunCase[] = [];
|
|
515
|
+
const runs = value("--runs");
|
|
516
|
+
if (runs !== undefined) {
|
|
517
|
+
const rf = resolve(repo, runs);
|
|
518
|
+
if (!existsSync(rf)) {
|
|
519
|
+
log(`changes: ${rf} does not exist\n`);
|
|
520
|
+
return 3;
|
|
521
|
+
}
|
|
522
|
+
const rec = readRecord(readTextFileSync(rf));
|
|
523
|
+
if (rec.kind === "err") {
|
|
524
|
+
log(`changes: ${rf} is not a test record\n`);
|
|
525
|
+
return 3;
|
|
526
|
+
}
|
|
527
|
+
cases = rec.value.tests.map((t) => ({ requirements: t.requirements, outcome: t.outcome }));
|
|
528
|
+
}
|
|
529
|
+
const citations = await termsOf(value("--terms"), repo, log);
|
|
530
|
+
if (typeof citations === "number") return citations;
|
|
531
|
+
const traces = wanted.map((r) =>
|
|
532
|
+
traceOf(r, {
|
|
533
|
+
specs: readSpecTexts(specsRoot).map((s) => ({ slug: s.slug, spec: s.spec })),
|
|
534
|
+
terms: citations,
|
|
535
|
+
sources: sources.filter((s) => !s.path.endsWith(".test.ts")),
|
|
536
|
+
tests: sources.filter((s) => s.path.endsWith(".test.ts")),
|
|
537
|
+
cases,
|
|
538
|
+
}),
|
|
539
|
+
);
|
|
540
|
+
out(`${traceLines(traces).join("\n")}${traces.length === 0 ? "the Done when section names no requirement\n" : "\n"}`);
|
|
541
|
+
if (traces.length === 0 || traces.some((t) => firstBreak(t) !== undefined)) failed = true;
|
|
542
|
+
}
|
|
543
|
+
return failed ? 1 : 0;
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
if (import.meta.main) process.exitCode = await run(process.argv.slice(2));
|