@intellectual-frontiers/ergonex 0.3.0 → 0.3.2
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/dist/desired.d.ts +1 -1
- package/dist/mod.js +2029 -2461
- package/dist/modules/external.d.ts +1 -1
- package/dist/modules/registry.d.ts +1 -1
- package/dist/modules/types.d.ts +6 -6
- package/dist/plan.d.ts +1 -1
- package/dist/platform/k-args.d.ts +3 -24
- package/dist/render.d.ts +2 -2
- package/dist/state-record.d.ts +2 -2
- package/dist/tools/catalog.d.ts +1 -1
- package/dist/vendor/ts/runtime/http-client.d.ts +1 -1
- package/ergonex.mjs +3484 -3769
- package/package.json +5 -2
- package/dist/vendor/ts/kernel/archive.d.ts +0 -147
- package/dist/vendor/ts/kernel/args.d.ts +0 -240
- package/dist/vendor/ts/kernel/assess.d.ts +0 -247
- package/dist/vendor/ts/kernel/attest.d.ts +0 -164
- package/dist/vendor/ts/kernel/base64.d.ts +0 -24
- package/dist/vendor/ts/kernel/cbor.d.ts +0 -39
- package/dist/vendor/ts/kernel/cms.d.ts +0 -106
- package/dist/vendor/ts/kernel/commands.d.ts +0 -103
- package/dist/vendor/ts/kernel/cose.d.ts +0 -34
- package/dist/vendor/ts/kernel/crypt.d.ts +0 -30
- package/dist/vendor/ts/kernel/csv.d.ts +0 -38
- package/dist/vendor/ts/kernel/der.d.ts +0 -67
- package/dist/vendor/ts/kernel/documentation.d.ts +0 -118
- package/dist/vendor/ts/kernel/dsse.d.ts +0 -137
- package/dist/vendor/ts/kernel/evidence.d.ts +0 -212
- package/dist/vendor/ts/kernel/glob.d.ts +0 -64
- package/dist/vendor/ts/kernel/grc.d.ts +0 -356
- package/dist/vendor/ts/kernel/http.d.ts +0 -46
- package/dist/vendor/ts/kernel/json5.d.ts +0 -46
- package/dist/vendor/ts/kernel/layers.d.ts +0 -35
- package/dist/vendor/ts/kernel/md5.d.ts +0 -19
- package/dist/vendor/ts/kernel/media-types.d.ts +0 -28
- package/dist/vendor/ts/kernel/mod.d.ts +0 -95
- package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +0 -4374
- package/dist/vendor/ts/kernel/ocsf.d.ts +0 -160
- package/dist/vendor/ts/kernel/oscal.d.ts +0 -356
- package/dist/vendor/ts/kernel/otel.d.ts +0 -365
- package/dist/vendor/ts/kernel/otlp.d.ts +0 -83
- package/dist/vendor/ts/kernel/palette.d.ts +0 -44
- package/dist/vendor/ts/kernel/png.d.ts +0 -124
- package/dist/vendor/ts/kernel/rdf-schema.d.ts +0 -190
- package/dist/vendor/ts/kernel/rdf-term.d.ts +0 -162
- package/dist/vendor/ts/kernel/rdf-vocabularies.d.ts +0 -148
- package/dist/vendor/ts/kernel/rdf-write.d.ts +0 -25
- package/dist/vendor/ts/kernel/rdf.d.ts +0 -35
- package/dist/vendor/ts/kernel/render.d.ts +0 -111
- package/dist/vendor/ts/kernel/schedule.d.ts +0 -207
- package/dist/vendor/ts/kernel/semver.d.ts +0 -94
- package/dist/vendor/ts/kernel/sha256.d.ts +0 -29
- package/dist/vendor/ts/kernel/signals.d.ts +0 -371
- package/dist/vendor/ts/kernel/sigv4.d.ts +0 -67
- package/dist/vendor/ts/kernel/test-record.d.ts +0 -222
- package/dist/vendor/ts/kernel/test-report.d.ts +0 -294
- package/dist/vendor/ts/kernel/toml.d.ts +0 -51
- package/dist/vendor/ts/kernel/trace.d.ts +0 -169
- package/dist/vendor/ts/kernel/ts-literal.d.ts +0 -62
- package/dist/vendor/ts/kernel/uuid.d.ts +0 -53
- package/dist/vendor/ts/kernel/vt.d.ts +0 -78
- package/dist/vendor/ts/kernel/webauthn.d.ts +0 -212
- package/dist/vendor/ts/kernel/width.d.ts +0 -63
- package/dist/vendor/ts/kernel/xml.d.ts +0 -73
- package/dist/vendor/ts/kernel/yaml.d.ts +0 -44
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@intellectual-frontiers/ergonex",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.2",
|
|
4
4
|
"description": "Ergonex, the workspaces management of Intellectual Frontiers: one command that sets up, configures and operates a team's software repositories, package registries and builds, on Windows, macOS and Linux, with Bun by default and Node 26 as the backup.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -19,7 +19,10 @@
|
|
|
19
19
|
}
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@intellectual-frontiers/core": "0.1.0"
|
|
22
|
+
"@intellectual-frontiers/core": "0.1.0",
|
|
23
|
+
"@intellectual-frontiers/crypto": "0.1.0",
|
|
24
|
+
"@intellectual-frontiers/formats": "0.1.0",
|
|
25
|
+
"@intellectual-frontiers/terminal": "0.1.0"
|
|
23
26
|
},
|
|
24
27
|
"files": [
|
|
25
28
|
"dist",
|
|
@@ -1,147 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Archives in memory, with no outside package (commons 0005-typescript-runtime FR-010). Writing: a POSIX ustar archive, a gzip stream of
|
|
3
|
-
* stored deflate blocks and a zip of stored entries (`zip`), each entry with a fixed time and mode and in the byte order of its path, so the
|
|
4
|
-
* bytes depend on the files alone (taken from erga's `lib/ts/archive`); and, where size matters more than the same bytes on every runtime,
|
|
5
|
-
* a zip of deflated entries (`zipDeflated`, through the web standard `CompressionStream`), the same bytes for the same files on one runtime
|
|
6
|
-
* and the same files unzipped on every runtime. Reading: a tar (ustar, pax and GNU long names), a gzip and a zip whose
|
|
7
|
-
* entries are stored or deflated (through the web standard `DecompressionStream`), each checked (header checksums, CRC-32) and every path
|
|
8
|
-
* refused that would leave the folder it is unpacked into. This is what lets Stolos drop `fflate` and unpack a verified copy of its engine.
|
|
9
|
-
* A tar, gzipped or not, is also read as a stream (`untarStream`, `readTarStream`), an entry at a time with each entry's bytes a stream of
|
|
10
|
-
* their own, with the same checks, so that an archive larger than memory can be read (FR-059).
|
|
11
|
-
*
|
|
12
|
-
* @example
|
|
13
|
-
* ```ts
|
|
14
|
-
* import { tar, untar, zip, unzip } from "./archive.js";
|
|
15
|
-
* const files = new Map([["a/b.txt", new TextEncoder().encode("hello")]]);
|
|
16
|
-
* const z = zip(files);
|
|
17
|
-
* const back = await unzip(z); // { kind: "ok", value: Map { "a/b.txt" => Uint8Array [104, 101, 108, 108, 111] } }
|
|
18
|
-
* ```
|
|
19
|
-
*
|
|
20
|
-
* @module
|
|
21
|
-
*/
|
|
22
|
-
import { type Result } from "@intellectual-frontiers/core";
|
|
23
|
-
/** The files of an archive, by their path inside it. */
|
|
24
|
-
export type Files = ReadonlyMap<string, Uint8Array>;
|
|
25
|
-
/** Why an archive could not be read or written. */
|
|
26
|
-
export type ArchiveError = {
|
|
27
|
-
readonly kind: "damaged";
|
|
28
|
-
readonly message: string;
|
|
29
|
-
} | {
|
|
30
|
-
readonly kind: "unsupported";
|
|
31
|
-
readonly message: string;
|
|
32
|
-
} | {
|
|
33
|
-
readonly kind: "unsafe-path";
|
|
34
|
-
readonly path: string;
|
|
35
|
-
} | {
|
|
36
|
-
readonly kind: "too-long";
|
|
37
|
-
readonly path: string;
|
|
38
|
-
};
|
|
39
|
-
/** An archive error as one sentence. */
|
|
40
|
-
export declare function formatArchiveError(e: ArchiveError): string;
|
|
41
|
-
/** The CRC-32 (ISO 3309) that gzip and zip both carry. */
|
|
42
|
-
export declare function crc32(bytes: Uint8Array): number;
|
|
43
|
-
/**
|
|
44
|
-
* Whether a path inside an archive stays inside the folder it is unpacked into: relative, with `/` between its parts, no part `..`, no
|
|
45
|
-
* empty part but a trailing one, no backslash, no drive letter and no NUL.
|
|
46
|
-
*/
|
|
47
|
-
export declare function isSafePath(path: string): boolean;
|
|
48
|
-
/** The paths of the files in the byte order of their UTF-8, the order every writer here uses. */
|
|
49
|
-
export declare function sortedPaths(paths: Iterable<string>): readonly string[];
|
|
50
|
-
/** Byte arrays joined end to end. */
|
|
51
|
-
export declare function concat(parts: readonly Uint8Array[]): Uint8Array;
|
|
52
|
-
/** A path too long for the 100 bytes of a ustar name, split into its prefix (up to 155 bytes) and name; undefined where it cannot be. */
|
|
53
|
-
export declare function splitName(path: string): readonly [string, string] | undefined;
|
|
54
|
-
/** One ustar header block of a file (mode 0644) or a folder (0755), owned by user 0, dated 0; undefined where the path does not fit. */
|
|
55
|
-
export declare function tarHeader(path: string, size: number, dir: boolean): Uint8Array | undefined;
|
|
56
|
-
/** A ustar archive of the files, each folder they lie in first given its own entry; or the path that does not fit or is not safe. */
|
|
57
|
-
export declare function tar(files: Files): Result<Uint8Array, ArchiveError>;
|
|
58
|
-
/** A gzip stream (RFC 1952) of the bytes in stored deflate blocks (RFC 1951 §3.2.4), with no name and no time: the same bytes every time. */
|
|
59
|
-
export declare function gzip(data: Uint8Array): Uint8Array;
|
|
60
|
-
/** A date as a zip writes it (MS-DOS): `(year - 1980) << 9 | month << 5 | day`. */
|
|
61
|
-
export declare function dosDate(year: number, month: number, day: number): number;
|
|
62
|
-
/** The zip's fixed date: 1980-01-01, the first a zip can hold. */
|
|
63
|
-
export declare const ZIP_EPOCH: number;
|
|
64
|
-
/** A zip (APPNOTE 6.3) of the files, each stored, dated `date` (1980-01-01 unless another is given) at midnight and readable by everyone. */
|
|
65
|
-
export declare function zip(files: Files, date?: number): Uint8Array;
|
|
66
|
-
/**
|
|
67
|
-
* A zip (APPNOTE 6.3) of the files as `zip` lays them out, but each entry deflated (method 8) through the web standard
|
|
68
|
-
* `CompressionStream("deflate-raw")`, or stored where deflating would not make it smaller (an empty or incompressible file). The bytes
|
|
69
|
-
* depend on the files alone on one runtime; another runtime's deflater may choose other (equally valid) bytes, so only what they unzip to
|
|
70
|
-
* is the same everywhere.
|
|
71
|
-
*/
|
|
72
|
-
export declare function zipDeflated(files: Files, date?: number): Promise<Uint8Array>;
|
|
73
|
-
/** The raw deflate stream (RFC 1951) a web `CompressionStream` gives for the bytes. */
|
|
74
|
-
export declare function deflateRaw(data: Uint8Array): Promise<Uint8Array>;
|
|
75
|
-
/** The bytes of a gzip stream, stored or deflated, its CRC checked by the decompressor. */
|
|
76
|
-
export declare function gunzip(data: Uint8Array): Promise<Result<Uint8Array, ArchiveError>>;
|
|
77
|
-
/** One entry of a tar archive. A folder's path has no trailing `/`; a link's target is in `linkName`. */
|
|
78
|
-
export type TarEntry = {
|
|
79
|
-
readonly path: string;
|
|
80
|
-
readonly kind: "file" | "directory" | "symlink" | "hardlink";
|
|
81
|
-
readonly mode: number;
|
|
82
|
-
readonly data: Uint8Array;
|
|
83
|
-
readonly linkName: string;
|
|
84
|
-
};
|
|
85
|
-
/** The header of one entry of a tar archive: its path (a folder's with no trailing `/`), kind, mode, size of body, time and link target. */
|
|
86
|
-
export type TarHeader = {
|
|
87
|
-
readonly path: string;
|
|
88
|
-
readonly kind: TarEntry["kind"];
|
|
89
|
-
readonly mode: number;
|
|
90
|
-
readonly size: number;
|
|
91
|
-
/** Seconds since 1970, as the header (or a pax `mtime`) gives them. */
|
|
92
|
-
readonly mtime: number;
|
|
93
|
-
readonly linkName: string;
|
|
94
|
-
};
|
|
95
|
-
/** The entries of a tar archive (ustar, with pax extended headers and GNU long names), each header's checksum checked and each path checked safe. */
|
|
96
|
-
export declare function untar(data: Uint8Array): Result<readonly TarEntry[], ArchiveError>;
|
|
97
|
-
/** An archive error raised as an `Error`, which is how a stream reports one: the error itself is in `error`. */
|
|
98
|
-
export declare class ArchiveFailure extends Error {
|
|
99
|
-
/** Why the archive could not be read. */
|
|
100
|
-
readonly error: ArchiveError;
|
|
101
|
-
/** An `Error` for the archive error, its message the error's sentence. */
|
|
102
|
-
constructor(error: ArchiveError);
|
|
103
|
-
}
|
|
104
|
-
/**
|
|
105
|
-
* One entry of a tar archive read as a stream: its header and its body as a stream (empty but for a file). The body MUST be read to its
|
|
106
|
-
* end or cancelled before the next entry is given, as with `@std/tar`'s `UntarStream`.
|
|
107
|
-
*/
|
|
108
|
-
export type TarStreamEntry = TarHeader & {
|
|
109
|
-
readonly readable: ReadableStream<Uint8Array>;
|
|
110
|
-
};
|
|
111
|
-
/**
|
|
112
|
-
* The entries of a tar archive given as a stream of bytes, gzipped or not (told by its first two bytes), one at a time as they are asked
|
|
113
|
-
* for, so that an archive larger than memory is read with one chunk held (commons 0005-typescript-runtime FR-059). Every header is checked
|
|
114
|
-
* as `untar` checks it (checksum, pax and GNU long names, a safe path); a failure errors the stream with an `ArchiveFailure`. Each entry's
|
|
115
|
-
* `readable` MUST be read to its end or cancelled before the next entry is given; cancelling the stream of entries cancels the bytes.
|
|
116
|
-
*/
|
|
117
|
-
export declare function readTarStream(stream: ReadableStream<Uint8Array>): ReadableStream<TarStreamEntry>;
|
|
118
|
-
/**
|
|
119
|
-
* A stream from a tar archive's bytes, gzipped or not, to its entries, to put in a `pipeThrough` as `@std/tar`'s `UntarStream` is: see
|
|
120
|
-
* `readTarStream` for what it checks and how each entry's body is read (commons 0005-typescript-runtime FR-059).
|
|
121
|
-
*
|
|
122
|
-
* @example
|
|
123
|
-
* ```ts
|
|
124
|
-
* for await (const entry of file.readable.pipeThrough(untarStream())) {
|
|
125
|
-
* if (entry.path === "bin/tool") await save(entry.readable);
|
|
126
|
-
* else await entry.readable.cancel();
|
|
127
|
-
* }
|
|
128
|
-
* ```
|
|
129
|
-
*/
|
|
130
|
-
export declare function untarStream(): ReadableWritablePair<TarStreamEntry, Uint8Array>;
|
|
131
|
-
/** The files of a list of tar entries, by path: folders and links left out. */
|
|
132
|
-
export declare function filesOf(entries: readonly TarEntry[]): Files;
|
|
133
|
-
/** One entry of a zip's central directory. */
|
|
134
|
-
export type ZipEntry = {
|
|
135
|
-
readonly name: string;
|
|
136
|
-
readonly method: number;
|
|
137
|
-
readonly crc: number;
|
|
138
|
-
readonly compressed: number;
|
|
139
|
-
readonly size: number;
|
|
140
|
-
readonly offset: number;
|
|
141
|
-
};
|
|
142
|
-
/** The entries of a zip, from its central directory; or why they cannot be read (a ZIP64 archive among the reasons). */
|
|
143
|
-
export declare function zipEntries(data: Uint8Array): Result<readonly ZipEntry[], ArchiveError>;
|
|
144
|
-
/** The bytes of one entry of a zip, stored (method 0) or deflated (method 8), its size and CRC-32 checked. */
|
|
145
|
-
export declare function zipRead(data: Uint8Array, e: ZipEntry): Promise<Result<Uint8Array, ArchiveError>>;
|
|
146
|
-
/** Every file of a zip by its path, folders left out, each read and checked, and every path checked safe. */
|
|
147
|
-
export declare function unzip(data: Uint8Array): Promise<Result<Files, ArchiveError>>;
|
|
@@ -1,240 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* A typed command-line parser (commons 0005-typescript-runtime FR-047): a command's options are declared once as data (`flag`, `value`,
|
|
3
|
-
* `many`), the type of what `parseArgs` gives is inferred from that declaration, and a command line that does not fit is a `UsageError`,
|
|
4
|
-
* a union told apart by `kind` that `formatUsageError` says in one sentence; `helpText` writes the help from the same declaration. It
|
|
5
|
-
* unifies the parsers of two harnesses: erga's `@erga/agent` `args.ts` (declared options, an undeclared option refused with a "did you mean", help that
|
|
6
|
-
* wins over everything and runs nothing: erga 247-ergactl FR-006 and FR-007) and Stolos's `parseArgs` (short letters, required options, defaults, repeatable options). It is pure: the
|
|
7
|
-
* caller passes the words, `proc.args` from `runtime/proc.ts`.
|
|
8
|
-
*
|
|
9
|
-
* The grammar: `--name VALUE` and `--name=VALUE`; `-x VALUE`; bundled short flags `-abc`, whose last letter may take the next word as its
|
|
10
|
-
* value; `--no-name` for a flag declared `negatable`; `--` ends the options, and the words after it are kept apart as `rest`; `-` and a
|
|
11
|
-
* word such as `-5` are arguments, since no option is a digit. A short option's value is never attached (`-ofile`, `-o=file`), which other
|
|
12
|
-
* parsers read differently. A value-taking option takes the next word whatever it is, as getopt does. Every option is given at most once
|
|
13
|
-
* (a `many` option as often as wanted): a second value would otherwise silently replace the first. `--help`, or a short word with the
|
|
14
|
-
* letter `h`, anywhere before `--` asks for help, which wins over every other word and every error, so `-h` and the name `help` are
|
|
15
|
-
* reserved.
|
|
16
|
-
*
|
|
17
|
-
* @example
|
|
18
|
-
* ```ts
|
|
19
|
-
* import { flag, integerText, many, parseArgs, value } from "./args.js";
|
|
20
|
-
* const spec = {
|
|
21
|
-
* verbose: flag({ short: "v", help: "Say more." }),
|
|
22
|
-
* out: value({ short: "o", help: "Where to write.", valueName: "FILE" }),
|
|
23
|
-
* tag: many({ help: "A tag." }),
|
|
24
|
-
* jobs: value({ help: "How many at once.", parse: integerText, default: 4 }),
|
|
25
|
-
* };
|
|
26
|
-
* parseArgs(["-v", "--tag", "a", "--tag=b", "--jobs", "8", "--", "x"], spec);
|
|
27
|
-
* // { kind: "ok", value: { kind: "args", options: { verbose: true, out: undefined, tag: ["a", "b"], jobs: 8 }, positionals: [], rest: ["x"] } }
|
|
28
|
-
* ```
|
|
29
|
-
*
|
|
30
|
-
* @module
|
|
31
|
-
*/
|
|
32
|
-
import { type Result } from "@intellectual-frontiers/core";
|
|
33
|
-
import type { DecodeError } from "@intellectual-frontiers/core";
|
|
34
|
-
/** A short option's letter: any ASCII letter but `h`, which is help's. */
|
|
35
|
-
export type ShortName = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z";
|
|
36
|
-
/** What turns an option's text into its value: a function of the text, or any of the kernel's decoders (`./decode.ts`), which take it as `unknown`. */
|
|
37
|
-
export type Parser<T> = (text: string) => Result<T, string | DecodeError>;
|
|
38
|
-
/** What an option is when the command line does not give it: nothing (`undefined`), a usage error, or a default. */
|
|
39
|
-
export type Presence = "none" | "required" | "default";
|
|
40
|
-
/** The fallback of an option of presence `P`: the default's value is kept with it. */
|
|
41
|
-
export type Fallback<T, P extends Presence> = P extends "none" ? {
|
|
42
|
-
readonly kind: "none";
|
|
43
|
-
} : P extends "required" ? {
|
|
44
|
-
readonly kind: "required";
|
|
45
|
-
} : {
|
|
46
|
-
readonly kind: "default";
|
|
47
|
-
readonly value: T;
|
|
48
|
-
};
|
|
49
|
-
/** A switch that takes no value: `true` when given, `false` with `--no-name` where it is negatable, else its fallback. */
|
|
50
|
-
export type FlagOption<P extends "none" | "default" = "none" | "default", L extends ShortName = ShortName> = {
|
|
51
|
-
readonly kind: "flag";
|
|
52
|
-
readonly short: L | undefined;
|
|
53
|
-
readonly help: string;
|
|
54
|
-
readonly negatable: boolean;
|
|
55
|
-
readonly fallback: Fallback<boolean, P>;
|
|
56
|
-
};
|
|
57
|
-
/** An option given at most once with one value, parsed into a `T`. */
|
|
58
|
-
export type ValueOption<T, P extends Presence = Presence, L extends ShortName = ShortName> = {
|
|
59
|
-
readonly kind: "value";
|
|
60
|
-
readonly short: L | undefined;
|
|
61
|
-
readonly help: string;
|
|
62
|
-
readonly valueName: string;
|
|
63
|
-
readonly parse: Parser<T>;
|
|
64
|
-
readonly fallback: Fallback<T, P>;
|
|
65
|
-
};
|
|
66
|
-
/** An option given any number of times, each value parsed into a `T`, kept in the order given. */
|
|
67
|
-
export type ManyOption<T, L extends ShortName = ShortName> = {
|
|
68
|
-
readonly kind: "many";
|
|
69
|
-
readonly short: L | undefined;
|
|
70
|
-
readonly help: string;
|
|
71
|
-
readonly valueName: string;
|
|
72
|
-
readonly parse: Parser<T>;
|
|
73
|
-
};
|
|
74
|
-
/** One declared option. */
|
|
75
|
-
export type Option = FlagOption | ValueOption<unknown> | ManyOption<unknown>;
|
|
76
|
-
/** A command's options, by name: the key `dryRun` is the option `--dry-run`. */
|
|
77
|
-
export type Spec = {
|
|
78
|
-
readonly [name: string]: Option;
|
|
79
|
-
};
|
|
80
|
-
/** The value an option gives, as its declaration says. */
|
|
81
|
-
export type OptionValue<O> = O extends {
|
|
82
|
-
readonly kind: "flag";
|
|
83
|
-
readonly fallback: infer F;
|
|
84
|
-
} ? [F] extends [{
|
|
85
|
-
readonly kind: "none";
|
|
86
|
-
}] ? boolean | undefined : boolean : O extends {
|
|
87
|
-
readonly kind: "many";
|
|
88
|
-
readonly parse: Parser<infer T>;
|
|
89
|
-
} ? readonly T[] : O extends {
|
|
90
|
-
readonly kind: "value";
|
|
91
|
-
readonly parse: Parser<infer T>;
|
|
92
|
-
readonly fallback: infer F;
|
|
93
|
-
} ? [F] extends [{
|
|
94
|
-
readonly kind: "none";
|
|
95
|
-
}] ? T | undefined : T : never;
|
|
96
|
-
/** The values of a spec's options, by the same names. */
|
|
97
|
-
export type OptionValues<S extends Spec> = {
|
|
98
|
-
readonly [K in keyof S]: OptionValue<S[K]>;
|
|
99
|
-
};
|
|
100
|
-
/** The short letter an option declares, if any. */
|
|
101
|
-
type ShortOf<O> = O extends {
|
|
102
|
-
readonly short: infer L;
|
|
103
|
-
} ? Exclude<L, undefined> : never;
|
|
104
|
-
/** The short letters that two options of a spec declare. */
|
|
105
|
-
type RepeatedShorts<S> = {
|
|
106
|
-
[K in keyof S]: ShortOf<S[K]> & ShortOf<S[Exclude<keyof S, K>]>;
|
|
107
|
-
}[keyof S];
|
|
108
|
-
/**
|
|
109
|
-
* `unknown` where a spec is well formed, else a type naming what is wrong, which the spec then does not satisfy: a short letter declared
|
|
110
|
-
* twice, a name written with a dash (names are camelCase keys), or the name `help`, which is reserved.
|
|
111
|
-
*/
|
|
112
|
-
export type SpecCheck<S> = [RepeatedShorts<S>] extends [never] ? [Extract<keyof S, `${string}-${string}`>] extends [never] ? ["help"] extends [keyof S] ? {
|
|
113
|
-
readonly "help is reserved": never;
|
|
114
|
-
} : unknown : {
|
|
115
|
-
readonly "option names are camelCase keys": Extract<keyof S, `${string}-${string}`>;
|
|
116
|
-
} : {
|
|
117
|
-
readonly "a short letter is declared twice": RepeatedShorts<S>;
|
|
118
|
-
};
|
|
119
|
-
/** A word, or words, that a command takes after its options: exactly one, at most one, or any number. */
|
|
120
|
-
export type Operand = {
|
|
121
|
-
readonly name: string;
|
|
122
|
-
readonly help: string;
|
|
123
|
-
readonly arity: "one" | "optional" | "many";
|
|
124
|
-
};
|
|
125
|
-
/** A command line that fits its spec: the options' values, the arguments, and the words after `--`. */
|
|
126
|
-
export type Args<S extends Spec> = {
|
|
127
|
-
readonly kind: "args";
|
|
128
|
-
readonly options: OptionValues<S>;
|
|
129
|
-
readonly positionals: readonly string[];
|
|
130
|
-
readonly rest: readonly string[];
|
|
131
|
-
};
|
|
132
|
-
/** What a command line asks: help, which runs nothing else (erga 247-ergactl FR-006), or the command with its arguments. */
|
|
133
|
-
export type Parsed<S extends Spec> = {
|
|
134
|
-
readonly kind: "help";
|
|
135
|
-
} | Args<S>;
|
|
136
|
-
/** Why a command line does not fit its spec. `option` is the option as it was written, or its long name where it was given twice or not at all. */
|
|
137
|
-
export type UsageError = {
|
|
138
|
-
readonly kind: "unknown-option";
|
|
139
|
-
readonly option: string;
|
|
140
|
-
readonly suggestion: string | undefined;
|
|
141
|
-
} | {
|
|
142
|
-
readonly kind: "missing-value";
|
|
143
|
-
readonly option: string;
|
|
144
|
-
} | {
|
|
145
|
-
readonly kind: "unexpected-value";
|
|
146
|
-
readonly option: string;
|
|
147
|
-
readonly value: string;
|
|
148
|
-
} | {
|
|
149
|
-
readonly kind: "attached-value";
|
|
150
|
-
readonly option: string;
|
|
151
|
-
readonly word: string;
|
|
152
|
-
} | {
|
|
153
|
-
readonly kind: "invalid-value";
|
|
154
|
-
readonly option: string;
|
|
155
|
-
readonly value: string;
|
|
156
|
-
readonly reason: string;
|
|
157
|
-
} | {
|
|
158
|
-
readonly kind: "repeated-option";
|
|
159
|
-
readonly option: string;
|
|
160
|
-
} | {
|
|
161
|
-
readonly kind: "missing-option";
|
|
162
|
-
readonly option: string;
|
|
163
|
-
} | {
|
|
164
|
-
readonly kind: "missing-argument";
|
|
165
|
-
readonly argument: string;
|
|
166
|
-
} | {
|
|
167
|
-
readonly kind: "unexpected-argument";
|
|
168
|
-
readonly argument: string;
|
|
169
|
-
readonly takes: readonly string[];
|
|
170
|
-
};
|
|
171
|
-
/** The fields every option declares. */
|
|
172
|
-
type Common<L extends ShortName> = {
|
|
173
|
-
readonly short?: L;
|
|
174
|
-
readonly help: string;
|
|
175
|
-
};
|
|
176
|
-
/** The fields an option with a value declares: the name of its value in the help, `VALUE` by default. */
|
|
177
|
-
type Valued<L extends ShortName> = Common<L> & {
|
|
178
|
-
readonly valueName?: string;
|
|
179
|
-
};
|
|
180
|
-
/** A flag: `false` when not given; with `negatable`, `--no-name` gives `false` and an absent flag gives `undefined`, or the `default`. */
|
|
181
|
-
export declare function flag<L extends ShortName = never>(o: Common<L> & {
|
|
182
|
-
readonly negatable: true;
|
|
183
|
-
readonly default: boolean;
|
|
184
|
-
}): FlagOption<"default", L>;
|
|
185
|
-
/** A negatable flag with no default. */
|
|
186
|
-
export declare function flag<L extends ShortName = never>(o: Common<L> & {
|
|
187
|
-
readonly negatable: true;
|
|
188
|
-
}): FlagOption<"none", L>;
|
|
189
|
-
/** A flag that cannot be negated. */
|
|
190
|
-
export declare function flag<L extends ShortName = never>(o: Common<L>): FlagOption<"default", L>;
|
|
191
|
-
/** An option with one value, parsed by `parse`, that must be given. */
|
|
192
|
-
export declare function value<T, L extends ShortName = never>(o: Valued<L> & {
|
|
193
|
-
readonly parse: Parser<T>;
|
|
194
|
-
readonly required: true;
|
|
195
|
-
}): ValueOption<T, "required", L>;
|
|
196
|
-
/** An option with one value, parsed by `parse`, and a default. */
|
|
197
|
-
export declare function value<T, L extends ShortName = never>(o: Valued<L> & {
|
|
198
|
-
readonly parse: Parser<T>;
|
|
199
|
-
readonly default: NoInfer<T>;
|
|
200
|
-
}): ValueOption<T, "default", L>;
|
|
201
|
-
/** An option with one value, parsed by `parse`, `undefined` when not given. */
|
|
202
|
-
export declare function value<T, L extends ShortName = never>(o: Valued<L> & {
|
|
203
|
-
readonly parse: Parser<T>;
|
|
204
|
-
}): ValueOption<T, "none", L>;
|
|
205
|
-
/** An option with one text value that must be given. */
|
|
206
|
-
export declare function value<L extends ShortName = never>(o: Valued<L> & {
|
|
207
|
-
readonly required: true;
|
|
208
|
-
}): ValueOption<string, "required", L>;
|
|
209
|
-
/** An option with one text value and a default. */
|
|
210
|
-
export declare function value<L extends ShortName = never>(o: Valued<L> & {
|
|
211
|
-
readonly default: string;
|
|
212
|
-
}): ValueOption<string, "default", L>;
|
|
213
|
-
/** An option with one text value, `undefined` when not given. */
|
|
214
|
-
export declare function value<L extends ShortName = never>(o: Valued<L>): ValueOption<string, "none", L>;
|
|
215
|
-
/** An option given any number of times, each value parsed by `parse`. */
|
|
216
|
-
export declare function many<T, L extends ShortName = never>(o: Valued<L> & {
|
|
217
|
-
readonly parse: Parser<T>;
|
|
218
|
-
}): ManyOption<T, L>;
|
|
219
|
-
/** An option given any number of times, each value its text. */
|
|
220
|
-
export declare function many<L extends ShortName = never>(o: Valued<L>): ManyOption<string, L>;
|
|
221
|
-
/** A parser of an integer written in decimal, with an optional `-`, within the safe integers. */
|
|
222
|
-
export declare function integerText(t: string): Result<number, string>;
|
|
223
|
-
/** The long option of a spec's key: `dryRun` is `--dry-run`. */
|
|
224
|
-
export declare function longName(key: string): string;
|
|
225
|
-
/** The number of insertions, deletions and substitutions that turn `a` into `b` (Levenshtein). */
|
|
226
|
-
export declare function editDistance(a: string, b: string): number;
|
|
227
|
-
/** The candidate nearest `word` by edit distance, the first of equals, if it is within two edits or half the word's length; else nothing. */
|
|
228
|
-
export declare function suggest(word: string, candidates: readonly string[]): string | undefined;
|
|
229
|
-
/**
|
|
230
|
-
* Parses `argv` against `spec`, and the arguments against `operands` (none by default): help where it is asked for, else every option's
|
|
231
|
-
* value with the arguments and the words after `--`, or the first thing that does not fit.
|
|
232
|
-
*/
|
|
233
|
-
export declare function parseArgs<S extends Spec>(argv: readonly string[], spec: S & SpecCheck<S>, operands?: readonly Operand[]): Result<Parsed<S>, UsageError>;
|
|
234
|
-
/** A usage error as one sentence; `command` names the command (`ergactl toolchain list`), "this command" by default. */
|
|
235
|
-
export declare function formatUsageError(e: UsageError, command?: string): string;
|
|
236
|
-
/** The help of a command: its summary, its usage, its options aligned with their defaults, and its arguments. */
|
|
237
|
-
export declare function helpText<S extends Spec>(program: string, summary: string, spec: S & SpecCheck<S>, operands?: readonly Operand[]): string;
|
|
238
|
-
/** The help of a command whose spec was checked where it was declared (a verb of `./commands.ts`), as `helpText` gives it. */
|
|
239
|
-
export declare function helpOf(program: string, summary: string, spec: Spec, operands?: readonly Operand[]): string;
|
|
240
|
-
export {};
|
|
@@ -1,247 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Assessment: what findings, evidence and declarations add up to (commons 0007-grc FR-010 to FR-015). Every function is pure and takes the
|
|
3
|
-
* instant it judges at as a value.
|
|
4
|
-
*
|
|
5
|
-
* - **Coverage** rolls each catalog control (a requirement) or control up as `gap`, `untested`, `partial`, `addressed` or `covered` (FR-010).
|
|
6
|
-
* - **Freshness** holds the newest evidence to a cadence (an ISO 8601 duration): `fresh`, `due` within the last tenth of the cadence, or
|
|
7
|
-
* `stale`, with the instant it falls due (FR-011).
|
|
8
|
-
* - **Drift** compares a declared and an observed view of keyed records: added, removed and changed, each change with its field's path
|
|
9
|
-
* and both values, in key order (FR-012).
|
|
10
|
-
* - The **change-impact gate** reads declarations of paths (globs) to controls and judges a change `allowed` or `blocked`, with every
|
|
11
|
-
* reason (FR-013).
|
|
12
|
-
* - The **risk register** levels each risk by NIST SP 800-30 Rev. 1's Table I-2 and reports those past their review (FR-014).
|
|
13
|
-
* - The **trace** relates each requirement to the mechanisms that enforce it and the evidence they gave, and names those with none (FR-015).
|
|
14
|
-
*
|
|
15
|
-
* @example
|
|
16
|
-
* ```ts
|
|
17
|
-
* import { riskLevel } from "./assess.js";
|
|
18
|
-
* riskLevel("moderate", "very-high"); // "high"
|
|
19
|
-
* ```
|
|
20
|
-
*
|
|
21
|
-
* @module
|
|
22
|
-
*/
|
|
23
|
-
import { type Decoder } from "@intellectual-frontiers/core";
|
|
24
|
-
import { type Catalog, type CatalogControl, type ControlRef, type Duration, type Finding, type Instant, type Outcome, type Role } from "./grc.js";
|
|
25
|
-
import type { Json } from "./json5.js";
|
|
26
|
-
import type { Sha256 } from "./sha256.js";
|
|
27
|
-
/** The findings of the newest assessment of each control and subject: for each, those with the latest `at`. */
|
|
28
|
-
export declare function newestFindings(findings: readonly Finding[]): readonly Finding[];
|
|
29
|
-
/** How well a requirement or control is met, from the worst to the best. */
|
|
30
|
-
export type CoverageStatus = "gap" | "untested" | "partial" | "addressed" | "covered";
|
|
31
|
-
/**
|
|
32
|
-
* The coverage that subjects' outcomes give, `not-applicable` ones left out: `untested` where none is left, `partial` where one is
|
|
33
|
-
* neither passing nor accepted, `addressed` where every one passes or is accepted and at least one is accepted, `covered` where every one
|
|
34
|
-
* passes.
|
|
35
|
-
*/
|
|
36
|
-
export declare function coverageOf(outcomes: readonly Outcome[]): Exclude<CoverageStatus, "gap">;
|
|
37
|
-
/** A control's coverage from the newest findings of it. */
|
|
38
|
-
export type ControlCoverage = {
|
|
39
|
-
readonly control: string;
|
|
40
|
-
readonly status: Exclude<CoverageStatus, "gap">;
|
|
41
|
-
readonly outcome: Outcome;
|
|
42
|
-
};
|
|
43
|
-
/** Each control's coverage, in the order given, from the newest findings of each control and subject. */
|
|
44
|
-
export declare function controlCoverage(controls: readonly {
|
|
45
|
-
readonly id: string;
|
|
46
|
-
}[], findings: readonly Finding[]): readonly ControlCoverage[];
|
|
47
|
-
/** A requirement's coverage: the catalog control, the controls that implement it, and how well they meet it. */
|
|
48
|
-
export type RequirementCoverage<C extends string = string, I extends string = string> = {
|
|
49
|
-
readonly requirement: ControlRef<C, I>;
|
|
50
|
-
readonly status: CoverageStatus;
|
|
51
|
-
readonly outcome: Outcome;
|
|
52
|
-
readonly controls: readonly string[];
|
|
53
|
-
};
|
|
54
|
-
/**
|
|
55
|
-
* Every control of a catalog as a requirement, in the catalog's order: `gap` where no control implements it, else the coverage of the
|
|
56
|
-
* newest findings of every control that does (`untested` where there are none).
|
|
57
|
-
*/
|
|
58
|
-
export declare function requirementCoverage<C extends string, E extends CatalogControl>(catalog: Catalog<C, E>, controls: readonly {
|
|
59
|
-
readonly id: string;
|
|
60
|
-
readonly implements: readonly ControlRef[];
|
|
61
|
-
}[], findings: readonly Finding[]): readonly RequirementCoverage<C, E["id"]>[];
|
|
62
|
-
/** Whether evidence is recent enough for its cadence. */
|
|
63
|
-
export type FreshnessStatus = "fresh" | "due" | "stale";
|
|
64
|
-
/** How fresh evidence is: its status, the newest evidence, when it falls due (`null` past the year 9999) and when the `due` window opens. */
|
|
65
|
-
export type Freshness = {
|
|
66
|
-
readonly status: FreshnessStatus;
|
|
67
|
-
readonly cadence: string;
|
|
68
|
-
readonly newest: Instant | null;
|
|
69
|
-
readonly dueAt: Instant | null;
|
|
70
|
-
readonly dueFrom: Instant | null;
|
|
71
|
-
};
|
|
72
|
-
/**
|
|
73
|
-
* The freshness at `at` of evidence observed at the given instants, held to a cadence: it falls due one cadence after the newest; it is
|
|
74
|
-
* `stale` after that instant, `due` in the last tenth of the cadence up to and at it, `fresh` before. No evidence at all is `stale`, due at `at`.
|
|
75
|
-
*/
|
|
76
|
-
export declare function freshness(cadence: Duration, evidence: readonly Instant[], at: Instant): Freshness;
|
|
77
|
-
/** The freshness of each control's newest finding, held to the control's cadence, in the order given. */
|
|
78
|
-
export declare function controlFreshness(controls: readonly {
|
|
79
|
-
readonly id: string;
|
|
80
|
-
readonly cadence: Duration;
|
|
81
|
-
}[], findings: readonly Finding[], at: Instant): readonly {
|
|
82
|
-
readonly control: string;
|
|
83
|
-
readonly freshness: Freshness;
|
|
84
|
-
}[];
|
|
85
|
-
/** One step of a field's path: a member name or an array index. */
|
|
86
|
-
export type PathStep = string | number;
|
|
87
|
-
/** A field that differs: its path inside the record, and its value on each side (absent where that side does not have it). */
|
|
88
|
-
export type FieldChange = {
|
|
89
|
-
readonly path: readonly PathStep[];
|
|
90
|
-
readonly field: string;
|
|
91
|
-
readonly declared?: Json;
|
|
92
|
-
readonly observed?: Json;
|
|
93
|
-
};
|
|
94
|
-
/** What differs between a declared and an observed view of keyed records, each list in key order. */
|
|
95
|
-
export type Drift = {
|
|
96
|
-
readonly added: readonly {
|
|
97
|
-
readonly key: string;
|
|
98
|
-
readonly value: Json;
|
|
99
|
-
}[];
|
|
100
|
-
readonly removed: readonly {
|
|
101
|
-
readonly key: string;
|
|
102
|
-
readonly value: Json;
|
|
103
|
-
}[];
|
|
104
|
-
readonly changed: readonly {
|
|
105
|
-
readonly key: string;
|
|
106
|
-
readonly changes: readonly FieldChange[];
|
|
107
|
-
}[];
|
|
108
|
-
};
|
|
109
|
-
/** Keyed records: a map, or an object whose members are the records. */
|
|
110
|
-
export type KeyedView = ReadonlyMap<string, Json> | {
|
|
111
|
-
readonly [key: string]: Json;
|
|
112
|
-
};
|
|
113
|
-
/** A field's path as text, `$` for the record itself: `$.ports[0]`, `$["a b"]`. */
|
|
114
|
-
export declare function formatFieldPath(path: readonly PathStep[]): string;
|
|
115
|
-
/** The field changes between two values: objects compared member by member in key order, arrays index by index, anything else whole. */
|
|
116
|
-
export declare function fieldChanges(declared: Json, observed: Json): readonly FieldChange[];
|
|
117
|
-
/** The drift from what is declared to what is observed: records only observed are added, only declared removed, in both but different changed. */
|
|
118
|
-
export declare function drift(declared: KeyedView, observed: KeyedView): Drift;
|
|
119
|
-
/** Paths (globs) and the controls a change to them bears on. */
|
|
120
|
-
export type ImpactDeclaration = {
|
|
121
|
-
readonly paths: readonly string[];
|
|
122
|
-
readonly controls: readonly string[];
|
|
123
|
-
};
|
|
124
|
-
/** A change: the paths it touches, the reviews it says it needs (by role) and the reviews given. */
|
|
125
|
-
export type Change = {
|
|
126
|
-
readonly paths: readonly string[];
|
|
127
|
-
readonly needsReview?: readonly Role[];
|
|
128
|
-
readonly reviewedBy?: readonly Role[];
|
|
129
|
-
};
|
|
130
|
-
/** The outcomes that block a change to the paths of a control. */
|
|
131
|
-
export type BlockingOutcome = "fail" | "error" | "gap";
|
|
132
|
-
/** Why a change is blocked. */
|
|
133
|
-
export type GateReason = {
|
|
134
|
-
readonly kind: "control";
|
|
135
|
-
readonly control: string;
|
|
136
|
-
readonly outcome: BlockingOutcome;
|
|
137
|
-
readonly paths: readonly string[];
|
|
138
|
-
} | {
|
|
139
|
-
readonly kind: "review";
|
|
140
|
-
readonly role: Role;
|
|
141
|
-
};
|
|
142
|
-
/** A control a change bears on, and the touched paths declared for it. */
|
|
143
|
-
export type Touched = {
|
|
144
|
-
readonly control: string;
|
|
145
|
-
readonly paths: readonly string[];
|
|
146
|
-
};
|
|
147
|
-
/** The gate's judgement of a change, with every control it touches; where blocked, every reason. */
|
|
148
|
-
export type GateDecision = {
|
|
149
|
-
readonly kind: "allowed";
|
|
150
|
-
readonly touched: readonly Touched[];
|
|
151
|
-
} | {
|
|
152
|
-
readonly kind: "blocked";
|
|
153
|
-
readonly touched: readonly Touched[];
|
|
154
|
-
readonly reasons: readonly [GateReason, ...GateReason[]];
|
|
155
|
-
};
|
|
156
|
-
/** A gate reason as one sentence. */
|
|
157
|
-
export declare function formatGateReason(r: GateReason): string;
|
|
158
|
-
/** Each control's newest outcome: the join of its newest findings' outcomes. */
|
|
159
|
-
export declare function newestOutcomes(findings: readonly Finding[]): ReadonlyMap<string, Outcome>;
|
|
160
|
-
/**
|
|
161
|
-
* A change judged against the declarations and each control's newest outcome: `blocked` where a touched path is declared for a control
|
|
162
|
-
* whose outcome is `fail`, `error` or `gap` (a control with no outcome does not block), or where a review the change needs was not given;
|
|
163
|
-
* else `allowed`. Reasons: controls in id order, then reviews in role order.
|
|
164
|
-
*/
|
|
165
|
-
export declare function gate(declarations: readonly ImpactDeclaration[], change: Change, outcomes: ReadonlyMap<string, Outcome>): GateDecision;
|
|
166
|
-
/** An impact declaration as a file holds it. */
|
|
167
|
-
export declare const impactDeclarationDecoder: Decoder<ImpactDeclaration>;
|
|
168
|
-
/** NIST SP 800-30's five qualitative levels, from the least to the greatest. */
|
|
169
|
-
export declare const RISK_LEVELS: readonly ["very-low", "low", "moderate", "high", "very-high"];
|
|
170
|
-
/** A qualitative level of likelihood, impact or risk (NIST SP 800-30 Rev. 1, Appendices G to I). */
|
|
171
|
-
export type RiskLevel = (typeof RISK_LEVELS)[number];
|
|
172
|
-
/**
|
|
173
|
-
* NIST SP 800-30 Rev. 1, Table I-2, "Assessment scale – level of risk (combination of likelihood and impact)": the level of risk for a
|
|
174
|
-
* likelihood (the row) and an impact (the column).
|
|
175
|
-
*/
|
|
176
|
-
export declare const RISK_MATRIX: Readonly<Record<RiskLevel, Readonly<Record<RiskLevel, RiskLevel>>>>;
|
|
177
|
-
/** The level of risk of a likelihood and an impact, by Table I-2. */
|
|
178
|
-
export declare function riskLevel(likelihood: RiskLevel, impact: RiskLevel): RiskLevel;
|
|
179
|
-
/** What is done about a risk. */
|
|
180
|
-
export type Treatment = "accept" | "mitigate" | "transfer" | "avoid";
|
|
181
|
-
/** A risk as it is written: the level is computed. */
|
|
182
|
-
export type RiskInput = {
|
|
183
|
-
readonly id: string;
|
|
184
|
-
readonly title: string;
|
|
185
|
-
readonly description?: string;
|
|
186
|
-
readonly likelihood: RiskLevel;
|
|
187
|
-
readonly impact: RiskLevel;
|
|
188
|
-
readonly treatment: Treatment;
|
|
189
|
-
readonly owner: Role;
|
|
190
|
-
readonly reviewBy: Instant;
|
|
191
|
-
readonly controls?: readonly string[];
|
|
192
|
-
};
|
|
193
|
-
/** A risk with its level. */
|
|
194
|
-
export type Risk = RiskInput & {
|
|
195
|
-
readonly level: RiskLevel;
|
|
196
|
-
};
|
|
197
|
-
/** A risk past its review date at the instant the register was taken. */
|
|
198
|
-
export type OverdueReview = {
|
|
199
|
-
readonly risk: string;
|
|
200
|
-
readonly owner: Role;
|
|
201
|
-
readonly reviewBy: Instant;
|
|
202
|
-
};
|
|
203
|
-
/** A register: its risks from the greatest level to the least (then by id), and those past their review. */
|
|
204
|
-
export type RiskRegister = {
|
|
205
|
-
readonly at: Instant;
|
|
206
|
-
readonly risks: readonly Risk[];
|
|
207
|
-
readonly overdue: readonly OverdueReview[];
|
|
208
|
-
};
|
|
209
|
-
/** A risk with its level computed. */
|
|
210
|
-
export declare function defineRisk(r: RiskInput): Risk;
|
|
211
|
-
/** The register of some risks at an instant: each levelled, and each whose review date is before the instant reported overdue. */
|
|
212
|
-
export declare function riskRegister(risks: readonly RiskInput[], at: Instant): RiskRegister;
|
|
213
|
-
/** A risk as a file holds it. */
|
|
214
|
-
export declare const riskDecoder: Decoder<RiskInput>;
|
|
215
|
-
/** What enforces requirements: a control, a policy, a process, named by its id. */
|
|
216
|
-
export type Mechanism<R extends string = string> = {
|
|
217
|
-
readonly id: string;
|
|
218
|
-
readonly enforces: readonly R[];
|
|
219
|
-
};
|
|
220
|
-
/** A piece of evidence a mechanism gave. */
|
|
221
|
-
export type EvidenceLink = {
|
|
222
|
-
readonly mechanism: string;
|
|
223
|
-
readonly digest: Sha256;
|
|
224
|
-
};
|
|
225
|
-
/** Why a requirement is unproven: no mechanism enforces it, or none that does gave evidence. */
|
|
226
|
-
export type Unproven = "unenforced" | "unevidenced";
|
|
227
|
-
/** One requirement's trace: each mechanism that enforces it with the evidence it gave (digests in order, once each). */
|
|
228
|
-
export type RequirementTrace<R extends string = string> = {
|
|
229
|
-
readonly requirement: R;
|
|
230
|
-
readonly status: "proven" | Unproven;
|
|
231
|
-
readonly mechanisms: readonly {
|
|
232
|
-
readonly id: string;
|
|
233
|
-
readonly evidence: readonly Sha256[];
|
|
234
|
-
}[];
|
|
235
|
-
};
|
|
236
|
-
/** Every requirement's trace in the order given, and those unproven. */
|
|
237
|
-
export type Trace<R extends string = string> = {
|
|
238
|
-
readonly requirements: readonly RequirementTrace<R>[];
|
|
239
|
-
readonly unproven: readonly {
|
|
240
|
-
readonly requirement: R;
|
|
241
|
-
readonly reason: Unproven;
|
|
242
|
-
}[];
|
|
243
|
-
};
|
|
244
|
-
/** The trace of requirements to mechanisms to evidence; a requirement is proven where a mechanism that enforces it gave evidence. */
|
|
245
|
-
export declare function trace<const R extends string>(requirements: readonly R[], mechanisms: readonly Mechanism<NoInfer<R>>[], evidence: readonly EvidenceLink[]): Trace<R>;
|
|
246
|
-
/** The evidence that findings carry, as links from their controls (the mechanisms) to the digests. */
|
|
247
|
-
export declare function evidenceOfFindings(findings: readonly Finding[]): readonly EvidenceLink[];
|