mdat-plugin-cli-help 2.1.2 → 3.0.1

package/dist/index.d.ts

@@ -1,15 +1,16 @@
-import * as _$mdat from "mdat";
 import { ILogBasic, ILogLayer } from "lognow";
 
 //#region src/utilities/log.d.ts
 /**
- * Set the logger instance for the module.
- * Export this for library consumers to inject their own logger.
- * @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
+ * Set the logger instance for the module. Export this for library consumers to
+ * inject their own logger.
+ *
+ * @param logger - Accepts either a LogLayer instance or a Console- or
+ *   Stream-like log target
  */
-declare function setLogger(logger?: ILogBasic | ILogLayer): void;
+declare function setLogger(logger?: ILogBasic | ILogLayer<unknown>): void;
 //#endregion
 //#region src/index.d.ts
-declare const _default: _$mdat.Config;
+declare const _default: import("mdat").Config;
 //#endregion
 export { _default as default, setLogger };

package/dist/index.js

@@ -126,9 +126,11 @@ let log = createLogger({
 	name: "mdat-plugin-cli-help"
 });
 /**
-* Set the logger instance for the module.
-* Export this for library consumers to inject their own logger.
-* @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
+* Set the logger instance for the module. Export this for library consumers to
+* inject their own logger.
+*
+* @param logger - Accepts either a LogLayer instance or a Console- or
+*   Stream-like log target
 */
 function setLogger(logger) {
 	log = injectionHelper(logger);
@@ -379,28 +381,29 @@ var CliHelpToObjectVisitor$2 = class extends parser$2.getBaseCstVisitorConstruct
 		};
 	}
 	/**
-	* Clean a Commander default value: strip `(default: ...)` wrapper, env info, and quotes.
+	* Clean a Commander default value: strip `(default: ...)` wrapper, env info,
+	* and quotes.
 	*/
 	cleanDefault(text) {
-		if (text === void 0) return void 0;
+		if (text === void 0) return;
 		let cleaned = text.replaceAll(/^\(default:\s*/g, "").replaceAll(/\)$/g, "").trim();
 		cleaned = cleaned.replaceAll(/,\s*env:\s*\S+$/g, "").trim();
 		cleaned = cleaned.replaceAll(/^["']|["']$/g, "");
 		return cleaned || void 0;
 	}
 	getArray(context) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => entry.image);
 	}
 	getString(context) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => entry.image).join(" ");
 	}
 	/**
 	* Trim leading/trailing whitespace from description text.
 	*/
 	trimDescription(text) {
-		if (text === void 0) return void 0;
+		if (text === void 0) return;
 		return text.trim() || void 0;
 	}
 };
@@ -441,8 +444,8 @@ function helpStringToObject$3(helpString) {
 * (typically 30+ spaces). The lexer's ROW_MODE exits on newline, so we must
 * unwrap these before tokenizing.
 *
-* Detection: a continuation line has 4+ leading spaces and does NOT start a
-* new row (which would be exactly 2 spaces + a non-space character).
+* Detection: a continuation line has 4+ leading spaces and does NOT start a new
+* row (which would be exactly 2 spaces + a non-space character).
 */
 const continuationLinePattern = /^ {4,}/;
 const newRowPattern = /^ {2}\S/;
@@ -647,11 +650,11 @@ var CliHelpToObjectVisitor$1 = class extends parser$1.getBaseCstVisitorConstruct
 		return text.replaceAll(/^[\s[]*(default:)?\s*|[\s\]]*$/g, "");
 	}
 	getArray(context) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => entry.image);
 	}
 	getString(context, clean = false) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => clean ? this.clean(entry.image) : entry.image).join(" ");
 	}
 };
@@ -950,11 +953,11 @@ var CliHelpToObjectVisitor = class extends parser.getBaseCstVisitorConstructor()
 		return text.replaceAll(/^[\s[]*(default:)?\s*|[\s\]]*$/g, "");
 	}
 	getArray(context) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => entry.image);
 	}
 	getString(context, clean = false) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => clean ? this.clean(entry.image) : entry.image).join(" ");
 	}
 	positionalParentCommandToArguments(object) {
@@ -966,7 +969,7 @@ var CliHelpToObjectVisitor = class extends parser.getBaseCstVisitorConstructor()
 		};
 	}
 	splitChoices(text) {
-		if (text === void 0) return void 0;
+		if (text === void 0) return;
 		return this.clean(text.replaceAll(/^\[choices:\s/g, "")).split(", ");
 	}
 };
