mdat-plugin-cli-help 2.0.2 → 2.1.0

package/dist/index.js

@@ -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
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat-plugin-cli-help",
-  "version": "2.0.2",
+  "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"

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