@oclif/core 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.16.0](https://github.com/oclif/core/compare/v1.15.0...v1.16.0) (2022-08-24)
+
+
+### Features
+
+* support complex flag relationships ([#468](https://github.com/oclif/core/issues/468)) ([222d1f6](https://github.com/oclif/core/commit/222d1f67012557ac0707077d6c8840966dbf00cb))
+
 ## [1.15.0](https://github.com/oclif/core/compare/v1.14.2...v1.15.0) (2022-08-23)
 
 

package/lib/config/config.js

@@ -660,6 +660,7 @@ async function toCached(c, plugin) {
                 multiple: flag.multiple,
                 options: flag.options,
                 dependsOn: flag.dependsOn,
+                relationships: flag.relationships,
                 exclusive: flag.exclusive,
                 default: await defaultToCached(flag),
             };

package/lib/interfaces/parser.d.ts

@@ -84,6 +84,14 @@ export declare type DefaultContext<T, P> = {
 };
 export declare type Default<T, P = Record<string, unknown>> = T | ((context: DefaultContext<T, P>) => Promise<T>);
 export declare type DefaultHelp<T, P = Record<string, unknown>> = T | ((context: DefaultContext<T, P>) => Promise<string | undefined>);
+export declare type FlagRelationship = string | {
+    name: string;
+    when: (flags: Record<string, unknown>) => Promise<boolean>;
+};
+export declare type Relationship = {
+    type: 'all' | 'some' | 'none';
+    flags: FlagRelationship[];
+};
 export declare type FlagProps = {
     name: string;
     char?: AlphabetLowercase | AlphabetUppercase;
@@ -131,6 +139,10 @@ export declare type FlagProps = {
      * Exactly one of these flags must be provided.
      */
     exactlyOne?: string[];
+    /**
+     * Define complex relationships between flags.
+     */
+    relationships?: Relationship[];
 };
 export declare type BooleanFlagProps = FlagProps & {
     type: 'boolean';

package/lib/parser/errors.d.ts

@@ -1,6 +1,12 @@
 import { CLIError } from '../errors';
 import { ParserArg, CLIParseErrorOptions, OptionFlag, Flag } from '../interfaces';
 export { CLIError } from '../errors';
+export declare type Validation = {
+    name: string;
+    status: 'success' | 'failed';
+    validationFn: string;
+    reason?: string;
+};
 export declare class CLIParseError extends CLIError {
     parse: CLIParseErrorOptions['parse'];
     constructor(options: CLIParseErrorOptions & {
@@ -37,3 +43,8 @@ export declare class FlagInvalidOptionError extends CLIParseError {
 export declare class ArgInvalidOptionError extends CLIParseError {
     constructor(arg: ParserArg<any>, input: string);
 }
+export declare class FailedFlagValidationError extends CLIParseError {
+    constructor({ parse, failed }: CLIParseErrorOptions & {
+        failed: Validation[];
+    });
+}

package/lib/parser/errors.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArgInvalidOptionError = exports.FlagInvalidOptionError = exports.UnexpectedArgsError = exports.RequiredFlagError = exports.RequiredArgsError = exports.InvalidArgsSpecError = exports.CLIParseError = exports.CLIError = void 0;
+exports.FailedFlagValidationError = exports.ArgInvalidOptionError = exports.FlagInvalidOptionError = exports.UnexpectedArgsError = exports.RequiredFlagError = exports.RequiredArgsError = exports.InvalidArgsSpecError = exports.CLIParseError = exports.CLIError = void 0;
 const errors_1 = require("../errors");
 const deps_1 = require("./deps");
+const util_1 = require("../config/util");
 var errors_2 = require("../errors");
 Object.defineProperty(exports, "CLIError", { enumerable: true, get: function () { return errors_2.CLIError; } });
 // eslint-disable-next-line new-cap
@@ -10,7 +11,8 @@ const m = (0, deps_1.default)()
     // eslint-disable-next-line node/no-missing-require
     .add('help', () => require('./help'))
     // eslint-disable-next-line node/no-missing-require
-    .add('list', () => require('./list'));
+    .add('list', () => require('./list'))
+    .add('chalk', () => require('chalk'));
 class CLIParseError extends errors_1.CLIError {
     constructor(options) {
         options.message += '\nSee more help with --help';
@@ -76,3 +78,13 @@ class ArgInvalidOptionError extends CLIParseError {
     }
 }
 exports.ArgInvalidOptionError = ArgInvalidOptionError;
+class FailedFlagValidationError extends CLIParseError {
+    constructor({ parse, failed }) {
+        const reasons = failed.map(r => r.reason);
+        const deduped = (0, util_1.uniq)(reasons);
+        const errString = deduped.length === 1 ? 'error' : 'errors';
+        const message = `The following ${errString} occurred:\n  ${m.chalk.dim(deduped.join('\n  '))}`;
+        super({ parse, message });
+    }
+}
+exports.FailedFlagValidationError = FailedFlagValidationError;

package/lib/parser/index.js

@@ -27,7 +27,7 @@ async function parse(argv, options) {
     };
     const parser = new parse_1.Parser(input);
     const output = await parser.parse();
-    m.validate({ input, output });
+    await m.validate({ input, output });
     return output;
 }
 exports.parse = parse;

package/lib/parser/validate.d.ts

@@ -2,4 +2,4 @@ import { ParserInput, ParserOutput } from '../interfaces';
 export declare function validate(parse: {
     input: ParserInput;
     output: ParserOutput;
-}): void;
+}): Promise<void>;

package/lib/parser/validate.js

@@ -1,14 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validate = void 0;
-const errors_1 = require("../errors");
-const errors_2 = require("./errors");
-function validate(parse) {
+const errors_1 = require("./errors");
+const util_1 = require("../config/util");
+async function validate(parse) {
     function validateArgs() {
         const maxArgs = parse.input.args.length;
         if (parse.input.strict && parse.output.argv.length > maxArgs) {
             const extras = parse.output.argv.slice(maxArgs);
-            throw new errors_2.UnexpectedArgsError({ parse, args: extras });
+            throw new errors_1.UnexpectedArgsError({ parse, args: extras });
         }
         const missingRequiredArgs = [];
         let hasOptional = false;
@@ -19,63 +19,138 @@ function validate(parse) {
             else if (hasOptional) {
                 // (required arg) check whether an optional has occurred before
                 // optionals should follow required, not before
-                throw new errors_2.InvalidArgsSpecError({ parse, args: parse.input.args });
+                throw new errors_1.InvalidArgsSpecError({ parse, args: parse.input.args });
             }
             if (arg.required && !parse.output.argv[index] && parse.output.argv[index] !== 0) {
                 missingRequiredArgs.push(arg);
             }
         }
         if (missingRequiredArgs.length > 0) {
-            throw new errors_2.RequiredArgsError({ parse, args: missingRequiredArgs });
+            throw new errors_1.RequiredArgsError({ parse, args: missingRequiredArgs });
         }
     }
+    async function validateFlags() {
+        const promises = Object.entries(parse.input.flags).map(async ([name, flag]) => {
+            const results = [];
+            if (parse.output.flags[name] !== undefined) {
+                results.push(...await validateRelationships(name, flag), await validateDependsOn(name, flag.dependsOn ?? []), await validateExclusive(name, flag.exclusive ?? []), await validateExactlyOne(name, flag.exactlyOne ?? []));
+            }
+            else if (flag.required) {
+                results.push({ status: 'failed', name, validationFn: 'required', reason: `Missing required flag ${name}` });
+            }
+            else if (flag.exactlyOne && flag.exactlyOne.length > 0) {
+                results.push(validateAcrossFlags(flag));
+            }
+            return results;
+        });
+        const results = (await Promise.all(promises)).flat();
+        const failed = results.filter(r => r.status === 'failed');
+        if (failed.length > 0)
+            throw new errors_1.FailedFlagValidationError({ parse, failed });
+    }
+    async function resolveFlags(flags) {
+        const promises = flags.map(async (flag) => {
+            if (typeof flag === 'string') {
+                return [flag, parse.output.flags[flag]];
+            }
+            const result = await flag.when(parse.output.flags);
+            return result ? [flag.name, parse.output.flags[flag.name]] : null;
+        });
+        const resolved = await Promise.all(promises);
+        return Object.fromEntries(resolved.filter(r => r !== null));
+    }
+    function getPresentFlags(flags) {
+        return Object.keys(flags).reduce((acc, key) => {
+            if (flags[key])
+                acc.push(key);
+            return acc;
+        }, []);
+    }
     function validateAcrossFlags(flag) {
+        const base = { name: flag.name, validationFn: 'validateAcrossFlags' };
         const intersection = Object.entries(parse.input.flags)
             .map(entry => entry[0]) // array of flag names
             .filter(flagName => parse.output.flags[flagName] !== undefined) // with values
             .filter(flagName => flag.exactlyOne && flag.exactlyOne.includes(flagName)); // and in the exactlyOne list
         if (intersection.length === 0) {
             // the command's exactlyOne may or may not include itself, so we'll use Set to add + de-dupe
-            throw new errors_1.CLIError(`Exactly one of the following must be provided: ${[
-                ...new Set(flag.exactlyOne?.map(flag => `--${flag}`)),
-            ].join(', ')}`);
+            const deduped = (0, util_1.uniq)(flag.exactlyOne?.map(flag => `--${flag}`) ?? []).join(', ');
+            const reason = `Exactly one of the following must be provided: ${deduped}`;
+            return { ...base, status: 'failed', reason };
         }
+        return { ...base, status: 'success' };
     }
-    function validateFlags() {
-        for (const [name, flag] of Object.entries(parse.input.flags)) {
-            if (parse.output.flags[name] !== undefined) {
-                for (const also of flag.dependsOn || []) {
-                    if (!parse.output.flags[also]) {
-                        throw new errors_1.CLIError(`--${also}= must also be provided when using --${name}=`);
-                    }
-                }
-                for (const also of flag.exclusive || []) {
-                    // do not enforce exclusivity for flags that were defaulted
-                    if (parse.output.metadata.flags[also] &&
-                        parse.output.metadata.flags[also].setFromDefault)
-                        continue;
-                    if (parse.output.metadata.flags[name] &&
-                        parse.output.metadata.flags[name].setFromDefault)
-                        continue;
-                    if (parse.output.flags[also]) {
-                        throw new errors_1.CLIError(`--${also}= cannot also be provided when using --${name}=`);
-                    }
-                }
-                for (const also of flag.exactlyOne || []) {
-                    if (also !== name && parse.output.flags[also]) {
-                        throw new errors_1.CLIError(`--${also}= cannot also be provided when using --${name}=`);
-                    }
-                }
+    async function validateExclusive(name, flags) {
+        const base = { name, validationFn: 'validateExclusive' };
+        const resolved = await resolveFlags(flags);
+        const keys = getPresentFlags(resolved);
+        for (const flag of keys) {
+            // do not enforce exclusivity for flags that were defaulted
+            if (parse.output.metadata.flags && parse.output.metadata.flags[flag]?.setFromDefault)
+                continue;
+            if (parse.output.metadata.flags && parse.output.metadata.flags[name]?.setFromDefault)
+                continue;
+            if (parse.output.flags[flag]) {
+                return { ...base, status: 'failed', reason: `--${flag}=${parse.output.flags[flag]} cannot also be provided when using --${name}` };
             }
-            else if (flag.required) {
-                throw new errors_2.RequiredFlagError({ parse, flag });
-            }
-            else if (flag.exactlyOne && flag.exactlyOne.length > 0) {
-                validateAcrossFlags(flag);
+        }
+        return { ...base, status: 'success' };
+    }
+    async function validateExactlyOne(name, flags) {
+        const base = { name, validationFn: 'validateExactlyOne' };
+        const resolved = await resolveFlags(flags);
+        const keys = getPresentFlags(resolved);
+        for (const flag of keys) {
+            if (flag !== name && parse.output.flags[flag]) {
+                return { ...base, status: 'failed', reason: `--${flag} cannot also be provided when using --${name}` };
             }
         }
+        return { ...base, status: 'success' };
+    }
+    async function validateDependsOn(name, flags) {
+        const base = { name, validationFn: 'validateDependsOn' };
+        const resolved = await resolveFlags(flags);
+        const foundAll = Object.values(resolved).every(Boolean);
+        if (!foundAll) {
+            const formattedFlags = Object.keys(resolved).map(f => `--${f}`).join(', ');
+            return { ...base, status: 'failed', reason: `All of the following must be provided when using --${name}: ${formattedFlags}` };
+        }
+        return { ...base, status: 'success' };
+    }
+    async function validateSome(name, flags) {
+        const base = { name, validationFn: 'validateSome' };
+        const resolved = await resolveFlags(flags);
+        const foundAtLeastOne = Object.values(resolved).some(Boolean);
+        if (!foundAtLeastOne) {
+            const formattedFlags = Object.keys(resolved).map(f => `--${f}`).join(', ');
+            return { ...base, status: 'failed', reason: `One of the following must be provided when using --${name}: ${formattedFlags}` };
+        }
+        return { ...base, status: 'success' };
+    }
+    async function validateRelationships(name, flag) {
+        if (!flag.relationships)
+            return [];
+        const results = await Promise.all(flag.relationships.map(async (relationship) => {
+            const flags = relationship.flags ?? [];
+            const results = [];
+            switch (relationship.type) {
+                case 'all':
+                    results.push(await validateDependsOn(name, flags));
+                    break;
+                case 'some':
+                    results.push(await validateSome(name, flags));
+                    break;
+                case 'none':
+                    results.push(await validateExclusive(name, flags));
+                    break;
+                default:
+                    break;
+            }
+            return results;
+        }));
+        return results.flat();
     }
     validateArgs();
-    validateFlags();
+    await validateFlags();
 }
 exports.validate = validate;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {