@oclif/core 2.4.0 → 2.5.1

package/lib/config/config.js

@@ -13,6 +13,8 @@ const util_3 = require("../util");
 const module_loader_1 = require("../module-loader");
 const help_1 = require("../help");
 const stream_1 = require("../cli-ux/stream");
+const performance_1 = require("../performance");
+const settings_1 = require("../settings");
 // eslint-disable-next-line new-cap
 const debug = (0, util_2.Debug)();
 const _pjson = (0, util_3.requireJson)(__dirname, '..', '..', 'package.json');
@@ -81,6 +83,7 @@ class Config {
     }
     // eslint-disable-next-line complexity
     async load() {
+        settings_1.settings.performanceEnabled = (settings_1.settings.performanceEnabled === undefined ? this.options.enablePerf : settings_1.settings.performanceEnabled) ?? false;
         const plugin = new Plugin.Plugin({ root: this.options.root });
         await plugin.load();
         this.plugins.push(plugin);
@@ -136,10 +139,19 @@ class Config {
                 ...s3.templates && s3.templates.vanilla,
             },
         };
+        const marker = performance_1.Performance.mark('config.load');
         await this.loadPluginsAndCommands();
         debug('config done');
+        marker?.addDetails({
+            plugins: this.plugins.length,
+            commandPermutations: this.commands.length,
+            commands: this.plugins.reduce((acc, p) => acc + p.commands.length, 0),
+            topics: this.topics.length,
+        });
+        marker?.stop();
     }
     async loadPluginsAndCommands() {
+        const marker = performance_1.Performance.mark('config.loadPluginsAndCommands');
         await this.loadUserPlugins();
         await this.loadDevPlugins();
         await this.loadCorePlugins();
@@ -147,6 +159,7 @@ class Config {
             this.loadCommands(plugin);
             this.loadTopics(plugin);
         }
+        marker?.stop();
     }
     async loadCorePlugins() {
         if (this.pjson.oclif.plugins) {
@@ -189,6 +202,7 @@ class Config {
         }
     }
     async runHook(event, opts, timeout, captureErrors) {
+        const marker = performance_1.Performance.mark(`config.runHook#${event}`);
         debug('start %s hook', event);
         const search = (m) => {
             if (typeof m === 'function')
@@ -233,6 +247,7 @@ class Config {
             };
             const hooks = p.hooks[event] || [];
             for (const hook of hooks) {
+                const marker = performance_1.Performance.mark(`config.runHook#${p.name}(${hook})`);
                 try {
                     /* eslint-disable no-await-in-loop */
                     const { isESM, module, filePath } = await module_loader_1.default.loadWithData(p, hook);
@@ -252,13 +267,21 @@ class Config {
                     if (!captureErrors && error.oclif?.exit !== undefined)
                         throw error;
                 }
+                marker?.addDetails({
+                    plugin: p.name,
+                    event,
+                    hook,
+                });
+                marker?.stop();
             }
         });
         await Promise.all(promises);
         debug('%s hook done', event);
+        marker?.stop();
         return final;
     }
     async runCommand(id, argv = [], cachedCommand = null) {
+        const marker = performance_1.Performance.mark(`config.runCommand#${id}`);
         debug('runCommand %s %o', id, argv);
         let c = cachedCommand ?? this.findCommand(id);
         if (!c) {
@@ -302,6 +325,8 @@ class Config {
         await this.runHook('prerun', { Command: command, argv });
         const result = (await command.run(argv, this));
         await this.runHook('postrun', { Command: command, result, argv });
+        marker?.addDetails({ command: id, plugin: c.pluginName });
+        marker?.stop();
         return result;
     }
     scopedEnvVar(k) {
@@ -453,6 +478,7 @@ class Config {
     async loadPlugins(root, type, plugins, parent) {
         if (!plugins || plugins.length === 0)
             return;
+        const mark = performance_1.Performance.mark(`config.loadPlugins#${type}`);
         debug('loading plugins', plugins);
         await Promise.all((plugins || []).map(async (plugin) => {
             try {
@@ -465,8 +491,18 @@ class Config {
                     opts.tag = plugin.tag || opts.tag;
                     opts.root = plugin.root || opts.root;
                 }
+                const pluginMarker = performance_1.Performance.mark(`plugin.load#${opts.name}`);
                 const instance = new Plugin.Plugin(opts);
                 await instance.load();
+                pluginMarker?.addDetails({
+                    hasManifest: instance.hasManifest,
+                    commandCount: instance.commands.length,
+                    topicCount: instance.topics.length,
+                    type: instance.type,
+                    usesMain: Boolean(instance.pjson.main),
+                    name: instance.name,
+                });
+                pluginMarker?.stop();
                 if (this.plugins.find(p => p.name === instance.name))
                     return;
                 this.plugins.push(instance);
@@ -482,6 +518,8 @@ class Config {
                 this.warn(error, 'loadPlugins');
             }
         }));
+        mark?.addDetails({ pluginCount: plugins.length });
+        mark?.stop();
     }
     warn(err, scope) {
         if (this.warned)
@@ -538,6 +576,7 @@ class Config {
         return id;
     }
     loadCommands(plugin) {
+        const marker = performance_1.Performance.mark(`config.loadCommands#${plugin.name}`, { plugin: plugin.name });
         for (const command of plugin.commands) {
             if (this._commands.has(command.id)) {
                 const prioritizedCommand = this.determinePriority([this._commands.get(command.id), command]);
@@ -564,8 +603,11 @@ class Config {
                 }
             }
         }
+        marker?.addDetails({ commandCount: plugin.commands.length });
+        marker?.stop();
     }
     loadTopics(plugin) {
+        const marker = performance_1.Performance.mark(`config.loadTopics#${plugin.name}`, { plugin: plugin.name });
         for (const topic of (0, util_2.compact)(plugin.topics)) {
             const existing = this._topics.get(topic.name);
             if (existing) {
@@ -591,6 +633,7 @@ class Config {
                 parts.pop();
             }
         }
+        marker?.stop();
     }
     /**
      * This method is responsible for locating the correct plugin to use for a named command id

package/lib/config/plugin.d.ts

@@ -23,6 +23,7 @@ export declare class Plugin implements IPlugin {
     alreadyLoaded: boolean;
     parent: Plugin | undefined;
     children: Plugin[];
+    hasManifest: boolean;
     protected _debug: (..._: any) => void;
     protected warned: boolean;
     constructor(options: PluginOptions);

package/lib/config/plugin.js

@@ -11,6 +11,7 @@ const ts_node_1 = require("./ts-node");
 const util_3 = require("./util");
 const util_4 = require("../util");
 const module_loader_1 = require("../module-loader");
+const performance_1 = require("../performance");
 const _pjson = (0, util_4.requireJson)(__dirname, '..', '..', 'package.json');
 function topicsToArray(input, base) {
     if (!input)
@@ -94,6 +95,7 @@ class Plugin {
         this.valid = false;
         this.alreadyLoaded = false;
         this.children = [];
+        this.hasManifest = false;
         // eslint-disable-next-line new-cap
         this._debug = (0, util_2.Debug)();
         this.warned = false;
@@ -144,6 +146,7 @@ class Plugin {
     get commandIDs() {
         if (!this.commandsDir)
             return [];
+        const marker = performance_1.Performance.mark(`plugin.commandIDs#${this.name}`, { plugin: this.name });
         this._debug(`loading IDs from ${this.commandsDir}`);
         const patterns = [
             '**/*.+(js|cjs|mjs|ts|tsx)',
@@ -158,9 +161,12 @@ class Plugin {
             return id === '' ? '.' : id;
         });
         this._debug('found commands', ids);
+        marker?.addDetails({ count: ids.length });
+        marker?.stop();
         return ids;
     }
     async findCommand(id, opts = {}) {
+        const marker = performance_1.Performance.mark(`plugin.findCommand#${this.name}.${id}`, { id, plugin: this.name });
         const fetch = async () => {
             if (!this.commandsDir)
                 return;
@@ -193,6 +199,7 @@ class Plugin {
         const cmd = await fetch();
         if (!cmd && opts.must)
             (0, errors_1.error)(`command ${id} not found`);
+        marker?.stop();
         return cmd;
     }
     async _manifest(ignoreManifest, errorOnManifestCreate = false) {
@@ -205,6 +212,7 @@ class Plugin {
                 }
                 else {
                     this._debug('using manifest from', p);
+                    this.hasManifest = true;
                     return manifest;
                 }
             }
@@ -218,12 +226,16 @@ class Plugin {
                 }
             }
         };
+        const marker = performance_1.Performance.mark(`plugin.manifest#${this.name}`, { plugin: this.name });
         if (!ignoreManifest) {
             const manifest = await readManifest();
-            if (manifest)
+            if (manifest) {
+                marker?.addDetails({ fromCache: true, commandCount: Object.keys(manifest.commands).length });
+                marker?.stop();
                 return manifest;
+            }
         }
-        return {
+        const manifest = {
             version: this.version,
             commands: (await Promise.all(this.commandIDs.map(async (id) => {
                 try {
@@ -243,6 +255,9 @@ class Plugin {
                 return commands;
             }, {}),
         };
+        marker?.addDetails({ fromCache: false, commandCount: Object.keys(manifest.commands).length });
+        marker?.stop();
+        return manifest;
     }
     warn(err, scope) {
         if (this.warned)

package/lib/index.d.ts

@@ -13,5 +13,6 @@ import { settings, Settings } from './settings';
 import { HelpSection, HelpSectionRenderer, HelpSectionKeyValueTable } from './help/formatter';
 import * as ux from './cli-ux';
 import { stderr, stdout } from './cli-ux/stream';
+import { Performance } from './performance';
 declare const flush: typeof ux.ux.flush;
-export { Args, Command, CommandHelp, Config, Errors, Flags, loadHelpClass, Help, HelpBase, HelpSection, HelpSectionRenderer, HelpSectionKeyValueTable, Hook, Interfaces, Parser, Plugin, run, toCached, tsPath, toStandardizedId, toConfiguredId, settings, Settings, flush, ux, execute, stderr, stdout, };
+export { Args, Command, CommandHelp, Config, Errors, Flags, loadHelpClass, Help, HelpBase, HelpSection, HelpSectionRenderer, HelpSectionKeyValueTable, Hook, Interfaces, Parser, Plugin, Performance, run, toCached, tsPath, toStandardizedId, toConfiguredId, settings, Settings, flush, ux, execute, stderr, stdout, };

package/lib/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stdout = exports.stderr = exports.execute = exports.ux = exports.flush = exports.settings = exports.toConfiguredId = exports.toStandardizedId = exports.tsPath = exports.toCached = exports.run = exports.Plugin = exports.Parser = exports.Interfaces = exports.HelpBase = exports.Help = exports.loadHelpClass = exports.Flags = exports.Errors = exports.Config = exports.CommandHelp = exports.Command = exports.Args = void 0;
+exports.stdout = exports.stderr = exports.execute = exports.ux = exports.flush = exports.settings = exports.toConfiguredId = exports.toStandardizedId = exports.tsPath = exports.toCached = exports.run = exports.Performance = exports.Plugin = exports.Parser = exports.Interfaces = exports.HelpBase = exports.Help = exports.loadHelpClass = exports.Flags = exports.Errors = exports.Config = exports.CommandHelp = exports.Command = exports.Args = void 0;
 const semver = require("semver");
 const command_1 = require("./command");
 Object.defineProperty(exports, "Command", { enumerable: true, get: function () { return command_1.Command; } });
@@ -38,6 +38,8 @@ const util_2 = require("./util");
 const stream_1 = require("./cli-ux/stream");
 Object.defineProperty(exports, "stderr", { enumerable: true, get: function () { return stream_1.stderr; } });
 Object.defineProperty(exports, "stdout", { enumerable: true, get: function () { return stream_1.stdout; } });
+const performance_1 = require("./performance");
+Object.defineProperty(exports, "Performance", { enumerable: true, get: function () { return performance_1.Performance; } });
 const flush = ux.flush;
 exports.flush = flush;
 function checkCWD() {

package/lib/interfaces/plugin.d.ts

@@ -17,6 +17,7 @@ export interface Options extends PluginOptions {
     userPlugins?: boolean;
     channel?: string;
     version?: string;
+    enablePerf?: boolean;
 }
 export interface Plugin {
     /**

package/lib/main.d.ts

@@ -2,7 +2,7 @@ import * as Interfaces from './interfaces';
 import { Config } from './config';
 export declare const helpAddition: (argv: string[], config: Interfaces.Config) => boolean;
 export declare const versionAddition: (argv: string[], config?: Interfaces.Config) => boolean;
-export declare function run(argv?: string[], options?: Interfaces.LoadOptions): Promise<void>;
+export declare function run(argv?: string[], options?: Interfaces.LoadOptions): Promise<unknown>;
 /**
  * Load and run oclif CLI
  *

package/lib/main.js

@@ -10,6 +10,7 @@ const settings_1 = require("./settings");
 const _1 = require(".");
 const path_1 = require("path");
 const stream_1 = require("./cli-ux/stream");
+const performance_1 = require("./performance");
 const log = (message = '', ...args) => {
     message = typeof message === 'string' ? message : (0, util_1.inspect)(message);
     stream_1.stdout.write((0, util_1.format)(message, ...args) + '\n');
@@ -36,6 +37,14 @@ const versionAddition = (argv, config) => {
 };
 exports.versionAddition = versionAddition;
 async function run(argv, options) {
+    const marker = performance_1.Performance.mark('main.run');
+    const initMarker = performance_1.Performance.mark('main.run#init');
+    const collectPerf = async () => {
+        marker?.stop();
+        initMarker?.stop();
+        await performance_1.Performance.collect();
+        performance_1.Performance.debug();
+    };
     argv = argv ?? process.argv.slice(2);
     // Handle the case when a file URL string or URL is passed in such as 'import.meta.url'; covert to file path.
     if (options && ((typeof options === 'string' && options.startsWith('file://')) || options instanceof url_2.URL)) {
@@ -48,6 +57,7 @@ async function run(argv, options) {
     // display version if applicable
     if ((0, exports.versionAddition)(argv, config)) {
         log(config.userAgent);
+        await collectPerf();
         return;
     }
     // display help version if applicable
@@ -55,6 +65,7 @@ async function run(argv, options) {
         const Help = await (0, help_1.loadHelpClass)(config);
         const help = new Help(config, config.pjson.helpOptions);
         await help.showHelp(argv);
+        await collectPerf();
         return;
     }
     // find & run command
@@ -68,12 +79,18 @@ async function run(argv, options) {
             argvSlice = argv;
         }
     }
+    initMarker?.stop();
     // If the the default command is '.' (signifying that the CLI is a single command CLI) and '.' is provided
     // as an argument, we need to add back the '.' to argv since it was stripped out earlier as part of the
     // command id.
     if (config.pjson.oclif.default === '.' && id === '.' && argv[0] === '.')
         argvSlice = ['.', ...argvSlice];
-    return config.runCommand(id, argvSlice, cmd);
+    try {
+        return await config.runCommand(id, argvSlice, cmd);
+    }
+    finally {
+        await collectPerf();
+    }
 }
 exports.run = run;
 function getTsConfigPath(dir, type) {

package/lib/performance.d.ts

@@ -0,0 +1,63 @@
+type Details = Record<string, string | boolean | number | string[]>;
+type PerfResult = {
+    name: string;
+    duration: number;
+    details: Details;
+    module: string;
+    method: string | undefined;
+    scope: string | undefined;
+};
+type PerfHighlights = {
+    configLoadTime: number;
+    runTime: number;
+    initTime: number;
+    commandLoadTime: number;
+    pluginLoadTimes: Record<string, number>;
+    corePluginsLoadTime: number;
+    userPluginsLoadTime: number;
+    linkedPluginsLoadTime: number;
+    hookRunTimes: Record<string, Record<string, number>>;
+};
+declare class Marker {
+    name: string;
+    details: Details;
+    module: string;
+    method: string;
+    scope: string;
+    stopped: boolean;
+    private startMarker;
+    private stopMarker;
+    constructor(name: string, details?: Details);
+    addDetails(details: Details): void;
+    stop(): void;
+    measure(): void;
+}
+export declare class Performance {
+    private static markers;
+    private static _results;
+    private static _highlights;
+    static get enabled(): boolean;
+    static get results(): PerfResult[];
+    static getResult(name: string): PerfResult | undefined;
+    static get highlights(): PerfHighlights;
+    /**
+     * Add a new performance marker
+     *
+     * @param name Name of the marker. Use `module.method#scope` format
+     * @param details Arbitrary details to attach to the marker
+     * @returns Marker instance
+     */
+    static mark(name: string, details?: Details): Marker | undefined;
+    /**
+     * Collect performance results into static Performance.results
+     *
+     * @returns Promise<void>
+     */
+    static collect(): Promise<void>;
+    /**
+     * Add debug logs for plugin loading performance
+     * @returns void
+     */
+    static debug(): void;
+}
+export {};

package/lib/performance.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Performance = void 0;
+const perf_hooks_1 = require("perf_hooks");
+const settings_1 = require("./settings");
+class Marker {
+    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('#');
+        const [module, method] = caller.split('.');
+        this.module = module;
+        this.method = method;
+        this.scope = scope;
+        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);
+    }
+    measure() {
+        perf_hooks_1.performance.measure(this.name, this.startMarker, this.stopMarker);
+    }
+}
+class Performance {
+    static get enabled() {
+        return settings_1.settings.performanceEnabled ?? false;
+    }
+    static get results() {
+        if (Performance._results.length > 0)
+            return Performance._results;
+        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);
+    }
+    static get highlights() {
+        if (Performance._highlights)
+            return Performance._highlights;
+        throw new Error('Perf results not available. Did you forget to call await Performance.collect()?');
+    }
+    /**
+     * Add a new performance marker
+     *
+     * @param name Name of the marker. Use `module.method#scope` format
+     * @param details Arbitrary details to attach to the marker
+     * @returns Marker instance
+     */
+    static mark(name, details = {}) {
+        if (!Performance.enabled)
+            return;
+        const marker = new Marker(name, details);
+        Performance.markers[marker.name] = marker;
+        return marker;
+    }
+    /**
+     * Collect performance results into static Performance.results
+     *
+     * @returns Promise<void>
+     */
+    static async collect() {
+        if (!Performance.enabled)
+            return;
+        if (Performance._results.length > 0)
+            return;
+        for (const marker of Object.values(Performance.markers).filter(m => !m.stopped)) {
+            marker.stop();
+        }
+        return new Promise(resolve => {
+            const perfObserver = new perf_hooks_1.PerformanceObserver(items => {
+                for (const entry of items.getEntries()) {
+                    if (Performance.markers[entry.name]) {
+                        const marker = Performance.markers[entry.name];
+                        Performance._results.push({
+                            name: entry.name,
+                            module: marker.module,
+                            method: marker.method,
+                            scope: marker.scope,
+                            duration: entry.duration,
+                            details: marker.details,
+                        });
+                    }
+                }
+                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]));
+                const hookRunTimes = Performance.results
+                    .filter(({ name }) => name.startsWith('config.runHook#'))
+                    .reduce((acc, perfResult) => {
+                    const event = perfResult.details.event;
+                    if (event) {
+                        if (!acc[event])
+                            acc[event] = {};
+                        acc[event][perfResult.scope] = perfResult.duration;
+                    }
+                    else {
+                        const event = perfResult.scope;
+                        if (!acc[event])
+                            acc[event] = {};
+                        acc[event].total = perfResult.duration;
+                    }
+                    return acc;
+                }, {});
+                const pluginLoadTimeByType = Object.fromEntries(Performance.results
+                    .filter(({ name }) => name.startsWith('config.loadPlugins#'))
+                    .sort((a, b) => b.duration - a.duration)
+                    .map(({ scope, duration }) => [scope, duration]));
+                Performance._highlights = {
+                    configLoadTime: Performance.getResult('config.load')?.duration ?? 0,
+                    runTime: Performance.getResult('main.run')?.duration ?? 0,
+                    initTime: Performance.getResult('main.run#init')?.duration ?? 0,
+                    commandLoadTime,
+                    pluginLoadTimes,
+                    hookRunTimes,
+                    corePluginsLoadTime: pluginLoadTimeByType.core ?? 0,
+                    userPluginsLoadTime: pluginLoadTimeByType.user ?? 0,
+                    linkedPluginsLoadTime: pluginLoadTimeByType.link ?? 0,
+                };
+                resolve();
+            });
+            perfObserver.observe({ entryTypes: ['measure'], buffered: true });
+            for (const marker of Object.values(Performance.markers)) {
+                try {
+                    marker.measure();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            perf_hooks_1.performance.clearMarks();
+        });
+    }
+    /**
+     * Add debug logs for plugin loading performance
+     * @returns void
+     */
+    static debug() {
+        if (!Performance.enabled)
+            return;
+        const debug = require('debug')('perf');
+        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('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`);
+        }
+        debug('Hook Run Times:');
+        for (const [event, runTimes] of Object.entries(Performance.highlights.hookRunTimes)) {
+            debug(`  ${event}:`);
+            for (const [plugin, duration] of Object.entries(runTimes)) {
+                debug(`    ${plugin}: ${duration.toFixed(4)}ms`);
+            }
+        }
+    }
+}
+exports.Performance = Performance;
+Performance.markers = {};
+Performance._results = [];

package/lib/settings.d.ts

@@ -30,5 +30,10 @@ export type Settings = {
      *   NODE_ENV=development
      */
     tsnodeEnabled?: boolean;
+    /**
+     * Enable performance tracking. Resulting data is available in the `perf` property of the `Config` class.
+     * This will be overridden by the `enablePerf` property passed into Config constructor.
+     */
+    performanceEnabled?: boolean;
 };
 export declare const settings: Settings;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {
@@ -36,7 +36,7 @@
   },
   "devDependencies": {
     "@commitlint/config-conventional": "^12.1.4",
-    "@oclif/plugin-help": "^5.2.5",
+    "@oclif/plugin-help": "^5.2.7",
     "@oclif/plugin-plugins": "^2.3.2",
     "@oclif/test": "^2.3.7",
     "@types/ansi-styles": "^3.2.1",