remark-mdat 1.2.2 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remark-mdat",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "A remark plugin implementing the Markdown Autophagic Template (MDAT) system.",
   "keywords": [
     "mdat",
@@ -26,7 +26,14 @@
     "email": "eric@ericmika.com",
     "url": "https://ericmika.com"
   },
+  "sideEffects": false,
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,34 +42,42 @@
   ],
   "dependencies": {
     "@types/mdast": "^4.0.4",
-    "@types/node": "^20.19.30",
     "@types/unist": "^3.0.3",
-    "picocolors": "^1.1.1",
-    "type-fest": "^5.4.1",
-    "unified": "^11.0.5",
-    "vfile": "^6.0.3",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@kitschpatrol/shared-config": "^5.12.0",
-    "bumpp": "^10.4.0",
     "cli-table3": "^0.6.5",
     "deepmerge-ts": "^7.1.5",
     "hast-util-from-html": "^2.0.3",
     "json5": "^2.2.3",
+    "picocolors": "^1.1.1",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
-    "tsdown": "^0.19.0",
-    "typescript": "~5.9.3",
-    "unist-util-visit": "^5.0.0",
+    "type-fest": "^5.4.4",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "vfile": "^6.0.3",
     "vfile-message": "^4.0.3",
-    "vitest": "^4.0.17"
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.2",
+    "@kitschpatrol/shared-config": "^6.0.2",
+    "@types/node": "~20.19.35",
+    "bumpp": "^10.4.1",
+    "publint": "^0.3.18",
+    "tsdown": "^0.20.3",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.18"
   },
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=20.0.0"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22.21.0"
+    }
   },
   "scripts": {
-    "build": "tsdown --no-fixed-extension --dts false && tsc -p tsconfig.build.json",
+    "build": "tsdown",
     "clean": "git rm -f pnpm-lock.yaml ; git clean -fdX",
     "dev": "pnpm run test",
     "fix": "ksc fix",

package/readme.md

@@ -97,15 +97,42 @@ remark().use(remarkMdat)
 
 #### Options
 
-The plugin accepts an optional options object which exposes some configuration options and, most importantly, determines how comments in the source Markdown file will be expanded via the `rules` field:
+The plugin accepts an optional options object. All fields are optional:
+
+| Option                  | Type                | Default | Description                                                                                                                                           |
+| ----------------------- | ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rules`                 | `Rules`             | `{}`    | A record mapping comment keywords to rules that determine what content is expanded at each comment site. See [Rules](#rules) below.                   |
+| `addMetaComment`        | `boolean \| string` | `false` | If `true`, prepends a warning comment to the document noting that content was auto-generated. If a `string`, uses that string as the warning message. |
+| `closingPrefix`         | `string`            | `'/'`   | The prefix used to identify closing comment tags, e.g. the `/` in `<!-- /keyword -->`.                                                                |
+| `keywordPrefix`         | `string`            | `''`    | A prefix required on all mdat comments. Useful for namespacing, e.g. setting `'mm-'` means only `<!-- mm-keyword -->` comments are processed.         |
+| `metaCommentIdentifier` | `string`            | `'+'`   | The character used to identify auto-generated meta comments, e.g. `<!--+ ... +-->`.                                                                   |
+
+#### Rules
+
+Rules are defined as a `Record<string, Rule>` where each key is a keyword matching an HTML comment in the Markdown file (e.g. `title` matches `<!-- title -->`).
+
+A `Rule` value can take several forms:
 
 ```ts
-export type Options = {
-  addMetaComment?: boolean | string // Default: false
-  closingPrefix?: string // Default: '/',
-  keywordPrefix?: string // Default: '',
-  metaCommentIdentifier?: string // Default: '+',
-  rules?: Rules // Default: a single test rule for the 'mdat' keyword
+const rules: Rules = {
+  // String: direct replacement
+  greeting: 'Hello, world!',
+  // Array: compound rule combining multiple sub-rules
+  header: ['# My Project', () => getDescription()],
+  // Function with arguments: receives parsed options from the comment
+  // e.g. <!-- greeting({name: "Alice"}) --> or <!-- greeting {name: "Alice"} -->
+  personalGreeting: (options) => `Hello, ${options.name}!`,
+  // Function: dynamic content (sync or async)
+  time: () => new Date().toDateString(),
+  // Object: rule with validation metadata
+  title: {
+    applicationOrder: 0, // Processing priority (default: 0)
+    content: () => getTitle(), // String, function, or array
+    order: 1, // Expected position relative to other comments
+    required: true, // Error if comment is missing (default: false)
+  },
+  // Function with document access: receives the full mdast tree
+  toc: (_options, tree) => generateTocFromTree(tree),
 }
 ```
 
@@ -173,35 +200,42 @@ The remark-mdat plugin chains these utilities together to accommodate the typica
 
   Composite transformer function performing end-to-end mdat comment expansion and validation on Markdown ASTs by chaining the other utility functions described below.
 
-  _Exported as `mdat`_
+  _Exported as `mdat(tree: Root, file: VFile, options: MdatOptions): Promise<void>`_
 
-  Utilities wrapped by `mdast-util-mdat`:
+  `MdatOptions` includes `addMetaComment`, `closingPrefix`, `keywordPrefix`, `metaCommentIdentifier`, and `rules` (all required, unlike the plugin's `Options` where they are optional with defaults).
 
+  Utilities wrapped by `mdast-util-mdat`:
   - [**`mdast-util-mdat-split`**](./src/lib/mdast-utils/mdast-util-mdat-split.ts)
 
-    Transformer function that allows inline mdat expansion comments.
+    Transformer function that splits multi-comment HTML nodes into individual mdast nodes, allowing inline mdat expansion comments.
 
-    _Exported as `mdatSplit`_
+    _Exported as `mdatSplit(tree: Root, file: VFile): void`_
 
   - [**`mdast-util-mdat-clean`**](./src/lib/mdast-utils/mdast-util-mdat-clean.ts)
 
     Transformer function that "resets" all mdat comment expansions in a file, collapsing expanded comments back into single-line placeholders.
 
-    _Exported as `mdatClean`_
+    _Exported as `mdatClean(tree: Root, file: VFile, options: MdatCleanOptions): void`_
+
+    `MdatCleanOptions` includes `closingPrefix`, `keywordPrefix`, and `metaCommentIdentifier`.
 
   - [**`mdast-util-mdat-expand`**](./src/lib/mdast-utils/mdast-util-mdat-expand.ts)
 
-    Transformer function that expands mdat comments (e.g. `<!-- title -->`) in a Markdown file according to the rule set passed in to the `MdatExpandOptions` argument.
+    Transformer function that expands mdat comments (e.g. `<!-- title -->`) in a Markdown file according to the rule set passed in to the options argument.
 
-    _Exported as `mdatExpand`_
+    _Exported as `mdatExpand(tree: Root, file: VFile, options: MdatExpandOptions): Promise<void>`_
+
+    `MdatExpandOptions` includes `addMetaComment`, `closingPrefix`, `keywordPrefix`, `metaCommentIdentifier`, and `rules`.
 
   - [**`mdast-util-mdat-check`**](./src/lib/mdast-utils/mdast-util-mdat-check.ts)
 
-    Transformer function that validates an expanded Markdown document against the requirements defined in the rules passed in to the `MdatCheckOptions` argument.
+    Transformer function that validates an expanded Markdown document against the requirements defined in the rules passed in to the options argument. Does not modify the tree, it only appends messages to the VFile.
+
+    _Exported as `mdatCheck(tree: Root, file: VFile, options: MdatCheckOptions): Promise<void>`_
 
-    See `reporterMdat` to extract, format, and log results from VFile messages written by `mdatCheck`. This function does not modify the tree, it only appends messages to the VFiles passed through it.
+    `MdatCheckOptions` extends `MdatExpandOptions` with a `paranoid` boolean for extra validation checks.
 
-    _Exported as `mdatCheck`_
+    See `reporterMdat` to extract, format, and log results from VFile messages written by `mdatCheck`.
 
 ## Implementation notes
 

package/dist/lib/mdast-utils/mdast-util-mdat-check.d.ts

@@ -1,16 +0,0 @@
-import type { Root } from 'mdast';
-import type { VFile } from 'vfile';
-import type { Rules } from '../mdat/rules';
-export type Options = {
-    addMetaComment: boolean | string;
-    closingPrefix: string;
-    keywordPrefix: string;
-    metaCommentIdentifier: string;
-    /** Enable extra checks, too noisy for real life. */
-    paranoid: boolean;
-    rules: Rules;
-};
-/**
- * Mdast utility function to check mdat source document, and output.
- */
-export declare function mdatCheck(tree: Root, file: VFile, options: Options): Promise<void>;

package/dist/lib/mdast-utils/mdast-util-mdat-clean.d.ts

@@ -1,13 +0,0 @@
-import type { Root } from 'mdast';
-import type { VFile } from 'vfile';
-export type Options = {
-    closingPrefix: string;
-    keywordPrefix: string;
-    metaCommentIdentifier: string;
-};
-/**
- * Collapses any expanded mdat comments and removes meta comments,
- * effectively resetting the document to its pre-expansion state. No-op if no
- * mdat comments are found.
- */
-export declare function mdatClean(tree: Root, file: VFile, options: Options): void;

package/dist/lib/mdast-utils/mdast-util-mdat-expand.d.ts

@@ -1,11 +0,0 @@
-import type { Root } from 'mdast';
-import type { VFile } from 'vfile';
-import type { Rules } from '../mdat/rules';
-export type Options = {
-    addMetaComment: boolean | string;
-    closingPrefix: string;
-    keywordPrefix: string;
-    metaCommentIdentifier: string;
-    rules: Rules;
-};
-export declare function mdatExpand(tree: Root, file: VFile, options: Options): Promise<void>;

package/dist/lib/mdast-utils/mdast-util-mdat-split.d.ts

@@ -1,8 +0,0 @@
-import type { Html, Root, Text } from 'mdast';
-import type { VFile } from 'vfile';
-/**
- * Mdast utility plugin to split any multi-comment nodes and their content into individual MDAST HTML
- * nodes. They're wrapped in a paragraph so as not to introduce new breaks.
- */
-export declare function mdatSplit(tree: Root, file: VFile): void;
-export declare function splitHtmlIntoMdastNodes(mdastNode: Html): Array<Html | Text>;

package/dist/lib/mdast-utils/mdast-util-mdat.d.ts

@@ -1,11 +0,0 @@
-import type { Root } from 'mdast';
-import type { VFile } from 'vfile';
-import type { Rules } from '../mdat/rules';
-export type Options = {
-    addMetaComment: boolean | string;
-    closingPrefix: string;
-    keywordPrefix: string;
-    metaCommentIdentifier: string;
-    rules: Rules;
-};
-export declare function mdat(tree: Root, file: VFile, options: Options): Promise<void>;

package/dist/lib/mdat/deep-merge-defined.d.ts

@@ -1 +0,0 @@
-export declare function deepMergeDefined<T extends Record<string, unknown>>(...objects: T[]): T;

package/dist/lib/mdat/log.d.ts

@@ -1,12 +0,0 @@
-declare const log: {
-    verbose: boolean;
-    log(...data: unknown[]): void;
-    logPrefixed(prefix: string, ...data: unknown[]): void;
-    info(...data: unknown[]): void;
-    infoPrefixed(prefix: string, ...data: unknown[]): void;
-    warn(...data: unknown[]): void;
-    warnPrefixed(prefix: string, ...data: unknown[]): void;
-    error(...data: unknown[]): void;
-    errorPrefixed(prefix: string, ...data: unknown[]): void;
-};
-export default log;

package/dist/lib/mdat/mdat-log.d.ts

@@ -1,23 +0,0 @@
-import type { Node } from 'unist';
-import type { VFile } from 'vfile';
-/**
- * Tries to provide a simpler wrapper to vfile.message
- */
-export type MdatMessage = {
-    column?: number;
-    level: 'error' | 'info' | 'warn';
-    line?: number;
-    message: string;
-    source?: string;
-};
-export type MdatFileReport = {
-    destinationPath?: string;
-    errors: MdatMessage[];
-    infos: MdatMessage[];
-    sourcePath: string;
-    warnings: MdatMessage[];
-};
-export declare function saveLog(file: VFile, level: 'error' | 'info' | 'warn', source: string, message: string, line?: number, column?: number): void;
-export declare function saveLog(file: VFile, level: 'error' | 'info' | 'warn', source: string, message: string, node?: Node): void;
-export declare function getMdatReports(files: VFile[]): MdatFileReport[];
-export declare function reporterMdat(files: VFile[]): void;

package/dist/lib/mdat/parse.d.ts

@@ -1,62 +0,0 @@
-import type { Html, Parent } from 'mdast';
-import type { JsonValue, Simplify } from 'type-fest';
-/**
- * Structured data about a parsed comment.
- * Note that this is a discriminated union based on the `type` field.
- */
-type CommentMarker = Simplify<{
-    /** The complete original comment, e.g. `<!-- keyword -->`  */
-    html: string;
-} & ({
-    /** Character used to delimit closing tags, e.g. the `/` in `<!-- /keyword -->`  */
-    closingPrefix: string;
-    /** The first complete word in the comment  */
-    keyword: string;
-    /** The unique keyword prefix  */
-    keywordPrefix: string;
-    /** Parsed JSON object of argument string that followed the keyword, empty object if nothing passed  */
-    options: JsonValue;
-    /**
-     * `open`: A mdat-style opening comment tag, e.g. `<!-- keyword -->`  \
-     * `close`: A mdat-style closing comment tag, e.g. `<!-- /keyword -->`
-     */
-    type: 'close' | 'open';
-} | {
-    /** The original text inside the comment, e.g. `<!-- content -->`  */
-    content: string;
-    /**
-     * `meta`: A mdat-style generated meta comment tag  \
-     * `native`: A normal comment that does not match the the `keywordPrefix` (if specified)
-     */
-    type: 'meta' | 'native';
-})>;
-/**
- * Parsed comment with additional information about the Mdast Node and its Parent.
- */
-export type CommentMarkerNode = Simplify<CommentMarker & {
-    /** Original Mdast HTML Node where the comment was found. */
-    node: Html;
-    /** Parent of original Mdast HTML Node where the comment was found. */
-    parent: Parent;
-}>;
-type CommentMarkerParseOptions = {
-    /** Character to identify closing tags, e.g. the `/` in `<!-- /keyword -->`  */
-    closingPrefix: string;
-    /** Prefix to require on all mdat comments, e.g. `mm-`  */
-    keywordPrefix: string;
-    /** Means of identifying mdat generated meta comments, e.g. `+`  */
-    metaCommentIdentifier: string;
-};
-/**
- * Parse an Mdast HTML comment node into structured data.
- * @returns A discriminated union of CommentMarkerNode based on comment type, or
- * undefined if the node is not a comment.
- */
-export declare function parseCommentNode(node: Html, parent: Parent, options: CommentMarkerParseOptions): CommentMarkerNode | undefined;
-/**
- * Parse any comment string into structured data.
- * @returns A discriminated union of CommentMarker based on comment type, or
- * undefined if the node is not a comment.
- */
-export declare function parseComment(text: string, options: CommentMarkerParseOptions): CommentMarker | undefined;
-export {};

package/dist/lib/mdat/rules.d.ts

@@ -1,112 +0,0 @@
-import type { Root } from 'mdast';
-import type { JsonValue, Merge, MergeDeep, SetOptional, Simplify } from 'type-fest';
-import { z } from 'zod';
-export type SimplifyDeep<T> = Simplify<MergeDeep<T, T>>;
-/**
- * Strict normalized rules used internally.
- * Rules normalized to a form with async content functions and other default metadata
- * Simplifies processing elsewhere, while retaining flexibility for rule authors
- */
-export type NormalizedRule = {
-    /**
-     * The order in which the rule should be applied during processing
-     * Helpful if a rule depends on the presence of content generated by another rule
-     * Defaults to 0.
-     */
-    applicationOrder: number;
-    /**
-     * The function that generates the expanded Markdown string.
-     * For 'compound' rules, this can be an array of rules (without keywords).
-     */
-    content: ((options: JsonValue, tree: Root) => Promise<string>) | NormalizedRule[];
-    /**
-     * The expected order of the keyword in the document relative to other expander comments.
-     * Used for validation purposes.
-     * Leave undefined to order skip validation.
-     * Defaults to undefined, which means order is not enforced.
-     */
-    order: number | undefined;
-    /**
-     * Whether the presence of the keyword comment in the document is required.
-     * Used for validation purposes.
-     * Defaults to false.
-     */
-    required: boolean;
-};
-export type Rule = 
-/**
- * Function that returns the Markdown string to expand at the comment site.
- */
-((options: JsonValue, tree: Root) => Promise<string> | string)
-/**
- * Compound rules may be defined an array of rules, without keywords.
- * Can be defined at the top level, if no validation metadata is required, or as the 'content' value
- * of a rule object with validation metadata.
- */
- | Rule[]
-/**
- * The Markdown string to expand at the comment site.
- */
- | SetOptional<Merge<NormalizedRule, {
-    /**
-     * Gets content to expand into the comment.
-     * Can be a simple string for direct replacement, a function that returns a string, or an async function that returns a string.
-     *
-     * If a function is provided, it will be passed the following arguments:
-     * @param options
-     * JSON value of options parsed immediately after the comment keyword in the comment, e.g.:
-     * `<!-- keyword({something: true}) -->` or
-     * `<!-- keyword {something: true}-->`
-     * Sets options to {something: true}
-     * @param tree
-     * Markdown (mdast) abstract syntax tree containing the entire parsed document. Useful for expanders that need the entire document context, such as when generating a table of contents. Do not mutate the AST, instead return a new string.
-     * @returns A string with the generated content. The string will be parsed as Markdown and inserted into the document at the comment's location.
-     */
-    content: ((options: JsonValue, tree: Root) => Promise<string> | string) | Rule[] | string;
-}>, 'applicationOrder' | 'order' | 'required'> | string;
-/**
- * Rules are record objects whose keys match strings inside a Markdown comment, and values explain what should be expanded at the comment site.
- *
- * The record value may be a string, or an object containing additional metadata, possibly with a function to invoke to generate content.
- * @example
- * Most basic rule:
- * ```ts
- * { basic: 'content' }
- * ```
- *
- * Rule with dynamic content:
- * ```ts
- * { basic: () => `${new Date().toISOString()}` }
- * ```
- *
- * Rule with metadata:
- * ```ts
- * { basic-meta: { required: true, content: 'content'} }
- * ```
- *
- * Rule with dynamic content and metadata:
- * { basic-date: { required: true, content: () => `${new Date().toISOString()}` } }
- */
-export type Rules = SimplifyDeep<Record<string, Rule>>;
-export type NormalizedRules = SimplifyDeep<Record<string, NormalizedRule>>;
-export declare function normalizeRules(rules: Rules): NormalizedRules;
-export declare function validateRules(rules: Rules): void;
-export declare const rulesSchema: z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>;
-/**
- * Compound rule helpers, used in both "expand" and "check" utilities
- */
-export declare function getRuleContent(rule: NormalizedRule, options: JsonValue, tree: Root, check?: boolean): Promise<string>;
-/**
- * Returns the rule value from a single-rule record.
- * Useful when aliasing rules or invoking them programmatically.
- *
- * Throws if there are no entries or more than one entry.
- */
-export declare function getSoleRule<T extends NormalizedRules | Rules>(rules: T): T[keyof T];
-/**
- * Returns the rule key from a single-rule record.
- * Useful for comment placeholder validation.
- *
- * Throws if there are no entries or more than one entry.
- */
-export declare function getSoleRuleKey<T extends NormalizedRules | Rules>(rules: T): keyof T;

package/dist/lib/remark-mdat.d.ts

@@ -1,29 +0,0 @@
-import type { Root } from 'mdast';
-import type { Plugin } from 'unified';
-import { z } from 'zod';
-import type { Options as MdatOptions } from './mdast-utils/mdast-util-mdat';
-export type Options = Partial<MdatOptions>;
-export declare const optionsSchema: z.ZodObject<{
-    addMetaComment: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>;
-    closingPrefix: z.ZodOptional<z.ZodString>;
-    keywordPrefix: z.ZodOptional<z.ZodString>;
-    metaCommentIdentifier: z.ZodOptional<z.ZodString>;
-    rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>>;
-}, "strip", z.ZodTypeAny, {
-    closingPrefix?: string | undefined;
-    keywordPrefix?: string | undefined;
-    metaCommentIdentifier?: string | undefined;
-    rules?: Record<string, any> | undefined;
-    addMetaComment?: string | boolean | undefined;
-}, {
-    closingPrefix?: string | undefined;
-    keywordPrefix?: string | undefined;
-    metaCommentIdentifier?: string | undefined;
-    rules?: Record<string, any> | undefined;
-    addMetaComment?: string | boolean | undefined;
-}>;
-/**
- * A remark plugin that expands HTML comments in Markdown files.
- */
-declare const remarkMdat: Plugin<[Options], Root>;
-export default remarkMdat;