remark-mdat 2.0.1 → 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,6 +118,7 @@ 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, 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
@@ -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);
@@ -215,6 +217,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 +253,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 +277,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 +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 = [];
@@ -459,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);
@@ -467,6 +474,7 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remark-mdat",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "A remark plugin implementing the Markdown Autophagic Template (MDAT) system.",
   "keywords": [
     "mdat",