mdat 2.0.1 → 2.2.0

package/dist/bin/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import picocolors from "picocolors";
 import prettyMilliseconds from "pretty-ms";
-import { getMdatReports, getSoleRule, mdatClean, mdatExpand, mdatSplit, reporterMdat, rulesSchema, setLogger } from "remark-mdat";
+import { getMdatReports, getSoleRule, mdatCollapse, mdatDiff, mdatExpand, mdatSplit, mdatStrip, reporterMdat, rulesSchema, setLogger } from "remark-mdat";
+import { remark } from "remark";
+import remarkGfm from "remark-gfm";
 import { cosmiconfig, defaultLoaders } from "cosmiconfig";
 import { TypeScriptLoader } from "cosmiconfig-typescript-loader";
 import fs from "node:fs/promises";
@@ -17,8 +19,6 @@ import { promisify } from "node:util";
 import { brotliCompress, gzip } from "node:zlib";
 import prettyBytes from "pretty-bytes";
 import { toc } from "mdast-util-toc";
-import { remark } from "remark";
-import remarkGfm from "remark-gfm";
 import { read, write } from "to-vfile";
 import "vfile";
 import { Configuration } from "unified-engine";
@@ -42,7 +42,7 @@ function deepMergeDefined(...objects) {
 //#endregion
 //#region package.json
 var name = "mdat";
-var version = "2.0.1";
+var version = "2.2.0";
 
 //#endregion
 //#region src/lib/log.ts
@@ -603,7 +603,7 @@ async function formatWithPrettier(content, filePath) {
 	if (config === void 0 && !configCache.has(configKey)) {
 		config = await cachedPrettier.resolveConfig(filePath ?? process.cwd());
 		configCache.set(configKey, config);
-		if (config) log.debug(`Using Prettier config from "${config.filepath}" for "${filePath ?? process.cwd()}"`);
+		if (config) log.debug(`Resolved Prettier config for "${configKey}"`);
 	}
 	return cachedPrettier.format(content, {
 		...config,
@@ -662,7 +662,8 @@ async function findReadme() {
 }
 /**
 * Searches up for a readme.md file.
-* @throws {Error} if no readme is found
+*
+* @throws {Error} If no readme is found
 */
 async function findReadmeThrows() {
 	const readme = await findReadme();
@@ -740,17 +741,26 @@ function getExpandProcessor(config, ambientRemarkConfig) {
 		emphasis: "_"
 	} }).use(remarkGfm).use(ambientRemarkConfig).use(() => async function(tree, file) {
 		mdatSplit(tree, file);
-		mdatClean(tree, file);
+		mdatCollapse(tree, file);
 		await mdatExpand(tree, file, config);
 	});
 }
-function getCleanProcessor(_config, ambientRemarkConfig) {
+function getCollapseProcessor(_config, ambientRemarkConfig) {
 	return remark().use({ settings: {
 		bullet: "-",
 		emphasis: "_"
 	} }).use(remarkGfm).use(ambientRemarkConfig).use(() => function(tree, file) {
 		mdatSplit(tree, file);
-		mdatClean(tree, file);
+		mdatCollapse(tree, file);
+	});
+}
+function getStripProcessor(_config, ambientRemarkConfig) {
+	return remark().use({ settings: {
+		bullet: "-",
+		emphasis: "_"
+	} }).use(remarkGfm).use(ambientRemarkConfig).use(() => function(tree, file) {
+		mdatSplit(tree, file);
+		mdatStrip(tree, file);
 	});
 }
 
@@ -874,9 +884,8 @@ async function createReadme(options) {
 	return readmePath;
 }
 function getTemplateForConfig(templateKey, compound) {
-	const templateString = templates_default[templateKey].content[compound ? "compound" : "explicit"];
-	if (templateString === void 0 || templateString === "") throw new Error(`No template found for "${templateKey}"`);
-	return templateString;
+	if (!(templateKey in templates_default)) throw new Error(`Unknown template "${templateKey}". Available templates: ${Object.keys(templates_default).join(", ")}`);
+	return templates_default[templateKey].content[compound ? "compound" : "explicit"];
 }
 function getTemplateOptions() {
 	return Object.entries(templates_default).map(([key, value]) => ({
@@ -889,10 +898,11 @@ function getTemplateOptions() {
 //#endregion
 //#region src/lib/api.ts
 /**
-* Expand MDAT comments in one or more Markdown files.
-* If no files are provided, auto-finds the closest readme.md.
-* Writing is the responsibility of the caller (e.g. via `await write(result)`)
-* @returns an array of VFiles
+* Expand MDAT comments in one or more Markdown files. If no files are provided,
+* auto-finds the closest readme.md. Writing is the responsibility of the caller
+* (e.g. via `await write(result)`)
+*
+* @returns An array of VFiles
 */
 async function expand(files, name, output, config, options) {
 	files ??= await findReadmeThrows();
@@ -901,21 +911,37 @@ async function expand(files, name, output, config, options) {
 	return results;
 }
 /**
-* Collapse MDAT comments in one or more Markdown files.
-* If no files are provided, auto-finds the closest readme.md.
-* Writing is the responsibility of the caller (e.g. via `await write(result)`)
-* @returns an array of VFiles
+* Collapse MDAT comments in one or more Markdown files. If no files are
+* provided, auto-finds the closest readme.md. Writing is the responsibility of
+* the caller (e.g. via `await write(result)`)
+*
+* @returns An array of VFiles
 */
 async function collapse(files, name, output, config, options) {
 	files ??= await findReadmeThrows();
-	const results = await processFiles(files, loadConfig, getCleanProcessor, name, output, config);
+	const results = await processFiles(files, loadConfig, getCollapseProcessor, name, output, config);
 	if (options?.format) await formatResults(results);
 	return results;
 }
 /**
-* Dry-run expand and compare with file on disk.
-* If no files are provided, auto-finds the closest readme.md.
-* @returns per-file sync status and expanded VFiles
+* Strips MDAT comments in one or more Markdown files without touching other
+* content. Does _not_ automatically expand Mdat content before stripping the
+* tags. If no files are provided, auto-finds the closest readme.md. Writing is
+* the responsibility of the caller (e.g. via `await write(result)`)
+*
+* @returns An array of VFiles
+*/
+async function strip(files, name, output, config, options) {
+	files ??= await findReadmeThrows();
+	const results = await processFiles(files, loadConfig, getStripProcessor, name, output, config);
+	if (options?.format) await formatResults(results);
+	return results;
+}
+/**
+* Dry-run expand and compare with file on disk. If no files are provided,
+* auto-finds the closest readme.md.
+*
+* @returns Per-file sync status and expanded VFiles
 */
 async function check(files, config, options) {
 	files ??= await findReadmeThrows();
@@ -923,10 +949,26 @@ async function check(files, config, options) {
 	const resolvedFiles = Array.isArray(files) ? files : [files];
 	const [originals, results] = await Promise.all([Promise.all(resolvedFiles.map(async (f) => read(f))), processFiles(files, loadConfig, getExpandProcessor, void 0, void 0, config)]);
 	if (options?.format) await formatResults(results);
-	return results.map((result, i) => ({
-		inSync: originals[i].toString().replaceAll("\r\n", "\n") === result.toString(),
+	return results.map((result, i) => compareWithDiff(originals[i], result, options));
+}
+function compareWithDiff(original, result, options) {
+	const inSync = original.toString().replaceAll("\r\n", "\n") === result.toString();
+	if (!inSync) {
+		const parser = remark().use(remarkGfm);
+		const originalTree = parser.parse(original.toString());
+		mdatSplit(originalTree, original);
+		const expandedTree = parser.parse(result.toString());
+		mdatSplit(expandedTree, result);
+		const diffResults = mdatDiff(originalTree, original, expandedTree, result);
+		if (options?.format && diffResults.every((r) => r.status === "ok")) {
+			const message = result.message("Formatting differences outside mdat tags", { source: "diff" });
+			message.fatal = false;
+		}
+	}
+	return {
+		inSync,
 		result
-	}));
+	};
 }
 async function formatResults(results) {
 	for (const file of results) file.value = await formatWithPrettier(file.toString(), file.path || void 0);
@@ -1041,6 +1083,18 @@ try {
 		reporterMdat(results);
 		log.debug(`Collapsed comments in ${prettyMilliseconds(performance.now() - startTime)}.`);
 		process.exitCode = getExitCode(results);
+	}).command("strip [files..] [options]", "Strip MDAT comments while preserving expanded content. If no files are provided, the closest readme.md is stripped.", (yargs) => yargs.positional(...filesPositional).option(outputOption).option(nameOption).option(printOption).option(formatOption), async ({ files, format, name, output, print }) => {
+		logConflicts({
+			name,
+			output,
+			print
+		});
+		const results = await strip(files, name, output, void 0, { format });
+		for (const file of results) if (print) process.stdout.write(file.toString());
+		else await write(file);
+		reporterMdat(results);
+		log.debug(`Stripped comments in ${prettyMilliseconds(performance.now() - startTime)}.`);
+		process.exitCode = getExitCode(results);
 	}).command("check [files..] [options]", "Check if MDAT placeholder comments are up to date. Exits with code 1 if any files have stale or unexpanded content.", (yargs) => yargs.positional(...filesPositional).option(configOption).option(formatOption), async ({ config, files, format }) => {
 		const results = await check(files, collectConfig(config), { format });
 		let allInSync = true;
@@ -1049,6 +1103,7 @@ try {
 			if (inSync) log.debug(`${picocolors.green("Up to date")}: ${filePath}`);
 			else {
 				log.warn(`${picocolors.red("Stale content")}: ${filePath}`);
+				reporterMdat([result]);
 				allInSync = false;
 			}
 		}

package/dist/lib/index.d.ts

@@ -67,10 +67,11 @@ declare function createReadme(options?: Partial<MdatReadmeCreateOptions>): Promi
 //#endregion
 //#region src/lib/api.d.ts
 /**
- * Expand MDAT comments in one or more Markdown files.
- * If no files are provided, auto-finds the closest readme.md.
- * Writing is the responsibility of the caller (e.g. via `await write(result)`)
- * @returns an array of VFiles
+ * Expand MDAT comments in one or more Markdown files. If no files are provided,
+ * auto-finds the closest readme.md. Writing is the responsibility of the caller
+ * (e.g. via `await write(result)`)
+ *
+ * @returns An array of VFiles
  */
 declare function expand(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, options?: {
   format?: boolean;
@@ -82,10 +83,11 @@ declare function expandString(markdown: string, config?: ConfigToLoad, options?:
   format?: boolean;
 }): Promise<VFile>;
 /**
- * Collapse MDAT comments in one or more Markdown files.
- * If no files are provided, auto-finds the closest readme.md.
- * Writing is the responsibility of the caller (e.g. via `await write(result)`)
- * @returns an array of VFiles
+ * Collapse MDAT comments in one or more Markdown files. If no files are
+ * provided, auto-finds the closest readme.md. Writing is the responsibility of
+ * the caller (e.g. via `await write(result)`)
+ *
+ * @returns An array of VFiles
  */
 declare function collapse(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, options?: {
   format?: boolean;
@@ -97,9 +99,27 @@ declare function collapseString(markdown: string, config?: ConfigToLoad, options
   format?: boolean;
 }): Promise<VFile>;
 /**
- * Dry-run expand and compare with file on disk.
- * If no files are provided, auto-finds the closest readme.md.
- * @returns per-file sync status and expanded VFiles
+ * Strips MDAT comments in one or more Markdown files without touching other
+ * content. Does _not_ automatically expand Mdat content before stripping the
+ * tags. If no files are provided, auto-finds the closest readme.md. Writing is
+ * the responsibility of the caller (e.g. via `await write(result)`)
+ *
+ * @returns An array of VFiles
+ */
+declare function strip(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, options?: {
+  format?: boolean;
+}): Promise<VFile[]>;
+/**
+ * Strip MDAT comments from a Markdown string.
+ */
+declare function stripString(markdown: string, config?: ConfigToLoad, options?: {
+  format?: boolean;
+}): Promise<VFile>;
+/**
+ * Dry-run expand and compare with file on disk. If no files are provided,
+ * auto-finds the closest readme.md.
+ *
+ * @returns Per-file sync status and expanded VFiles
  */
 declare function check(files?: string | string[], config?: ConfigToLoad, options?: {
   format?: boolean;
@@ -107,6 +127,16 @@ declare function check(files?: string | string[], config?: ConfigToLoad, options
   inSync: boolean;
   result: VFile;
 }>>;
+/**
+ * Check if MDAT comments in a Markdown string are up to date by expanding and
+ * comparing per-tag.
+ */
+declare function checkString(markdown: string, config?: ConfigToLoad, options?: {
+  format?: boolean;
+}): Promise<{
+  inSync: boolean;
+  result: VFile;
+}>;
 //#endregion
 //#region src/lib/context.d.ts
 /**
@@ -160,4 +190,4 @@ declare function resetMetadataCaches(): void;
  */
 declare function setLogger(logger?: ILogBasic | ILogLayer): void;
 //#endregion
-export { type Config, type ReadmeMetadata, type Rule, check, collapse, collapseString, createReadme as create, createReadmeInteractive as createInteractive, defineConfig, expand, expandString, getContextMetadata, getReadmeMetadata, loadConfig, mergeConfig, resetMetadataCaches, setLogger };
+export { type Config, type ReadmeMetadata, type Rule, check, checkString, collapse, collapseString, createReadme as create, createReadmeInteractive as createInteractive, defineConfig, expand, expandString, getContextMetadata, getReadmeMetadata, loadConfig, mergeConfig, resetMetadataCaches, setLogger, strip, stripString };

package/dist/lib/index.js

@@ -1,10 +1,12 @@
+import { remark } from "remark";
+import remarkGfm from "remark-gfm";
+import { getSoleRule, mdatCollapse, mdatDiff, mdatExpand, mdatSplit, mdatStrip, rulesSchema, setLogger as setLogger$1 } from "remark-mdat";
 import { cosmiconfig, defaultLoaders } from "cosmiconfig";
 import { TypeScriptLoader } from "cosmiconfig-typescript-loader";
 import fs from "node:fs/promises";
 import path from "node:path";
 import picocolors from "picocolors";
 import plur from "plur";
-import { getSoleRule, mdatClean, mdatExpand, mdatSplit, rulesSchema, setLogger as setLogger$1 } from "remark-mdat";
 import { deepmerge } from "deepmerge-ts";
 import { createLogger, getChildLogger, injectionHelper } from "lognow";
 import { defineTemplate, getMetadata, helpers, setLogger as setLogger$2, templates } from "metascope";
@@ -15,8 +17,6 @@ import { promisify } from "node:util";
 import { brotliCompress, gzip } from "node:zlib";
 import prettyBytes from "pretty-bytes";
 import { toc } from "mdast-util-toc";
-import { remark } from "remark";
-import remarkGfm from "remark-gfm";
 import { read, write } from "to-vfile";
 import { VFile } from "vfile";
 import { Configuration } from "unified-engine";
@@ -124,7 +124,8 @@ const GIT_PREFIX_REGEX = /^git\+/;
 const GIT_SUFFIX_REGEX = /\.git$/;
 const TRAILING_SLASH_REGEX = /\/$/;
 /**
-* Reset
+* Reset cached context metadata. Call between tests or when the underlying
+* project files may have changed on disk.
 *
 * @public
 */
@@ -163,7 +164,8 @@ async function getReadmeMetadata() {
 	return readmeMetadata;
 }
 /**
-* Reset
+* Reset cached readme metadata. Call between tests or when the underlying
+* project files may have changed on disk.
 *
 * @public
 */
@@ -609,7 +611,7 @@ async function formatWithPrettier(content, filePath) {
 	if (config === void 0 && !configCache.has(configKey)) {
 		config = await cachedPrettier.resolveConfig(filePath ?? process.cwd());
 		configCache.set(configKey, config);
-		if (config) log.debug(`Using Prettier config from "${config.filepath}" for "${filePath ?? process.cwd()}"`);
+		if (config) log.debug(`Resolved Prettier config for "${configKey}"`);
 	}
 	return cachedPrettier.format(content, {
 		...config,
@@ -667,7 +669,8 @@ async function findReadme() {
 }
 /**
 * Searches up for a readme.md file.
-* @throws {Error} if no readme is found
+*
+* @throws {Error} If no readme is found
 */
 async function findReadmeThrows() {
 	const readme = await findReadme();
@@ -748,17 +751,26 @@ function getExpandProcessor(config, ambientRemarkConfig) {
 		emphasis: "_"
 	} }).use(remarkGfm).use(ambientRemarkConfig).use(() => async function(tree, file) {
 		mdatSplit(tree, file);
-		mdatClean(tree, file);
+		mdatCollapse(tree, file);
 		await mdatExpand(tree, file, config);
 	});
 }
-function getCleanProcessor(_config, ambientRemarkConfig) {
+function getCollapseProcessor(_config, ambientRemarkConfig) {
 	return remark().use({ settings: {
 		bullet: "-",
 		emphasis: "_"
 	} }).use(remarkGfm).use(ambientRemarkConfig).use(() => function(tree, file) {
 		mdatSplit(tree, file);
-		mdatClean(tree, file);
+		mdatCollapse(tree, file);
+	});
+}
+function getStripProcessor(_config, ambientRemarkConfig) {
+	return remark().use({ settings: {
+		bullet: "-",
+		emphasis: "_"
+	} }).use(remarkGfm).use(ambientRemarkConfig).use(() => function(tree, file) {
+		mdatSplit(tree, file);
+		mdatStrip(tree, file);
 	});
 }
 //#endregion
@@ -874,9 +886,8 @@ async function createReadme(options) {
 	return readmePath;
 }
 function getTemplateForConfig(templateKey, compound) {
-	const templateString = templates_default[templateKey].content[compound ? "compound" : "explicit"];
-	if (templateString === void 0 || templateString === "") throw new Error(`No template found for "${templateKey}"`);
-	return templateString;
+	if (!(templateKey in templates_default)) throw new Error(`Unknown template "${templateKey}". Available templates: ${Object.keys(templates_default).join(", ")}`);
+	return templates_default[templateKey].content[compound ? "compound" : "explicit"];
 }
 function getTemplateOptions() {
 	return Object.entries(templates_default).map(([key, value]) => ({
@@ -888,10 +899,11 @@ function getTemplateOptions() {
 //#endregion
 //#region src/lib/api.ts
 /**
-* Expand MDAT comments in one or more Markdown files.
-* If no files are provided, auto-finds the closest readme.md.
-* Writing is the responsibility of the caller (e.g. via `await write(result)`)
-* @returns an array of VFiles
+* Expand MDAT comments in one or more Markdown files. If no files are provided,
+* auto-finds the closest readme.md. Writing is the responsibility of the caller
+* (e.g. via `await write(result)`)
+*
+* @returns An array of VFiles
 */
 async function expand(files, name, output, config, options) {
 	files ??= await findReadmeThrows();
@@ -908,14 +920,15 @@ async function expandString(markdown, config, options) {
 	return result;
 }
 /**
-* Collapse MDAT comments in one or more Markdown files.
-* If no files are provided, auto-finds the closest readme.md.
-* Writing is the responsibility of the caller (e.g. via `await write(result)`)
-* @returns an array of VFiles
+* Collapse MDAT comments in one or more Markdown files. If no files are
+* provided, auto-finds the closest readme.md. Writing is the responsibility of
+* the caller (e.g. via `await write(result)`)
+*
+* @returns An array of VFiles
 */
 async function collapse(files, name, output, config, options) {
 	files ??= await findReadmeThrows();
-	const results = await processFiles(files, loadConfig, getCleanProcessor, name, output, config);
+	const results = await processFiles(files, loadConfig, getCollapseProcessor, name, output, config);
 	if (options?.format) await formatResults(results);
 	return results;
 }
@@ -923,14 +936,37 @@ async function collapse(files, name, output, config, options) {
 * Collapse MDAT comments in a Markdown string.
 */
 async function collapseString(markdown, config, options) {
-	const result = await processString(markdown, loadConfig, getCleanProcessor, config);
+	const result = await processString(markdown, loadConfig, getCollapseProcessor, config);
 	if (options?.format) await formatResults([result]);
 	return result;
 }
 /**
-* Dry-run expand and compare with file on disk.
-* If no files are provided, auto-finds the closest readme.md.
-* @returns per-file sync status and expanded VFiles
+* Strips MDAT comments in one or more Markdown files without touching other
+* content. Does _not_ automatically expand Mdat content before stripping the
+* tags. If no files are provided, auto-finds the closest readme.md. Writing is
+* the responsibility of the caller (e.g. via `await write(result)`)
+*
+* @returns An array of VFiles
+*/
+async function strip(files, name, output, config, options) {
+	files ??= await findReadmeThrows();
+	const results = await processFiles(files, loadConfig, getStripProcessor, name, output, config);
+	if (options?.format) await formatResults(results);
+	return results;
+}
+/**
+* Strip MDAT comments from a Markdown string.
+*/
+async function stripString(markdown, config, options) {
+	const result = await processString(markdown, loadConfig, getStripProcessor, config);
+	if (options?.format) await formatResults([result]);
+	return result;
+}
+/**
+* Dry-run expand and compare with file on disk. If no files are provided,
+* auto-finds the closest readme.md.
+*
+* @returns Per-file sync status and expanded VFiles
 */
 async function check(files, config, options) {
 	files ??= await findReadmeThrows();
@@ -938,13 +974,40 @@ async function check(files, config, options) {
 	const resolvedFiles = Array.isArray(files) ? files : [files];
 	const [originals, results] = await Promise.all([Promise.all(resolvedFiles.map(async (f) => read(f))), processFiles(files, loadConfig, getExpandProcessor, void 0, void 0, config)]);
 	if (options?.format) await formatResults(results);
-	return results.map((result, i) => ({
-		inSync: originals[i].toString().replaceAll("\r\n", "\n") === result.toString(),
+	return results.map((result, i) => compareWithDiff(originals[i], result, options));
+}
+/**
+* Check if MDAT comments in a Markdown string are up to date by expanding and
+* comparing per-tag.
+*/
+async function checkString(markdown, config, options) {
+	const { VFile: VF } = await import("vfile");
+	const original = new VF(markdown);
+	const result = await processString(markdown, loadConfig, getExpandProcessor, config);
+	if (options?.format) await formatResults([result]);
+	return compareWithDiff(original, result, options);
+}
+function compareWithDiff(original, result, options) {
+	const inSync = original.toString().replaceAll("\r\n", "\n") === result.toString();
+	if (!inSync) {
+		const parser = remark().use(remarkGfm);
+		const originalTree = parser.parse(original.toString());
+		mdatSplit(originalTree, original);
+		const expandedTree = parser.parse(result.toString());
+		mdatSplit(expandedTree, result);
+		const diffResults = mdatDiff(originalTree, original, expandedTree, result);
+		if (options?.format && diffResults.every((r) => r.status === "ok")) {
+			const message = result.message("Formatting differences outside mdat tags", { source: "diff" });
+			message.fatal = false;
+		}
+	}
+	return {
+		inSync,
 		result
-	}));
+	};
 }
 async function formatResults(results) {
 	for (const file of results) file.value = await formatWithPrettier(file.toString(), file.path || void 0);
 }
 //#endregion
-export { check, collapse, collapseString, createReadme as create, createReadmeInteractive as createInteractive, defineConfig, expand, expandString, getContextMetadata, getReadmeMetadata, loadConfig, mergeConfig, resetMetadataCaches, setLogger };
+export { check, checkString, collapse, collapseString, createReadme as create, createReadmeInteractive as createInteractive, defineConfig, expand, expandString, getContextMetadata, getReadmeMetadata, loadConfig, mergeConfig, resetMetadataCaches, setLogger, strip, stripString };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "CLI tool and TypeScript library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.",
   "keywords": [
     "mdat",
@@ -50,7 +50,7 @@
     "globby": "^16.2.0",
     "lognow": "^0.6.0",
     "mdast-util-toc": "^7.1.0",
-    "metascope": "^0.5.0",
+    "metascope": "^0.6.0",
     "path-type": "^6.0.0",
     "picocolors": "^1.1.1",
     "plur": "^6.0.0",
@@ -58,7 +58,7 @@
     "pretty-ms": "^9.3.0",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
-    "remark-mdat": "^2.0.2",
+    "remark-mdat": "^2.2.0",
     "to-vfile": "^8.0.0",
     "type-fest": "^5.5.0",
     "unified-engine": "^11.2.2",
@@ -69,16 +69,17 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.2",
-    "@kitschpatrol/shared-config": "^7.0.0",
+    "@kitschpatrol/shared-config": "^7.0.1",
     "@types/mdast": "^4.0.4",
     "@types/node": "~22.17.2",
     "@types/unist": "^3.0.3",
     "@types/yargs": "^17.0.35",
+    "@vitest/coverage-v8": "4.1.2",
     "bumpp": "^11.0.1",
     "execa": "^9.6.1",
     "mdat-plugin-cli-help": "^2.0.2",
     "mdat-plugin-example": "^2.0.0",
-    "mdat-plugin-tldraw": "^2.0.0",
+    "mdat-plugin-tldraw": "^2.0.1",
     "nanoid": "^5.1.7",
     "prettier": "^3.8.1",
     "publint": "^0.3.18",
@@ -109,6 +110,7 @@
     "bench:baseline": "vitest bench --run --outputJson test/benchmarks/baseline.json",
     "build": "tsdown",
     "clean": "git rm -f pnpm-lock.yaml ; git clean -fdX",
+    "coverage": "vitest --coverage --run",
     "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",

package/readme.md

@@ -228,6 +228,7 @@ mdat [command] [files..] [options]
 | ---------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | `expand`   | `[files..]` `[options]` | Expand MDAT placeholder comments. If no files are provided, the closest readme.md is expanded. _(Default command.)_ |
 | `collapse` | `[files..]` `[options]` | Collapse MDAT placeholder comments. If no files are provided, the closest readme.md is collapsed.                   |
+| `strip`    | `[files..]` `[options]` | Strip MDAT comments while preserving expanded content. If no files are provided, the closest readme.md is stripped. |
 | `check`    | `[files..]` `[options]` | Check if MDAT placeholder comments are up to date. Exits with code 1 if any files have stale or unexpanded content. |
 | `create`   | `[options]`             | Create a new Markdown file from a template.                                                                         |
 
@@ -282,6 +283,30 @@ mdat collapse [files..] [options]
 | `--help`<br>`-h`    | Show help                                                                                                                     | `boolean` |                                                     |
 | `--version`<br>`-v` | Show version number                                                                                                           | `boolean` |                                                     |
 
+#### Subcommand: `mdat strip`
+
+Strip MDAT comments while preserving expanded content. If no files are provided, the closest readme.md is stripped.
+
+Usage:
+
+```txt
+mdat strip [files..] [options]
+```
+
+| Positional Argument | Description                                                                                           | Type     |
+| ------------------- | ----------------------------------------------------------------------------------------------------- | -------- |
+| `files`             | Markdown file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. | `string` |
+
+| Option              | Description                                                                                                                   | Type      | Default                                             |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------- |
+| `--verbose`         | Enable verbose logging. All verbose logs are prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` |                                                     |
+| `--output`<br>`-o`  | Output file directory.                                                                                                        | `string`  | Same directory as input file.                       |
+| `--name`<br>`-n`    | Output file name.                                                                                                             | `string`  | Same name as input file. Overwrites the input file. |
+| `--print`           | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.                   | `boolean` |                                                     |
+| `--format`<br>`-f`  | Format the output with Prettier. Discovers Prettier config from the file path. Requires `prettier` as a peer dependency.      | `boolean` |                                                     |
+| `--help`<br>`-h`    | Show help                                                                                                                     | `boolean` |                                                     |
+| `--version`<br>`-v` | Show version number                                                                                                           | `boolean` |                                                     |
+
 #### Subcommand: `mdat check`
 
 Check if MDAT placeholder comments are up to date. Exits with code 1 if any files have stale or unexpanded content.
@@ -366,6 +391,12 @@ mdat check
 mdat collapse
 ```
 
+##### Strip MDAT comments from expanded content
+
+```sh
+mdat strip
+```
+
 ##### Expand and format with Prettier
 
 ```sh
@@ -382,19 +413,9 @@ mdat create
 
 `mdat` exports functions for expanding, collapsing, checking, and creating Markdown files programmatically.
 
-#### `expand`
+#### `expand` / `expandString`
 
-```ts
-function expand(
-  files?: string | string[],
-  name?: string,
-  output?: string,
-  config?: ConfigToLoad,
-  options?: { format?: boolean },
-): Promise<VFile[]>
-```
-
-Expands MDAT comments in one or more files. If no files are provided, auto-finds the closest readme. Writing is the caller's responsibility:
+Expands MDAT comments in one or more files. If no files are provided, auto-finds the closest readme. Writing is the caller's responsibility. Call `.toString()` on the returned [VFile](https://github.com/vfile) to get the result.
 
 ```ts
 import { expand } from 'mdat'
@@ -404,8 +425,6 @@ const [file] = await expand('readme.md')
 await write(file)
 ```
 
-#### `expandString`
-
 ```ts
 function expandString(
   markdown: string,
@@ -414,23 +433,19 @@ function expandString(
 ): Promise<VFile>
 ```
 
-Expands MDAT comments in a Markdown string. Call `.toString()` on the returned [VFile](https://github.com/vfile) to get the result.
-
 #### `collapse` / `collapseString`
 
 Removes expanded content, leaving only the opening comment placeholders. Same signatures as `expand` / `expandString`.
 
-#### `check`
+#### `strip` / `stripString`
 
-```ts
-function check(
-  files?: string | string[],
-  config?: ConfigToLoad,
-  options?: { format?: boolean },
-): Promise<{ inSync: boolean; results: VFile[] }>
-```
+Strips all MDAT comment tags (both opening and closing) while preserving expanded content between them. Same signatures as `expand` / `expandString` (without the `config` parameter, since rules are not needed).
+
+This is useful for producing a "clean" Markdown file that no longer depends on MDAT for future updates.
 
-Dry-run expand and compare with the file on disk. Returns `inSync: false` if the file would change.
+#### `check` / `checkString`
+
+Dry-run expand and compare with the file on disk. Returns `inSync: false` if the file would change. When stale, per-tag diagnostic messages are added to the result VFile identifying which specific tags are stale or unexpanded. Use `reporterMdat` from `remark-mdat` to display these messages.
 
 #### `create` / `createInteractive`
 
@@ -577,16 +592,16 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
 
   Embeds a file's size, with optional Brotli or Gzip compressed size.
 
-- ##### `<!-- size-table({ files: [".gitignore", "readme.md"] }) -->`
+- ##### `<!-- size-table({ files: [".gitignore", "license.txt"] }) -->`
 
   A table of files and their compressed sizes:
 
-  <!-- size-table({ files: [".gitignore", "readme.md"] }) -->
+  <!-- size-table({ files: [".gitignore", "license.txt"] }) -->
 
-  | File       | Original | Gzip   | Brotli |
-  | ---------- | -------- | ------ | ------ |
-  | .gitignore | 305 B    | 245 B  | 216 B  |
-  | readme.md  | 34.4 kB  | 8.3 kB | 6.9 kB |
+  | File        | Original | Gzip  | Brotli |
+  | ----------- | -------- | ----- | ------ |
+  | .gitignore  | 305 B    | 245 B | 216 B  |
+  | license.txt | 1 kB     | 659 B | 468 B  |
 
   <!-- /size-table -->
 
@@ -779,30 +794,6 @@ There's quite a bit of prior art and similar explorations of this problem space:
 
 - VitePress' [Markdown file inclusion](https://vitepress.dev/guide/markdown#markdown-file-inclusion)
 
-There's quite a bit of prior art and similar explorations of this problem space:
-
-- Benjamin Lupton's [projectz](https://github.com/bevry/projectz)\
-  Goes way back.
-
-- David Wells' [Markdown Magic](https://github.com/DavidWells/markdown-magic)\
-  I somehow missed the existence of this one until after building out MDAT. It's very similar conceptually, and has a nice ecosystem of plugins.
-
-- Titus Wormer's [mdast-zone](https://github.com/syntax-tree/mdast-zone)\
-  Allows comments to be used as ranges or markers in Markdown files. Similar tree parsing and walking strategy to MDAT. Mdast-zone uses different syntax for arguments, and requires both opening and closing tags to be present for expansion to occur.
-
-- Jason Dent's [inject-markdown](https://github.com/streetsidesoftware/inject-markdown)
-
-- lillallol's [md-in-place](https://www.npmjs.com/package/md-in-place)
-
-- [AutoMD](https://automd.unjs.io/)\
-  Extremely similar functionality to mdat. The project was initiated around the same time as MDAT, but I didn't find the project until a few years later. Ships in the night.
-
-- Franck Abgrall's [readme-md-generator](https://github.com/kefranabg/readme-md-generator)
-
-- Anders Pitman's [tuplates](https://github.com/anderspitman/tuplates-py)
-
-- VitePress' [Markdown file inclusion](https://vitepress.dev/guide/markdown#markdown-file-inclusion)
-
 ### Implementation notes
 
 This project was split from a monorepo containing both `mdat` and `remark-mdat` into separate repos in July 2024.