remark-mdat 2.0.2 → 2.2.0

package/dist/index.d.ts

@@ -6,7 +6,10 @@ import { JsonValue, MergeDeep, Simplify } from "type-fest";
 import { Plugin } from "unified";
 
 //#region src/lib/mdat/rules.d.ts
-/** Recursively simplifies a type for cleaner IDE hover display. Approximation of type-fest's internal `SimplifyDeep`. */
+/**
+ * Recursively simplifies a type for cleaner IDE hover display. Approximation of
+ * type-fest's internal `SimplifyDeep`.
+ */
 type SimplifyDeep<T> = Simplify<MergeDeep<T, T>>;
 /**
  * Context passed to rule content functions during expansion.
@@ -17,19 +20,19 @@ type RuleContext = {
   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
+ * 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 function that generates the expanded Markdown string.
-   * For 'compound' rules, this can be an array of rules (without keywords).
+   * The function that generates the expanded Markdown string. For 'compound'
+   * rules, this can be an array of rules (without keywords).
    */
   content: ((options: JsonValue, context: RuleContext) => Promise<string>) | 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
+   * 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.
    */
   order: number;
@@ -40,9 +43,9 @@ type Rule =
  */
 ((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
- * of a rule object with validation metadata.
+ * 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[]
 /**
@@ -54,18 +57,22 @@ type Rule =
  */
 | {
   /**
-   * 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.
+   * 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 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.
+   *
+   * @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 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, context: RuleContext) => Promise<string> | string) | Rule[] | string;
   /**
@@ -75,27 +82,30 @@ type Rule =
   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.
+ * 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.
  *
- * 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' }
- * ```
+ * 	Most basic rule:
+ * 	```ts
+ * 	{ basic: 'content' }
+ * 	```
  *
- * Rule with dynamic content:
- * ```ts
- * { basic: () => `${new Date().toISOString()}` }
- * ```
+ * 	Rule with dynamic content:
+ * 	```ts
+ * 	{ basic: () => `${new Date().toISOString()}` }
+ * 	```
  *
- * Rule with metadata:
- * ```ts
- * { basic-meta: { order: 1, content: 'content'} }
- * ```
+ * 	Rule with metadata:
+ * 	```ts
+ * 	{ basic-meta: { order: 1, content: 'content'} }
+ * 	```
  *
- * Rule with dynamic content and metadata:
- * { basic-date: { order: 1, content: () => `${new Date().toISOString()}` } }
+ * 	Rule with dynamic content and metadata:
+ * 	{ basic-date: { order: 1, content: () => `${new Date().toISOString()}` } }
  */
 type Rules = SimplifyDeep<Record<string, Rule>>;
 /** A record mapping comment keywords to {@link NormalizedRule} objects. */
@@ -103,30 +113,61 @@ type NormalizedRules = SimplifyDeep<Record<string, NormalizedRule>>;
 /** Zod schema for validating {@link Rules} records. */
 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.
+ * 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.
  */
 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.
+ * 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.
  */
 declare function getSoleRuleKey<T extends NormalizedRules | Rules>(rules: T): keyof T;
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat.d.ts
-/** Mdast utility that splits, cleans, and expands all mdat comments in the tree. */
+/**
+ * Mdast utility that splits, collapses, and then re-expands all mdat comments
+ * in the tree.
+ */
 declare function mdat(tree: Root, file: VFile, rules: NormalizedRules | Rules): Promise<void>;
 //#endregion
-//#region src/lib/mdast-utils/mdast-util-mdat-clean.d.ts
+//#region src/lib/mdast-utils/mdast-util-mdat-collapse.d.ts
 /**
  * Collapses any expanded mdat comments, effectively resetting the document to
- * its pre-expansion state. No-op if no mdat comments are found.
+ * its pre-expansion state, preserving the original comments. No-op if no mdat
+ * comments are found.
+ */
+declare function mdatCollapse(tree: Root, file: VFile): void;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-clean.d.ts
+/**
+ * @deprecated Use {@link mdatCollapse} instead. This alias will be removed in a
+ *   future major version.
  */
-declare function mdatClean(tree: Root, file: VFile): void;
+declare const mdatClean: typeof mdatCollapse;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-diff.d.ts
+/** Per-tag comparison result from {@link mdatDiff}. */
+type MdatDiffResult = {
+  /** The keyword for this tag. */keyword: string; /** 1-based line number of the opening comment in the expanded document. */
+  line: number; /** Comparison status. */
+  status: 'added' | 'missing' | 'ok' | 'stale' | 'unexpanded';
+};
+/**
+ * Compare original and expanded documents per-tag. Walks both ASTs to extract
+ * content between open/close comment markers, then compares per-tag.
+ *
+ * Callers should run {@link mdatSplit} on both trees before calling this
+ * function to ensure multi-comment nodes are split into individual nodes.
+ *
+ * Adds diagnostic messages to `expandedFile` via the VFile message pipeline.
+ *
+ * @returns Per-tag comparison results.
+ */
+declare function mdatDiff(originalTree: Root, originalFile: VFile, expandedTree: Root, expandedFile: VFile): MdatDiffResult[];
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat-expand.d.ts
 /**
@@ -136,11 +177,20 @@ declare function mdatExpand(tree: Root, file: VFile, rules: NormalizedRules | Ru
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat-split.d.ts
 /**
- * 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.
+ * 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.
  */
 declare function mdatSplit(tree: Root, file: VFile): void;
 //#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-strip.d.ts
+/**
+ * Strips all mdat comment nodes (both opening and closing) from the tree,
+ * preserving any content between them. Code-style comments (`//`, `#`, `/*`)
+ * are left untouched.
+ */
+declare function mdatStrip(tree: Root, _file: VFile): void;
+//#endregion
 //#region src/lib/mdat/log.d.ts
 /**
  * Set the logger instance for the module.
@@ -185,4 +235,4 @@ declare const optionsSchema: z.ZodObject<{
  */
 declare const remarkMdat: Plugin<[Options?], Root>;
 //#endregion
-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, optionsSchema, reporterMdat, rulesSchema, setLogger };
+export { type MdatDiffResult, 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, mdatCollapse, mdatDiff, mdatExpand, mdatSplit, mdatStrip, optionsSchema, reporterMdat, rulesSchema, setLogger };

package/dist/index.js

@@ -111,7 +111,9 @@ function highlightComments(text, level) {
 //#region src/lib/mdat/parse.ts
 /**
 * Parse an Mdast HTML comment node into structured data.
-* @returns A CommentMarkerNode or undefined if the node is not a recognized comment.
+*
+* @returns A CommentMarkerNode or undefined if the node is not a recognized
+*   comment.
 */
 function parseCommentNode(node, parent) {
 	try {
@@ -126,17 +128,20 @@ function parseCommentNode(node, parent) {
 		if (error instanceof VFileMessage) {
 			error.line = node.position?.start.line;
 			throw error;
-		} else if (error instanceof Error) throw new VFileMessage(error.message, node);
-		else throw new VFileMessage("Unknown error", node);
+		}
+		if (error instanceof Error) throw new VFileMessage(error.message, node);
+		throw new VFileMessage("Unknown error", node);
 	}
 }
 const HTML_COMMENT_OPEN_REGEX = /^\s*<!-{2,}\s*/;
 const HTML_COMMENT_CLOSE_REGEX = /\s*-{2,}>\s*$/;
 const WHITESPACE_REGEX = /\s/;
 /**
-* Parse any comment string into structured data.
-* Comments using code-style notation (`//`, `#`, `/*`) are ignored and return `undefined`.
-* @returns A CommentMarker or undefined if the node is not a recognized comment.
+* Parse any comment string into structured data. 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) {
 	if (!isComment(text)) return;
@@ -173,12 +178,13 @@ function isComment(text) {
 	return trimmed.startsWith("<!--") && trimmed.endsWith("-->");
 }
 //#endregion
-//#region src/lib/mdast-utils/mdast-util-mdat-clean.ts
+//#region src/lib/mdast-utils/mdast-util-mdat-collapse.ts
 /**
 * Collapses any expanded mdat comments, effectively resetting the document to
-* its pre-expansion state. No-op if no mdat comments are found.
+* its pre-expansion state, preserving the original comments. No-op if no mdat
+* comments are found.
 */
-function mdatClean(tree, file) {
+function mdatCollapse(tree, file) {
 	let lastOpenMarker;
 	visit(tree, "html", (node, index, parent) => {
 		if (parent === void 0 || index === void 0) return CONTINUE;
@@ -188,25 +194,23 @@ function mdatClean(tree, file) {
 			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];
+		if (lastOpenMarker === void 0) {
+			saveLog(file, "error", "collapse", "Found closing marker without opening marker", node);
+			return CONTINUE;
 		}
+		if (lastOpenMarker.parent !== marker.parent) {
+			saveLog(file, "error", "collapse", "Opening marker doesn't share a parent", node);
+			return CONTINUE;
+		}
+		if (lastOpenMarker.keyword !== marker.keyword) {
+			saveLog(file, "error", "collapse", "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
@@ -217,7 +221,10 @@ const NORMALIZED = Symbol("normalized");
 function isNormalized(rules) {
 	return NORMALIZED in rules;
 }
-/** Converts flexible {@link Rules} into strict {@link NormalizedRules} for internal processing. */
+/**
+* Converts flexible {@link Rules} into strict {@link NormalizedRules} for
+* internal processing.
+*/
 function normalizeRules(rules) {
 	validateRules(rules);
 	const normalizedRules = {};
@@ -280,9 +287,9 @@ const keywordSchema = z.string().check(z.refine((key) => !COMMENT_PREFIX_REGEX.t
 /** Zod schema for validating {@link Rules} records. */
 const rulesSchema = z.record(keywordSchema, ruleSchema).describe("MDAT Rules");
 /**
-* Expand rule content. For compound rules (content arrays), individual
-* sub-rule failures are reported via `onWarning` and skipped. The entire
-* expansion only fails if every sub-rule fails.
+* Expand rule content. For compound rules (content arrays), individual sub-rule
+* failures are reported via `onWarning` and skipped. The entire expansion only
+* fails if every sub-rule fails.
 */
 async function getRuleContent(rule, options, context, onWarning) {
 	if (Array.isArray(rule.content)) {
@@ -308,8 +315,8 @@ async function getRuleContent(rule, options, context, onWarning) {
 	}
 }
 /**
-* Returns the rule value from a single-rule record.
-* Useful when aliasing rules or invoking them programmatically.
+* 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.
 */
@@ -317,8 +324,8 @@ function getSoleRule(rules) {
 	return getSoleRecord(rules);
 }
 /**
-* Returns the rule key from a single-rule record.
-* Useful for comment placeholder validation.
+* 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.
 */
@@ -330,9 +337,11 @@ function getSoleRuleKey(rules) {
 /**
 * Get the sole entry in a record.
 *
-* Useful for working with Rules records
-* that are only supposed to contain a single rule.
+* Useful for working with Rules records that are only supposed to contain a
+* single rule.
+*
 * @param record The record to get the sole entry from
+*
 * @returns The value of the sole entry in the record
 * @throws {Error} If there are no entries or more than one entry
 */
@@ -401,8 +410,9 @@ async function mdatExpand(tree, file, rules) {
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat-split.ts
 /**
-* 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.
+* 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.
 */
 function mdatSplit(tree, file) {
 	visit(tree, "html", (node, index, parent) => {
@@ -419,7 +429,10 @@ function mdatSplit(tree, file) {
 		}
 	});
 }
-/** Splits a single mdast HTML node containing multiple comments into individual HTML and text nodes. Exported for testing. */
+/**
+* Splits a single mdast HTML node containing multiple comments into individual
+* HTML and text nodes. Exported for testing.
+*/
 function splitHtmlIntoMdastNodes(mdastNode) {
 	const htmlTree = fromHtml(mdastNode.value, { fragment: true });
 	const mdastNodes = [];
@@ -465,13 +478,163 @@ function getOriginalMarkup(mdastNode, hastNode) {
 }
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat.ts
-/** Mdast utility that splits, cleans, and expands all mdat comments in the tree. */
+/**
+* Mdast utility that splits, collapses, and then re-expands all mdat comments
+* in the tree.
+*/
 async function mdat(tree, file, rules) {
 	mdatSplit(tree, file);
-	mdatClean(tree, file);
+	mdatCollapse(tree, file);
 	await mdatExpand(tree, file, rules);
 }
 //#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-clean.ts
+/**
+* @deprecated Use {@link mdatCollapse} instead. This alias will be removed in a
+*   future major version.
+*/
+const mdatClean = mdatCollapse;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-diff.ts
+/**
+* Compare original and expanded documents per-tag. Walks both ASTs to extract
+* content between open/close comment markers, then compares per-tag.
+*
+* Callers should run {@link mdatSplit} on both trees before calling this
+* function to ensure multi-comment nodes are split into individual nodes.
+*
+* Adds diagnostic messages to `expandedFile` via the VFile message pipeline.
+*
+* @returns Per-tag comparison results.
+*/
+function mdatDiff(originalTree, originalFile, expandedTree, expandedFile) {
+	const originalText = originalFile.toString();
+	const expandedText = expandedFile.toString();
+	const originalSections = extractSections(originalTree, originalText, originalFile);
+	const expandedSections = extractSections(expandedTree, expandedText, expandedFile);
+	const results = [];
+	const originalByKeyword = groupByKeyword(originalSections);
+	const expandedByKeyword = groupByKeyword(expandedSections);
+	for (const [keyword, expandedList] of expandedByKeyword) {
+		const originalList = originalByKeyword.get(keyword) ?? [];
+		for (const [i, exp] of expandedList.entries()) {
+			const orig = originalList.at(i);
+			if (orig === void 0) {
+				results.push({
+					keyword,
+					line: exp.line,
+					status: "added"
+				});
+				saveLog(expandedFile, "info", "diff", `Added: <!-- ${keyword} -->`, exp.line);
+			} else if (orig.content === void 0) {
+				results.push({
+					keyword,
+					line: exp.line,
+					status: "unexpanded"
+				});
+				saveLog(expandedFile, "warn", "diff", `Unexpanded: <!-- ${keyword} -->`, exp.line);
+			} else if (orig.content === exp.content) {
+				results.push({
+					keyword,
+					line: exp.line,
+					status: "ok"
+				});
+				saveLog(expandedFile, "info", "diff", `Up to date: <!-- ${keyword} -->`, exp.line);
+			} else {
+				results.push({
+					keyword,
+					line: exp.line,
+					status: "stale"
+				});
+				saveLog(expandedFile, "warn", "diff", `Stale: <!-- ${keyword} -->`, exp.line);
+			}
+		}
+	}
+	for (const [keyword, originalList] of originalByKeyword) {
+		const expandedList = expandedByKeyword.get(keyword) ?? [];
+		for (const orig of originalList.slice(expandedList.length)) {
+			results.push({
+				keyword,
+				line: orig.line,
+				status: "missing"
+			});
+			saveLog(expandedFile, "warn", "diff", `Missing: <!-- ${keyword} -->`, orig.line);
+		}
+	}
+	return results;
+}
+function extractSections(tree, text, file) {
+	const sections = [];
+	let lastOpenKeyword;
+	let lastOpenLine = 0;
+	let lastOpenEndOffset;
+	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") {
+			if (lastOpenKeyword !== void 0) sections.push({
+				content: void 0,
+				keyword: lastOpenKeyword,
+				line: lastOpenLine
+			});
+			lastOpenKeyword = marker.keyword;
+			lastOpenLine = marker.node.position?.start.line ?? 0;
+			lastOpenEndOffset = marker.node.position?.end.offset;
+			return CONTINUE;
+		}
+		if (lastOpenKeyword === void 0) {
+			saveLog(file, "warn", "diff", `Close marker without open: <!-- /${marker.keyword} -->`, node);
+			return CONTINUE;
+		}
+		if (lastOpenKeyword !== marker.keyword) {
+			saveLog(file, "warn", "diff", `Keyword mismatch: expected <!-- /${lastOpenKeyword} -->, found <!-- /${marker.keyword} -->`, node);
+			return CONTINUE;
+		}
+		const closeStartOffset = marker.node.position?.start.offset;
+		const sliced = closeStartOffset === void 0 || lastOpenEndOffset === void 0 ? void 0 : text.slice(lastOpenEndOffset, closeStartOffset).replaceAll("\r\n", "\n").trim();
+		const content = sliced === "" ? void 0 : sliced;
+		sections.push({
+			content,
+			keyword: lastOpenKeyword,
+			line: lastOpenLine
+		});
+		lastOpenKeyword = void 0;
+		lastOpenEndOffset = void 0;
+		return CONTINUE;
+	});
+	if (lastOpenKeyword !== void 0) sections.push({
+		content: void 0,
+		keyword: lastOpenKeyword,
+		line: lastOpenLine
+	});
+	return sections;
+}
+function groupByKeyword(sections) {
+	const map = /* @__PURE__ */ new Map();
+	for (const section of sections) {
+		const list = map.get(section.keyword);
+		if (list) list.push(section);
+		else map.set(section.keyword, [section]);
+	}
+	return map;
+}
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-strip.ts
+/**
+* Strips all mdat comment nodes (both opening and closing) from the tree,
+* preserving any content between them. Code-style comments (`//`, `#`, `/*`)
+* are left untouched.
+*/
+function mdatStrip(tree, _file) {
+	visit(tree, "html", (node, index, parent) => {
+		if (parent === void 0 || index === void 0) return CONTINUE;
+		if (parseCommentNode(node, parent) === void 0) return CONTINUE;
+		parent.children.splice(index, 1);
+		return [CONTINUE, index];
+	});
+}
+//#endregion
 //#region src/lib/remark-mdat.ts
 const defaultRules = { mdat: `Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat).` };
 /** Zod schema for validating {@link Options}. */
@@ -489,4 +652,4 @@ const remarkMdat = function(options) {
 	};
 };
 //#endregion
-export { remarkMdat as default, getMdatReports, getSoleRule, getSoleRuleKey, mdat, mdatClean, mdatExpand, mdatSplit, optionsSchema, reporterMdat, rulesSchema, setLogger };
+export { remarkMdat as default, getMdatReports, getSoleRule, getSoleRuleKey, mdat, mdatClean, mdatCollapse, mdatDiff, mdatExpand, mdatSplit, mdatStrip, optionsSchema, reporterMdat, rulesSchema, setLogger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remark-mdat",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "A remark plugin implementing the Markdown Autophagic Template (MDAT) system.",
   "keywords": [
     "mdat",
@@ -59,8 +59,9 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.2",
-    "@kitschpatrol/shared-config": "^7.0.0",
+    "@kitschpatrol/shared-config": "^7.0.1",
     "@types/node": "~20.19.37",
+    "@vitest/coverage-v8": "^4.1.2",
     "bumpp": "^11.0.1",
     "publint": "^0.3.18",
     "tsdown": "^0.21.7",
@@ -77,10 +78,11 @@
     }
   },
   "scripts": {
-    "bench": "vitest bench --no-file-parallelism --compare test/benchmarks/baseline.json",
-    "bench:baseline": "vitest bench --no-file-parallelism --outputJson test/benchmarks/baseline.json",
+    "bench": "vitest bench --run --no-file-parallelism --compare test/benchmarks/baseline.json",
+    "bench:baseline": "vitest bench --run --no-file-parallelism --outputJson test/benchmarks/baseline.json",
     "build": "tsdown",
     "clean": "git rm -f pnpm-lock.yaml ; git clean -fdX",
+    "coverage": "vitest --coverage --run",
     "dev": "pnpm run test",
     "fix": "ksc fix",
     "lint": "ksc lint",

package/readme.md

@@ -46,11 +46,13 @@
   - [Removed options](#removed-options)
   - [Removed rule properties](#removed-rule-properties)
   - [Changed rule properties](#changed-rule-properties)
+  - [Renamed `clean` to `collapse`](#renamed-clean-to-collapse)
   - [Removed validation utility](#removed-validation-utility)
   - [Rule function signature change](#rule-function-signature-change)
   - [Stricter argument syntax](#stricter-argument-syntax)
   - [Comment-style comments are ignored](#comment-style-comments-are-ignored)
   - [Compound rule error handling](#compound-rule-error-handling)
+  - [New utility: `mdatStrip`](#new-utility-mdatstrip)
   - [Removed export: `deepMergeDefined`](#removed-export-deepmergedefined)
 - [Implementation notes](#implementation-notes)
 - [Maintainers](#maintainers)
@@ -273,11 +275,11 @@ Errors and warnings are reported inline during expansion via [VFile messages](ht
 
     _Exported as `mdatSplit(tree: Root, file: VFile): void`_
 
-  - [**`mdast-util-mdat-clean`**](./src/lib/mdast-utils/mdast-util-mdat-clean.ts)
+  - [**`mdast-util-mdat-collapse`**](./src/lib/mdast-utils/mdast-util-mdat-collapse.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): void`_
+    _Exported as `mdatCollapse(tree: Root, file: VFile): void`_
 
   - [**`mdast-util-mdat-expand`**](./src/lib/mdast-utils/mdast-util-mdat-expand.ts)
 
@@ -285,6 +287,18 @@ Errors and warnings are reported inline during expansion via [VFile messages](ht
 
     _Exported as `mdatExpand(tree: Root, file: VFile, rules: Rules): Promise<void>`_
 
+- [**`mdast-util-mdat-strip`**](./src/lib/mdast-utils/mdast-util-mdat-strip.ts)
+
+  Transformer function that strips all mdat comment nodes (both opening and closing) from the tree, preserving any content between them. Code-style comments (`<!-- // ... -->`, `<!-- # ... -->`, `<!-- /* ... */ -->`) are left untouched. Useful for producing a final Markdown document with all mdat scaffolding removed.
+
+  _Exported as `mdatStrip(tree: Root, file: VFile): void`_
+
+- [**`mdast-util-mdat-diff`**](./src/lib/mdast-utils/mdast-util-mdat-diff.ts)
+
+  Compares an original document against an expanded document per-tag, identifying which mdat comments have stale content, are unexpanded, missing, or are up to date. Reports results via VFile messages (`source: 'diff'`) and returns structured `MdatDiffResult[]`. Both trees should have `mdatSplit` applied before calling. Useful for implementing `check` commands that report which specific tags need updating.
+
+  _Exported as `mdatDiff(originalTree: Root, originalFile: VFile, expandedTree: Root, expandedFile: VFile): MdatDiffResult[]`_
+
 ## Migrating from 1.x to 2.x
 
 Version 2.0 simplifies and solidifies the API by removing several configuration options and validation features that added complexity without sufficient benefit. The core expansion behavior is unchanged — the plugin still matches HTML comments to rules and expands them — but the way you configure it has changed.
@@ -339,6 +353,10 @@ The following plugin options have been removed entirely:
 | ------------------ | ------------------ |
 | `applicationOrder` | Change to `order`. |
 
+### Renamed `clean` to `collapse`
+
+The former `mdast-util-mdat-clean` / `mdatClean` is now `mdast-util-mdat-collapse` / `mdatCollapse` since this is more clearly the opposite of "expand", and aligns with language used in the Mdat CLI tool. (Note that `mdatClean` is still available as a deprecated alias, but it will be removed in 3.0.)
+
 ### Removed validation utility
 
 The `mdast-util-mdat-check` utility and its export `mdatCheck` have been removed. Validation logic (missing rules, empty content, rule errors) is now handled inline during expansion by `mdatExpand`, which reports issues as VFile messages. Use `reporterMdat` to format and display these messages.
@@ -391,6 +409,10 @@ HTML comments using code-style prefixes (`<!-- // ... -->`, `<!-- # ... -->`, `<
 
 In 1.x, a failing sub-rule in a compound rule (array of rules) caused the entire expansion to fail. In 2.x, individual sub-rule failures are reported as warnings and skipped — the expansion only fails if every sub-rule fails.
 
+### New utility: `mdatStrip`
+
+A new `mdast-util-mdat-strip` utility is available for removing all mdat comment nodes from a document while preserving the content between them. Code-style comments (`//`, `#`, `/*`) are left untouched. This is useful for producing a final Markdown document with no mdat scaffolding. See the [Utilities](#utilities) section for details.
+
 ### Removed export: `deepMergeDefined`
 
 The `deepMergeDefined` utility has been moved to the [`mdat`](https://github.com/kitschpatrol/mdat) package. If you were importing it from `remark-mdat`, import it from `mdat` instead.