mdat 1.1.0 → 1.2.1

package/dist/readme/rules/index.d.ts

@@ -4,9 +4,6 @@ declare const _default: {
         content(options: import("type-fest").JsonValue, tree: import("mdast").Root): Promise<string>;
         order: number;
     };
-    tldraw: {
-        content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
-    };
     title: {
         applicationOrder: number;
         content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
@@ -57,12 +54,6 @@ declare const _default: {
     code: {
         content(options: import("type-fest").JsonValue): Promise<string>;
     };
-    'cli-help': {
-        content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
-    };
-    cli: {
-        content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
-    };
     banner: {
         content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
         order: number;

package/dist/readme/rules/utilities/size/size-report.d.ts

@@ -13,7 +13,7 @@ export type SizeReport = {
  * Analyzes a file's size and its compressed sizes using Brotli and Gzip
  * @param filePath - Path to the file to analyze
  * @returns Promise containing detailed size report
- * @throws Error if file cannot be read or compressed
+ * @throws {Error} if file cannot be read or compressed
  */
 export declare function createSizeReport(filePath: string): Promise<SizeReport>;
 export {};

package/dist/readme/utilities.d.ts

@@ -10,6 +10,6 @@ export declare function findReadme(): Promise<string | undefined>;
  * Searches up for a readme.md file
  * @see `findReadme()` for more details on the search process.
  * @returns The path to the readme file
- * @throws if no readme is found
+ * @throws {Error} if no readme is found
  */
 export declare function findReadmeThrows(): Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "CLI tool and TypeScript library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.",
   "keywords": [
     "mdat",
@@ -38,45 +38,44 @@
   ],
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@kitschpatrol/tldraw-cli": "^5.0.0",
     "@types/mdast": "^4.0.4",
-    "@types/node": "^20.19.17",
+    "@types/node": "^22.19.0",
     "@types/unist": "^3.0.3",
-    "@types/which": "^3.0.4",
-    "@types/yargs": "^17.0.33",
+    "@types/yargs": "^17.0.34",
     "cosmiconfig": "^9.0.0",
-    "cosmiconfig-typescript-loader": "^6.1.0",
-    "execa": "^9.6.0",
+    "cosmiconfig-typescript-loader": "^6.2.0",
     "globby": "^14.1.0",
     "read-pkg": "^9.0.1",
-    "remark-mdat": "^1.1.1",
-    "type-fest": "^5.0.1",
+    "remark-mdat": "^1.1.3",
+    "type-fest": "^5.2.0",
     "unified-engine": "^11.2.2",
-    "vfile": "^6.0.3",
-    "which": "^5.0.0"
+    "vfile": "^6.0.3"
   },
   "devDependencies": {
-    "@kitschpatrol/shared-config": "^5.7.0",
-    "bumpp": "^10.2.3",
-    "chevrotain": "^11.0.3",
+    "@kitschpatrol/shared-config": "^5.8.1",
+    "bumpp": "^10.3.1",
+    "execa": "^9.6.0",
     "find-up": "^8.0.0",
     "mdast-util-toc": "^7.1.0",
+    "mdat-plugin-cli-help": "^1.0.2",
+    "mdat-plugin-example": "^1.0.1",
+    "mdat-plugin-tldraw": "^1.0.2",
     "nanoid": "^5.1.6",
     "package-directory": "^8.1.0",
     "package-up": "^5.0.0",
     "path-type": "^6.0.0",
     "picocolors": "^1.1.1",
-    "plur": "^5.1.0",
+    "plur": "^6.0.0",
     "pretty-bytes": "^7.1.0",
     "pretty-ms": "^9.3.0",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
     "to-vfile": "^8.0.0",
-    "tsdown": "^0.15.5",
-    "typescript": "~5.9.2",
+    "tsdown": "^0.16.0",
+    "typescript": "~5.9.3",
     "unplugin-raw": "^0.6.3",
     "untildify": "^6.0.0",
-    "vitest": "^3.2.4",
+    "vitest": "^4.0.7",
     "yargs": "^17.7.2",
     "zod": "^3.25.76"
   },
@@ -92,7 +91,7 @@
     "dev": "pnpm run test",
     "fix": "ksc fix",
     "lint": "ksc lint",
-    "release": "bumpp --commit 'Release: %s' && pnpm run build && pnpm publish --otp $(op read 'op://Personal/Npmjs/one-time password?attribute=otp')",
+    "release": "bumpp --commit 'Release: %s' && pnpm run build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish",
     "test": "vitest --no-file-parallelism"
   }
 }

package/readme.md

@@ -34,6 +34,10 @@
   - [Configuration](#configuration)
   - [Creating custom rules](#creating-custom-rules)
   - [The `mdat readme` subcommand](#the-mdat-readme-subcommand)
+- [Plugins](#plugins)
+  - [Installing a rule plugin](#installing-a-rule-plugin)
+  - [Creating a rule plugin](#creating-a-rule-plugin)
+  - [Available rule plugins](#available-rule-plugins)
 - [Background](#background)
   - [Motivation](#motivation)
   - [Similar projects](#similar-projects)
@@ -190,7 +194,7 @@ As [noted below](#similar-projects), there are several similar projects out ther
    }
    ```
 
-   This scales all the way up to some of the [more](src/lib/readme/rules/table-of-contents.ts) [elaborate](src/lib/readme/rules/cli-help.ts) rules found in the `mdat readme` subcommand.
+   This scales all the way up to some of the [more elaborate](src/lib/readme/rules/table-of-contents.ts) rules found in the `mdat readme` subcommand.
 
    You can also treat any JSON file as a rule set. MDAT will flatten it to allow any dot-notated key path to become a placeholder comment keyword.
 
@@ -454,7 +458,7 @@ mdat readme init [options]
 
 <!-- /cli-help -->
 
-_Meta note: The entire section above was generated automatically by the [`<!-- cli-help -->`](src/lib/readme/rules/cli-help.ts) mdat expansion rule provided in `mdat readme` subcommand. It dynamically parses the output from `mdat --help` into a Markdown table, recursively calling `--help` on subcommands to build a tidy representation of the help output._
+_Meta note: The entire section above was generated automatically by the [mdat-plugin-cli-help](https://github.com/kitschpatrol/mdat-plugin-cli-help) plugin. It dynamically parses the output from `mdat --help` into a Markdown table, recursively calling `--help` on subcommands to build a tidy representation of the help output._
 
 #### Examples
 
@@ -745,33 +749,11 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
 
   | File         | Original | Gzip    | Brotli |
   | ------------ | -------- | ------- | ------ |
-  | package.json | 2.6 kB   | 1.1 kB  | 987 B  |
-  | readme.md    | 57.5 kB  | 11.4 kB | 9.1 kB |
+  | package.json | 2.5 kB   | 1.1 kB  | 974 B  |
+  | readme.md    | 58 kB    | 11.4 kB | 9.1 kB |
 
   <!-- /size-table -->
 
-- ###### `<!-- cli-help -->`
-
-  Automatically transform a CLI command's `--help` output into nicely formatted Markdown tables. 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.
-
-  ([Parsing help output](src/lib/readme/rules/utilities/cli-help/parsers) 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.)
-
-  This rule is also aliased under the `<!-- cli -->` keyword.
-
-- ###### `<!-- tldraw { src: "./sketch.tldr" } -->`
-
-  Allows embedding [tldraw](https://www.tldraw.com) files in your readme. Accepts either a path to a local `.tldr` file, or remote tldraw URLs.
-
-  Automatically generates both "light" and "dark" SVG variations of the sketch, and emits a `<picture>` element per [GitHub's guidelines](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#specifying-the-theme-an-image-is-shown-to) to present the correctly themed image based on the viewer's preferences.
-
-  Generated assets are intelligently hashed to aide in cache busting. For locally referenced files, the image will only be regenerated when the content in the source file changes.
-
-  The implementation is based on [@kitschpatrol/tldraw-cli](https://github.com/kitschpatrol/tldraw-cli), and depends on Puppeteer to generate the assets, so it can be a bit slow. Referencing local files instead of remote URLs is recommended for improved performance.
-
-  This rule is used to embed the diagram at the top of this readme.
-
 ##### Compound
 
 Compound rules combine several stand-alone rules under a single keyword, which can help reduce comment clutter in your readme's Markdown.
@@ -812,6 +794,99 @@ The `init` command provides a number of "starter readme" templates incorporating
 
   Includes all sections from the [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) specification. [See an example](https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/maximal-readme.md).
 
+## Plugins
+
+Rule plugins are packages that export one or more mdat expansion rules.
+
+### Installing a rule plugin
+
+Install the plugin package using your package manager of choice. For example, with npm:
+
+```sh
+npm install mdat-plugin-example
+```
+
+To use the rule, just spread the plugin into your `mdat` configuration, for example in your project's `mdat.config.ts` file:
+
+```ts
+import type { Config } from 'mdat'
+import example from 'mdat-plugin-example'
+
+export default {
+  rules: {
+    ...example,
+  },
+} satisfies Config
+```
+
+Then, you can use the `example` expansion rule in your Markdown files:
+
+For example, in your `readme.md` file you can add:
+
+```md
+<!-- example -->
+```
+
+Then run the `mdat readme` subcommand:
+
+```sh
+mdat readme
+```
+
+Which will expand the `example` rule in your `readme.md` file to:
+
+```md
+<!-- example -->
+
+Hello from the [mdat](https://github.com/kitschpatrol/mdat) example plugin!
+
+<!-- /example -->
+```
+
+### Creating a rule plugin
+
+A rule plugin is a ESM module or npm package with a default export of or more mdat rules.
+
+If you just need a quick one-off rule specific to your project, you can define it directly in your `mdat.config.ts` file. A plugin is only necessary if you want to share the rule or use it across multiple projects.
+
+By convention, mdat plugin rule packages should have the name prefix `mdat-plugin-`. The package should take a peer dependency on `mdat`.
+
+The most basic rule plugin might look like this:
+
+```ts
+import type { Rules } from 'mdat'
+
+export default {
+  hello: {
+    content() {
+      return 'Hello from an mdat plugin!'
+    },
+  },
+} satisfies Rules
+```
+
+See the [mdat-plugin-example](https://github.com/kitschpatrol/mdat-plugin-example) repository for a complete example.
+
+### Available rule plugins
+
+#### [mdat-plugin-tldraw](https://github.com/kitschpatrol/mdat-plugin-tldraw)
+
+Allows embedding [tldraw](https://www.tldraw.com) files in your readme.
+
+This rule is used to embed the diagram at the top of this readme.
+
+Example usage: `<!-- tldraw { src: "./sketch.tldr" } -->`
+
+#### [mdat-plugin-cli-help](https://github.com/kitschpatrol/mdat-plugin-cli-help)
+
+Automatically transform a CLI command's `--help` output into nicely formatted Markdown tables. 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.
+
+Example usage: `<!-- cli-help -->`
+
+This rule is also aliased under the `<!-- cli -->` keyword.
+
 ## Background
 
 ### Motivation

package/dist/readme/rules/cli-help.d.ts

@@ -1,6 +0,0 @@
-declare const _default: {
-    'cli-help': {
-        content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
-    };
-};
-export default _default;

package/dist/readme/rules/cli.d.ts

@@ -1,9 +0,0 @@
-/**
- * Simple alias for cli-help
- */
-declare const _default: {
-    cli: {
-        content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
-    };
-};
-export default _default;

package/dist/readme/rules/tldraw.d.ts

@@ -1,6 +0,0 @@
-declare const _default: {
-    tldraw: {
-        content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
-    };
-};
-export default _default;

package/dist/readme/rules/utilities/cli-help/get-help-markdown.d.ts

@@ -1,8 +0,0 @@
-/**
- * Get help output from a CLI command and return it as markdown
- */
-export declare function getHelpMarkdown(cliCommand: string, helpFlag?: string, depth?: number): Promise<string>;
-/**
- * Exported for testing
- */
-export declare function renderHelpMarkdownBasic(rawHelpString: string): string;

package/dist/readme/rules/utilities/cli-help/help-object-to-markdown.d.ts

@@ -1,6 +0,0 @@
-import type { ProgramInfo } from './parsers/index';
-/**
- * Converts a ProgramInfo object extracted by one of the help parsers into a big
- * beautiful Markdown table.
- */
-export declare function helpObjectToMarkdown(programInfo: ProgramInfo, depthRemaining?: number): string;

package/dist/readme/rules/utilities/cli-help/help-string-to-object.d.ts

@@ -1,10 +0,0 @@
-import type { ProgramInfo } from './parsers/index';
-/**
- * Tries to parse a help string into an object through a process of trial and
- * error with the available parsers.
- *
- * Generally, there's no way to know which framework was used to generate a
- * particular CLI tool without inspecting the output for particular formatting
- * patterns.
- */
-export declare function helpStringToObject(helpString: string): ProgramInfo | undefined;

package/dist/readme/rules/utilities/cli-help/infer-command.d.ts

@@ -1,7 +0,0 @@
-/**
- * Accommodate missing or sloppy cli help command input
- * @param cliCommand - Can be nothing, a command name on the path like `git`, or a path to an executable like `./bin/cli.js`
- * @returns The path to a verified executable
- * @throws If nothing can be inferred or resolved
- */
-export declare function inferCommand(cliCommand: string | undefined): Promise<string>;

package/dist/readme/rules/utilities/cli-help/is-executable.d.ts

@@ -1,9 +0,0 @@
-/**
- * This file is vendored with modification from https://github.com/sindresorhus/is-executable
- * to work around a "[DEP0176] DeprecationWarning: fs.X_OK is deprecated, use fs.constants.X_OK instead"
- * error from Node.
- */
-/**
- * Check if a file is executable (async).
- */
-export declare function isExecutable(filePath: string): Promise<boolean>;

package/dist/readme/rules/utilities/cli-help/parsers/index.d.ts

@@ -1,46 +0,0 @@
-import { helpStringToObject as helpStringToObjectMeow } from './meow';
-import { helpStringToObject as helpStringToObjectYargs } from './yargs';
-export type Command = {
-    arguments?: string[];
-    commandName?: string;
-    default?: boolean;
-    description?: string;
-    parentCommandName?: string;
-};
-export type Positional = {
-    arguments?: string[];
-    defaultValue?: string;
-    description?: string;
-    required?: boolean;
-    type?: string;
-};
-export type Option = {
-    aliases?: string[];
-    arguments?: string[];
-    choices?: string[];
-    defaultValue?: string;
-    description?: string;
-    flags?: string[];
-    type?: string;
-};
-export type ProgramInfo = {
-    arguments?: string[];
-    commandName: string;
-    commands?: Command[];
-    description?: string;
-    options?: Option[];
-    positionals?: Positional[];
-    subcommandName?: string;
-};
-declare const _default: {
-    yargs: typeof helpStringToObjectYargs;
-    meow: typeof helpStringToObjectMeow;
-};
-export default _default;
-/**
- * Get the command and subcommand from a command string.
- */
-export declare function getCommandParts(wholeCommand: string | undefined): {
-    command: string;
-    subcommand: string | undefined;
-};

package/dist/readme/rules/utilities/cli-help/parsers/meow.d.ts

@@ -1,7 +0,0 @@
-import type { ProgramInfo } from './index';
-/**
- * Converts am unstructured help string emitted from a CLI tool built with the
- * `meow` CLI library and turn it into a structured POJO describing the
- * command.
- */
-export declare function helpStringToObject(helpString: string): ProgramInfo;

package/dist/readme/rules/utilities/cli-help/parsers/yargs.d.ts

@@ -1,7 +0,0 @@
-import type { ProgramInfo } from './index';
-/**
- * Converts am unstructured help string emitted from a CLI tool built with the
- * `Yargs` CLI library and turn it into a structured POJO describing the
- * command.
- */
-export declare function helpStringToObject(helpString: string): ProgramInfo;