✨feat: custom help rendering (#32)

Author: so1ve

packages/plugin-help/package.json

@@ -58,7 +58,6 @@
     "@clerc/core": "workspace:*",
     "@clerc/utils": "workspace:*",
     "@types/text-table": "^0.2.2",
-    "get-func-name": "^2.0.0",
     "picocolors": "^1.0.0",
     "text-table": "^0.2.0"
   }

packages/plugin-help/src/index.ts

@@ -1,17 +1,22 @@
 
 // TODO: unit tests
-
 import type { Clerc, Command, HandlerContext, RootType, TranslateFn } from "@clerc/core";
 import { NoSuchCommandError, Root, definePlugin, formatCommandName, resolveCommandStrict, withBrackets } from "@clerc/core";
 
 import { gracefulFlagName, toArray } from "@clerc/utils";
 import pc from "picocolors";
 
-import type { Render, Section } from "./renderer";
-import { renderCliffy } from "./renderer";
-import { splitTable, stringifyType } from "./utils";
+import type { Render, Renderers, Section } from "./renderer";
+import { defaultRenderers, render } from "./renderer";
+import { splitTable } from "./utils";
 import { locales } from "./locales";
 
+declare module "@clerc/core" {
+  export interface CommandCustomProperties {
+    help?: Renderers
+  }
+}
+
 const DELIMITER = pc.yellow("-");
 
 const print = (s: string) => { process.stdout.write(s); };
@@ -48,7 +53,7 @@ const generateExamples = (sections: Section[], examples: [string, string][], t:
   const examplesFormatted = examples.map(([command, description]) => [command, DELIMITER, description]);
   sections.push({
     title: t("help.examples")!,
-    body: splitTable(...examplesFormatted),
+    body: splitTable(examplesFormatted),
   });
 };
 
