@intellectual-frontiers/ergonex 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/mod.js +1236 -1528
- package/dist/modules/types.d.ts +4 -4
- package/dist/platform/k-args.d.ts +3 -24
- package/dist/state-record.d.ts +1 -1
- package/dist/vendor/ts/kernel/mod.d.ts +0 -6
- package/dist/vendor/ts/kernel/render.d.ts +1 -1
- package/dist/vendor/ts/kernel/trace.d.ts +1 -1
- package/ergonex.mjs +3421 -3705
- package/package.json +4 -2
- package/dist/vendor/ts/kernel/args.d.ts +0 -240
- package/dist/vendor/ts/kernel/commands.d.ts +0 -103
- package/dist/vendor/ts/kernel/palette.d.ts +0 -44
- 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/vt.d.ts +0 -78
- package/dist/vendor/ts/kernel/width.d.ts +0 -63
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@intellectual-frontiers/ergonex",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.1",
|
|
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,9 @@
|
|
|
19
19
|
}
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@intellectual-frontiers/core": "0.1.0"
|
|
22
|
+
"@intellectual-frontiers/core": "0.1.0",
|
|
23
|
+
"@intellectual-frontiers/rdf": "0.1.0",
|
|
24
|
+
"@intellectual-frontiers/terminal": "0.1.0"
|
|
23
25
|
},
|
|
24
26
|
"files": [
|
|
25
27
|
"dist",
|
|
@@ -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,103 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* A command tree declared once as data (commons 0005-typescript-runtime FR-072): a command of groups and verbs to any depth, each with a
|
|
3
|
-
* name and a summary, and each verb with its options (`./args.ts`'s declaration) and its arguments. From that declaration alone it
|
|
4
|
-
* resolves an argument vector to the verb it names, to the help asked for, or to a typed error that names the word not known, where, the
|
|
5
|
-
* words known there and the nearest of them; and it renders the help of every level, so that help never runs a verb.
|
|
6
|
-
*
|
|
7
|
-
* @remarks
|
|
8
|
-
* A group named with no verb asks for its help, as `git remote` with no verb would list; `--help` or `-h` anywhere before `--` asks for
|
|
9
|
-
* the help of the deepest group or verb named before it. Unknown options of a verb are its own parser's business (`parseArgs`), which the
|
|
10
|
-
* verb runs on the arguments left to it.
|
|
11
|
-
*
|
|
12
|
-
* @example
|
|
13
|
-
* ```ts
|
|
14
|
-
* import { group, resolveCommand, verb } from "./commands.js";
|
|
15
|
-
* const tree = group({ name: "tool", summary: "A tool.", children: [group({ name: "work", summary: "Works.", children: [
|
|
16
|
-
* verb({ name: "build", summary: "Build.", options: {} }),
|
|
17
|
-
* ] })] });
|
|
18
|
-
* resolveCommand(tree, ["work", "build", "a"]); // ok: the verb build, with ["a"] left
|
|
19
|
-
* resolveCommand(tree, ["wrk"]); // err: wrk is not known at the top, did you mean work?
|
|
20
|
-
* ```
|
|
21
|
-
*
|
|
22
|
-
* @module
|
|
23
|
-
*/
|
|
24
|
-
import { type Result } from "@intellectual-frontiers/core";
|
|
25
|
-
import { type Operand, type Spec, type SpecCheck } from "./args.js";
|
|
26
|
-
/** An example of a verb: the words after the verb, and what it does. */
|
|
27
|
-
export type Example = {
|
|
28
|
-
readonly args: readonly string[];
|
|
29
|
-
readonly says: string;
|
|
30
|
-
};
|
|
31
|
-
/** A verb: a leaf of the tree, with the options and arguments it takes. */
|
|
32
|
-
export type Verb<S extends Spec = Spec> = {
|
|
33
|
-
readonly kind: "verb";
|
|
34
|
-
readonly name: string;
|
|
35
|
-
readonly summary: string;
|
|
36
|
-
readonly options: S;
|
|
37
|
-
readonly operands: readonly Operand[];
|
|
38
|
-
readonly examples: readonly Example[];
|
|
39
|
-
};
|
|
40
|
-
/** A group: a word that names more words, groups or verbs. */
|
|
41
|
-
export type Group = {
|
|
42
|
-
readonly kind: "group";
|
|
43
|
-
readonly name: string;
|
|
44
|
-
readonly summary: string;
|
|
45
|
-
readonly children: readonly CommandNode[];
|
|
46
|
-
};
|
|
47
|
-
/** One node of a command tree. */
|
|
48
|
-
export type CommandNode = Group | Verb;
|
|
49
|
-
/** A verb, declared with its options checked as `parseArgs` checks them. */
|
|
50
|
-
export declare function verb<S extends Spec>(v: {
|
|
51
|
-
readonly name: string;
|
|
52
|
-
readonly summary: string;
|
|
53
|
-
readonly options: S & SpecCheck<S>;
|
|
54
|
-
readonly operands?: readonly Operand[];
|
|
55
|
-
readonly examples?: readonly Example[];
|
|
56
|
-
}): Verb<S>;
|
|
57
|
-
/** A group of nodes. */
|
|
58
|
-
export declare function group(g: {
|
|
59
|
-
readonly name: string;
|
|
60
|
-
readonly summary: string;
|
|
61
|
-
readonly children: readonly CommandNode[];
|
|
62
|
-
}): Group;
|
|
63
|
-
/** Whether a name is one a command may have: lower case letters, digits and dashes, beginning with a letter. */
|
|
64
|
-
export declare function validCommandName(name: string): boolean;
|
|
65
|
-
/** What is wrong with a declared tree: a name that may not be one, or two children of a group with the same name. */
|
|
66
|
-
export type TreeProblem = {
|
|
67
|
-
readonly kind: "bad-name";
|
|
68
|
-
readonly path: readonly string[];
|
|
69
|
-
readonly name: string;
|
|
70
|
-
} | {
|
|
71
|
-
readonly kind: "duplicate";
|
|
72
|
-
readonly path: readonly string[];
|
|
73
|
-
readonly name: string;
|
|
74
|
-
};
|
|
75
|
-
/** Every problem of a tree, in the order of its nodes; none where it is well formed. */
|
|
76
|
-
export declare function treeProblems(root: CommandNode, path?: readonly string[]): readonly TreeProblem[];
|
|
77
|
-
/** What an argument vector names: a verb with the arguments left for it, or the help of a node. */
|
|
78
|
-
export type Resolved = {
|
|
79
|
-
readonly kind: "verb";
|
|
80
|
-
readonly path: readonly string[];
|
|
81
|
-
readonly verb: Verb;
|
|
82
|
-
readonly args: readonly string[];
|
|
83
|
-
} | {
|
|
84
|
-
readonly kind: "help";
|
|
85
|
-
readonly path: readonly string[];
|
|
86
|
-
readonly node: CommandNode;
|
|
87
|
-
};
|
|
88
|
-
/** Why an argument vector names nothing: a word not known below `path`, the words known there, and the nearest. */
|
|
89
|
-
export type CommandError = {
|
|
90
|
-
readonly kind: "unknown-command";
|
|
91
|
-
readonly path: readonly string[];
|
|
92
|
-
readonly word: string;
|
|
93
|
-
readonly known: readonly string[];
|
|
94
|
-
readonly suggestion: string | undefined;
|
|
95
|
-
};
|
|
96
|
-
/** Whether a word asks for help. */
|
|
97
|
-
export declare function asksForHelp(word: string): boolean;
|
|
98
|
-
/** Resolves an argument vector (the words after the program's name) against a tree whose root is the program. */
|
|
99
|
-
export declare function resolveCommand(root: Group, argv: readonly string[]): Result<Resolved, CommandError>;
|
|
100
|
-
/** A command error as one sentence, with the help to run next. */
|
|
101
|
-
export declare function formatCommandError(e: CommandError): string;
|
|
102
|
-
/** The help of a node at `path` (the words that name it, the program's first), from its declaration alone. */
|
|
103
|
-
export declare function commandHelp(path: readonly string[], node: CommandNode): string;
|
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
/** What the terminal written to can show: colour, emoji, and its width in columns (the fields of the runtime's `Look`). */
|
|
2
|
-
export type Capabilities = {
|
|
3
|
-
readonly colour: boolean;
|
|
4
|
-
readonly emoji: boolean;
|
|
5
|
-
readonly columns: number;
|
|
6
|
-
};
|
|
7
|
-
/** What a piece of output means, and so its colour. */
|
|
8
|
-
export type Role = "success" | "failure" | "skipped" | "cancelled" | "hint" | "warning" | "dim" | "accent" | "plain";
|
|
9
|
-
/** Every role, in a fixed order. */
|
|
10
|
-
export declare const ROLES: readonly Role[];
|
|
11
|
-
/** A mark at the start of a line: how something ended, or what a line is. */
|
|
12
|
-
export type MarkKind = "done" | "failed" | "skipped" | "cancelled" | "hint" | "warning" | "pending" | "action";
|
|
13
|
-
/** Every mark, in a fixed order. */
|
|
14
|
-
export declare const MARK_KINDS: readonly MarkKind[];
|
|
15
|
-
/** A mark as an emoji, its ASCII fallback, and the role it is painted in. */
|
|
16
|
-
export type MarkStyle = {
|
|
17
|
-
readonly emoji: string;
|
|
18
|
-
readonly ascii: string;
|
|
19
|
-
readonly role: Role;
|
|
20
|
-
};
|
|
21
|
-
/**
|
|
22
|
-
* The marks: ✅ ❌ ⏭️ ⏹️ 👉 ⚠️ ⏳ ⚡, and `[ok]` `[x]` `[skip]` `[stop]` `->` `[!]` `[todo]` `[you]` where there are no emoji. ❌ and ⚠️ are
|
|
23
|
-
* problems; ⏳ (pending) is something not set up yet, expected until someone does it; ⚡ (action) is a step that is the person's to take
|
|
24
|
-
* (send a change, back up, approve): nothing is wrong, so it is neither a warning nor an error (FR-027).
|
|
25
|
-
*/
|
|
26
|
-
export declare const MARKS: Readonly<Record<MarkKind, MarkStyle>>;
|
|
27
|
-
/** A mark: its emoji where the terminal shows emoji, else its ASCII fallback. */
|
|
28
|
-
export declare function mark(kind: MarkKind, caps: {
|
|
29
|
-
readonly emoji: boolean;
|
|
30
|
-
}): string;
|
|
31
|
-
/** The SGR parameters of a role; empty for `plain`. */
|
|
32
|
-
export declare function sgrOf(role: Role): string;
|
|
33
|
-
/**
|
|
34
|
-
* A text in a role's colour, followed by a reset, where colour is allowed; the text as it is where it is not, for the role `plain`, and for
|
|
35
|
-
* an empty text. Painted texts are put side by side, not inside one another: the inner reset would end the outer colour.
|
|
36
|
-
*/
|
|
37
|
-
export declare function paint(role: Role, text: string, caps: {
|
|
38
|
-
readonly colour: boolean;
|
|
39
|
-
}): string;
|
|
40
|
-
/** A line's beginning: the mark painted in its role, a space, and the text. */
|
|
41
|
-
export declare function label(kind: MarkKind, text: string, caps: {
|
|
42
|
-
readonly colour: boolean;
|
|
43
|
-
readonly emoji: boolean;
|
|
44
|
-
}): string;
|
|
@@ -1,190 +0,0 @@
|
|
|
1
|
-
import { type Iri, type LangString, type Named, type NamedOf, type Namespace, type Triple, type Value, type VocabularyTerm } from "./rdf-term.js";
|
|
2
|
-
/** What a field's values may be: a plain string, a string in a language, either, a boolean, an integer, or a reference. */
|
|
3
|
-
export type RangeKind = "string" | "lang" | "text" | "boolean" | "integer" | "ref";
|
|
4
|
-
/** A field's range, with the TypeScript type `V` of its values for the compiler. */
|
|
5
|
-
export type Range<V> = {
|
|
6
|
-
readonly kind: RangeKind;
|
|
7
|
-
readonly words?: readonly string[];
|
|
8
|
-
readonly "@ifc/rdf-value": V;
|
|
9
|
-
};
|
|
10
|
-
/** The ranges of a field. `ref<"a" | "b">()` accepts an individual of either class. */
|
|
11
|
-
export declare const range: {
|
|
12
|
-
/** A plain string (`xsd:string`). */
|
|
13
|
-
readonly string: Range<string>;
|
|
14
|
-
/** A string in a language. */
|
|
15
|
-
readonly langString: Range<LangString>;
|
|
16
|
-
/** A plain string or a string in a language. */
|
|
17
|
-
readonly text: Range<string | LangString>;
|
|
18
|
-
/** A boolean (`xsd:boolean`). */
|
|
19
|
-
readonly boolean: Range<boolean>;
|
|
20
|
-
/** An integer (`xsd:integer`); one that is not a safe integer is found by `validate`. */
|
|
21
|
-
readonly integer: Range<number>;
|
|
22
|
-
/** A reference to an individual of one of the classes `C`. */
|
|
23
|
-
readonly ref: <C extends string>() => Range<NamedOf<C>>;
|
|
24
|
-
/** A plain string that is one of `words`: the union of the words is the field's type. */
|
|
25
|
-
readonly oneOf: <const W extends readonly [string, ...string[]]>(words: W) => Range<W[number]>;
|
|
26
|
-
};
|
|
27
|
-
/** How many values a field holds: exactly one, at most one, or any number in order. */
|
|
28
|
-
export type Cardinality = "one" | "optional" | "many";
|
|
29
|
-
/** A field of a schema: its property, its range and its cardinality. */
|
|
30
|
-
export type Field<V, K extends Cardinality> = {
|
|
31
|
-
readonly property: Named;
|
|
32
|
-
readonly range: Range<V>;
|
|
33
|
-
readonly cardinality: K;
|
|
34
|
-
};
|
|
35
|
-
/** A field holding exactly one value. */
|
|
36
|
-
export declare function one<V>(property: Named, r: Range<V>): Field<V, "one">;
|
|
37
|
-
/** A field holding at most one value. */
|
|
38
|
-
export declare function optional<V>(property: Named, r: Range<V>): Field<V, "optional">;
|
|
39
|
-
/** A field holding any number of values, in the order given. */
|
|
40
|
-
export declare function many<V>(property: Named, r: Range<V>): Field<V, "many">;
|
|
41
|
-
/** The fields of a schema, by the names its individuals' values are written with. */
|
|
42
|
-
export type Fields = Readonly<Record<string, Field<unknown, Cardinality>>>;
|
|
43
|
-
type ValueOf<F> = F extends Field<infer V, Cardinality> ? V : never;
|
|
44
|
-
type Keys<S extends Fields, K extends Cardinality> = {
|
|
45
|
-
readonly [N in keyof S]: S[N] extends Field<unknown, K> ? N : never;
|
|
46
|
-
}[keyof S];
|
|
47
|
-
/** The values of an individual of a schema with the fields `S`: a required field's value, an optional one's, a list for `many`. */
|
|
48
|
-
export type ValuesOf<S extends Fields> = {
|
|
49
|
-
readonly [N in Keys<S, "one">]: ValueOf<S[N]>;
|
|
50
|
-
} & {
|
|
51
|
-
readonly [N in Keys<S, "optional">]?: ValueOf<S[N]>;
|
|
52
|
-
} & {
|
|
53
|
-
readonly [N in Keys<S, "many">]?: readonly ValueOf<S[N]>[];
|
|
54
|
-
};
|
|
55
|
-
/** One predicate of an individual and its values in order: what its triples are made from. */
|
|
56
|
-
export type Statement = {
|
|
57
|
-
readonly predicate: Named;
|
|
58
|
-
readonly objects: readonly Value[];
|
|
59
|
-
readonly words?: readonly string[];
|
|
60
|
-
};
|
|
61
|
-
/** An individual: a named node of its class `C`, with the class, its values `V` and the statements they make (its type first). */
|
|
62
|
-
export type Individual<C extends string, V> = Named<C> & {
|
|
63
|
-
readonly class: Named;
|
|
64
|
-
readonly values: V;
|
|
65
|
-
readonly statements: readonly Statement[];
|
|
66
|
-
};
|
|
67
|
-
/** An individual of any class, as a writer or a check takes it. */
|
|
68
|
-
export type AnyIndividual = Named & {
|
|
69
|
-
readonly class: Named;
|
|
70
|
-
readonly statements: readonly Statement[];
|
|
71
|
-
};
|
|
72
|
-
/** A class schema: the class, its CURIE, its fields, and how an individual of it is made. */
|
|
73
|
-
export type ClassSchema<C extends string, S extends Fields> = {
|
|
74
|
-
/** The class. */
|
|
75
|
-
readonly class: Named;
|
|
76
|
-
/** The class's CURIE, the brand of its individuals. */
|
|
77
|
-
readonly curie: C;
|
|
78
|
-
/** The fields, in the order their triples are made. */
|
|
79
|
-
readonly fields: S;
|
|
80
|
-
/** An individual of the class: the subject and its values. */
|
|
81
|
-
readonly make: (subject: Named<C>, values: ValuesOf<S>) => Individual<C, ValuesOf<S>>;
|
|
82
|
-
};
|
|
83
|
-
/** The schema of a class (a term of a vocabulary, whose CURIE brands the individuals) with its fields. */
|
|
84
|
-
export declare function classSchema<const C extends string, const S extends Fields>(cls: VocabularyTerm<never, C>, fields: S): ClassSchema<C, S>;
|
|
85
|
-
/** The schema of an ontology's own description: `owl:Ontology` with its label, description and version. */
|
|
86
|
-
export declare const OwlOntology: ClassSchema<"owl:Ontology", {
|
|
87
|
-
readonly label: Field<LangString, "optional">;
|
|
88
|
-
readonly comment: Field<LangString, "optional">;
|
|
89
|
-
readonly description: Field<LangString, "optional">;
|
|
90
|
-
readonly versionInfo: Field<string, "optional">;
|
|
91
|
-
readonly versionIri: Field<Named<"owl:Ontology">, "optional">;
|
|
92
|
-
}>;
|
|
93
|
-
/** The schema of a class: its label, comment, SKOS definition and superclasses. */
|
|
94
|
-
export declare const OwlClass: ClassSchema<"owl:Class", {
|
|
95
|
-
readonly label: Field<LangString, "optional">;
|
|
96
|
-
readonly comment: Field<LangString, "optional">;
|
|
97
|
-
readonly subClassOf: Field<Named<"owl:Class"> | Named<"rdfs:Class">, "many">;
|
|
98
|
-
readonly definition: Field<LangString, "optional">;
|
|
99
|
-
}>;
|
|
100
|
-
/** The schema of an object property: its label, comment, domain, range and SKOS definition. */
|
|
101
|
-
export declare const ObjectProperty: ClassSchema<"owl:ObjectProperty", {
|
|
102
|
-
readonly label: Field<LangString, "optional">;
|
|
103
|
-
readonly comment: Field<LangString, "optional">;
|
|
104
|
-
readonly domain: Field<Named<"owl:Class"> | Named<"rdfs:Class"> | Named<"rdfs:Datatype">, "optional">;
|
|
105
|
-
readonly range: Field<Named<"owl:Class"> | Named<"rdfs:Class"> | Named<"rdfs:Datatype">, "optional">;
|
|
106
|
-
readonly definition: Field<LangString, "optional">;
|
|
107
|
-
}>;
|
|
108
|
-
/** The schema of a datatype property: its label, comment, domain, range and SKOS definition. */
|
|
109
|
-
export declare const DatatypeProperty: ClassSchema<"owl:DatatypeProperty", {
|
|
110
|
-
readonly label: Field<LangString, "optional">;
|
|
111
|
-
readonly comment: Field<LangString, "optional">;
|
|
112
|
-
readonly domain: Field<Named<"owl:Class"> | Named<"rdfs:Class"> | Named<"rdfs:Datatype">, "optional">;
|
|
113
|
-
readonly range: Field<Named<"owl:Class"> | Named<"rdfs:Class"> | Named<"rdfs:Datatype">, "optional">;
|
|
114
|
-
readonly definition: Field<LangString, "optional">;
|
|
115
|
-
}>;
|
|
116
|
-
/** The named node of the ontology a namespace's terms belong to (`https://example.org/terms` for `https://example.org/terms#`). */
|
|
117
|
-
export declare function ontologyOf(ns: Namespace): Named<"owl:Ontology">;
|
|
118
|
-
/** A code list: individuals of one class keyed by their local names, whose keys' union is the type code branches on. */
|
|
119
|
-
export type CodeList<C extends string, V, K extends string> = {
|
|
120
|
-
readonly [N in K]: Individual<C, V>;
|
|
121
|
-
};
|
|
122
|
-
/** The code list of a schema's class in a namespace: each key is a local name, each value the individual's values. */
|
|
123
|
-
export declare function codes<C extends string, S extends Fields, const E extends Readonly<Record<string, ValuesOf<S>>>>(schema: ClassSchema<C, S>, ns: Namespace, entries: E): CodeList<C, ValuesOf<S>, keyof E & string>;
|
|
124
|
-
/** The key of a code list that names an individual, or nothing where none does. */
|
|
125
|
-
export declare function codeOf<K extends string>(list: {
|
|
126
|
-
readonly [N in K]: Named;
|
|
127
|
-
}, node: Named): K | undefined;
|
|
128
|
-
/** The schema of a SKOS concept scheme: its label and definition. */
|
|
129
|
-
export declare const ConceptSchemeSchema: ClassSchema<"skos:ConceptScheme", {
|
|
130
|
-
readonly prefLabel: Field<LangString, "one">;
|
|
131
|
-
readonly definition: Field<LangString, "optional">;
|
|
132
|
-
}>;
|
|
133
|
-
/** The schema of a SKOS concept: its scheme, notation, label and definition. */
|
|
134
|
-
export declare const ConceptSchema: ClassSchema<"skos:Concept", {
|
|
135
|
-
readonly inScheme: Field<Named<"skos:ConceptScheme">, "one">;
|
|
136
|
-
readonly notation: Field<string, "one">;
|
|
137
|
-
readonly prefLabel: Field<LangString, "one">;
|
|
138
|
-
readonly definition: Field<LangString, "optional">;
|
|
139
|
-
}>;
|
|
140
|
-
/** What one concept of a scheme says beside its notation: its local name in the namespace, its label and its definition. */
|
|
141
|
-
export type ConceptEntry = {
|
|
142
|
-
readonly local: string;
|
|
143
|
-
readonly label: LangString;
|
|
144
|
-
readonly definition?: LangString;
|
|
145
|
-
};
|
|
146
|
-
/** A SKOS concept scheme: the scheme, its concepts by notation, and every individual it states. */
|
|
147
|
-
export type ConceptScheme<N extends string> = {
|
|
148
|
-
/** The scheme itself. */
|
|
149
|
-
readonly scheme: Individual<"skos:ConceptScheme", ValuesOf<typeof ConceptSchemeSchema.fields>>;
|
|
150
|
-
/** Its concepts, by notation. */
|
|
151
|
-
readonly concepts: {
|
|
152
|
-
readonly [K in N]: Individual<"skos:Concept", ValuesOf<typeof ConceptSchema.fields>>;
|
|
153
|
-
};
|
|
154
|
-
/** The scheme and its concepts, in order. */
|
|
155
|
-
readonly individuals: readonly AnyIndividual[];
|
|
156
|
-
};
|
|
157
|
-
/** A SKOS concept scheme in a namespace, its concepts keyed by their notations, whose union is the type of a notation. */
|
|
158
|
-
export declare function conceptScheme<const E extends Readonly<Record<string, ConceptEntry>>>(ns: Namespace, local: string, head: {
|
|
159
|
-
readonly label: LangString;
|
|
160
|
-
readonly definition?: LangString;
|
|
161
|
-
}, entries: E): ConceptScheme<keyof E & string>;
|
|
162
|
-
/** One file of an ontology: its name, the prefixes its Turtle may write, and the individuals it states, in order. */
|
|
163
|
-
export type OntologyFile = {
|
|
164
|
-
readonly name: string;
|
|
165
|
-
readonly prefixes: readonly Namespace[];
|
|
166
|
-
readonly individuals: readonly AnyIndividual[];
|
|
167
|
-
};
|
|
168
|
-
/** The triples of individuals: each individual's statements in order, each triple once, where first stated. */
|
|
169
|
-
export declare function triplesOf(individuals: readonly AnyIndividual[]): readonly Triple[];
|
|
170
|
-
/** What a type cannot state about individuals (or what a run without the type checker lets through): an integer that is not a safe integer, a word not of its field's list, or a subject stated twice. */
|
|
171
|
-
export type RdfFinding = {
|
|
172
|
-
readonly kind: "not-an-integer";
|
|
173
|
-
readonly subject: Iri;
|
|
174
|
-
readonly predicate: Iri;
|
|
175
|
-
readonly value: number;
|
|
176
|
-
} | {
|
|
177
|
-
readonly kind: "not-one-of";
|
|
178
|
-
readonly subject: Iri;
|
|
179
|
-
readonly predicate: Iri;
|
|
180
|
-
readonly value: string;
|
|
181
|
-
readonly words: readonly string[];
|
|
182
|
-
} | {
|
|
183
|
-
readonly kind: "stated-twice";
|
|
184
|
-
readonly subject: Iri;
|
|
185
|
-
};
|
|
186
|
-
/** The sentence a finding is told with. */
|
|
187
|
-
export declare function formatRdfFinding(f: RdfFinding): string;
|
|
188
|
-
/** Every finding about the individuals, in the order they are stated. */
|
|
189
|
-
export declare function validate(individuals: readonly AnyIndividual[]): readonly RdfFinding[];
|
|
190
|
-
export {};
|