mdat-plugin-cli-help 1.0.7 → 2.0.0

package/dist/index.d.ts

@@ -1,13 +1,15 @@
-import * as type_fest0 from "type-fest";
+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
+ */
+declare function setLogger(logger?: ILogBasic | ILogLayer): void;
+//#endregion
 //#region src/index.d.ts
-declare const _default: {
-  cli: {
-    content(options?: type_fest0.JsonValue | undefined): Promise<string>;
-  };
-  'cli-help': {
-    content(options?: type_fest0.JsonValue | undefined): Promise<string>;
-  };
-};
+declare const _default: _$mdat.Config;
 //#endregion
-export { _default as default };
+export { _default as default, setLogger };

package/dist/index.js

@@ -1,14 +1,12 @@
+import { defineConfig, getContextMetadata } from "mdat";
 import { z } from "zod";
 import { execaCommand } from "execa";
-import { log } from "remark-mdat";
+import { createLogger, injectionHelper } from "lognow";
 import { CstParser, Lexer, createToken } from "chevrotain";
 import path from "node:path";
 import which from "which";
-import { loadConfig } from "mdat";
-import { readPackage } from "read-pkg";
 import fs from "node:fs/promises";
 import process from "node:process";
-
 //#region src/utilities/help-object-to-markdown.ts
 /**
 * Converts a ProgramInfo object extracted by one of the help parsers into a big
@@ -118,7 +116,23 @@ function findEmptyColumns(rows) {
 	}
 	return emptyColumnsIndexes;
 }
-
+//#endregion
+//#region src/utilities/log.ts
+/**
+* The default logger instance for the library.
+*/
+let log = createLogger({
+	logToConsole: { showTime: false },
+	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
+*/
+function setLogger(logger) {
+	log = injectionHelper(logger);
+}
 //#endregion
 //#region src/utilities/parsers/meow.ts
 const flag$1 = createToken({
@@ -342,7 +356,6 @@ function helpStringToObject$2(helpString) {
 	if (programInfo === void 0) throw new Error("Could not parse help string");
 	return programInfo;
 }
-
 //#endregion
 //#region src/utilities/parsers/yargs.ts
 const flag = createToken({
@@ -658,7 +671,6 @@ function helpStringToObject$1(helpString) {
 	if (programInfo === void 0) throw new Error("Could not parse help string");
 	return programInfo;
 }
-
 //#endregion
 //#region src/utilities/parsers/index.ts
 var parsers_default = {
@@ -682,7 +694,6 @@ function getCommandParts(wholeCommand) {
 		subcommand
 	};
 }
-
 //#endregion
 //#region src/utilities/help-string-to-object.ts
 /**
@@ -695,17 +706,16 @@ function getCommandParts(wholeCommand) {
 */
 function helpStringToObject(helpString) {
 	for (const [parserName, helpStringToObjectFunction] of Object.entries(parsers_default)) {
-		log.info(`Trying to parse help string with ${parserName} parser...`);
+		log.debug(`Trying to parse help string with ${parserName} parser...`);
 		try {
 			return helpStringToObjectFunction(helpString);
 		} catch (error) {
-			if (error instanceof Error) log.info(`Error in "${parserName}" parser: ${String(error)}`);
+			if (error instanceof Error) log.error(`Error in "${parserName}" parser: ${String(error)}`);
 			continue;
 		}
 	}
 	log.error("Could not parse help string with any parser");
 }
-
 //#endregion
 //#region src/utilities/get-help-markdown.ts
 /**
@@ -722,7 +732,7 @@ async function getHelpMarkdown(cliCommand, helpFlag = "--help", depth) {
 }
 async function renderHelpMarkdownObject(cliCommand, helpFlag, depth, programInfo) {
 	if (depth <= 0) {
-		log.info(`Max CLI command help depth reached, stopping recursion`);
+		log.warn(`Max CLI command help depth reached, stopping recursion`);
 		return "";
 	}
 	let markdown = helpObjectToMarkdown(programInfo, depth);
@@ -758,26 +768,6 @@ async function getHelpString(resolvedCommand) {
 	if (rawHelpString === void 0 || rawHelpString === "") throw new Error(`No result from running CLI help command: "${resolvedCommand}"\n`);
 	return rawHelpString;
 }
-
-//#endregion
-//#region src/utilities/get-package-json.ts
-let packageJson;
-/**
-* Convenience function for rules
-* Load as package json only as needed, memoize
-* Rules could call this themselves, but this is more convenient and efficient
-* @throws {Error} If no package.json is found
-*/
-async function getPackageJson() {
-	const { packageFile } = await loadConfig();
-	if (packageFile === void 0) throw new Error("No packageFile found or set in config");
-	packageJson ??= await readPackage({ cwd: path.dirname(packageFile) });
-	return {
-		packageJson,
-		packagePath: packageFile
-	};
-}
-
 //#endregion
 //#region src/utilities/is-executable.ts
 /**
@@ -798,7 +788,6 @@ async function isExecutable(filePath, strictExtensions = false) {
 		return false;
 	}
 }
-
 //#endregion
 //#region src/utilities/infer-command.ts
 /**
@@ -811,17 +800,23 @@ async function inferCommand(cliCommand) {
 	cliCommand ??= await getFirstBinFromPackage();
 	return ensureExecutable(cliCommand);
 }
+function firstOf(value) {
+	if (value === void 0) return void 0;
+	return Array.isArray(value) ? value[0] : value;
+}
 async function getFirstBinFromPackage() {
-	const { packageJson, packagePath } = await getPackageJson();
-	const packageDirectory = path.dirname(packagePath);
-	if (packageJson.bin) {
-		const binPath = typeof packageJson.bin === "string" ? path.resolve(packageDirectory, packageJson.bin) : path.resolve(packageDirectory, String(Object.values(packageJson.bin).at(0)));
+	const { nodePackageJson } = await getContextMetadata();
+	const nodePackage = firstOf(nodePackageJson);
+	if (nodePackage?.source !== void 0 && nodePackage.data.bin !== void 0) {
+		const packageDirectory = path.dirname(nodePackage.source);
+		const packageBin = nodePackage.data.bin;
+		const binPath = typeof packageBin === "string" ? path.resolve(packageDirectory, packageBin) : path.resolve(packageDirectory, String(Object.values(packageBin).at(0)));
 		if (looksLikePath(binPath)) {
-			log.info(`Inferred <!-- cli-help --> command to run from package.json: ${binPath}`);
+			log.debug(`Inferred <!-- cli-help --> command to run from package.json: ${binPath}`);
 			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 "cliCommand" option to the expansion comment, e.g. <!-- cli-help({cliCommand: './dist/bin.js'}) -->`);
 }
 function looksLikePath(maybePath) {
 	const parsed = path.parse(maybePath);
@@ -834,27 +829,26 @@ async function ensureExecutable(filePath) {
 	throw new Error(`The cli-help rule noticed that "${resolvedPath}" is not executable.`);
 }
 async function getCommandPathFromPackage(commandName) {
-	const { packageJson } = await getPackageJson();
-	for (const [key, value] of Object.entries(packageJson.bin ?? {})) {
+	const { nodePackageJson } = await getContextMetadata();
+	const binObject = firstOf(nodePackageJson)?.data.bin;
+	if (binObject !== void 0 && typeof binObject !== "string") for (const [key, value] of Object.entries(binObject)) {
 		if (key === commandName) return value;
 		if (path.normalize(value) === path.normalize(commandName)) return value;
 	}
 }
-
 //#endregion
 //#region src/index.ts
-const cliHelpRule = { async content(options) {
+const cliHelpRule = defineConfig({ cli: { async content(options, _context) {
 	const validOptions = z.object({
 		cliCommand: z.string().optional(),
 		depth: z.number().optional(),
 		helpFlag: z.string().optional()
 	}).optional().parse(options);
 	return getHelpMarkdown(await inferCommand(validOptions?.cliCommand), validOptions?.helpFlag, validOptions?.depth);
-} };
-var src_default = {
-	cli: cliHelpRule,
-	"cli-help": cliHelpRule
-};
-
+} } });
+var src_default = defineConfig({
+	cli: cliHelpRule.cli,
+	"cli-help": cliHelpRule.cli
+});
 //#endregion
-export { src_default as default };
+export { src_default as default, setLogger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat-plugin-cli-help",
-  "version": "1.0.7",
+  "version": "2.0.0",
   "description": "Mdat plugin to generate tabular help documentation for CLI tools in Markdown files.",
   "keywords": [
     "markdown",
@@ -21,6 +21,7 @@
     "email": "eric@ericmika.com",
     "url": "https://ericmika.com"
   },
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -35,30 +36,28 @@
   ],
   "dependencies": {
     "@types/which": "^3.0.4",
-    "chevrotain": "^11.1.1",
+    "chevrotain": "^12.0.0",
     "execa": "^9.6.1",
-    "read-pkg": "^10.1.0",
-    "type-fest": "^5.4.4",
+    "lognow": "^0.5.2",
+    "type-fest": "^5.5.0",
     "which": "^6.0.1",
-    "zod": "^3.25.76"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@kitschpatrol/shared-config": "^6.0.0",
-    "@types/node": "~20.19.33",
-    "bumpp": "^10.4.1",
-    "mdat": "^1.3.5",
+    "@kitschpatrol/shared-config": "^6.2.0",
+    "@types/node": "~22.17.2",
+    "bumpp": "^11.0.1",
+    "mdat": "^2.0.0",
     "meow": "^14.1.0",
-    "remark-mdat": "^1.2.3",
-    "tsdown": "^0.20.3",
+    "tsdown": "^0.21.7",
     "typescript": "~5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.2"
   },
   "peerDependencies": {
-    "mdat": "^1.1.0",
-    "remark-mdat": "^1.1.0"
+    "mdat": "^2.0.0"
   },
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.17.0"
   },
   "devEngines": {
     "runtime": {
@@ -72,6 +71,6 @@
     "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",
-    "test": "vitest --no-file-parallelism"
+    "test": "vitest run --no-file-parallelism"
   }
 }

package/readme.md

@@ -1,5 +1,3 @@
-<!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->
-
 <!-- title -->
 
 # mdat-plugin-cli-help
@@ -10,6 +8,7 @@
 
 [![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)
+[![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 -->
 
@@ -46,14 +45,12 @@ pnpm add -D mdat-plugin-cli-help
 Register the plugin in your mdat config file, e.g. `mdat.config.ts`:
 
 ```ts
-import type { Config } from 'mdat'
+import { defineConfig } from 'mdat'
 import cliHelp from 'mdat-plugin-cli-help'
 
-export default {
-  rules: {
-    ...cliHelp,
-  },
-} satisfies Config
+export default defineConfig({
+  ...cliHelp,
+})
 ```
 
 ## Usage
@@ -61,13 +58,13 @@ export default {
 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({ cliCommand: "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({ cliCommand: "mdat", depth: 1 }) -->
 
 #### Command: `mdat`
 
@@ -113,7 +110,7 @@ The command is also aliased under the `<!-- cli -->` keyword.
 This would have equivalent output to the above:
 
 ```markdown
-<!-- cli { cliCommand: "mdat", depth: 1 } -->
+<!-- cli({ cliCommand: "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: