@oclif/core 2.8.12 → 2.9.0

package/lib/interfaces/parser.d.ts

@@ -48,7 +48,7 @@ export type Metadata = {
         [key: string]: MetadataFlag;
     };
 };
-type MetadataFlag = {
+export type MetadataFlag = {
     setFromDefault?: boolean;
     defaultHelp?: unknown;
 };
@@ -368,4 +368,3 @@ export type ArgInput<T extends ArgOutput = {
 }> = {
     [P in keyof T]: Arg<T[P]>;
 };
-export {};

package/lib/parser/parse.d.ts

@@ -6,17 +6,14 @@ export declare class Parser<T extends ParserInput, TFlags extends OutputFlags<T[
     private readonly booleanFlags;
     private readonly flagAliases;
     private readonly context;
-    private readonly metaData;
     private currentFlag?;
     constructor(input: T);
     parse(): Promise<ParserOutput<TFlags, BFlags, TArgs>>;
     private _flags;
-    private _parseFlag;
-    private _validateOptions;
     private _args;
     private _debugOutput;
     private _debugInput;
     private get _argTokens();
-    private get _flagTokens();
     private _setNames;
+    private mapAndValidateFlags;
 }

package/lib/parser/parse.js

@@ -63,7 +63,6 @@ class Parser {
         this.flagAliases = Object.fromEntries(Object.values(input.flags).flatMap(flag => {
             return (flag.aliases ?? []).map(a => [a, flag]);
         }));
-        this.metaData = {};
     }
     async parse() {
         this._debugInput();
@@ -163,8 +162,7 @@ class Parser {
             const arg = Object.keys(this.input.args)[this._argTokens.length];
             this.raw.push({ type: 'arg', arg, input });
         }
-        const { argv, args } = await this._args();
-        const flags = await this._flags();
+        const [{ argv, args }, { flags, metadata }] = await Promise.all([this._args(), this._flags()]);
         this._debugOutput(argv, args, flags);
         const unsortedArgv = (dashdash ? [...argv, ...nonExistentFlags, '--'] : [...argv, ...nonExistentFlags]);
         return {
@@ -172,113 +170,118 @@ class Parser {
             flags,
             args: args,
             raw: this.raw,
-            metadata: this.metaData,
+            metadata,
             nonExistentFlags,
         };
     }
-    // eslint-disable-next-line complexity
     async _flags() {
-        const flags = {};
-        this.metaData.flags = {};
-        for (const token of this._flagTokens) {
-            const flag = this.input.flags[token.flag];
-            if (!flag)
-                throw new errors_1.CLIError(`Unexpected flag ${token.flag}`);
-            if (flag.type === 'boolean') {
-                if (token.input === `--no-${flag.name}`) {
-                    flags[token.flag] = false;
-                }
-                else {
-                    flags[token.flag] = true;
+        const validateOptions = (flag, input) => {
+            if (flag.options && !flag.options.includes(input))
+                throw new errors_1.FlagInvalidOptionError(flag, input);
+            return input;
+        };
+        const parseFlagOrThrowError = async (input, flag, token, context = {}) => {
+            if (!flag.parse)
+                return input;
+            try {
+                if (flag.type === 'boolean') {
+                    return await flag.parse(input, { ...context, token }, flag);
                 }
-                flags[token.flag] = await this._parseFlag(flags[token.flag], flag, token);
+                return await flag.parse(input, { ...context, token }, flag);
             }
-            else {
-                const input = token.input;
-                if (flag.delimiter && flag.multiple) {
-                    // split, trim, and remove surrounding doubleQuotes (which would hav been needed if the elements contain spaces)
-                    const values = await Promise.all(input.split(flag.delimiter).map(async (v) => this._parseFlag(v.trim().replace(/^"(.*)"$/, '$1').replace(/^'(.*)'$/, '$1'), flag, token)));
-                    // then parse that each element aligns with the `options` property
-                    for (const v of values) {
-                        this._validateOptions(flag, v);
-                    }
-                    flags[token.flag] = flags[token.flag] || [];
-                    flags[token.flag].push(...values);
+            catch (error) {
+                error.message = `Parsing --${flag.name} \n\t${error.message}\nSee more help with --help`;
+                throw error;
+            }
+        };
+        /* Could add a valueFunction (if there is a value/env/default) and could metadata.
+        *  Value function can be resolved later.
+        */
+        const addValueFunction = (fws) => {
+            const tokenLength = fws.tokens?.length;
+            // user provided some input
+            if (tokenLength) {
+                // boolean
+                if (fws.inputFlag.flag.type === 'boolean' && fws.tokens?.at(-1)?.input) {
+                    return { ...fws, valueFunction: async (i) => parseFlagOrThrowError(i.tokens?.at(-1)?.input !== `--no-${i.inputFlag.name}`, i.inputFlag.flag, i.tokens?.at(-1), this.context) };
                 }
-                else {
-                    this._validateOptions(flag, input);
-                    const value = await this._parseFlag(input, flag, token);
-                    if (flag.multiple) {
-                        flags[token.flag] = flags[token.flag] || [];
-                        flags[token.flag].push(value);
-                    }
-                    else {
-                        flags[token.flag] = value;
-                    }
+                // multiple with custom delimiter
+                if (fws.inputFlag.flag.type === 'option' && fws.inputFlag.flag.delimiter && fws.inputFlag.flag.multiple) {
+                    return {
+                        ...fws, valueFunction: async (i) => (await Promise.all(((i.tokens ?? []).flatMap(token => token.input.split(i.inputFlag.flag.delimiter)))
+                            // trim, and remove surrounding doubleQuotes (which would hav been needed if the elements contain spaces)
+                            .map(v => v.trim().replace(/^"(.*)"$/, '$1').replace(/^'(.*)'$/, '$1'))
+                            .map(async (v) => parseFlagOrThrowError(v, i.inputFlag.flag, { ...i.tokens?.at(-1), input: v }, this.context)))).map(v => validateOptions(i.inputFlag.flag, v)),
+                    };
                 }
-            }
-        }
-        for (const k of Object.keys(this.input.flags)) {
-            const flag = this.input.flags[k];
-            if (flags[k])
-                continue;
-            if (flag.env && Reflect.has(process.env, flag.env)) {
-                const input = process.env[flag.env];
-                if (flag.type === 'option') {
-                    if (input) {
-                        this._validateOptions(flag, input);
-                        flags[k] = await this._parseFlag(input, flag);
-                    }
+                // multiple in the oclif-core style
+                if (fws.inputFlag.flag.type === 'option' && fws.inputFlag.flag.multiple) {
+                    return { ...fws, valueFunction: async (i) => Promise.all((fws.tokens ?? []).map(token => parseFlagOrThrowError(validateOptions(i.inputFlag.flag, token.input), i.inputFlag.flag, token, this.context))) };
                 }
-                else if (flag.type === 'boolean') {
-                    // eslint-disable-next-line no-negated-condition
-                    flags[k] = input !== undefined ? (0, util_1.isTruthy)(input) : false;
+                // simple option flag
+                if (fws.inputFlag.flag.type === 'option') {
+                    return { ...fws, valueFunction: async (i) => parseFlagOrThrowError(validateOptions(i.inputFlag.flag, fws.tokens?.at(-1)?.input), i.inputFlag.flag, fws.tokens?.at(-1), this.context) };
                 }
             }
-            if (!(k in flags) && flag.default !== undefined) {
-                this.metaData.flags[k] = { ...this.metaData.flags[k], setFromDefault: true };
-                const defaultValue = (typeof flag.default === 'function' ? await flag.default({ options: flag, flags }) : flag.default);
-                flags[k] = defaultValue;
-            }
-        }
-        for (const k of Object.keys(this.input.flags)) {
-            if ((k in flags) && Reflect.has(this.input.flags[k], 'defaultHelp')) {
-                try {
-                    const defaultHelpProperty = Reflect.get(this.input.flags[k], 'defaultHelp');
-                    const defaultHelp = (typeof defaultHelpProperty === 'function' ? await defaultHelpProperty({
-                        options: flags[k],
-                        flags, ...this.context,
-                    }) : defaultHelpProperty);
-                    this.metaData.flags[k] = { ...this.metaData.flags[k], defaultHelp };
+            // no input: env flags
+            if (fws.inputFlag.flag.env && process.env[fws.inputFlag.flag.env]) {
+                const valueFromEnv = process.env[fws.inputFlag.flag.env];
+                if (fws.inputFlag.flag.type === 'option' && valueFromEnv) {
+                    return { ...fws, valueFunction: async (i) => parseFlagOrThrowError(validateOptions(i.inputFlag.flag, valueFromEnv), i.inputFlag.flag, this.context) };
                 }
-                catch {
-                    // no-op
+                if (fws.inputFlag.flag.type === 'boolean') {
+                    return { ...fws, valueFunction: async (i) => Promise.resolve((0, util_1.isTruthy)(process.env[i.inputFlag.flag.env] ?? 'false')) };
                 }
             }
-        }
-        return flags;
-    }
-    async _parseFlag(input, flag, token) {
-        if (!flag.parse)
-            return input;
-        try {
-            const ctx = this.context;
-            ctx.token = token;
-            if (flag.type === 'boolean') {
-                const ctx = this.context;
-                ctx.token = token;
-                return await flag.parse(input, ctx, flag);
+            // no input, but flag has default value
+            if (typeof fws.inputFlag.flag.default !== undefined) {
+                return {
+                    ...fws, metadata: { setFromDefault: true },
+                    valueFunction: typeof fws.inputFlag.flag.default === 'function' ?
+                        (i, allFlags = {}) => fws.inputFlag.flag.default({ options: i.inputFlag.flag, flags: allFlags }) :
+                        async () => fws.inputFlag.flag.default,
+                };
             }
-            return flag.parse ? await flag.parse(input, ctx, flag) : input;
-        }
-        catch (error) {
-            error.message = `Parsing --${flag.name} \n\t${error.message}\nSee more help with --help`;
-            throw error;
-        }
-    }
-    _validateOptions(flag, input) {
-        if (flag.options && !flag.options.includes(input))
-            throw new errors_1.FlagInvalidOptionError(flag, input);
+            // base case (no value function)
+            return fws;
+        };
+        const addHelpFunction = (fws) => {
+            if (fws.inputFlag.flag.type === 'option' && fws.inputFlag.flag.defaultHelp) {
+                return {
+                    ...fws, helpFunction: typeof fws.inputFlag.flag.defaultHelp === 'function' ?
+                        // @ts-expect-error flag type isn't specific enough to know defaultHelp will definitely be there
+                        (i, flags, ...context) => i.inputFlag.flag.defaultHelp({ options: i.inputFlag, flags }, ...context) :
+                        // @ts-expect-error flag type isn't specific enough to know defaultHelp will definitely be there
+                        (i) => i.inputFlag.flag.defaultHelp,
+                };
+            }
+            return fws;
+        };
+        const addDefaultHelp = async (fws) => {
+            const valueReferenceForHelp = fwsArrayToObject(flagsWithAllValues.filter(fws => !fws.metadata?.setFromDefault));
+            return Promise.all(fws.map(async (fws) => fws.helpFunction ? ({ ...fws, metadata: { ...fws.metadata, defaultHelp: await fws.helpFunction?.(fws, valueReferenceForHelp, this.context) } }) : fws));
+        };
+        const fwsArrayToObject = (fwsArray) => Object.fromEntries(fwsArray.map(fws => [fws.inputFlag.name, fws.value]));
+        const flagTokenMap = this.mapAndValidateFlags();
+        const flagsWithValues = await Promise.all(Object.entries(this.input.flags)
+            // we check them if they have a token, or might have env, default, or defaultHelp.  Also include booleans so they get their default value
+            .filter(([name, flag]) => flag.type === 'boolean' || flag.env || flag.default || 'defaultHelp' in flag || flagTokenMap.has(name))
+            // match each possible flag to its token, if there is one
+            .map(([name, flag]) => ({ inputFlag: { name, flag }, tokens: flagTokenMap.get(name) }))
+            .map(fws => addValueFunction(fws))
+            .filter(fws => fws.valueFunction !== undefined)
+            .map(fws => addHelpFunction(fws))
+            // we can't apply the default values until all the other flags are resolved because `flag.default` can reference other flags
+            .map(async (fws) => (fws.metadata?.setFromDefault ? fws : { ...fws, value: await fws.valueFunction?.(fws) })));
+        const valueReference = fwsArrayToObject(flagsWithValues.filter(fws => !fws.metadata?.setFromDefault));
+        const flagsWithAllValues = await Promise.all(flagsWithValues
+            .map(async (fws) => (fws.metadata?.setFromDefault ? { ...fws, value: await fws.valueFunction?.(fws, valueReference) } : fws)));
+        const finalFlags = (flagsWithAllValues.some(fws => typeof fws.helpFunction === 'function')) ? await addDefaultHelp(flagsWithAllValues) : flagsWithAllValues;
+        return {
+            // @ts-ignore original version returned an any.  Not sure how to get to the return type for `flags` prop
+            flags: fwsArrayToObject(finalFlags),
+            metadata: { flags: Object.fromEntries(finalFlags.filter(fws => fws.metadata).map(fws => [fws.inputFlag.name, fws.metadata])) },
+        };
     }
     async _args() {
         const argv = [];
@@ -352,9 +355,6 @@ class Parser {
     get _argTokens() {
         return this.raw.filter(o => o.type === 'arg');
     }
-    get _flagTokens() {
-        return this.raw.filter(o => o.type === 'flag');
-    }
     _setNames() {
         for (const k of Object.keys(this.input.flags)) {
             this.input.flags[k].name = k;
@@ -363,5 +363,17 @@ class Parser {
             this.input.args[k].name = k;
         }
     }
+    mapAndValidateFlags() {
+        const flagTokenMap = new Map();
+        for (const token of this.raw.filter(o => o.type === 'flag')) {
+            // fail fast if there are any invalid flags
+            if (!(token.flag in this.input.flags)) {
+                throw new errors_1.CLIError(`Unexpected flag ${token.flag}`);
+            }
+            const existing = flagTokenMap.get(token.flag) ?? [];
+            flagTokenMap.set(token.flag, [...existing, token]);
+        }
+        return flagTokenMap;
+    }
 }
 exports.Parser = Parser;

package/lib/parser/validate.js

@@ -4,6 +4,7 @@ exports.validate = void 0;
 const errors_1 = require("./errors");
 const util_1 = require("../config/util");
 async function validate(parse) {
+    let cachedResolvedFlags;
     function validateArgs() {
         if (parse.output.nonExistentFlags?.length > 0) {
             throw new errors_1.NonExistentFlagsError({ parse, flags: parse.output.nonExistentFlags });
@@ -33,25 +34,31 @@ async function validate(parse) {
         }
     }
     async function validateFlags() {
-        const promises = Object.entries(parse.input.flags).map(async ([name, flag]) => {
-            const results = [];
+        const promises = Object.entries(parse.input.flags).flatMap(([name, flag]) => {
             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 ?? []));
+                return [
+                    ...flag.relationships ? validateRelationships(name, flag) : [],
+                    ...flag.dependsOn ? [validateDependsOn(name, flag.dependsOn)] : [],
+                    ...flag.exclusive ? [validateExclusive(name, flag.exclusive)] : [],
+                    ...flag.exactlyOne ? [validateExactlyOne(name, flag.exactlyOne)] : [],
+                ];
             }
-            else if (flag.required) {
-                results.push({ status: 'failed', name, validationFn: 'required', reason: `Missing required flag ${name}` });
+            if (flag.required) {
+                return [{ status: 'failed', name, validationFn: 'required', reason: `Missing required flag ${name}` }];
             }
-            else if (flag.exactlyOne && flag.exactlyOne.length > 0) {
-                results.push(validateAcrossFlags(flag));
+            if (flag.exactlyOne && flag.exactlyOne.length > 0) {
+                return [validateAcrossFlags(flag)];
             }
-            return results;
+            return [];
         });
-        const results = (await Promise.all(promises)).flat();
+        const results = (await Promise.all(promises));
         const failed = results.filter(r => r.status === 'failed');
         if (failed.length > 0)
             throw new errors_1.FailedFlagValidationError({ parse, failed });
     }
     async function resolveFlags(flags) {
+        if (cachedResolvedFlags)
+            return cachedResolvedFlags;
         const promises = flags.map(async (flag) => {
             if (typeof flag === 'string') {
                 return [flag, parse.output.flags[flag]];
@@ -60,15 +67,10 @@ async function validate(parse) {
             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] !== undefined)
-                acc.push(key);
-            return acc;
-        }, []);
+        cachedResolvedFlags = Object.fromEntries(resolved.filter(r => r !== null));
+        return cachedResolvedFlags;
     }
+    const getPresentFlags = (flags) => Object.keys(flags).filter(key => key !== undefined);
     function validateAcrossFlags(flag) {
         const base = { name: flag.name, validationFn: 'validateAcrossFlags' };
         const intersection = Object.entries(parse.input.flags)
@@ -131,30 +133,21 @@ async function validate(parse) {
         }
         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 = [];
+    function validateRelationships(name, flag) {
+        return ((flag.relationships ?? []).map(relationship => {
             switch (relationship.type) {
                 case 'all':
-                    results.push(await validateDependsOn(name, flags));
-                    break;
+                    return validateDependsOn(name, relationship.flags);
                 case 'some':
-                    results.push(await validateSome(name, flags));
-                    break;
+                    return validateSome(name, relationship.flags);
                 case 'none':
-                    results.push(await validateExclusive(name, flags));
-                    break;
+                    return validateExclusive(name, relationship.flags);
                 default:
-                    break;
+                    throw new Error(`Unknown relationship type: ${relationship.type}`);
             }
-            return results;
         }));
-        return results.flat();
     }
     validateArgs();
-    await validateFlags();
+    return validateFlags();
 }
 exports.validate = validate;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "2.8.12",
+  "version": "2.9.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {
@@ -42,6 +42,7 @@
     "@oclif/plugin-plugins": "^2.4.7",
     "@oclif/test": "^2.3.15",
     "@types/ansi-styles": "^3.2.1",
+    "@types/benchmark": "^2.1.2",
     "@types/chai": "^4.3.4",
     "@types/chai-as-promised": "^7.1.5",
     "@types/clean-stack": "^2.1.1",
@@ -61,6 +62,7 @@
     "@types/supports-color": "^8.1.1",
     "@types/wordwrap": "^1.0.1",
     "@types/wrap-ansi": "^3.0.0",
+    "benchmark": "^2.1.4",
     "chai": "^4.3.7",
     "chai-as-promised": "^7.1.1",
     "commitlint": "^12.1.4",
@@ -114,7 +116,8 @@
     "prepack": "yarn run build",
     "test": "mocha --forbid-only \"test/**/*.test.ts\"",
     "test:e2e": "mocha --forbid-only \"test/**/*.e2e.ts\" --timeout 1200000",
-    "pretest": "yarn build --noEmit && tsc -p test --noEmit --skipLibCheck"
+    "pretest": "yarn build --noEmit && tsc -p test --noEmit --skipLibCheck",
+    "test:perf": "ts-node test/perf/parser.perf.ts"
   },
   "types": "lib/index.d.ts"
 }