remark-mdat 2.0.1 → 2.1.0

package/dist/index.d.ts

@@ -6,6 +6,7 @@ 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`. */
 type SimplifyDeep<T> = Simplify<MergeDeep<T, T>>;
 /**
  * Context passed to rule content functions during expansion.
@@ -97,7 +98,9 @@ type Rule =
  * { basic-date: { order: 1, content: () => `${new Date().toISOString()}` } }
  */
 type Rules = SimplifyDeep<Record<string, Rule>>;
+/** A record mapping comment keywords to {@link NormalizedRule} objects. */
 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.
@@ -115,14 +118,26 @@ 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
+/**
+ * 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-expand.d.ts
 /**
@@ -137,6 +152,14 @@ declare function mdatExpand(tree: Root, file: VFile, rules: NormalizedRules | Ru
  */
 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.
@@ -146,30 +169,33 @@ declare function mdatSplit(tree: Root, file: VFile): void;
 declare function setLogger(logger?: ILogBasic | ILogLayer): void;
 //#endregion
 //#region src/lib/mdat/mdat-log.d.ts
-/**
- * Tries to provide a simpler wrapper to vfile.message
- */
+/** A simplified representation of a {@link VFileMessage}. */
 type MdatMessage = {
-  column?: number;
-  level: 'error' | 'info' | 'warn';
-  line?: number;
-  message: string;
+  /** Starting column of the message origin. */column?: number; /** Severity level. */
+  level: 'error' | 'info' | 'warn'; /** Starting line of the message origin. */
+  line?: number; /** Human-readable description of the issue. */
+  message: string; /** Namespace that produced the message (e.g. the rule name). */
   source?: string;
 };
+/** Aggregated processing report for a single file. */
 type MdatFileReport = {
-  destinationPath?: string;
-  errors: MdatMessage[];
-  infos: MdatMessage[];
-  sourcePath: string;
+  /** Output path if the file was written to a different location. */destinationPath?: string; /** Fatal errors that prevented successful processing. */
+  errors: MdatMessage[]; /** Informational messages. */
+  infos: MdatMessage[]; /** Original input file path. */
+  sourcePath: string; /** Non-fatal warnings encountered during processing. */
   warnings: MdatMessage[];
 };
+/** Converts an array of processed VFiles into {@link MdatFileReport} objects. */
 declare function getMdatReports(files: VFile[]): MdatFileReport[];
+/** Logs a human-readable processing report for each VFile to the library logger. */
 declare function reporterMdat(files: VFile[]): void;
 //#endregion
 //#region src/lib/remark-mdat.d.ts
+/** Configuration for the remarkMdat plugin. */
 type Options = {
-  rules?: Rules;
+  /** Rules mapping comment keywords to expansion content. Merged with built-in defaults. */rules?: Rules;
 };
+/** Zod schema for validating {@link Options}. */
 declare const optionsSchema: z.ZodObject<{
   rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
 }, z.core.$strip>;
@@ -178,4 +204,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 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 };

package/dist/index.js

@@ -63,6 +63,7 @@ function vFileMessageToMdatMessage(vFileMessage) {
 		source: vFileMessage.source
 	};
 }
+/** Converts an array of processed VFiles into {@link MdatFileReport} objects. */
 function getMdatReports(files) {
 	return files.map((file) => getMdatReport(file));
 }
@@ -83,6 +84,7 @@ function getMdatReport(file) {
 	}
 	return mdatFileReport;
 }
+/** Logs a human-readable processing report for each VFile to the library logger. */
 function reporterMdat(files) {
 	for (const file of files) {
 		const { destinationPath, errors, infos, sourcePath, warnings } = getMdatReport(file);
@@ -171,12 +173,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,15 +191,15 @@ function mdatClean(tree, file) {
 		}
 		if (marker.type === "close") {
 			if (lastOpenMarker === void 0) {
-				saveLog(file, "error", "clean", "Found closing marker without opening marker", node);
+				saveLog(file, "error", "collapse", "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);
+				saveLog(file, "error", "collapse", "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);
+				saveLog(file, "error", "collapse", "Opening marker doesn't share a keyword", node);
 				return CONTINUE;
 			}
 			const openMarkerIndex = parent.children.indexOf(lastOpenMarker.node);
@@ -215,6 +218,7 @@ const NORMALIZED = Symbol("normalized");
 function isNormalized(rules) {
 	return NORMALIZED in rules;
 }
+/** Converts flexible {@link Rules} into strict {@link NormalizedRules} for internal processing. */
 function normalizeRules(rules) {
 	validateRules(rules);
 	const normalizedRules = {};
@@ -250,6 +254,7 @@ function normalizeRules(rules) {
 	Object.defineProperty(normalizedRules, NORMALIZED, { value: true });
 	return normalizedRules;
 }
+/** Validates rules against {@link rulesSchema}, throwing on invalid input. */
 function validateRules(rules) {
 	try {
 		rulesSchema.parse(rules);
@@ -273,6 +278,7 @@ const ruleSchema = z.lazy(() => z.union([
 ]));
 const COMMENT_PREFIX_REGEX = /^[/*#]/;
 const keywordSchema = z.string().check(z.refine((key) => !COMMENT_PREFIX_REGEX.test(key), { message: "Rule keywords must not start with \"/\", \"*\", or \"#\" — these prefixes are reserved for comment syntax" }));
+/** 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
@@ -414,6 +420,7 @@ function mdatSplit(tree, file) {
 		}
 	});
 }
+/** 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 = [];
@@ -459,14 +466,41 @@ function getOriginalMarkup(mdastNode, hastNode) {
 }
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat.ts
+/**
+* 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-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}. */
 const optionsSchema = z.object({ rules: rulesSchema.optional() }).describe("MDAT Plugin Options");
 /**
 * A remark plugin that expands HTML comments in Markdown files.
@@ -481,4 +515,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, mdatExpand, mdatSplit, mdatStrip, optionsSchema, reporterMdat, rulesSchema, setLogger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remark-mdat",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A remark plugin implementing the Markdown Autophagic Template (MDAT) system.",
   "keywords": [
     "mdat",
@@ -59,7 +59,7 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.2",
-    "@kitschpatrol/shared-config": "^7.0.0",
+    "@kitschpatrol/shared-config": "^7.0.1",
     "@types/node": "~20.19.37",
     "bumpp": "^11.0.1",
     "publint": "^0.3.18",
@@ -77,8 +77,8 @@
     }
   },
   "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",
     "dev": "pnpm run test",

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,12 @@ 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`_
+
 ## 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 +347,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 +403,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.