@@ -1073,12 +1076,15 @@ function helpStringToObject(helpString) {
 /**
 * Get help output from a CLI command and return it as markdown
 *
-* @param cliCommand - The executable path (may contain spaces, e.g. on Windows)
+* @param command - The executable path (may contain spaces, e.g. on Windows)
 * @param helpFlag - The flag to pass to get help output
 * @param depth - Max recursion depth for subcommands
+* @param subcommands - Initial subcommand path to invoke before the help flag
+*   (e.g. `['remote', 'add']` produces `command remote add --help`). Discovered
+*   subcommands are appended to this path during recursion.
 */
-async function getHelpMarkdown(cliCommand, helpFlag = "--help", depth) {
-	return getHelpMarkdownInternal(cliCommand, [], helpFlag, depth ?? Number.MAX_SAFE_INTEGER);
+async function getHelpMarkdown(command, helpFlag = "--help", depth, subcommands = []) {
+	return getHelpMarkdownInternal(command, subcommands, helpFlag, depth ?? Number.MAX_SAFE_INTEGER);
 }
 async function getHelpMarkdownInternal(executable, subcommands, helpFlag, depth) {
 	const rawHelpString = await getHelpString(executable, [...subcommands, helpFlag]);
@@ -1131,8 +1137,9 @@ async function getHelpString(command, args) {
 //#endregion
 //#region src/utilities/is-executable.ts
 /**
-* This file is vendored with modification from https://github.com/sindresorhus/is-executable
-* to work around a "[DEP0176] DeprecationWarning: fs.X_OK is deprecated, use fs.constants.X_OK instead"
+* This file is vendored with modification from
+* https://github.com/sindresorhus/is-executable to work around a "[DEP0176]
+* DeprecationWarning: fs.X_OK is deprecated, use fs.constants.X_OK instead"
 * error from Node.
 */
 const isWindows = process.platform === "win32";
@@ -1152,16 +1159,19 @@ async function isExecutable(filePath, strictExtensions = false) {
 //#region src/utilities/infer-command.ts
 /**
 * Accommodate missing or sloppy cli help command input
-* @param cliCommand - Can be nothing, a command name on the path like `git`, or a path to an executable like `./bin/cli.js`
+*
+* @param command - Can be nothing, a command name on the path like `git`, or a
+*   path to an executable like `./bin/cli.js`
+*
 * @returns The path to a verified executable
 * @throws {Error} If nothing can be inferred or resolved
 */
-async function inferCommand(cliCommand) {
-	cliCommand ??= await getFirstBinFromPackage();
-	return ensureExecutable(cliCommand);
+async function inferCommand(command) {
+	command ??= await getFirstBinFromPackage();
+	return ensureExecutable(command);
 }
 function firstOf(value) {
-	if (value === void 0) return void 0;
+	if (value === void 0) return;
 	return Array.isArray(value) ? value[0] : value;
 }
 async function getFirstBinFromPackage() {
@@ -1176,7 +1186,7 @@ async function getFirstBinFromPackage() {
 			return binPath;
 		}
 	}
-	throw new Error(`Could not infer which command to run for the <!-- cli-help --> rule. Please pass a "cliCommand" option to the expansion comment, e.g. <!-- cli-help({cliCommand: './dist/bin.js'}) -->`);
+	throw new Error(`Could not infer which command to run for the <!-- cli-help --> rule. Please pass a "command" option to the expansion comment, e.g. <!-- cli-help({command: './dist/bin.js'}) -->`);
 }
 function looksLikePath(maybePath) {
 	const parsed = path.parse(maybePath);
@@ -1202,13 +1212,17 @@ async function getCommandPathFromPackage(commandName) {
 }
 //#endregion
 //#region src/index.ts
+const WHITESPACE_REGEX = /\s+/;
 const cliHelpRule = defineConfig({ cli: { async content(options, _context) {
 	const validOptions = z.object({
-		cliCommand: z.string().optional(),
+		command: z.string().optional(),
 		depth: z.number().optional(),
-		helpFlag: z.string().optional()
-	}).optional().parse(options);
-	return getHelpMarkdown(await inferCommand(validOptions?.cliCommand), validOptions?.helpFlag, validOptions?.depth);
+		helpFlag: z.string().optional(),
+		subcommand: z.string().optional()
+	}).strict().optional().parse(options);
+	const resolvedCommand = await inferCommand(validOptions?.command);
+	const subcommands = validOptions?.subcommand?.split(WHITESPACE_REGEX).filter(Boolean) ?? [];
+	return getHelpMarkdown(resolvedCommand, validOptions?.helpFlag, validOptions?.depth, subcommands);
 } } });
 var src_default = defineConfig({
 	cli: cliHelpRule.cli,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat-plugin-cli-help",
-  "version": "2.1.2",
+  "version": "3.0.1",
   "description": "Mdat plugin to generate tabular help documentation for CLI tools in Markdown files.",
   "keywords": [
     "markdown",
@@ -38,44 +38,39 @@
     "@types/which": "^3.0.4",
     "chevrotain": "^12.0.0",
     "execa": "^9.6.1",
-    "lognow": "^0.6.1",
-    "type-fest": "^5.5.0",
-    "which": "^6.0.1",
-    "zod": "^4.3.6"
+    "lognow": "^0.6.2",
+    "type-fest": "^5.6.0",
+    "which": "^7.0.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@kitschpatrol/shared-config": "^7.1.0",
-    "@types/node": "~22.17.2",
+    "@kitschpatrol/shared-config": "^7.6.0",
+    "@types/node": "~22.19.19",
     "@types/yargs": "^17.0.35",
-    "bumpp": "^11.0.1",
+    "bumpp": "^11.1.0",
     "commander": "^14.0.3",
-    "mdat": "^2.2.1",
+    "mdat": "^2.3.4",
     "meow": "^14.1.0",
-    "tsdown": "^0.21.7",
+    "shx": "^0.4.0",
+    "tsdown": "^0.22.0",
     "typescript": "~5.9.3",
-    "vitest": "^4.1.3",
+    "vitest": "^4.1.6",
     "yargs": "^18.0.0"
   },
   "peerDependencies": {
     "mdat": "^2.0.0"
   },
   "engines": {
-    "node": ">=22.17.0"
-  },
-  "devEngines": {
-    "runtime": {
-      "name": "node",
-      "version": ">=22.21.0"
-    }
+    "node": ">=22.22.2"
   },
   "scripts": {
     "bench": "vitest bench --run --no-file-parallelism --compare test/benchmarks/baseline.json",
     "bench:baseline": "vitest bench --run --no-file-parallelism --outputJson test/benchmarks/baseline.json",
     "build": "tsdown --no-fixed-extension --tsconfig tsconfig.build.json",
-    "clean": "git rm -f pnpm-lock.yaml ; git clean -fdX",
+    "clean": "shx rm -f pnpm-lock.yaml && git clean -fdX -e !.claude/",
     "fix": "ksc fix",
     "lint": "ksc lint",
-    "release": "bumpp --commit 'Release: %s' && pnpm run build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish",
+    "release": "bumpp --commit 'Release: %s' && pnpm build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') pnpm publish",
     "test": "vitest run --no-file-parallelism"
   }
 }

package/readme.md

@@ -7,7 +7,7 @@
 <!-- badges -->
 
 [![NPM Package mdat-plugin-cli-help](https://img.shields.io/npm/v/mdat-plugin-cli-help.svg)](https://npmjs.com/package/mdat-plugin-cli-help)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit/)
 [![CI](https://github.com/kitschpatrol/mdat-plugin-cli-help/actions/workflows/ci.yml/badge.svg)](https://github.com/kitschpatrol/mdat-plugin-cli-help/actions/workflows/ci.yml)
 
 <!-- /badges -->
@@ -58,13 +58,13 @@ export default defineConfig({
 Assuming you have an executable with a `--help` flag on your path or in your project's scope:
 
 ```markdown
-<!-- cli-help({ cliCommand: "mdat", depth: 1 }) -->
+<!-- cli-help({ command: "mdat", depth: 1 }) -->
 ```
 
 Then run the `mdat` CLI command on your Markdown file to expand the rule and embed the tabular help output:
 
 ````markdown
-<!-- cli-help({ cliCommand: "mdat", depth: 1 }) -->
+<!-- cli-help({ command: "mdat", depth: 1 }) -->
 
 #### Command: `mdat`
 
@@ -105,12 +105,20 @@ mdat [command]
 <!-- /cli-help -->
 ````
 
+To generate help for a specific subcommand, pass `subcommand`. Whitespace-separated for nested paths:
+
+```markdown
+<!-- cli-help({ command: "mdat", subcommand: "readme", depth: 1 }) -->
+```
+
+This invokes `mdat readme --help`. Discovered sub-subcommands are appended to this path during recursion.
+
 The command is also aliased under the `<!-- cli -->` keyword.
 
 This would have equivalent output to the above:
 
 ```markdown
-<!-- cli({ cliCommand: "mdat", depth: 1 }) -->
+<!-- cli({ command: "mdat", depth: 1 }) -->
 ```
 
 If you embed the rule without any arguments, it will look for the binary file listed in the closest `package.json` file and run it with `--help`. This is what you want if you're documenting a package's CLI options in its readme.md file:
@@ -157,13 +165,17 @@ Currently, the parser implementation lives in this repository because I really o
 
 ## Maintainers
 
-[@kitschpatrol](https://github.com/kitschpatrol)
+[kitschpatrol](https://github.com/kitschpatrol)
 
 <!-- contributing -->
 
 ## Contributing
 
-[Issues](https://github.com/kitschpatrol/mdat-plugin-cli-help/issues) and pull requests are welcome.
+[Issues](https://github.com/kitschpatrol/mdat-plugin-cli-help/issues) are welcome and appreciated.
+
+Please open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.
+
+This repository uses [@kitschpatrol/shared-config](https://github.com/kitschpatrol/shared-config) (via its `ksc` CLI) for linting and formatting, plus [MDAT](https://github.com/kitschpatrol/mdat) for readme placeholder expansion.
 
 <!-- /contributing -->
 
@@ -171,6 +183,6 @@ Currently, the parser implementation lives in this repository because I really o
 
 ## License
 
-[MIT](license.txt) © Eric Mika
+[MIT](license.txt) © [Eric Mika](https://ericmika.com)
 
 <!-- /license -->