mdat-plugin-cli-help 2.0.1 → 2.1.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { defineConfig, getContextMetadata } from "mdat";
 import { z } from "zod";
-import { execaCommand } from "execa";
+import { execa } from "execa";
 import { createLogger, injectionHelper } from "lognow";
 import { CstParser, Lexer, createToken } from "chevrotain";
 import path from "node:path";
@@ -134,6 +134,277 @@ function setLogger(logger) {
 	log = injectionHelper(logger);
 }
 //#endregion
+//#region src/utilities/parsers/commander.ts
+const flag$2 = createToken({
+	name: "flag",
+	pattern: /--[\w-]+/
+});
+const alias$2 = createToken({
+	name: "alias",
+	pattern: /-[A-Z]/i
+});
+const comma$2 = createToken({
+	group: Lexer.SKIPPED,
+	name: "comma",
+	pattern: /,/
+});
+const word$2 = createToken({
+	name: "word",
+	pattern: /\S+/
+});
+const argument$2 = createToken({
+	name: "argument",
+	pattern: /<\S+>|\[\S+\]/
+});
+const defaultInfoParens = createToken({
+	name: "defaultInfoParens",
+	pattern: /\(default:\s.+?\)/
+});
+const whiteSpace$2 = createToken({
+	group: Lexer.SKIPPED,
+	name: "whiteSpace",
+	pattern: /\s/
+});
+const usagePrefix = createToken({
+	group: Lexer.SKIPPED,
+	name: "usagePrefix",
+	pattern: /Usage:\s/
+});
+const startProgramDescription$1 = createToken({
+	group: Lexer.SKIPPED,
+	name: "startProgramDescription",
+	pattern: /\n\n/,
+	push_mode: "PROGRAM_DESCRIPTION_MODE"
+});
+const programDescription$2 = createToken({
+	name: "programDescription",
+	pattern: /.+/
+});
+const endProgramDescription$1 = createToken({
+	group: Lexer.SKIPPED,
+	name: "endProgramDescription",
+	pattern: /\n\n/,
+	pop_mode: true
+});
+const startOptionsSection$1 = createToken({
+	name: "startOptionsSection",
+	pattern: /Options:\n/,
+	push_mode: "SECTION_MODE"
+});
+const startCommandsSection$1 = createToken({
+	name: "startCommandsSection",
+	pattern: /Commands:\n/,
+	push_mode: "SECTION_MODE"
+});
+const startRow$2 = createToken({
+	name: "startRow",
+	pattern: / {2,}/,
+	push_mode: "ROW_MODE"
+});
+const rowDescription$2 = createToken({
+	name: "rowDescription",
+	pattern: / {2}\w.+? {2}/
+});
+const rowDescriptionTerminal$1 = createToken({
+	name: "rowDescriptionTerminal",
+	pattern: / {2}\w[^(\n]+(?=\(default:)| {2}\w.+/
+});
+const endRow$2 = createToken({
+	group: Lexer.SKIPPED,
+	name: "endRow",
+	pattern: /\n/,
+	pop_mode: true
+});
+const endSection$1 = createToken({
+	group: Lexer.SKIPPED,
+	name: "endSection",
+	pattern: /\n+/,
+	pop_mode: true
+});
+const lexer$2 = new Lexer({
+	defaultMode: "DEFAULT_MODE",
+	modes: {
+		DEFAULT_MODE: [
+			startOptionsSection$1,
+			startCommandsSection$1,
+			usagePrefix,
+			startProgramDescription$1,
+			argument$2,
+			word$2,
+			whiteSpace$2
+		],
+		PROGRAM_DESCRIPTION_MODE: [endProgramDescription$1, programDescription$2],
+		ROW_MODE: [
+			endRow$2,
+			comma$2,
+			defaultInfoParens,
+			rowDescription$2,
+			rowDescriptionTerminal$1,
+			flag$2,
+			alias$2,
+			argument$2,
+			word$2,
+			whiteSpace$2
+		],
+		SECTION_MODE: [startRow$2, endSection$1]
+	}
+});
+const allTokens$2 = [
+	flag$2,
+	alias$2,
+	comma$2,
+	word$2,
+	argument$2,
+	defaultInfoParens,
+	whiteSpace$2,
+	usagePrefix,
+	startProgramDescription$1,
+	programDescription$2,
+	endProgramDescription$1,
+	startOptionsSection$1,
+	startCommandsSection$1,
+	startRow$2,
+	rowDescription$2,
+	rowDescriptionTerminal$1,
+	endRow$2,
+	endSection$1
+];
+var CliParser$2 = class extends CstParser {
+	sectionRow = this.RULE("sectionRow", () => {
+		this.CONSUME(startRow$2);
+		this.MANY(() => {
+			this.OR([
+				{ ALT: () => this.CONSUME(argument$2) },
+				{ ALT: () => this.CONSUME(alias$2) },
+				{ ALT: () => this.CONSUME(flag$2) },
+				{ ALT: () => this.CONSUME(rowDescription$2, { LABEL: "description" }) },
+				{ ALT: () => this.CONSUME(rowDescriptionTerminal$1, { LABEL: "description" }) },
+				{ ALT: () => this.CONSUME(defaultInfoParens) },
+				{ ALT: () => this.CONSUME(word$2, { LABEL: "commandName" }) }
+			]);
+		});
+	});
+	commandsSection = this.RULE("commandsSection", () => {
+		this.CONSUME(startCommandsSection$1);
+		this.MANY1(() => {
+			this.SUBRULE1(this.sectionRow);
+		});
+	});
+	optionsSection = this.RULE("optionsSection", () => {
+		this.CONSUME(startOptionsSection$1);
+		this.MANY2(() => {
+			this.SUBRULE2(this.sectionRow);
+		});
+	});
+	programHelp = this.RULE("programHelp", () => {
+		this.AT_LEAST_ONE(() => {
+			this.CONSUME(word$2, { LABEL: "commandName" });
+		});
+		this.MANY1(() => {
+			this.CONSUME(argument$2);
+		});
+		this.OPTION(() => {
+			this.CONSUME(programDescription$2, { LABEL: "description" });
+		});
+		this.OPTION1(() => {
+			this.SUBRULE(this.optionsSection);
+		});
+		this.OPTION2(() => {
+			this.SUBRULE(this.commandsSection);
+		});
+	});
+	constructor() {
+		super(allTokens$2);
+		this.performSelfAnalysis();
+	}
+};
+const parser$2 = new CliParser$2();
+var CliHelpToObjectVisitor$2 = class extends parser$2.getBaseCstVisitorConstructor() {
+	constructor() {
+		super();
+		this.validateVisitor();
+	}
+	commandsSection(context) {
+		return context.sectionRow.map((entry) => this.visit(entry));
+	}
+	optionsSection(context) {
+		return context.sectionRow.map((entry) => this.visit(entry));
+	}
+	programHelp(context) {
+		const { command: commandName, subcommand: subcommandName } = getCommandParts(this.getString(context.commandName));
+		return {
+			arguments: this.getArray(context.argument),
+			commandName,
+			commands: context.commandsSection ? this.visit(context.commandsSection) : void 0,
+			description: this.getString(context.description),
+			options: context.optionsSection ? this.visit(context.optionsSection) : void 0,
+			subcommandName
+		};
+	}
+	sectionRow(context) {
+		return {
+			aliases: this.getArray(context.alias),
+			arguments: this.getArray(context.argument),
+			commandName: this.getString(context.commandName),
+			defaultValue: this.cleanDefault(this.getString(context.defaultInfoParens)),
+			description: this.trimDescription(this.getString(context.description)),
+			flags: this.getArray(context.flag)
+		};
+	}
+	/**
+	* Clean a Commander default value: strip `(default: ...)` wrapper, env info, and quotes.
+	*/
+	cleanDefault(text) {
+		if (text === void 0) return void 0;
+		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;
+		return context.map((entry) => entry.image);
+	}
+	getString(context) {
+		if (context === void 0) return void 0;
+		return context.map((entry) => entry.image).join(" ");
+	}
+	/**
+	* Trim leading/trailing whitespace from description text.
+	*/
+	trimDescription(text) {
+		if (text === void 0) return void 0;
+		return text.trim() || void 0;
+	}
+};
+const visitor$2 = new CliHelpToObjectVisitor$2();
+/**
+* Converts an unstructured help string emitted from a CLI tool built with the
+* `Commander` CLI library and turn it into a structured POJO describing the
+* command.
+*/
+function helpStringToObject$3(helpString) {
+	if (!helpString.trimStart().startsWith("Usage:")) throw new Error("Not a Commander-format help string (must start with \"Usage:\")");
+	const lexingResult = lexer$2.tokenize(helpString);
+	if (lexingResult.errors.length > 0) throw new Error(`Errors lexing CLI command: ${JSON.stringify(lexingResult.errors, void 0, 2)}`);
+	parser$2.input = lexingResult.tokens;
+	const cst = parser$2.programHelp();
+	if (parser$2.errors.length > 0) throw new Error(`Errors parsing CLI command help text: ${JSON.stringify(parser$2.errors, void 0, 2)}`);
+	let programInfo;
+	try {
+		programInfo = visitor$2.visit(cst);
+	} catch (error) {
+		if (error instanceof Error) throw new TypeError(`Errors visiting CLI command help text: ${String(error)}`);
+	}
+	if (programInfo === void 0) throw new Error("Could not parse help string");
+	if (programInfo.commands) {
+		programInfo.commands = programInfo.commands.filter((cmd) => cmd.commandName !== void 0 || cmd.description !== void 0);
+		for (const cmd of programInfo.commands) if (cmd.commandName && !cmd.parentCommandName) cmd.parentCommandName = programInfo.commandName;
+		if (programInfo.commands.length === 0) programInfo.commands = void 0;
+	}
+	return programInfo;
+}
+//#endregion
 //#region src/utilities/parsers/meow.ts
 const flag$1 = createToken({
 	name: "flag",
@@ -674,6 +945,7 @@ function helpStringToObject$1(helpString) {
 //#endregion
 //#region src/utilities/parsers/index.ts
 var parsers_default = {
+	commander: helpStringToObject$3,
 	yargs: helpStringToObject$1,
 	meow: helpStringToObject$2
 };
@@ -720,26 +992,32 @@ function helpStringToObject(helpString) {
 //#region src/utilities/get-help-markdown.ts
 /**
 * 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 helpFlag - The flag to pass to get help output
+* @param depth - Max recursion depth for subcommands
 */
 async function getHelpMarkdown(cliCommand, helpFlag = "--help", depth) {
-	const rawHelpString = await getHelpString(`${cliCommand} ${helpFlag}`);
+	return getHelpMarkdownInternal(cliCommand, [], helpFlag, depth ?? Number.MAX_SAFE_INTEGER);
+}
+async function getHelpMarkdownInternal(executable, subcommands, helpFlag, depth) {
+	const rawHelpString = await getHelpString(executable, [...subcommands, helpFlag]);
 	const programInfo = helpStringToObject(rawHelpString);
 	if (programInfo === void 0) {
 		log.warn(`Falling back to basic cli help text output.`);
 		return renderHelpMarkdownBasic(rawHelpString);
 	}
-	return renderHelpMarkdownObject(cliCommand, helpFlag, depth ?? Number.MAX_SAFE_INTEGER, programInfo);
+	return renderHelpMarkdownObject(executable, subcommands, helpFlag, depth, programInfo);
 }
-async function renderHelpMarkdownObject(cliCommand, helpFlag, depth, programInfo) {
+async function renderHelpMarkdownObject(executable, subcommands, helpFlag, depth, programInfo) {
 	if (depth <= 0) {
 		log.warn(`Max CLI command help depth reached, stopping recursion`);
 		return "";
 	}
 	let markdown = helpObjectToMarkdown(programInfo, depth);
-	const baseCommand = cliCommand.split(" ")[0];
 	if (programInfo.commands) for (const command of programInfo.commands) {
 		if (!command.parentCommandName || !command.commandName) continue;
-		const subCommandHelp = await getHelpMarkdown(`${baseCommand} ${command.commandName}`, helpFlag, depth - 1);
+		const subCommandHelp = await getHelpMarkdownInternal(executable, [...subcommands, command.commandName], helpFlag, depth - 1);
 		if (subCommandHelp === "") return markdown;
 		markdown += `\n\n${subCommandHelp}`;
 	}
@@ -753,19 +1031,21 @@ function renderHelpMarkdownBasic(rawHelpString) {
 }
 /**
 * Run the CLI help command and return the output, throw if there's no output
+*
+* @returns The full help string from the resolved command
 * @throws {TypeError} If there's an error running the CLI help command
-* @returns the full help string from the resolved command
 */
-async function getHelpString(resolvedCommand) {
+async function getHelpString(command, args) {
+	const displayCommand = `${command} ${args.join(" ")}`;
 	let rawHelpString;
 	try {
-		const { stderr, stdout } = await execaCommand(resolvedCommand);
+		const { stderr, stdout } = await execa(command, args, { preferLocal: true });
 		rawHelpString = stdout;
 		if (rawHelpString === void 0 || rawHelpString === "") rawHelpString = stderr;
 	} catch (error) {
-		if (error instanceof Error) throw new TypeError(`Error running CLI help command: "${resolvedCommand}"\n${error.message}\n`);
+		if (error instanceof Error) throw new TypeError(`Error running CLI help command: "${displayCommand}"\n${error.message}\n`);
 	}
-	if (rawHelpString === void 0 || rawHelpString === "") throw new Error(`No result from running CLI help command: "${resolvedCommand}"\n`);
+	if (rawHelpString === void 0 || rawHelpString === "") throw new Error(`No result from running CLI help command: "${displayCommand}"\n`);
 	return rawHelpString;
 }
 //#endregion
@@ -823,10 +1103,14 @@ function looksLikePath(maybePath) {
 	return parsed.root !== "" || parsed.dir !== "";
 }
 async function ensureExecutable(filePath) {
-	let resolvedPath = path.isAbsolute(filePath) ? filePath : await which(filePath, { nothrow: true }) ?? void 0;
-	resolvedPath ??= await getCommandPathFromPackage(filePath) ?? void 0;
-	if (resolvedPath !== void 0 && await isExecutable(resolvedPath)) return resolvedPath;
-	throw new Error(`The cli-help rule noticed that "${resolvedPath}" is not executable.`);
+	if (path.isAbsolute(filePath)) {
+		if (await isExecutable(filePath)) return filePath;
+		throw new Error(`The cli-help rule noticed that "${filePath}" is not executable.`);
+	}
+	if (await which(filePath, { nothrow: true }) !== null) return filePath;
+	const packagePath = await getCommandPathFromPackage(filePath);
+	if (packagePath !== void 0 && await isExecutable(packagePath)) return packagePath;
+	throw new Error(`The cli-help rule noticed that "${filePath}" is not executable.`);
 }
 async function getCommandPathFromPackage(commandName) {
 	const { nodePackageJson } = await getContextMetadata();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat-plugin-cli-help",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Mdat plugin to generate tabular help documentation for CLI tools in Markdown files.",
   "keywords": [
     "markdown",
@@ -38,20 +38,23 @@
     "@types/which": "^3.0.4",
     "chevrotain": "^12.0.0",
     "execa": "^9.6.1",
-    "lognow": "^0.6.0",
+    "lognow": "^0.6.1",
     "type-fest": "^5.5.0",
     "which": "^6.0.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@kitschpatrol/shared-config": "^7.0.0",
+    "@kitschpatrol/shared-config": "^7.1.0",
     "@types/node": "~22.17.2",
+    "@types/yargs": "^17.0.35",
     "bumpp": "^11.0.1",
-    "mdat": "^2.0.0",
+    "commander": "^14.0.3",
+    "mdat": "^2.2.0",
     "meow": "^14.1.0",
     "tsdown": "^0.21.7",
     "typescript": "~5.9.3",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.2",
+    "yargs": "^18.0.0"
   },
   "peerDependencies": {
     "mdat": "^2.0.0"
@@ -66,8 +69,8 @@
     }
   },
   "scripts": {
-    "bench": "vitest bench --no-file-parallelism --compare test/benchmarks/baseline.json",
-    "bench:baseline": "vitest bench --no-file-parallelism --outputJson test/benchmarks/baseline.json",
+    "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",
     "fix": "ksc fix",

package/readme.md

@@ -26,7 +26,7 @@ This plugin automatically transforms a CLI command's `--help` output into nicely
 
 The rule also recursively calls `--help` on any subcommands found for inclusion in the output.
 
-Currently, the rule can only parse help output in the format provided by [Yargs](https://yargs.js.org)- and [Meow](https://github.com/sindresorhus/meow)-based tools. If parsing fails, the rule will fall back to show the raw help output in a regular code block instead.
+Currently, the rule can parse help output in the format provided by [Commander](https://github.com/tj/commander.js)-, [Yargs](https://yargs.js.org)-, and [Meow](https://github.com/sindresorhus/meow)-based tools. If parsing fails, the rule will fall back to show the raw help output in a regular code block instead.
 
 ## Getting started