spec-controller 0.1.0-alpha.4 → 0.1.0-alpha.40
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 +34 -6
- package/dist/cli-allocate/cli.d.ts +2 -0
- package/dist/cli-allocate/cli.d.ts.map +1 -0
- package/dist/cli-allocate/cli.js +57 -0
- package/dist/cli-allocate/cli.js.map +1 -0
- package/dist/cli-allocate/readHistory.d.ts +29 -0
- package/dist/cli-allocate/readHistory.d.ts.map +1 -0
- package/dist/cli-allocate/readHistory.js +136 -0
- package/dist/cli-allocate/readHistory.js.map +1 -0
- package/dist/cli-allocate/readParts.d.ts +3 -0
- package/dist/cli-allocate/readParts.d.ts.map +1 -0
- package/dist/cli-allocate/readParts.js +28 -0
- package/dist/cli-allocate/readParts.js.map +1 -0
- package/dist/cli-allocate/readTree.d.ts +16 -0
- package/dist/cli-allocate/readTree.d.ts.map +1 -0
- package/dist/cli-allocate/readTree.js +106 -0
- package/dist/cli-allocate/readTree.js.map +1 -0
- package/dist/cli-allocate/refStore.d.ts +3 -0
- package/dist/cli-allocate/refStore.d.ts.map +1 -0
- package/dist/cli-allocate/refStore.js +47 -0
- package/dist/cli-allocate/refStore.js.map +1 -0
- package/dist/cli-allocate/request.d.ts +11 -0
- package/dist/cli-allocate/request.d.ts.map +1 -0
- package/dist/cli-allocate/request.js +29 -0
- package/dist/cli-allocate/request.js.map +1 -0
- package/dist/cli-allocate/stderr.d.ts +14 -0
- package/dist/cli-allocate/stderr.d.ts.map +1 -0
- package/dist/cli-allocate/stderr.js +33 -0
- package/dist/cli-allocate/stderr.js.map +1 -0
- package/dist/cli-allocate/unreadable.d.ts +24 -0
- package/dist/cli-allocate/unreadable.d.ts.map +1 -0
- package/dist/cli-allocate/unreadable.js +43 -0
- package/dist/cli-allocate/unreadable.js.map +1 -0
- package/dist/cli-args.d.ts +73 -18
- package/dist/cli-args.d.ts.map +1 -1
- package/dist/cli-args.js +244 -22
- package/dist/cli-args.js.map +1 -1
- package/dist/cli-balance/cli.d.ts +31 -13
- package/dist/cli-balance/cli.d.ts.map +1 -1
- package/dist/cli-balance/cli.js +205 -251
- package/dist/cli-balance/cli.js.map +1 -1
- package/dist/cli-balance/emit/writer.d.ts +8 -23
- package/dist/cli-balance/emit/writer.d.ts.map +1 -1
- package/dist/cli-balance/emit/writer.js +24 -32
- package/dist/cli-balance/emit/writer.js.map +1 -1
- package/dist/cli-balance/exitStatus.d.ts +3 -0
- package/dist/cli-balance/exitStatus.d.ts.map +1 -0
- package/dist/cli-balance/exitStatus.js +12 -0
- package/dist/cli-balance/exitStatus.js.map +1 -0
- package/dist/cli-balance/reRender.d.ts +22 -0
- package/dist/cli-balance/reRender.d.ts.map +1 -0
- package/dist/cli-balance/reRender.js +36 -0
- package/dist/cli-balance/reRender.js.map +1 -0
- package/dist/cli-balance/unreadableInputs.d.ts +35 -0
- package/dist/cli-balance/unreadableInputs.d.ts.map +1 -0
- package/dist/cli-balance/unreadableInputs.js +101 -0
- package/dist/cli-balance/unreadableInputs.js.map +1 -0
- package/dist/cli-registry.d.ts +28 -0
- package/dist/cli-registry.d.ts.map +1 -1
- package/dist/cli-registry.js +40 -35
- package/dist/cli-registry.js.map +1 -1
- package/dist/cli.d.ts +4 -5
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +37 -21
- package/dist/cli.js.map +1 -1
- package/dist/host.d.ts +28 -3
- package/dist/host.d.ts.map +1 -1
- package/dist/host.js +137 -17
- package/dist/host.js.map +1 -1
- package/dist/ingest/gherkinValidation.d.ts +3 -7
- package/dist/ingest/gherkinValidation.d.ts.map +1 -1
- package/dist/ingest/gherkinValidation.js +3 -7
- package/dist/ingest/gherkinValidation.js.map +1 -1
- package/dist/ingest/ingestQualityChecks.d.ts +25 -54
- package/dist/ingest/ingestQualityChecks.d.ts.map +1 -1
- package/dist/ingest/ingestQualityChecks.js +112 -145
- package/dist/ingest/ingestQualityChecks.js.map +1 -1
- package/dist/ingest/ingestScenarios.d.ts +11 -17
- package/dist/ingest/ingestScenarios.d.ts.map +1 -1
- package/dist/ingest/ingestScenarios.js +52 -62
- package/dist/ingest/ingestScenarios.js.map +1 -1
- package/dist/ingest/inputShapes.d.ts +47 -0
- package/dist/ingest/inputShapes.d.ts.map +1 -0
- package/dist/ingest/inputShapes.js +143 -0
- package/dist/ingest/inputShapes.js.map +1 -0
- package/dist/outputLocation.d.ts +15 -0
- package/dist/outputLocation.d.ts.map +1 -0
- package/dist/outputLocation.js +39 -0
- package/dist/outputLocation.js.map +1 -0
- package/dist/run-management/keptRun.d.ts +27 -25
- package/dist/run-management/keptRun.d.ts.map +1 -1
- package/dist/run-management/keptRun.js +20 -21
- package/dist/run-management/keptRun.js.map +1 -1
- package/dist/storedRun.d.ts +27 -0
- package/dist/storedRun.d.ts.map +1 -0
- package/dist/storedRun.js +49 -0
- package/dist/storedRun.js.map +1 -0
- package/package.json +2 -2
- package/dist/corpus/cli.d.ts +0 -34
- package/dist/corpus/cli.d.ts.map +0 -1
- package/dist/corpus/cli.js +0 -128
- package/dist/corpus/cli.js.map +0 -1
- package/dist/mutation-ratchet/index.d.ts +0 -51
- package/dist/mutation-ratchet/index.d.ts.map +0 -1
- package/dist/mutation-ratchet/index.js +0 -51
- package/dist/mutation-ratchet/index.js.map +0 -1
- package/dist/mutation-ratchet/record.d.ts +0 -178
- package/dist/mutation-ratchet/record.d.ts.map +0 -1
- package/dist/mutation-ratchet/record.js +0 -314
- package/dist/mutation-ratchet/record.js.map +0 -1
- package/dist/mutation-ratchet/report.d.ts +0 -109
- package/dist/mutation-ratchet/report.d.ts.map +0 -1
- package/dist/mutation-ratchet/report.js +0 -156
- package/dist/mutation-ratchet/report.js.map +0 -1
package/dist/cli-args.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* THE ONE READING OF A COMMAND'S ARGV, and the one bounding of it against the registry.
|
|
3
3
|
*
|
|
4
|
-
* WHY IT IS ITS OWN MODULE
|
|
4
|
+
* WHY IT IS ITS OWN MODULE. Both halves lived inside `cli-balance/cli.ts` while
|
|
5
5
|
* `balance` was the only command — `parseArgs` private to it, `checkUnknownFlags` exported for
|
|
6
6
|
* its own `@unit` arm. A second command needs both, and the two ways of giving it them were
|
|
7
7
|
* worse than moving them: copying `parseArgs` would put a second reading of argv in a tree whose
|
|
@@ -12,11 +12,13 @@
|
|
|
12
12
|
* THE BOUNDING IS PER-COMMAND, which is what makes "accepted = registry = help" hold for every
|
|
13
13
|
* command rather than for the one this code was written beside. `checkUnknownFlags` took the
|
|
14
14
|
* registry and looked `balance` up inside itself; the command is a parameter now, exactly as it
|
|
15
|
-
* became one for `renderCommandHelp
|
|
16
|
-
* asks about `balance`:
|
|
17
|
-
* residual — that an unregistered flag to `tags` is unproven by a scenario of its own — is named
|
|
18
|
-
* on 3F-3286 rather than left silent.
|
|
15
|
+
* became one for `renderCommandHelp`. The unknown-flag scenario is unchanged and still
|
|
16
|
+
* asks about `balance`: a command added later gets the same bounding BY CONSTRUCTION.
|
|
19
17
|
*/
|
|
18
|
+
/** True when a command's argv asks for its help, wherever `--help` or `-h` stands in it. */
|
|
19
|
+
export function asksForHelp(argv) {
|
|
20
|
+
return argv.includes("--help") || argv.includes("-h");
|
|
21
|
+
}
|
|
20
22
|
/**
|
|
21
23
|
* Parse `--flag value` pairs from a command's argv into a record, keys with the `--` stripped.
|
|
22
24
|
*
|
|
@@ -24,10 +26,11 @@
|
|
|
24
26
|
* the boolean flags — `--strict`, `--help` — are recognised: presence is what matters, so callers
|
|
25
27
|
* read them with `!== undefined`.
|
|
26
28
|
*
|
|
27
|
-
* PERMISSIVE BY ITSELF, AND BOUNDED BY THE CALLER. It records whatever it is given
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
29
|
+
* PERMISSIVE BY ITSELF, AND BOUNDED BY THE CALLER. It records whatever it is given — a flag no
|
|
30
|
+
* registry names, the last of two copies, a word after a flag that takes none — and drops a word
|
|
31
|
+
* that follows no flag. `checkArgvShape` and `checkUnknownFlags` below are what refuse those, before
|
|
32
|
+
* anything reads the record. The split is deliberate — the parse has no opinion about which
|
|
33
|
+
* command it is reading for, and the bounding has nothing else to do.
|
|
31
34
|
*/
|
|
32
35
|
export function parseArgs(argv) {
|
|
33
36
|
const args = {};
|
|
@@ -48,26 +51,224 @@ export function parseArgs(argv) {
|
|
|
48
51
|
return args;
|
|
49
52
|
}
|
|
50
53
|
/**
|
|
51
|
-
* The
|
|
54
|
+
* The value flags of one scope: every flag the registry gives a value placeholder (`arg`), by
|
|
55
|
+
* name and alias, dashes kept. Read from the registry alone, so a value flag added later is one.
|
|
56
|
+
*/
|
|
57
|
+
export function valueFlagsOf(flags) {
|
|
58
|
+
const valueFlags = new Map();
|
|
59
|
+
for (const flag of flags) {
|
|
60
|
+
if (flag.arg === undefined)
|
|
61
|
+
continue;
|
|
62
|
+
for (const name of [flag.name, ...(flag.aliases ?? [])])
|
|
63
|
+
valueFlags.set(name, flag);
|
|
64
|
+
}
|
|
65
|
+
return valueFlags;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* True when the token after a value flag is not a value: there is none, it is the next flag (the
|
|
69
|
+
* same `--` test `parseArgs` reads a flag by), or it is empty — an unset variable, quoted.
|
|
70
|
+
*/
|
|
71
|
+
export function isMissingValue(next) {
|
|
72
|
+
return next === undefined || next === "" || next.startsWith("--");
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* A flag that takes a value, given none, is a usage fault. It reads the
|
|
76
|
+
* RAW argv, because `parseArgs` has already turned a missing value into the string "true" — which a
|
|
77
|
+
* path flag then looked for on disk, `--target` recorded, and `--format` dropped on its way to a
|
|
78
|
+
* verdict `--exit-zero` turned green. Returns the refusal for the first such flag, else null.
|
|
79
|
+
*/
|
|
80
|
+
export function checkMissingValues(argv, registry, command) {
|
|
81
|
+
const entry = registry.commands.find((c) => c.name === command);
|
|
82
|
+
const valueFlags = valueFlagsOf(entry?.flags ?? []);
|
|
83
|
+
for (let i = 0; i < argv.length; i++) {
|
|
84
|
+
const flag = valueFlags.get(argv[i] ?? "");
|
|
85
|
+
if (flag !== undefined && isMissingValue(argv[i + 1])) {
|
|
86
|
+
return missingValueRefusal(argv[i] ?? flag.name, flag, `spec-controller ${command}`);
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
return null;
|
|
90
|
+
}
|
|
91
|
+
/** The refusal for a value flag given none: the flag, the value it takes, and where the flags are listed. */
|
|
92
|
+
export function missingValueRefusal(given, flag, scope) {
|
|
93
|
+
return (`The ${given} flag of '${scope}' needs a value — ${given} ${flag.arg ?? ""} — and was given none.\n` +
|
|
94
|
+
`Run '${scope} --help' to see the flags this version accepts and the values they take.`);
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* The shape of a command's argv, read against its registry scope: every token is a flag,
|
|
98
|
+
* or the value of the flag before it, or a usage fault. Returns the refusal for the first token that
|
|
99
|
+
* is neither, else null.
|
|
100
|
+
*/
|
|
101
|
+
export function checkArgvShape(argv, registry, command) {
|
|
102
|
+
const scope = flagScopeOf(registry, command);
|
|
103
|
+
const seen = new Set();
|
|
104
|
+
const positionals = positionalsOf(registry, command);
|
|
105
|
+
const walk = { scope, seen, positionals, slotsLeft: positionals.length };
|
|
106
|
+
for (let i = 0; i < argv.length; i++) {
|
|
107
|
+
const read = readToken(argv, i, walk, command);
|
|
108
|
+
if (typeof read === "string")
|
|
109
|
+
return read;
|
|
110
|
+
i += read;
|
|
111
|
+
}
|
|
112
|
+
return null;
|
|
113
|
+
}
|
|
114
|
+
/** The positional arguments a command takes, in order; none for a command that takes flags only. */
|
|
115
|
+
function positionalsOf(registry, command) {
|
|
116
|
+
return registry.commands.find((c) => c.name === command)?.positionals ?? [];
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* The positional arguments in a command's argv, in order: every word that is no flag and no flag's
|
|
120
|
+
* value. A flag the registry gives no value placeholder takes none, so `--new ZZ` reads ZZ as the
|
|
121
|
+
* positional, never as `--new`'s value — which `parseArgs` alone would make it.
|
|
122
|
+
*/
|
|
123
|
+
export function positionalArguments(argv, registry, command) {
|
|
124
|
+
const scope = flagScopeOf(registry, command);
|
|
125
|
+
const words = [];
|
|
126
|
+
for (let i = 0; i < argv.length; i++) {
|
|
127
|
+
const token = argv[i] ?? "";
|
|
128
|
+
if (!isFlagShaped(token))
|
|
129
|
+
words.push(token);
|
|
130
|
+
else if (scope.get(token)?.arg !== undefined)
|
|
131
|
+
i++;
|
|
132
|
+
}
|
|
133
|
+
return words;
|
|
134
|
+
}
|
|
135
|
+
/** One token of the walk: the refusal it earns, or how many of the tokens after it are its value. */
|
|
136
|
+
function readToken(argv, i, walk, command) {
|
|
137
|
+
const token = argv[i] ?? "";
|
|
138
|
+
const next = argv[i + 1];
|
|
139
|
+
if (isEqualsForm(token))
|
|
140
|
+
return equalsFormRefusal(token, walk.scope, `spec-controller ${command}`);
|
|
141
|
+
if (!isFlagShaped(token) && !walk.scope.has(token))
|
|
142
|
+
return positionalRead(token, walk, command);
|
|
143
|
+
const flag = walk.scope.get(token);
|
|
144
|
+
if (flag === undefined)
|
|
145
|
+
return valueTokensAfter(undefined, next);
|
|
146
|
+
return registeredFlagRefusal(flag, token, next, walk, command) ?? valueTokensAfter(flag, next);
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* The refusal a registered flag earns where it stands: given a second time when the registry does not
|
|
150
|
+
* mark it `repeatable` (by name or alias, one flag), or given a value it does not take.
|
|
151
|
+
*/
|
|
152
|
+
function registeredFlagRefusal(flag, token, next, walk, command) {
|
|
153
|
+
if (walk.seen.has(flag) && flag.repeatable !== true)
|
|
154
|
+
return givenTwiceRefusal(token, `spec-controller ${command}`);
|
|
155
|
+
walk.seen.add(flag);
|
|
156
|
+
if (flag.arg === undefined && next !== undefined && !isFlagShaped(next) && !walk.scope.has(next) && walk.slotsLeft === 0) {
|
|
157
|
+
return takesNoValueRefusal(token, next, command);
|
|
158
|
+
}
|
|
159
|
+
return undefined;
|
|
160
|
+
}
|
|
161
|
+
/** The refusal for a flag given more than once that is read once: the flag, and where. */
|
|
162
|
+
export function givenTwiceRefusal(given, scope) {
|
|
163
|
+
return (`The ${given} flag of '${scope}' was given more than once, and is read once: give it once.\n` +
|
|
164
|
+
`Run '${scope} --help' to see the flags this version accepts.`);
|
|
165
|
+
}
|
|
166
|
+
/** Every flag of one command's scope, by name and alias, dashes kept. */
|
|
167
|
+
function flagScopeOf(registry, command) {
|
|
168
|
+
const scope = new Map();
|
|
169
|
+
for (const flag of registry.commands.find((c) => c.name === command)?.flags ?? []) {
|
|
170
|
+
for (const name of [flag.name, ...(flag.aliases ?? [])])
|
|
171
|
+
scope.set(name, flag);
|
|
172
|
+
}
|
|
173
|
+
return scope;
|
|
174
|
+
}
|
|
175
|
+
/** A token read as a flag whether or not the scope has it: two dashes, as `parseArgs` reads one. */
|
|
176
|
+
function isFlagShaped(token) {
|
|
177
|
+
return token.startsWith("--");
|
|
178
|
+
}
|
|
179
|
+
/** A flag written with its value after an `=`, as in `--format=json`: a form this CLI does not read. */
|
|
180
|
+
export function isEqualsForm(token) {
|
|
181
|
+
return isFlagShaped(token) && token.includes("=");
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* The refusal for a flag written `--flag=value`: the form as given, and the
|
|
185
|
+
* spelling that is read — the flag and its value as two arguments, or the flag alone when it takes
|
|
186
|
+
* none. Never the unknown-flag pin advice: no version reads the form, so no pin cures it. Refused
|
|
187
|
+
* rather than split, by ruling: one spelling means one reader of argv, where splitting would teach
|
|
188
|
+
* every reader of it the same answer.
|
|
189
|
+
*/
|
|
190
|
+
export function equalsFormRefusal(token, flags, scope) {
|
|
191
|
+
const at = token.indexOf("=");
|
|
192
|
+
const name = token.slice(0, at);
|
|
193
|
+
const value = token.slice(at + 1);
|
|
194
|
+
const flag = flags.get(name);
|
|
195
|
+
const spelling = flag !== undefined && flag.arg === undefined ? name : `${name} ${value === "" ? (flag?.arg ?? "<value>") : value}`;
|
|
196
|
+
return (`The ${token} form is not read by '${scope}': a flag and its value are two arguments, as in '${spelling}'.\n` +
|
|
197
|
+
`Run '${scope} --help' to see the flags this version accepts.`);
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* How many tokens after a flag are its value: one for a value flag given one, and — for a flag the
|
|
201
|
+
* scope does not have — one for the word after it, exactly as `parseArgs` pairs them, so an unknown
|
|
202
|
+
* flag and its word stay the unknown-flag check's to refuse. An empty value is consumed as one, so it
|
|
203
|
+
* stays a missing value rather than becoming a stray argument.
|
|
204
|
+
*/
|
|
205
|
+
function valueTokensAfter(flag, next) {
|
|
206
|
+
if (next === undefined || isFlagShaped(next))
|
|
207
|
+
return 0;
|
|
208
|
+
return flag === undefined || flag.arg !== undefined ? 1 : 0;
|
|
209
|
+
}
|
|
210
|
+
/** The refusal for a value given to a flag that takes none: the flag, and the value it was given. */
|
|
211
|
+
function takesNoValueRefusal(flag, value, command) {
|
|
212
|
+
return (`The ${flag} flag of 'spec-controller ${command}' takes no value, and was given one: '${value}'.\n` +
|
|
213
|
+
`Run 'spec-controller ${command} --help' to see the flags this version accepts and the values they take.`);
|
|
214
|
+
}
|
|
215
|
+
/** A word that is no flag fills the command's next positional slot, or is refused when none is left. */
|
|
216
|
+
function positionalRead(token, walk, command) {
|
|
217
|
+
if (walk.slotsLeft === 0) {
|
|
218
|
+
return walk.positionals.length === 0 ? notAFlagRefusal(token, command) : extraPositionalRefusal(token, walk, command);
|
|
219
|
+
}
|
|
220
|
+
walk.slotsLeft--;
|
|
221
|
+
return 0;
|
|
222
|
+
}
|
|
223
|
+
/** The refusal for a word beyond the positional arguments a command takes: the word, and what it takes. */
|
|
224
|
+
function extraPositionalRefusal(token, walk, command) {
|
|
225
|
+
const takes = walk.positionals.map((positional) => positional.name).join(" ");
|
|
226
|
+
return (`The argument '${token}' is more than 'spec-controller ${command}' takes: it takes ${takes} once, and its flags.\n` +
|
|
227
|
+
`Run 'spec-controller ${command} --help' to see what this version accepts.`);
|
|
228
|
+
}
|
|
229
|
+
/** The refusal for a token that is no flag and no flag's value: the token, and what the command takes. */
|
|
230
|
+
function notAFlagRefusal(token, command) {
|
|
231
|
+
return (`The argument '${token}' is not a flag, nor the value of the flag before it: ` +
|
|
232
|
+
`'spec-controller ${command}' takes only flags and their values.\n` +
|
|
233
|
+
`Run 'spec-controller ${command} --help' to see the flags this version accepts.`);
|
|
234
|
+
}
|
|
235
|
+
/**
|
|
236
|
+
* A host modifier given after the command is out of place, not unknown: the
|
|
237
|
+
* flag exists, so the unknown-flag advice to bump a pin to a version that accepts it is false. Returns the
|
|
238
|
+
* refusal for the first such flag, else null.
|
|
239
|
+
*/
|
|
240
|
+
export function checkMisplacedHostModifiers(args, registry, command) {
|
|
241
|
+
const modifiers = new Set(registry.global.map((flag) => flag.name.replace(/^-+/, "")));
|
|
242
|
+
const key = Object.keys(args).find((k) => modifiers.has(k));
|
|
243
|
+
if (key === undefined)
|
|
244
|
+
return null;
|
|
245
|
+
return (`The --${key} flag is a host modifier: it goes before the command, as in ` +
|
|
246
|
+
`'spec-controller --${key} <value> ${command} …', never after it.\n` +
|
|
247
|
+
`Run 'spec-controller --help' to see the host modifiers this version accepts.`);
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* The registry-bounded flag check at a command's CLI edge. A command accepts ONLY
|
|
52
251
|
* the flags its per-command registry scope LISTS (by `name` or `alias`); an unregistered flag — a
|
|
53
|
-
* typo like `--strcit`, a stray `--bogus` — is a usage error,
|
|
54
|
-
*
|
|
55
|
-
*
|
|
252
|
+
* typo like `--strcit`, a stray `--bogus` — is a usage error, where the permissive parse above would
|
|
253
|
+
* have recorded it. It bounds flag NAMES and nothing else: a word that is no flag, a value given to a
|
|
254
|
+
* flag that takes none, a second copy, a `--flag=value` form, are `checkArgvShape`'s, which runs
|
|
255
|
+
* first. This is the structural teeth behind "accepted = registry
|
|
256
|
+
* = help": a flag cannot affect behaviour without a registry entry, and so (by the help-completeness
|
|
56
257
|
* guard) without appearing in that command's help.
|
|
57
258
|
*
|
|
58
259
|
* PURE and `@unit`-testable: the parsed args (keys already `--`-stripped) plus the registry and
|
|
59
260
|
* the command to bound against, returning the FIRST unregistered flag as a typed usage error
|
|
60
261
|
* naming it WITH its dashes — routed to stderr and the enumerated usage status 2 by the caller,
|
|
61
|
-
* never 1, never a silent run — else null. The global `--store`/`--run-id` modifiers
|
|
62
|
-
*
|
|
63
|
-
*
|
|
262
|
+
* never 1, never a silent run — else null. The global `--store`/`--run-id` modifiers are consumed
|
|
263
|
+
* by the top-level dispatcher when they come BEFORE the command; written after it they reach the
|
|
264
|
+
* command, and `checkMisplacedHostModifiers` refuses them as out of place before this runs.
|
|
64
265
|
*
|
|
65
266
|
* A COMMAND THE REGISTRY DOES NOT NAME ACCEPTS NOTHING, which is the honest reading rather than a
|
|
66
267
|
* degenerate one: an unregistered command has no scope, so every flag given to it is outside it.
|
|
67
268
|
* The dispatcher refuses such a command before this is ever reached, so the case is unreachable
|
|
68
269
|
* today and stated here so it cannot become a silent "accept everything" later.
|
|
69
270
|
*
|
|
70
|
-
* IT NAMES THE VERSION THAT REFUSED, AND THAT IS FOR THE PINNED READER
|
|
271
|
+
* IT NAMES THE VERSION THAT REFUSED, AND THAT IS FOR THE PINNED READER.
|
|
71
272
|
* A consumer pins spec-controller and then moves their own tree; the pinned reader is handed argv
|
|
72
273
|
* it was published too early — or too late — to understand, and an unadorned "unknown flag" is
|
|
73
274
|
* indistinguishable from a typo. Naming the running version makes version skew legible from the CI
|
|
@@ -81,6 +282,9 @@ export function parseArgs(argv) {
|
|
|
81
282
|
* refusal is exactly that forbidden wrapper, and no other adopter could write one either. So the
|
|
82
283
|
* refusal is the tool's own, which makes it universal rather than local.
|
|
83
284
|
*
|
|
285
|
+
* EXCEPT FOR A FLAG THE COMMAND HAS RETIRED, where the bump is false advice: `retiredFlagRefusal`
|
|
286
|
+
* below names the retirement and its replacement instead.
|
|
287
|
+
*
|
|
84
288
|
* THE STATUS DOES NOT MOVE. The caller still routes this to stderr and exit 2. A mistyped `--strcit`
|
|
85
289
|
* is still a usage fault, and giving skew its own status would cost every adopter the ordinary
|
|
86
290
|
* reading to serve the rarer one.
|
|
@@ -102,13 +306,31 @@ export function checkUnknownFlags(args, registry, command, toolVersion) {
|
|
|
102
306
|
// whose scope refused it — a consumer running two commands needs to know which help to open.
|
|
103
307
|
for (const key of Object.keys(args)) {
|
|
104
308
|
if (!accepted.has(key)) {
|
|
105
|
-
return (
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
309
|
+
return (retiredFlagRefusal(entry, key, command, toolVersion) ??
|
|
310
|
+
`Unknown flag --${key} for 'spec-controller ${command}' — this is spec-controller ` +
|
|
311
|
+
`${toolVersion}, and that flag is not in its ${command} scope.\n` +
|
|
312
|
+
`If this version is pinned, the pin and the tree it is reading have drifted apart: ` +
|
|
313
|
+
`bump the pin to a version whose '${command}' accepts --${key}.\n` +
|
|
314
|
+
`Otherwise run 'spec-controller ${command} --help' to see the flags this version accepts.`);
|
|
110
315
|
}
|
|
111
316
|
}
|
|
112
317
|
return null;
|
|
113
318
|
}
|
|
319
|
+
/**
|
|
320
|
+
* THE REFUSAL FOR A FLAG THE COMMAND HAS RETIRED, or `undefined` when the
|
|
321
|
+
* flag is merely unregistered. The drift advice above is true of a flag newer than the pin and
|
|
322
|
+
* false of a retired one: every earlier version accepts it and no later one will, so the only pin
|
|
323
|
+
* that satisfies "bump the pin to a version that accepts it" is a downgrade back onto the route
|
|
324
|
+
* the retirement removed. So this names the retirement and the replacement, and offers no pin.
|
|
325
|
+
*/
|
|
326
|
+
function retiredFlagRefusal(entry, key, command, toolVersion) {
|
|
327
|
+
const retired = entry?.retiredFlags?.find((flag) => flag.name.replace(/^-+/, "") === key);
|
|
328
|
+
if (retired === undefined)
|
|
329
|
+
return undefined;
|
|
330
|
+
return (`Retired flag ${retired.name} for 'spec-controller ${command}' — retired in spec-controller ` +
|
|
331
|
+
`${retired.retiredIn}, and no later version accepts it (this is spec-controller ${toolVersion}).\n` +
|
|
332
|
+
`Do not pin an earlier version to get it back: that restores the route it was retired with. ` +
|
|
333
|
+
`${retired.replacement}\n` +
|
|
334
|
+
`Run 'spec-controller ${command} --help' to see the flags this version accepts.`);
|
|
335
|
+
}
|
|
114
336
|
//# sourceMappingURL=cli-args.js.map
|
package/dist/cli-args.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,4FAA4F;AAC5F,MAAM,UAAU,WAAW,CAAC,IAAuB;IACjD,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,IAAuB;IAC/C,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnD,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAClB,CAAC,EAAE,CAAC;YACN,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAA0B;IACrD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC/C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;YAAE,SAAS;QACrC,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YAAE,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAwB;IACrD,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAuB,EACvB,QAAqB,EACrB,OAAe;IAEf,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAChE,MAAM,UAAU,GAAG,YAAY,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IACpD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,SAAS,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACtD,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,mBAAmB,OAAO,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,IAAc,EAAE,KAAa;IAC9E,OAAO,CACL,OAAO,KAAK,aAAa,KAAK,qBAAqB,KAAK,IAAI,IAAI,CAAC,GAAG,IAAI,EAAE,0BAA0B;QACpG,QAAQ,KAAK,0EAA0E,CACxF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAuB,EAAE,QAAqB,EAAE,OAAe;IAC5F,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAY,CAAC;IACjC,MAAM,WAAW,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrD,MAAM,IAAI,GAAS,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC;IAC/E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1C,CAAC,IAAI,IAAI,CAAC;IACZ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAWD,oGAAoG;AACpG,SAAS,aAAa,CAAC,QAAqB,EAAE,OAAe;IAC3D,OAAO,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB,EAAE,QAAqB,EAAE,OAAe;IACjG,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;aACvC,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,SAAS;YAAE,CAAC,EAAE,CAAC;IACpD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,qGAAqG;AACrG,SAAS,SAAS,CAAC,IAAuB,EAAE,CAAS,EAAE,IAAU,EAAE,OAAe;IAChF,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,IAAI,YAAY,CAAC,KAAK,CAAC;QAAE,OAAO,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,mBAAmB,OAAO,EAAE,CAAC,CAAC;IACnG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAChG,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACjE,OAAO,qBAAqB,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACjG,CAAC;AAED;;;GAGG;AACH,SAAS,qBAAqB,CAC5B,IAAc,EACd,KAAa,EACb,IAAwB,EACxB,IAAU,EACV,OAAe;IAEf,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,OAAO,EAAE,CAAC,CAAC;IACnH,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpB,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,KAAK,CAAC,EAAE,CAAC;QACzH,OAAO,mBAAmB,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,KAAa;IAC5D,OAAO,CACL,OAAO,KAAK,aAAa,KAAK,+DAA+D;QAC7F,QAAQ,KAAK,iDAAiD,CAC/D,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,SAAS,WAAW,CAAC,QAAqB,EAAE,OAAe;IACzD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QAClF,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,oGAAoG;AACpG,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,KAAoC,EAAE,KAAa;IAClG,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,QAAQ,GACZ,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;IACrH,OAAO,CACL,OAAO,KAAK,yBAAyB,KAAK,qDAAqD,QAAQ,MAAM;QAC7G,QAAQ,KAAK,iDAAiD,CAC/D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,IAA0B,EAAE,IAAwB;IAC5E,IAAI,IAAI,KAAK,SAAS,IAAI,YAAY,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACvD,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,qGAAqG;AACrG,SAAS,mBAAmB,CAAC,IAAY,EAAE,KAAa,EAAE,OAAe;IACvE,OAAO,CACL,OAAO,IAAI,6BAA6B,OAAO,yCAAyC,KAAK,MAAM;QACnG,wBAAwB,OAAO,0EAA0E,CAC1G,CAAC;AACJ,CAAC;AAED,wGAAwG;AACxG,SAAS,cAAc,CAAC,KAAa,EAAE,IAAU,EAAE,OAAe;IAChE,IAAI,IAAI,CAAC,SAAS,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACxH,CAAC;IACD,IAAI,CAAC,SAAS,EAAE,CAAC;IACjB,OAAO,CAAC,CAAC;AACX,CAAC;AAED,2GAA2G;AAC3G,SAAS,sBAAsB,CAAC,KAAa,EAAE,IAAU,EAAE,OAAe;IACxE,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9E,OAAO,CACL,iBAAiB,KAAK,mCAAmC,OAAO,qBAAqB,KAAK,yBAAyB;QACnH,wBAAwB,OAAO,4CAA4C,CAC5E,CAAC;AACJ,CAAC;AAED,0GAA0G;AAC1G,SAAS,eAAe,CAAC,KAAa,EAAE,OAAe;IACrD,OAAO,CACL,iBAAiB,KAAK,wDAAwD;QAC9E,oBAAoB,OAAO,wCAAwC;QACnE,wBAAwB,OAAO,iDAAiD,CACjF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAA4B,EAC5B,QAAqB,EACrB,OAAe;IAEf,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACvF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,CACL,SAAS,GAAG,8DAA8D;QAC1E,sBAAsB,GAAG,YAAY,OAAO,wBAAwB;QACpE,8EAA8E,CAC/E,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAA4B,EAC5B,QAAqB,EACrB,OAAe,EACf,WAAmB;IAEnB,+FAA+F;IAC/F,6FAA6F;IAC7F,qFAAqF;IACrF,+CAA+C;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QACtC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;QAC3C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE;YAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,2FAA2F;IAC3F,gGAAgG;IAChG,6FAA6F;IAC7F,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CACL,kBAAkB,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,CAAC;gBACpD,kBAAkB,GAAG,yBAAyB,OAAO,8BAA8B;oBACnF,GAAG,WAAW,iCAAiC,OAAO,WAAW;oBACjE,oFAAoF;oBACpF,oCAAoC,OAAO,eAAe,GAAG,KAAK;oBAClE,kCAAkC,OAAO,iDAAiD,CAC3F,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CACzB,KAA8B,EAC9B,GAAW,EACX,OAAe,EACf,WAAmB;IAEnB,MAAM,OAAO,GAAG,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC;IAC1F,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,OAAO,CACL,gBAAgB,OAAO,CAAC,IAAI,yBAAyB,OAAO,iCAAiC;QAC7F,GAAG,OAAO,CAAC,SAAS,8DAA8D,WAAW,MAAM;QACnG,6FAA6F;QAC7F,GAAG,OAAO,CAAC,WAAW,IAAI;QAC1B,wBAAwB,OAAO,iDAAiD,CACjF,CAAC;AACJ,CAAC"}
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
* [--format <fmt>[:<path>]]
|
|
13
13
|
*/
|
|
14
14
|
/**
|
|
15
|
-
* The legacy-`--json` guard at the CLI edge
|
|
15
|
+
* The legacy-`--json` guard at the CLI edge. The earlier
|
|
16
16
|
* `--json <path>` flag is removed; supplying it must fail fast with a migration hint to
|
|
17
17
|
* `--format json:<path>`, so the removed flag never silently no-ops and drops output. PURE
|
|
18
18
|
* and `@unit`-testable: the removed flag is NOT a `--format` spec (planOutput never sees
|
|
@@ -22,8 +22,8 @@
|
|
|
22
22
|
*/
|
|
23
23
|
export declare function checkLegacyJson(args: Record<string, string>): string | null;
|
|
24
24
|
/**
|
|
25
|
-
* Source the provenance "Target repo:" name for a run
|
|
26
|
-
*
|
|
25
|
+
* Source the provenance "Target repo:" name for a run. The
|
|
26
|
+
* operator's `--target` is recorded VERBATIM — no resolution — defaulting to
|
|
27
27
|
* `"unknown-target"` when omitted (parallel to `sourceSha`'s `"unknown"`; the facts
|
|
28
28
|
* artefact is self-describing, so the line always renders). PURE and `@unit`-testable at
|
|
29
29
|
* the CLI edge, like `checkLegacyJson`. It never inspects `--features`: the prior
|
|
@@ -32,30 +32,48 @@ export declare function checkLegacyJson(args: Record<string, string>): string |
|
|
|
32
32
|
* explicit default.
|
|
33
33
|
*/
|
|
34
34
|
export declare function sourceTarget(args: Record<string, string>): string;
|
|
35
|
+
/**
|
|
36
|
+
* Guard the supplied input-file/dir flags at the CLI edge. A
|
|
37
|
+
* mistyped `--vitest` / `--cucumber` / `--features` / `--ci` / `--package-json`
|
|
38
|
+
* pointing at a non-existent path used to reconcile silently against ZERO evidence —
|
|
39
|
+
* a terrifying false all-red report meaning "you forgot the reports", not "your code
|
|
40
|
+
* is broken" (the dogfooding fault). These flags are Examples of ONE boundary
|
|
41
|
+
* rule: a supplied-but-absent input path is a hard error, and a flag added to the set
|
|
42
|
+
* inherits it rather than restating it. Scope is existence only
|
|
43
|
+
* (readability / file-vs-dir type-correctness out of scope; `exists` covers the dir
|
|
44
|
+
* flag and the file flags alike).
|
|
45
|
+
*
|
|
46
|
+
* PURE and `@unit`-testable like `checkLegacyJson` / `sourceTarget`: reads the parsed
|
|
47
|
+
* args + an injected `exists` fn (no fs), returns the FIRST supplied-but-absent
|
|
48
|
+
* `(flag, path)` as a typed error naming both — routed to stderr + a non-zero exit by
|
|
49
|
+
* `refuseUnreadableInputs` (the shared typed-error surface) — else null. An OMITTED flag is not an
|
|
50
|
+
* error (legitimately optional: simply no evidence of that kind).
|
|
51
|
+
*/
|
|
35
52
|
export declare function checkInputsExist(args: Record<string, string>, exists: (path: string) => boolean): string | null;
|
|
36
53
|
/**
|
|
37
|
-
* Guard the READABILITY of the supplied JSON inputs at the CLI edge
|
|
54
|
+
* Guard the READABILITY of the supplied JSON inputs at the CLI edge.
|
|
38
55
|
* `checkInputsExist` already guards their PRESENCE — but a path that is present yet
|
|
39
56
|
* UNPARSEABLE fell straight through it: the reader threw mid-parse, nothing caught it, and
|
|
40
57
|
* the process hit Node's default exit 1 — the code reserved for a genuine OUT-OF-BALANCE
|
|
41
58
|
* verdict. A crashed invocation was therefore indistinguishable, by exit code, from an
|
|
42
|
-
* honest disagreement
|
|
43
|
-
* sibling to a missing path
|
|
59
|
+
* honest disagreement. An input the tool cannot read is a USAGE fault: exit 2,
|
|
60
|
+
* sibling to a missing path and an unrecognised flag.
|
|
44
61
|
*
|
|
45
62
|
* PURE and `@unit`-testable like its sibling guards: reads the parsed args + an injected
|
|
46
63
|
* `read` fn (no fs), returns the FIRST supplied-but-unparseable `(flag, path, failure)` as
|
|
47
|
-
* a typed error naming all three — routed to stderr + exit 2 by `
|
|
48
|
-
* An omitted flag is not an error, and
|
|
49
|
-
* check)
|
|
64
|
+
* a typed error naming all three — routed to stderr + exit 2 by `refuseUnreadableInputs` — else null.
|
|
65
|
+
* An omitted flag is not an error, and a file that cannot be read at all (a race after the
|
|
66
|
+
* existence check, a permission refused) is refused as one that could not be read, never as JSON
|
|
67
|
+
* that did not parse.
|
|
50
68
|
*/
|
|
51
69
|
export declare function checkInputsParse(args: Record<string, string>, read: (path: string) => string): string | null;
|
|
52
70
|
/**
|
|
53
|
-
* Guard the readability of `--render-from-json` at the CLI edge
|
|
71
|
+
* Guard the readability of `--render-from-json` at the CLI edge. The
|
|
54
72
|
* render-from-saved-JSON branch RETURNS before the input guards ever run, so it honoured
|
|
55
73
|
* NEITHER: a missing path crashed to `ENOENT` and a malformed file to `SyntaxError`, both
|
|
56
|
-
* landing on Node's default exit 1 — the out-of-balance code
|
|
74
|
+
* landing on Node's default exit 1 — the out-of-balance code.
|
|
57
75
|
*
|
|
58
|
-
* The missing-path case was a live violation of
|
|
76
|
+
* The missing-path case was a live violation of the missing-input rule's own shipped principle: a
|
|
59
77
|
* supplied input path that does not exist is a hard error at exit 2, enforced for the five
|
|
60
78
|
* evidence flags and not for this one. The CLI shipped a guard that half-honoured its Rule.
|
|
61
79
|
*
|
|
@@ -66,5 +84,5 @@ export declare function checkInputsParse(args: Record<string, string>, read: (pa
|
|
|
66
84
|
* not an error (the ordinary reconcile path).
|
|
67
85
|
*/
|
|
68
86
|
export declare function checkRenderFromJson(args: Record<string, string>, read: (path: string) => string): string | null;
|
|
69
|
-
export declare function runBalance(argv: string[]):
|
|
87
|
+
export declare function runBalance(argv: string[]): boolean;
|
|
70
88
|
//# sourceMappingURL=cli.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli-balance/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;
|
|
1
|
+
{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli-balance/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA4DH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAS3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEjE;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAChC,MAAM,GAAG,IAAI,CAcf;AAUD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,GAAG,IAAI,CAmBf;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,GAAG,IAAI,CAcf;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAwGlD"}
|