@intellectual-frontiers/libraries 0.0.0-stage → 0.1.0
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 +614 -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 +847 -0
- package/src/workflows/mod.ts +30 -0
- package/src/workflows/model.ts +187 -0
- package/src/workflows/render.ts +176 -0
package/src/versions.ts
ADDED
|
@@ -0,0 +1,594 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `versions`, how works are versioned (commons 0026-works-versioning): `check` finds a work whose files changed since the base and whose version did not grow by its scheme, `bump` writes the next
|
|
3
|
+
* version into a work's record, `tag` creates the annotated (and, where Git is set to sign, signed) tag `<slug>-v<version>`, `notes` prints the release notes from the capabilities closed since the
|
|
4
|
+
* last tag, `cite` writes `CITATION.cff` from the record, and `ledger` derives the ledger of releases from the tags.
|
|
5
|
+
*
|
|
6
|
+
* bun commons/libraries/src/versions.ts check [--base REV] judge every work against the merge base with REV (origin/main by default)
|
|
7
|
+
* bun commons/libraries/src/versions.ts bump WORK --impact major|minor|patch|auto write the next version into WORK's record (auto: the greatest `Impact:` of the commits since its last tag)
|
|
8
|
+
* bun commons/libraries/src/versions.ts tag WORK [--tier TIER] [--declaration FILE] create the annotated tag at HEAD, signed where Git signs; a regulated harness releases only on its declared tier
|
|
9
|
+
* bun commons/libraries/src/versions.ts notes WORK [--from TAG] release notes (Markdown) from the `Closes #N` lines of the commits since the last tag
|
|
10
|
+
* bun commons/libraries/src/versions.ts cite WORK [--check] write CITATION.cff (--check: exit 1 where the file is not what the record makes)
|
|
11
|
+
* bun commons/libraries/src/versions.ts ledger [WORK] [--json] [--against FILE] the releases, from the tags; --against finds a tag that moved or is gone since an earlier --json
|
|
12
|
+
* other flags: --repo DIR (the repository, the working folder by default)
|
|
13
|
+
*
|
|
14
|
+
* A work is named by its slug or by its folder. Exit status: 0 where it did what was asked and found nothing, 1 where it found something (or `cite --check` finds the file different, or a release
|
|
15
|
+
* is refused), 2 for a usage error (an unknown command, option or work, a work of no version, no commit that states an impact), 3 where the environment cannot do it. A run that could not run says
|
|
16
|
+
* `not_run` with its reason (Git absent, no repository, a base that cannot be found) and writes no record (FR-031). It reads only Git: a repository on plain Git, with no host, is enough.
|
|
17
|
+
*
|
|
18
|
+
* Spec: 0001-libraries FR-008
|
|
19
|
+
*
|
|
20
|
+
* @module
|
|
21
|
+
*/
|
|
22
|
+
import process from "node:process";
|
|
23
|
+
import { absurd, err, ok } from "@intellectual-frontiers/core";
|
|
24
|
+
import {
|
|
25
|
+
flag,
|
|
26
|
+
formatUsageError,
|
|
27
|
+
helpText,
|
|
28
|
+
type Operand,
|
|
29
|
+
parseArgs,
|
|
30
|
+
type Parser,
|
|
31
|
+
suggest,
|
|
32
|
+
value,
|
|
33
|
+
} from "@intellectual-frontiers/terminal/args";
|
|
34
|
+
import { existsSync, readTextFileSync, sha256File, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
35
|
+
import { formatGitError } from "@intellectual-frontiers/system/git";
|
|
36
|
+
import { join, resolve } from "@intellectual-frontiers/system/path";
|
|
37
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
38
|
+
import { dayOf, decodeHarnessRecord, type Declaration, formatRecordError } from "@intellectual-frontiers/mizan/changes/declaration";
|
|
39
|
+
import { citationOf } from "@intellectual-frontiers/mizan/versions/cite";
|
|
40
|
+
import { releaseGate } from "@intellectual-frontiers/mizan/versions/gate";
|
|
41
|
+
import {
|
|
42
|
+
commitsSince,
|
|
43
|
+
commitSeconds,
|
|
44
|
+
createTag,
|
|
45
|
+
editionFacts,
|
|
46
|
+
findBase,
|
|
47
|
+
changedBetween,
|
|
48
|
+
isAncestor,
|
|
49
|
+
isDirty,
|
|
50
|
+
isRepository,
|
|
51
|
+
readTags,
|
|
52
|
+
readTree,
|
|
53
|
+
readWorkingTree,
|
|
54
|
+
resolveCommit,
|
|
55
|
+
signingConfigured,
|
|
56
|
+
tagAncestry,
|
|
57
|
+
tagsMerged,
|
|
58
|
+
text as gitText,
|
|
59
|
+
} from "@intellectual-frontiers/mizan/versions/git";
|
|
60
|
+
import {
|
|
61
|
+
editionsNeeded,
|
|
62
|
+
judgeWorks,
|
|
63
|
+
recordFindings,
|
|
64
|
+
type ReadRecord,
|
|
65
|
+
type TreeFacts,
|
|
66
|
+
versionProblems,
|
|
67
|
+
} from "@intellectual-frontiers/mizan/versions/judge";
|
|
68
|
+
import {
|
|
69
|
+
type EarlierEntry,
|
|
70
|
+
lastRelease,
|
|
71
|
+
ledgerJson,
|
|
72
|
+
ledgerText,
|
|
73
|
+
readEarlier,
|
|
74
|
+
readLedger,
|
|
75
|
+
tagNameOf,
|
|
76
|
+
} from "@intellectual-frontiers/mizan/versions/ledger";
|
|
77
|
+
import { impactOfCommits, notesOf } from "@intellectual-frontiers/mizan/versions/notes";
|
|
78
|
+
import { type Release, releaseSource, CITATION_FILE } from "@intellectual-frontiers/mizan/versions/record";
|
|
79
|
+
import { formatFinding, sortFindings, type VersionsFinding } from "@intellectual-frontiers/mizan/versions/rules";
|
|
80
|
+
import {
|
|
81
|
+
type Impact,
|
|
82
|
+
IMPACTS,
|
|
83
|
+
compareVersions,
|
|
84
|
+
editionAt,
|
|
85
|
+
nextSemVer,
|
|
86
|
+
parseVersion,
|
|
87
|
+
schemeOf,
|
|
88
|
+
utcDay,
|
|
89
|
+
} from "@intellectual-frontiers/mizan/versions/scheme";
|
|
90
|
+
import { isReleaseTier } from "@intellectual-frontiers/mizan/versions/gate";
|
|
91
|
+
import { recordPathOf, scopeOf, workFolders } from "@intellectual-frontiers/mizan/versions/works";
|
|
92
|
+
|
|
93
|
+
/** What the command is given besides its arguments: where it writes and the clock (the one place the tool reads it, for the day a snapshot or an approval is made). */
|
|
94
|
+
export type Deps = {
|
|
95
|
+
readonly out?: (text: string) => void;
|
|
96
|
+
readonly err?: (text: string) => void;
|
|
97
|
+
readonly now?: () => Date;
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
/** The commands, in the order the help lists them. */
|
|
101
|
+
export const COMMANDS = ["check", "bump", "tag", "notes", "cite", "ledger"] as const;
|
|
102
|
+
|
|
103
|
+
type Say = { readonly out: (t: string) => void; readonly err: (t: string) => void };
|
|
104
|
+
|
|
105
|
+
const REPO = value({ help: "The repository (the working folder where not given).", valueName: "DIR", default: "." });
|
|
106
|
+
const dayParser: Parser<string> = (t) => (dayOf(t) === undefined ? err("a day is YYYY-MM-DD") : ok(t));
|
|
107
|
+
const impactParser: Parser<Impact | "auto"> = (t) => {
|
|
108
|
+
const i = IMPACTS.find((x) => x === t);
|
|
109
|
+
return i !== undefined ? ok(i) : t === "auto" ? ok("auto") : err("major, minor, patch or auto");
|
|
110
|
+
};
|
|
111
|
+
const tierParser: Parser<string> = (t) => (isReleaseTier(t) ? ok(t) : err("Tier0, Tier1 or Tier2"));
|
|
112
|
+
const WORK: readonly Operand[] = [{ name: "WORK", help: "The work, by its slug or its folder.", arity: "one" }];
|
|
113
|
+
|
|
114
|
+
const CHECK = {
|
|
115
|
+
repo: REPO,
|
|
116
|
+
base: value({
|
|
117
|
+
help: "The revision to compare with (the merge base with it is the base): origin/main where not given.",
|
|
118
|
+
valueName: "REV",
|
|
119
|
+
}),
|
|
120
|
+
};
|
|
121
|
+
const BUMP = {
|
|
122
|
+
repo: REPO,
|
|
123
|
+
impact: value({
|
|
124
|
+
help: "The impact of the change: major, minor, patch, or auto (the greatest `Impact:` of the commits since the last tag).",
|
|
125
|
+
valueName: "IMPACT",
|
|
126
|
+
parse: impactParser,
|
|
127
|
+
}),
|
|
128
|
+
snapshot: value({ help: "For data: the file whose SHA-256 is the snapshot's digest.", valueName: "FILE" }),
|
|
129
|
+
day: value({ help: "For data and an approval: the day (the clock where not given).", valueName: "DAY", parse: dayParser }),
|
|
130
|
+
approvedBy: value({ help: "For a controlled document: the person who approves the new revision.", valueName: "NAME" }),
|
|
131
|
+
role: value({ help: "For a controlled document: the role of the approver.", valueName: "ROLE" }),
|
|
132
|
+
decision: value({ help: "For a controlled document: the identifier of the Decision.", valueName: "ID" }),
|
|
133
|
+
};
|
|
134
|
+
const TAG = {
|
|
135
|
+
repo: REPO,
|
|
136
|
+
tier: value({
|
|
137
|
+
help: "The evidence tier judged by `quality tier` (Tier0, Tier1 or Tier2); a regulated harness releases only on the tier it declares.",
|
|
138
|
+
valueName: "TIER",
|
|
139
|
+
parse: tierParser,
|
|
140
|
+
}),
|
|
141
|
+
declaration: value({ help: "The harness's record (ifccm.declaration.ts of the repository where not given).", valueName: "FILE" }),
|
|
142
|
+
};
|
|
143
|
+
const NOTES = { repo: REPO, from: value({ help: "The tag to start after (the work's last tag where not given).", valueName: "TAG" }) };
|
|
144
|
+
const CITE = { repo: REPO, check: flag({ help: "Write nothing: exit 1 where CITATION.cff is not what the record makes." }) };
|
|
145
|
+
const LEDGER = {
|
|
146
|
+
repo: REPO,
|
|
147
|
+
json: flag({ help: "Print a deterministic JSON document." }),
|
|
148
|
+
against: value({ help: "An earlier `ledger --json` output: a tag of it that moved or is gone is a finding.", valueName: "FILE" }),
|
|
149
|
+
};
|
|
150
|
+
|
|
151
|
+
const HELP_SUMMARY: Readonly<Record<(typeof COMMANDS)[number], string>> = {
|
|
152
|
+
check: "Find a work whose files changed and whose version did not grow.",
|
|
153
|
+
bump: "Write the next version into a work's record.",
|
|
154
|
+
tag: "Create the annotated tag of a work's version.",
|
|
155
|
+
notes: "Print the release notes from the capabilities closed since the last tag.",
|
|
156
|
+
cite: "Write CITATION.cff from a work's record.",
|
|
157
|
+
ledger: "Print the releases derived from the tags.",
|
|
158
|
+
};
|
|
159
|
+
|
|
160
|
+
/** One sentence of why a run did not run, in the form every command says it. */
|
|
161
|
+
function notRun(s: Say, reason: string): number {
|
|
162
|
+
s.err(`versions: not_run: ${reason}\n`);
|
|
163
|
+
return 3;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
function usage(s: Say, message: string): number {
|
|
167
|
+
s.err(`versions: ${message}\nusage: versions.ts ${COMMANDS.join("|")} [options] (--help for a command)\n`);
|
|
168
|
+
return 2;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
type Loaded = {
|
|
172
|
+
readonly repo: string;
|
|
173
|
+
readonly tree: TreeFacts;
|
|
174
|
+
readonly works: readonly ReadRecord[];
|
|
175
|
+
readonly invalid: readonly VersionsFinding[];
|
|
176
|
+
};
|
|
177
|
+
|
|
178
|
+
/** The repository and its records as they are now, or the code and the reason a run could not run. */
|
|
179
|
+
async function load(repo: string, s: Say): Promise<Loaded | number> {
|
|
180
|
+
const inside = await isRepository(repo);
|
|
181
|
+
if (inside.kind === "err") return notRun(s, formatGitError(inside.error));
|
|
182
|
+
if (!inside.value) return notRun(s, `${repo} is not a Git repository`);
|
|
183
|
+
const tree = await readWorkingTree(repo);
|
|
184
|
+
if (tree.kind === "err") return notRun(s, formatGitError(tree.error));
|
|
185
|
+
const works: ReadRecord[] = [];
|
|
186
|
+
const invalid: VersionsFinding[] = [];
|
|
187
|
+
for (const folder of workFolders(tree.value.paths)) {
|
|
188
|
+
const r = recordFindings(folder, tree.value.records.get(folder));
|
|
189
|
+
if (r.record === undefined) invalid.push(...r.found);
|
|
190
|
+
else works.push(r.record);
|
|
191
|
+
}
|
|
192
|
+
return { repo, tree: tree.value, works, invalid };
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/** The work a name means: by slug, or by its folder (`.` for the root); or the code to exit with and what to say. */
|
|
196
|
+
function select(l: Loaded, name: string, s: Say): ReadRecord | number {
|
|
197
|
+
const found = l.works.find((w) => w.release.slug === name) ?? l.works.find((w) => w.folder === name || (name === "." && w.folder === ""));
|
|
198
|
+
if (found !== undefined) return found;
|
|
199
|
+
const bad = l.invalid.find((f) => f.file === recordPathOf(name === "." ? "" : name));
|
|
200
|
+
if (bad !== undefined) {
|
|
201
|
+
s.err(`${formatFinding(bad)}\n`);
|
|
202
|
+
return 1;
|
|
203
|
+
}
|
|
204
|
+
return usage(
|
|
205
|
+
s,
|
|
206
|
+
`no work ${JSON.stringify(name)}: the works are ${l.works.map((w) => w.release.slug).join(", ") || "none (no release.ts is tracked)"}`,
|
|
207
|
+
);
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** What `checkVersions` found, or why it could not run (`not_run`, FR-031): the findings, the number of works judged and what they were judged against. */
|
|
211
|
+
export type VersionsCheck =
|
|
212
|
+
| { readonly kind: "judged"; readonly findings: readonly VersionsFinding[]; readonly works: number; readonly from: string }
|
|
213
|
+
| { readonly kind: "not_run"; readonly reason: string };
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* The version check as data (0026-works-versioning FR-022, FR-040): every work of the repository at `repo` judged against the merge base with `rev` (`origin/main` where not given). It reads only
|
|
217
|
+
* Git, so it runs offline: no host, no network, a base that is any revision the repository holds (a branch, a tag or a commit). A consumer calls this, or `run(["check", "--base", rev, "--repo", repo])`.
|
|
218
|
+
*/
|
|
219
|
+
export async function checkVersions(repo: string, rev = "origin/main"): Promise<VersionsCheck> {
|
|
220
|
+
const notRunBecause = (reason: string): VersionsCheck => ({ kind: "not_run", reason });
|
|
221
|
+
const inside = await isRepository(repo);
|
|
222
|
+
if (inside.kind === "err") return notRunBecause(formatGitError(inside.error));
|
|
223
|
+
if (!inside.value) return notRunBecause(`${repo} is not a Git repository`);
|
|
224
|
+
const base = await findBase(repo, rev);
|
|
225
|
+
if (base.kind === "err") return notRunBecause(base.error.kind === "git" ? formatGitError(base.error.error) : base.error.reason);
|
|
226
|
+
const head = await readTree(repo, "HEAD");
|
|
227
|
+
if (head.kind === "err") return notRunBecause(formatGitError(head.error));
|
|
228
|
+
const headCommit = await resolveCommit(repo, "HEAD");
|
|
229
|
+
if (headCommit.kind === "err") return notRunBecause(formatGitError(headCommit.error));
|
|
230
|
+
const baseTree =
|
|
231
|
+
base.value.kind === "commit" ? await readTree(repo, base.value.commit) : ok<TreeFacts>({ paths: [], records: new Map() });
|
|
232
|
+
if (baseTree.kind === "err") return notRunBecause(formatGitError(baseTree.error));
|
|
233
|
+
const changed =
|
|
234
|
+
base.value.kind === "commit" ? await changedBetween(repo, base.value.commit, headCommit.value) : ok<readonly string[]>([]);
|
|
235
|
+
if (changed.kind === "err") return notRunBecause(formatGitError(changed.error));
|
|
236
|
+
const editions = await editionFacts(repo, editionsNeeded(head.value, baseTree.value), headCommit.value);
|
|
237
|
+
if (editions.kind === "err") return notRunBecause(formatGitError(editions.error));
|
|
238
|
+
return {
|
|
239
|
+
kind: "judged",
|
|
240
|
+
findings: sortFindings(judgeWorks({ head: head.value, base: baseTree.value, changed: changed.value, editions: editions.value })),
|
|
241
|
+
works: workFolders(head.value.paths).length,
|
|
242
|
+
from: base.value.kind === "commit" ? `the base ${base.value.commit.slice(0, 12)}` : "no base (the first commit)",
|
|
243
|
+
};
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
async function runCheck(rest: readonly string[], s: Say): Promise<number> {
|
|
247
|
+
const p = parseArgs(rest, CHECK);
|
|
248
|
+
if (p.kind === "err") return usage(s, formatUsageError(p.error, "versions check"));
|
|
249
|
+
if (p.value.kind === "help") return help(s, "check", helpText("versions check", HELP_SUMMARY.check, CHECK));
|
|
250
|
+
const repo = resolve(p.value.options.repo);
|
|
251
|
+
const judged = await checkVersions(repo, p.value.options.base ?? "origin/main");
|
|
252
|
+
if (judged.kind === "not_run") return notRun(s, judged.reason);
|
|
253
|
+
const { findings: found, works, from } = judged;
|
|
254
|
+
if (found.length === 0) {
|
|
255
|
+
s.out(`versions: ${works} ${works === 1 ? "work" : "works"} judged against ${from}: nothing found\n`);
|
|
256
|
+
return 0;
|
|
257
|
+
}
|
|
258
|
+
for (const f of found) s.err(`${formatFinding(f)}\n`);
|
|
259
|
+
s.err(
|
|
260
|
+
`versions: ${found.length} ${found.length === 1 ? "finding" : "findings"} in ${works} ${works === 1 ? "work" : "works"}, against ${from}\n`,
|
|
261
|
+
);
|
|
262
|
+
return 1;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
function help(s: Say, _command: string, text: string): number {
|
|
266
|
+
s.out(`${text}\n`);
|
|
267
|
+
return 0;
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
/** The ledger of a repository for the commands that need it: tags, ancestry and the ledger of the records given. */
|
|
271
|
+
async function ledgerOf(repo: string, works: readonly Release[], earlier?: readonly EarlierEntry[]) {
|
|
272
|
+
const tags = await readTags(repo);
|
|
273
|
+
if (tags.kind === "err") return tags;
|
|
274
|
+
const ancestry = await tagAncestry(repo, tags.value);
|
|
275
|
+
if (ancestry.kind === "err") return ancestry;
|
|
276
|
+
const result = readLedger({
|
|
277
|
+
tags: tags.value,
|
|
278
|
+
works,
|
|
279
|
+
isAncestor: (a, b) => ancestry.value.has(`${a} ${b}`),
|
|
280
|
+
...(earlier === undefined ? {} : { earlier }),
|
|
281
|
+
});
|
|
282
|
+
return ok({ tags: tags.value, ancestry: ancestry.value, ...result });
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
async function runBump(rest: readonly string[], s: Say, now: () => Date): Promise<number> {
|
|
286
|
+
const p = parseArgs(rest, BUMP, WORK);
|
|
287
|
+
if (p.kind === "err") return usage(s, formatUsageError(p.error, "versions bump"));
|
|
288
|
+
if (p.value.kind === "help") return help(s, "bump", helpText("versions bump", HELP_SUMMARY.bump, BUMP, WORK));
|
|
289
|
+
const o = p.value.options;
|
|
290
|
+
const l = await load(resolve(o.repo), s);
|
|
291
|
+
if (typeof l === "number") return l;
|
|
292
|
+
const w = select(l, p.value.positionals[0] ?? "", s);
|
|
293
|
+
if (typeof w === "number") return w;
|
|
294
|
+
const r = w.release;
|
|
295
|
+
const scheme = schemeOf(r.kind);
|
|
296
|
+
if (scheme === "NoVersion" || r.version === undefined)
|
|
297
|
+
return usage(s, `${r.slug} is a ${r.kind}: a specification has no version, and bump does not raise one`);
|
|
298
|
+
const bad = versionProblems(r);
|
|
299
|
+
if (bad.length > 0) {
|
|
300
|
+
s.err(`${w.file}: versions/scheme-mismatch: ${bad.join("; ")}\n`);
|
|
301
|
+
return 1;
|
|
302
|
+
}
|
|
303
|
+
const today = utcDay(now().getTime() / 1000);
|
|
304
|
+
let next: Release;
|
|
305
|
+
switch (scheme) {
|
|
306
|
+
case "SemVer": {
|
|
307
|
+
let impact: Impact;
|
|
308
|
+
if (o.impact === undefined) return usage(s, `bump of a ${r.kind} needs --impact major, minor, patch or auto`);
|
|
309
|
+
if (o.impact === "auto") {
|
|
310
|
+
const led = await ledgerOf(
|
|
311
|
+
l.repo,
|
|
312
|
+
l.works.map((x) => x.release),
|
|
313
|
+
);
|
|
314
|
+
if (led.kind === "err") return notRun(s, formatGitError(led.error));
|
|
315
|
+
const merged = await tagsMerged(l.repo, "HEAD");
|
|
316
|
+
if (merged.kind === "err") return notRun(s, formatGitError(merged.error));
|
|
317
|
+
const last = lastRelease(led.value.entries, r, merged.value);
|
|
318
|
+
const commits = await commitsSince(l.repo, last?.tag);
|
|
319
|
+
if (commits.kind === "err") return notRun(s, formatGitError(commits.error));
|
|
320
|
+
const inScope = scopeOf(w.folder, workFolders(l.tree.paths), r.exclude ?? [], r.paths ?? []);
|
|
321
|
+
const found = impactOfCommits(commits.value.filter((c) => c.files.some(inScope)));
|
|
322
|
+
if (found === undefined)
|
|
323
|
+
return usage(
|
|
324
|
+
s,
|
|
325
|
+
`no commit since ${last?.tag ?? "the beginning"} that touches ${r.slug} states an impact (a line "Impact: major", "Impact: minor" or "Impact: patch")`,
|
|
326
|
+
);
|
|
327
|
+
impact = found;
|
|
328
|
+
} else impact = o.impact;
|
|
329
|
+
const v = nextSemVer(r.version, impact);
|
|
330
|
+
if (v.kind === "err") return usage(s, v.error);
|
|
331
|
+
next = { ...r, version: v.value };
|
|
332
|
+
break;
|
|
333
|
+
}
|
|
334
|
+
case "CommitDateEdition": {
|
|
335
|
+
const head = await resolveCommit(l.repo, "HEAD");
|
|
336
|
+
if (head.kind === "err") return notRun(s, formatGitError(head.error));
|
|
337
|
+
const secs = await commitSeconds(l.repo, head.value);
|
|
338
|
+
if (secs.kind === "err") return notRun(s, formatGitError(secs.error));
|
|
339
|
+
next = { ...r, version: editionAt(head.value, secs.value) };
|
|
340
|
+
break;
|
|
341
|
+
}
|
|
342
|
+
case "SnapshotDate": {
|
|
343
|
+
if (o.snapshot === undefined || r.snapshot === undefined)
|
|
344
|
+
return usage(s, "bump of data needs --snapshot FILE, the snapshot whose SHA-256 the record carries");
|
|
345
|
+
const file = resolve(o.snapshot);
|
|
346
|
+
if (!existsSync(file)) return notRun(s, `${file} does not exist`);
|
|
347
|
+
const digest = String(await sha256File(file));
|
|
348
|
+
const schemaVersion =
|
|
349
|
+
o.impact === undefined
|
|
350
|
+
? ok(r.snapshot.schemaVersion)
|
|
351
|
+
: o.impact === "auto"
|
|
352
|
+
? err("bump of data takes an explicit --impact for its schema, not auto")
|
|
353
|
+
: nextSemVer(r.snapshot.schemaVersion, o.impact);
|
|
354
|
+
if (schemaVersion.kind === "err") return usage(s, schemaVersion.error);
|
|
355
|
+
next = { ...r, version: o.day ?? today, snapshot: { ...r.snapshot, digest, schemaVersion: schemaVersion.value } };
|
|
356
|
+
break;
|
|
357
|
+
}
|
|
358
|
+
case "IntegerRevision": {
|
|
359
|
+
const n = Number(r.version) + 1;
|
|
360
|
+
const given = [o.approvedBy, o.role, o.decision];
|
|
361
|
+
if (given.some((g) => g !== undefined) && given.some((g) => g === undefined))
|
|
362
|
+
return usage(s, "an approval needs --approved-by, --role and --decision together");
|
|
363
|
+
const on = dayOf(o.day ?? today);
|
|
364
|
+
if (on === undefined) return usage(s, `${o.day ?? today} is not a day`);
|
|
365
|
+
const { approval: _previous, ...rest0 } = r;
|
|
366
|
+
next =
|
|
367
|
+
o.approvedBy === undefined || o.role === undefined || o.decision === undefined
|
|
368
|
+
? { ...rest0, version: String(n) }
|
|
369
|
+
: { ...rest0, version: String(n), approval: { approvedBy: o.approvedBy, role: o.role, on, decision: o.decision } };
|
|
370
|
+
break;
|
|
371
|
+
}
|
|
372
|
+
default:
|
|
373
|
+
return absurd(scheme);
|
|
374
|
+
}
|
|
375
|
+
writeTextFileSync(join(l.repo, w.file), releaseSource(next));
|
|
376
|
+
s.out(`${r.slug}: ${r.version} -> ${next.version} (${w.file})\n`);
|
|
377
|
+
if (scheme === "IntegerRevision" && next.approval === undefined)
|
|
378
|
+
s.out("the new revision has no approval yet: the check finds it until the approval is recorded\n");
|
|
379
|
+
return 0;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
async function runTag(rest: readonly string[], s: Say): Promise<number> {
|
|
383
|
+
const p = parseArgs(rest, TAG, WORK);
|
|
384
|
+
if (p.kind === "err") return usage(s, formatUsageError(p.error, "versions tag"));
|
|
385
|
+
if (p.value.kind === "help") return help(s, "tag", helpText("versions tag", HELP_SUMMARY.tag, TAG, WORK));
|
|
386
|
+
const o = p.value.options;
|
|
387
|
+
const repo = resolve(o.repo);
|
|
388
|
+
const l = await load(repo, s);
|
|
389
|
+
if (typeof l === "number") return l;
|
|
390
|
+
const w = select(l, p.value.positionals[0] ?? "", s);
|
|
391
|
+
if (typeof w === "number") return w;
|
|
392
|
+
const r = w.release;
|
|
393
|
+
const scheme = schemeOf(r.kind);
|
|
394
|
+
if (scheme === "NoVersion" || r.version === undefined)
|
|
395
|
+
return usage(s, `${r.slug} is a ${r.kind}: a specification has no version, and tag does not release one`);
|
|
396
|
+
const refuse = (m: string): number => {
|
|
397
|
+
s.err(`versions: tag refused: ${m}\n`);
|
|
398
|
+
return 1;
|
|
399
|
+
};
|
|
400
|
+
const bad = versionProblems(r);
|
|
401
|
+
if (bad.length > 0) return refuse(`${w.file}: ${bad.join("; ")}`);
|
|
402
|
+
const dirty = await isDirty(repo, w.file);
|
|
403
|
+
if (dirty.kind === "err") return notRun(s, formatGitError(dirty.error));
|
|
404
|
+
if (dirty.value) return refuse(`${w.file} has a change that is not committed: commit the record, then tag the commit`);
|
|
405
|
+
const led = await ledgerOf(
|
|
406
|
+
repo,
|
|
407
|
+
l.works.map((x) => x.release),
|
|
408
|
+
);
|
|
409
|
+
if (led.kind === "err") return notRun(s, formatGitError(led.error));
|
|
410
|
+
const name = tagNameOf(r.slug, r.version);
|
|
411
|
+
if (led.value.tags.some((t) => t.name === name))
|
|
412
|
+
return refuse(`the tag ${name} exists: a published version is immutable, and a correction is a new version`);
|
|
413
|
+
const head = await resolveCommit(repo, "HEAD");
|
|
414
|
+
if (head.kind === "err") return notRun(s, formatGitError(head.error));
|
|
415
|
+
const last = lastRelease(led.value.entries, r);
|
|
416
|
+
const mine = parseVersion(scheme, r.version);
|
|
417
|
+
const before = last === undefined ? undefined : parseVersion(scheme, last.version);
|
|
418
|
+
if (mine.kind === "ok" && before?.kind === "ok" && last !== undefined) {
|
|
419
|
+
const behind = await isAncestor(repo, last.commit, head.value);
|
|
420
|
+
if (behind.kind === "err") return notRun(s, formatGitError(behind.error));
|
|
421
|
+
const c = compareVersions(mine.value, before.value, () => (behind.value ? 1 : 0));
|
|
422
|
+
if (c === undefined || c <= 0)
|
|
423
|
+
return refuse(`the version ${r.version} is not greater than ${last.version}, the last tag of ${r.slug} (${last.tag})`);
|
|
424
|
+
}
|
|
425
|
+
// the gate of a regulated harness (FR-026)
|
|
426
|
+
const declFile = o.declaration === undefined ? join(repo, "ifccm.declaration.ts") : resolve(repo, o.declaration);
|
|
427
|
+
let declaration: Declaration | undefined;
|
|
428
|
+
if (existsSync(declFile)) {
|
|
429
|
+
const rec = decodeHarnessRecord(readTextFileSync(declFile));
|
|
430
|
+
if (rec.kind === "err") return notRun(s, `${declFile}: ${formatRecordError(rec.error)}`);
|
|
431
|
+
declaration = rec.value.declaration;
|
|
432
|
+
} else if (o.declaration !== undefined) return notRun(s, `${declFile} does not exist`);
|
|
433
|
+
const gate = releaseGate(declaration, o.tier !== undefined && isReleaseTier(o.tier) ? o.tier : undefined);
|
|
434
|
+
if (gate.kind === "refused") return refuse(gate.reason);
|
|
435
|
+
const tree = await gitText(repo, ["rev-parse", "HEAD^{tree}"]);
|
|
436
|
+
if (tree.kind === "err") return notRun(s, formatGitError(tree.error));
|
|
437
|
+
const message = `${r.slug} ${r.version}\n\ncommit: ${head.value}\ntree: ${tree.value.trim()}\nscheme: ${scheme}\ntier: ${gate.tier ?? "not judged"}\n`;
|
|
438
|
+
const signing = await signingConfigured(repo);
|
|
439
|
+
if (signing.kind === "err") return notRun(s, formatGitError(signing.error));
|
|
440
|
+
const made = await createTag(repo, name, message, signing.value);
|
|
441
|
+
if (made.kind === "err") return notRun(s, `the tag ${name} was not made: ${formatGitError(made.error)}`);
|
|
442
|
+
s.out(
|
|
443
|
+
`${name}: tagged ${head.value.slice(0, 12)} (${signing.value ? "signed" : "not signed: Git signing is not configured (user.signingkey or tag.gpgSign), so the tag is annotated only"})\n`,
|
|
444
|
+
);
|
|
445
|
+
return 0;
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
async function runNotes(rest: readonly string[], s: Say): Promise<number> {
|
|
449
|
+
const p = parseArgs(rest, NOTES, WORK);
|
|
450
|
+
if (p.kind === "err") return usage(s, formatUsageError(p.error, "versions notes"));
|
|
451
|
+
if (p.value.kind === "help") return help(s, "notes", helpText("versions notes", HELP_SUMMARY.notes, NOTES, WORK));
|
|
452
|
+
const o = p.value.options;
|
|
453
|
+
const l = await load(resolve(o.repo), s);
|
|
454
|
+
if (typeof l === "number") return l;
|
|
455
|
+
const w = select(l, p.value.positionals[0] ?? "", s);
|
|
456
|
+
if (typeof w === "number") return w;
|
|
457
|
+
const r = w.release;
|
|
458
|
+
if (schemeOf(r.kind) === "NoVersion")
|
|
459
|
+
return usage(s, `${r.slug} is a ${r.kind}: a specification has no version, so it has no release notes`);
|
|
460
|
+
let from = o.from;
|
|
461
|
+
if (from === undefined) {
|
|
462
|
+
const led = await ledgerOf(
|
|
463
|
+
l.repo,
|
|
464
|
+
l.works.map((x) => x.release),
|
|
465
|
+
);
|
|
466
|
+
if (led.kind === "err") return notRun(s, formatGitError(led.error));
|
|
467
|
+
const merged = await tagsMerged(l.repo, "HEAD");
|
|
468
|
+
if (merged.kind === "err") return notRun(s, formatGitError(merged.error));
|
|
469
|
+
from = lastRelease(led.value.entries, r, merged.value)?.tag;
|
|
470
|
+
} else {
|
|
471
|
+
const known = await resolveCommit(l.repo, from);
|
|
472
|
+
if (known.kind === "err") return usage(s, `--from ${from} is not a tag or a commit of this repository`);
|
|
473
|
+
}
|
|
474
|
+
const commits = await commitsSince(l.repo, from);
|
|
475
|
+
if (commits.kind === "err") return notRun(s, formatGitError(commits.error));
|
|
476
|
+
const inScope = scopeOf(w.folder, workFolders(l.tree.paths), r.exclude ?? [], r.paths ?? []);
|
|
477
|
+
s.out(notesOf({ slug: r.slug, title: r.title, version: r.version, from, commits: commits.value.filter((c) => c.files.some(inScope)) }));
|
|
478
|
+
return 0;
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
async function runCite(rest: readonly string[], s: Say): Promise<number> {
|
|
482
|
+
const p = parseArgs(rest, CITE, WORK);
|
|
483
|
+
if (p.kind === "err") return usage(s, formatUsageError(p.error, "versions cite"));
|
|
484
|
+
if (p.value.kind === "help") return help(s, "cite", helpText("versions cite", HELP_SUMMARY.cite, CITE, WORK));
|
|
485
|
+
const o = p.value.options;
|
|
486
|
+
const l = await load(resolve(o.repo), s);
|
|
487
|
+
if (typeof l === "number") return l;
|
|
488
|
+
const w = select(l, p.value.positionals[0] ?? "", s);
|
|
489
|
+
if (typeof w === "number") return w;
|
|
490
|
+
const r = w.release;
|
|
491
|
+
if (schemeOf(r.kind) === "NoVersion" || r.version === undefined)
|
|
492
|
+
return usage(s, `${r.slug} is a ${r.kind}: a specification has no version, and cite does not cite one`);
|
|
493
|
+
const tags = await readTags(l.repo);
|
|
494
|
+
if (tags.kind === "err") return notRun(s, formatGitError(tags.error));
|
|
495
|
+
const tag = tags.value.find((t) => t.name === tagNameOf(r.slug, r.version ?? ""));
|
|
496
|
+
let seconds: number;
|
|
497
|
+
if (tag === undefined) {
|
|
498
|
+
const head = await commitSeconds(l.repo, "HEAD");
|
|
499
|
+
if (head.kind === "err") return notRun(s, formatGitError(head.error));
|
|
500
|
+
seconds = head.value;
|
|
501
|
+
} else seconds = tag.seconds;
|
|
502
|
+
const cff = citationOf(r, utcDay(seconds));
|
|
503
|
+
if (cff === undefined) return usage(s, `${r.slug} has no version to cite`);
|
|
504
|
+
const path = join(l.repo, w.folder, CITATION_FILE);
|
|
505
|
+
const shown = w.folder === "" ? CITATION_FILE : `${w.folder}/${CITATION_FILE}`;
|
|
506
|
+
if (o.check) {
|
|
507
|
+
const current = existsSync(path) ? readTextFileSync(path) : undefined;
|
|
508
|
+
if (current === cff) {
|
|
509
|
+
s.out(`${shown}: is what the record makes\n`);
|
|
510
|
+
return 0;
|
|
511
|
+
}
|
|
512
|
+
s.err(`${shown}: ${current === undefined ? "does not exist" : "differs from what the record makes"}; run versions cite ${r.slug}\n`);
|
|
513
|
+
return 1;
|
|
514
|
+
}
|
|
515
|
+
writeTextFileSync(path, cff);
|
|
516
|
+
s.out(`${shown}: written for ${r.slug} ${r.version}\n`);
|
|
517
|
+
return 0;
|
|
518
|
+
}
|
|
519
|
+
|
|
520
|
+
async function runLedger(rest: readonly string[], s: Say): Promise<number> {
|
|
521
|
+
const WORKS: readonly Operand[] = [{ name: "WORK", help: "Only this work, by its slug or its folder.", arity: "optional" }];
|
|
522
|
+
const p = parseArgs(rest, LEDGER, WORKS);
|
|
523
|
+
if (p.kind === "err") return usage(s, formatUsageError(p.error, "versions ledger"));
|
|
524
|
+
if (p.value.kind === "help") return help(s, "ledger", helpText("versions ledger", HELP_SUMMARY.ledger, LEDGER, WORKS));
|
|
525
|
+
const o = p.value.options;
|
|
526
|
+
const l = await load(resolve(o.repo), s);
|
|
527
|
+
if (typeof l === "number") return l;
|
|
528
|
+
let only: string | undefined;
|
|
529
|
+
const name = p.value.positionals[0];
|
|
530
|
+
if (name !== undefined) {
|
|
531
|
+
const w = select(l, name, s);
|
|
532
|
+
if (typeof w === "number") return w;
|
|
533
|
+
only = w.release.slug;
|
|
534
|
+
}
|
|
535
|
+
let earlier: readonly EarlierEntry[] | undefined;
|
|
536
|
+
if (o.against !== undefined) {
|
|
537
|
+
const file = resolve(o.against);
|
|
538
|
+
if (!existsSync(file)) return notRun(s, `${file} does not exist`);
|
|
539
|
+
const e = readEarlier(readTextFileSync(file));
|
|
540
|
+
if (e.kind === "err") return usage(s, `${file} is not a ledger written by --json: ${e.error}`);
|
|
541
|
+
earlier = only === undefined ? e.value : e.value.filter((x) => x.work === only);
|
|
542
|
+
}
|
|
543
|
+
const led = await ledgerOf(
|
|
544
|
+
l.repo,
|
|
545
|
+
l.works.map((x) => x.release),
|
|
546
|
+
earlier,
|
|
547
|
+
);
|
|
548
|
+
if (led.kind === "err") return notRun(s, formatGitError(led.error));
|
|
549
|
+
const entries = only === undefined ? led.value.entries : led.value.entries.filter((e) => e.work === only);
|
|
550
|
+
const findings = sortFindings([
|
|
551
|
+
...(only === undefined ? l.invalid : []),
|
|
552
|
+
...led.value.findings.filter((f) => only === undefined || f.work === only),
|
|
553
|
+
]);
|
|
554
|
+
s.out(o.json ? ledgerJson(entries) : ledgerText(entries));
|
|
555
|
+
for (const f of findings) s.err(`${formatFinding(f)}\n`);
|
|
556
|
+
return findings.length === 0 ? 0 : 1;
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
/** Run the command: the exit status (0, 1 findings, 2 usage, 3 the environment cannot do it). */
|
|
560
|
+
export async function run(argv: readonly string[], deps: Deps = {}): Promise<number> {
|
|
561
|
+
const s: Say = {
|
|
562
|
+
out: deps.out ?? ((t: string): void => void stdio.stdout.writeSync(t)),
|
|
563
|
+
err: deps.err ?? ((t: string): void => void stdio.stderr.writeSync(t)),
|
|
564
|
+
};
|
|
565
|
+
const now = deps.now ?? ((): Date => new Date());
|
|
566
|
+
const [command, ...rest] = argv;
|
|
567
|
+
if (command === undefined) return usage(s, "no command");
|
|
568
|
+
if (command === "--help" || command === "-h" || command === "help") {
|
|
569
|
+
s.out(
|
|
570
|
+
`versions: how works are versioned (commons 0026-works-versioning)\n\n${COMMANDS.map((c) => ` ${c.padEnd(7)}${HELP_SUMMARY[c]}`).join("\n")}\n\nversions COMMAND --help says the options of a command.\n`,
|
|
571
|
+
);
|
|
572
|
+
return 0;
|
|
573
|
+
}
|
|
574
|
+
switch (command) {
|
|
575
|
+
case "check":
|
|
576
|
+
return runCheck(rest, s);
|
|
577
|
+
case "bump":
|
|
578
|
+
return runBump(rest, s, now);
|
|
579
|
+
case "tag":
|
|
580
|
+
return runTag(rest, s);
|
|
581
|
+
case "notes":
|
|
582
|
+
return runNotes(rest, s);
|
|
583
|
+
case "cite":
|
|
584
|
+
return runCite(rest, s);
|
|
585
|
+
case "ledger":
|
|
586
|
+
return runLedger(rest, s);
|
|
587
|
+
default: {
|
|
588
|
+
const near = suggest(command, COMMANDS);
|
|
589
|
+
return usage(s, `unknown command ${command}${near === undefined ? "" : ` (did you mean ${near}?)`}`);
|
|
590
|
+
}
|
|
591
|
+
}
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
if (import.meta.main) process.exitCode = await run(process.argv.slice(2), {});
|