remark-mdat 2.1.0 → 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,15 +113,15 @@ 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.
  */
@@ -139,6 +149,26 @@ declare function mdatCollapse(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
 /**
  * Mdast utility to expand mdat comments in the tree.
@@ -147,8 +177,9 @@ 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
@@ -204,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, mdatCollapse, mdatExpand, mdatSplit, mdatStrip, 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;
@@ -189,25 +194,23 @@ function mdatCollapse(tree, file) {
 			lastOpenMarker = marker;
 			return CONTINUE;
 		}
-		if (marker.type === "close") {
-			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];
+		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
@@ -218,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 = {};
@@ -281,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)) {
@@ -309,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.
 */
@@ -318,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.
 */
@@ -331,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
 */
@@ -402,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) => {
@@ -420,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 = [];
@@ -483,6 +495,131 @@ async function mdat(tree, file, rules) {
 */
 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,
@@ -515,4 +652,4 @@ const remarkMdat = function(options) {
 	};
 };
 //#endregion
-export { remarkMdat as default, getMdatReports, getSoleRule, getSoleRuleKey, mdat, mdatClean, mdatCollapse, mdatExpand, mdatSplit, mdatStrip, 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.1.0",
+  "version": "2.2.0",
   "description": "A remark plugin implementing the Markdown Autophagic Template (MDAT) system.",
   "keywords": [
     "mdat",
@@ -61,6 +61,7 @@
     "@arethetypeswrong/core": "^0.18.2",
     "@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",
@@ -81,6 +82,7 @@
     "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

@@ -293,6 +293,12 @@ Errors and warnings are reported inline during expansion via [VFile messages](ht
 
   _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.