mdat-plugin-cli-help 2.1.0 → 2.1.2

package/dist/index.js

@@ -186,6 +186,11 @@ const endProgramDescription$1 = createToken({
 	pattern: /\n\n/,
 	pop_mode: true
 });
+const startArgumentsSection = createToken({
+	name: "startArgumentsSection",
+	pattern: /Arguments:\n/,
+	push_mode: "SECTION_MODE"
+});
 const startOptionsSection$1 = createToken({
 	name: "startOptionsSection",
 	pattern: /Options:\n/,
@@ -225,6 +230,7 @@ const lexer$2 = new Lexer({
 	defaultMode: "DEFAULT_MODE",
 	modes: {
 		DEFAULT_MODE: [
+			startArgumentsSection,
 			startOptionsSection$1,
 			startCommandsSection$1,
 			usagePrefix,
@@ -261,6 +267,7 @@ const allTokens$2 = [
 	startProgramDescription$1,
 	programDescription$2,
 	endProgramDescription$1,
+	startArgumentsSection,
 	startOptionsSection$1,
 	startCommandsSection$1,
 	startRow$2,
@@ -284,6 +291,12 @@ var CliParser$2 = class extends CstParser {
 			]);
 		});
 	});
+	argumentsSection = this.RULE("argumentsSection", () => {
+		this.CONSUME(startArgumentsSection);
+		this.MANY3(() => {
+			this.SUBRULE3(this.sectionRow);
+		});
+	});
 	commandsSection = this.RULE("commandsSection", () => {
 		this.CONSUME(startCommandsSection$1);
 		this.MANY1(() => {
@@ -307,9 +320,12 @@ var CliParser$2 = class extends CstParser {
 			this.CONSUME(programDescription$2, { LABEL: "description" });
 		});
 		this.OPTION1(() => {
-			this.SUBRULE(this.optionsSection);
+			this.SUBRULE(this.argumentsSection);
 		});
 		this.OPTION2(() => {
+			this.SUBRULE(this.optionsSection);
+		});
+		this.OPTION3(() => {
 			this.SUBRULE(this.commandsSection);
 		});
 	});
@@ -324,6 +340,16 @@ var CliHelpToObjectVisitor$2 = class extends parser$2.getBaseCstVisitorConstruct
 		super();
 		this.validateVisitor();
 	}
+	argumentsSection(context) {
+		return context.sectionRow.map((entry) => {
+			const row = this.visit(entry);
+			return {
+				arguments: row.commandName ? [row.commandName] : void 0,
+				defaultValue: row.defaultValue,
+				description: row.description
+			};
+		});
+	}
 	commandsSection(context) {
 		return context.sectionRow.map((entry) => this.visit(entry));
 	}
@@ -338,6 +364,7 @@ var CliHelpToObjectVisitor$2 = class extends parser$2.getBaseCstVisitorConstruct
 			commands: context.commandsSection ? this.visit(context.commandsSection) : void 0,
 			description: this.getString(context.description),
 			options: context.optionsSection ? this.visit(context.optionsSection) : void 0,
+			positionals: context.argumentsSection ? this.visit(context.argumentsSection) : void 0,
 			subcommandName
 		};
 	}
@@ -385,7 +412,8 @@ const visitor$2 = new CliHelpToObjectVisitor$2();
 */
 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);
+	const unwrapped = unwrapContinuationLines$1(helpString);
+	const lexingResult = lexer$2.tokenize(unwrapped);
 	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();
@@ -399,11 +427,32 @@ function helpStringToObject$3(helpString) {
 	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);
+		programInfo.commands = programInfo.commands.filter((cmd) => cmd.commandName !== "help");
 		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;
 }
