@oclif/core 3.0.0-beta.2 → 3.0.0-beta.21

package/lib/performance.js

@@ -1,13 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Performance = void 0;
-const perf_hooks_1 = require("perf_hooks");
+const node_perf_hooks_1 = require("node:perf_hooks");
 const settings_1 = require("./settings");
 class Marker {
+    name;
+    details;
+    module;
+    method;
+    scope;
+    stopped = false;
+    startMarker;
+    stopMarker;
     constructor(name, details = {}) {
         this.name = name;
         this.details = details;
-        this.stopped = false;
         this.startMarker = `${this.name}-start`;
         this.stopMarker = `${this.name}-stop`;
         const [caller, scope] = name.split('#');
@@ -15,20 +22,23 @@ class Marker {
         this.module = module;
         this.method = method;
         this.scope = scope;
-        perf_hooks_1.performance.mark(this.startMarker);
+        node_perf_hooks_1.performance.mark(this.startMarker);
     }
     addDetails(details) {
         this.details = { ...this.details, ...details };
     }
     stop() {
         this.stopped = true;
-        perf_hooks_1.performance.mark(this.stopMarker);
+        node_perf_hooks_1.performance.mark(this.stopMarker);
     }
     measure() {
-        perf_hooks_1.performance.measure(this.name, this.startMarker, this.stopMarker);
+        node_perf_hooks_1.performance.measure(this.name, this.startMarker, this.stopMarker);
     }
 }
 class Performance {
+    static markers = {};
+    static _results = [];
+    static _highlights;
     static get enabled() {
         return settings_1.settings.performanceEnabled ?? false;
     }
@@ -40,7 +50,7 @@ class Performance {
         throw new Error('Perf results not available. Did you forget to call await Performance.collect()?');
     }
     static getResult(name) {
-        return Performance.results.find(r => r.name === name);
+        return Performance.results.find((r) => r.name === name);
     }
     static get highlights() {
         if (!Performance.enabled)
@@ -76,11 +86,11 @@ class Performance {
         const markers = Object.values(Performance.markers);
         if (markers.length === 0)
             return;
-        for (const marker of markers.filter(m => !m.stopped)) {
+        for (const marker of markers.filter((m) => !m.stopped)) {
             marker.stop();
         }
-        return new Promise(resolve => {
-            const perfObserver = new perf_hooks_1.PerformanceObserver(items => {
+        return new Promise((resolve) => {
+            const perfObserver = new node_perf_hooks_1.PerformanceObserver((items) => {
                 for (const entry of items.getEntries()) {
                     if (Performance.markers[entry.name]) {
                         const marker = Performance.markers[entry.name];
@@ -94,12 +104,15 @@ class Performance {
                         });
                     }
                 }
-                const command = Performance.results.find(r => r.name.startsWith('config.runCommand'));
-                const commandLoadTime = command ? Performance.getResult(`plugin.findCommand#${command.details.plugin}.${command.details.command}`)?.duration ?? 0 : 0;
+                const command = Performance.results.find((r) => r.name.startsWith('config.runCommand'));
+                const commandLoadTime = command
+                    ? Performance.getResult(`plugin.findCommand#${command.details.plugin}.${command.details.command}`)
+                        ?.duration ?? 0
+                    : 0;
                 const pluginLoadTimes = Object.fromEntries(Performance.results
                     .filter(({ name }) => name.startsWith('plugin.load#'))
                     .sort((a, b) => b.duration - a.duration)
-                    .map(({ scope, duration }) => [scope, duration]));
+                    .map(({ scope, duration, details }) => [scope, { duration, details }]));
                 const hookRunTimes = Performance.results
                     .filter(({ name }) => name.startsWith('config.runHook#'))
                     .reduce((acc, perfResult) => {
@@ -121,10 +134,12 @@ class Performance {
                     .filter(({ name }) => name.startsWith('config.loadPlugins#'))
                     .sort((a, b) => b.duration - a.duration)
                     .map(({ scope, duration }) => [scope, duration]));
+                const commandRunTime = Performance.results.find(({ name }) => name.startsWith('config.runCommand#'))?.duration ?? 0;
                 Performance._highlights = {
                     configLoadTime: Performance.getResult('config.load')?.duration ?? 0,
                     runTime: Performance.getResult('main.run')?.duration ?? 0,
                     initTime: Performance.getResult('main.run#init')?.duration ?? 0,
+                    commandRunTime,
                     commandLoadTime,
                     pluginLoadTimes,
                     hookRunTimes,
@@ -143,7 +158,7 @@ class Performance {
                     // ignore
                 }
             }
-            perf_hooks_1.performance.clearMarks();
+            node_perf_hooks_1.performance.clearMarks();
         });
     }
     /**
@@ -154,16 +169,22 @@ class Performance {
         if (!Performance.enabled)
             return;
         const debug = require('debug')('perf');
+        debug('Total Time: %sms', Performance.highlights.runTime.toFixed(4));
         debug('Init Time: %sms', Performance.highlights.initTime.toFixed(4));
         debug('Config Load Time: %sms', Performance.highlights.configLoadTime.toFixed(4));
-        debug('Command Load Time: %sms', Performance.highlights.commandLoadTime.toFixed(4));
-        debug('Execution Time: %sms', Performance.highlights.runTime.toFixed(4));
+        debug('  • Plugins Load Time: %sms', Performance.getResult('config.loadAllPlugins')?.duration.toFixed(4) ?? 0);
+        debug('  • Commands Load Time: %sms', Performance.getResult('config.loadAllCommands')?.duration.toFixed(4) ?? 0);
         debug('Core Plugin Load Time: %sms', Performance.highlights.corePluginsLoadTime.toFixed(4));
         debug('User Plugin Load Time: %sms', Performance.highlights.userPluginsLoadTime.toFixed(4));
         debug('Linked Plugin Load Time: %sms', Performance.highlights.linkedPluginsLoadTime.toFixed(4));
         debug('Plugin Load Times:');
-        for (const [plugin, duration] of Object.entries(Performance.highlights.pluginLoadTimes)) {
-            debug(`  ${plugin}: ${duration.toFixed(4)}ms`);
+        for (const [plugin, result] of Object.entries(Performance.highlights.pluginLoadTimes)) {
+            if (result.details.hasManifest) {
+                debug(`  ${plugin}: ${result.duration.toFixed(4)}ms`);
+            }
+            else {
+                debug(`  ${plugin}: ${result.duration.toFixed(4)}ms (no manifest!)`);
+            }
         }
         debug('Hook Run Times:');
         for (const [event, runTimes] of Object.entries(Performance.highlights.hookRunTimes)) {
@@ -172,8 +193,8 @@ class Performance {
                 debug(`    ${plugin}: ${duration.toFixed(4)}ms`);
             }
         }
+        debug('Command Load Time: %sms', Performance.highlights.commandLoadTime.toFixed(4));
+        debug('Command Run Time: %sms', Performance.highlights.commandRunTime.toFixed(4));
     }
 }
 exports.Performance = Performance;
-Performance.markers = {};
-Performance._results = [];

package/lib/util/aggregate-flags.d.ts

@@ -0,0 +1,2 @@
+import { FlagInput, FlagOutput } from '../interfaces/parser';
+export declare function aggregateFlags<F extends FlagOutput, B extends FlagOutput>(flags: FlagInput<F> | undefined, baseFlags: FlagInput<B> | undefined, enableJsonFlag: boolean | undefined): FlagInput<F>;

package/lib/util/aggregate-flags.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregateFlags = void 0;
+const flags_1 = require("../flags");
+const json = (0, flags_1.boolean)({
+    description: 'Format output as json.',
+    helpGroup: 'GLOBAL',
+});
+function aggregateFlags(flags, baseFlags, enableJsonFlag) {
+    const combinedFlags = { ...baseFlags, ...flags };
+    return (enableJsonFlag ? { json, ...combinedFlags } : combinedFlags);
+}
+exports.aggregateFlags = aggregateFlags;

package/lib/util/cache-command.d.ts

@@ -0,0 +1,3 @@
+import { Command } from '../command';
+import { Plugin as IPlugin } from '../interfaces/plugin';
+export declare function cacheCommand(uncachedCmd: Command.Class, plugin?: IPlugin, respectNoCacheDefault?: boolean): Promise<Command.Cached>;

package/lib/util/cache-command.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheCommand = void 0;
+const aggregate_flags_1 = require("./aggregate-flags");
+const cache_default_value_1 = require("./cache-default-value");
+const ensure_arg_object_1 = require("./ensure-arg-object");
+const util_1 = require("./util");
+// In order to collect static properties up the inheritance chain, we need to recursively
+// access the prototypes until there's nothing left. This allows us to combine baseFlags
+// and flags as well as add in the json flag if enableJsonFlag is enabled.
+function mergePrototype(result, cmd) {
+    const proto = Object.getPrototypeOf(cmd);
+    const filteredProto = (0, util_1.pickBy)(proto, (v) => v !== undefined);
+    return Object.keys(proto).length > 0 ? mergePrototype({ ...filteredProto, ...result }, proto) : result;
+}
+async function cacheFlags(cmdFlags, respectNoCacheDefault) {
+    const promises = Object.entries(cmdFlags).map(async ([name, flag]) => [
+        name,
+        {
+            name,
+            char: flag.char,
+            summary: flag.summary,
+            hidden: flag.hidden,
+            required: flag.required,
+            helpLabel: flag.helpLabel,
+            helpGroup: flag.helpGroup,
+            description: flag.description,
+            dependsOn: flag.dependsOn,
+            relationships: flag.relationships,
+            exclusive: flag.exclusive,
+            deprecated: flag.deprecated,
+            deprecateAliases: flag.deprecateAliases,
+            aliases: flag.aliases,
+            charAliases: flag.charAliases,
+            noCacheDefault: flag.noCacheDefault,
+            ...(flag.type === 'boolean'
+                ? {
+                    allowNo: flag.allowNo,
+                    type: flag.type,
+                }
+                : {
+                    type: flag.type,
+                    helpValue: flag.helpValue,
+                    multiple: flag.multiple,
+                    options: flag.options,
+                    delimiter: flag.delimiter,
+                    default: await (0, cache_default_value_1.cacheDefaultValue)(flag, respectNoCacheDefault),
+                    hasDynamicHelp: typeof flag.defaultHelp === 'function',
+                }),
+        },
+    ]);
+    return Object.fromEntries(await Promise.all(promises));
+}
+async function cacheArgs(cmdArgs, respectNoCacheDefault) {
+    const promises = Object.entries(cmdArgs).map(async ([name, arg]) => [
+        name,
+        {
+            name,
+            description: arg.description,
+            required: arg.required,
+            options: arg.options,
+            default: await (0, cache_default_value_1.cacheDefaultValue)(arg, respectNoCacheDefault),
+            hidden: arg.hidden,
+            noCacheDefault: arg.noCacheDefault,
+        },
+    ]);
+    return Object.fromEntries(await Promise.all(promises));
+}
+async function cacheCommand(uncachedCmd, plugin, respectNoCacheDefault = false) {
+    const cmd = mergePrototype(uncachedCmd, uncachedCmd);
+    const flags = await cacheFlags((0, aggregate_flags_1.aggregateFlags)(cmd.flags, cmd.baseFlags, cmd.enableJsonFlag), respectNoCacheDefault);
+    const args = await cacheArgs((0, ensure_arg_object_1.ensureArgObject)(cmd.args), respectNoCacheDefault);
+    const stdProperties = {
+        id: cmd.id,
+        summary: cmd.summary,
+        description: cmd.description,
+        strict: cmd.strict,
+        usage: cmd.usage,
+        pluginName: plugin && plugin.name,
+        pluginAlias: plugin && plugin.alias,
+        pluginType: plugin && plugin.type,
+        hidden: cmd.hidden,
+        state: cmd.state,
+        aliases: cmd.aliases || [],
+        examples: cmd.examples || cmd.example,
+        deprecationOptions: cmd.deprecationOptions,
+        deprecateAliases: cmd.deprecateAliases,
+        flags,
+        args,
+        hasDynamicHelp: Object.values(flags).some((f) => f.hasDynamicHelp),
+    };
+    // do not include these properties in manifest
+    const ignoreCommandProperties = [
+        'plugin',
+        '_flags',
+        '_enableJsonFlag',
+        '_globalFlags',
+        '_baseFlags',
+        'baseFlags',
+        '_--',
+        '_base',
+    ];
+    // Add in any additional properties that are not standard command properties.
+    const stdKeysAndIgnored = new Set([...Object.keys(stdProperties), ...ignoreCommandProperties]);
+    const keysToAdd = Object.keys(cmd).filter((property) => !stdKeysAndIgnored.has(property));
+    const additionalProperties = Object.fromEntries(keysToAdd.map((key) => [key, cmd[key]]));
+    return { ...stdProperties, ...additionalProperties };
+}
+exports.cacheCommand = cacheCommand;

package/lib/util/cache-default-value.d.ts

@@ -0,0 +1,2 @@
+import { Arg, OptionFlag } from '../interfaces/parser';
+export declare const cacheDefaultValue: (flagOrArg: OptionFlag<any> | Arg<any>, respectNoCacheDefault: boolean) => Promise<any>;

package/lib/util/cache-default-value.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheDefaultValue = void 0;
+// when no manifest exists, the default is calculated.  This may throw, so we need to catch it
+const cacheDefaultValue = async (flagOrArg, respectNoCacheDefault) => {
+    if (respectNoCacheDefault && flagOrArg.noCacheDefault)
+        return;
+    // Prefer the defaultHelp function (returns a friendly string for complex types)
+    if (typeof flagOrArg.defaultHelp === 'function') {
+        try {
+            return await flagOrArg.defaultHelp({ options: flagOrArg, flags: {} });
+        }
+        catch {
+            return;
+        }
+    }
+    // if not specified, try the default function
+    if (typeof flagOrArg.default === 'function') {
+        try {
+            return await flagOrArg.default({ options: flagOrArg, flags: {} });
+        }
+        catch { }
+    }
+    else {
+        return flagOrArg.default;
+    }
+};
+exports.cacheDefaultValue = cacheDefaultValue;

package/lib/util/ensure-arg-object.d.ts

@@ -0,0 +1,12 @@
+import { ArgInput } from '../interfaces/parser';
+import { Command } from '../command';
+/**
+ * Ensure that the provided args are an object. This is for backwards compatibility with v1 commands which
+ * defined args as an array.
+ *
+ * @param args Either an array of args or an object of args
+ * @returns ArgInput
+ */
+export declare function ensureArgObject(args?: any[] | ArgInput | {
+    [name: string]: Command.Arg.Cached;
+}): ArgInput;

package/lib/util/ensure-arg-object.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureArgObject = void 0;
+/**
+ * Ensure that the provided args are an object. This is for backwards compatibility with v1 commands which
+ * defined args as an array.
+ *
+ * @param args Either an array of args or an object of args
+ * @returns ArgInput
+ */
+function ensureArgObject(args) {
+    return (Array.isArray(args) ? (args ?? []).reduce((x, y) => ({ ...x, [y.name]: y }), {}) : args ?? {});
+}
+exports.ensureArgObject = ensureArgObject;

package/lib/util/fs.d.ts

@@ -0,0 +1,7 @@
+export declare function requireJson<T>(...pathParts: string[]): T;
+export declare function exists(path: string): Promise<boolean>;
+export declare const dirExists: (input: string) => Promise<string>;
+export declare const fileExists: (input: string) => Promise<string>;
+export declare function readJson<T = unknown>(path: string): Promise<T>;
+export declare function readJsonSync(path: string, parse: false): string;
+export declare function readJsonSync<T = unknown>(path: string, parse?: true): T;

package/lib/util/fs.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readJsonSync = exports.readJson = exports.fileExists = exports.dirExists = exports.exists = exports.requireJson = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const debug = require('debug');
+function requireJson(...pathParts) {
+    return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(...pathParts), 'utf8'));
+}
+exports.requireJson = requireJson;
+async function exists(path) {
+    try {
+        await (0, promises_1.access)(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+exports.exists = exists;
+const dirExists = async (input) => {
+    if (!(await exists(input))) {
+        throw new Error(`No directory found at ${input}`);
+    }
+    const fileStat = await (0, promises_1.stat)(input);
+    if (!fileStat.isDirectory()) {
+        throw new Error(`${input} exists but is not a directory`);
+    }
+    return input;
+};
+exports.dirExists = dirExists;
+const fileExists = async (input) => {
+    if (!(await exists(input))) {
+        throw new Error(`No file found at ${input}`);
+    }
+    const fileStat = await (0, promises_1.stat)(input);
+    if (!fileStat.isFile()) {
+        throw new Error(`${input} exists but is not a file`);
+    }
+    return input;
+};
+exports.fileExists = fileExists;
+async function readJson(path) {
+    debug('config')('readJson %s', path);
+    const contents = await (0, promises_1.readFile)(path, 'utf8');
+    return JSON.parse(contents);
+}
+exports.readJson = readJson;
+function readJsonSync(path, parse = true) {
+    const contents = (0, node_fs_1.readFileSync)(path, 'utf8');
+    return parse ? JSON.parse(contents) : contents;
+}
+exports.readJsonSync = readJsonSync;

package/lib/util/os.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="node" />
+/**
+ * Call os.homedir() and return the result
+ *
+ * Wrapping this allows us to stub these in tests since os.homedir() is
+ * non-configurable and non-writable.
+ *
+ * @returns The user's home directory
+ */
+export declare function getHomeDir(): string;
+/**
+ * Call os.platform() and return the result
+ *
+ * Wrapping this allows us to stub these in tests since os.platform() is
+ * non-configurable and non-writable.
+ *
+ * @returns The process' platform
+ */
+export declare function getPlatform(): NodeJS.Platform;

package/lib/util/os.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPlatform = exports.getHomeDir = void 0;
+const node_os_1 = require("node:os");
+/**
+ * Call os.homedir() and return the result
+ *
+ * Wrapping this allows us to stub these in tests since os.homedir() is
+ * non-configurable and non-writable.
+ *
+ * @returns The user's home directory
+ */
+function getHomeDir() {
+    return (0, node_os_1.homedir)();
+}
+exports.getHomeDir = getHomeDir;
+/**
+ * Call os.platform() and return the result
+ *
+ * Wrapping this allows us to stub these in tests since os.platform() is
+ * non-configurable and non-writable.
+ *
+ * @returns The process' platform
+ */
+function getPlatform() {
+    return (0, node_os_1.platform)();
+}
+exports.getPlatform = getPlatform;

package/lib/{util.d.ts → util/util.d.ts}

@@ -1,5 +1,3 @@
-import { Command } from './command';
-import { ArgInput } from './interfaces/parser';
 export declare function pickBy<T extends {
     [s: string]: T[keyof T];
 } | ArrayLike<T[keyof T]>>(obj: T, fn: (i: T[keyof T]) => boolean): Partial<T>;
@@ -13,19 +11,12 @@ export declare function isProd(): boolean;
 export declare function maxBy<T>(arr: T[], fn: (i: T) => number): T | undefined;
 export declare function sumBy<T>(arr: T[], fn: (i: T) => number): number;
 export declare function capitalize(s: string): string;
-export declare const dirExists: (input: string) => Promise<string>;
-export declare const fileExists: (input: string) => Promise<string>;
 export declare function isTruthy(input: string): boolean;
 export declare function isNotFalsy(input: string): boolean;
-export declare function requireJson<T>(...pathParts: string[]): T;
-/**
- * Ensure that the provided args are an object. This is for backwards compatibility with v1 commands which
- * defined args as an array.
- *
- * @param args Either an array of args or an object of args
- * @returns ArgInput
- */
-export declare function ensureArgObject(args?: any[] | ArgInput | {
-    [name: string]: Command.Arg.Cached;
-}): ArgInput;
+export declare function uniq<T>(arr: T[]): T[];
+export declare function mapValues<T extends Record<string, any>, TResult>(obj: {
+    [P in keyof T]: T[P];
+}, fn: (i: T[keyof T], k: keyof T) => TResult): {
+    [P in keyof T]: TResult;
+};
 export {};

package/lib/util/util.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapValues = exports.uniq = exports.isNotFalsy = exports.isTruthy = exports.capitalize = exports.sumBy = exports.maxBy = exports.isProd = exports.castArray = exports.sortBy = exports.last = exports.uniqBy = exports.compact = exports.pickBy = void 0;
+function pickBy(obj, fn) {
+    return Object.entries(obj).reduce((o, [k, v]) => {
+        if (fn(v))
+            o[k] = v;
+        return o;
+    }, {});
+}
+exports.pickBy = pickBy;
+function compact(a) {
+    // eslint-disable-next-line unicorn/prefer-native-coercion-functions
+    return a.filter((a) => Boolean(a));
+}
+exports.compact = compact;
+function uniqBy(arr, fn) {
+    return arr.filter((a, i) => {
+        const aVal = fn(a);
+        return !arr.find((b, j) => j > i && fn(b) === aVal);
+    });
+}
+exports.uniqBy = uniqBy;
+function last(arr) {
+    if (!arr)
+        return;
+    return arr.at(-1);
+}
+exports.last = last;
+function compare(a, b) {
+    a = a === undefined ? 0 : a;
+    b = b === undefined ? 0 : b;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length === 0 && b.length === 0)
+            return 0;
+        const diff = compare(a[0], b[0]);
+        if (diff !== 0)
+            return diff;
+        return compare(a.slice(1), b.slice(1));
+    }
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+function sortBy(arr, fn) {
+    return arr.sort((a, b) => compare(fn(a), fn(b)));
+}
+exports.sortBy = sortBy;
+function castArray(input) {
+    if (input === undefined)
+        return [];
+    return Array.isArray(input) ? input : [input];
+}
+exports.castArray = castArray;
+function isProd() {
+    return !['development', 'test'].includes(process.env.NODE_ENV ?? '');
+}
+exports.isProd = isProd;
+function maxBy(arr, fn) {
+    if (arr.length === 0) {
+        return undefined;
+    }
+    return arr.reduce((maxItem, i) => {
+        const curr = fn(i);
+        const max = fn(maxItem);
+        return curr > max ? i : maxItem;
+    });
+}
+exports.maxBy = maxBy;
+function sumBy(arr, fn) {
+    return arr.reduce((sum, i) => sum + fn(i), 0);
+}
+exports.sumBy = sumBy;
+function capitalize(s) {
+    return s ? s.charAt(0).toUpperCase() + s.slice(1).toLowerCase() : '';
+}
+exports.capitalize = capitalize;
+function isTruthy(input) {
+    return ['true', '1', 'yes', 'y'].includes(input.toLowerCase());
+}
+exports.isTruthy = isTruthy;
+function isNotFalsy(input) {
+    return !['false', '0', 'no', 'n'].includes(input.toLowerCase());
+}
+exports.isNotFalsy = isNotFalsy;
+function uniq(arr) {
+    return [...new Set(arr)].sort();
+}
+exports.uniq = uniq;
+function mapValues(obj, fn) {
+    return Object.entries(obj).reduce((o, [k, v]) => {
+        o[k] = fn(v, k);
+        return o;
+    }, {});
+}
+exports.mapValues = mapValues;