@@ -76,7 +81,7 @@ const generateHelp = (render: Render, ctx: HandlerContext, notes: string[] | und
   });
   sections.push({
     title: t("help.commands")!,
-    body: splitTable(...commands),
+    body: splitTable(commands),
   });
   if (notes) {
     sections.push({
@@ -97,7 +102,8 @@ const generateSubcommandHelp = (render: Render, ctx: HandlerContext, command: st
   if (!subcommand) {
     throw new NoSuchCommandError(formatCommandName(command), t);
   }
-  const sections = [] as Section[];
+  const renderers = Object.assign({}, defaultRenderers, subcommand.help);
+  let sections = [] as Section[];
   if (command === Root) {
     generateCliDetail(sections, cli);
   } else {
@@ -118,16 +124,17 @@ const generateSubcommandHelp = (render: Render, ctx: HandlerContext, command: st
     sections.push({
       title: t("help.flags")!,
       body: splitTable(
-        ...Object.entries(subcommand.flags).map(([name, flag]) => {
-          const flagNameWithAlias = [gracefulFlagName(name)];
+        Object.entries(subcommand.flags).map(([name, flag]) => {
+          const hasDefault = flag.default !== undefined;
+          let flagNameWithAlias: string[] = [gracefulFlagName(name)];
           if (flag.alias) {
             flagNameWithAlias.push(gracefulFlagName(flag.alias));
           }
-          const items = [pc.blue(flagNameWithAlias.join(", "))];
+          flagNameWithAlias = flagNameWithAlias.map(renderers.renderFlagName);
+          const items = [pc.blue(flagNameWithAlias.join(", ")), renderers.renderType(flag.type, hasDefault)];
           items.push(DELIMITER, flag.description || t("help.noDescription")!);
-          if (flag.type) {
-            const type = stringifyType(flag.type);
-            items.push(pc.gray(`(${type})`));
+          if (hasDefault) {
+            items.push(`(${t("help.default", renderers.renderDefault(flag.default))})`);
           }
           return items;
         }),
@@ -143,6 +150,7 @@ const generateSubcommandHelp = (render: Render, ctx: HandlerContext, command: st
   if (subcommand.examples) {
     generateExamples(sections, subcommand.examples, t);
   }
+  sections = renderers.renderSections(sections);
   return render(sections);
 };
 
@@ -169,23 +177,17 @@ export interface HelpPluginOptions {
    * Banner
    */
   banner?: string
-  /**
-   * Render type
-   */
-  renderer?: "cliffy"
 }
 export const helpPlugin = ({
   command = true,
   showHelpWhenNoCommand = true,
   notes,
   examples,
   banner,
-  renderer = "cliffy",
 }: HelpPluginOptions = {}) => definePlugin({
   setup: (cli) => {
     const { add, t } = cli.i18n;
     add(locales);
-    const render: Render = renderer === "cliffy" ? renderCliffy : () => "";
     const printHelp = (s: string) => {
       banner && print(`${banner}\n`);
       print(s);

packages/plugin-help/src/locales.ts

@@ -18,6 +18,7 @@ export const locales: Locales = {
     "help.examples.1": "Show help",
     "help.examples.2": "Show help for a specific command",
     "help.commandDescription": "Show help",
+    "help.default": "Default: ",
   },
   "zh-CN": {
     "help.name": "名称",
@@ -36,5 +37,6 @@ export const locales: Locales = {
     "help.examples.1": "展示 CLI 的帮助信息",
     "help.examples.2": "展示指定命令的帮助信息",
     "help.commandDescription": "展示帮助信息",
+    "help.default": "默认值: %s",
   },
 };

packages/plugin-help/src/renderer.ts

@@ -1,6 +1,6 @@
 import pc from "picocolors";
 
-import { table } from "./utils";
+import { stringifyType, table } from "./utils";
 
 export interface BlockSection {
   type?: "block"
@@ -18,8 +18,14 @@ export interface InlineSection {
 
 export type Section = BlockSection | InlineSection;
 export type Render = (sections: Section[]) => string;
+export interface Renderers {
+  renderSections?: (sections: Section[]) => Section[]
+  renderFlagName?: (name: string) => string
+  renderType?: (type: any, hasDefault: boolean) => string
+  renderDefault?: (default_: any) => string
+}
 
-export const renderCliffy: Render = (sections: Section[]) => {
+export const render: Render = (sections: Section[]) => {
   const rendered = [] as string[];
   for (const section of sections) {
     if (section.type === "block" || !section.type) {
@@ -28,34 +34,21 @@ export const renderCliffy: Render = (sections: Section[]) => {
         .map(line => indent + line);
       formattedBody.unshift("");
       const body = formattedBody.join("\n");
-      rendered.push(table([pc.bold(`${section.title}:`)], [body]).toString());
+      rendered.push(table([[pc.bold(`${section.title}:`)], [body]]).toString());
     } else if (section.type === "inline") {
       const formattedBody = section.items
         .map(item => [pc.bold(`${item.title}:`), item.body]);
-      const tableGenerated = table(...formattedBody);
+      const tableGenerated = table(formattedBody);
       rendered.push(tableGenerated.toString());
     }
     rendered.push("");
   }
   return rendered.join("\n");
 };
 
-// export const renderTyper: Render = (sections: Section[]) => {
-//   const rendered = [] as string[];
-//   for (const section of sections) {
-//     if (section.type === "block" || !section.type) {
-//       rendered.push(boxen(section.body.join("\n\n"), {
-//         title: section.title,
-//         borderStyle: "round",
-//         padding: 0.5,
-//       }));
-//     } else if (section.type === "inline") {
-//       const formattedBody = section.items
-//         .map(item => [pc.bold(`${item.title}:`), item.body]);
-//       const tableGenerated = table(...formattedBody);
-//       rendered.push(tableGenerated.toString());
-//     }
-//     rendered.push("");
-//   }
-//   return rendered.join("\n");
-// };
+export const defaultRenderers: Required<Renderers> = {
+  renderFlagName: n => n,
+  renderSections: s => s,
+  renderType: (type, hasDefault) => stringifyType(type, hasDefault),
+  renderDefault: default_ => JSON.stringify(default_),
+};

packages/plugin-help/src/shims.d.ts

@@ -0,0 +1,7 @@
+import type { Section } from "./renderer";
+
+export interface Renderers {
+  renderSections?: (sections: Section[]) => Section[]
+  renderFlagName?: (name: string) => string
+  renderDefault?: (type: any) => string
+}

packages/plugin-help/src/types.ts

@@ -1,14 +1,19 @@
-import getFuncName from "get-func-name";
 import textTable from "text-table";
 
-export const table = (...items: string[][]) => textTable(items);
+export const table = (items: string[][]) => textTable(items);
 
-export const splitTable = (...items: string[][]) => {
-  return table(...items).toString().split("\n");
+export const splitTable = (items: string[][]) => {
+  return table(items).toString().split("\n");
 };
 
-export const stringifyType = (type: any) => {
-  return Array.isArray(type)
-    ? `Array<${getFuncName(type[0])}>`
-    : getFuncName(type);
+const primitiveMap = new Map<any, string>([
+  [Boolean, ""],
+  [String, "string"],
+  [Number, "number"],
+]);
+export const stringifyType = (type: any, hasDefault = false) => {
+  const res = primitiveMap.has(type)
+    ? primitiveMap.get(type)
+    : "value";
+  return hasDefault ? `[${res}]` : `<${res}>`;
 };