@oclif/plugin-help 2.2.3 → 3.0.0

package/lib/_test-help-class.d.ts

@@ -0,0 +1,6 @@
+import { HelpBase } from '.';
+export default class extends HelpBase {
+    showHelp(): void;
+    showCommandHelp(): void;
+    getCommandHelpForReadme(): string;
+}

package/lib/_test-help-class.js

@@ -0,0 +1,19 @@
+"use strict";
+// `getHelpClass` tests require an oclif project for testing so
+// it is re-using the setup here to be able to do a lookup for
+// this sample help class file in tests, although it is not needed
+// for @oclif/plugin-help itself.
+Object.defineProperty(exports, "__esModule", { value: true });
+const _1 = require(".");
+class default_1 extends _1.HelpBase {
+    showHelp() {
+        console.log('help');
+    }
+    showCommandHelp() {
+        console.log('command help');
+    }
+    getCommandHelpForReadme() {
+        return 'help for readme';
+    }
+}
+exports.default = default_1;

package/lib/commands/help.js

@@ -5,7 +5,8 @@ const __1 = require("..");
 class HelpCommand extends command_1.Command {
     async run() {
         const { flags, argv } = this.parse(HelpCommand);
-        const help = new __1.default(this.config, { all: flags.all });
+        const Help = __1.getHelpClass(this.config);
+        const help = new Help(this.config, { all: flags.all });
         help.showHelp(argv);
     }
 }

package/lib/index.d.ts

@@ -1,18 +1,45 @@
 import * as Config from '@oclif/config';
+export { getHelpClass } from './util';
 export interface HelpOptions {
     all?: boolean;
     maxWidth: number;
     stripAnsi?: boolean;
 }
