@oclif/core 1.5.3 → 1.6.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.6.0](https://github.com/oclif/core/compare/v1.5.3...v1.6.0) (2022-03-14)
+
+
+### Features
+
+* POC for allowing flexible command taxonomy ([#376](https://github.com/oclif/core/issues/376)) ([c47c6c6](https://github.com/oclif/core/commit/c47c6c6fb689a92f66d40aacfa146d885f08d962))
+
 ### [1.5.3](https://github.com/oclif/core/compare/v1.5.2...v1.5.3) (2022-03-09)
 
 

package/lib/config/config.d.ts

@@ -29,10 +29,13 @@ export declare class Config implements IConfig {
     binPath?: string;
     valid: boolean;
     topicSeparator: ':' | ' ';
+    flexibleTaxonomy: boolean;
     protected warned: boolean;
-    private _commands?;
-    private _commandIDs?;
-    private _topics?;
+    private commandPermutations;
+    private topicPermutations;
+    private _commands;
+    private _topics;
+    private _commandIDs;
     constructor(options: Options);
     static load(opts?: LoadOptions): Promise<IConfig | Config>;
     load(): Promise<void>;
@@ -56,6 +59,30 @@ export declare class Config implements IConfig {
     findTopic(id: string, opts?: {
         must: boolean;
     }): Topic | undefined;
+    /**
+     * Find all command ids that include the provided command id.
+     *
+     * For example, if the command ids are:
+     * - foo:bar:baz
+     * - one:two:three
+     *
+     * `bar` would return `foo:bar:baz`
+     *
+     * @param partialCmdId string
+     * @param argv string[] process.argv containing the flags and arguments provided by the user
+     * @returns string[]
+     */
+    findMatches(partialCmdId: string, argv: string[]): Command.Plugin[];
+    /**
+     * Returns an array of all commands. If flexible taxonomy is enabled then all permutations will be appended to the array.
+     * @returns Command.Plugin[]
+     */
+    getAllCommands(): Command.Plugin[];
+    /**
+     * Returns an array of all command ids. If flexible taxonomy is enabled then all permutations will be appended to the array.
+     * @returns string[]
+     */
+    getAllCommandIDs(): string[];
     get commands(): Command.Plugin[];
     get commandIDs(): string[];
     get topics(): Topic[];
@@ -78,5 +105,29 @@ export declare class Config implements IConfig {
         detail: string;
     }, scope?: string): void;
     protected get isProd(): boolean;
+    private getCmdLookupId;
+    private getTopicLookupId;
+    private loadCommands;
+    private loadTopics;
+    /**
+     * This method is responsible for locating the correct plugin to use for a named command id
+     * It searches the {Config} registered commands to match either the raw command id or the command alias
+     * It is possible that more than one command will be found. This is due the ability of two distinct plugins to
+     * create the same command or command alias.
+     *
+     * In the case of more than one found command, the function will select the command based on the order in which
+     * the plugin is included in the package.json `oclif.plugins` list. The command that occurs first in the list
+     * is selected as the command to run.
+     *
+     * Commands can also be present from either an install or a link. When a command is one of these and a core plugin
+     * is present, this function defers to the core plugin.
+     *
+     * If there is not a core plugin command present, this function will return the first
+     * plugin as discovered (will not change the order)
+     *
+     * @param commands commands to determine the priority of
+     * @returns command instance {Command.Plugin} or undefined
+     */
+    private determinePriority;
 }
 export declare function toCached(c: Command.Class, plugin?: IPlugin): Promise<Command>;

package/lib/config/config.js

@@ -7,11 +7,11 @@ const os = require("os");
 const path = require("path");
 const url_1 = require("url");
 const util_1 = require("util");
-const util_2 = require("./util");
 const Plugin = require("./plugin");
-const util_3 = require("./util");
-const util_4 = require("../util");
+const util_2 = require("./util");
+const util_3 = require("../util");
 const module_loader_1 = require("../module-loader");
+const util_4 = require("../help/util");
 // eslint-disable-next-line new-cap
 const debug = (0, util_2.Debug)();
 const _pjson = require('../../package.json');
@@ -23,6 +23,36 @@ const WSL = require('is-wsl');
 function isConfig(o) {
     return o && Boolean(o._base);
 }
+class Permutations extends Map {
+    constructor() {
+        super(...arguments);
+        this.validPermutations = new Map();
+    }
+    add(permutation, commandId) {
+        this.validPermutations.set(permutation, commandId);
+        for (const id of (0, util_2.collectUsableIds)([permutation])) {
+            if (this.has(id)) {
+                this.set(id, this.get(id).add(commandId));
+            }
+            else {
+                this.set(id, new Set([commandId]));
+            }
+        }
+    }
+    get(key) {
+        var _a;
+        return (_a = super.get(key)) !== null && _a !== void 0 ? _a : new Set();
+    }
+    getValid(key) {
+        return this.validPermutations.get(key);
+    }
+    getAllValid() {
+        return [...this.validPermutations.keys()];
+    }
+    hasValid(key) {
+        return this.validPermutations.has(key);
+    }
+}
 class Config {
     // eslint-disable-next-line no-useless-constructor
     constructor(options) {
@@ -32,6 +62,10 @@ class Config {
         this.plugins = [];
         this.topicSeparator = ':';
         this.warned = false;
+        this.commandPermutations = new Permutations();
+        this.topicPermutations = new Permutations();
+        this._commands = new Map();
+        this._topics = new Map();
     }
     static async load(opts = (module.parent && module.parent.parent && module.parent.parent.filename) || __dirname) {
         // Handle the case when a file URL string is passed in such as 'import.meta.url'; covert to file path.
@@ -62,6 +96,7 @@ class Config {
         this.windows = this.platform === 'win32';
         this.bin = this.pjson.oclif.bin || this.name;
         this.dirname = this.pjson.oclif.dirname || this.name;
+        this.flexibleTaxonomy = this.pjson.oclif.flexibleTaxonomy || false;
         // currently, only colons or spaces are valid separators
         if (this.pjson.oclif.topicSeparator && [':', ' '].includes(this.pjson.oclif.topicSeparator))
             this.topicSeparator = this.pjson.oclif.topicSeparator;
@@ -104,6 +139,10 @@ class Config {
         await this.loadUserPlugins();
         await this.loadDevPlugins();
         await this.loadCorePlugins();
+        for (const plugin of this.plugins) {
+            this.loadCommands(plugin);
+            this.loadTopics(plugin);
+        }
         debug('config done');
     }
     async loadCorePlugins() {
@@ -129,7 +168,7 @@ class Config {
             try {
                 const userPJSONPath = path.join(this.dataDir, 'package.json');
                 debug('reading user plugins pjson %s', userPJSONPath);
-                const pjson = await (0, util_3.loadJSON)(userPJSONPath);
+                const pjson = await (0, util_2.loadJSON)(userPJSONPath);
                 this.userPJSON = pjson;
                 if (!pjson.oclif)
                     pjson.oclif = { schema: 1 };
@@ -214,7 +253,10 @@ class Config {
         debug('runCommand %s %o', id, argv);
         const c = cachedCommand || this.findCommand(id);
         if (!c) {
-            const hookResult = await this.runHook('command_not_found', { id, argv });
+            const matches = this.flexibleTaxonomy ? this.findMatches(id, argv) : [];
+            const hookResult = this.flexibleTaxonomy && matches.length > 0 ?
+                await this.runHook('command_incomplete', { id, argv, matches }) :
+                await this.runHook('command_not_found', { id, argv });
             if (hookResult.successes[0]) {
                 const cmdResult = hookResult.successes[0].result;
                 return cmdResult;
@@ -240,106 +282,79 @@ class Config {
             .join('_')
             .toUpperCase();
     }
-    /**
-     * This function is responsible for locating the correct plugin to use for a named command id
-     * It searches the {Config} registered commands to match either the raw command id or the command alias
-     * It is possible that more than one command will be found. This is due the ability of two distinct plugins to
-     * create the same command or command alias.
-     *
-     * In the case of more than one found command, the function will select the command based on the order in which
-     * the plugin is included in the package.json `oclif.plugins` list. The command that occurs first in the list
-     * is selected as the command to run.
-     *
-     * Commands can also be present from either an install or a link. When a command is one of these and a core plugin
-     * is present, this function defers to the core plugin.
-     *
-     * If there is not a core plugin command present, this function will return the first
-     * plugin as discovered (will not change the order)
-     * @param id raw command id or command alias
-     * @param opts options to control if the command must be found
-     * @returns command instance {Command.Plugin} or undefined
-     */
     findCommand(id, opts = {}) {
-        var _a, _b;
-        const commands = this.commands.filter(c => c.id === id || c.aliases.includes(id));
-        if (opts.must && commands.length === 0)
-            (0, errors_1.error)(`command ${id} not found`);
-        if (commands.length === 1)
-            return commands[0];
-        // more than one command found across available plugins
-        const oclifPlugins = (_b = (_a = this.pjson.oclif) === null || _a === void 0 ? void 0 : _a.plugins) !== null && _b !== void 0 ? _b : [];
-        const commandPlugins = commands.sort((a, b) => {
-            var _a, _b;
-            const pluginAliasA = (_a = a.pluginAlias) !== null && _a !== void 0 ? _a : 'A-Cannot-Find-This';
-            const pluginAliasB = (_b = b.pluginAlias) !== null && _b !== void 0 ? _b : 'B-Cannot-Find-This';
-            const aIndex = oclifPlugins.indexOf(pluginAliasA);
-            const bIndex = oclifPlugins.indexOf(pluginAliasB);
-            // When both plugin types are 'core' plugins sort based on index
-            if (a.pluginType === 'core' && b.pluginType === 'core') {
-                // If b appears first in the pjson.plugins sort it first
-                return aIndex - bIndex;
-            }
-            // if b is a core plugin and a is not sort b first
-            if (b.pluginType === 'core' && a.pluginType !== 'core') {
-                return 1;
-            }
-            // if a is a core plugin and b is not sort a first
-            if (a.pluginType === 'core' && b.pluginType !== 'core') {
-                return -1;
-            }
-            // neither plugin is core, so do not change the order
-            return 0;
-        });
-        return commandPlugins[0];
+        const lookupId = this.getCmdLookupId(id);
+        const command = this._commands.get(lookupId);
+        if (opts.must && !command)
+            (0, errors_1.error)(`command ${lookupId} not found`);
+        return command;
     }
     findTopic(name, opts = {}) {
-        const topic = this.topics.find(t => t.name === name);
+        const lookupId = this.getTopicLookupId(name);
+        const topic = this._topics.get(lookupId);
         if (topic)
             return topic;
         if (opts.must)
             throw new Error(`topic ${name} not found`);
     }
+    /**
+     * Find all command ids that include the provided command id.
+     *
+     * For example, if the command ids are:
+     * - foo:bar:baz
+     * - one:two:three
+     *
+     * `bar` would return `foo:bar:baz`
+     *
+     * @param partialCmdId string
+     * @param argv string[] process.argv containing the flags and arguments provided by the user
+     * @returns string[]
+     */
+    findMatches(partialCmdId, argv) {
+        const flags = argv.filter(arg => !(0, util_4.getHelpFlagAdditions)(this).includes(arg) && arg.startsWith('-')).map(a => a.replace(/-/g, ''));
+        const possibleMatches = [...this.commandPermutations.get(partialCmdId)].map(k => this._commands.get(k));
+        const matches = possibleMatches.filter(command => {
+            const cmdFlags = Object.entries(command.flags).flatMap(([flag, def]) => {
+                return def.char ? [def.char, flag] : [flag];
+            });
+            // A command is a match if the provided flags belong to the full command
+            return flags.every(f => cmdFlags.includes(f));
+        });
+        return matches;
+    }
+    /**
+     * Returns an array of all commands. If flexible taxonomy is enabled then all permutations will be appended to the array.
+     * @returns Command.Plugin[]
+     */
+    getAllCommands() {
+        const commands = [...this._commands.values()];
+        const validPermutations = [...this.commandPermutations.getAllValid()];
+        for (const permutation of validPermutations) {
+            if (!this._commands.has(permutation)) {
+                const cmd = this._commands.get(this.getCmdLookupId(permutation));
+                commands.push({ ...cmd, id: permutation });
+            }
+        }
+        return commands;
+    }
+    /**
+     * Returns an array of all command ids. If flexible taxonomy is enabled then all permutations will be appended to the array.
+     * @returns string[]
+     */
+    getAllCommandIDs() {
+        return this.getAllCommands().map(c => c.id);
+    }
     get commands() {
-        if (this._commands)
-            return this._commands;
-        this._commands = (0, util_3.flatMap)(this.plugins, p => p.commands);
-        return this._commands;
+        return [...this._commands.values()];
     }
     get commandIDs() {
         if (this._commandIDs)
             return this._commandIDs;
-        const ids = this.commands.flatMap(c => [c.id, ...c.aliases]);
-        this._commandIDs = (0, util_3.uniq)(ids);
+        this._commandIDs = this.commands.map(c => c.id);
         return this._commandIDs;
     }
     get topics() {
-        if (this._topics)
-            return this._topics;
-        const topics = [];
-        for (const plugin of this.plugins) {
-            for (const topic of (0, util_3.compact)(plugin.topics)) {
-                const existing = topics.find(t => t.name === topic.name);
-                if (existing) {
-                    existing.description = topic.description || existing.description;
-                    existing.hidden = existing.hidden || topic.hidden;
-                }
-                else
-                    topics.push(topic);
-            }
-        }
-        // add missing topics
-        for (const c of this.commands.filter(c => !c.hidden)) {
-            const parts = c.id.split(':');
-            while (parts.length > 0) {
-                const name = parts.join(':');
-                if (name && !topics.find(t => t.name === name)) {
-                    topics.push({ name, description: c.summary || c.description });
-                }
-                parts.pop();
-            }
-        }
-        this._topics = topics;
-        return this._topics;
+        return [...this._topics.values()];
     }
     s3Key(type, ext, options = {}) {
         var _a;
@@ -444,7 +459,7 @@ class Config {
         if (err instanceof Error) {
             const modifiedErr = err;
             modifiedErr.name = `${err.name} Plugin: ${this.name}`;
-            modifiedErr.detail = (0, util_3.compact)([
+            modifiedErr.detail = (0, util_2.compact)([
                 err.detail,
                 `module: ${this._base}`,
                 scope && `task: ${scope}`,
@@ -458,7 +473,7 @@ class Config {
         // err is an object
         process.emitWarning('Config.warn expected either a string or Error, but instead received an object');
         err.name = `${err.name} Plugin: ${this.name}`;
-        err.detail = (0, util_3.compact)([
+        err.detail = (0, util_2.compact)([
             err.detail,
             `module: ${this._base}`,
             scope && `task: ${scope}`,
@@ -469,7 +484,123 @@ class Config {
         process.emitWarning(JSON.stringify(err));
     }
     get isProd() {
-        return (0, util_4.isProd)();
+        return (0, util_3.isProd)();
+    }
+    getCmdLookupId(id) {
+        if (this._commands.has(id))
+            return id;
+        if (this.commandPermutations.hasValid(id))
+            return this.commandPermutations.getValid(id);
+        return id;
+    }
+    getTopicLookupId(id) {
+        if (this._topics.has(id))
+            return id;
+        if (this.topicPermutations.hasValid(id))
+            return this.topicPermutations.getValid(id);
+        return id;
+    }
+    loadCommands(plugin) {
+        var _a;
+        for (const command of plugin.commands) {
+            if (this._commands.has(command.id)) {
+                const prioritizedCommand = this.determinePriority([this._commands.get(command.id), command]);
+                this._commands.set(prioritizedCommand.id, prioritizedCommand);
+            }
+            else {
+                this._commands.set(command.id, command);
+            }
+            const permutations = this.flexibleTaxonomy ? (0, util_2.getCommandIdPermutations)(command.id) : [command.id];
+            for (const permutation of permutations) {
+                this.commandPermutations.add(permutation, command.id);
+            }
+            for (const alias of (_a = command.aliases) !== null && _a !== void 0 ? _a : []) {
+                if (this._commands.has(alias)) {
+                    const prioritizedCommand = this.determinePriority([this._commands.get(alias), command]);
+                    this._commands.set(prioritizedCommand.id, prioritizedCommand);
+                }
+                else {
+                    this._commands.set(alias, command);
+                }
+                const aliasPermutations = this.flexibleTaxonomy ? (0, util_2.getCommandIdPermutations)(alias) : [alias];
+                for (const permutation of aliasPermutations) {
+                    this.commandPermutations.add(permutation, command.id);
+                }
+            }
+        }
+    }
+    loadTopics(plugin) {
+        for (const topic of (0, util_2.compact)(plugin.topics)) {
+            const existing = this._topics.get(topic.name);
+            if (existing) {
+                existing.description = topic.description || existing.description;
+                existing.hidden = existing.hidden || topic.hidden;
+            }
+            else {
+                this._topics.set(topic.name, topic);
+            }
+            const permutations = this.flexibleTaxonomy ? (0, util_2.getCommandIdPermutations)(topic.name) : [topic.name];
+            for (const permutation of permutations) {
+                this.topicPermutations.add(permutation, topic.name);
+            }
+        }
+        // Add missing topics for displaying help when partial commands are entered.
+        for (const c of plugin.commands.filter(c => !c.hidden)) {
+            const parts = c.id.split(':');
+            while (parts.length > 0) {
+                const name = parts.join(':');
+                if (name && !this._topics.has(name)) {
+                    this._topics.set(name, { name, description: c.summary || c.description });
+                }
+                parts.pop();
+            }
+        }
+    }
+    /**
+     * This method is responsible for locating the correct plugin to use for a named command id
+     * It searches the {Config} registered commands to match either the raw command id or the command alias
+     * It is possible that more than one command will be found. This is due the ability of two distinct plugins to
+     * create the same command or command alias.
+     *
+     * In the case of more than one found command, the function will select the command based on the order in which
+     * the plugin is included in the package.json `oclif.plugins` list. The command that occurs first in the list
+     * is selected as the command to run.
+     *
+     * Commands can also be present from either an install or a link. When a command is one of these and a core plugin
+     * is present, this function defers to the core plugin.
+     *
+     * If there is not a core plugin command present, this function will return the first
+     * plugin as discovered (will not change the order)
+     *
+     * @param commands commands to determine the priority of
+     * @returns command instance {Command.Plugin} or undefined
+     */
+    determinePriority(commands) {
+        var _a, _b;
+        const oclifPlugins = (_b = (_a = this.pjson.oclif) === null || _a === void 0 ? void 0 : _a.plugins) !== null && _b !== void 0 ? _b : [];
+        const commandPlugins = commands.sort((a, b) => {
+            var _a, _b;
+            const pluginAliasA = (_a = a.pluginAlias) !== null && _a !== void 0 ? _a : 'A-Cannot-Find-This';
+            const pluginAliasB = (_b = b.pluginAlias) !== null && _b !== void 0 ? _b : 'B-Cannot-Find-This';
+            const aIndex = oclifPlugins.indexOf(pluginAliasA);
+            const bIndex = oclifPlugins.indexOf(pluginAliasB);
+            // When both plugin types are 'core' plugins sort based on index
+            if (a.pluginType === 'core' && b.pluginType === 'core') {
+                // If b appears first in the pjson.plugins sort it first
+                return aIndex - bIndex;
+            }
+            // if b is a core plugin and a is not sort b first
+            if (b.pluginType === 'core' && a.pluginType !== 'core') {
+                return 1;
+            }
+            // if a is a core plugin and b is not sort a first
+            if (a.pluginType === 'core' && b.pluginType !== 'core') {
+                return -1;
+            }
+            // neither plugin is core, so do not change the order
+            return 0;
+        });
+        return commandPlugins[0];
     }
 }
 exports.Config = Config;

package/lib/config/plugin.js

@@ -126,9 +126,10 @@ class Plugin {
         }
         this.hooks = (0, util_3.mapValues)(this.pjson.oclif.hooks || {}, i => Array.isArray(i) ? i : [i]);
         this.manifest = await this._manifest(Boolean(this.options.ignoreManifest), Boolean(this.options.errorOnManifestCreate));
-        this.commands = Object.entries(this.manifest.commands)
-            .map(([id, c]) => ({ ...c, pluginAlias: this.alias, pluginType: this.type, load: async () => this.findCommand(id, { must: true }) }));
-        this.commands.sort((a, b) => a.id.localeCompare(b.id));
+        this.commands = Object
+            .entries(this.manifest.commands)
+            .map(([id, c]) => ({ ...c, pluginAlias: this.alias, pluginType: this.type, load: async () => this.findCommand(id, { must: true }) }))
+            .sort((a, b) => a.id.localeCompare(b.id));
     }
     get topics() {
         return topicsToArray(this.pjson.oclif.topics || {});

package/lib/config/util.d.ts

@@ -12,3 +12,25 @@ export declare function loadJSON(path: string): Promise<any>;
 export declare function compact<T>(a: (T | undefined)[]): T[];
 export declare function uniq<T>(arr: T[]): T[];
 export declare function Debug(...scope: string[]): (..._: any) => void;
+export declare function getPermutations(arr: string[]): Array<string[]>;
+export declare function getCommandIdPermutations(commandId: string): string[];
+/**
+ * Return an array of ids that represent all the usable combinations that a user could enter.
+ *
+ * For example, if the command ids are:
+ * - foo:bar:baz
+ * - one:two:three
+ * Then the usable ids would be:
+ * - foo
+ * - foo:bar
+ * - foo:bar:baz
+ * - one
+ * - one:two
+ * - one:two:three
+ *
+ * This allows us to determine which parts of the argv array belong to the command id whenever the topicSeparator is a space.
+ *
+ * @param commandIds string[]
+ * @returns string[]
+ */
+export declare function collectUsableIds(commandIds: string[]): string[];

package/lib/config/util.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Debug = exports.uniq = exports.compact = exports.loadJSON = exports.resolvePackage = exports.exists = exports.mapValues = exports.flatMap = void 0;
+exports.collectUsableIds = exports.getCommandIdPermutations = exports.getPermutations = exports.Debug = exports.uniq = exports.compact = exports.loadJSON = exports.resolvePackage = exports.exists = exports.mapValues = exports.flatMap = void 0;
 const fs = require("fs");
 const debug = require('debug');
 function flatMap(arr, fn) {
@@ -46,9 +46,7 @@ function compact(a) {
 }
 exports.compact = compact;
 function uniq(arr) {
-    return arr.filter((a, i) => {
-        return !arr.find((b, j) => j > i && b === a);
-    });
+    return [...new Set(arr)].sort();
 }
 exports.uniq = uniq;
 function displayWarnings() {
@@ -69,3 +67,61 @@ function Debug(...scope) {
     return (...args) => d(...args);
 }
 exports.Debug = Debug;
+// Adapted from https://github.com/angus-c/just/blob/master/packages/array-permutations/index.js
+function getPermutations(arr) {
+    if (arr.length === 0)
+        return [];
+    if (arr.length === 1)
+        return [arr];
+    const output = [];
+    const partialPermutations = getPermutations(arr.slice(1));
+    const first = arr[0];
+    for (let i = 0, len = partialPermutations.length; i < len; i++) {
+        const partial = partialPermutations[i];
+        for (let j = 0, len2 = partial.length; j <= len2; j++) {
+            const start = partial.slice(0, j);
+            const end = partial.slice(j);
+            const merged = start.concat(first, end);
+            output.push(merged);
+        }
+    }
+    return output;
+}
+exports.getPermutations = getPermutations;
+function getCommandIdPermutations(commandId) {
+    return getPermutations(commandId.split(':')).flatMap(c => c.join(':'));
+}
+exports.getCommandIdPermutations = getCommandIdPermutations;
+/**
+ * Return an array of ids that represent all the usable combinations that a user could enter.
+ *
+ * For example, if the command ids are:
+ * - foo:bar:baz
+ * - one:two:three
+ * Then the usable ids would be:
+ * - foo
+ * - foo:bar
+ * - foo:bar:baz
+ * - one
+ * - one:two
+ * - one:two:three
+ *
+ * This allows us to determine which parts of the argv array belong to the command id whenever the topicSeparator is a space.
+ *
+ * @param commandIds string[]
+ * @returns string[]
+ */
+function collectUsableIds(commandIds) {
+    const usuableIds = [];
+    for (const id of commandIds) {
+        const parts = id.split(':');
+        while (parts.length > 0) {
+            const name = parts.join(':');
+            if (name)
+                usuableIds.push(name);
+            parts.pop();
+        }
+    }
+    return uniq(usuableIds).sort();
+}
+exports.collectUsableIds = collectUsableIds;

package/lib/help/index.d.ts

@@ -2,8 +2,7 @@ import * as Interfaces from '../interfaces';
 import CommandHelp from './command';
 import { HelpFormatter } from './formatter';
 export { CommandHelp } from './command';
-export { standardizeIDFromArgv, loadHelpClass } from './util';
-export declare function getHelpFlagAdditions(config: Interfaces.Config): string[];
+export { standardizeIDFromArgv, loadHelpClass, getHelpFlagAdditions } from './util';
 export declare abstract class HelpBase extends HelpFormatter {
     constructor(config: Interfaces.Config, opts?: Partial<Interfaces.HelpOptions>);
     /**

package/lib/help/index.js

@@ -15,16 +15,10 @@ Object.defineProperty(exports, "CommandHelp", { enumerable: true, get: function
 var util_3 = require("./util");
 Object.defineProperty(exports, "standardizeIDFromArgv", { enumerable: true, get: function () { return util_3.standardizeIDFromArgv; } });
 Object.defineProperty(exports, "loadHelpClass", { enumerable: true, get: function () { return util_3.loadHelpClass; } });
-const helpFlags = ['--help'];
-function getHelpFlagAdditions(config) {
-    var _a;
-    const additionalHelpFlags = (_a = config.pjson.oclif.additionalHelpFlags) !== null && _a !== void 0 ? _a : [];
-    return [...new Set([...helpFlags, ...additionalHelpFlags]).values()];
-}
-exports.getHelpFlagAdditions = getHelpFlagAdditions;
+Object.defineProperty(exports, "getHelpFlagAdditions", { enumerable: true, get: function () { return util_3.getHelpFlagAdditions; } });
 function getHelpSubject(args, config) {
     // for each help flag that starts with '--' create a new flag with same name sans '--'
-    const mergedHelpFlags = getHelpFlagAdditions(config);
+    const mergedHelpFlags = (0, util_2.getHelpFlagAdditions)(config);
     for (const arg of args) {
         if (arg === '--')
             return;
@@ -76,7 +70,8 @@ class Help extends HelpBase {
         return topics;
     }
     async showHelp(argv) {
-        argv = argv.filter(arg => !getHelpFlagAdditions(this.config).includes(arg));
+        const originalArgv = argv.slice(1);
+        argv = argv.filter(arg => !(0, util_2.getHelpFlagAdditions)(this.config).includes(arg));
         if (this.config.topicSeparator !== ':')
             argv = (0, util_2.standardizeIDFromArgv)(argv, this.config);
         const subject = getHelpSubject(argv, this.config);
@@ -105,6 +100,14 @@ class Help extends HelpBase {
             await this.showTopicHelp(topic);
             return;
         }
+        if (this.config.flexibleTaxonomy) {
+            const matches = this.config.findMatches(subject, originalArgv);
+            if (matches.length > 0) {
+                const result = await this.config.runHook('command_incomplete', { id: subject, argv: originalArgv, matches });
+                if (result.successes.length > 0)
+                    return;
+            }
+        }
         (0, errors_1.error)(`Command ${subject} not found.`);
     }
     async getDynamicCommand(cmdName) {

package/lib/help/util.d.ts

@@ -8,4 +8,5 @@ export declare function template(context: any): (t: string) => string;
 export declare function toStandardizedId(commandID: string, config: IConfig): string;
 export declare function toConfiguredId(commandID: string, config: IConfig): string;
 export declare function standardizeIDFromArgv(argv: string[], config: IConfig): string[];
+export declare function getHelpFlagAdditions(config: IConfig): string[];
 export {};

package/lib/help/util.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.standardizeIDFromArgv = exports.toConfiguredId = exports.toStandardizedId = exports.template = exports.loadHelpClass = void 0;
+exports.getHelpFlagAdditions = exports.standardizeIDFromArgv = exports.toConfiguredId = exports.toStandardizedId = exports.template = exports.loadHelpClass = void 0;
 const ejs = require("ejs");
 const _1 = require(".");
 const module_loader_1 = require("../module-loader");
+const util_1 = require("../config/util");
 function extractClass(exported) {
     return exported && exported.default ? exported.default : exported;
 }
@@ -32,22 +33,20 @@ exports.template = template;
 function collateSpacedCmdIDFromArgs(argv, config) {
     if (argv.length === 1)
         return argv;
-    const ids = new Set(config.commandIDs.concat(config.topics.map(t => t.name)));
+    const ids = (0, util_1.collectUsableIds)(config.commandIDs);
     const findId = (argv) => {
         const final = [];
-        const idPresent = (id) => ids.has(id);
+        const idPresent = (id) => ids.includes(id);
         const isFlag = (s) => s.startsWith('-');
         const isArgWithValue = (s) => s.includes('=');
         const finalizeId = (s) => s ? [...final, s].join(':') : final.join(':');
         const hasSubCommandsWithArgs = () => {
             const id = finalizeId();
-            /**
-             * Get a list of sub commands for the current command id. A command is returned as a subcommand under either
-             * of these conditions:
-             * 1. the `id` start with the current command id.
-             * 2. any of the aliases start with the current command id.
-             */
-            const subCommands = config.commands.filter(c => (c.id).startsWith(id) || c.aliases.some(a => a.startsWith(id)));
+            if (!id)
+                return false;
+            // Get a list of sub commands for the current command id. A command is returned as a subcommand if the `id` starts with the current command id.
+            // e.g. `foo:bar` is a subcommand of `foo`
+            const subCommands = config.commands.filter(c => (c.id).startsWith(id));
             return Boolean(subCommands.find(cmd => { var _a; return cmd.strict === false || ((_a = cmd.args) === null || _a === void 0 ? void 0 : _a.length) > 0; }));
         };
         for (const arg of argv) {
@@ -88,3 +87,10 @@ function standardizeIDFromArgv(argv, config) {
     return argv;
 }
 exports.standardizeIDFromArgv = standardizeIDFromArgv;
+function getHelpFlagAdditions(config) {
+    var _a;
+    const helpFlags = ['--help'];
+    const additionalHelpFlags = (_a = config.pjson.oclif.additionalHelpFlags) !== null && _a !== void 0 ? _a : [];
+    return [...new Set([...helpFlags, ...additionalHelpFlags]).values()];
+}
+exports.getHelpFlagAdditions = getHelpFlagAdditions;

package/lib/interfaces/config.d.ts

@@ -86,6 +86,7 @@ export interface Config {
     plugins: Plugin[];
     binPath?: string;
     valid: boolean;
+    flexibleTaxonomy?: boolean;
     topicSeparator: ':' | ' ';
     readonly commands: Command.Plugin[];
     readonly topics: Topic[];
@@ -93,6 +94,8 @@ export interface Config {
     runCommand<T = unknown>(id: string, argv?: string[]): Promise<T>;
     runCommand<T = unknown>(id: string, argv?: string[], cachedCommand?: Command.Plugin): Promise<T>;
     runHook<T extends keyof Hooks>(event: T, opts: Hooks[T]['options'], timeout?: number): Promise<Hook.Result<Hooks[T]['return']>>;
+    getAllCommandIDs(): string[];
+    getAllCommands(): Command.Plugin[];
     findCommand(id: string, opts: {
         must: true;
     }): Command.Plugin;
@@ -105,6 +108,7 @@ export interface Config {
     findTopic(id: string, opts?: {
         must: boolean;
     }): Topic | undefined;
+    findMatches(id: string, argv: string[]): Command.Plugin[];
     scopedEnvVar(key: string): string | undefined;
     scopedEnvVarKey(key: string): string;
     scopedEnvVarTrue(key: string): boolean;

package/lib/interfaces/hooks.d.ts

@@ -50,6 +50,14 @@ export interface Hooks {
         };
         return: unknown;
     };
+    'command_incomplete': {
+        options: {
+            id: string;
+            argv: string[];
+            matches: Command.Plugin[];
+        };
+        return: unknown;
+    };
     'plugins:preinstall': {
         options: {
             plugin: {
@@ -75,6 +83,7 @@ export declare namespace Hook {
     type Preupdate = Hook<'preupdate'>;
     type Update = Hook<'update'>;
     type CommandNotFound = Hook<'command_not_found'>;
+    type CommandIncomplete = Hook<'command_incomplete'>;
     interface Context {
         config: Config;
         exit(code?: number): void;

package/lib/interfaces/pjson.d.ts

@@ -16,6 +16,7 @@ export declare namespace PJSON {
             schema?: number;
             description?: string;
             topicSeparator?: ':' | ' ';
+            flexibleTaxonomy?: boolean;
             hooks?: {
                 [name: string]: (string | string[]);
             };
@@ -78,6 +79,7 @@ export declare namespace PJSON {
             npmRegistry?: string;
             scope?: string;
             dirname?: string;
+            flexibleTaxonomy?: boolean;
         };
     }
     interface User extends PJSON {

package/lib/main.js

@@ -62,7 +62,7 @@ async function run(argv = process.argv.slice(2), options) {
     // find & run command
     const cmd = config.findCommand(id);
     if (!cmd) {
-        const topic = config.findTopic(id);
+        const topic = config.flexibleTaxonomy ? null : config.findTopic(id);
         if (topic)
             return config.runCommand('help', [id]);
         if (config.pjson.oclif.default) {

package/package.json

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