mdat-plugin-cli-help 2.0.1 → 2.0.2

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";
@@ -720,26 +720,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 +759,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 +831,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.0.2",
   "description": "Mdat plugin to generate tabular help documentation for CLI tools in Markdown files.",
   "keywords": [
     "markdown",
@@ -66,8 +66,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",