remark-mdat 1.2.5 → 2.0.0-preview.2

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { ILogBasic, ILogLayer } from "lognow";
 import { z } from "zod";
 import { Root } from "mdast";
 import { VFile } from "vfile";
@@ -6,42 +7,37 @@ import { Plugin } from "unified";
 
 //#region src/lib/mdat/rules.d.ts
 type SimplifyDeep<T> = Simplify<MergeDeep<T, T>>;
+/**
+ * Context passed to rule content functions during expansion.
+ */
+type RuleContext = {
+  /** File path of the source document, if known. */filePath: string | undefined; /** Parsed YAML frontmatter from the document, if present. */
+  frontmatter: Record<string, unknown> | undefined; /** The full mdast AST of the document. Do not mutate. */
+  tree: Root;
+};
 /**
  * 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
  */
 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[];
+  content: ((options: JsonValue, context: RuleContext) => 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.
+   * 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.
    */
-  required: boolean;
+  order: number;
 };
 type Rule =
 /**
  * Function that returns the Markdown string to expand at the comment site.
  */
-((options: JsonValue, tree: Root) => Promise<string> | string)
+((options: JsonValue, context: RuleContext) => 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
@@ -53,14 +49,9 @@ type Rule =
  */
 | string
 /**
- * Rule object with optional validation metadata.
+ * Rule object with optional metadata.
  */
 | {
-  /**
-   * The order in which the rule should be applied during processing.
-   * Defaults to 0.
-   */
-  applicationOrder?: number;
   /**
    * 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.
@@ -71,21 +62,16 @@ type Rule =
    * `<!-- 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.
+   * @param context
+   * Rule context containing the mdast AST, parsed frontmatter, and file path.
    * @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;
+  content: ((options: JsonValue, context: RuleContext) => Promise<string> | string) | Rule[] | string;
   /**
-   * The expected order of the keyword in the document relative to other expander comments.
-   * Defaults to undefined, which means order is not enforced.
-   */
-  order?: number | undefined;
-  /**
-   * Whether the presence of the keyword comment in the document is required.
-   * Defaults to false.
+   * The order in which the rule should be applied during processing.
+   * Defaults to 0.
    */
-  required?: boolean;
+  order?: number;
 };
 /**
  * Rules are record objects whose keys match strings inside a Markdown comment, and values explain what should be expanded at the comment site.
@@ -104,15 +90,15 @@ type Rule =
  *
  * Rule with metadata:
  * ```ts
- * { basic-meta: { required: true, content: 'content'} }
+ * { basic-meta: { order: 1, content: 'content'} }
  * ```
  *
  * Rule with dynamic content and metadata:
- * { basic-date: { required: true, content: () => `${new Date().toISOString()}` } }
+ * { basic-date: { order: 1, content: () => `${new Date().toISOString()}` } }
  */
 type Rules = SimplifyDeep<Record<string, Rule>>;
 type NormalizedRules = SimplifyDeep<Record<string, NormalizedRule>>;
-declare const rulesSchema: z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>;
+declare const rulesSchema: z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
 /**
  * Returns the rule value from a single-rule record.
  * Useful when aliasing rules or invoking them programmatically.
@@ -129,51 +115,20 @@ declare function getSoleRule<T extends NormalizedRules | Rules>(rules: T): T[key
 declare function getSoleRuleKey<T extends NormalizedRules | Rules>(rules: T): keyof T;
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat.d.ts
-type MdatOptions = {
-  addMetaComment: boolean | string;
-  closingPrefix: string;
-  keywordPrefix: string;
-  metaCommentIdentifier: string;
-  rules: Rules;
-};
-declare function mdat(tree: Root, file: VFile, options: MdatOptions): Promise<void>;
-//#endregion
-//#region src/lib/mdast-utils/mdast-util-mdat-check.d.ts
-type MdatCheckOptions = {
-  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.
- */
-declare function mdatCheck(tree: Root, file: VFile, options: MdatCheckOptions): Promise<void>;
+declare function mdat(tree: Root, file: VFile, rules: Rules): Promise<void>;
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat-clean.d.ts
-type MdatCleanOptions = {
-  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.
+ * Collapses any expanded mdat comments, effectively resetting the document to
+ * its pre-expansion state. No-op if no mdat comments are found.
  */
-declare function mdatClean(tree: Root, file: VFile, options: MdatCleanOptions): void;
+declare function mdatClean(tree: Root, file: VFile): void;
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat-expand.d.ts
-type MdatExpandOptions = {
-  addMetaComment: boolean | string;
-  closingPrefix: string;
-  keywordPrefix: string;
-  metaCommentIdentifier: string;
-  rules: Rules;
-};
-declare function mdatExpand(tree: Root, file: VFile, options: MdatExpandOptions): Promise<void>;
+/**
+ * Mdast utility to expand mdat comments in the tree.
+ */
+declare function mdatExpand(tree: Root, file: VFile, rules: Rules): Promise<void>;
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat-split.d.ts
 /**
@@ -182,21 +137,13 @@ declare function mdatExpand(tree: Root, file: VFile, options: MdatExpandOptions)
  */
 declare function mdatSplit(tree: Root, file: VFile): void;
 //#endregion
-//#region src/lib/mdat/deep-merge-defined.d.ts
-declare function deepMergeDefined<T extends Record<string, unknown>>(...objects: T[]): T;
-//#endregion
 //#region src/lib/mdat/log.d.ts
-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;
-};
+/**
+ * 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/lib/mdat/mdat-log.d.ts
 /**
@@ -220,29 +167,10 @@ declare function getMdatReports(files: VFile[]): MdatFileReport[];
 declare function reporterMdat(files: VFile[]): void;
 //#endregion
 //#region src/lib/remark-mdat.d.ts
-type Options = Partial<MdatOptions>;
-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;
-  addMetaComment?: string | boolean | undefined;
-  metaCommentIdentifier?: string | undefined;
-  rules?: Record<string, any> | undefined;
-}, {
-  closingPrefix?: string | undefined;
-  keywordPrefix?: string | undefined;
-  addMetaComment?: string | boolean | undefined;
-  metaCommentIdentifier?: string | undefined;
-  rules?: Record<string, any> | undefined;
-}>;
+type Options = Rules;
 /**
  * A remark plugin that expands HTML comments in Markdown files.
  */
 declare const remarkMdat: Plugin<[Options], Root>;
 //#endregion
-export { type MdatCheckOptions, type MdatCleanOptions, type MdatExpandOptions, type MdatFileReport, type MdatMessage, type MdatOptions, type NormalizedRule, type NormalizedRules, type Options, type Rule, type Rules, type SimplifyDeep, deepMergeDefined, remarkMdat as default, getMdatReports, getSoleRule, getSoleRuleKey, log, mdat, mdatCheck, mdatClean, mdatExpand, mdatSplit, optionsSchema, reporterMdat, rulesSchema };
+export { type MdatFileReport, type MdatMessage, type NormalizedRule, type NormalizedRules, type Options, type Rule, type RuleContext, type Rules, type SimplifyDeep, remarkMdat as default, getMdatReports, getSoleRule, getSoleRuleKey, mdat, mdatClean, mdatExpand, mdatSplit, rulesSchema as optionsSchema, rulesSchema, reporterMdat, setLogger };

package/dist/index.js

@@ -1,49 +1,31 @@
-import Table from "cli-table3";
-import picocolors from "picocolors";
 import { CONTINUE, SKIP, visit } from "unist-util-visit";
 import path from "node:path";
+import picocolors from "picocolors";
+import { createLogger, injectionHelper } from "lognow";
 import json5 from "json5";
 import { VFileMessage } from "vfile-message";
-import { z } from "zod";
+import { matter } from "gray-matter-es";
 import { remark } from "remark";
 import remarkGfm from "remark-gfm";
+import { z } from "zod";
 import { fromHtml } from "hast-util-from-html";
-import { deepmerge } from "deepmerge-ts";
+//#endregion
 //#region src/lib/mdat/log.ts
-const isNode = process?.versions?.node !== void 0;
-const log = {
-	verbose: false,
-	log(...data) {
-		if (!this.verbose) return;
-		const levelPrefix = picocolors.gray("[Log]");
-		if (isNode) console.warn(levelPrefix, ...data);
-		else console.log(levelPrefix, ...data);
-	},
-	logPrefixed(prefix, ...data) {
-		this.info(picocolors.blue(`[${prefix}]`), ...data);
-	},
-	info(...data) {
-		if (!this.verbose) return;
-		const levelPrefix = picocolors.green("[Info]");
-		if (isNode) console.warn(levelPrefix, ...data);
-		else console.info(levelPrefix, ...data);
-	},
-	infoPrefixed(prefix, ...data) {
-		this.info(picocolors.blue(`[${prefix}]`), ...data);
-	},
-	warn(...data) {
-		console.warn(picocolors.yellow("[Warning]"), ...data);
-	},
-	warnPrefixed(prefix, ...data) {
-		this.warn(picocolors.blue(`[${prefix}]`), ...data);
-	},
-	error(...data) {
-		console.error(picocolors.red("[Error]"), ...data);
-	},
-	errorPrefixed(prefix, ...data) {
-		this.error(picocolors.blue(`[${prefix}]`), ...data);
-	}
-};
+/**
+* The default logger instance for the library.
+*/
+let log = createLogger({
+	logToConsole: { showTime: false },
+	name: "remark-mdat"
+});
+/**
+* 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/lib/mdat/mdat-log.ts
 function saveLog(file, level, source, message, lineOrNode, maybeColumn) {
@@ -127,12 +109,11 @@ function highlightComments(text, level) {
 //#region src/lib/mdat/parse.ts
 /**
 * 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.
+* @returns A CommentMarkerNode or undefined if the node is not a recognized comment.
 */
-function parseCommentNode(node, parent, options) {
+function parseCommentNode(node, parent) {
 	try {
-		const result = parseComment(node.value, options);
+		const result = parseComment(node.value);
 		if (result === void 0) return;
 		return {
 			...result,
@@ -149,110 +130,111 @@ function parseCommentNode(node, parent, options) {
 }
 /**
 * 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.
+* Comments using code-style notation (`//`, `#`, `/*`) are ignored and return `undefined`.
+* @returns A CommentMarker or undefined if the node is not a recognized comment.
 */
-function parseComment(text, options) {
+function parseComment(text) {
 	if (!isComment(text)) return;
-	const { closingPrefix, keywordPrefix, metaCommentIdentifier } = options;
-	if (closingPrefix === "") throw new VFileMessage("closingPrefix must not be an empty string");
+	const closingPrefix = "/";
 	const commentHtml = text.trim();
 	const commentBody = commentHtml.replace(/^\s*<!-{2,}\s*/, "").replace(/\s*-{2,}>\s*$/, "");
-	const [rawKeyword, ...argumentParts] = commentBody.split(/(\s+|\(|\{)/);
-	const type = rawKeyword.startsWith(metaCommentIdentifier) ? "meta" : keywordPrefix !== "" && !rawKeyword.startsWith(keywordPrefix) && !rawKeyword.startsWith(`${closingPrefix}${keywordPrefix}`) ? "native" : rawKeyword.startsWith(closingPrefix) ? "close" : "open";
-	if (type === "meta") return {
-		content: trimMetaIdentifiers(commentBody, metaCommentIdentifier),
-		html: commentHtml,
-		type
-	};
-	if (type === "native") return {
-		content: commentBody,
-		html: commentHtml,
-		type
-	};
+	const parenIndex = commentBody.indexOf("(");
+	const rawKeyword = parenIndex === -1 ? commentBody.split(/\s/)[0] : commentBody.slice(0, parenIndex).trim();
+	if (rawKeyword.startsWith("//") || rawKeyword.startsWith("#") || rawKeyword.startsWith("/*")) return;
+	const type = rawKeyword.startsWith(closingPrefix) ? "close" : "open";
 	let keyword = rawKeyword;
-	if (keyword.startsWith(closingPrefix)) keyword = keyword.slice(closingPrefix.length);
-	if (keyword.startsWith(keywordPrefix)) keyword = keyword.slice(keywordPrefix.length);
-	const optionText = makeValidJson(argumentParts.join(""));
-	if (type === "open" || type === "close") {
-		let options = {};
-		try {
-			options = json5.parse(optionText);
-		} catch (error) {
-			if (error instanceof Error) throw new VFileMessage(`Failed to parse comment options "${optionText}" for keyword "${keyword}": ${error.message}`);
+	if (type === "close") keyword = keyword.slice(1);
+	let options = {};
+	if (parenIndex !== -1) {
+		const lastParen = commentBody.lastIndexOf(")");
+		if (lastParen > parenIndex) {
+			const argText = commentBody.slice(parenIndex + 1, lastParen).trim();
+			if (argText.length > 0) try {
+				options = json5.parse(argText);
+			} catch (error) {
+				if (error instanceof Error) throw new VFileMessage(`Failed to parse comment options "${argText}" for keyword "${keyword}": ${error.message}`);
+			}
 		}
-		return {
-			closingPrefix,
-			html: commentHtml,
-			keyword,
-			keywordPrefix,
-			options,
-			type
-		};
 	}
+	return {
+		html: commentHtml,
+		keyword,
+		options,
+		type
+	};
 }
 function isComment(text) {
 	const trimmed = text.trim();
 	return trimmed.startsWith("<!--") && trimmed.endsWith("-->");
 }
-function makeValidJson(text) {
-	text = text.trim();
-	text = text.startsWith("(") ? text.slice(1) : text;
-	text = text.endsWith(")") ? text.slice(0, -1) : text;
-	text = text.trim();
-	if (!text.startsWith("{") && !text.startsWith("[")) text = "{" + text;
-	if (!text.endsWith("}") && !text.endsWith("]")) text += "}";
-	return text;
-}
-function trimMetaIdentifiers(text, metaCommentIdentifier) {
-	text = text.trim();
-	text = text.startsWith(metaCommentIdentifier) ? text.slice(metaCommentIdentifier.length) : text;
-	text = text.endsWith(metaCommentIdentifier) ? text.slice(0, -metaCommentIdentifier.length) : text;
-	return text;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-clean.ts
+/**
+* Collapses any expanded mdat comments, effectively resetting the document to
+* its pre-expansion state. No-op if no mdat comments are found.
+*/
+function mdatClean(tree, file) {
+	let lastOpenMarker;
+	visit(tree, "html", (node, index, parent) => {
+		if (parent === void 0 || index === void 0) return CONTINUE;
+		const marker = parseCommentNode(node, parent);
+		if (marker === void 0) return CONTINUE;
+		if (marker.type === "open") {
+			lastOpenMarker = marker;
+			return CONTINUE;
+		}
+		if (marker.type === "close") {
+			if (lastOpenMarker === void 0) {
+				saveLog(file, "error", "clean", "Found closing marker without opening marker", node);
+				return CONTINUE;
+			}
+			if (lastOpenMarker.parent !== marker.parent) {
+				saveLog(file, "error", "clean", "Opening marker doesn't share a parent", node);
+				return CONTINUE;
+			}
+			if (lastOpenMarker.keyword !== marker.keyword) {
+				saveLog(file, "error", "clean", "Opening marker doesn't share a keyword", node);
+				return CONTINUE;
+			}
+			const openMarkerIndex = parent.children.indexOf(lastOpenMarker.node);
+			const nodesToRemove = parent.children.indexOf(marker.node) - openMarkerIndex + 1;
+			parent.children.splice(openMarkerIndex + 1, nodesToRemove - 1);
+			lastOpenMarker = void 0;
+			return [CONTINUE, index - nodesToRemove + 1];
+		}
+	});
 }
 //#endregion
 //#region src/lib/mdat/rules.ts
 function normalizeRules(rules) {
 	const normalizedRules = {};
 	for (const [keyword, rule] of Object.entries(rules)) if (typeof rule === "string") normalizedRules[keyword] = {
-		applicationOrder: 0,
 		content: async () => rule,
-		order: void 0,
-		required: false
+		order: 0
 	};
 	else if (typeof rule === "function") normalizedRules[keyword] = {
-		applicationOrder: 0,
-		content: async (options, tree) => rule(options, tree),
-		order: void 0,
-		required: false
+		content: async (options, context) => rule(options, context),
+		order: 0
 	};
 	else if (Array.isArray(rule)) normalizedRules[keyword] = {
-		applicationOrder: 0,
 		content: Object.values(normalizeRules(Object.fromEntries(rule.entries()))),
-		order: void 0,
-		required: false
+		order: 0
 	};
 	else if (typeof rule.content === "string") {
 		const ruleContent = rule.content;
 		normalizedRules[keyword] = {
-			applicationOrder: rule.applicationOrder ?? 0,
 			content: async () => ruleContent,
-			order: rule.order ?? void 0,
-			required: rule.required ?? false
+			order: rule.order ?? 0
 		};
 	} else if (Array.isArray(rule.content)) normalizedRules[keyword] = {
-		applicationOrder: rule.applicationOrder ?? 0,
 		content: Object.values(normalizeRules(Object.fromEntries(rule.content.entries()))),
-		order: rule.order ?? void 0,
-		required: rule.required ?? false
+		order: rule.order ?? 0
 	};
 	else {
 		const ruleContent = rule.content;
 		normalizedRules[keyword] = {
-			applicationOrder: rule.applicationOrder ?? 0,
-			content: async (options, tree) => ruleContent(options, tree),
-			order: rule.order ?? void 0,
-			required: rule.required ?? false
+			content: async (options, context) => ruleContent(options, context),
+			order: rule.order ?? 0
 		};
 	}
 	validateNormalizedRules(normalizedRules);
@@ -272,52 +254,42 @@ function validateNormalizedRules(rules) {
 		if (error instanceof Error) throw new TypeError(`Error validating rules: ${error.message}`);
 	}
 }
-const jsonValueSchema = z.any();
-const rootSchema = z.any();
+const functionSchema = z.custom((value) => typeof value === "function");
 const normalizedRuleSchema = z.lazy(() => z.object({
-	applicationOrder: z.number(),
-	content: z.union([z.function().args(jsonValueSchema.optional(), rootSchema.optional()).returns(z.promise(z.string())), z.array(normalizedRuleSchema)]),
-	order: z.number().optional(),
-	required: z.boolean().default(false)
+	content: z.union([functionSchema, z.array(normalizedRuleSchema)]),
+	order: z.number()
 }));
-const ruleContentFunctionSchema = z.function().args(jsonValueSchema.optional(), rootSchema.optional()).returns(z.union([z.string(), z.promise(z.string())]));
 const ruleSchema = z.lazy(() => z.union([
-	ruleContentFunctionSchema,
+	functionSchema,
 	z.array(ruleSchema),
 	z.string(),
 	z.object({
-		applicationOrder: z.number().optional(),
 		content: z.union([
-			ruleContentFunctionSchema,
+			functionSchema,
 			z.array(ruleSchema),
 			z.string()
 		]),
-		order: z.number().optional(),
-		required: z.boolean().optional()
+		order: z.number().optional()
 	})
 ]));
-const rulesSchema = z.record(ruleSchema).describe("MDAT Rules");
-const normalizedRulesSchema = z.record(normalizedRuleSchema).describe("MDAT Rules");
+const keywordSchema = z.string().check(z.refine((key) => !/^[/*#]/.test(key), { message: "Rule keywords must not start with \"/\", \"*\", or \"#\" — these prefixes are reserved for comment syntax" }));
+const rulesSchema = z.record(keywordSchema, ruleSchema).describe("MDAT Rules");
+const normalizedRulesSchema = z.record(keywordSchema, normalizedRuleSchema).describe("MDAT Rules");
 /**
-* Compound rule helpers, used in both "expand" and "check" utilities
+* Compound rule helpers for expanding rule content.
 */
-async function getRuleContent(rule, options, tree, check = false) {
+async function getRuleContent(rule, options, context) {
 	if (Array.isArray(rule.content)) {
 		const subruleContent = [];
 		for (const [index, subrule] of rule.content.entries()) {
 			const subruleOptions = Array.isArray(options) ? options.at(index) : void 0;
-			try {
-				subruleContent.push(await getRuleContent(subrule, subruleOptions ?? {}, tree));
-			} catch (error) {
-				if (check) throw error;
-			}
+			subruleContent.push(await getRuleContent(subrule, subruleOptions ?? {}, context));
 		}
 		return subruleContent.join("\n\n");
 	}
 	try {
-		return await rule.content(options, tree);
+		return await rule.content(options, context);
 	} catch (error) {
-		if (check) throw error;
 		throw new Error("Failed to expand content", { cause: error });
 	}
 }
@@ -357,209 +329,41 @@ function getSoleRecord(record) {
 	return recordValues[0];
 }
 //#endregion
-//#region src/lib/mdast-utils/mdast-util-mdat-check.ts
+//#region src/lib/mdast-utils/mdast-util-mdat-expand.ts
 /**
-* Mdast utility function to check mdat source document, and output.
+* Mdast utility to expand mdat comments in the tree.
 */
-async function mdatCheck(tree, file, options) {
-	const { closingPrefix, keywordPrefix, metaCommentIdentifier, paranoid, rules: rawRules } = options;
-	validateRules(rawRules);
-	const rules = normalizeRules(rawRules);
+async function mdatExpand(tree, file, rules) {
+	validateRules(rules);
+	const normalizedRules = normalizeRules(rules);
+	const frontmatter = (() => {
+		if (typeof file.value !== "string") return;
+		const { data } = matter(file.value);
+		return Object.keys(data).length > 0 ? data : void 0;
+	})();
+	const context = {
+		filePath: file.history.length > 0 ? file.path : void 0,
+		frontmatter,
+		tree
+	};
 	const commentMarkers = [];
 	visit(tree, "html", (node, index, parent) => {
 		if (parent === void 0 || index === void 0) return CONTINUE;
-		const commentMarker = parseCommentNode(node, parent, {
-			closingPrefix,
-			keywordPrefix,
-			metaCommentIdentifier
-		});
-		if (commentMarker !== void 0) {
-			const rule = commentMarker.type === "open" || commentMarker.type === "close" ? rules[commentMarker.keyword] : void 0;
-			commentMarkers.push({
-				...commentMarker,
-				rule
-			});
-		}
-	});
-	checkMissingRequiredComments(file, commentMarkers, rules, rawRules);
-	checkCommentOrder(file, commentMarkers);
-	checkMetaCommentPresence(file, commentMarkers, options);
-	await checkRulesReturnedContent(file, commentMarkers, tree);
-	if (paranoid) checkMissingOptionalComments(file, commentMarkers, rules, rawRules);
-	checkMissingRules(file, commentMarkers);
-	checkMissingPrefix(file, commentMarkers, rules, options);
-}
-/**
-* Check that all the rules are working by getting their content
-*/
-async function checkRulesReturnedContent(file, comments, tree) {
-	for (const comment of comments) if (comment.type === "open" && comment.rule !== void 0) try {
-		if ((await getRuleContent(comment.rule, comment.options, tree, true)).trim() === "") saveLog(file, comment.rule.required ? "error" : "warn", "check", `${comment.html} returned an empty string.`, comment.node);
-	} catch (error) {
-		if (error instanceof Error) saveLog(file, comment.rule.required ? "error" : "warn", "check", `Could not get content for ${comment.html}. ${error.message}`, comment.node);
-	}
-}
-/**
-* Check for comments with missing prefix (have an un-prefixed comment that matches a rule)
-*/
-function checkMissingPrefix(file, comments, rules, options) {
-	if (options.keywordPrefix === "") return;
-	const ruleKeywords = Object.keys(rules);
-	for (const comment of comments) if (comment.type === "native" && ruleKeywords.includes(comment.content)) saveLog(file, "warn", "check", `Missing prefix: ${comment.html}`, comment.node);
-}
-/**
-* Check for missing "optional" rules. These are instances where we have the comment, but not the rule
-*/
-function checkMissingRules(file, comments) {
-	for (const comment of comments) if (comment.type === "open" && comment.rule === void 0) saveLog(file, "warn", "check", `Missing rule for: ${comment.html}`, comment.node);
-}
-/**
-* Check for missing optional comments. We have defined the rule, but not written a matching comment.
-*/
-function checkMissingOptionalComments(file, comments, rules, rawRules) {
-	for (const [keyword, rule] of Object.entries(rules)) if (!rule.required && !comments.some((comment) => comment.type === "open" && comment.keyword === keyword) && !satisfiedByCompoundRule(keyword, rawRules)) saveLog(file, "warn", "check", `Missing optional: <!-- ${keyword} -->`);
-}
-/**
-* Check for missing required comments.
-* The rule set includes a rule with `required: true`, but no matching comment was found in the document.
-*/
-function checkMissingRequiredComments(file, comments, rules, rawRules) {
-	for (const [keyword, rule] of Object.entries(rules)) if (rule.required && !comments.some((comment) => comment.type === "open" && comment.keyword === keyword) && !satisfiedByCompoundRule(keyword, rawRules)) saveLog(file, "error", "check", `Missing required: <!-- ${keyword} -->`);
-}
-/**
-* Extract the content value from a raw rule, unwrapping object-form rules.
-*/
-function getRawRuleContent(rule) {
-	if (typeof rule === "object" && !Array.isArray(rule)) return rule.content;
-	return rule;
-}
-/**
-* Get the sub-rule array from a compound rule, if it is one.
-*/
-function getCompoundSubRules(rule) {
-	if (Array.isArray(rule)) return rule;
-	if (typeof rule === "object" && !Array.isArray(rule) && Array.isArray(rule.content)) return rule.content;
-}
-/**
-* Helper to see if a rule keyword is covered by a compound rule in the rule set.
-* Checks whether any compound rule contains the same raw content value (by reference)
-* as the rule for the given keyword. This works when the sub-rule was imported
-* directly into the compound rule definition.
-*/
-function satisfiedByCompoundRule(keyword, rawRules) {
-	const rawRule = rawRules[keyword];
-	const ruleContent = getRawRuleContent(rawRule);
-	for (const otherRule of Object.values(rawRules)) {
-		const subRules = getCompoundSubRules(otherRule);
-		if (subRules === void 0) continue;
-		if (subRules.some((subRule) => getRawRuleContent(subRule) === ruleContent)) return true;
-	}
-	return false;
-}
-/**
-* Check if comment order in document is different from order specified in the rules
-*/
-function checkCommentOrder(file, comments) {
-	const commentsInOrderOfAppearance = comments.filter((commentMarker) => commentMarker.type === "open" && commentMarker.rule?.order !== void 0);
-	const commentsInCorrectOrder = [...commentsInOrderOfAppearance].toSorted((a, b) => {
-		const orderA = a.rule?.order;
-		const orderB = b.rule?.order;
-		if (orderA === void 0 || orderB === void 0) throw new Error("Unexpected undefined rule order");
-		return orderA - orderB;
-	});
-	const currentOrderList = commentOrderList(commentsInOrderOfAppearance);
-	const correctOrderList = commentOrderList(commentsInCorrectOrder);
-	const table = new Table({
-		head: [picocolors.red(picocolors.bold("Current Order")), picocolors.green(picocolors.bold("Required Order"))],
-		style: { compact: true }
-	});
-	if (currentOrderList.join(",") !== correctOrderList.join(",")) {
-		table.push(...currentOrderList.map((currentOrder, index) => [currentOrder, correctOrderList[index]]));
-		saveLog(file, "error", "check", `Out of order:\n${table.toString()}`);
-	}
-}
-/**
-* Check that meta presence / absence comment matches options.
-*/
-function checkMetaCommentPresence(file, comments, options) {
-	const { addMetaComment } = options;
-	const metaCommentCount = comments.filter((comment) => comment.type === "meta").length;
-	const shouldHaveMetaComment = typeof addMetaComment === "string" ? true : addMetaComment;
-	if (shouldHaveMetaComment && metaCommentCount !== 1) saveLog(file, "error", "check", `Missing meta comment`);
-	if (!shouldHaveMetaComment && metaCommentCount !== 0) saveLog(file, "error", "check", `Unexpected meta comment`);
-	if (metaCommentCount > 1) saveLog(file, "error", "check", `Multiple meta comments`);
-}
-function commentOrderList(comments) {
-	return comments.map((comment, index) => {
-		if (comment.type === "open" || comment.type === "close") return `${index + 1}. ${comment.html}`;
-		throw new Error("Unexpected comment type");
-	});
-}
-//#endregion
-//#region src/lib/mdast-utils/mdast-util-mdat-clean.ts
-/**
-* 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.
-*/
-function mdatClean(tree, file, options) {
-	let lastOpenMarker;
-	visit(tree, "html", (node, index, parent) => {
-		if (parent === void 0 || index === void 0) return CONTINUE;
-		const marker = parseCommentNode(node, parent, options);
-		if (marker === void 0 || marker.type === "native") return CONTINUE;
-		if (marker.type === "meta") {
-			parent.children.splice(index, 1);
-			return [CONTINUE, index];
-		}
-		if (marker.type === "open") {
-			lastOpenMarker = marker;
+		const commentMarker = parseCommentNode(node, parent);
+		if (commentMarker?.type !== "open") return CONTINUE;
+		if (normalizedRules[commentMarker.keyword] === void 0) {
+			saveLog(file, "warn", "expand", `Missing rule for: ${commentMarker.html}`, node);
 			return CONTINUE;
 		}
-		if (marker.type === "close") {
-			if (lastOpenMarker === void 0) {
-				saveLog(file, "error", "clean", "Found closing marker without opening marker", node);
-				return CONTINUE;
-			}
-			if (lastOpenMarker.parent !== marker.parent) {
-				saveLog(file, "error", "clean", "Opening marker doesn't share a parent", node);
-				return CONTINUE;
-			}
-			if (lastOpenMarker.keyword !== marker.keyword) {
-				saveLog(file, "error", "clean", "Opening marker doesn't share a keyword", node);
-				return CONTINUE;
-			}
-			const openMarkerIndex = parent.children.indexOf(lastOpenMarker.node);
-			const nodesToRemove = parent.children.indexOf(marker.node) - openMarkerIndex + 1;
-			parent.children.splice(openMarkerIndex + 1, nodesToRemove - 1);
-			lastOpenMarker = void 0;
-			return [CONTINUE, index - nodesToRemove + 1];
-		}
+		commentMarkers.push(commentMarker);
 	});
-}
-//#endregion
-//#region src/lib/mdast-utils/mdast-util-mdat-expand.ts
-async function mdatExpand(tree, file, options) {
-	const { addMetaComment, closingPrefix, keywordPrefix, metaCommentIdentifier, rules: rawRules } = options;
-	validateRules(rawRules);
-	const rules = normalizeRules(rawRules);
-	const commentMarkers = [];
-	visit(tree, "html", (node, index, parent) => {
-		if (parent === void 0 || index === void 0) return CONTINUE;
-		const commentMarker = parseCommentNode(node, parent, {
-			closingPrefix,
-			keywordPrefix,
-			metaCommentIdentifier
-		});
-		if (commentMarker?.type === "open" && rules[commentMarker.keyword] !== void 0) commentMarkers.push(commentMarker);
-	});
-	commentMarkers.sort((a, b) => rules[a.keyword].applicationOrder - rules[b.keyword].applicationOrder);
+	commentMarkers.sort((a, b) => normalizedRules[a.keyword].order - normalizedRules[b.keyword].order);
 	for (const comment of commentMarkers) {
-		const { closingPrefix, html, keyword, keywordPrefix, node, options, parent } = comment;
-		const rule = rules[keyword];
+		const { html, keyword, node, options, parent } = comment;
+		const rule = normalizedRules[keyword];
 		let newMarkdownString = "";
 		try {
-			newMarkdownString = await getRuleContent(rule, options, tree);
+			newMarkdownString = await getRuleContent(rule, options, context);
 			if (newMarkdownString.trim() === "") saveLog(file, "error", "expand", `Got empty content when expanding ${html}`, node);
 		} catch (error) {
 			if (error instanceof Error) {
@@ -571,19 +375,12 @@ async function mdatExpand(tree, file, options) {
 		const newNodes = remark().use(remarkGfm).parse(newMarkdownString).children;
 		const closingNode = {
 			type: "html",
-			value: `<!-- ${closingPrefix}${keywordPrefix}${keyword} -->`
+			value: `<!-- /${keyword} -->`
 		};
 		const openingCommentIndex = parent.children.indexOf(node);
 		parent.children.splice(openingCommentIndex + 1, 0, ...newNodes, closingNode);
 		saveLog(file, "info", "expand", `Expanded: ${html}`, node);
 	}
-	if (addMetaComment) {
-		const metaComment = {
-			type: "html",
-			value: `<!--${metaCommentIdentifier} ${typeof addMetaComment === "string" ? addMetaComment : "Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten."} ${metaCommentIdentifier}-->`
-		};
-		tree.children.unshift(metaComment);
-	}
 }
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat-split.ts
@@ -649,66 +446,25 @@ function getOriginalMarkup(mdastNode, hastNode) {
 }
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat.ts
-async function mdat(tree, file, options) {
-	const { addMetaComment, closingPrefix, keywordPrefix, metaCommentIdentifier, rules } = options;
+async function mdat(tree, file, rules) {
 	mdatSplit(tree, file);
-	mdatClean(tree, file, {
-		closingPrefix,
-		keywordPrefix,
-		metaCommentIdentifier
-	});
-	await mdatExpand(tree, file, {
-		addMetaComment,
-		closingPrefix,
-		keywordPrefix,
-		metaCommentIdentifier,
-		rules
-	});
-	await mdatCheck(tree, file, {
-		addMetaComment,
-		closingPrefix,
-		keywordPrefix,
-		metaCommentIdentifier,
-		paranoid: false,
-		rules
-	});
-}
-//#endregion
-//#region src/lib/mdat/deep-merge-defined.ts
-function stripUndefinedDeep(object) {
-	if (Array.isArray(object)) return object.map((v) => v && typeof v === "object" ? stripUndefinedDeep(v) : v).filter((v) => v !== void 0);
-	return Object.entries(object).map(([k, v]) => [k, v && typeof v === "object" ? stripUndefinedDeep(v) : v]).reduce((acc, [k, v]) => v === void 0 ? acc : {
-		...acc,
-		[k]: v
-	}, {});
-}
-function deepMergeDefined(...objects) {
-	return deepmerge(...objects.map((v, i) => i === 0 ? v : stripUndefinedDeep(v)));
+	mdatClean(tree, file);
+	await mdatExpand(tree, file, rules);
 }
 //#endregion
 //#region src/lib/remark-mdat.ts
-const defaultOptions = {
-	addMetaComment: false,
-	closingPrefix: "/",
-	keywordPrefix: "",
-	metaCommentIdentifier: "+",
-	rules: { mdat: `Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat).` }
-};
-const optionsSchema = z.object({
-	addMetaComment: z.union([z.boolean(), z.string()]).optional(),
-	closingPrefix: z.string().min(1).optional(),
-	keywordPrefix: z.string().optional(),
-	metaCommentIdentifier: z.string().optional(),
-	rules: rulesSchema.optional()
-}).describe("MDAT Options");
+const defaultRules = { mdat: `Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat).` };
 /**
 * A remark plugin that expands HTML comments in Markdown files.
 */
-const remarkMdat = function(options) {
-	const resolvedOptions = deepMergeDefined(defaultOptions, options);
+const remarkMdat = function(rules) {
+	const resolvedRules = {
+		...defaultRules,
+		...rules
+	};
 	return async function(tree, file) {
-		await mdat(tree, file, resolvedOptions);
+		await mdat(tree, file, resolvedRules);
 	};
 };
 //#endregion
-export { deepMergeDefined, remarkMdat as default, getMdatReports, getSoleRule, getSoleRuleKey, log, mdat, mdatCheck, mdatClean, mdatExpand, mdatSplit, optionsSchema, reporterMdat, rulesSchema };
+export { remarkMdat as default, getMdatReports, getSoleRule, getSoleRuleKey, mdat, mdatClean, mdatExpand, mdatSplit, rulesSchema as optionsSchema, rulesSchema, reporterMdat, setLogger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remark-mdat",
-  "version": "1.2.5",
+  "version": "2.0.0-preview.2",
   "description": "A remark plugin implementing the Markdown Autophagic Template (MDAT) system.",
   "keywords": [
     "mdat",
@@ -43,10 +43,10 @@
   "dependencies": {
     "@types/mdast": "^4.0.4",
     "@types/unist": "^3.0.3",
-    "cli-table3": "^0.6.5",
-    "deepmerge-ts": "^7.1.5",
+    "gray-matter-es": "^0.2.1",
     "hast-util-from-html": "^2.0.3",
     "json5": "^2.2.3",
+    "lognow": "^0.5.2",
     "picocolors": "^1.1.1",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
@@ -55,7 +55,7 @@
     "unist-util-visit": "^5.1.0",
     "vfile": "^6.0.3",
     "vfile-message": "^4.0.3",
-    "zod": "^3.25.76"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.2",
@@ -68,7 +68,7 @@
     "vitest": "^4.1.1"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.19.6"
   },
   "devEngines": {
     "runtime": {
@@ -83,6 +83,7 @@
     "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",
+    "release-preview": "bumpp --preid preview --commit 'Release: %s' && pnpm run build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish --tag preview",
     "test": "vitest run"
   }
 }

package/readme.md

@@ -1,5 +1,3 @@
-<!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->
-
 <!-- title -->
 
 # remark-mdat
@@ -44,7 +42,6 @@
   - [Examples](#examples)
 - [Utilities](#utilities)
 - [Implementation notes](#implementation-notes)
-- [The future](#the-future)
 - [Maintainers](#maintainers)
 - [Acknowledgments](#acknowledgments)
 - [Contributing](#contributing)
@@ -105,19 +102,9 @@ remark().use(remarkMdat)
 
 #### Options
 
-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. `<!--+ ... +-->`.                                                                   |
+The plugin accepts an optional `Rules` object as its options. This is a `Record<string, Rule>` where each key is a keyword matching an HTML comment in the Markdown file (e.g. `title` matches `<!-- title -->`).
 
-#### 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 -->`).
+HTML comments using code-style notation (`<!-- // ... -->`, `<!-- # ... -->`, `<!-- /* ... */ -->`) are ignored and will not be treated as mdat keywords. Rule keywords cannot start with `/`, `*`, or `#`.
 
 A `Rule` value can take several forms:
 
@@ -125,25 +112,81 @@ A `Rule` value can take several forms:
 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(),
+
+  // Function with arguments: receives parsed options from the comment
+  personalGreeting: (options) => `Hello, ${options.name}!`,
+
   // Object: rule with validation metadata
   title: {
-    applicationOrder: 0, // Processing priority (default: 0)
+    order: 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),
+
+  // Array: compound rule combining multiple sub-rules
+  header: ['# My Project', () => getDescription()],
+
+  // Function with context: access the document tree, frontmatter, and file path
+  toc: (_options, context) => generateTocFromTree(context.tree),
 }
 ```
 
+#### Rule context
+
+Rule content functions receive a `RuleContext` object as their second argument, providing access to the document being processed:
+
+```ts
+type RuleContext = {
+  /** File path of the source document, if known. */
+  filePath: string | undefined
+  /** Parsed YAML frontmatter from the document, if present. */
+  frontmatter: Record<string, unknown> | undefined
+  /** The full mdast AST of the document. Do not mutate. */
+  tree: Root
+}
+```
+
+Frontmatter is automatically extracted from the raw Markdown source using [gray-matter-es](https://github.com/ryoppippi/gray-matter-es), so it works regardless of whether `remark-frontmatter` is in your pipeline. If the document has no frontmatter block, `context.frontmatter` is `undefined`.
+
+```ts
+const rules: Rules = {
+  // Access frontmatter values
+  title: (_options, context) => `# ${context.frontmatter?.title ?? 'Untitled'}`,
+
+  // Use the file path
+  source: (_options, context) => `Source: ${context.filePath ?? 'unknown'}`,
+
+  // Traverse the AST
+  toc: (_options, context) => generateTocFromTree(context.tree),
+}
+```
+
+#### Passing arguments to rules
+
+Arguments are passed using function-call syntax: `<!-- keyword(...) -->`. The value inside the parentheses is parsed as [JSON5](https://json5.org/), which means unquoted keys and single quotes are allowed.
+
+```md
+Options as JSON5 (unquoted keys, single quotes):
+
+<!-- greeting({name: 'Alice', shout: true}) -->
+
+Options as strict JSON:
+
+<!-- greeting({"name": "Alice", "shout": true}) -->
+
+Single primitive value:
+
+<!-- repeat(3) -->
+```
+
+Any JSON5 value is supported: objects, arrays, strings, numbers, and booleans. Comments without parentheses receive an empty object `{}` as their options.
+
+For simplicity's sake, only a single argument position is supported. If you need pass multiple arguments, wrap them in an object.
+
+Prefer object arguments for all but the most contextually clear argument values.
+
 ### Examples
 
 #### Basic
@@ -167,7 +210,7 @@ console.log(markdownOutput.toString())
 // <!-- /mdat -->
 ```
 
-#### With options
+#### With rules
 
 If you wanted to replace `<!-- time -->` comments in your Markdown file with the current time, you could pass in a rule:
 
@@ -176,15 +219,15 @@ import type { Rules } from 'remark-mdat'
 import { remark } from 'remark'
 import remarkMdat from 'remark-mdat'
 
-// Create the rule
+// Create the rules
 const rules: Rules = {
   time: () => new Date().toDateString(),
 }
 
 const markdownInput = '<!-- time -->'
 
-// Pass the time rule to remarkMdat
-const markdownOutput = await remark().use(remarkMdat, { rules }).process(markdownInput)
+// Pass the rules to remarkMdat
+const markdownOutput = await remark().use(remarkMdat, rules).process(markdownInput)
 
 console.log(markdownOutput.toString())
 
@@ -202,15 +245,15 @@ See the [`mdat`](https://github.com/kitschpatrol/mdat) package for a higher-leve
 
 The plugin bundles a number of [mdast](https://github.com/syntax-tree/mdast) utilities designed to operate directly on syntax trees. These are exported to support customized Unified.js processors and enforce modularity and separation of concerns in mdat's internal implementation, but you do not need to use them directly — all functionality is encapsulated in the single `remarkMdat` plugin export.
 
-The remark-mdat plugin chains these utilities together to accommodate the typical use case of end-to-end expansion and validation of mdat comments. For now, the individual utility transformers are not published individually to NPM, and are instead bundled with `remark-mdat`.
+The remark-mdat plugin chains these utilities together to accommodate the typical use case of end-to-end expansion of mdat comments. For now, the individual utility transformers are not published individually to NPM, and are instead bundled with `remark-mdat`.
 
-- [**`mdast-util-mdat`**](./src/lib/mdast-utils/mdast-util-mdat.ts)
+Errors and warnings are reported inline during expansion via [VFile messages](https://github.com/vfile/vfile-message), following remark ecosystem conventions. Use `reporterMdat` to extract and format these messages for console output.
 
-  Composite transformer function performing end-to-end mdat comment expansion and validation on Markdown ASTs by chaining the other utility functions described below.
+- [**`mdast-util-mdat`**](./src/lib/mdast-utils/mdast-util-mdat.ts)
 
-  _Exported as `mdat(tree: Root, file: VFile, options: MdatOptions): Promise<void>`_
+  Composite transformer function performing end-to-end mdat comment expansion on Markdown ASTs by chaining the other utility functions described below.
 
-  `MdatOptions` includes `addMetaComment`, `closingPrefix`, `keywordPrefix`, `metaCommentIdentifier`, and `rules` (all required, unlike the plugin's `Options` where they are optional with defaults).
+  _Exported as `mdat(tree: Root, file: VFile, rules: Rules): Promise<void>`_
 
   Utilities wrapped by `mdast-util-mdat`:
   - [**`mdast-util-mdat-split`**](./src/lib/mdast-utils/mdast-util-mdat-split.ts)
@@ -221,37 +264,21 @@ The remark-mdat plugin chains these utilities together to accommodate the typica
 
   - [**`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(tree: Root, file: VFile, options: MdatCleanOptions): void`_
+    Transformer function that resets all mdat comment expansions in a file, collapsing expanded comments back into single-line placeholders.
 
-    `MdatCleanOptions` includes `closingPrefix`, `keywordPrefix`, and `metaCommentIdentifier`.
+    _Exported as `mdatClean(tree: Root, file: VFile): void`_
 
   - [**`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 options argument.
-
-    _Exported as `mdatExpand(tree: Root, file: VFile, options: MdatExpandOptions): Promise<void>`_
+    Transformer function that expands mdat comments (e.g. `<!-- title -->`) in a Markdown file according to the provided rules. Reports errors for rules that throw or return empty content, and warnings for comments with no matching rule.
 
-    `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 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>`_
-
-    `MdatCheckOptions` extends `MdatExpandOptions` with a `paranoid` boolean for extra validation checks.
-
-    See `reporterMdat` to extract, format, and log results from VFile messages written by `mdatCheck`.
+    _Exported as `mdatExpand(tree: Root, file: VFile, rules: Rules): Promise<void>`_
 
 ## Implementation notes
 
 This project was split from a monorepo containing both `mdat` and `remark-mdat` into separate repos in July 2024.
 
-## The future
-
-- Consider making remark a peer dependency? Though perhaps not [strip-markdown/issues/24](https://github.com/remarkjs/strip-markdown/issues/24)...
+Remark is not a peer dependency on account of this discussion: [strip-markdown/issues/24](https://github.com/remarkjs/strip-markdown/issues/24)
 
 ## Maintainers