Vihren Atlas

lib/validation.ts

520 LOC · 520 covered · 0 uncovered · 125 ranges · 1119 concepts · 59 introducers · 788 tests

File neighbourhood

The centred file is linked to every concept that introduces one of its ranges, every test that runs code from the file, and the gray connector concepts standing between those tests and the file's own introducer concepts. Undirected links join concepts to every file where they introduce source and concepts to the tests they introduce; arrows show specialization between the displayed concepts and bridge only concepts omitted from this view. Concept colors match the source ranges below; connector concepts have no source color and are shown in gray.

Focused file, its introducer and connector concepts, their introduced files, and tests that run code from the file

In the embedded map, ordinary wheel input scrolls the page; use the visible controls to zoom and drag to pan. Open the full-screen map for canvas navigation: wheel pans, Ctrl/Command plus wheel zooms, and arrow keys pan when this region is focused. On touch screens, open the full-screen map to pan or pinch. If JavaScript or WebGL is unavailable, use the related-file, concept, and source links on this page.

Graph controls are ready.

Interactive rendering requires JavaScript and WebGL. Use the related-file, concept, and source links on this page while the interactive map is unavailable.

Files sharing a concept 11

A concept that introduces code in this file also introduces code in these files.

Files with a broader (ancestor) concept 9

These files introduce code for a direct ancestor — a broader, larger-extent concept — of a concept that introduces code here.

Files with a narrower (descendant) concept 16

These files introduce code for a direct descendant — a narrower, larger-intent concept — of a concept that introduces code here.

