remark-mdat 2.0.0 → 2.0.2

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,7 +118,8 @@ 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
-declare function mdat(tree: Root, file: VFile, rules: Rules): Promise<void>;
+/** Mdast utility that splits, cleans, and 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
 /**
@@ -128,7 +132,7 @@ declare function mdatClean(tree: Root, file: VFile): void;
 /**
  * Mdast utility to expand mdat comments in the tree.
  */
-declare function mdatExpand(tree: Root, file: VFile, rules: Rules): Promise<void>;
+declare function mdatExpand(tree: Root, file: VFile, rules: NormalizedRules | Rules): Promise<void>;
 //#endregion
 //#region src/lib/mdast-utils/mdast-util-mdat-split.d.ts
 /**
@@ -146,30 +150,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>;

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);
@@ -128,6 +130,9 @@ function parseCommentNode(node, parent) {
 		else 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`.
@@ -137,9 +142,9 @@ function parseComment(text) {
 	if (!isComment(text)) return;
 	const closingPrefix = "/";
 	const commentHtml = text.trim();
-	const commentBody = commentHtml.replace(/^\s*<!-{2,}\s*/, "").replace(/\s*-{2,}>\s*$/, "");
+	const commentBody = commentHtml.replace(HTML_COMMENT_OPEN_REGEX, "").replace(HTML_COMMENT_CLOSE_REGEX, "");
 	const parenIndex = commentBody.indexOf("(");
-	const rawKeyword = parenIndex === -1 ? commentBody.split(/\s/)[0] : commentBody.slice(0, parenIndex).trim();
+	const rawKeyword = parenIndex === -1 ? commentBody.split(WHITESPACE_REGEX)[0] : commentBody.slice(0, parenIndex).trim();
 	if (rawKeyword.startsWith("//") || rawKeyword.startsWith("#") || rawKeyword.startsWith("/*")) return;
 	const type = rawKeyword.startsWith(closingPrefix) ? "close" : "open";
 	let keyword = rawKeyword;
@@ -206,7 +211,15 @@ function mdatClean(tree, file) {
 }
 //#endregion
 //#region src/lib/mdat/rules.ts
+/** Brand symbol to detect pre-normalized rules and skip re-validation. */
+const NORMALIZED = Symbol("normalized");
+/** Check whether rules have already been 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 = {};
 	for (const [keyword, rule] of Object.entries(rules)) if (typeof rule === "string") normalizedRules[keyword] = {
 		content: async () => rule,
@@ -237,9 +250,10 @@ function normalizeRules(rules) {
 			order: rule.order ?? 0
 		};
 	}
-	validateNormalizedRules(normalizedRules);
+	Object.defineProperty(normalizedRules, NORMALIZED, { value: true });
 	return normalizedRules;
 }
+/** Validates rules against {@link rulesSchema}, throwing on invalid input. */
 function validateRules(rules) {
 	try {
 		rulesSchema.parse(rules);
@@ -247,18 +261,7 @@ function validateRules(rules) {
 		if (error instanceof Error) throw new TypeError(`Error validating rules: ${error.message}`);
 	}
 }
-function validateNormalizedRules(rules) {
-	try {
-		normalizedRulesSchema.parse(rules);
-	} catch (error) {
-		if (error instanceof Error) throw new TypeError(`Error validating rules: ${error.message}`);
-	}
-}
 const functionSchema = z.custom((value) => typeof value === "function");
-const normalizedRuleSchema = z.lazy(() => z.object({
-	content: z.union([functionSchema, z.array(normalizedRuleSchema)]),
-	order: z.number()
-}));
 const ruleSchema = z.lazy(() => z.union([
 	functionSchema,
 	z.array(ruleSchema),
@@ -272,9 +275,10 @@ const ruleSchema = z.lazy(() => z.union([
 		order: z.number().optional()
 	})
 ]));
-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 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");
-const normalizedRulesSchema = z.record(keywordSchema, normalizedRuleSchema).describe("MDAT Rules");
 /**
 * Expand rule content. For compound rules (content arrays), individual
 * sub-rule failures are reported via `onWarning` and skipped. The entire
@@ -344,8 +348,7 @@ function getSoleRecord(record) {
 * Mdast utility to expand mdat comments in the tree.
 */
 async function mdatExpand(tree, file, rules) {
-	validateRules(rules);
-	const normalizedRules = normalizeRules(rules);
+	const normalizedRules = isNormalized(rules) ? rules : normalizeRules(rules);
 	const frontmatter = (() => {
 		if (typeof file.value !== "string") return;
 		const { data } = matter(file.value);
@@ -368,6 +371,7 @@ async function mdatExpand(tree, file, rules) {
 		commentMarkers.push(commentMarker);
 	});
 	commentMarkers.sort((a, b) => normalizedRules[a.keyword].order - normalizedRules[b.keyword].order);
+	const parser = remark().use(remarkGfm);
 	for (const comment of commentMarkers) {
 		const { html, keyword, node, options, parent } = comment;
 		const rule = normalizedRules[keyword];
@@ -384,7 +388,7 @@ async function mdatExpand(tree, file, rules) {
 			}
 			continue;
 		}
-		const newNodes = remark().use(remarkGfm).parse(newMarkdownString).children;
+		const newNodes = parser.parse(newMarkdownString).children;
 		const closingNode = {
 			type: "html",
 			value: `<!-- /${keyword} -->`
@@ -403,6 +407,8 @@ async function mdatExpand(tree, file, rules) {
 function mdatSplit(tree, file) {
 	visit(tree, "html", (node, index, parent) => {
 		if (parent === void 0 || index === void 0) return CONTINUE;
+		const v = node.value;
+		if (v.startsWith("<!--") && v.endsWith("-->") && !v.includes("<!--", 4)) return CONTINUE;
 		const htmlNodes = splitHtmlIntoMdastNodes(node);
 		if (htmlNodes.length > 1) {
 			saveLog(file, "warn", "split", "Multiple comments in a single HTML node.", node);
@@ -413,6 +419,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 = [];
@@ -458,6 +465,7 @@ 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. */
 async function mdat(tree, file, rules) {
 	mdatSplit(tree, file);
 	mdatClean(tree, file);
@@ -466,17 +474,18 @@ async function mdat(tree, file, rules) {
 //#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.
 */
 const remarkMdat = function(options) {
-	const resolvedRules = {
+	const normalizedRules = normalizeRules({
 		...defaultRules,
 		...options?.rules
-	};
+	});
 	return async function(tree, file) {
-		await mdat(tree, file, resolvedRules);
+		await mdat(tree, file, normalizedRules);
 	};
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remark-mdat",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "A remark plugin implementing the Markdown Autophagic Template (MDAT) system.",
   "keywords": [
     "mdat",
@@ -46,7 +46,7 @@
     "gray-matter-es": "^0.2.1",
     "hast-util-from-html": "^2.0.3",
     "json5": "^2.2.3",
-    "lognow": "^0.5.2",
+    "lognow": "^0.6.0",
     "picocolors": "^1.1.1",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
@@ -59,7 +59,7 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.2",
-    "@kitschpatrol/shared-config": "^6.2.0",
+    "@kitschpatrol/shared-config": "^7.0.0",
     "@types/node": "~20.19.37",
     "bumpp": "^11.0.1",
     "publint": "^0.3.18",
@@ -77,6 +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",
     "build": "tsdown",
     "clean": "git rm -f pnpm-lock.yaml ; git clean -fdX",
     "dev": "pnpm run test",