-export default class Help {
-    config: Config.IConfig;
-    opts: HelpOptions;
+export declare abstract class HelpBase {
+    constructor(config: Config.IConfig, opts?: Partial<HelpOptions>);
+    protected config: Config.IConfig;
+    protected opts: HelpOptions;
+    /**
+     * Show help, used in multi-command CLIs
+     * @param args passed into your command, useful for determining which type of help to display
+     */
+    abstract showHelp(argv: string[]): void;
+    /**
+     * Show help for an individual command
+     * @param command
+     * @param topics
+     */
+    abstract showCommandHelp(command: Config.Command, topics: Config.Topic[]): void;
+}
+export default class Help extends HelpBase {
     render: (input: string) => string;
+    private get _topics();
+    protected get sortedCommands(): Config.Command.Plugin[];
+    protected get sortedTopics(): Config.Topic[];
     constructor(config: Config.IConfig, opts?: Partial<HelpOptions>);
     showHelp(argv: string[]): void;
-    showCommandHelp(command: Config.Command, topics: Config.Topic[]): void;
-    root(): string;
-    topic(topic: Config.Topic): string;
-    command(command: Config.Command): string;
-    topics(topics: Config.Topic[]): string | undefined;
+    showCommandHelp(command: Config.Command): void;
+    protected showRootHelp(): void;
+    protected showTopicHelp(topic: Config.Topic): void;
+    protected formatRoot(): string;
+    protected formatCommand(command: Config.Command): string;
+    protected formatCommands(commands: Config.Command[]): string;
+    protected formatTopic(topic: Config.Topic): string;
+    protected formatTopics(topics: Config.Topic[]): string;
+    /**
+     * @deprecated used for readme generation
+     * @param {object} command The command to generate readme help for
+     * @return {string} the readme help string for the given command
+     */
+    protected command(command: Config.Command): string;
 }

package/lib/index.js

@@ -9,12 +9,11 @@ const list_1 = require("./list");
 const root_1 = require("./root");
 const screen_1 = require("./screen");
 const util_1 = require("./util");
+var util_2 = require("./util");
+exports.getHelpClass = util_2.getHelpClass;
 const wrap = require('wrap-ansi');
 const { bold, } = chalk_1.default;
 function getHelpSubject(args) {
-    // special case
-    // if (['help:help', 'help:--help', '--help:help'].includes(argv.slice(0, 2).join(':'))) {
-    // if (argv[0] === 'help') return 'help'
     for (const arg of args) {
         if (arg === '--')
             return;
@@ -25,71 +24,140 @@ function getHelpSubject(args) {
         return arg;
     }
 }
-class Help {
+class HelpBase {
     constructor(config, opts = {}) {
         this.config = config;
         this.opts = Object.assign({ maxWidth: screen_1.stdtermwidth }, opts);
+    }
+}
+exports.HelpBase = HelpBase;
+class Help extends HelpBase {
+    constructor(config, opts = {}) {
+        super(config, opts);
         this.render = util_1.template(this);
     }
-    showHelp(argv) {
-        let topics = this.config.topics;
+    /*
+     * _topics is to work around Config.topics mistakenly including commands that do
+     * not have children, as well as topics. A topic has children, either commands or other topics. When
+     * this is fixed upstream config.topics should return *only* topics with children,
+     * and this can be removed.
+     */
+    get _topics() {
+        return this.config.topics.filter((topic) => {
+            // it is assumed a topic has a child if it has children
+            const hasChild = this.config.topics.some(subTopic => subTopic.name.includes(`${topic.name}:`));
+            return hasChild;
+        });
+    }
+    get sortedCommands() {
+        let commands = this.config.commands;
+        commands = commands.filter(c => this.opts.all || !c.hidden);
+        commands = util_1.sortBy(commands, c => c.id);
+        commands = util_1.uniqBy(commands, c => c.id);
+        return commands;
+    }
+    get sortedTopics() {
+        let topics = this._topics;
         topics = topics.filter(t => this.opts.all || !t.hidden);
         topics = util_1.sortBy(topics, t => t.name);
         topics = util_1.uniqBy(topics, t => t.name);
+        return topics;
+    }
+    showHelp(argv) {
         const subject = getHelpSubject(argv);
-        let command;
-        if (subject) {
-            command = this.config.findCommand(subject);
-        }
-        let topic;
-        if (subject && !command) {
-            topic = this.config.findTopic(subject);
-        }
         if (!subject) {
-            console.log(this.root());
-            console.log('');
-            if (!this.opts.all) {
-                topics = topics.filter(t => !t.name.includes(':'));
-            }
-            console.log(this.topics(topics));
-            console.log('');
-        }
-        else if (command) {
-            this.showCommandHelp(command, topics);
+            this.showRootHelp();
+            return;
         }
-        else if (topic) {
-            const name = topic.name;
-            const depth = name.split(':').length;
-            topics = topics.filter(t => t.name.startsWith(name + ':') && t.name.split(':').length === depth + 1);
-            console.log(this.topic(topic));
-            if (topics.length > 0) {
-                console.log(this.topics(topics));
-                console.log('');
-            }
+        const command = this.config.findCommand(subject);
+        if (command) {
+            this.showCommandHelp(command);
+            return;
         }
-        else {
-            errors_1.error(`command ${subject} not found`);
+        const topic = this.config.findTopic(subject);
+        if (topic) {
+            this.showTopicHelp(topic);
+            return;
         }
+        errors_1.error(`command ${subject} not found`);
     }
-    showCommandHelp(command, topics) {
+    showCommandHelp(command) {
         const name = command.id;
         const depth = name.split(':').length;
-        topics = topics.filter(t => t.name.startsWith(name + ':') && t.name.split(':').length === depth + 1);
+        const subTopics = this.sortedTopics.filter(t => t.name.startsWith(name + ':') && t.name.split(':').length === depth + 1);
+        const subCommands = this.sortedCommands.filter(c => c.id.startsWith(name + ':') && c.id.split(':').length === depth + 1);
         const title = command.description && this.render(command.description).split('\n')[0];
         if (title)
             console.log(title + '\n');
-        console.log(this.command(command));
+        console.log(this.formatCommand(command));
         console.log('');
-        if (topics.length > 0) {
-            console.log(this.topics(topics));
+        if (subTopics.length > 0) {
+            console.log(this.formatTopics(subTopics));
+            console.log('');
+        }
+        if (subCommands.length > 0) {
+            console.log(this.formatCommands(subCommands));
+            console.log('');
+        }
+    }
+    showRootHelp() {
+        let rootTopics = this.sortedTopics;
+        let rootCommands = this.sortedCommands;
+        console.log(this.formatRoot());
+        console.log('');
+        if (!this.opts.all) {
+            rootTopics = rootTopics.filter(t => !t.name.includes(':'));
+            rootCommands = rootCommands.filter(c => !c.id.includes(':'));
+        }
+        if (rootTopics.length > 0) {
+            console.log(this.formatTopics(rootTopics));
+            console.log('');
+        }
+        if (rootCommands.length > 0) {
+            console.log(this.formatCommands(rootCommands));
+            console.log('');
+        }
+    }
+    showTopicHelp(topic) {
+        const name = topic.name;
+        const depth = name.split(':').length;
+        const subTopics = this.sortedTopics.filter(t => t.name.startsWith(name + ':') && t.name.split(':').length === depth + 1);
+        const commands = this.sortedCommands.filter(c => c.id.startsWith(name + ':') && c.id.split(':').length === depth + 1);
+        console.log(this.formatTopic(topic));
+        if (subTopics.length > 0) {
+            console.log(this.formatTopics(subTopics));
+            console.log('');
+        }
+        if (commands.length > 0) {
+            console.log(this.formatCommands(commands));
             console.log('');
         }
     }
-    root() {
+    formatRoot() {
         const help = new root_1.default(this.config, this.opts);
         return help.root();
     }
-    topic(topic) {
+    formatCommand(command) {
+        const help = new command_1.default(command, this.config, this.opts);
+        return help.generate();
+    }
+    formatCommands(commands) {
+        if (commands.length === 0)
+            return '';
+        const body = list_1.renderList(commands.map(c => [
+            c.id,
+            c.description && this.render(c.description.split('\n')[0]),
+        ]), {
+            spacer: '\n',
+            stripAnsi: this.opts.stripAnsi,
+            maxWidth: this.opts.maxWidth - 2,
+        });
+        return [
+            bold('COMMANDS'),
+            indent(body, 2),
+        ].join('\n');
+    }
+    formatTopic(topic) {
         let description = this.render(topic.description || '');
         const title = description.split('\n')[0];
         description = description.split('\n').slice(1).join('\n');
@@ -108,13 +176,9 @@ class Help {
             output = stripAnsi(output);
         return output + '\n';
     }
-    command(command) {
-        const help = new command_1.default(command, this.config, this.opts);
-        return help.generate();
-    }
-    topics(topics) {
+    formatTopics(topics) {
         if (topics.length === 0)
-            return;
+            return '';
         const body = list_1.renderList(topics.map(c => [
             c.name,
             c.description && this.render(c.description.split('\n')[0]),
@@ -124,12 +188,17 @@ class Help {
             maxWidth: this.opts.maxWidth - 2,
         });
         return [
-            bold('COMMANDS'),
+            bold('TOPICS'),
             indent(body, 2),
         ].join('\n');
     }
+    /**
+     * @deprecated used for readme generation
+     * @param {object} command The command to generate readme help for
+     * @return {string} the readme help string for the given command
+     */
+    command(command) {
+        return this.formatCommand(command);
+    }
 }
 exports.default = Help;
-// function id(c: Config.Command | Config.Topic): string {
-//   return (c as any).id || (c as any).name
-// }

package/lib/util.d.ts

@@ -1,3 +1,5 @@
+import { IConfig } from '@oclif/config';
+import { HelpBase, HelpOptions } from '.';
 export declare function uniqBy<T>(arr: T[], fn: (cur: T) => any): T[];
 export declare function compact<T>(a: (T | undefined)[]): T[];
 export declare function castArray<T>(input?: T | T[]): T[];
@@ -6,3 +8,8 @@ export declare namespace sort {
     type Types = string | number | undefined | boolean;
 }
 export declare function template(context: any): (t: string) => string;
+interface HelpBaseDerived {
+    new (config: IConfig, opts?: Partial<HelpOptions>): HelpBase;
+}
+export declare function getHelpClass(config: IConfig, defaultClass?: string): HelpBaseDerived;
+export {};

package/lib/util.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const ts_node_1 = require("@oclif/config/lib/ts-node");
 const lodashTemplate = require("lodash.template");
 function uniqBy(arr, fn) {
     return arr.filter((a, i) => {
@@ -46,3 +47,32 @@ function template(context) {
     return render;
 }
 exports.template = template;
+function extractExport(config, classPath) {
+    const helpClassPath = ts_node_1.tsPath(config.root, classPath);
+    return require(helpClassPath);
+}
+function extractClass(exported) {
+    return exported && exported.default ? exported.default : exported;
+}
+function getHelpClass(config, defaultClass = '@oclif/plugin-help') {
+    const pjson = config.pjson;
+    const configuredClass = pjson && pjson.oclif && pjson.oclif.helpClass;
+    if (configuredClass) {
+        try {
+            const exported = extractExport(config, configuredClass);
+            return extractClass(exported);
+        }
+        catch (error) {
+            throw new Error(`Unable to load configured help class "${configuredClass}", failed with message:\n${error.message}`);
+        }
+    }
+    try {
+        const defaultModulePath = require.resolve(defaultClass, { paths: [config.root] });
+        const exported = require(defaultModulePath);
+        return extractClass(exported);
+    }
+    catch (error) {
+        throw new Error(`Could not load a help class, consider installing the @oclif/plugin-help package, failed with message:\n${error.message}`);
+    }
+}
+exports.getHelpClass = getHelpClass;

package/oclif.manifest.json

@@ -1 +1 @@
-{"version":"2.2.3","commands":{"help":{"id":"help","description":"display help for <%= config.bin %>","pluginName":"@oclif/plugin-help","pluginType":"core","aliases":[],"flags":{"all":{"name":"all","type":"boolean","description":"see all commands in CLI","allowNo":false}},"args":[{"name":"command","description":"command to show help for","required":false}]}}}
+{"version":"3.0.0","commands":{"help":{"id":"help","description":"display help for <%= config.bin %>","pluginName":"@oclif/plugin-help","pluginType":"core","aliases":[],"flags":{"all":{"name":"all","type":"boolean","description":"see all commands in CLI","allowNo":false}},"args":[{"name":"command","description":"command to show help for","required":false}]}}}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@oclif/plugin-help",
   "description": "standard help for oclif",
-  "version": "2.2.3",
+  "version": "3.0.0",
   "author": "Jeff Dickey @jdxcode",
   "bugs": "https://github.com/oclif/plugin-help/issues",
   "dependencies": {
-    "@oclif/command": "^1.5.13",
+    "@oclif/command": "^1.5.20",
+    "@oclif/config": "^1.15.1",
     "chalk": "^2.4.1",
     "indent-string": "^4.0.0",
     "lodash.template": "^4.4.0",
@@ -15,7 +16,6 @@
     "wrap-ansi": "^4.0.0"
   },
   "devDependencies": {
-    "@oclif/config": "^1.13.0",
     "@oclif/dev-cli": "^1.21.0",
     "@oclif/errors": "^1.2.2",
     "@oclif/plugin-legacy": "^1.1.3",
@@ -33,8 +33,9 @@
     "eslint-config-oclif-typescript": "^0.1.0",
     "globby": "^9.0.0",
     "mocha": "^5.2.0",
-    "ts-node": "^8.0.2",
-    "typescript": "^3.7.2"
+    "sinon": "^9.0.1",
+    "ts-node": "^8.8.2",
+    "typescript": "^3.8.3"
   },
   "engines": {
     "node": ">=8.0.0"