remark-mdat 2.0.0-preview.1 → 2.0.0-preview.3

package/dist/index.d.ts

@@ -7,6 +7,14 @@ import { Plugin } from "unified";
 
 //#region src/lib/mdat/rules.d.ts
 type SimplifyDeep<T> = Simplify<MergeDeep<T, T>>;
+/**
+ * Context passed to rule content functions during expansion.
+ */
+type RuleContext = {
+  /** File path of the source document, if known. */filePath: string | undefined; /** Parsed YAML frontmatter from the document, if present. */
+  frontmatter: Record<string, unknown> | undefined; /** The full mdast AST of the document. Do not mutate. */
+  tree: Root;
+};
 /**
  * Strict normalized rules used internally.
  * Rules normalized to a form with async content functions and other default metadata
@@ -17,7 +25,7 @@ type NormalizedRule = {
    * The function that generates the expanded Markdown string.
    * For 'compound' rules, this can be an array of rules (without keywords).
    */
-  content: ((options: JsonValue, tree: Root) => Promise<string>) | NormalizedRule[];
+  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
@@ -29,7 +37,7 @@ type Rule =
 /**
  * Function that returns the Markdown string to expand at the comment site.
  */
-((options: JsonValue, tree: Root) => Promise<string> | string)
+((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
@@ -54,11 +62,11 @@ type Rule =
    * `<!-- keyword({something: true}) -->` or
    * `<!-- keyword {something: true}-->`
    * Sets options to {something: true}
-   * @param tree
-   * Markdown (mdast) abstract syntax tree containing the entire parsed document. Useful for expanders that need the entire document context, such as when generating a table of contents. Do not mutate the AST, instead return a new string.
+   * @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, tree: Root) => Promise<string> | string) | Rule[] | string;
+  content: ((options: JsonValue, context: RuleContext) => Promise<string> | string) | Rule[] | string;
   /**
    * The order in which the rule should be applied during processing.
    * Defaults to 0.
@@ -165,4 +173,4 @@ type Options = Rules;
  */
 declare const remarkMdat: Plugin<[Options], Root>;
 //#endregion
-export { type MdatFileReport, type MdatMessage, type NormalizedRule, type NormalizedRules, type Options, type Rule, type Rules, type SimplifyDeep, remarkMdat as default, getMdatReports, getSoleRule, getSoleRuleKey, mdat, mdatClean, mdatExpand, mdatSplit, rulesSchema as optionsSchema, rulesSchema, reporterMdat, 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, mdatExpand, mdatSplit, rulesSchema as optionsSchema, rulesSchema, reporterMdat, setLogger };

package/dist/index.js

@@ -4,6 +4,7 @@ import picocolors from "picocolors";
 import { createLogger, injectionHelper } from "lognow";
 import json5 from "json5";
 import { VFileMessage } from "vfile-message";
+import { matter } from "gray-matter-es";
 import { remark } from "remark";
 import remarkGfm from "remark-gfm";
 import { z } from "zod";
