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.
Files changed (114) hide show
  1. package/README.md +34 -6
  2. package/dist/cli-allocate/cli.d.ts +2 -0
  3. package/dist/cli-allocate/cli.d.ts.map +1 -0
  4. package/dist/cli-allocate/cli.js +57 -0
  5. package/dist/cli-allocate/cli.js.map +1 -0
  6. package/dist/cli-allocate/readHistory.d.ts +29 -0
  7. package/dist/cli-allocate/readHistory.d.ts.map +1 -0
  8. package/dist/cli-allocate/readHistory.js +136 -0
  9. package/dist/cli-allocate/readHistory.js.map +1 -0
  10. package/dist/cli-allocate/readParts.d.ts +3 -0
  11. package/dist/cli-allocate/readParts.d.ts.map +1 -0
  12. package/dist/cli-allocate/readParts.js +28 -0
  13. package/dist/cli-allocate/readParts.js.map +1 -0
  14. package/dist/cli-allocate/readTree.d.ts +16 -0
  15. package/dist/cli-allocate/readTree.d.ts.map +1 -0
  16. package/dist/cli-allocate/readTree.js +106 -0
  17. package/dist/cli-allocate/readTree.js.map +1 -0
  18. package/dist/cli-allocate/refStore.d.ts +3 -0
  19. package/dist/cli-allocate/refStore.d.ts.map +1 -0
  20. package/dist/cli-allocate/refStore.js +47 -0
  21. package/dist/cli-allocate/refStore.js.map +1 -0
  22. package/dist/cli-allocate/request.d.ts +11 -0
  23. package/dist/cli-allocate/request.d.ts.map +1 -0
  24. package/dist/cli-allocate/request.js +29 -0
  25. package/dist/cli-allocate/request.js.map +1 -0
  26. package/dist/cli-allocate/stderr.d.ts +14 -0
  27. package/dist/cli-allocate/stderr.d.ts.map +1 -0
  28. package/dist/cli-allocate/stderr.js +33 -0
  29. package/dist/cli-allocate/stderr.js.map +1 -0
  30. package/dist/cli-allocate/unreadable.d.ts +24 -0
  31. package/dist/cli-allocate/unreadable.d.ts.map +1 -0
  32. package/dist/cli-allocate/unreadable.js +43 -0
  33. package/dist/cli-allocate/unreadable.js.map +1 -0
  34. package/dist/cli-args.d.ts +73 -18
  35. package/dist/cli-args.d.ts.map +1 -1
  36. package/dist/cli-args.js +244 -22
  37. package/dist/cli-args.js.map +1 -1
  38. package/dist/cli-balance/cli.d.ts +31 -13
  39. package/dist/cli-balance/cli.d.ts.map +1 -1
  40. package/dist/cli-balance/cli.js +205 -251
  41. package/dist/cli-balance/cli.js.map +1 -1
  42. package/dist/cli-balance/emit/writer.d.ts +8 -23
  43. package/dist/cli-balance/emit/writer.d.ts.map +1 -1
  44. package/dist/cli-balance/emit/writer.js +24 -32
  45. package/dist/cli-balance/emit/writer.js.map +1 -1
  46. package/dist/cli-balance/exitStatus.d.ts +3 -0
  47. package/dist/cli-balance/exitStatus.d.ts.map +1 -0
  48. package/dist/cli-balance/exitStatus.js +12 -0
  49. package/dist/cli-balance/exitStatus.js.map +1 -0
  50. package/dist/cli-balance/reRender.d.ts +22 -0
  51. package/dist/cli-balance/reRender.d.ts.map +1 -0
  52. package/dist/cli-balance/reRender.js +36 -0
  53. package/dist/cli-balance/reRender.js.map +1 -0
  54. package/dist/cli-balance/unreadableInputs.d.ts +35 -0
  55. package/dist/cli-balance/unreadableInputs.d.ts.map +1 -0
  56. package/dist/cli-balance/unreadableInputs.js +101 -0
  57. package/dist/cli-balance/unreadableInputs.js.map +1 -0
  58. package/dist/cli-registry.d.ts +28 -0
  59. package/dist/cli-registry.d.ts.map +1 -1
  60. package/dist/cli-registry.js +40 -35
  61. package/dist/cli-registry.js.map +1 -1
  62. package/dist/cli.d.ts +4 -5
  63. package/dist/cli.d.ts.map +1 -1
  64. package/dist/cli.js +37 -21
  65. package/dist/cli.js.map +1 -1
  66. package/dist/host.d.ts +28 -3
  67. package/dist/host.d.ts.map +1 -1
  68. package/dist/host.js +137 -17
  69. package/dist/host.js.map +1 -1
  70. package/dist/ingest/gherkinValidation.d.ts +3 -7
  71. package/dist/ingest/gherkinValidation.d.ts.map +1 -1
  72. package/dist/ingest/gherkinValidation.js +3 -7
  73. package/dist/ingest/gherkinValidation.js.map +1 -1
  74. package/dist/ingest/ingestQualityChecks.d.ts +25 -54
  75. package/dist/ingest/ingestQualityChecks.d.ts.map +1 -1
  76. package/dist/ingest/ingestQualityChecks.js +112 -145
  77. package/dist/ingest/ingestQualityChecks.js.map +1 -1
  78. package/dist/ingest/ingestScenarios.d.ts +11 -17
  79. package/dist/ingest/ingestScenarios.d.ts.map +1 -1
  80. package/dist/ingest/ingestScenarios.js +52 -62
  81. package/dist/ingest/ingestScenarios.js.map +1 -1
  82. package/dist/ingest/inputShapes.d.ts +47 -0
  83. package/dist/ingest/inputShapes.d.ts.map +1 -0
  84. package/dist/ingest/inputShapes.js +143 -0
  85. package/dist/ingest/inputShapes.js.map +1 -0
  86. package/dist/outputLocation.d.ts +15 -0
  87. package/dist/outputLocation.d.ts.map +1 -0
  88. package/dist/outputLocation.js +39 -0
  89. package/dist/outputLocation.js.map +1 -0
  90. package/dist/run-management/keptRun.d.ts +27 -25
  91. package/dist/run-management/keptRun.d.ts.map +1 -1
  92. package/dist/run-management/keptRun.js +20 -21
  93. package/dist/run-management/keptRun.js.map +1 -1
  94. package/dist/storedRun.d.ts +27 -0
  95. package/dist/storedRun.d.ts.map +1 -0
  96. package/dist/storedRun.js +49 -0
  97. package/dist/storedRun.js.map +1 -0
  98. package/package.json +2 -2
  99. package/dist/corpus/cli.d.ts +0 -34
  100. package/dist/corpus/cli.d.ts.map +0 -1
  101. package/dist/corpus/cli.js +0 -128
  102. package/dist/corpus/cli.js.map +0 -1
  103. package/dist/mutation-ratchet/index.d.ts +0 -51
  104. package/dist/mutation-ratchet/index.d.ts.map +0 -1
  105. package/dist/mutation-ratchet/index.js +0 -51
  106. package/dist/mutation-ratchet/index.js.map +0 -1
  107. package/dist/mutation-ratchet/record.d.ts +0 -178
  108. package/dist/mutation-ratchet/record.d.ts.map +0 -1
  109. package/dist/mutation-ratchet/record.js +0 -314
  110. package/dist/mutation-ratchet/record.js.map +0 -1
  111. package/dist/mutation-ratchet/report.d.ts +0 -109
  112. package/dist/mutation-ratchet/report.d.ts.map +0 -1
  113. package/dist/mutation-ratchet/report.js +0 -156
  114. 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 (3F-3300). Both halves lived inside `cli-balance/cli.ts` while
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` (3F-3298). @SCN-CLI-009's scenario is unchanged and still
16
- * asks about `balance`: what a second command gets is the same bounding BY CONSTRUCTION, and the
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, including a
28
- * flag no registry names; `checkUnknownFlags` below is what turns that into a usage error. The
29
- * split is deliberate — the parse has no opinion about which command it is reading for, and the
30
- * bounding has nothing else to do.
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 registry-bounded flag check at a command's CLI edge (@SCN-CLI-009). A command accepts ONLY
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, NOT silently swallowed the way the
54
- * permissive parse above would leave it. This is the structural teeth behind "accepted = registry
55
- * = help": a flag cannot affect behaviour without a registry entry, and so (by @SCN-CLI-008's
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 never reach
62
- * here: the top-level dispatcher consumes them BEFORE any command is dispatched, so a bounded
63
- * parse sees only the command's own args.
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 (3F-3105, @SCN-SLF-008).
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 (`Unknown flag --${key} for 'spec-controller ${command}' — this is spec-controller ` +
106
- `${toolVersion}, and that flag is not in its ${command} scope.\n` +
107
- `If this version is pinned, the pin and the tree it is reading have drifted apart: ` +
108
- `bump the pin to a version whose '${command}' accepts --${key}.\n` +
109
- `Otherwise run 'spec-controller ${command} --help' to see the flags this version accepts.`);
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
@@ -1 +1 @@
1
- {"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;;;;;;;;GAWG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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,GAAG,yBAAyB,OAAO,8BAA8B;gBACnF,GAAG,WAAW,iCAAiC,OAAO,WAAW;gBACjE,oFAAoF;gBACpF,oCAAoC,OAAO,eAAe,GAAG,KAAK;gBAClE,kCAAkC,OAAO,iDAAiD,CAC3F,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
1
+ {"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"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"}
@@ -12,7 +12,7 @@
12
12
  * [--format <fmt>[:<path>]]
13
13
  */
14
14
  /**
15
- * The legacy-`--json` guard at the CLI edge (@SCN-FMT-006). The earlier
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 (@SCN-RPT-001 Update —
26
- * Fork A). The operator's `--target` is recorded VERBATIM — no resolution — defaulting to
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 (@SCN-CLI-014).
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 (3F-1742). An input the tool cannot read is a USAGE fault: exit 2,
43
- * sibling to a missing path (@SCN-CLI-002) and an unrecognised flag (@SCN-CLI-009).
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 `runBalance` — else null.
48
- * An omitted flag is not an error, and an unreadable file (a race after the existence
49
- * check) reports as the same input fault rather than escaping as a crash.
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 (@SCN-CLI-015). The
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 (3F-1764).
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 @SCN-CLI-002's own shipped principle: a
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[]): void;
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;AAiDH;;;;;;;;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;AAuCD,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;AAYD;;;;;;;;;;;;;;GAcG;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,CAef;AAED;;;;;;;;;;;;;;;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,IAAI,CAsR/C"}
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"}