1 > import {argsert} from './argsert.js'; yargs-factory.ts ×124
2 > import {
3 > Dictionary,
4 > assertNotStrictEqual,
5 > PlatformShim,
6 > } from './typings/common-types.js';
7 > import {levenshtein as distance} from './utils/levenshtein.js';
8 > import {objFilter} from './utils/obj-filter.js';
9 > import {UsageInstance} from './usage.js';
10 > import {YargsInstance, Arguments} from './yargs-factory.js';
11 > import {DetailedArguments} from './typings/yargs-parser-types.js';
12 >
13 > const specialKeys = ['$0', '--', '_'];
14 >
15 > // validation-type-stuff, missing params,
16 > // bad implications:
17 > export function validation(
18 > yargs: YargsInstance, yargs-factory.ts ×35
19 > usage: UsageInstance,
20 > shim: PlatformShim
21 > ) {
22 > const __ = shim.y18n.__;
23 > const __n = shim.y18n.__n;
24 > const self = {} as ValidationInstance;
25 >
26 > // validate appropriate # of non-option
27 > // arguments were provided, i.e., '_'.
28 > self.nonOptionCount = function nonOptionCount(argv) {
29 > const demandedCommands = yargs.getDemandedCommands(); validation.ts ×4
30 > // don't count currently executing commands
31 > const positionalCount =
32 > argv._.length + (argv['--'] ? argv['--'].length : 0);
33 > const _s =
34 > positionalCount - yargs.getInternalMethods().getContext().commands.length;
35 >
36 > if (
37 > demandedCommands._ &&
38 > (_s < demandedCommands._.min || _s > demandedCommands._.max) validation.ts ×1
39 > ) { validation.ts ×4
40 > if (_s < demandedCommands._.min) { validation.ts ×3
41 > if (demandedCommands._.minMsg !== undefined) { validation.ts ×2
42 > usage.fail( validation.ts ×2
43 > // replace $0 with observed, $1 with expected.
44 > demandedCommands._.minMsg
45 > ? demandedCommands._.minMsg
46 > .replace(/\$0/g, _s.toString()) validation.ts ×1
47 > .replace(/\$1/, demandedCommands._.min.toString())
48 > : null validation.ts ×2
49 > );
50 > } else { validation.ts ×2
51 > usage.fail( validation.ts ×1
52 > __n(
53 > 'Not enough non-option arguments: got %s, need at least %s',
54 > 'Not enough non-option arguments: got %s, need at least %s',
55 > _s,
56 > _s.toString(),
57 > demandedCommands._.min.toString()
58 > )
59 > );
60 > }
61 > } else if (_s > demandedCommands._.max) { validation.ts ×3
62 > if (demandedCommands._.maxMsg !== undefined) { validation.ts ×3
63 > usage.fail( validation.ts ×1
64 > // replace $0 with observed, $1 with expected.
65 > demandedCommands._.maxMsg
66 > ? demandedCommands._.maxMsg
67 > .replace(/\$0/g, _s.toString())
68 > .replace(/\$1/, demandedCommands._.max.toString())
69 > : null
70 > );
71 > } else { validation.ts ×3
72 > usage.fail( validation.ts ×1
73 > __n(
74 > 'Too many non-option arguments: got %s, maximum of %s',
75 > 'Too many non-option arguments: got %s, maximum of %s',
76 > _s,
77 > _s.toString(),
78 > demandedCommands._.max.toString()
79 > )
80 > );
81 > }
82 > } validation.ts ×3
83 > } validation.ts ×3
84 > }; yargs-factory.ts ×35
85 >
86 > // validate the appropriate # of <required>
87 > // positional arguments were provided:
88 > self.positionalCount = function positionalCount(required, observed) {
89 > if (observed < required) { command.ts ×8
90 > usage.fail( validation.ts ×1
91 > __n(
92 > 'Not enough non-option arguments: got %s, need at least %s',
93 > 'Not enough non-option arguments: got %s, need at least %s',
94 > observed,
95 > observed + '',
96 > required + ''
97 > )
98 > );
99 > }
100 > }; yargs-factory.ts ×35
101 >
102 > // make sure all the required arguments are present.
103 > self.requiredArguments = function requiredArguments(
104 > argv, validation.ts ×4
105 > demandedOptions: Dictionary<string | undefined>
106 > ) {
107 > let missing: Dictionary<string | undefined> | null = null;
108 >
109 > for (const key of Object.keys(demandedOptions)) {
110 > if ( validation.ts ×3
111 > !Object.prototype.hasOwnProperty.call(argv, key) ||
112 > typeof argv[key] === 'undefined' validation.ts ×1
113 > ) { validation.ts ×3
114 > missing = missing || {}; validation.ts ×3
115 > missing[key] = demandedOptions[key];
116 > }
117 > } validation.ts ×3
118 > validation.ts ×4
119 > if (missing) {
120 > const customMsgs: string[] = []; validation.ts ×3
121 > for (const key of Object.keys(missing)) {
122 > const msg = missing[key];
123 > if (msg && customMsgs.indexOf(msg) < 0) {
124 > customMsgs.push(msg); validation.ts ×1
125 > }
126 > } validation.ts ×3
127 >
128 > const customMsg = customMsgs.length ? `\n${customMsgs.join('\n')}` : '';
129 > usage.fail(
130 > __n(
131 > 'Missing required argument: %s',
132 > 'Missing required arguments: %s',
133 > Object.keys(missing).length,
134 > Object.keys(missing).join(', ') + customMsg
135 > )
136 > );
137 > }
138 > }; yargs-factory.ts ×35
139 >
140 > // check for unknown arguments (strict-mode).
141 > self.unknownArguments = function unknownArguments(
142 > argv, validation.ts ×7
143 > aliases,
144 > positionalMap,
145 > isDefaultCommand,
146 > checkPositionals = true
147 > ) {
148 > const commandKeys = yargs
149 > .getInternalMethods()
150 > .getCommandInstance()
151 > .getCommands();
152 > const unknown: string[] = [];
153 > const currentContext = yargs.getInternalMethods().getContext();
154 >
155 > Object.keys(argv).forEach(key => {
156 > if (
157 > !specialKeys.includes(key) &&
158 > !Object.prototype.hasOwnProperty.call(positionalMap, key) &&
159 > !Object.prototype.hasOwnProperty.call( validation.ts ×1
160 > yargs.getInternalMethods().getParseContext(),
161 > key
162 > ) && validation.ts ×7
163 > !self.isValidAndSomeAliasIsNotNew(key, aliases) validation.ts ×2
164 > ) { validation.ts ×7
165 > unknown.push(key); validation.ts ×1
166 > }
167 > }); validation.ts ×7
168 >
169 > if (
170 > checkPositionals &&
171 > (currentContext.commands.length > 0 || validation.ts ×3
172 > commandKeys.length > 0 ||
173 > isDefaultCommand)
174 > ) { validation.ts ×7
175 > argv._.slice(currentContext.commands.length).forEach(key => { validation.ts ×2
176 > if (!commandKeys.includes('' + key)) { validation.ts ×1
177 > unknown.push('' + key);
178 > }
179 > }); validation.ts ×2
180 > }
181 > validation.ts ×7
182 > // https://github.com/yargs/yargs/issues/1861
183 > if (checkPositionals) {
184 > // Check for non-option args that are not in currentContext.commands validation.ts ×3
185 > // Take into account expected args from commands and yargs.demand(number)
186 > const demandedCommands = yargs.getDemandedCommands();
187 > const maxNonOptDemanded = demandedCommands._?.max || 0;
188 > const expected = currentContext.commands.length + maxNonOptDemanded;
189 > if (expected < argv._.length) {
190 > argv._.slice(expected).forEach(key => { validation.ts ×2
191 > key = String(key);
192 > if (
193 > !currentContext.commands.includes(key) &&
194 > !unknown.includes(key)
195 > ) {
196 > unknown.push(key); validation.ts ×1
197 > }
198 > }); validation.ts ×2
199 > }
200 > } validation.ts ×3
201 > validation.ts ×7
202 > if (unknown.length) {
203 > usage.fail( validation.ts ×1
204 > __n(
205 > 'Unknown argument: %s',
206 > 'Unknown arguments: %s',
207 > unknown.length,
208 > unknown.map(s => (s.trim() ? s : `"${s}"`)).join(', ')
209 > )
210 > );
211 > }
212 > }; yargs-factory.ts ×35
213 >
214 > self.unknownCommands = function unknownCommands(argv) {
215 > const commandKeys = yargs validation.ts ×3
216 > .getInternalMethods()
217 > .getCommandInstance()
218 > .getCommands();
219 > const unknown: string[] = [];
220 > const currentContext = yargs.getInternalMethods().getContext();
221 >
222 > if (currentContext.commands.length > 0 || commandKeys.length > 0) {
223 > argv._.slice(currentContext.commands.length).forEach(key => {
224 > if (!commandKeys.includes('' + key)) { validation.ts ×2
225 > unknown.push('' + key);
226 > }
227 > }); validation.ts ×3
228 > }
229 >
230 > if (unknown.length > 0) {
231 > usage.fail( validation.ts ×2
232 > __n(
233 > 'Unknown command: %s',
234 > 'Unknown commands: %s',
235 > unknown.length,
236 > unknown.join(', ')
237 > )
238 > );
239 > return true;
240 > } else { validation.ts ×3
241 > return false; validation.ts ×1
242 > }
243 > }; yargs-factory.ts ×35
244 >
245 > // check for a key that is not an alias, or for which every alias is new,
246 > // implying that it was invented by the parser, e.g., during camelization
247 > self.isValidAndSomeAliasIsNotNew = function isValidAndSomeAliasIsNotNew(
248 > key, validation.ts ×2
249 > aliases
250 > ) {
251 > if (!Object.prototype.hasOwnProperty.call(aliases, key)) {
252 > return false; validation.ts ×1
253 > }
254 > const newAliases = (yargs.parsed as DetailedArguments).newAliases; validation.ts ×1
255 > return [key, ...aliases[key]].some(
256 > a =>
257 > !Object.prototype.hasOwnProperty.call(newAliases, a) || !newAliases[key]
258 > );
259 > }; yargs-factory.ts ×35
260 >
261 > // validate arguments limited to enumerated choices
262 > self.limitedChoices = function limitedChoices(argv) {
263 > const options = yargs.getOptions(); yargs-factory.ts ×2
264 > const invalid: Dictionary<any[]> = {};
265 >
266 > if (!Object.keys(options.choices).length) return;
267 > validation.ts ×3
268 > Object.keys(argv).forEach(key => {
269 > if (
270 > specialKeys.indexOf(key) === -1 &&
271 > Object.prototype.hasOwnProperty.call(options.choices, key) validation.ts ×1
272 > ) { validation.ts ×3
273 > [].concat(argv[key]).forEach(value => { validation.ts ×3
274 > // TODO case-insensitive configurability
275 > if (
276 > options.choices[key].indexOf(value) === -1 &&
277 > value !== undefined validation.ts ×3
278 > ) { validation.ts ×3
279 > invalid[key] = (invalid[key] || []).concat(value); validation.ts ×3
280 > }
281 > }); validation.ts ×3
282 > }
283 > }); validation.ts ×3
284 >
285 > const invalidKeys = Object.keys(invalid);
286 >
287 > if (!invalidKeys.length) return;
288 > validation.ts ×3
289 > let msg = __('Invalid values:');
290 > invalidKeys.forEach(key => {
291 > msg += `\n ${__(
292 > 'Argument: %s, Given: %s, Choices: %s',
293 > key,
294 > usage.stringifiedValues(invalid[key]),
295 > usage.stringifiedValues(options.choices[key])
296 > )}`;
297 > });
298 > usage.fail(msg);
299 > }; yargs-factory.ts ×35
300 >
301 > // check implications, argument foo implies => argument bar.
302 > let implied: Dictionary<KeyOrPos[]> = {};
303 > self.implies = function implies(key, value) {
304 > argsert( validation.ts ×3
305 > '<string|object> [array|number|string]',
306 > [key, value],
307 > arguments.length
308 > );
309 >
310 > if (typeof key === 'object') {
311 > Object.keys(key).forEach(k => { validation.ts ×1
312 > self.implies(k, key[k]);
313 > });
314 > } else { validation.ts ×3
315 > yargs.global(key);
316 > if (!implied[key]) {
317 > implied[key] = [];
318 > }
319 > if (Array.isArray(value)) {
320 > value.forEach(i => self.implies(key, i)); validation.ts ×1
321 > } else { validation.ts ×3
322 > assertNotStrictEqual(value, undefined, shim);
323 > implied[key].push(value);
324 > }
325 > }
326 > }; yargs-factory.ts ×35
327 > self.getImplied = function getImplied() {
328 > return implied; validation.ts ×1
329 > }; yargs-factory.ts ×35
330 >
331 > function keyExists(argv: Arguments, val: any): any {
332 > // convert string '1' to number 1 validation.ts ×5
333 > const num = Number(val);
334 > val = isNaN(num) ? val : num;
335 >
336 > if (typeof val === 'number') {
337 > // check length of argv._ validation.ts ×1
338 > val = argv._.length >= val;
339 > } else if (val.match(/^--no-.+/)) { validation.ts ×5
340 > // check if key/value doesn't exist validation.ts ×1
341 > val = val.match(/^--no-(.+)/)[1];
342 > val = !Object.prototype.hasOwnProperty.call(argv, val);
343 > } else { validation.ts ×5
344 > // check if key/value exists
345 > val = Object.prototype.hasOwnProperty.call(argv, val);
346 > }
347 > return val;
348 > }
349 > yargs-factory.ts ×35
350 > self.implications = function implications(argv) {
351 > const implyFail: string[] = []; validation.ts ×4
352 >
353 > Object.keys(implied).forEach(key => {
354 > const origKey = key; validation.ts ×5
355 > (implied[key] || []).forEach(value => {
356 > let key = origKey;
357 > const origValue = value;
358 > key = keyExists(argv, key);
359 > value = keyExists(argv, value);
360 >
361 > if (key && !value) {
362 > implyFail.push(` ${origKey} -> ${origValue}`); validation.ts ×2
363 > }
364 > }); validation.ts ×5
365 > }); validation.ts ×4
366 >
367 > if (implyFail.length) {
368 > let msg = `${__('Implications failed:')}\n`; validation.ts ×2
369 >
370 > implyFail.forEach(value => {
371 > msg += value;
372 > });
373 >
374 > usage.fail(msg);
375 > }
376 > }; yargs-factory.ts ×35
377 >
378 > let conflicting: Dictionary<(string | undefined)[]> = {};
379 > self.conflicts = function conflicts(key, value) {
380 > argsert('<string|object> [array|string]', [key, value], arguments.length); validation.ts ×3
381 >
382 > if (typeof key === 'object') {
383 > Object.keys(key).forEach(k => { validation.ts ×1
384 > self.conflicts(k, key[k]);
385 > });
386 > } else { validation.ts ×3
387 > yargs.global(key);
388 > if (!conflicting[key]) {
389 > conflicting[key] = [];
390 > }
391 > if (Array.isArray(value)) {
392 > value.forEach(i => self.conflicts(key, i)); validation.ts ×1
393 > } else { validation.ts ×3
394 > conflicting[key].push(value);
395 > }
396 > }
397 > }; yargs-factory.ts ×35
398 > self.getConflicting = () => conflicting;
399 >
400 > self.conflicting = function conflictingFn(argv) {
401 > Object.keys(argv).forEach(key => { validation.ts ×4
402 > if (conflicting[key]) {
403 > conflicting[key].forEach(value => { validation.ts ×2
404 > // we default keys to 'undefined' that have been configured, we should not
405 > // apply conflicting check unless they are a value other than 'undefined'.
406 > if (value && argv[key] !== undefined && argv[value] !== undefined) {
407 > usage.fail( validation.ts ×1
408 > __('Arguments %s and %s are mutually exclusive', key, value)
409 > );
410 > }
411 > }); validation.ts ×2
412 > }
413 > }); validation.ts ×4
414 >
415 > // When strip-dashed is true, match conflicts (kebab) with argv (camel)
416 > // Addresses: https://github.com/yargs/yargs/issues/1952
417 > if (yargs.getInternalMethods().getParserConfiguration()['strip-dashed']) {
418 > Object.keys(conflicting).forEach(key => { validation.ts ×2
419 > conflicting[key].forEach(value => { validation.ts ×1
420 > if (
421 > value &&
422 > argv[shim.Parser.camelCase(key)] !== undefined &&
423 > argv[shim.Parser.camelCase(value)] !== undefined
424 > ) {
425 > usage.fail(
426 > __('Arguments %s and %s are mutually exclusive', key, value)
427 > );
428 > }
429 > });
430 > }); validation.ts ×2
431 > }
432 > }; yargs-factory.ts ×35
433 >
434 > self.recommendCommands = function recommendCommands(cmd, potentialCommands) {
435 > const threshold = 3; // if it takes more than three edits, let's move on. levenshtein.ts ×2
436 > potentialCommands = potentialCommands.sort((a, b) => b.length - a.length);
437 >
438 > let recommended = null;
439 > let bestDistance = Infinity;
440 > for (
441 > let i = 0, candidate;
442 > (candidate = potentialCommands[i]) !== undefined;
443 > i++
444 > ) {
445 > const d = distance(cmd, candidate);
446 > if (d <= threshold && d < bestDistance) {
447 > bestDistance = d; validation.ts ×1
448 > recommended = candidate;
449 > }
450 > } levenshtein.ts ×2
451 > if (recommended) usage.fail(__('Did you mean %s?', recommended));
452 > }; yargs-factory.ts ×35
453 >
454 > self.reset = function reset(localLookup) {
455 > implied = objFilter(implied, k => !localLookup[k]); command.ts ×1
456 > conflicting = objFilter(conflicting, k => !localLookup[k]);
457 > return self;
458 > }; yargs-factory.ts ×35
459 >
460 > const frozens: FrozenValidationInstance[] = [];
461 > self.freeze = function freeze() {
462 > frozens.push({ yargs-factory.ts ×5
463 > implied,
464 > conflicting,
465 > });
466 > }; yargs-factory.ts ×35
467 > self.unfreeze = function unfreeze() {
468 > const frozen = frozens.pop(); yargs-factory.ts ×2
469 > assertNotStrictEqual(frozen, undefined, shim);
470 > ({implied, conflicting} = frozen);
471 > }; yargs-factory.ts ×35
472 >
473 > return self;
474 > }
475 > yargs-factory.ts ×124
476 > /** Instance of the validation module. */
477 > export interface ValidationInstance {
478 > conflicting(argv: Arguments): void;
479 > conflicts(
480 > key: string | Dictionary<string | string[]>,
481 > value?: string | string[]
482 > ): void;
483 > freeze(): void;
484 > getConflicting(): Dictionary<(string | undefined)[]>;
485 > getImplied(): Dictionary<KeyOrPos[]>;
486 > implications(argv: Arguments): void;
487 > implies(
488 > key: string | Dictionary<KeyOrPos | KeyOrPos[]>,
489 > value?: KeyOrPos | KeyOrPos[]
490 > ): void;
491 > isValidAndSomeAliasIsNotNew(
492 > key: string,
493 > aliases: DetailedArguments['aliases']
494 > ): boolean;
495 > limitedChoices(argv: Arguments): void;
496 > nonOptionCount(argv: Arguments): void;
497 > positionalCount(required: number, observed: number): void;
498 > recommendCommands(cmd: string, potentialCommands: string[]): void;
499 > requiredArguments(
500 > argv: Arguments,
501 > demandedOptions: Dictionary<string | undefined>
502 > ): void;
503 > reset(localLookup: Dictionary): ValidationInstance;
504 > unfreeze(): void;
505 > unknownArguments(
506 > argv: Arguments,
507 > aliases: DetailedArguments['aliases'],
508 > positionalMap: Dictionary,
509 > isDefaultCommand: boolean,
510 > checkPositionals?: boolean
511 > ): void;
512 > unknownCommands(argv: Arguments): boolean;
513 > }
514 >
515 > interface FrozenValidationInstance {
516 > implied: Dictionary<KeyOrPos[]>;
517 > conflicting: Dictionary<(string | undefined)[]>;
518 > }
519 >
520 > export type KeyOrPos = string | number;