remark-mdat 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { type Options as MdatOptions, mdat } from './lib/mdast-utils/mdast-util-mdat';
+export { type Options as MdatCheckOptions, mdatCheck, } from './lib/mdast-utils/mdast-util-mdat-check';
+export { type Options as MdatCleanOptions, mdatClean, } from './lib/mdast-utils/mdast-util-mdat-clean';
+export { type Options as MdatExpandOptions, mdatExpand, } from './lib/mdast-utils/mdast-util-mdat-expand';
+export { mdatSplit } from './lib/mdast-utils/mdast-util-mdat-split';
+export { deepMergeDefined } from './lib/mdat/deep-merge-defined';
+export { default as log } from './lib/mdat/log';
+export { type MdatFileReport, type MdatMessage, getMdatReports, reporterMdat, } from './lib/mdat/mdat-log';
+export { type NormalizedRule, type NormalizedRules, type Rule, type Rules, type SimplifyDeep, getSoleRule, getSoleRuleKey, rulesSchema, } from './lib/mdat/rules';
+export { type Options, default, optionsSchema } from './lib/remark-mdat';

package/dist/index.js

@@ -0,0 +1,4 @@
+import h from"chalk";var J,L=((J=process==null?void 0:process.versions)==null?void 0:J.node)!==void 0,ae={verbose:!1,log(...e){if(!this.verbose)return;let r=h.gray("[Log]");L?console.warn(r,...e):console.log(r,...e)},logPrefixed(e,...r){this.info(h.blue(`[${e}]`),...r)},info(...e){if(!this.verbose)return;let r=h.green("[Info]");L?console.warn(r,...e):console.info(r,...e)},infoPrefixed(e,...r){this.info(h.blue(`[${e}]`),...r)},warn(...e){console.warn(h.yellow("[Warning]"),...e)},warnPrefixed(e,...r){this.warn(h.blue(`[${e}]`),...r)},error(...e){console.error(h.red("[Error]"),...e)},errorPrefixed(e,...r){this.error(h.blue(`[${e}]`),...r)}},y=ae;import w from"chalk";import D from"node:path";function u(e,r,n,t,o,i){var p,c;let a,s;o===void 0||typeof o=="number"?(a=o??0,s=i??0):(a=((p=o==null?void 0:o.position)==null?void 0:p.start.line)??0,s=((c=o==null?void 0:o.position)==null?void 0:c.start.column)??0);let l={place:{end:{column:s,line:a},start:{column:s,line:a}},source:n},d=e.message(t,l);d.fatal=r==="error"?!0:r==="warn"?!1:void 0}function le(e){return{column:e.column,level:e.fatal?"error":e.fatal===!1?"warn":"info",line:e.line,message:e.reason,source:e.source}}function me(e){return e.map(r=>U(r))}function U(e){var n;let r={destinationPath:e.history.length>0?e.history.at(-1):void 0,errors:[],infos:[],sourcePath:e.history.at(0)??e.path,warnings:[]};(n=r.sourcePath)!=null&&n.startsWith(".")&&(r.sourcePath=D.relative(process.cwd(),D.join(process.cwd(),r.sourcePath)));for(let t of e.messages){let o=le(t);o.level==="error"?r.errors.push(o):o.level==="warn"?r.warnings.push(o):r.infos.push(o)}return r}function de(e){for(let r of e){let n=U(r),{destinationPath:t,errors:o,infos:i,sourcePath:a,warnings:s}=n;y.info(`${w.bold("Comment Expansion Report:")}`),y.info(`	From: ${w.blue.bold(a)}`),y.info(`	To:   ${w.blue.bold(t)}`);for(let l of o)y.error(V(a,l));for(let l of s)y.warn(V(a,l));for(let l of i)y.info(V(a,l));o.length===0&&s.length===0?y.info(`No issues found in ${a}`):y.error(`${o.length} errors, ${s.length} warnings found in ${a}`)}}function V(e,r){let{column:n,level:t,line:o,message:i,source:a}=r,s=a?w.gray(`[${a}] `):"",l=o&&n?`:${o}:${n}`:"",d=pe(i,t);return`${s}${d} ${w.whiteBright(e+l)}`}function pe(e,r){return e.replaceAll(/<!--.+-->/g,n=>r==="info"?w.green(n):r==="warn"?w.yellow(n):w.red(n))}import ue from"json5";import{VFileMessage as P}from"vfile-message";function R(e,r,n){var t;try{let o=ce(e.value,n);return o===void 0?void 0:{...o,node:e,parent:r}}catch(o){throw o instanceof P?(o.line=(t=e.position)==null?void 0:t.start.line,o):o instanceof Error?new P(o.message,e):new P("Unknown error",e)}}function ce(e,r){if(!fe(e))return;let{closingPrefix:n,keywordPrefix:t,metaCommentIdentifier:o}=r,i=e.trim(),a=i.replace(/^\s*<!--+\s*/,"").replace(/\s*-*-->\s*$/,""),[s,...l]=a.split(/(\s+|\(|{)/),d=s.startsWith(o)?"meta":t!==""&&!s.startsWith(t)&&!s.startsWith(`${n}${t}`)?"native":s.startsWith(n)?"close":"open";if(d==="meta")return{content:ye(a,o),html:i,type:d};if(d==="native")return{content:a,html:i,type:d};let p=s.replace(new RegExp(`^${n}`),"").replace(new RegExp(`^${t}`),""),c=ge(l.join(""));if(d==="open"||d==="close"){let f={};try{f=ue.parse(c)}catch(g){if(g instanceof Error)throw new P(`Failed to parse comment options "${c}" for keyword "${p}": ${g.message}`)}return{closingPrefix:n,html:i,keyword:p,keywordPrefix:t,options:f,type:d}}}function fe(e){let r=e.trim();return r.startsWith("<!--")&&r.endsWith("-->")}function ge(e){return e=e.trim(),e=e.startsWith("(")?e.slice(1):e,e=e.endsWith(")")?e.slice(0,-1):e,e=e.trim(),!e.startsWith("{")&&!e.startsWith("[")&&(e="{"+e),!e.endsWith("}")&&!e.endsWith("]")&&(e+="}"),e}function ye(e,r){return e=e.trim(),e=e.startsWith(r)?e.slice(r.length):e,e=e.endsWith(r)?e.slice(0,-r.length):e,e}import{z as m}from"zod";function M(e){let r={};for(let[n,t]of Object.entries(e))if(typeof t=="string")r[n]={applicationOrder:0,content:async()=>t,order:void 0,required:!1};else if(typeof t=="function")r[n]={applicationOrder:0,content:async(o,i)=>t(o,i),order:void 0,required:!1};else if(Array.isArray(t))r[n]={applicationOrder:0,content:Object.values(M(Object.fromEntries(t.entries()))),order:void 0,required:!1};else if(typeof t.content=="string"){let o=t.content;r[n]={applicationOrder:t.applicationOrder??0,content:async()=>o,order:t.order??void 0,required:t.required??!1}}else if(Array.isArray(t.content))r[n]={applicationOrder:t.applicationOrder??0,content:Object.values(M(Object.fromEntries(t.content.entries()))),order:t.order??void 0,required:t.required??!1};else{let o=t.content;r[n]={applicationOrder:t.applicationOrder??0,content:async(i,a)=>o(i,a),order:t.order??void 0,required:t.required??!1}}return he(r),r}function b(e){try{v.parse(e)}catch(r){if(r instanceof Error)throw new TypeError(`Error validating rules: ${r.message}`)}}function he(e){try{we.parse(e)}catch(r){if(r instanceof Error)throw new TypeError(`Error validating rules: ${r.message}`)}}var B=m.any(),G=m.any(),Z=m.lazy(()=>m.object({applicationOrder:m.number(),content:m.union([m.function().args(B.optional(),G.optional()).returns(m.promise(m.string())),m.array(Z)]),order:m.number().optional(),required:m.boolean().default(!1)})),K=m.function().args(B.optional(),G.optional()).returns(m.union([m.string(),m.promise(m.string())])),S=m.lazy(()=>m.union([K,m.array(S),m.string(),m.object({applicationOrder:m.number().optional(),content:m.union([K,m.array(S),m.string()]),order:m.number().optional(),required:m.boolean().optional()})])),v=m.record(S).describe("Mdat Rules"),we=m.record(Z).describe("Mdat Rules");async function C(e,r,n,t=!1){if(Array.isArray(e.content)){let o=[];for(let[i,a]of e.content.entries()){let s=Array.isArray(r)?r.at(i):void 0;try{o.push(await C(a,s??{},n))}catch(l){if(t)throw l}}return o.join(`
+
+`)}try{return await e.content(r,n)}catch(o){if(t)throw o}throw new Error("Failed to expand content")}function ke(e){return Me(e)}function Re(e){let r=Object.keys(e);if(r.length!==1)throw new Error(`Expected exactly one rule, found ${r.length}`);return r[0]}function Me(e){let r=Object.values(e);if(r.length===0)throw new Error('Found no entries in a "sole record" record. This should never happen');if(r.length>1)throw new Error('Found multiple entries in "sole record" record. This should never happen');return r[0]}import Q from"chalk";import Ce from"cli-table3";import{CONTINUE as xe,visit as Oe}from"unist-util-visit";async function F(e,r,n){let{closingPrefix:t,keywordPrefix:o,metaCommentIdentifier:i,paranoid:a=!1,rules:s}=n;b(s);let l=M(s),d=[];Oe(e,"html",(p,c,f)=>{if(f===void 0||c===void 0)return xe;let g=R(p,f,{closingPrefix:t,keywordPrefix:o,metaCommentIdentifier:i});if(g!==void 0){let $=g.type==="open"||g.type==="close"?l[g.keyword]:void 0;d.push({...g,rule:$})}}),Te(r,d,l),Ve(r,d),Se(r,d,n),await Pe(r,d,e),a&&$e(r,d,l),ve(r,d),be(r,d,l,n)}async function Pe(e,r,n){for(let t of r)if(t.type==="open"&&t.rule!==void 0)try{(await C(t.rule,t.options,n,!0)).trim()===""&&u(e,t.rule.required?"error":"warn","check",`${t.html} returned an empty string.`,t.node)}catch(o){o instanceof Error&&u(e,t.rule.required?"error":"warn","check",`Could not get content for ${t.html}. ${o.message}`,t.node)}}function be(e,r,n,t){if(t.keywordPrefix==="")return;let o=Object.keys(n);for(let i of r)i.type==="native"&&o.includes(i.content)&&u(e,"warn","check",`Missing prefix: ${i.html}`,i.node)}function ve(e,r){for(let n of r)n.type==="open"&&n.rule===void 0&&u(e,"warn","check",`Missing rule for: ${n.html}`,n.node)}function $e(e,r,n){for(let[t,o]of Object.entries(n))!o.required&&!r.some(i=>i.type==="open"&&i.keyword===t)&&!Y(o,r)&&u(e,"warn","check",`Missing optional: <!-- ${t} -->`)}function Te(e,r,n){for(let[t,o]of Object.entries(n))o.required&&!r.some(i=>i.type==="open"&&i.keyword===t)&&!Y(o,r)&&u(e,"error","check",`Missing required: <!-- ${t} -->`)}function Y(e,r){return r.reduce((n,t)=>{var o;if(Array.isArray((o=t.rule)==null?void 0:o.content))for(let i of t.rule.content)i.content.toString()===e.content.toString()&&(n=!0);return n},!1)}function Ve(e,r){let n=r.filter(s=>{var l;return s.type==="open"&&((l=s.rule)==null?void 0:l.order)!==void 0}),t=[...n].sort((s,l)=>{var c,f;let d=(c=s.rule)==null?void 0:c.order,p=(f=l.rule)==null?void 0:f.order;if(d===void 0||p===void 0)throw new Error("Unexpected undefined rule order");return d-p}),o=X(n),i=X(t),a=new Ce({head:[Q.bold.red("Current Order"),Q.bold.green("Required Order")],style:{compact:!0}});o.join(",")!==i.join(",")&&(a.push(...o.map((s,l)=>[s,i[l]])),u(e,"error","check",`Out of order:
+${a.toString()}`))}function Se(e,r,n){let{addMetaComment:t}=n,o=r.filter(i=>i.type==="meta").length;t&&o!==1&&u(e,"error","check","Missing meta comment"),!t&&o!==0&&u(e,"error","check","Unexpected meta comment"),o>1&&u(e,"error","check","Multiple meta comments")}function X(e){return e.map((r,n)=>{if(r.type==="open"||r.type==="close")return`${n+1}. ${r.html}`;throw new Error("Unexpected comment type")})}import{CONTINUE as k,visit as Fe}from"unist-util-visit";function E(e,r,n){let t;Fe(e,"html",(o,i,a)=>{if(a===void 0||i===void 0)return k;let s=R(o,a,n);if(s===void 0||s.type==="native")return k;if(s.type==="meta")return a.children.splice(i,1),[k,i];if(s.type==="open")return t=s,k;if(s.type==="close"){if(t===void 0)return u(r,"error","clean","Found closing marker without opening marker",o),k;if(t.parent!==s.parent)return u(r,"error","clean","Opening marker doesn't share a parent",o),k;if(t.keyword!==s.keyword)return u(r,"error","clean","Opening marker doesn't share a keyword",o),k;let l=a.children.indexOf(t.node),p=a.children.indexOf(s.node)-l+1;return a.children.splice(l+1,p-1),t=void 0,[k,i-p+1]}})}import{remark as Ee}from"remark";import ze from"remark-gfm";import{CONTINUE as Ne,visit as We}from"unist-util-visit";async function z(e,r,n){let{addMetaComment:t,closingPrefix:o,keywordPrefix:i,metaCommentIdentifier:a,rules:s}=n;b(s);let l=M(s),d=[];We(e,"html",(p,c,f)=>{if(f===void 0||c===void 0)return Ne;let g=R(p,f,{closingPrefix:o,keywordPrefix:i,metaCommentIdentifier:a});g!==void 0&&g.type==="open"&&l[g.keyword]!==void 0&&d.push(g)}),d.sort((p,c)=>l[p.keyword].applicationOrder-l[c.keyword].applicationOrder);for(let p of d){let{closingPrefix:c,html:f,keyword:g,keywordPrefix:$,node:O,options:te,parent:A}=p,oe=l[g],T="";try{T=await C(oe,te,e),T.trim()===""&&u(r,"error","expand",`Got empty content when expanding ${f}`,O)}catch(H){H instanceof Error&&u(r,"error","expand",`Caught error expanding ${f}, Error message: "${H.message}"`,O);continue}let ne=Ee().use(ze).parse(T).children,ie={type:"html",value:`<!-- ${c}${$}${g} -->`},se=A.children.indexOf(O);A.children.splice(se+1,0,...ne,ie),u(r,"info","expand",`Expanded: ${f}`,O)}if(t){let p="Warning: Content in HTML comment blocks generated by mdat",c=new Date().toISOString().slice(0,10),f={type:"html",value:`<!--${a} ${p} on ${c} ${a}-->`};e.children.unshift(f)}}import{fromHtml as Ie}from"hast-util-from-html";import{CONTINUE as N,SKIP as je,visit as re}from"unist-util-visit";function W(e,r){re(e,"html",(n,t,o)=>{if(o===void 0||t===void 0)return N;let i=qe(n);i.length>1&&(u(r,"warn","split","Multiple comments in a single HTML node.",n),o.children.splice(t,1,{children:i,type:"paragraph"}))})}function qe(e){let r=Ie(e.value,{fragment:!0}),n=[];return re(r,t=>{var o,i;return t.type==="root"?N:t.type==="text"?(n.push({position:_(t.position,(o=e.position)==null?void 0:o.start),type:"text",value:ee(e,t)}),N):(n.push({position:_(t.position,(i=e.position)==null?void 0:i.start),type:"html",value:ee(e,t)}),je)}),n}function _(e,r){if(!(e===void 0||r===void 0))return{end:{column:e.end.column-1+r.column,line:e.end.line-1+r.line,offset:e.end.offset!==void 0&&r.offset!==void 0?e.end.offset+r.offset:void 0},start:{column:e.start.column-1+r.column,line:e.start.line-1+r.line,offset:e.start.offset!==void 0&&r.offset!==void 0?e.start.offset+r.offset:void 0}}}function ee(e,r){if(r.position===void 0)throw new Error("Hast ElementContent node has no position!");return e.value.slice(r.position.start.offset,r.position.end.offset)}async function I(e,r,n){let{addMetaComment:t,closingPrefix:o,keywordPrefix:i,metaCommentIdentifier:a,rules:s}=n;W(e,r),E(e,r,{closingPrefix:o,keywordPrefix:i,metaCommentIdentifier:a}),await z(e,r,{addMetaComment:t,closingPrefix:o,keywordPrefix:i,metaCommentIdentifier:a,rules:s}),await F(e,r,{addMetaComment:t,closingPrefix:o,keywordPrefix:i,metaCommentIdentifier:a,paranoid:!1,rules:s})}import{deepmerge as Ae}from"deepmerge-ts";function j(e){return Array.isArray(e)?e.map(r=>r&&typeof r=="object"?j(r):r).filter(r=>r!==void 0):Object.entries(e).map(([r,n])=>[r,n&&typeof n=="object"?j(n):n]).reduce((r,[n,t])=>t===void 0?r:{...r,[n]:t},{})}function q(...e){let r=e.map((n,t)=>t===0?n:j(n));return Ae(...r)}import{z as x}from"zod";var He={addMetaComment:!1,closingPrefix:"/",keywordPrefix:"",metaCommentIdentifier:"+",rules:{mdat:"Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat)."}},Le=x.object({addMetaComment:x.boolean().optional(),closingPrefix:x.string().optional(),keywordPrefix:x.string().optional(),metaCommentIdentifier:x.string().optional(),rules:v.optional()}).describe("Mdat Options"),Je=function(e){let r=q(He,e);return async function(n,t){await I(n,t,r)}},De=Je;export{q as deepMergeDefined,De as default,me as getMdatReports,ke as getSoleRule,Re as getSoleRuleKey,y as log,I as mdat,F as mdatCheck,E as mdatClean,z as mdatExpand,W as mdatSplit,Le as optionsSchema,de as reporterMdat,v as rulesSchema};

package/dist/lib/mdast-utils/mdast-util-mdat-check.d.ts

@@ -0,0 +1,16 @@
+import { type Rules } from '../mdat/rules';
+import type { Root } from 'mdast';
+import type { VFile } from 'vfile';
+export type Options = {
+    addMetaComment: boolean;
+    closingPrefix: string;
+    keywordPrefix: string;
+    metaCommentIdentifier: string;
+    /** Enable extra checks, too noisy for real life. */
+    paranoid: boolean;
+    rules: Rules;
+};
+/**
+ * Mdast utility function to check mdat source document, and output.
+ */
+export declare function mdatCheck(tree: Root, file: VFile, options: Options): Promise<void>;

package/dist/lib/mdast-utils/mdast-util-mdat-clean.d.ts

@@ -0,0 +1,13 @@
+import type { Root } from 'mdast';
+import { type VFile } from 'vfile';
+export type Options = {
+    closingPrefix: string;
+    keywordPrefix: string;
+    metaCommentIdentifier: string;
+};
+/**
+ * Collapses any expanded mdat comments and removes meta comments,
+ * effectively resetting the document to its pre-expansion state. No-op if no
+ * mdat comments are found.
+ */
+export declare function mdatClean(tree: Root, file: VFile, options: Options): void;

package/dist/lib/mdast-utils/mdast-util-mdat-expand.d.ts

@@ -0,0 +1,11 @@
+import { type Rules } from '../mdat/rules';
+import type { Root } from 'mdast';
+import { type VFile } from 'vfile';
+export type Options = {
+    addMetaComment: boolean;
+    closingPrefix: string;
+    keywordPrefix: string;
+    metaCommentIdentifier: string;
+    rules: Rules;
+};
+export declare function mdatExpand(tree: Root, file: VFile, options: Options): Promise<void>;

package/dist/lib/mdast-utils/mdast-util-mdat-split.d.ts

@@ -0,0 +1,9 @@
+import { type Html, type Text } from 'mdast';
+import type { Root } from 'mdast';
+import { type VFile } from 'vfile';
+/**
+ * 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.
+ */
+export declare function mdatSplit(tree: Root, file: VFile): void;
+export declare function splitHtmlIntoMdastNodes(mdastNode: Html): Array<Html | Text>;

package/dist/lib/mdast-utils/mdast-util-mdat.d.ts

@@ -0,0 +1,11 @@
+import { type Rules } from '../mdat/rules';
+import type { Root } from 'mdast';
+import { type VFile } from 'vfile';
+export type Options = {
+    addMetaComment: boolean;
+    closingPrefix: string;
+    keywordPrefix: string;
+    metaCommentIdentifier: string;
+    rules: Rules;
+};
+export declare function mdat(tree: Root, file: VFile, options: Options): Promise<void>;

package/dist/lib/mdat/deep-merge-defined.d.ts

@@ -0,0 +1,2 @@
+export declare function stripUndefinedDeep<T>(object: T | T[]): T | T[];
+export declare function deepMergeDefined<T extends Record<string, unknown>>(...objects: T[]): T;

package/dist/lib/mdat/log.d.ts

@@ -0,0 +1,12 @@
+declare const log: {
+    verbose: boolean;
+    log(...data: unknown[]): void;
+    logPrefixed(prefix: string, ...data: unknown[]): void;
+    info(...data: unknown[]): void;
+    infoPrefixed(prefix: string, ...data: unknown[]): void;
+    warn(...data: unknown[]): void;
+    warnPrefixed(prefix: string, ...data: unknown[]): void;
+    error(...data: unknown[]): void;
+    errorPrefixed(prefix: string, ...data: unknown[]): void;
+};
+export default log;

package/dist/lib/mdat/mdat-log.d.ts

@@ -0,0 +1,20 @@
+import type { Node } from 'unist';
+import { type VFile } from 'vfile';
+export type MdatMessage = {
+    column?: number;
+    level: 'error' | 'info' | 'warn';
+    line?: number;
+    message: string;
+    source?: string;
+};
+export type MdatFileReport = {
+    destinationPath?: string;
+    errors: MdatMessage[];
+    infos: MdatMessage[];
+    sourcePath: string;
+    warnings: MdatMessage[];
+};
+export declare function saveLog(file: VFile, level: 'error' | 'info' | 'warn', source: string, message: string, line?: number, column?: number): void;
+export declare function saveLog(file: VFile, level: 'error' | 'info' | 'warn', source: string, message: string, node?: Node): void;
+export declare function getMdatReports(files: VFile[]): MdatFileReport[];
+export declare function reporterMdat(files: VFile[]): void;

package/dist/lib/mdat/parse.d.ts

@@ -0,0 +1,62 @@
+import { type Html, type Parent } from 'mdast';
+import type { JsonValue } from 'type-fest';
+import { type Simplify } from 'type-fest';
+/**
+ * Structured data about a parsed comment.
+ * Note that this is a discriminated union based on the `type` field.
+ */
+export type CommentMarker = Simplify<({
+    /** Character used to delimit closing tags, e.g. the `/` in `<!-- /keyword -->`  */
+    closingPrefix: string;
+    /** The first complete word in the comment  */
+    keyword: string;
+    /** The unique keyword prefix  */
+    keywordPrefix: string;
+    /** Parsed JSON object of argument string that followed the keyword, empty object if nothing passed  */
+    options: JsonValue;
+    /**
+     * `open`: A mdat-style opening comment tag, e.g. `<!-- keyword -->`  \
+     * `close`: A mdat-style closing comment tag, e.g. `<!-- /keyword -->`
+     */
+    type: 'close' | 'open';
+} | {
+    /** The original text inside the comment, e.g. `<!-- content -->`  */
+    content: string;
+    /**
+     * `meta`: A mdat-style generated meta comment tag  \
+     * `native`: A normal comment that does not match the the `keywordPrefix` (if specified)
+     */
+    type: 'meta' | 'native';
+}) & {
+    /** The complete original comment, e.g. `<!-- keyword -->`  */
+    html: string;
+}>;
+/**
+ * Parsed comment with additional information about the Mdast Node and its Parent.
+ */
+export type CommentMarkerNode = Simplify<CommentMarker & {
+    /** Original Mdast HTML Node where the comment was found. */
+    node: Html;
+    /** Parent of original Mdast HTML Node where the comment was found. */
+    parent: Parent;
+}>;
+export type CommentMarkerParseOptions = {
+    /** Character to identify closing tags, e.g. the `/` in `<!-- /keyword -->`  */
+    closingPrefix: string;
+    /** Prefix to require on all mdat comments, e.g. `mm-`  */
+    keywordPrefix: string;
+    /** Means of identifying mdat generated meta comments, e.g. `+`  */
+    metaCommentIdentifier: string;
+};
+/**
+ * Parse an Mdast HTML comment node into structured data.
+ * @returns A discriminated union of CommentMarkerNode based on comment type, or
+ * undefined if the node is not a comment.
+ */
+export declare function parseCommentNode(node: Html, parent: Parent, options: CommentMarkerParseOptions): CommentMarkerNode | undefined;
+/**
+ * Parse any comment string into structured data.
+ * @returns A discriminated union of CommentMarker based on comment type, or
+ * undefined if the node is not a comment.
+ */
+export declare function parseComment(text: string, options: CommentMarkerParseOptions): CommentMarker | undefined;

package/dist/lib/mdat/rules.d.ts

@@ -0,0 +1,105 @@
+import { type Root } from 'mdast';
+import { type JsonValue } from 'type-fest';
+import type { Merge, MergeDeep, SetOptional, Simplify } from 'type-fest';
+import { z } from 'zod';
+export type SimplifyDeep<T> = Simplify<MergeDeep<T, T>>;
+/**
+ * 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
+ */
+export type 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
+     * Defaults to 0.
+     */
+    applicationOrder: number;
+    /**
+     * The function that generates the expansion markdown string.
+     * For 'compound' rules, this can be an array of rules (without keywords).
+     */
+    content: ((options: JsonValue, tree: Root) => Promise<string>) | NormalizedRule[];
+    /**
+     * The expected order of the keyword in the document relative to other expander comments.
+     * Used for validation purposes.
+     * Leave undefined to order skip validation.
+     * Defaults to undefined, which means order is not enforced.
+     */
+    order: number | undefined;
+    /**
+     * Whether the presence of the keyword comment in the document is required.
+     * Used for validation purposes.
+     * Defaults to false.
+     */
+    required: boolean;
+};
+export type Rule = 
+/**
+ * Function that returns the markdown string to expand at the comment site.
+ */
+((options: JsonValue, tree: Root) => 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.
+ */
+ | Rule[]
+/**
+ * The markdown string to expand at the comment site.
+ */
+ | SetOptional<Merge<NormalizedRule, {
+    /**
+     * 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 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.
+     *
+     * @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;
+}>, 'applicationOrder' | 'order' | 'required'> | string;
+/**
+ * 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.
+ *
+ *
+ *
+ * @example
+ * Most basic rule:
+ * ```ts
+ * { basic: 'content' }
+ * ```
+ *
+ * Rule with dynamic content:
+ * ```ts
+ * { basic: () => `${new Date().toISOString()}` }
+ * ```
+ *
+ * Rule with metadata:
+ * ```ts
+ * { basic-meta: { required: true, content: 'content'} }
+ * ```
+ *
+ * Rule with dynamic content and metadata:
+ * { basic-date: { required: true, content: () => `${new Date().toISOString()}` } }
+ */
+export type Rules = SimplifyDeep<Record<string, Rule>>;
+export type NormalizedRules = SimplifyDeep<Record<string, NormalizedRule>>;
+export declare function normalizeRules(rules: Rules): NormalizedRules;
+export declare function validateRules(rules: Rules): void;
+export declare const rulesSchema: z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>;
+export declare const normalizedRulesSchema: z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>;
+export declare function getRuleContent(rule: NormalizedRule, options: JsonValue, tree: Root, check?: boolean): Promise<string>;
+export declare function getSoleRule<T extends NormalizedRules | Rules>(rules: T): T[keyof T];
+export declare function getSoleRuleKey<T extends NormalizedRules | Rules>(rules: T): keyof T;

package/dist/lib/remark-mdat.d.ts

@@ -0,0 +1,29 @@
+import { type Options as MdatOptions } from './mdast-utils/mdast-util-mdat';
+import type { Root } from 'mdast';
+import type { Plugin } from 'unified';
+import { z } from 'zod';
+export type Options = Partial<MdatOptions>;
+export declare const optionsSchema: z.ZodObject<{
+    addMetaComment: z.ZodOptional<z.ZodBoolean>;
+    closingPrefix: z.ZodOptional<z.ZodString>;
+    keywordPrefix: z.ZodOptional<z.ZodString>;
+    metaCommentIdentifier: z.ZodOptional<z.ZodString>;
+    rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>>;
+}, "strip", z.ZodTypeAny, {
+    addMetaComment?: boolean | undefined;
+    closingPrefix?: string | undefined;
+    keywordPrefix?: string | undefined;
+    metaCommentIdentifier?: string | undefined;
+    rules?: Record<string, any> | undefined;
+}, {
+    addMetaComment?: boolean | undefined;
+    closingPrefix?: string | undefined;
+    keywordPrefix?: string | undefined;
+    metaCommentIdentifier?: string | undefined;
+    rules?: Record<string, any> | undefined;
+}>;
+/**
+ * A remark plugin that expands HTML comments in Markdown files.
+ */
+declare const remarkMdat: Plugin<[Options], Root>;
+export default remarkMdat;

package/license.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Eric Mika
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "remark-mdat",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A remark plugin implementing the Markdown Autophagic Template (mdat) system.",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:kitschpatrol/mdat.git",
+    "directory": "packages/remark-mdat"
+  },
+  "bugs": {
+    "url": "https://github.com/kitschpatrol/mdat/issues",
+    "email": "eric@ericmika.com"
+  },
+  "author": {
+    "name": "Eric Mika",
+    "email": "eric@ericmika.com",
+    "url": "https://ericmika.com"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0",
+    "pnpm": ">=8.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/*"
+  ],
+  "keywords": [
+    "mdat",
+    "markdown",
+    "template",
+    "comments",
+    "unist",
+    "mdast",
+    "mdast-util",
+    "syntax-tree",
+    "remark",
+    "remark-plugin"
+  ],
+  "dependencies": {
+    "@types/mdast": "^4.0.3",
+    "@types/unist": "^3.0.2",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.3",
+    "deepmerge-ts": "^5.1.0",
+    "hast-util-from-html": "^2.0.1",
+    "json5": "^2.2.3",
+    "remark": "^15.0.1",
+    "remark-gfm": "^4.0.0",
+    "type-fest": "^4.10.2",
+    "unified": "^11.0.4",
+    "unist-util-visit": "^5.0.0",
+    "vfile": "^6.0.1",
+    "vfile-message": "^4.0.2",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.14",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "dev": "pnpm run test",
+    "mdat": "../mdat-readme/bin/cli.js --config ../../mdat.config.ts",
+    "test": "vitest"
+  }
+}

package/readme.md

@@ -0,0 +1,221 @@
+<!--+ Warning: Content in HTML comment blocks generated by mdat on 2024-02-08 +-->
+
+<!-- header -->
+
+# remark-mdat
+
+[![NPM Package](https://img.shields.io/npm/v/remark-mdat.svg)](https://npmjs.com/package/remark-mdat)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**A remark plugin implementing the Markdown Autophagic Template (mdat) system.**
+
+<!-- /header -->
+
+> \[!NOTE]\
+> **Please see the [Mdat Monorepo readme](http://github.com/kitschpatrol/mdat) for additional context.**
+
+<!-- table-of-contents -->
+
+## Table of contents
+
+- [Overview](#overview)
+- [Getting started](#getting-started)
+  - [Dependencies](#dependencies)
+  - [Installation](#installation)
+- [Usage](#usage)
+  - [API](#api)
+  - [Examples](#examples)
+- [Utilities](#utilities)
+- [The future](#the-future)
+- [Maintainers](#maintainers)
+- [Acknowledgements](#acknowledgements)
+- [Contributing](#contributing)
+- [License](#license)
+
+<!-- /table-of-contents -->
+
+## Overview
+
+This is a [remark](https://remark.js.org) plugin that automates the inline expansion of placeholder HTML comments with dynamic content in Markdown, making it easy to keep readme files and other documentation in sync with an external single source of truth.
+
+The plugin can take placeholder comments in a Markdown file like this:
+
+```md
+<!-- title -->
+```
+
+And replace it with dynamic data. In this case, from `package.json`:
+
+```md
+<!-- title -->
+
+# remark-mdat
+
+<!-- /title -->
+```
+
+This plugin powers the higher-level [`mdat`](../mdat) and [`mdat-readme`](../mdat-readme) packages in this monorepo. Either of those is a better place to start if you just want to expand some comments.
+
+Please see the [Mdat Monorepo readme](http://github.com/kitschpatrol/mdat) for much more information and context.
+
+## Getting started
+
+### Dependencies
+
+This library is ESM only and requires Node 16 or newer. It's designed to work with Remark 15. `remark-mdat` is implemented in TypeScript and bundles a complete set of type definitions.
+
+### Installation
+
+```sh
+npm install remark-mdat
+```
+
+## Usage
+
+### API
+
+#### Core plugin
+
+This package's default export implements the unified [Plugin](https://github.com/unifiedjs/unified#plugin) type.
+
+The plugin is integrated into a remark process chain via the `.use()` method:
+
+```ts
+import { remark } from 'remark'
+import remarkMdat from 'remark-mdat'
+
+remark().use(remarkMdat)
+```
+
+#### Options
+
+The plugin accepts an optional options object which exposes some configuration options and, most importantly, determines how comments in the source Markdown file will be expanded via the `rules` field:
+
+```ts
+export type Options = {
+  addMetaComment?: Boolean // default: false
+  closingPrefix?: String // default: '/',
+  keywordPrefix?: String // default: '',
+  metaCommentIdentifier?: String // default: '+',
+  rules?: Rules // default: a single test rule for the 'mdat' keyword
+}
+```
+
+### Examples
+
+#### Basic
+
+`remark-mdat` includes one test rule by default, `<!-- mdat -->`.
+
+```ts
+import { remark } from 'remark'
+import remarkMdat from 'remark-mdat'
+
+const markdownInput = '<!-- mdat -->'
+const markdownOutput = await remark().use(remarkMdat).process(markdown)
+
+console.log(markdownOutput.toString())
+
+// Logs:
+// <!-- mdat -->
+//
+// Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat).
+//
+// <!-- /mdat -->
+```
+
+#### With options
+
+If you wanted to replace `<!-- time -->` comments in your Markdown file with the current time, you could pass in a rule:
+
+```ts
+import { remark } from 'remark'
+import { type Rules, default as remarkMdat } from 'remark-mdat'
+
+// Create the rule
+const rules: Rules = {
+  time: () => new Date().toDateString(),
+}
+
+const markdownInput = '<!-- time -->'
+
+// Pass the time rule to remarkMdat
+const markdownOutput = await remark().use(remarkMdat, { rules }).process(markdown)
+
+console.log(markdownOutput.toString())
+
+// Logs:
+// <!-- time -->
+//
+// Mon Feb 05 2024
+//
+// <!-- /time -->
+```
+
+See the [`mdat`](../mdat) package for a higher-level API and CLI that can operate directly on files or strings. It also provides dynamic rule loading and configuration resolution.
+
+[`mdat-readme`](../mdat-readme) also provides a higher-still API and CLI, and bundles a collection of rules convenient for use in readme files.
+
+## Utilities
+
+The plugin bundles a number of [mdast](https://github.com/syntax-tree/mdast) utilities designed to operate directly on syntax trees. These are exported to support customized Unified.js processors and enforce modularity and separation of concerns in mdat's internal implementation, but you do not need to use them directly — all functionality is encapsulated in the single `remarkMdat` plugin export.
+
+The remark-mdat plugin chains these utilities together to accommodate the typical use case of end-to-end expansion and validation of mdat comments. For now, the individual utility transformers are not published individually to NPM, and are instead bundled with `remark-mdat`.
+
+- [**`mdast-util-mdat`**](./src/lib/mdast-utils/mdast-util-mdat.ts)
+
+  Composite transformer function performing end-to-end mdat comment expansion and validation on Markdown ASTs by chaining the other utility functions described below.
+
+  _Exported as `mdat`_
+
+  Utilities wrapped by `mdast-util-mdat`:
+
+  - [**`mdast-util-mdat-split`**](./src/lib/mdast-utils/mdast-util-mdat-split.ts)
+
+    Transformer function that allows inline mdat expansion comments.
+
+    _Exported as `mdatSplit`_
+
+  - [**`mdast-util-mdat-clean`**](./src/lib/mdast-utils/mdast-util-mdat-clean.ts)
+
+    Transformer function that "resets" all mdat comment expansions in a file, collapsing expanded comments back into single-line placeholders.
+
+    _Exported as `mdatClean`_
+
+  - [**`mdast-util-mdat-expand`**](./src/lib/mdast-utils/mdast-util-mdat-expand.ts)
+
+    Transformer function that expands mdat comments (e.g. `<!-- title -->`) in a Markdown file according to the rule set passed in to the `MdatExpandOptions` argument.
+
+    _Exported as `mdatExpand`_
+
+  - [**`mdast-util-mdat-check`**](./src/lib/mdast-utils/mdast-util-mdat-check.ts)
+
+    Transformer function that validates an expanded Markdown document against the requirements defined in the rules passed in to the `MdatCheckOptions` argument.
+
+    See `reporterMdat` to extract, format, and log results from VFile messages written by `mdatCheck`. This function does not modify the tree, it only appends messages to the VFiles passed through it.
+
+    _Exported as `mdatCheck`_
+
+## The future
+
+- Consider making remark a peer dependency? Though perhaps not [strip-markdown/issues/24](https://github.com/remarkjs/strip-markdown/issues/24)...
+
+## Maintainers
+
+[@kitschpatrol](https://github.com/kitschpatrol)
+
+## Acknowledgements
+
+Please see the [monorepo readme](../../readme.md#acknowledgments).
+
+<!-- footer -->
+
+## Contributing
+
+[Issues](https://github.com/kitschpatrol/mdat/issues) and pull requests are welcome.
+
+## License
+
+[MIT](license.txt) © Eric Mika
+
+<!-- /footer -->