@@ -212,7 +213,7 @@ function normalizeRules(rules) {
 		order: 0
 	};
 	else if (typeof rule === "function") normalizedRules[keyword] = {
-		content: async (options, tree) => rule(options, tree),
+		content: async (options, context) => rule(options, context),
 		order: 0
 	};
 	else if (Array.isArray(rule)) normalizedRules[keyword] = {
@@ -232,7 +233,7 @@ function normalizeRules(rules) {
 	else {
 		const ruleContent = rule.content;
 		normalizedRules[keyword] = {
-			content: async (options, tree) => ruleContent(options, tree),
+			content: async (options, context) => ruleContent(options, context),
 			order: rule.order ?? 0
 		};
 	}
@@ -275,25 +276,30 @@ const keywordSchema = z.string().check(z.refine((key) => !/^[/*#]/.test(key), {
 const rulesSchema = z.record(keywordSchema, ruleSchema).describe("MDAT Rules");
 const normalizedRulesSchema = z.record(keywordSchema, normalizedRuleSchema).describe("MDAT Rules");
 /**
-* Compound rule helpers, used in both "expand" and "check" utilities
+* 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, tree, check = false) {
+async function getRuleContent(rule, options, context, onWarning) {
 	if (Array.isArray(rule.content)) {
 		const subruleContent = [];
+		const errors = [];
 		for (const [index, subrule] of rule.content.entries()) {
 			const subruleOptions = Array.isArray(options) ? options.at(index) : void 0;
 			try {
-				subruleContent.push(await getRuleContent(subrule, subruleOptions ?? {}, tree));
+				subruleContent.push(await getRuleContent(subrule, subruleOptions ?? {}, context, onWarning));
 			} catch (error) {
-				if (check) throw error;
+				const message = error instanceof Error ? error.cause instanceof Error ? error.cause.message : error.message : String(error);
+				onWarning?.(`Sub-rule ${String(index)} failed: ${message}`);
+				errors.push(error instanceof Error ? error : new Error(String(error)));
 			}
 		}
+		if (subruleContent.length === 0) throw new AggregateError(errors, "All sub-rules failed in compound rule");
 		return subruleContent.join("\n\n");
 	}
 	try {
-		return await rule.content(options, tree);
+		return await rule.content(options, context);
 	} catch (error) {
-		if (check) throw error;
 		throw new Error("Failed to expand content", { cause: error });
 	}
 }
@@ -340,6 +346,16 @@ function getSoleRecord(record) {
 async function mdatExpand(tree, file, rules) {
 	validateRules(rules);
 	const normalizedRules = normalizeRules(rules);
+	const frontmatter = (() => {
+		if (typeof file.value !== "string") return;
+		const { data } = matter(file.value);
+		return Object.keys(data).length > 0 ? data : void 0;
+	})();
+	const context = {
+		filePath: file.history.length > 0 ? file.path : void 0,
+		frontmatter,
+		tree
+	};
 	const commentMarkers = [];
 	visit(tree, "html", (node, index, parent) => {
 		if (parent === void 0 || index === void 0) return CONTINUE;
@@ -357,7 +373,9 @@ async function mdatExpand(tree, file, rules) {
 		const rule = normalizedRules[keyword];
 		let newMarkdownString = "";
 		try {
-			newMarkdownString = await getRuleContent(rule, options, tree);
+			newMarkdownString = await getRuleContent(rule, options, context, (warning) => {
+				saveLog(file, "warn", "expand", `${html}: ${warning}`, node);
+			});
 			if (newMarkdownString.trim() === "") saveLog(file, "error", "expand", `Got empty content when expanding ${html}`, node);
 		} catch (error) {
 			if (error instanceof Error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remark-mdat",
-  "version": "2.0.0-preview.1",
+  "version": "2.0.0-preview.3",
   "description": "A remark plugin implementing the Markdown Autophagic Template (MDAT) system.",
   "keywords": [
     "mdat",
@@ -43,6 +43,7 @@
   "dependencies": {
     "@types/mdast": "^4.0.4",
     "@types/unist": "^3.0.3",
+    "gray-matter-es": "^0.2.1",
     "hast-util-from-html": "^2.0.3",
     "json5": "^2.2.3",
     "lognow": "^0.5.2",
@@ -67,7 +68,7 @@
     "vitest": "^4.1.1"
   },
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=20.19.6"
   },
   "devEngines": {
     "runtime": {
@@ -82,7 +83,7 @@
     "fix": "ksc fix",
     "lint": "ksc lint",
     "release": "bumpp --commit 'Release: %s' && pnpm run build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish",
-    "release-preview": "bumpp --preid preview --commit 'Release: %s' && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish --tag preview",
+    "release-preview": "bumpp --preid preview --commit 'Release: %s' && pnpm run build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish --tag preview",
     "test": "vitest run"
   }
 }

package/readme.md

@@ -128,8 +128,38 @@ const rules: Rules = {
   // Array: compound rule combining multiple sub-rules
   header: ['# My Project', () => getDescription()],
 
-  // Function with document access: receives the full mdast tree
-  toc: (_options, tree) => generateTocFromTree(tree),
+  // Function with context: access the document tree, frontmatter, and file path
+  toc: (_options, context) => generateTocFromTree(context.tree),
+}
+```
+
+#### Rule context
+
+Rule content functions receive a `RuleContext` object as their second argument, providing access to the document being processed:
+
+```ts
+type RuleContext = {
+  /** File path of the source document, if known. */
+  filePath: string | undefined
+  /** Parsed YAML frontmatter from the document, if present. */
+  frontmatter: Record<string, unknown> | undefined
+  /** The full mdast AST of the document. Do not mutate. */
+  tree: Root
+}
+```
+
+Frontmatter is automatically extracted from the raw Markdown source using [gray-matter-es](https://github.com/ryoppippi/gray-matter-es), so it works regardless of whether `remark-frontmatter` is in your pipeline. If the document has no frontmatter block, `context.frontmatter` is `undefined`.
+
+```ts
+const rules: Rules = {
+  // Access frontmatter values
+  title: (_options, context) => `# ${context.frontmatter?.title ?? 'Untitled'}`,
+
+  // Use the file path
+  source: (_options, context) => `Source: ${context.filePath ?? 'unknown'}`,
+
+  // Traverse the AST
+  toc: (_options, context) => generateTocFromTree(context.tree),
 }
 ```