@intellectual-frontiers/ergonex 0.2.5 → 0.3.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/README.md +2 -0
- package/dist/desired.d.ts +27 -0
- package/dist/diff.d.ts +12 -0
- package/dist/doctor.d.ts +79 -0
- package/dist/findings.d.ts +85 -0
- package/dist/layout.d.ts +83 -0
- package/dist/manifest.d.ts +84 -0
- package/dist/mod.d.ts +29 -0
- package/dist/mod.js +4219 -0
- package/dist/modules/external.d.ts +31 -0
- package/dist/modules/mod.d.ts +10 -0
- package/dist/modules/name.d.ts +32 -0
- package/dist/modules/registry.d.ts +51 -0
- package/dist/modules/types.d.ts +178 -0
- package/dist/places.d.ts +35 -0
- package/dist/plan.d.ts +176 -0
- package/dist/platform/k-args.d.ts +28 -0
- package/dist/policy.d.ts +39 -0
- package/dist/portable.d.ts +111 -0
- package/dist/render.d.ts +95 -0
- package/dist/setup/evidence.d.ts +58 -0
- package/dist/shell/block.d.ts +45 -0
- package/dist/shell/mod.d.ts +8 -0
- package/dist/shell/snippet.d.ts +43 -0
- package/dist/state-record.d.ts +59 -0
- package/dist/state.d.ts +64 -0
- package/dist/templates/data.d.ts +25 -0
- package/dist/templates/hooks.d.ts +13 -0
- package/dist/templates/mod.d.ts +16 -0
- package/dist/tools/catalog.d.ts +70 -0
- package/dist/types.d.ts +51 -0
- package/dist/vendor/ts/githost/capabilities.d.ts +18 -0
- package/dist/vendor/ts/githost/git.d.ts +16 -0
- package/dist/vendor/ts/githost/github.d.ts +15 -0
- package/dist/vendor/ts/githost/gitlab.d.ts +15 -0
- package/dist/vendor/ts/githost/mod.d.ts +29 -0
- package/dist/vendor/ts/githost/remote.d.ts +59 -0
- package/dist/vendor/ts/githost/types.d.ts +101 -0
- package/dist/vendor/ts/kernel/archive.d.ts +147 -0
- package/dist/vendor/ts/kernel/args.d.ts +240 -0
- package/dist/vendor/ts/kernel/assess.d.ts +247 -0
- package/dist/vendor/ts/kernel/attest.d.ts +164 -0
- package/dist/vendor/ts/kernel/base64.d.ts +24 -0
- package/dist/vendor/ts/kernel/cbor.d.ts +39 -0
- package/dist/vendor/ts/kernel/cms.d.ts +106 -0
- package/dist/vendor/ts/kernel/commands.d.ts +103 -0
- package/dist/vendor/ts/kernel/cose.d.ts +34 -0
- package/dist/vendor/ts/kernel/crypt.d.ts +30 -0
- package/dist/vendor/ts/kernel/csv.d.ts +38 -0
- package/dist/vendor/ts/kernel/der.d.ts +67 -0
- package/dist/vendor/ts/kernel/documentation.d.ts +118 -0
- package/dist/vendor/ts/kernel/dsse.d.ts +137 -0
- package/dist/vendor/ts/kernel/evidence.d.ts +212 -0
- package/dist/vendor/ts/kernel/glob.d.ts +64 -0
- package/dist/vendor/ts/kernel/grc.d.ts +356 -0
- package/dist/vendor/ts/kernel/http.d.ts +46 -0
- package/dist/vendor/ts/kernel/json5.d.ts +46 -0
- package/dist/vendor/ts/kernel/layers.d.ts +35 -0
- package/dist/vendor/ts/kernel/md5.d.ts +19 -0
- package/dist/vendor/ts/kernel/media-types.d.ts +28 -0
- package/dist/vendor/ts/kernel/mod.d.ts +95 -0
- package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +4374 -0
- package/dist/vendor/ts/kernel/ocsf.d.ts +160 -0
- package/dist/vendor/ts/kernel/oscal.d.ts +356 -0
- package/dist/vendor/ts/kernel/otel.d.ts +365 -0
- package/dist/vendor/ts/kernel/otlp.d.ts +83 -0
- package/dist/vendor/ts/kernel/palette.d.ts +44 -0
- package/dist/vendor/ts/kernel/png.d.ts +124 -0
- package/dist/vendor/ts/kernel/rdf-schema.d.ts +190 -0
- package/dist/vendor/ts/kernel/rdf-term.d.ts +162 -0
- package/dist/vendor/ts/kernel/rdf-vocabularies.d.ts +148 -0
- package/dist/vendor/ts/kernel/rdf-write.d.ts +25 -0
- package/dist/vendor/ts/kernel/rdf.d.ts +35 -0
- package/dist/vendor/ts/kernel/render.d.ts +111 -0
- package/dist/vendor/ts/kernel/schedule.d.ts +207 -0
- package/dist/vendor/ts/kernel/semver.d.ts +94 -0
- package/dist/vendor/ts/kernel/sha256.d.ts +29 -0
- package/dist/vendor/ts/kernel/signals.d.ts +371 -0
- package/dist/vendor/ts/kernel/sigv4.d.ts +67 -0
- package/dist/vendor/ts/kernel/test-record.d.ts +222 -0
- package/dist/vendor/ts/kernel/test-report.d.ts +294 -0
- package/dist/vendor/ts/kernel/toml.d.ts +51 -0
- package/dist/vendor/ts/kernel/trace.d.ts +169 -0
- package/dist/vendor/ts/kernel/ts-literal.d.ts +62 -0
- package/dist/vendor/ts/kernel/uuid.d.ts +53 -0
- package/dist/vendor/ts/kernel/vt.d.ts +78 -0
- package/dist/vendor/ts/kernel/webauthn.d.ts +212 -0
- package/dist/vendor/ts/kernel/width.d.ts +63 -0
- package/dist/vendor/ts/kernel/xml.d.ts +73 -0
- package/dist/vendor/ts/kernel/yaml.d.ts +44 -0
- package/dist/vendor/ts/runtime/http-client.d.ts +149 -0
- package/ergonex.mjs +140 -140
- package/package.json +17 -5
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Test evidence (commons 0008-test-evidence): the record of a test run as OpenTelemetry and every report rendered from it, purely.
|
|
3
|
+
*
|
|
4
|
+
* - Capture (FR-001 to FR-004) is `./test-record.ts`: the model of a test case and an installation, and the signals a test process writes.
|
|
5
|
+
* - The run (FR-005 to FR-007): the exit rule (`judge`), the run's `test run` span and the one OTLP JSON document of a run
|
|
6
|
+
* (`assembleRecord`), read back only through the OTLP decoders of 0006-signals FR-004 into a typed model (`readRecord`). The requirement
|
|
7
|
+
* lists a run is held to: ids one per line, or a spec-kit enforcement register's rows of mechanism `check` (`parseRequirementList`), and
|
|
8
|
+
* requirements declared reviewed (`parseReviewList`).
|
|
9
|
+
* - Reports (FR-008 to FR-010): TAP version 14, JUnit XML, CTRF JSON, SARIF 2.1.0, OSCAL 1.2.3 assessment results and a completion report
|
|
10
|
+
* in Markdown and in self-contained HTML. Each is a function of the model alone (and, for the completion report, of the signatures the
|
|
11
|
+
* ledger holds), with no clock: rendering a record twice gives the same bytes, and the counts of each agree with the model's.
|
|
12
|
+
* - Evidence (FR-011 to FR-013): the ledger entries of a run and of a signature with its meaning and role, the in-toto Test Result
|
|
13
|
+
* statement of a run, and `verifyEvidence`, which checks a record's digest against a ledger, the ledger's chain, each envelope given and,
|
|
14
|
+
* where asked, a signature of meaning `reviewed`.
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```ts
|
|
18
|
+
* import { readRecord, tap14 } from "./test-report.js";
|
|
19
|
+
* // const run = readRecord(await readTextFile("out/4bf92f3577b34da6a3ce929d0e0e4736.otlp.json"));
|
|
20
|
+
* // if (run.kind === "ok") console.log(tap14(run.value));
|
|
21
|
+
* ```
|
|
22
|
+
*
|
|
23
|
+
* @module
|
|
24
|
+
*/
|
|
25
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
26
|
+
import { type DsseEnvelope, type DsseKey, type ResourceDescriptor, type Statement } from "./dsse.js";
|
|
27
|
+
import { type LedgerBreak, type LedgerEntry, type LedgerRecord } from "./evidence.js";
|
|
28
|
+
import { type ControlRef, type Instant } from "./grc.js";
|
|
29
|
+
import type { JsonObject } from "./json5.js";
|
|
30
|
+
import { type SpanId, type TraceId } from "./otel.js";
|
|
31
|
+
import type { Sha256 } from "./sha256.js";
|
|
32
|
+
import { type Installation, type Outcome, type RecordError, type Review, type Risk, type RunnerOutcome, type Signals, type TestCase } from "./test-record.js";
|
|
33
|
+
/** A test of a run: the case, the runtime it ran on (its process's `process.runtime.name`) and the id of its span. */
|
|
34
|
+
export type RunTest = TestCase & {
|
|
35
|
+
readonly runtime: string;
|
|
36
|
+
readonly spanId: string;
|
|
37
|
+
};
|
|
38
|
+
/** How far a requirement is met by a run. */
|
|
39
|
+
export type RequirementState = "proven" | "failing" | "skipped" | "reviewed" | "unproven";
|
|
40
|
+
/** One requirement of a run: the tests that prove it, the reviews of it, its risk and its state. */
|
|
41
|
+
export type RequirementTrace = {
|
|
42
|
+
readonly id: string;
|
|
43
|
+
/** Whether it is in the list the run was held to. */
|
|
44
|
+
readonly required: boolean;
|
|
45
|
+
readonly risk: Risk;
|
|
46
|
+
readonly state: RequirementState;
|
|
47
|
+
readonly tests: readonly {
|
|
48
|
+
readonly id: string;
|
|
49
|
+
readonly name: string;
|
|
50
|
+
readonly runtime: string;
|
|
51
|
+
readonly outcome: Outcome;
|
|
52
|
+
}[];
|
|
53
|
+
readonly reviews: readonly string[];
|
|
54
|
+
};
|
|
55
|
+
/** The counts of a run (FR-010). */
|
|
56
|
+
export type Counts = {
|
|
57
|
+
readonly tests: number;
|
|
58
|
+
readonly passed: number;
|
|
59
|
+
readonly failed: number;
|
|
60
|
+
readonly skipped: number;
|
|
61
|
+
readonly todo: number;
|
|
62
|
+
readonly cancelled: number;
|
|
63
|
+
};
|
|
64
|
+
/** A run's status, as `test.suite.run.status` says it. */
|
|
65
|
+
export type RunStatus = "success" | "failure";
|
|
66
|
+
/** A run's record as a typed model (FR-008). */
|
|
67
|
+
export type TestRun = {
|
|
68
|
+
readonly traceId: string;
|
|
69
|
+
readonly spanId: string;
|
|
70
|
+
readonly start: bigint;
|
|
71
|
+
readonly end: bigint;
|
|
72
|
+
readonly status: RunStatus;
|
|
73
|
+
/** Why it failed, one sentence each; empty where it passed. */
|
|
74
|
+
readonly failures: readonly string[];
|
|
75
|
+
/** The requirements of the list neither proven nor reviewed. */
|
|
76
|
+
readonly unproven: readonly string[];
|
|
77
|
+
/** The list the run was held to. */
|
|
78
|
+
readonly required: readonly string[];
|
|
79
|
+
/** The installation of the process that ran the runners. */
|
|
80
|
+
readonly runner: Installation;
|
|
81
|
+
/** The installation of each runtime the tests ran on, by runtime. */
|
|
82
|
+
readonly installations: readonly Installation[];
|
|
83
|
+
readonly runners: readonly RunnerOutcome[];
|
|
84
|
+
/** In a stable order: runtime, file, name, attempt, start. */
|
|
85
|
+
readonly tests: readonly RunTest[];
|
|
86
|
+
readonly reviews: readonly Review[];
|
|
87
|
+
readonly warnings: readonly string[];
|
|
88
|
+
/** By id. */
|
|
89
|
+
readonly requirements: readonly RequirementTrace[];
|
|
90
|
+
readonly counts: Counts;
|
|
91
|
+
};
|
|
92
|
+
/** The tests of some signals, in a stable order, each with its steps (the `test step` spans under its span). */
|
|
93
|
+
export declare function testsOf(signals: Signals): Result<readonly RunTest[], RecordError>;
|
|
94
|
+
/** The reviews some signals declare, each once, by requirement and reason. */
|
|
95
|
+
export declare function reviewsOf(signals: Signals): readonly Review[];
|
|
96
|
+
/** The counts of some tests. */
|
|
97
|
+
export declare function countsOf(tests: readonly {
|
|
98
|
+
readonly outcome: Outcome;
|
|
99
|
+
}[]): Counts;
|
|
100
|
+
/** Each requirement named by a test, a review or the list, with its state (FR-006, FR-009). */
|
|
101
|
+
export declare function requirementsOf(tests: readonly RunTest[], reviews: readonly Review[], required: readonly string[]): readonly RequirementTrace[];
|
|
102
|
+
/** What the exit rule says of a run (FR-006). */
|
|
103
|
+
export type Judgement = {
|
|
104
|
+
readonly status: RunStatus;
|
|
105
|
+
readonly failures: readonly string[];
|
|
106
|
+
readonly unproven: readonly string[];
|
|
107
|
+
};
|
|
108
|
+
/**
|
|
109
|
+
* The exit rule (FR-006): a run fails when a test failed, when a runner exited non-zero or is not installed, when a test was cancelled,
|
|
110
|
+
* or when a requirement of the list is neither proven by a test of the run nor declared reviewed.
|
|
111
|
+
*/
|
|
112
|
+
export declare function judge(input: {
|
|
113
|
+
readonly tests: readonly RunTest[];
|
|
114
|
+
readonly runners: readonly RunnerOutcome[];
|
|
115
|
+
readonly required: readonly string[];
|
|
116
|
+
readonly reviews: readonly Review[];
|
|
117
|
+
}): Judgement;
|
|
118
|
+
/** What a run is assembled from: its ids and times, the installation that ran it, the signals its processes wrote, the runners, the list and the reviews of a list. */
|
|
119
|
+
export type RunInput = {
|
|
120
|
+
readonly traceId: TraceId;
|
|
121
|
+
readonly spanId: SpanId;
|
|
122
|
+
readonly start: bigint;
|
|
123
|
+
readonly end: bigint;
|
|
124
|
+
readonly runner: Installation;
|
|
125
|
+
readonly signals: Signals;
|
|
126
|
+
readonly runners: readonly RunnerOutcome[];
|
|
127
|
+
readonly required: readonly string[];
|
|
128
|
+
/** Reviews from a list rather than from the tests' own code. */
|
|
129
|
+
readonly reviews?: readonly Review[];
|
|
130
|
+
readonly warnings?: readonly string[];
|
|
131
|
+
};
|
|
132
|
+
/**
|
|
133
|
+
* The one OTLP JSON document of a run (FR-005, FR-006): every process's signals, a cancelled span for each test that never ended, and the
|
|
134
|
+
* run's `test run` span with `test.suite.run.status` and `ifc.test.unproven`, its reviews, runners and warnings; with the judgement.
|
|
135
|
+
*/
|
|
136
|
+
export declare function assembleRecord(input: RunInput): Result<{
|
|
137
|
+
readonly record: JsonObject;
|
|
138
|
+
readonly judgement: Judgement;
|
|
139
|
+
}, RecordError>;
|
|
140
|
+
/** A record as the bytes kept: its JSON and a line feed (FR-007). */
|
|
141
|
+
export declare function recordText(record: JsonObject): string;
|
|
142
|
+
/**
|
|
143
|
+
* A run's record read into the typed model (FR-007, FR-008), only through the OTLP decoders of 0006-signals: the run's span, its
|
|
144
|
+
* installation records (a resource that names a person is refused), its tests, its reviews and its requirements. `input` is the
|
|
145
|
+
* record's text, or its JSON already parsed.
|
|
146
|
+
*/
|
|
147
|
+
export declare function readRecord(input: unknown): Result<TestRun, RecordError>;
|
|
148
|
+
/**
|
|
149
|
+
* The requirements a run is held to (FR-006): one id per line (`0008-test-evidence FR-001`; `#` begins a comment), or a spec-kit
|
|
150
|
+
* enforcement register, whose rows (`requirement`, a tab, `mechanism`, ...) of mechanism `check` are taken. `spec` keeps only the ids
|
|
151
|
+
* that begin with it (`0005-typescript-runtime`). Each id once, in the order given.
|
|
152
|
+
*/
|
|
153
|
+
export declare function parseRequirementList(input: string, spec?: string): readonly string[];
|
|
154
|
+
/** Requirements declared reviewed in a list (FR-006): a line of the requirement, a tab and the reason (`#` begins a comment). A line without a reason is left out. */
|
|
155
|
+
export declare function parseReviewList(input: string): readonly Review[];
|
|
156
|
+
/** Nanoseconds since the Unix epoch as ISO 8601 text in UTC with milliseconds. */
|
|
157
|
+
export declare function isoTime(nanos: bigint): string;
|
|
158
|
+
/** The seconds between two times in nanoseconds, with three decimals. */
|
|
159
|
+
export declare function seconds(start: bigint, end: bigint): string;
|
|
160
|
+
/**
|
|
161
|
+
* The run as TAP version 14 (FR-008): a plan, one subtest per runtime and file, each test `ok` or `not ok` numbered, `# SKIP` and
|
|
162
|
+
* `# TODO` with their reasons, and a YAML diagnostic block for a failure or a cancellation; the counts as closing comments. A test's
|
|
163
|
+
* steps are a subtest of their own before its line (0005-typescript-runtime FR-060).
|
|
164
|
+
*/
|
|
165
|
+
export declare function tap14(run: TestRun): string;
|
|
166
|
+
/**
|
|
167
|
+
* The run as JUnit XML (FR-008): one `testsuite` per file and runtime with the installation as `properties`, a `testcase` with its
|
|
168
|
+
* `classname` (the file) and its time in seconds, the requirements, risk, id and steps (`step`, as `pass outer > inner`) as its
|
|
169
|
+
* `properties`, and `failure`, `error` (cancelled) or `skipped` (skip and todo).
|
|
170
|
+
*/
|
|
171
|
+
export declare function junitXml(run: TestRun): string;
|
|
172
|
+
/** The run as CTRF JSON (FR-008): `results.tool`, `summary` and `tests`, with the requirements, risk, id and outcome under `extra`. */
|
|
173
|
+
export declare function ctrfJson(run: TestRun): string;
|
|
174
|
+
/** The rule of a failed test that proves no requirement. */
|
|
175
|
+
export declare const NO_REQUIREMENT_RULE = "ifc.test.no-requirement";
|
|
176
|
+
/** The run as SARIF 2.1.0 (FR-008): each failed or cancelled test a result at its file, its first requirement as its rule; the counts as the run's properties. */
|
|
177
|
+
export declare function sarif(run: TestRun): string;
|
|
178
|
+
/** The URI the UUIDs and properties of a test run's OSCAL document are named in. */
|
|
179
|
+
export declare const OSCAL_NAMESPACE_URI = "https://github.com/intellectual-frontiers/.github/tree/main/commons/spec-kit/specs/0008-test-evidence";
|
|
180
|
+
/** A requirement as a catalog control: its specification and its number (`0008-test-evidence FR-001`). */
|
|
181
|
+
export declare function requirementRef(id: string): ControlRef;
|
|
182
|
+
/** A requirement as an OSCAL token: `req-` and its words in lower case joined by `-`. */
|
|
183
|
+
export declare function oscalControlId(r: ControlRef): string;
|
|
184
|
+
/**
|
|
185
|
+
* The run as OSCAL 1.2.3 assessment results (FR-008, 0007-grc FR-017): one observation per test (its control the test, its subject the
|
|
186
|
+
* runtime it ran on) and one finding per requirement, satisfied or not by the outcomes of the tests that prove it.
|
|
187
|
+
*/
|
|
188
|
+
export declare function oscalAssessmentResults(run: TestRun, options?: {
|
|
189
|
+
readonly version?: string;
|
|
190
|
+
readonly organization?: string;
|
|
191
|
+
}): Promise<string>;
|
|
192
|
+
/** The meaning of a signature on a run (FR-011). */
|
|
193
|
+
export type Meaning = "executed" | "reviewed" | "approved";
|
|
194
|
+
/** Every meaning. */
|
|
195
|
+
export declare const MEANINGS: readonly Meaning[];
|
|
196
|
+
/** Whether a text is a meaning. */
|
|
197
|
+
export declare function isMeaning(text: string): text is Meaning;
|
|
198
|
+
/** The ledger kind of a run's record. */
|
|
199
|
+
export declare const RUN_KIND = "test-run";
|
|
200
|
+
/** The ledger kind of a signature on a run: `test-signature:<meaning>:<role>`. */
|
|
201
|
+
export declare function signatureKind(meaning: Meaning, role: string): string;
|
|
202
|
+
/** The ledger entry of a run (FR-011): kind `test-run`, the run's trace id as its subject and the record's digest as its evidence. */
|
|
203
|
+
export declare function runEntry(traceId: string, digest: Sha256, at: Instant): LedgerRecord;
|
|
204
|
+
/** The ledger entry of a signature (FR-011): its meaning and role in its kind, the record's digest as its subject, the envelope's digest as its evidence. */
|
|
205
|
+
export declare function signatureEntry(meaning: Meaning, role: string, recordDigest: Sha256, envelopeDigest: Sha256, at: Instant): LedgerRecord;
|
|
206
|
+
/** A signature on a run as the ledger holds it. */
|
|
207
|
+
export type SignatureOnRun = {
|
|
208
|
+
readonly seq: number;
|
|
209
|
+
readonly meaning: Meaning;
|
|
210
|
+
readonly role: string;
|
|
211
|
+
readonly at: string;
|
|
212
|
+
readonly envelope: string;
|
|
213
|
+
};
|
|
214
|
+
/** The signatures the ledger holds on the record of a digest, in the ledger's order. */
|
|
215
|
+
export declare function signaturesOf(ledger: readonly LedgerEntry[], recordDigest: string): readonly SignatureOnRun[];
|
|
216
|
+
/** The predicate type of an in-toto Test Result. */
|
|
217
|
+
export declare const TEST_RESULT_PREDICATE = "https://in-toto.io/attestation/test-result/v0.1";
|
|
218
|
+
/** An in-toto Test Result predicate (v0.1). */
|
|
219
|
+
export type TestResultPredicate = {
|
|
220
|
+
readonly result: "PASSED" | "WARNED" | "FAILED";
|
|
221
|
+
readonly configuration: readonly ResourceDescriptor[];
|
|
222
|
+
readonly url?: string;
|
|
223
|
+
readonly passedTests: readonly string[];
|
|
224
|
+
readonly warnedTests: readonly string[];
|
|
225
|
+
readonly failedTests: readonly string[];
|
|
226
|
+
};
|
|
227
|
+
/**
|
|
228
|
+
* The in-toto Statement v1 of a run (FR-011): its subject the record (`name`, the SHA-256 of its bytes), its predicate the Test Result:
|
|
229
|
+
* `FAILED` where the run failed, `WARNED` where it passed with tests skipped or todo, else `PASSED`; the configuration the record and the
|
|
230
|
+
* lockfile and pins it names.
|
|
231
|
+
*/
|
|
232
|
+
export declare function testResultStatement(run: TestRun, record: {
|
|
233
|
+
readonly name: string;
|
|
234
|
+
readonly digest: Sha256;
|
|
235
|
+
readonly url?: string;
|
|
236
|
+
}): Statement<TestResultPredicate>;
|
|
237
|
+
/** Why `ifc test verify` refused a record (FR-012, FR-013). */
|
|
238
|
+
export type VerifyProblem = {
|
|
239
|
+
readonly kind: "not-in-ledger";
|
|
240
|
+
readonly digest: string;
|
|
241
|
+
} | {
|
|
242
|
+
readonly kind: "ledger-broken";
|
|
243
|
+
readonly break: LedgerBreak;
|
|
244
|
+
} | {
|
|
245
|
+
readonly kind: "envelope";
|
|
246
|
+
readonly name: string;
|
|
247
|
+
readonly reason: string;
|
|
248
|
+
} | {
|
|
249
|
+
readonly kind: "envelope-subject";
|
|
250
|
+
readonly name: string;
|
|
251
|
+
readonly digest: string;
|
|
252
|
+
} | {
|
|
253
|
+
readonly kind: "no-key";
|
|
254
|
+
} | {
|
|
255
|
+
readonly kind: "review-missing";
|
|
256
|
+
readonly digest: string;
|
|
257
|
+
};
|
|
258
|
+
/** A verification problem as one sentence. */
|
|
259
|
+
export declare function formatVerifyProblem(p: VerifyProblem): string;
|
|
260
|
+
/** What verification found where nothing is wrong: the ledger's head and the signatures on the record. */
|
|
261
|
+
export type Verification = {
|
|
262
|
+
readonly seq: number;
|
|
263
|
+
readonly signatures: readonly SignatureOnRun[];
|
|
264
|
+
};
|
|
265
|
+
/**
|
|
266
|
+
* A record's evidence checked (FR-012, FR-013): its digest is in the ledger as a `test-run`, the ledger's chain is whole, each envelope
|
|
267
|
+
* given verifies with the keys given and names the digest, and, with `requireReview`, the ledger holds a signature of meaning `reviewed`
|
|
268
|
+
* on it (one of the envelopes given, where any are). Every problem is named, not only the first.
|
|
269
|
+
*/
|
|
270
|
+
export declare function verifyEvidence(input: {
|
|
271
|
+
readonly recordDigest: Sha256;
|
|
272
|
+
readonly ledger: readonly LedgerEntry[];
|
|
273
|
+
readonly envelopes?: readonly {
|
|
274
|
+
readonly name: string;
|
|
275
|
+
readonly envelope: DsseEnvelope;
|
|
276
|
+
readonly digest: Sha256;
|
|
277
|
+
}[];
|
|
278
|
+
readonly keys?: readonly DsseKey[];
|
|
279
|
+
readonly requireReview?: boolean;
|
|
280
|
+
}): Promise<Result<Verification, readonly VerifyProblem[]>>;
|
|
281
|
+
/** What a completion report adds to the record: the record's digest and the signatures the ledger holds on it. */
|
|
282
|
+
export type CompletionOptions = {
|
|
283
|
+
readonly digest?: string;
|
|
284
|
+
readonly signatures?: readonly SignatureOnRun[];
|
|
285
|
+
};
|
|
286
|
+
/** The test completion report in Markdown (FR-009). */
|
|
287
|
+
export declare function completionMarkdown(run: TestRun, options?: CompletionOptions): string;
|
|
288
|
+
/** The test completion report as one HTML document that needs nothing outside itself (FR-009). */
|
|
289
|
+
export declare function completionHtml(run: TestRun, options?: CompletionOptions): string;
|
|
290
|
+
/** Parses a trace id and a span id (for a runner that holds them as text). */
|
|
291
|
+
export declare function runIds(traceId: string, spanId: string): Result<{
|
|
292
|
+
readonly traceId: TraceId;
|
|
293
|
+
readonly spanId: SpanId;
|
|
294
|
+
}, string>;
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* TOML 1.0.0 (https://toml.io/en/v1.0.0), read and written with no outside package (commons 0005-typescript-runtime FR-035). The reader
|
|
3
|
+
* takes the whole language (bare, quoted and dotted keys; tables, arrays of tables and inline tables; the four kinds of string; decimal,
|
|
4
|
+
* hexadecimal, octal and binary integers; floats with `inf` and `nan`; the four kinds of date and time) and holds to its rules: no key or
|
|
5
|
+
* table defined twice, an inline table or a static array never extended, a table made by dotted keys never reopened by a header. It
|
|
6
|
+
* gives a typed `TomlTable`, or the line and column where the text stops being TOML. An integer outside JavaScript's safe range is refused
|
|
7
|
+
* rather than rounded. A date or time stays as its text, with its kind. The writer gives TOML the reader reads back as the same table.
|
|
8
|
+
* Replaces `@std/toml` in erga.
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* ```ts
|
|
12
|
+
* import { parseToml } from "./toml.js";
|
|
13
|
+
* parseToml('[server]\nhost = "127.0.0.1"\nports = [8000, 8001]\n');
|
|
14
|
+
* // { kind: "ok", value: { server: { host: "127.0.0.1", ports: [8000, 8001] } } }
|
|
15
|
+
* ```
|
|
16
|
+
*
|
|
17
|
+
* @module
|
|
18
|
+
*/
|
|
19
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
20
|
+
/** A date, a time, or both, as TOML wrote it (a space between date and time made `T`), with which of the four it is. */
|
|
21
|
+
export type TomlDateTime = {
|
|
22
|
+
readonly kind: "offset-date-time" | "local-date-time" | "local-date" | "local-time";
|
|
23
|
+
readonly text: string;
|
|
24
|
+
};
|
|
25
|
+
/** A TOML value. */
|
|
26
|
+
export type TomlValue = string | number | boolean | TomlDateTime | readonly TomlValue[] | TomlTable;
|
|
27
|
+
/** A TOML table: its keys in the order they were defined. */
|
|
28
|
+
export type TomlTable = {
|
|
29
|
+
readonly [key: string]: TomlValue;
|
|
30
|
+
};
|
|
31
|
+
/** Where a text stops being TOML, and why. Lines and columns count from 1. */
|
|
32
|
+
export type TomlError = {
|
|
33
|
+
readonly kind: "toml";
|
|
34
|
+
readonly line: number;
|
|
35
|
+
readonly column: number;
|
|
36
|
+
readonly message: string;
|
|
37
|
+
};
|
|
38
|
+
/** A TOML error as one line: `3:14: expected a value`. */
|
|
39
|
+
export declare function formatTomlError(e: TomlError): string;
|
|
40
|
+
/** Whether a TOML value is a date or time. */
|
|
41
|
+
export declare function isTomlDateTime(v: TomlValue): v is TomlDateTime;
|
|
42
|
+
/** Whether a TOML value is a table (not an array, not a date or time). */
|
|
43
|
+
export declare function isTomlTable(v: TomlValue): v is TomlTable;
|
|
44
|
+
/** TOML text read as a table, or where and why it is not TOML. */
|
|
45
|
+
export declare function parseToml(text: string): Result<TomlTable, TomlError>;
|
|
46
|
+
/** A key as TOML writes it: bare where it can be, else a basic string. */
|
|
47
|
+
export declare function tomlKey(k: string): string;
|
|
48
|
+
/** A string as a TOML basic string: `"`, `\` and every control character escaped. */
|
|
49
|
+
export declare function tomlString(s: string): string;
|
|
50
|
+
/** A table as TOML text: plain values first, then each table under its header and each array of tables under `[[...]]`, ending in a line break. */
|
|
51
|
+
export declare function toToml(table: TomlTable): string;
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Trace: every source file tied to a requirement, every requirement proved, every ontology term citing its specification (commons
|
|
3
|
+
* 0015-trace FR-001 to FR-008). Pure functions over the contents of files a harness passes in: the specifications (`specs/NNN-slug/spec.md`
|
|
4
|
+
* and `reviewed.tsv`), the source files and their `// Spec:` lines, the tests and their `proves([...])` calls and `// Proves:` lines, and
|
|
5
|
+
* the ontology's citations. The findings are data, held against a baseline that may only shrink; the layers check (`layers.ts`) gives its
|
|
6
|
+
* findings in the same shape and is judged the same way.
|
|
7
|
+
*
|
|
8
|
+
* @remarks
|
|
9
|
+
* A citation is `// Spec: 097-controller FR-001, FR-003 to FR-005; 098-pair` (a spec with no requirement cites all of it). A baseline is a
|
|
10
|
+
* plain text file of finding keys, one a line, sorted: the tool writes it, a person only deletes lines from it, and nothing in it runs when
|
|
11
|
+
* it is read (FR-002).
|
|
12
|
+
*
|
|
13
|
+
* @limits
|
|
14
|
+
* It reads TypeScript's text, not its syntax tree: a requirement built at run time (`FR(3)`) is not read, and a `proves(` inside a string
|
|
15
|
+
* is. It runs no test.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* ```ts
|
|
19
|
+
* import { judge, parseSpec, traceFindings } from "./trace.js";
|
|
20
|
+
* const spec = parseSpec("001-demo", "**Status:** Active\n\n- **FR-001**: It MUST work.\n");
|
|
21
|
+
* const found = traceFindings({ specs: [spec], sources: [{ path: "src/a.ts", text: "// Spec: 001-demo FR-001\n" }], tests: [], ontology: [] });
|
|
22
|
+
* judge(found, []); // { fresh: [the unproved FR-001], stale: [], kept: [] }
|
|
23
|
+
* ```
|
|
24
|
+
*
|
|
25
|
+
* @module
|
|
26
|
+
*/
|
|
27
|
+
import type { AnyIndividual, Fields } from "./rdf-schema.js";
|
|
28
|
+
/** The rules of the trace check (FR-007). */
|
|
29
|
+
export type TraceRule = "trace/no-spec-line" | "trace/unknown-spec" | "trace/unknown-requirement" | "trace/unproved" | "trace/term-uncited" | "trace/term-unknown-spec";
|
|
30
|
+
/** The rules of the layers check (`layers.ts`, FR-009, FR-010). */
|
|
31
|
+
export type LayerRule = "layers/unclassified" | "layers/ambiguous" | "layers/above" | "layers/around";
|
|
32
|
+
/** Every rule a finding may be of. */
|
|
33
|
+
export type Rule = TraceRule | LayerRule;
|
|
34
|
+
/** A finding (FR-001): where, by which rule, one sentence, and a key that names it without its line. */
|
|
35
|
+
export type Finding = {
|
|
36
|
+
/** The file, relative to the repository, with `/`. */
|
|
37
|
+
readonly file: string;
|
|
38
|
+
/** The line, from 1 (1 for a whole file). */
|
|
39
|
+
readonly line: number;
|
|
40
|
+
/** The rule's id. */
|
|
41
|
+
readonly rule: Rule;
|
|
42
|
+
/** One plain sentence. */
|
|
43
|
+
readonly message: string;
|
|
44
|
+
/** `<rule> <file>`, and what the finding is about where a file holds several of one rule. */
|
|
45
|
+
readonly key: string;
|
|
46
|
+
};
|
|
47
|
+
/** What a baseline and its judgement need of a finding, whatever its rule: a harness's own rules (commons 0003-mizan FR-015) use the same baseline as the trace and layers checks. */
|
|
48
|
+
export type Keyed = {
|
|
49
|
+
readonly file: string;
|
|
50
|
+
readonly line: number;
|
|
51
|
+
readonly rule: string;
|
|
52
|
+
readonly message: string;
|
|
53
|
+
readonly key: string;
|
|
54
|
+
};
|
|
55
|
+
/** A finding, its key made from its rule, its file and what it is about. */
|
|
56
|
+
export declare function finding(rule: Rule, file: string, line: number, message: string, about?: string): Finding;
|
|
57
|
+
/** A file a harness passes in: its path relative to the repository, with `/`, and its text. */
|
|
58
|
+
export type SourceFile = {
|
|
59
|
+
readonly path: string;
|
|
60
|
+
readonly text: string;
|
|
61
|
+
};
|
|
62
|
+
/** Whether a file is generated, so exempt from the trace's rules: its name holds `.auto.` (FR-007). */
|
|
63
|
+
export declare function isGenerated(path: string): boolean;
|
|
64
|
+
/** The keys of a baseline file: every line that is not blank and not a `#` comment, trimmed, each once. */
|
|
65
|
+
export declare function parseBaseline(text: string): readonly string[];
|
|
66
|
+
/** A baseline file from findings: the comment lines given (each prefixed `# `), then the keys sorted by code point, each once. */
|
|
67
|
+
export declare function formatBaseline(findings: readonly Keyed[], comments?: readonly string[]): string;
|
|
68
|
+
/** A judgement of findings against a baseline: the new findings, the stale keys, and the findings the baseline keeps. */
|
|
69
|
+
export type Judgement<F extends Keyed = Finding> = {
|
|
70
|
+
/** Findings whose key the baseline does not hold: they fail the check. */
|
|
71
|
+
readonly fresh: readonly F[];
|
|
72
|
+
/** Baseline keys no finding has: they fail the check until they are deleted. */
|
|
73
|
+
readonly stale: readonly string[];
|
|
74
|
+
/** Findings the baseline holds. */
|
|
75
|
+
readonly kept: readonly F[];
|
|
76
|
+
};
|
|
77
|
+
/** Findings judged against a baseline's keys (FR-002). */
|
|
78
|
+
export declare function judge<F extends Keyed>(findings: readonly F[], baseline: readonly string[]): Judgement<F>;
|
|
79
|
+
/** Whether a judgement passes: nothing new and nothing stale. */
|
|
80
|
+
export declare function passes(j: Judgement<Keyed>): boolean;
|
|
81
|
+
/** The lines a judgement is told with (FR-003): each new finding, each stale key, then a summary. `name` names the check and its baseline. */
|
|
82
|
+
export declare function report(j: Judgement<Keyed>, name: string, baselineFile: string): readonly string[];
|
|
83
|
+
/** A requirement of a specification and the line of `spec.md` it is on. */
|
|
84
|
+
export type SpecRequirement = {
|
|
85
|
+
readonly id: string;
|
|
86
|
+
readonly line: number;
|
|
87
|
+
};
|
|
88
|
+
/** A specification as the trace reads it (FR-004). */
|
|
89
|
+
export type Spec = {
|
|
90
|
+
/** Its folder's name, `NNN-slug`. */
|
|
91
|
+
readonly slug: string;
|
|
92
|
+
/** The first word of its status, where its head states one. */
|
|
93
|
+
readonly status: string | undefined;
|
|
94
|
+
/** Its requirements, in order. */
|
|
95
|
+
readonly requirements: readonly SpecRequirement[];
|
|
96
|
+
/** The requirements its `reviewed.tsv` reviews (`FR-NNN`). */
|
|
97
|
+
readonly reviewed: readonly string[];
|
|
98
|
+
};
|
|
99
|
+
/** A specification read from its `spec.md` and, where it has one, its `reviewed.tsv` (FR-004). */
|
|
100
|
+
export declare function parseSpec(slug: string, specText: string, reviewedText?: string): Spec;
|
|
101
|
+
/** Whether a spec is held to proofs: its status is neither Draft nor Retired (FR-007). */
|
|
102
|
+
export declare function inForce(spec: Spec): boolean;
|
|
103
|
+
/** A requirement or a range of them, as a citation writes it. */
|
|
104
|
+
export type Cited = {
|
|
105
|
+
readonly kind: "one";
|
|
106
|
+
readonly id: string;
|
|
107
|
+
} | {
|
|
108
|
+
readonly kind: "range";
|
|
109
|
+
readonly from: string;
|
|
110
|
+
readonly to: string;
|
|
111
|
+
};
|
|
112
|
+
/** One group of a citation: a spec, and the requirements it names (none: the whole spec). */
|
|
113
|
+
export type Citation = {
|
|
114
|
+
readonly line: number;
|
|
115
|
+
readonly spec: string;
|
|
116
|
+
readonly requirements: readonly Cited[];
|
|
117
|
+
};
|
|
118
|
+
/** The groups of a citation's text (`097-controller FR-001, FR-003 to FR-005; 098-pair`), at a line. */
|
|
119
|
+
export declare function parseCitation(text: string, line: number): readonly Citation[];
|
|
120
|
+
/**
|
|
121
|
+
* The text of each line of a file that is a comment line (FR-005, FR-012), with its line number: a line that begins with two slashes and a space gives what follows; a line inside a block comment
|
|
122
|
+
* (from a line that begins with a slash and an asterisk to the asterisk and slash that close it) gives what follows its leading asterisk, without the closing pair. A line of code that holds a
|
|
123
|
+
* comment after the code is not a comment line.
|
|
124
|
+
*/
|
|
125
|
+
export declare function commentLines(text: string): readonly {
|
|
126
|
+
readonly line: number;
|
|
127
|
+
readonly body: string;
|
|
128
|
+
}[];
|
|
129
|
+
/** Every citation of a file's `Spec:` lines (FR-005, FR-012): `// Spec: ...`, and `Spec: ...` as a line of a block comment. */
|
|
130
|
+
export declare function specLines(text: string): readonly Citation[];
|
|
131
|
+
/** A requirement, or a range of them, a test names, and its line. */
|
|
132
|
+
export type Proof = {
|
|
133
|
+
readonly line: number;
|
|
134
|
+
readonly spec: string;
|
|
135
|
+
readonly requirement: Cited;
|
|
136
|
+
};
|
|
137
|
+
/** Every requirement a test file proves (FR-006, FR-012): in the array a `proves(` call opens, and on its `// Proves:` lines and the `Proves:` lines of its block comments. */
|
|
138
|
+
export declare function proofsOf(text: string): readonly Proof[];
|
|
139
|
+
/** An ontology term and what it cites: specs (`NNN-slug`) or requirements (`NNN-slug FR-NNN`), and where it is stated. */
|
|
140
|
+
export type OntologyCitation = {
|
|
141
|
+
readonly term: string;
|
|
142
|
+
readonly cites: readonly string[];
|
|
143
|
+
readonly file: string;
|
|
144
|
+
readonly line?: number;
|
|
145
|
+
};
|
|
146
|
+
/** What `citationsOf` reads of a class schema: its class and its fields. */
|
|
147
|
+
export type CitingSchema = {
|
|
148
|
+
readonly class: {
|
|
149
|
+
readonly iri: string;
|
|
150
|
+
};
|
|
151
|
+
readonly fields: Fields;
|
|
152
|
+
};
|
|
153
|
+
/** The citations of the individuals made by schemas that have a field `field` (`spec` by default): its values, or none (FR-008). */
|
|
154
|
+
export declare function citationsOf(schemas: readonly CitingSchema[], individuals: readonly AnyIndividual[], file: string, field?: string, termOf?: (iri: string) => string): readonly OntologyCitation[];
|
|
155
|
+
/** What the trace check reads (FR-007). */
|
|
156
|
+
export type TraceInput = {
|
|
157
|
+
/** The specifications. */
|
|
158
|
+
readonly specs: readonly Spec[];
|
|
159
|
+
/** The source files, each to carry a `// Spec:` line. */
|
|
160
|
+
readonly sources: readonly SourceFile[];
|
|
161
|
+
/** The test files, whose proofs are read. */
|
|
162
|
+
readonly tests: readonly SourceFile[];
|
|
163
|
+
/** The ontology's terms and their citations. */
|
|
164
|
+
readonly ontology: readonly OntologyCitation[];
|
|
165
|
+
/** Where the specifications are, from the repository (`specs` by default). */
|
|
166
|
+
readonly specsFolder?: string;
|
|
167
|
+
};
|
|
168
|
+
/** Every finding of the trace (FR-007), in the order: sources, specifications, ontology. */
|
|
169
|
+
export declare function traceFindings(input: TraceInput): readonly Finding[];
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Data as TypeScript object literals, for files a program writes for people to read and edit (keys bare where they are identifiers, strings
|
|
3
|
+
* in double quotes, two-space indentation and trailing commas), and the reader of exactly that subset, which never runs the file, so a past
|
|
4
|
+
* version from `git show` can be read safely (commons 0005-typescript-runtime FR-011); the writer takes any type shaped as JSON (FR-063).
|
|
5
|
+
* Taken from Stolos's `src/archon/core/ts-literal.ts`; the reader returns a `Result` instead of throwing.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* import { parseTsLiteral, tsLiteral } from "./ts-literal.js";
|
|
10
|
+
* const text = tsLiteral({ timezone: "America/New_York", "otel-ui": true });
|
|
11
|
+
* parseTsLiteral(text); // { kind: "ok", value: { value: { timezone: "America/New_York", "otel-ui": true }, end: text.length } }
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* @module
|
|
15
|
+
*/
|
|
16
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
17
|
+
/** A key that needs no quotes: an identifier (letters, digits, `_`, `$`; not starting with a digit). */
|
|
18
|
+
export declare const BARE_KEY: RegExp;
|
|
19
|
+
/** A key as TypeScript writes it: bare where it can be, else a double-quoted string. */
|
|
20
|
+
export declare function tsKey(key: string): string;
|
|
21
|
+
/** A value that {@link parseTsLiteral} reads back, and so {@link tsLiteral} writes: what JSON holds. */
|
|
22
|
+
export type Literal = null | boolean | number | string | readonly Literal[] | {
|
|
23
|
+
readonly [key: string]: Literal | undefined;
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* `T` itself where `T` is shaped as JSON at every depth, else a type `T` is not assignable to, so that a parameter `T & LiteralShape<T>`
|
|
27
|
+
* takes any JSON-shaped type (FR-063), an interface with no index signature included: strings, numbers, booleans and `null`; arrays and
|
|
28
|
+
* tuples of such values; objects whose string keys hold such values, `undefined` allowed only as an optional property's. A function, a
|
|
29
|
+
* `Date`, a `Map`, a `bigint`, a symbol or `unknown` anywhere makes it `never` there.
|
|
30
|
+
*/
|
|
31
|
+
export type LiteralShape<T> = T extends Literal ? T : T extends readonly unknown[] ? {
|
|
32
|
+
readonly [I in keyof T]: LiteralShape<T[I]>;
|
|
33
|
+
} : T extends (...args: never) => unknown ? never : T extends object ? {
|
|
34
|
+
readonly [K in keyof T]: K extends string ? PropertyShape<T[K]> : never;
|
|
35
|
+
} : never;
|
|
36
|
+
/** A property's value shaped as JSON: `undefined` allowed, as an absent optional property, beside a JSON-shaped value. */
|
|
37
|
+
type PropertyShape<V> = undefined extends V ? LiteralShape<Exclude<V, undefined>> | undefined : LiteralShape<V>;
|
|
38
|
+
/**
|
|
39
|
+
* A value as a TypeScript literal, indented for `depth` (two spaces each). It takes any value whose type is shaped as JSON (FR-063), an
|
|
40
|
+
* interface with no index signature included, and refuses at compile time a value holding a function, a `Date`, a `bigint` or another
|
|
41
|
+
* type JSON has not. Objects and arrays span lines (empty ones stay `{}` and `[]`); properties that are `undefined` are left out, as
|
|
42
|
+
* `JSON.stringify` leaves them out. A number that is not finite is written `null`, as JSON writes it. (The check is on the parameter,
|
|
43
|
+
* `T & LiteralShape<T>`, because TypeScript refuses `T extends LiteralShape<T>` as a circular constraint.)
|
|
44
|
+
*/
|
|
45
|
+
export declare function tsLiteral<T>(value: T & LiteralShape<T>, depth?: number): string;
|
|
46
|
+
/** Where a text stopped being a literal, and what was expected there. */
|
|
47
|
+
export type LiteralError = {
|
|
48
|
+
readonly kind: "literal";
|
|
49
|
+
readonly at: number;
|
|
50
|
+
readonly expected: string;
|
|
51
|
+
};
|
|
52
|
+
/**
|
|
53
|
+
* The value of a literal {@link tsLiteral} wrote, starting at `start`, and where it ended: objects with bare or quoted keys, arrays,
|
|
54
|
+
* double-quoted strings, numbers, `true`, `false` and `null`, with trailing commas and `//` comments. Anything else is an error.
|
|
55
|
+
*/
|
|
56
|
+
export declare function parseTsLiteral(text: string, start?: number): Result<{
|
|
57
|
+
readonly value: Literal;
|
|
58
|
+
readonly end: number;
|
|
59
|
+
}, LiteralError>;
|
|
60
|
+
/** The value of `export const <name>[: Type] = <literal>;` in a file {@link tsLiteral} wrote, or why it cannot be read. */
|
|
61
|
+
export declare function exportedLiteral(source: string, name: string): Result<Literal, LiteralError>;
|
|
62
|
+
export {};
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* UUIDs (RFC 9562): the branded `Uuid`, its text form read and written, the name-based version 5 (SHA-1 of a namespace and a name) and the
|
|
3
|
+
* namespaces RFC 9562 defines (Appendix A.4: DNS, URL, OID, X.500). A version 5 UUID is the same for the same namespace and name on every
|
|
4
|
+
* runtime, so the standard formats name what they describe by it and the same input gives the same document (commons 0007-grc FR-017,
|
|
5
|
+
* FR-018). SHA-1 is Web Crypto's (`crypto.subtle.digest`), so `uuidV5` is asynchronous; it is used here as RFC 9562 uses it, to name, not
|
|
6
|
+
* to protect.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { NAMESPACE_DNS, uuidV5 } from "./uuid.js";
|
|
11
|
+
* await uuidV5(NAMESPACE_DNS, "www.example.com"); // "2ed6657d-e927-568b-95e1-2665a8aea6a2"
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* @module
|
|
15
|
+
*/
|
|
16
|
+
import { type Decoder } from "@intellectual-frontiers/core";
|
|
17
|
+
import type { Brand } from "@intellectual-frontiers/core";
|
|
18
|
+
/** A UUID in RFC 9562's text form, lower-case: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`; made only by `uuidOf`, `uuidFromBytes` and `uuidV5`. */
|
|
19
|
+
export type Uuid = Brand<string, "Uuid">;
|
|
20
|
+
/** Text as a `Uuid` (any case, with or without a `urn:uuid:` prefix), lower-cased; undefined where it is not one. */
|
|
21
|
+
export declare function uuidOf(text: string): Uuid | undefined;
|
|
22
|
+
/** Sixteen bytes as a `Uuid`, or undefined where there are not sixteen. */
|
|
23
|
+
export declare function uuidFromBytes(bytes: Uint8Array): Uuid | undefined;
|
|
24
|
+
/** A UUID's sixteen bytes. */
|
|
25
|
+
export declare function uuidBytes(u: Uuid): Uint8Array;
|
|
26
|
+
/** A UUID's version, the high four bits of its seventh byte (5 for a name-based UUID with SHA-1). */
|
|
27
|
+
export declare function uuidVersion(u: Uuid): number;
|
|
28
|
+
/** A UUID as a URN, `urn:uuid:...` (RFC 9562 Section 4). */
|
|
29
|
+
export declare function uuidUrn(u: Uuid): `urn:uuid:${string}`;
|
|
30
|
+
/** The Nil UUID, all zeros (RFC 9562 Section 5.9). */
|
|
31
|
+
export declare const NIL_UUID: Uuid;
|
|
32
|
+
/** The namespace of fully qualified domain names (RFC 9562 Section 6.6). */
|
|
33
|
+
export declare const NAMESPACE_DNS: Uuid;
|
|
34
|
+
/** The namespace of URLs (RFC 9562 Section 6.6). */
|
|
35
|
+
export declare const NAMESPACE_URL: Uuid;
|
|
36
|
+
/** The namespace of ISO object identifiers (RFC 9562 Section 6.6). */
|
|
37
|
+
export declare const NAMESPACE_OID: Uuid;
|
|
38
|
+
/** The namespace of X.500 distinguished names, in DER or text (RFC 9562 Section 6.6). */
|
|
39
|
+
export declare const NAMESPACE_X500: Uuid;
|
|
40
|
+
/**
|
|
41
|
+
* The version 5 UUID of a name in a namespace (RFC 9562 Section 5.5): the first sixteen bytes of SHA-1 over the namespace's bytes and then
|
|
42
|
+
* the name's (a string is taken as UTF-8), with the version (5) and the variant (`10`) set.
|
|
43
|
+
*/
|
|
44
|
+
export declare function uuidV5(namespace: Uuid, name: string | Uint8Array): Promise<Uuid>;
|
|
45
|
+
/**
|
|
46
|
+
* A stable name made of parts, for `uuidV5`: the parts as a JSON array, so that no two lists of parts give the same name (`["a/b"]` and
|
|
47
|
+
* `["a", "b"]` stay apart).
|
|
48
|
+
*/
|
|
49
|
+
export declare function nameOf(parts: readonly string[]): string;
|
|
50
|
+
/** The version 5 UUID of a name made of parts (`nameOf`) in a namespace. */
|
|
51
|
+
export declare function uuidV5Of(namespace: Uuid, parts: readonly string[]): Promise<Uuid>;
|
|
52
|
+
/** The decoder of a UUID in text (any case, or a `urn:uuid:` URN). */
|
|
53
|
+
export declare const uuidDecoder: Decoder<Uuid>;
|