+/**
+* Join continuation lines in Commander help output before lexing.
+*
+* Commander wraps long descriptions and default values across multiple lines,
+* indenting continuation lines to align with the description start column
+* (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).
+*/
+const continuationLinePattern = /^ {4,}/;
+const newRowPattern = /^ {2}\S/;
+function unwrapContinuationLines$1(helpString) {
+	const lines = helpString.split("\n");
+	const result = [];
+	for (const line of lines) if (result.length > 0 && line.length > 0 && continuationLinePattern.test(line) && !newRowPattern.test(line)) result[result.length - 1] += " " + line.trim();
+	else result.push(line);
+	return result.join("\n");
+}
 //#endregion
 //#region src/utilities/parsers/meow.ts
 const flag$1 = createToken({
@@ -928,7 +977,8 @@ const visitor = new CliHelpToObjectVisitor();
 * command.
 */
 function helpStringToObject$1(helpString) {
-	const lexingResult = lexer.tokenize(helpString);
+	const unwrapped = unwrapContinuationLines(helpString);
+	const lexingResult = lexer.tokenize(unwrapped);
 	if (lexingResult.errors.length > 0) throw new Error(`Errors lexing CLI command: ${JSON.stringify(lexingResult.errors, void 0, 2)}`);
 	parser.input = lexingResult.tokens;
 	const cst = parser.programHelp();
@@ -942,6 +992,36 @@ function helpStringToObject$1(helpString) {
 	if (programInfo === void 0) throw new Error("Could not parse help string");
 	return programInfo;
 }
+/**
+* Join continuation lines in Yargs help output before lexing.
+*
+* When terminal width is narrow, Yargs wraps long descriptions across multiple
+* lines, indenting continuations to align with the description start column.
+* The lexer's ROW_MODE exits on newline, so we must unwrap these first.
+*
+* Detection: a continuation line has 4+ leading spaces and its first non-space
+* character is NOT `-` (which would indicate a new option/alias row). Yargs
+* uses variable indentation for option rows (2 spaces for aliased options like
+* `-r, --rules`, 6 spaces for long-only options like `--config`), so we cannot
+* rely on indent depth alone to distinguish new rows from continuations.
+*/
+const deepIndentPattern = /^ {4,}/;
+const newOptionRowPattern = /^ *-/;
+const sectionHeaderPattern = /^(?:Options|Commands|Positionals):?\s*$/;
+function unwrapContinuationLines(helpString) {
+	const lines = helpString.split("\n");
+	const result = [];
+	let inSection = false;
+	for (const line of lines) if (sectionHeaderPattern.test(line)) {
+		inSection = true;
+		result.push(line);
+	} else if (line.trim() === "") {
+		inSection = false;
+		result.push(line);
+	} else if (inSection && result.length > 0 && line.length > 0 && deepIndentPattern.test(line) && !newOptionRowPattern.test(line)) result[result.length - 1] += " " + line.trim();
+	else result.push(line);
+	return result.join("\n");
+}
 //#endregion
 //#region src/utilities/parsers/index.ts
 var parsers_default = {
@@ -986,7 +1066,7 @@ function helpStringToObject(helpString) {
 			continue;
 		}
 	}
-	log.warn("Could not parse help string with any parser");
+	log.debug("Could not parse help string with any parser");
 }
 //#endregion
 //#region src/utilities/get-help-markdown.ts
@@ -1004,7 +1084,7 @@ 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.`);
+		log.debug(`Falling back to basic cli help text output.`);
 		return renderHelpMarkdownBasic(rawHelpString);
 	}
 	return renderHelpMarkdownObject(executable, subcommands, helpFlag, depth, programInfo);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat-plugin-cli-help",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Mdat plugin to generate tabular help documentation for CLI tools in Markdown files.",
   "keywords": [
     "markdown",
@@ -49,11 +49,11 @@
     "@types/yargs": "^17.0.35",
     "bumpp": "^11.0.1",
     "commander": "^14.0.3",
-    "mdat": "^2.2.0",
+    "mdat": "^2.2.1",
     "meow": "^14.1.0",
     "tsdown": "^0.21.7",
     "typescript": "~5.9.3",
-    "vitest": "^4.1.2",
+    "vitest": "^4.1.3",
     "yargs": "^18.0.0"
   },
   "peerDependencies": {

package/readme.md

@@ -119,9 +119,39 @@ If you embed the rule without any arguments, it will look for the binary file li
 <!-- cli-help -->
 ```
 
+### Supported CLI frameworks
+
+#### [Yargs](https://yargs.js.org)
+
+Fully supported, including options, commands, positionals, choices, defaults, and type annotations.
+
+The parser handles line-wrapped output by unwrapping continuation lines before parsing. However, when Yargs wraps command _arguments_ onto new lines at very narrow terminal widths (e.g. below \~70 columns), those wrapped argument lines are indistinguishable from new command rows and cannot be reliably unwrapped. In practice, this is rare.
+
+For the most reliable parsing if you control the upstream project, configure your Yargs CLI to disable wrapping:
+
+```ts
+yargs(process.argv).wrap(process.stdout.isTTY ? Math.min(120, yargs.terminalWidth()) : 0)
+```
+
+This outputs unwrapped help text when piped, while preserving normal wrapping for interactive use.
+
+#### [Commander](https://github.com/tj/commander.js)
+
+Fully supported, including options, commands, arguments (positionals), and parenthesized defaults with optional environment variable annotations (e.g. `(default: "value", env: MY_VAR)`).
+
+The parser handles line-wrapped output by unwrapping continuation lines before parsing. Commander's built-in `help` command is automatically filtered from subcommand recursion to avoid duplicate output.
+
+#### [Meow](https://github.com/sindresorhus/meow)
+
+Should be fully supported or nearly so.
+
 ## Development notes
 
-Parsing arbitrary `--help` output is a bit tricky. The [jc](https://github.com/kellyjonbrazil/jc) project is a heroic collection of output parsers, but does not currently implement help output parsing. It might be interesting to try to contribute mdat's help parsing implementations to jc.
+Parsing arbitrary `--help` output is a bit tricky.
+
+You're right to think that an LLM could make quick work of this kind of "fuzzy text to structured data" transcription. However, when this tool was originally developed in 2024, testing a language model approach yielded sub-par results, so I pursued a traditional lexer/parser approach instead. There is also the logistical overhead of providing a smart-enough model both locally and in CI, where this tool frequently runs; it's technically feasible, but unpleasant. While the current hand-tuned parsers are admittedly a brittle tangle, future versions may revisit the LLM approach.
+
+In terms of prior art, the [jc](https://github.com/kellyjonbrazil/jc) project stands out as a heroic collection of CLI-tool output parsers, but does not currently implement help output parsing. It might be interesting to try to contribute mdat's help parsing implementations to jc.
 
 Currently, the parser implementation lives in this repository because I really only use it in the context of my CLI tool readme files. In theory, it really belongs in a separate package.